feat(lint): doc-refs + allow-manifest guards (CI-gated)#77
Merged
Conversation
…cribing, refresh phase-2 statuses, land plan docs - CLAUDE.md: the duplicate Pitfall #20 (Export-Only Destination) is renumbered #32; the referenced #20 (Failed Entity Loss) keeps its number (code comments cite it). Numbering note added: #8 retired, #20 out of sequence, and the rule that a pitfall citation is always number + short name so it means something to a human without a lookup. (AGENTS.md mirrored locally; it is gitignored.) - ENGINEERING_FAQ.md: every bare section-letter reference ("(same as §E)", "(§G)", ...) expanded to include the section name; "Pitfall #20" citation made self-describing. - Phase-2 plan docs: stale status lines corrected (PR-1 #73 and PR-2 #75 are MERGED, not in progress; #76 in review, its fluid-gate fix gated on LAB-A). - New: 2026-07-08-pr-3-protocol-wiring-plan.md — the approved PR-3 executor plan rescued from the session (it existed nowhere on disk). - Landed the empirical-test docs (backlog, suite design, LAB-A spec); the first-pass lab-coverage doc gets a SUPERSEDED banner (its #76 checklist predates the 3a47a58 remediation) and is kept as the method record.
…un lint) lint:doc-refs — human-resolvable documentation cross-references: - duplicate-pitfall-number: CLAUDE.md defining "### N." twice (the original #20 collision sat unnoticed for months) goes red. - unknown-pitfall-ref: citing a number that does not exist in CLAUDE.md (renumber rot, the retired #8) goes red. - pure-pointer-citation: a parenthetical or "See ..." sentence whose entire content is the reference goes red — the number + short name rule, now mechanical (a fresh reader broke the written rule within 48h; rules humans break that fast need a machine). Scope: root *.md + docs/*.md (docs/superpowers/** excluded as frozen records) + plugin docs. lint:allow-manifest — every *:allow escape hatch on a DI lint must be enumerated in scripts/lint-allow-manifest.json with reason + approver; unlisted, stale, and count-drifted annotations all go red. Allows are escalations (memory: lint-allows-are-escalations); the manifest diff is the reviewable record. Baseline: the 3 audited pre-manifest allows. Teeth verified red-on-violation for all rules: 15 organic pure-pointer reds (fixed in the previous commit), injected Pitfall #99 red, injected duplicate "### 19." red, manifest unlisted/stale reds during path canonicalization.
… PR step) Third guard in the family. Enforces the audit-boundary rule mechanically: any commit labeled docs:/docs(...) in the PR range may touch only *.md files or docs/ paths. The rule is twice-paid (the original rider incident, then a recurrence in an agent lab-findings commit within days of the rule being restated in its brief). No escape hatch — a mixed change is always splittable. Runs as a dedicated PR step (checkout fetch-depth: 0); fails loudly if the base ref cannot be resolved, never silently passes. Teeth verified: injected docs-labeled .lua rider red, clean range green.
…ate failure (binding on #30) Discard always; bank the always-on forensic bundle first (dest scan + per-name diff + force-state snapshot + tick stamps, never debug-gated); source preserved; opt-in preserve_failed_destination for active hunts. Grounded in BELT-2 drift (a preserved surface smears positionally even fully locked) and payload+dest-state determinism.
…n-world gate + Black-Box Discard The campaign converges here: fluid injection moves to the R11 seam position; ONE exact gate (items 0/0, fluids exact by-name at 1e-6) fed segment_temps; failed-entity-FLUID subtraction gap closed; dropped_fluids attributed; Black-Box Discard on failure (always-on bundle, then delete, opt-in preserve flag); post-activation fluid gate + quarantine fields retired; LossAnalysis writes a separate postActivationReport; two TS one-line hardenings; full test and doc blast radius from the impact map. Supersedes the ON-HOLD 2026-07-09 brief.
…ct frozen-world gate + Black-Box Discard" This reverts commit 3d3b72d.
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
1 participant
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
Two new mechanical guards, both wired into
npm run lint(the CI gate):lint:doc-refs— documentation cross-references must be human-resolvable### N.twice goes red. This is the rule the original incident needed: TWO "Pitfall chore: docs reconciliation + test-harness fixes (cleanup, belt fixture, engine invariant) #20"s coexisted for months and a citation of "chore: docs reconciliation + test-harness fixes (cleanup, belt fixture, engine invariant) #20" meant nothing.(Pitfall #16),(see Pitfall #12),(same as §E)) goes red. The written rule ("always number + short name") was broken by a fresh reader within 48 hours of being written; rules humans break that fast need a machine.*.md+docs/*.md+ plugin docs.docs/superpowers/**excluded (frozen historical plan records).lint:allow-manifest— allow annotations are escalations, now with a ledgerEvery
*:allowescape hatch on a DI lint (lint-lua:allow,pcall:allow,lint-webpack-cache:allow,lint-test-grounding:allow,lint-doc-refs:allow) must be enumerated inscripts/lint-allow-manifest.jsonwith a reason and approver. Unlisted annotation → red. Stale manifest entry → red. Count drift → red. The manifest diff is the reviewable record; there is deliberately no escape hatch on this guard itself.Also in this PR
docs(refs)commit: the 15 existing pure-pointer citations fixed (names added, no content changes) so the guard lands green.codex/composite-transfer-verdictbranch (pitfall renumbering chore: docs reconciliation + test-harness fixes (cleanup, belt fixture, engine invariant) #20→test(transfer-fidelity): freeze-first — fix the clock, not the tolerance #32 + self-describing FAQ refs) — main still had the duplicate### 20.. Identical changes on both branches merge cleanly when Fix composite transfer validation verdict #76 lands.Teeth (red-on-violation, all verified)
Pitfall #99→ red → reverted → green.### 19.→ red → reverted → green.Verification
Both scripts pass locally (
19 files scanned, 31 pitfalls in the index, 0 problems;3 annotated (file,marker) pairs). They are dependency-free (node:fsonly); CI exercises them via the existingnpm run lintstep.