Bridge audit

Skill bks-lab/open-bridge/skills/bridge-audit

Your AI coding agent starts every session knowing your repos, your clients, and how you work — a plain git repo of markdown + YAML it reads at session start, independent of model or frontend. Context compounds instead of restarting. MIT.

Install

npx -y skills add bks-lab/open-bridge --skill bridge-audit

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

8 stars8 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Auditing skill for The Bridge repos — finds drift between docs and reality (license badge ↔ LICENSE file ↔ footer; README skill list ↔ skills/ dir; protocol counts; renamed-but-not-everywhere; broken cross-refs; missing scope frontmatter; routing-SoT conflicts; common typos; user-level skill shadowing between instances; cross-repo skill-tree sync coverage with --cross-repo). Returns a P0/P1/P2/P3 stratified report with concrete fix proposals — the same output shape that a human-led drift-audit would produce. Trigger: "/bridge-audit", "audit", "drift check", "bridge audit", "check consistency", "find drift", "is README still accurate", "are my skills shadowed", "whose skills are running".

SKILL.md

10.0 KB, as published. Nobody here has run it

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 13 categorical checks against the current repo state and returns a stratified report. 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), and Check 13 (user-level skill shadowing) always run.

Read the referenced file ONLY when triggered.

Arguments

Argument	Effect	Default
`(none)`	Full audit, all checks	—
`--check <name>`	Run only one check (license / skill-tree / protocol-count / renames / xrefs / scopes / routing-sot / typos / agent-identity / memory-gate / config-driven / skill-shadowing)	all
`--cross-repo`	Also clone configured upstreams and compare README/AGENTS for divergence	false
`--strict-oss`	When run on an OSS variant: flag hardcoded internal vocabulary (delegates to `bridge-leak-check`)	false
`--fix`	Where unambiguous, apply the suggested fix	false (advisory only)
`--no-history`	Skip writing the post-run JSON to `work/_learning/audit-history/`	history written by default if `learning.enabled`
`--no-recurring-scan`	Skip the trend-detection step that auto-generates proposals for recurring findings	scan runs by default

The 13 Checks

#	Check	What it compares	Severity hint
1	License consistency	README badge ↔ LICENSE file ↔ README footer ↔ CLAUDE.md license claim ↔ MEMORY mentions	P0 if any disagree
2	Skill-tree truth	README skill table/tree ↔ AGENTS.md skill table ↔ `skills/*/SKILL.md` actual	P1
3	Standing-order count	"N standing orders" claims ↔ `protocols/standing-orders/*.md` count (excluding `_template.md`, `README.md`)	P1
4	Renamed-everywhere	`data/renames.yaml` old-name greps in tracked content (excluding listed exceptions)	P1
5	Cross-reference validity	Markdown `[text](path)` and `path` references resolve to existing files	P2
6	Scope coverage	Group A: `skills//SKILL.md` have explicit `scope:` under `metadata:` (`metadata.scope`); `.claude/agents/.md` have explicit top-level `scope:` (P2); `rules/.md` scope is REQUIRED + hard-gated by `validate-bridge.py` (P1). Group B: every `identity/{mandants,accounts,personas}/.yaml` + `workflow/{contexts,projects}/.yaml` + `infra/{remotes,channels}/.yaml` has the required top-level `scope:` (P1 — schema-enforced, routing-critical)	P1/P2
7	Routing-SoT conflicts	Multiple files claim authoritative status for the same routing domain (heuristic: same path appears in multiple "source of truth" tables with different rules)	P2
8	Typo lint	Bridge-corpus typo patterns from `data/typo-patterns.yaml`	P3
9	Skill-tree sync coverage (`--cross-repo` only)	Local `skills/*/` scope ↔ each upstream's `skills/` directory listing — forward-drops + reverse-leaks	P1 (P0 if outstanding >2 sync windows)
10	Agent-identity health	`identity/agent/SOUL.md` present + ≤80 lines / ≤4 KB · `IDENTITY.md` present · both carry valid frontmatter (`schema_version`/`type`/`scope`/`last_updated`)	P1 if SOUL.md missing, else P2
11	Gate-shaped memory without a `rules/` home	Memory files whose body uses gate language (imperative + always/never/immer/nie, or "when X → do Y" routing) but have NO corresponding rule in `rules/` (core/bks/user) — a behavioral rule trapped in the private store	P2
12	Config-driven CORE skills	`scope: core` skill files (`SKILL.md` + `references/`) that hardcode instance specifics — org/project IDs, tracker queries, persona names, pipeline IDs, absolute instance paths — instead of reading them from `bridge-config.yaml` / `workflow/` / `infra/` / `identity/` (CLAUDE.md § Generic CORE Skills)	P2
13	User-level skill shadowing	`~/.claude/skills/` (resolved) ↔ this repo's `skills/` — the user level overrides the project level, so a pointer at a Bridge repo silently serves one instance's skills to every other instance (AGENTS.md § Skills). Both directions: this instance shadowing others, and others shadowing this one (with `diff -rq` drift per colliding name). Also reports scripts that resolve the path as a filesystem location	P0 if own skills are shadowed or instance-bound skills (scope org or user) leak machine-wide, else P1

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-dashboard`, `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.

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:

Check if work/_learning/proposals/*.md already has a proposal whose frontmatter source.fingerprint matches. If yes: skip (proposal exists).
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.
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.
source.type: audit-recurring, evidence: points to oldest + latest history JSON in the streak.

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.