refactor(doc-truth): consolidate the two #176 guards into one (fold DOC-17 into DOC-16)

PRs #476 (DOC-16, banner/primacy/mirror PRESENCE guard) and #475 (DOC-17,
over-claim RATCHET) landed in parallel and left two near-identically-named
scripts on main — tools/check-doc-truthing.sh and tools/check-doc-overclaims.sh
— with overlapping intent. This folds them into a single guard so neither
lingers, taking the best of both:

* tools/check-doc-truthing.sh is now the one unified, toolchain-free gate. It
  keeps #476's fail-accumulator + note() structure (reports ALL problems in
  one run) for the presence invariants (DOC-04/05: matrix primacy + anti-
  over-claim section + banner pointers + STATE.a2ml mirror keys), and absorbs
  #475's over-claim ratchet (DOC-08/09) as a fourth check feeding the same
  accumulator, plus the `--update` re-baseline mode. Presence-checking covers
  the banners (where "production-ready" legitimately appears); the frozen
  tools/doc-overclaims.allow baseline adds phrase detection without false
  positives.
* tools/check-doc-overclaims.sh deleted; tools/doc-overclaims.allow kept
  (13 signatures unchanged), now owned by the unified script.
* CI: the two "Issue #176" build steps collapse into one.
* justfile: `guard` runs the single script; `doc-overclaims-bless` →
  `doc-truth-bless` (calls `check-doc-truthing.sh --update`).
* Ledger: DOC-16 rewritten to describe the unified guard; DOC-17 marked
  "folded into DOC-16"; matrix change-control + STATE.a2ml mirror updated.

Pure consolidation — no behavioural change to either check, no compiler code
touched. Verified: unified guard green; `--update` green; both negative
directions (new over-claim phrase / dropped banner) bite.

Refs #176
Refs #175

https://claude.ai/code/session_01HR1GHjBfNdfcFZm1XiLXK4

Author: claude

.github/workflows/ci.yml

@@ -75,22 +75,15 @@ jobs:
         # rationale + recovery instructions.
         run: ./tools/check-no-extension-ts.sh
 
-      - name: Issue #176 — block status-doc truthing re-drift
-        # docs/CAPABILITY-MATRIX.adoc is the single authoritative status
-        # doc. This guard fails if the over-claiming docs lose their
-        # banners pointing back at it, if the matrix stops self-declaring
-        # primacy / loses its anti-over-claim section, or if STATE.a2ml
-        # stops flagging itself as a mirror (DOC-01..09). Toolchain-free.
+      - name: Issue #176 — doc-truthing re-drift guard (DOC-01..09)
+        # Single toolchain-free gate enforcing both halves of the doc-truthing
+        # MONITOR: the presence invariants (DOC-04/05 — banner pointers, matrix
+        # primacy + anti-over-claim section, STATE.a2ml mirror keys) AND the
+        # over-claim ratchet (DOC-08/09 — fails any NEW backend-breadth /
+        # "production-ready" / stdlib-% phrase beyond tools/doc-overclaims.allow).
+        # See tools/check-doc-truthing.sh.
         run: ./tools/check-doc-truthing.sh
 
-      - name: Issue #176 — over-claim ratchet (DOC-08/09)
-        # Companion to the banner guard above (DOC-16): a frozen-baseline
-        # ratchet that fails any *new* backend-breadth / "production-ready"
-        # / stdlib-% phrase beyond tools/doc-overclaims.allow — the
-        # DOC-08/09 detection the banner guard deliberately leaves to bots.
-        # Toolchain-free. See tools/check-doc-overclaims.sh (DOC-17).
-        run: ./tools/check-doc-overclaims.sh
-
       - name: Check formatting
         run: opam exec -- dune build @fmt
 

.machine_readable/6a2/STATE.a2ml

@@ -222,12 +222,11 @@ current authoring frontier. A few primitives remain `extern` builtins.
 Any PR that re-introduces backend-breadth, "production-ready", or
 stdlib-percentage over-claims must be rejected (DOC-01..09 / issue #176;
 Hypatia/gitbot `DOC-FORMAT`/`DOC-DEDUP` rules). This is enforced
-*mechanically* in-repo (wired into `just check` + CI): `tools/check-doc-truthing.sh`
-(DOC-16) holds the banner/primacy/mirror invariant, and
-`tools/check-doc-overclaims.sh` (DOC-17) ratchets against new over-claim
-phrasings beyond the frozen `tools/doc-overclaims.allow` baseline. Update
-*this file* in the same PR as any capability change; `STATE.a2ml` mirrors,
-it does not lead.
+*mechanically* in-repo by the single guard `tools/check-doc-truthing.sh`
+(DOC-16; wired into `just check` + CI): it holds the banner/primacy/mirror
+invariant *and* ratchets against new over-claim phrasings beyond the frozen
+`tools/doc-overclaims.allow` baseline. Update *this file* in the same PR as
+any capability change; `STATE.a2ml` mirrors, it does not lead.
 
 == See also
 

docs/CAPABILITY-MATRIX.adoc

@@ -114,35 +114,37 @@ ABI coordination model (four axes: spec authority / coordinated
 landing / test parity / conflict resolution). Both filed in
 META.a2ml; ADR-020 lands first as the first test of ADR-021's
 protocol. Both require owner ratification. |*PROPOSED 2026-05-23*
