docs: reconcile the brief's surface chapters with the shipped binary#132
Merged
Conversation
The iss35 crosscheck at full depth found 102 discrepancies between the brief's 17 surface docs and what actually ships; adversarial triage confirmed 95 (7 refuted: duplicates, wrong-reality, legitimately staged). Fixes per adr-5's current-state contract: 68 rewrites to shipped reality, 14 missing-surface documentations (install override flags, session-start/session-end hooks, identity-pin write, git-identity detection), 8 deletions of abandoned-design prose (dev-sync, the agent-dispatch pack flow, disembark-to backgrounding, maxAgentTokens), 5 explicit staged markings for genuinely later-phase design. Orphaned cross-references and the stale disembark superseded-banner are stitched in the same pass. Resolves iss-121; the three merge-retro decisions and the session learnings land in DECISIONS.md. Assisted-by: Claude:claude-opus-4-8 Assisted-by: Claude:claude-fable-5
A fresh full-depth crosscheck over the reconciled brief surfaced 52 further discrepancies — mostly new sites the first run's checkers never cited (the unpinned-depth effect iss-122 records) plus sibling claims the first round's site-scoped fixes left behind. Adversarial triage confirmed 44 (8 refuted, largely the spc-N predecessor- provenance exemption); fixes applied per document with an explicit fix-the-class sibling sweep this round. Assisted-by: Claude:claude-opus-4-8 Assisted-by: Claude:claude-fable-5
…sweep (round 3) Round 3 of the crosscheck surfaced 25 findings, dominated by a class independent panels kept ruling opposite ways: bare predecessor spc-N citations that now collide with this repo's native spc-2..spc-13 store. Every such citation carries an explicit predecessor-store qualifier per the brief README's provenance note, so it can no longer be read as naming a native spec. The genuinely false claims are rewritten to the shipped reality (no reclassify sub-verb, no embark resolution prompt, itd-73 derived versioning ships, embark's optional [target] argument), and the two panel flip-flop sites carry explicit design-target markers — the ambiguity itself was the defect. The disembark voyage open question narrows to what the shipped voyage line leaves open. Assisted-by: Claude:claude-opus-4-8 Assisted-by: Claude:claude-fable-5
The final targeted pass over the four-round crosscheck's residue: bare ahoy's next-step line scoped to unmanaged kinds; doctor's distinct contribution stated as the audit pass, not sole user-scope validation; embark's conflict render depicted as the shipped per-file list and its manifest seal qualified with the excluded synthesis layer; launch's opening sentence and gate-render claims aligned with the binary's text and JSON outputs; the live spc-83-operator-surfaces bundle (itd-20/24/63/69, verified in frontmatter — the finding undercounted at two) recorded in both the kinds table and the intents/README.md bundles table; history capture idempotency stated as the (content hash, session id, kind) triple. Resolves iss-123. Assisted-by: Claude:claude-opus-4-8 Assisted-by: Claude:claude-fable-5
REPPL
added a commit
that referenced
this pull request
Jul 22, 2026
The two host-run semantic gates PROMOTE content commit fa795d5: docs-currency (full-surface review at 68ce240 carried forward — this commit differs only by the internal design-record reconciliation the detector does not inspect, plus a three-line commands/README.md count correction verified directly) and the iss35 brief-surface crosscheck (four rounds over PR #132, 102 -> 52 -> 25 -> 9 findings, 148 fixes, 15 refuted in triage; PROMOTE is the maintainer's recorded decision, with the gate's scope/depth pinning owned by iss-122). Validated with the exact CI invocation: record-lint --release-gate fa795d5 --require-gate docs-currency-reviewer --require-gate iss35-brief-surface-crosscheck, exit 0. This is the receipts commit of the two-commit release shape; on push, auto-release tags it and the release job arms the gate with its parent, whose receipts are in the tagged tree. Assisted-by: Claude:claude-fable-5
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.
Reconcile the brief's surface chapters with the shipped binary
The iss35 brief↔surface crosscheck, run at full depth for the first time (17 brief
docs, both directions, 22 independent checkers per run), found the brief's surface
chapters had drifted badly from what actually ships. This PR is the reconciliation:
148 fixes over four rounds, every finding adversarially triaged before fixing and
every fix verified against the binary and source before writing.
The four rounds
dev-sync, the agent-dispatch pack flow,disembark to,reflectmachinery)spc-Ncitations colliding with the native store — all qualified(predecessor store)per the brief README's provenance notespc-83-operator-surfacesbundle, idempotency keys)Refutations were themselves adversarial: independent verifiers re-probed the binary
and applied the two legitimate exemptions (explicit staged/design-target markings;
the predecessor-store provenance note) — 15 findings died that way rather than
becoming false "fixes".
What else rides along
.abcd/work/DECISIONS.md: the three merge-retro learnings (release rolls follow thetwo-commit receipts shape; detector findings are triaged adversarially before fixing;
a brief agreed upfront is a target document that becomes the state document
claim-by-claim at ship time).
iss-122 (the crosscheck's unpinned scope/depth) stays open — the four-round
geometric tail (102 → 52 → 25 → 9, each round finding mostly new sites) is its
empirical evidence, and pinning the gate's inputs and pass threshold is its remedy.
iss-122 calibration data, not a merge gate.
Verification
Every round ended with record-lint (0 blockers), docs lint (0 blockers), and the full
preflight (build, gofmt, vet, tests, race) green; the pre-push gate re-ran the suite
on push. No Go code, workflow file, CHANGELOG.md, or go.mod/go.sum is touched — this
PR is the design record only.
Closes #—: tracked in the abcd ledger (iss-121, iss-123), not GitHub issues.