feat(doc-truth): over-claim ratchet (DOC-17) complementing #476's banner guard (Refs #176)#475
Merged
Merged
Conversation
hyperpolymath
force-pushed
the
claude/wonderful-gauss-SbT8o
branch
from
fac9645 to
470bf14
Compare
hyperpolymath
pushed a commit
that referenced
this pull request
May 30, 2026
…ner guard (Refs #176) PR #476 landed the DOC-16 banner/primacy/mirror PRESENCE guard (tools/check-doc-truthing.sh) but deliberately does not phrase-scan — "production-ready" legitimately appears in the negating banners and future-roadmap sections, so a naive grep false-positives, and it leaves novel over-claim phrasings (the DOC-08/09 MONITOR) to the Hypatia/gitbot bots. This adds the missing phrase-detection half without that false-positive problem, as DOC-17: * tools/check-doc-overclaims.sh — toolchain-free ratchet. Scans README + docs/** (excluding the two governance docs that quote the rule — CAPABILITY-MATRIX + TECH-DEBT) and fails any backend-breadth / "production-ready" / stdlib-% signature not in the frozen baseline. * tools/doc-overclaims.allow — the 13-signature baseline (future-tense roadmap milestones, dated history snapshots, the corrective banners; none a live over-claim). Re-baseline with `--update`; the diff is the audit trail. Signatures are path + normalised-line (robust to moves). * Wired into the `guard` recipe (so `just check`) and the CI build job, right after #476's banner guard. Distinct script/recipe names — no clash with check-doc-truthing.sh. * Ledger DOC-17 row + MONITOR note (both halves now mechanical); matrix change-control + STATE.a2ml mirror updated. Originally this PR (#475) was a superset of #476, built in the same parallel session; on finding #476 merged first it was reworked to drop the duplicate banner check and keep only the unique ratchet (DOC-DEDUP). DOC-05 gate-number policy unchanged; no compiler code touched. Verified locally: both guards green, ratchet negative-test bites. Refs #176 Refs #175 https://claude.ai/code/session_01HR1GHjBfNdfcFZm1XiLXK4
hyperpolymath
force-pushed
the
claude/wonderful-gauss-SbT8o
branch
from
470bf14 to
6c39eb4
Compare
hyperpolymath
changed the title
…ner guard (Refs #176) PR #476 landed the DOC-16 banner/primacy/mirror PRESENCE guard (tools/check-doc-truthing.sh) but deliberately does not phrase-scan — "production-ready" legitimately appears in the negating banners and future-roadmap sections, so a naive grep false-positives, and it leaves novel over-claim phrasings (the DOC-08/09 MONITOR) to the Hypatia/gitbot bots. This adds the missing phrase-detection half without that false-positive problem, as DOC-17: * tools/check-doc-overclaims.sh — toolchain-free ratchet. Scans README + docs/** (excluding the two governance docs that quote the rule — CAPABILITY-MATRIX + TECH-DEBT) and fails any backend-breadth / "production-ready" / stdlib-% signature not in the frozen baseline. * tools/doc-overclaims.allow — the 13-signature baseline (future-tense roadmap milestones, dated history snapshots, the corrective banners; none a live over-claim). Re-baseline with `--update`; the diff is the audit trail. Signatures are path + normalised-line (robust to moves). * Wired into the `guard` recipe (so `just check`) and the CI build job, right after #476's banner guard. Distinct script/recipe names — no clash with check-doc-truthing.sh. * Ledger DOC-17 row + MONITOR note (both halves now mechanical); matrix change-control + STATE.a2ml mirror updated. Originally this PR (#475) was a superset of #476, built in the same parallel session; on finding #476 merged first it was reworked to drop the duplicate banner check and keep only the unique ratchet (DOC-DEDUP). DOC-05 gate-number policy unchanged; no compiler code touched. Verified locally: both guards green, ratchet negative-test bites. Refs #176 Refs #175 https://claude.ai/code/session_01HR1GHjBfNdfcFZm1XiLXK4
hyperpolymath
force-pushed
the
claude/wonderful-gauss-SbT8o
branch
from
6c39eb4 to
a1e6903
Compare
hyperpolymath
added a commit
that referenced
this pull request
May 30, 2026
… check-doc-truthing.sh (#479) Folds the over-claim ratchet (#475 / DOC-17) into the banner-presence guard (#476 / DOC-16) so the two near-identically-named doc-truthing scripts do not linger. tools/check-doc-truthing.sh is now the single toolchain-free gate: #476's fail-accumulator structure for the presence invariants (DOC-04/05) + #475's over-claim ratchet (DOC-08/09) + the `--update` re-baseline mode, over the unchanged 13-signature tools/doc-overclaims.allow. check-doc-overclaims.sh deleted; CI two steps -> one; justfile guard runs one script (doc-truth-bless); ledger DOC-16 rewritten, DOC-17 folded in. Pure consolidation, no behavioural change, no compiler code touched. Refs #176 Refs #175 https://claude.ai/code/session_01HR1GHjBfNdfcFZm1XiLXK4
This was referenced May 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds the phrase-detection half of the issue #176 doc-truthing MONITOR, as ledger row DOC-17 — complementing the DOC-16 banner guard that landed in #476.
Context / dedup: This PR was originally built in parallel with #476 as a superset (banner invariant + over-claim ratchet). #476 merged first, landing
tools/check-doc-truthing.sh, which enforces banner/matrix-primacy/STATE-mirror presence but deliberately does not phrase-scan — its header notes a naiveproduction-readygrep false-positives on the negating banners and future-roadmap text, so it leaves novel over-claim phrasings to the Hypatia/gitbot bots. This PR was then reworked to drop the now-duplicate banner check and keep only the unique part: a false-positive-free ratchet for exactly that phrase detection. Renamed to avoid any clash with #476's script.How
tools/check-doc-overclaims.sh— toolchain-free ratchet. ScansREADME.adoc+docs/**(excluding the two governance docs that quote the rule —CAPABILITY-MATRIX+TECH-DEBT) and fails any backend-breadth /production-ready/ stdlib-% signature not in a frozen baseline. No false positives, because the legitimate set is frozen and only new phrases fail.tools/doc-overclaims.allow— the 13-signature baseline (future-tense roadmap milestones, dated history snapshots, the corrective banners — none a live over-claim). Re-baseline with--update/just doc-overclaims-bless; the diff is the audit trail. Signatures arepath + normalised-line(robust to line moves).guardrecipe (sojust check) and the CIbuildjob, right after feat(doc-truthing): in-repo DOC-04/05 guard + ADR-019 record (Refs #175 #176 #260) #476's banner guard. Distinct names — no clash withcheck-doc-truthing.sh.TECH-DEBT.adocDOC-17 row + MONITOR note (both halves now mechanical);CAPABILITY-MATRIX.adocchange-control references both guards;STATE.a2mlmirror note.Verification
bash -nclean; scriptchmod +x; SPDX headers on both new files.mainafter feat(doc-truthing): in-repo DOC-04/05 guard + ADR-019 record (Refs #175 #176 #260) #476, so DOC-16 + DOC-17 are both present with a single, clean ledger.Refs #176
Refs #175
https://claude.ai/code/session_01HR1GHjBfNdfcFZm1XiLXK4