-|DOC-16 |In-repo enforcement of the DOC-04/05 truthing invariant —
-`tools/check-doc-truthing.sh` (toolchain-free bash) fails if any
-over-claiming doc loses its `CAPABILITY-MATRIX.adoc` banner, if the
-matrix stops self-declaring primacy or loses its "What AffineScript is
-NOT" section, or if `STATE.a2ml` drops its mirror keys. Wired into
-`just check` (the `guard` recipe) and CI (`ci.yml` build job). Converts
-the DOC-08/09 MONITOR posture from external-bot-only to a first-class
-in-repo gate. |*DONE 2026-05-30*
-|DOC-17 |Over-claim ratchet — the *phrase-detection* complement to DOC-16.
-`tools/check-doc-overclaims.sh` + `tools/doc-overclaims.allow` baseline:
-a frozen-signature ratchet over README + `docs/**` (excluding the two
-governance docs that quote the rule — CAPABILITY-MATRIX + this ledger)
-fails any *new* backend-breadth / "production-ready" / stdlib-% phrase
-beyond the 13-line baseline (future-tense roadmap milestones, dated
-history snapshots, the corrective banners — none a live over-claim).
-DOC-16 deliberately checks banner *presence* not phrasing (a naive grep
-false-positives); the ratchet closes that gap without false positives
-because the legitimate set is frozen and only *new* phrases fail.
-Re-baseline via `--update` / `just doc-overclaims-bless`; the diff is
-the audit trail. Wired into `just check` + CI (toolchain-free bash).
-|*DONE 2026-05-30*
+|DOC-16 |In-repo doc-truthing re-drift guard — `tools/check-doc-truthing.sh`
+(toolchain-free bash), the single gate enforcing *both* halves of the
+MONITOR. *Presence invariants (DOC-04/05):* fails if any over-claiming doc
+loses its `CAPABILITY-MATRIX.adoc` banner, if the matrix stops
+self-declaring primacy or loses its "What AffineScript is NOT" section, or
+if `STATE.a2ml` drops its mirror keys. *Over-claim ratchet (DOC-08/09):*
+a frozen-signature baseline (`tools/doc-overclaims.allow`) over README +
+`docs/**` (excluding the two governance docs that quote the rule —
+CAPABILITY-MATRIX + this ledger) fails any *new* backend-breadth /
+"production-ready" / stdlib-% phrase beyond the 13-line accepted set
+(future-tense roadmap milestones, dated history snapshots, the corrective
+banners — none a live over-claim). Presence-checking handles the banners
+(where "production-ready" legitimately appears); the frozen baseline adds
+phrase detection without false positives. Re-baseline via `--update` /
+`just doc-truth-bless`; the diff is the audit trail. Wired into
+`just check` (the `guard` recipe) and CI (`ci.yml` build job). Converts the
+DOC-08/09 MONITOR posture from external-bot-only to a first-class in-repo
+gate. |*DONE 2026-05-30*
+|DOC-17 |Over-claim ratchet — *folded into DOC-16.* Briefly shipped as a
+separate `tools/check-doc-overclaims.sh` (PR #475) alongside #476's banner
+guard; consolidated into the single `tools/check-doc-truthing.sh` so the
+two near-identically-named guards do not linger. The ratchet behaviour +
+`tools/doc-overclaims.allow` baseline are unchanged — see DOC-16.
+|*DONE 2026-05-30 (consolidated)*
 |===
 
 MONITOR enforcement (DOC-08/09): any PR re-introducing backend-breadth,
-"production-ready", or stdlib-percentage over-claims must be rejected.
-As of 2026-05-30 this is enforced in-repo on *both* halves: DOC-16
-(`tools/check-doc-truthing.sh`) holds the banner/primacy/mirror presence
-invariant, and DOC-17 (`tools/check-doc-overclaims.sh`) ratchets against
-new over-claim *phrasings*. The external Hypatia/gitbot DOC rules remain
+"production-ready", or stdlib-percentage over-claims must be rejected. As of
+2026-05-30 this is enforced in-repo by the single unified guard
+`tools/check-doc-truthing.sh` (DOC-16) — presence invariants *and* the
+over-claim ratchet in one run. The external Hypatia/gitbot DOC rules remain
 the estate-level backstop for anything outside both nets.
 
 == Section B — CORE (compiler soundness / completeness)

docs/TECH-DEBT.adoc

@@ -90,19 +90,18 @@ check: lint test guard
 # Regression guards:
 #  - Issue #35 Phase 3: fails if extension.ts reappears under
 #    editors/vscode/src or any face's vscode extension dir.
-#  - Issue #176 (DOC-16): fails if the status-doc truthing banners
-#    re-drift (authoritative matrix pointers + STATE.a2ml mirror keys).
-#  - Issue #176 (DOC-17): fails if a NEW backend-breadth / "production-
-#    ready" / stdlib-% over-claim appears beyond the frozen baseline.
+#  - Issue #176 (DOC-01..09): the unified doc-truthing guard — fails if the
+#    status-doc banners / matrix primacy / STATE.a2ml mirror keys re-drift,
+#    OR if a NEW backend-breadth / "production-ready" / stdlib-% over-claim
+#    appears beyond the frozen baseline.
 guard:
     ./tools/check-no-extension-ts.sh
     ./tools/check-doc-truthing.sh
-    ./tools/check-doc-overclaims.sh
 
-# Re-baseline the over-claim ledger (DOC-17) after a deliberate, legitimate
+# Re-baseline the doc-truthing over-claim ledger after a deliberate, legitimate
 # change (e.g. a new dated roadmap milestone). Commit the .allow diff.
-doc-overclaims-bless:
-    ./tools/check-doc-overclaims.sh --update
+doc-truth-bless:
+    ./tools/check-doc-truthing.sh --update
 
 # ── Compiler subcommands ──────────────────────────────────────────────────────