Knowledge tools and workflow API

Symptom: A subsystem can report status 'mapped' with zero stale entries while an arbitrary fraction of its declared scope has never been classified, and while ledger rows continue to assert that deleted files were examined. Root cause: The refresh path never reconciles the file ledger against the working tree. detect_changes inner-joins the commit-range diff against file_ledger, so paths added since the baseline match no row and are silently dropped; no ledger writer enumerates the tree; the scoping-to-structural invariant checks only that at least one ledger row exists; and no classification value or non-destructive tool can retire a row whose file was deleted.

Business context: Coverage completeness is the core product claim: the conspectus exists so a reader can trust that a 'mapped' subsystem was actually surveyed. Because the completeness signal is computed from survey status rather than from scope coverage, the dashboard reports full coverage in exactly the state where it is least true. Observed at 5694080 before this refresh: 197 of 422 tracked files (47%) carried no ledger row and 11 rows named files deleted in 3f3065d, while the dashboard reported 7 of 7 mapped and 0 stale. The drift accumulates silently across releases and is only visible to someone who reconciles the ledger by hand.

Primary files:

Symptom: The entire staleness surface is inert. detect_changes reports drift to its caller but persists none of it, get_stale_backlog always returns empty, clear_staleness has nothing to clear, and the dashboard's stale_entries is permanently 0 regardless of how far the conspectus has drifted from HEAD. Root cause: All staleness state lives in the entries table, and no server code path ever inserts a row into it. The only INSERT INTO entries in the repository is in materializer/test-readback.py, a test fixture. Every read and update of staleness therefore operates on a permanently empty table.

Business context: Staleness is the mechanism by which a living conspectus is supposed to admit that it has fallen behind the code. Because the gate can never turn red, the product's freshness claim is unfalsifiable: a conspectus 23 commits and 197 unclassified files behind HEAD reports the same clean dashboard as one surveyed at HEAD this minute. This is a zero-denominator green — the gate passes because nothing can ever populate it, not because the state is healthy. It also masks B03-1: the reviewer sees stale_entries 0 and has no signal prompting a manual reconciliation.

Primary files:

Symptom: A disposition whose strongest supporting evidence is test-observed, config-asserted, or doc-asserted cannot record that quality; set_disposition rejects the value, forcing the agent to overstate it as code-verified or understate it as contract-stated. Root cause: The EVIDENCE_QUALITY enum in tools/dispositions.ts lists five values while the KINDS enum in tools/evidence.ts lists nine, and the B-01 methodology contract publishes an eight-rung ladder as the authoritative evidence-quality scale. The two vocabularies were allowed to diverge, and nothing checks them against each other or against the published contract.

Business context: The methodology names overstating evidence quality as the single most common way it fails, and the evidence ladder is the mechanism meant to prevent that. Here the substrate makes the rule unfollowable in exactly the case that matters most — an agent that actually ran a test and wants to say so. The bias is systematic and one-directional in practice: code-verified is the nearest acceptable value and reads as stronger, so executed-test evidence is silently promoted to code-read evidence across the corpus. Because dispositions are the primary durable record of concern verdicts, this corrupts the quality signal a later reader uses to decide how far to trust a verdict.

Primary files:

Symptom: A scoped file whose content is identical to what was examined can be reported stale indefinitely, because staleness is decided by whether its path appeared in a commit range rather than by whether its content changed. Root cause: The drift predicate in detect_changes tests path membership in the lastSha..currentSha diff and only null-checks the row's ref_sha, never comparing content at that commit against the current one. Nothing clears stale except an explicit clear_staleness, so a path touched and reverted — or touched on a branch later deleted — remains flagged against unchanged content.

Business context: The failure is conservative — it over-reports obligation and never under-reports, so unlike B03-2 it cannot manufacture false confidence, and a reader acting on it re-examines a file that did not need it. It matters because the metric it inflates is the headline repair of this release: the commit that introduced the exemption filter is titled 'Count staleness as obligation, not as churn', and the count is still partly churn. Two such rows exist on this repository at adc4ce0 from a probe branch that no longer exists. Making ref_sha load-bearing also needs a reachability fallback, since clear_staleness can store a sha that later becomes unreachable.

Primary files: