Bridge Audit — Drift Detection

bridge-audit is the systematic version of "let me re-read the README and see what doesn't match anymore". It runs 17 categorical checks against the current repo state and returns a stratified report. Check 16 runs the repository's own checkers (scripts/check-*.py, validate-*.py, measure-context.py) through scripts/run-checkers.py and carries every red one into the report: an instance whose CI never runs meets those checkers nowhere else. Check 9 only runs with --cross-repo (it fetches sister-repo trunks); Check 10 (agent-identity health), Check 11 (gate-shaped memory), Check 12 (config-driven CORE skills), Check 13 (user-level skill shadowing), Check 14 (skill learnings pairing), Check 15 (question map), Check 16 (checkers) and Check 17 (entry-file shadow) always run.

Read the referenced file ONLY when triggered.

Arguments

The Checks

Decision Tree

User wants to...
├── Full audit                          → references/checks.md
├── Single check                        → references/checks.md § the named check
├── Cross-repo divergence               → references/checks.md § cross-repo mode
├── OSS-strictness pass                 → delegate to bridge-leak-check
├── Auto-fix unambiguous findings       → references/checks.md § --fix mode
└── Add/extend a rename to track        → edit data/renames.yaml directly

Output Shape

Bridge Audit — <repo>:<branch>  (<timestamp>)

P0 — License (1 finding)
  README badge says "MIT", LICENSE file is Apache 2.0, README footer says "Apache 2.0 — see LICENSE"
  → Pick one. Suggested fix: replace LICENSE + footer with MIT.

P1 — Skill tree (3 findings)
  README lists `cockpit-office/`, `bks-context/`, `bridge-bks-export/` — none exist in skills/.
  Existing but unlisted: `bridge-sync`.
  → Update README skill tree.

...

P3 — Typo (1 finding)
  docs/structure.md:121 "gepushtdurch" — missing space.
  → Fix.

Post-run JSON history (Phase 3 — Learning Loop integration)

After every audit run, if bridge-config.yaml.learning.enabled is true (default) and --no-history is NOT set, write a structured JSON dump of all findings to work/_learning/audit-history/<YYYY-MM-DD-HHMM>.json. The file format is defined in references/audit-history-format.md.

Why: a single audit run prints findings to the terminal and they're gone. Persisting findings lets /bridge-learn trends detect recurring drift — the same finding appearing in 3+ consecutive runs is a stronger signal than a one-off P2 in a single report.

The JSON write is the LAST step of the audit run, after the human-readable output. It runs even if --fix applied some fixes (the JSON reflects state before fixes, so the next run can show the diff).

Fingerprint computation

Each finding has a fingerprint field — a stable SHA-256 hash of the finding's identity, NOT its prose. Use this normalized payload:

SHA-256 of utf8(
  check_name + "\n" +
  target_path + "\n" +
  normalize(summary)
)

Where normalize(s) = lowercase, collapse whitespace, replace absolute paths with repo-relative, strip timestamps, strip line numbers within ±5.

This is what makes "the same finding" stable across runs even if README content shifts.

Learning-ledger consistency (read-only)

Run python3 scripts/learning-ledger.py check once per audit. Each line it prints (a proposal whose folder, frontmatter status and last audit-trail row disagree, a placeholder timestamp, an implemented row without a commit, a row with no proposal file) is one P2 finding with the line as its text. The audit never repairs them: /bridge-learn owns those files. Exit 0 means no finding.

Optional, off by default: learning-ledger.py check --provenance also compares each skill's work/_learning/provenance/<skill>.md with the trail's implemented rows, both ways, and names a record still at the old in-skill path. Run it only when asked; it starts opt-in because the convention starts at zero adoption. Report its lines as P3.

Recurring-findings auto-proposal (Phase 3)

After writing the history JSON, scan the last 10 history files for fingerprints that appear in ≥3 most-recent consecutive runs. For each recurring fingerprint:

1. Check if work/_learning/proposals/*.md already has a proposal whose frontmatter source.fingerprint matches. If yes: skip (proposal exists). Then widen the lookup to proposals/rejected/: run python3 scripts/learning-ledger.py prior-rejections <target.path> for the path the new proposal would target. On a hit, carry prior_rejections: and argue the difference in the body, or skip writing. Never neither.
2. If no proposal exists: write a new proposal file work/_learning/proposals/<YYYY-MM-DD>-audit-recurring-<fp-short>.md using the template in skills/bridge-learn/references/trend-analysis.md.
3. Severity = ONE-LEVEL-UP from the finding's severity (P1 finding → P0 proposal, P3 finding → P2 proposal). Rationale: recurring P1 is worse than fresh P0 — it's been left.
4. source.type: audit-recurring, evidence: points to oldest + latest history JSON in the streak.
5. Surface to user at end of audit run:

   🔁 1 recurring finding auto-generated as proposal:
     work/_learning/proposals/2026-05-13-audit-recurring-3f2a8b1c.md
     (skill-tree-drift / README ↔ skills/ — 4 consecutive runs)
   → Review at /bridge-learn

This skip-able with --no-recurring-scan for cases where you're audit- debugging the audit itself (avoid feedback loop).

Maintenance contract

• New rename happens in repo? → add to data/renames.yaml, audit catches future drift.
• New typo pattern noticed twice? → add to data/typo-patterns.yaml.
• New cross-doc invariant? → add a check to references/checks.md and a row to the table here.
• A gate-shaped memory keeps reappearing in Check 11? → promote it to rules/<tier>/ (memory stays as dated provenance); see rules/knowledge-growth.md for where behavioral rules belong.
• Audit-history files getting large (>365)? → roll up oldest 30 days into monthly aggregates; see references/audit-history-format.md § Retention.

See also

• bridge-leak-check — content-blocklist scan + OSS-strictness pass (legitimate vs leak categorization)
• bridge-sync — cross-repo propagation of fixes (uses bridge-audit + bridge-leak-check internally)
• bridge-learn — Phase 2 review surface; consumes the audit-history JSON via trend mode
• task-close-postmortem — Phase 1 proposal-writer (different source: postmortem instead of audit)
• work/_learning/README.md — the aggregation layer this writes into
• rules/operations.md — CORE/USER path discipline
• rules/promote-safety.md — content scan rules