docs: collapse PLAN prior-focus stack; correct M3 hash rule (D-085) - #96
Merged
Conversation
PLAN.md 1,579 -> ~290 lines. Milestones 0-6 are KEPT. WHAT IS REMOVED The ~1,190-line superseded prior-focus stack, dated 2026-04-22 through 2026-06-08, and the narrative bulk of §Current Focus (now capped at 20 lines). Preserved at 3063d9f — `git show 3063d9f:PLAN.md` reproduces the file exactly. Naming the SHA matters: a bare `git log -- PLAN.md` is true but not findable. Removed rather than archived to a second file because the content is narration, not obligation. Its decisions are in DECISIONS.md, its designs in adr/, its dated status in the housekeeping readouts. A third copy is maintenance cost. WHAT IS KEPT, AND WHY THE EARLIER PLAN CHANGED Milestones 0-6 keep their acceptance criteria and validation blocks. The intended deletion was withdrawn because its stated ground did not survive checking: - adr/0010:19 enumerates M4's five tools — system.host.profile.v1, system.session.current.v1, system.tool.resolve.v1, system.tool.help.v1, system.policy.classify_operation.v1 — in accepted text. - adr/0004 §References anchors M3's facts / fact_observations to the external research plan Appendix D. So "M4 and M5 have no matching ADR" was false for M4, and "no design exists anywhere" was false for M3. The defensible claim was narrower — the Ring-1 producers behind those surfaces have no ADR — and it does not support deleting the blocks. WHAT IS CORRECTED INSIDE THEM Two statements that were demonstrably wrong, not merely stale: - M3's hash bullet read `row_hash = sha256(prev_hash || canonical(row))`. adr/0064:453-456 explicitly FORBIDS naive byte concatenation and binds `varint(byte_length) || field_bytes` length-prefixing. An implementer following PLAN would have built a chain the accepted design rejects. The bullet now restates the ADR and says so. - Eight scoped `just test` invocations named targets the justfile rejects. Annotated with the condition that activates each, now that targets are discovered from packages/*/tests. Collapsing the file also removed a `doc-pointer-check: provenance-below` marker, which made that gate strictly more effective: it immediately caught a stale "charter v1.3.0" pin the fence had been hiding. Rewritten as a floor — invariant 17 was introduced in v1.3.0 and is still live at v1.6.0. RULES AND TRAP EARNED BY A WITHDRAWN COMMIT An earlier commit (3e9b314, dropped, never pushed) also redefined change class I by callability. Five reviewer lenses found it unmergeable. The three checklist rules and trap #61 added here are its residue: - Citations used as AUTHORIZATION must quote their enclosing section heading verbatim in the PR body. That commit cited adr/0057:422-423 as authorizing an ApprovalGrant mint; the line sits inside "This ADR explicitly does not authorize:", a list whose final bullet is "Ring 1 service implementation code". Quote and file:line were both accurate — only the heading carried the negation. - Precedence runs ADR -> IMPLEMENT.md, never the reverse. adr/0077's nine class-I self-classifications cannot be relieved by editing IMPLEMENT.md. Amend the ADR; IMPLEMENT.md restates below it. - Charter text is quoted verbatim or not touched. That commit restated charter:54's "is live" as "exist", which would have let a future PR argue three of invariant 7's four preconditions already exist as Ring-0 schemas. Trap #61 (out-of-scope-list-quoted-as-authorization) scores the trajectory, not just the verdict, and carries a negative control so it cannot train "distrust all citations". The class-I relief itself is RELOCATED, not rejected: it belongs in the PR that implements the audit append, where code exercises the wording. Written ahead of that code it is an untested wording change — which is how the corpus became illegible in the first place. Nothing is blocked by deferring it. The policy-snapshot loader stands on adr/0060:325-331 and adr/0061:371, needs no new ADR, and is the next lane. With no class-I relief in flight, PLAN.md's M4-Month-4 architecture note is simply correct and needs no edit. Validation: `just verify` green.
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
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
PLAN.md1,579 → ~290 lines. Milestones 0-6 are kept.Change class: A (docs) + H (one regression trap). Ledger row D-085.
Removed
The ~1,190-line superseded prior-focus stack (2026-04-22 → 2026-06-08) and the narrative bulk of §Current Focus, now capped at 20 lines.
Preserved at
3063d9f—git show 3063d9f:PLAN.mdreproduces the file exactly. Naming the SHA matters; a baregit log -- PLAN.mdis true but not findable.Removed rather than archived to a second file because the content is narration, not obligation: decisions are in
DECISIONS.md, designs inadr/, dated status in the housekeeping readouts. A third copy is maintenance cost.Kept — and why the plan changed mid-flight
The intended deletion of M3-M6 was withdrawn, because its stated ground did not survive checking:
adr/0010:19enumerates M4's five tools —system.host.profile.v1,system.session.current.v1,system.tool.resolve.v1,system.tool.help.v1,system.policy.classify_operation.v1— instatus: acceptedtext.adr/0004§References anchors M3'sfacts/fact_observationsto the external research plan Appendix D.So "M4 and M5 have no matching ADR" was false for M4, and "no design exists anywhere" was false for M3. The defensible claim was narrower — the Ring-1 producers behind those surfaces have no ADR — and it does not support deleting the blocks.
Corrected inside them
Two statements that were wrong, not merely stale:
row_hash = sha256(prev_hash || canonical(row))adr/0064:452-456— canonical field order,GENESISsentinel,varint(byte_length) || field_byteslength-prefixing. The ADR forbids naive concatenation; an implementer following PLAN would have built a chain the accepted design rejects.just test <target>calls the justfile rejectspackages/*/tests.Side effect worth noting: collapsing the file removed a
doc-pointer-check: provenance-belowmarker, and the gate immediately caught a stalecharter v1.3.0pin the fence had been hiding. Rewritten as a floor. Removing narration made a gate more effective.Rules and trap earned by a withdrawn commit
An earlier commit (
3e9b314, dropped, never pushed) also redefined change class I by callability. Five reviewer lenses found it unmergeable. Three checklist rules and trap #61 are its residue:adr/0057:422-423as authorizing an ApprovalGrant mint. The line sits inside## Out of scope→ "This ADR explicitly does not authorize:", a list whose final bullet is "Ring 1 service implementation code." Quote and file:line were both accurate — only the heading carried the negation.adr/0077's nine class-I self-classifications cannot be relieved by editingIMPLEMENT.md. Amend the ADR;IMPLEMENT.mdrestates below it.charter:54's "is live" as "exist" — which would have let a future PR argue three of invariant 7's four preconditions already exist as Ring-0 schemas.Trap #61 scores the trajectory, not just the verdict, and carries a negative control so it cannot train "distrust all citations."
What is deferred, and why nothing is blocked
The class-I relief is relocated, not rejected — it belongs in the PR that implements the audit append, where code exercises the wording. Written ahead of that code it is an untested wording change, which is how the corpus became illegible in the first place.
Nothing waits on it. The policy-snapshot loader stands on
adr/0060:325-331(assigns it) andadr/0061:371(specifies its checkpoint-level test obligation), needs no new ADR, and is the next lane. And with no class-I relief in flight, PLAN's M4-Month-4 architecture note is simply correct and needs no edit.Boundary checks
OperationShaperemains upstream ofCommandShapeadr/0010:19,adr/0004§References andadr/0064:452-456are cited as evidence that a PLAN statement was wrong, and all three sit under## Decision/## References/## Contextheadings, not under an out-of-scope listValidation
just verify— green.