coherence-check

/foundry:coherence-check

An operator/agent ADVISORY sweep that walks the direct-edit WORKSPACE corpus (docs/, foundry/, specs/ markdown) and reports citation coherence. It builds the citation graph fresh in-memory on every run — it does NOT read the committed .foundry/graph.json (no cache trust, no is_stale branch, single fresh-walk provenance shape).

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/foundry-coherence-check.py"
# override the scope (repeatable); default is the canonical docs/ foundry/ specs/:
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/foundry-coherence-check.py" --scope specs --scope docs

Output (deterministic JSON, single document on stdout)

{
  "provenance": {"source": "fresh-walk", "scope": ["docs","foundry","specs"],
                 "corpus_root": "/abs/root", "node_count": 42},
  "findings":     [ {"src","target","resolved","reason"} ],   // broken; reason ∈ {malformed, target_missing}
  "out_of_scope": [ {"src","target","resolved"} ],            // resolve to a real .md outside scope — NOT broken
  "counts":       {"broken": N, "out_of_scope": M}
}

findings are sorted by (reason, src, target); out_of_scope by (src, target). On an operational failure provenance.source == "error" and an error key carries the cause.

Tri-state, fail-CLOSED exit (LOAD-BEARING)

• 0 — ran, zero broken citations.
• 1 — ran, ≥1 broken citation. This is ADVISORY only.
• 2 — operational failure: build_graph raised, the resolved corpus root is missing, OR the corpus walked to zero nodes. An empty / mis-resolved corpus is a HARD error, never a vacuous clean 0 — that is what makes the sweep fail-closed.

The 1 vs 2 split is load-bearing. Downstream wiring MUST NOT promote exit 1 into a blocking gate over the workspace corpus. 1 says "broken citations exist, an operator should look" — it is not a merge veto. 2 is the only fail-closed operational stop, and it exists so a mis-resolved/empty corpus can never masquerade as clean.