Interlinked Spec Audit

interlinked-spec-audit — keep prose specs honest against code

The spec-audit system is three cooperating substrates plus doctest. Its one policy: detect, never autofix — findings carry evidence and candidate resolutions, but the agent always writes the fix.

• Fact ledger (interlinked spec) — deterministically extracts the enumerable facts that drift during revision (ID registries like FG-INV-07/B7, count/range claims, headings/ §-refs, backticked paths, <!-- fact:NAME --> markers), merges them cross-file, and flags disagreements ("drift") at edit time.
• Findings reconciliation (interlinked findings) — ingest an external reviewer's numbered report into a durable corpus, then track each finding to closure (touched by an overlapping edit, or acked with a reason).
• Invariants + review agenda — extract a doc's invariants into a taxonomy, and generate a standing discovery agenda for the next reviewer.

Load this when

• Extracting invariants/facts from a design doc, or building a review agenda.
• You see a [interlinked:spec-*] or [interlinked:disputed-ground] warning after a markdown edit.
• Ingesting or triaging an external code-review report.
• Running executable examples embedded in docs.

interlinked spec

Two subcommands, no flags:

interlinked spec agenda                       # → .interlinked/review-agenda.md
interlinked spec invariants <file>            # → .interlinked/policies/<basename>.invariants.md

• spec agenda — walks cwd, writes a review agenda with three sections: compose-checks (an ID namespace/declared fact constrained from ≥2 files — "read them together, confirm no contradiction"), coverage gaps (a section whose heading matches a kind — format / protocol / crypto-keys / … — but whose body omits that kind's standard concerns), and outstanding deterministic drift, then an open review-findings section appended last. It asks questions, never renders verdicts.
• spec invariants <file> — for markdown: numbered registry rows + MUST/never/"sole truth" doctrine sentences (fenced code/blockquotes skipped). For code: // INVARIANT: / // SAFETY: comments + assert(/assert! calls. Output is a labeled taxonomy with verbatim quotes + file:line provenance (review context / Tier-2 classification input).

interlinked findings

Review-report ingestion + reconciliation. The CLI operates on review_-prefixed findings.

interlinked findings ingest <report> [--reviewer <name>]   # parse a numbered report into the corpus
interlinked findings status [--all]                        # "N total — X open, Y touched, Z acked"
interlinked findings verify [--write]                      # re-anchor findings whose lines moved
interlinked findings ack <findingId> --reason <text> [--by <name>]

• ingest parses findings that start at column 0 as N. [severity: high] statement… (severity optional; first repo-path:line token = the anchor; Evidence: line = the quote). bug_class is derived from the statement's first 6 words, so re-ingesting a reworded finding creates a new row (same text merges provenance).
• status folds the reconciliation sidecar; open findings are what you must close.
• verify re-checks each finding's anchor against the tree (live / moved / drifted / gone / unverified); --write re-anchors moved rows. verify never changes reconciliation state — it keeps the ledger true, it doesn't close anything.
• ack appends an acked txn (a later touch never downgrades an ack).
• An edit that overlaps a finding's cited span (±3 lines) auto-marks it touched.

Storage: corpus .interlinked/findings/corpus.jsonl (append-only, last-write-wins per id)

• global cache ~/.interlinked/findings-corpus.jsonl; reconciliation sidecar .interlinked/findings/reconciliation.jsonl (states: open/touched/acked). Two-axis model: corpus status (candidate/approved/…) vs. the reconciliation state the CLI reports.

interlinked doctest

For expected output as well as successful execution, use tests contracts import <doc> on explicit json interlinked-contract fences. Ordinary code fences remain illustrative. Import creates proposed cases with the original document hash and quoted example; it never executes them or authorizes policy. Exact observation bindings detect altered expectations; general requirement interpretation stays advisory. Run selected cases explicitly with tests contracts run; use interlinked-verify for the manifest and bounded runners. Existing doctest behavior remains exit-status based. Executes markdown code-fences that opted in with a doctest info-string token, asserting each exits 0. Only tagged fences run (untagged rm -rf examples are never executed).

```bash doctest
interlinked findings status
```

Flags: --path <file|dir> (default cwd), --json. Each block is an independent bash -c (60s timeout); output doctest: P/T block(s) passed, exit 1 on any failure. Caveats (verified): it runs in the CLI's process.cwd(), not --path's directory (run it from the repo root); a missing/typo'd --path silently reports 0/0 and exits 0 (check the total is nonzero); no cd/env/var state carries across blocks; the fence language is ignored (everything runs as bash).

Checks you encounter at edit time

All gated by config spec_checks (default on).

The repository ledger skips Git-ignored files and directory trees, including local archive copies. Tracked files matched by ignore patterns still participate. Incremental refreshes and previews preserve the scope captured when the ledger was built; rebuild after changing ignore or tracking rules. Every build takes a fresh Git ignore snapshot. If Git is unavailable, the bounded filesystem walk still runs with its standard exclusions. Do not rewrite historical snapshots to satisfy a live-repository link warning. After updating the daemon, the next markdown observation refreshes the derived Stop stash; evidence logs stay intact. A fresh spec agenda run can confirm repository scope independently of the daemon's ledger.

PostToolUse single-file (8 checks, severity: warning): spec_dangling_anchor (proven — a [x](#slug) or §N.N ref with no target), spec_numbering, spec_count_claim ("six bets" above a B1..B7 census), spec_pitfall (curated spec falsehoods), spec_claim_untagged, spec_capacity_claim, spec_table_sum (proven — a Total row that doesn't recompute), spec_stage_order.

PostToolUse cross-file drift — on a markdown edit, [interlinked:spec-drift] for count/range/declared-fact/xref drift involving the edited file (≤5/edit; the rest deferred to the evidence log and review agenda).

Quoted code examples, quoted phrases and explicit Evidence:/Example:/input/output fields do not assert live numeric facts or contribute example IDs to the census. Individually formatted identifiers and count tokens remain supported. These rules depend on content, not repository names or review-directory paths. Declared fact: markers must be live markup: markers inside inline code, fenced code or blockquotes are examples, not declarations.

Generic count claims use a scoped identifier census. A README may describe its directory; other documents must mention the namespace or link to its home near the claim before sibling files enter the census. Nearby explicit links can select another document set. A shared noun such as “gates” does not join an unrelated repository-wide identifier namespace. Stop reports a repository snapshot; it does not claim that the current session introduced every finding. Full comparisons, related files, stable finding IDs and observation provenance are retained in spec-drift.jsonl and can be searched with interlinked data search --source spec-drift. The prior session stash is bounded, so first observation is not evidence of when a defect was introduced.