docs(proof): gate journaling on a 4/4 retention score

[tonyketcham]

Keep Proof writes for durable turning points only. Score the
information before any mutation or body edit. Existing records do
not bypass the gate. Bundle the four eval cases with the skill.

Drop PR-lifecycle Proof records from #254 and keep the accepted
pagination Decision as the durable rationale.

Co-authored-by: Cursor cursoragent@cursor.com

[tonyketcham]

Revision history

#	Type	Changes	Reason	Date
1	initial	0f4a144		2026-08-22 18:57 UTC
2	content	0f4a144 → 03023ec (raw)	add Unreleased changelog note for the 4/4 journaling gate	2026-08-22 18:57 UTC
3	content	03023ec → b9aa6cd (raw)	drop the changelog sentence about handoffs and PR anecdotes	2026-08-22 18:59 UTC
4	content	b9aa6cd → fe367ce (raw)	address review: carve 4/4 gate to creates and claim-adding body edits, require rejectSiblings false in eval 4, stop teaching bare record deletes, and move 1.0.1-shipped notes out of Unreleased	2026-08-22 20:05 UTC

[cursor]

Stale comment

This PR is skill, eval, changelog, and journal cleanup — not a dependency bump. I reviewed 55673a2...b9aa6cd only. Stacked completeness work from #254 is context, not this change.

The 4/4 gate belongs in the skill, not the writer schema. Dual SKILL.md / evals.json copies match, and pnpm --filter @flatbread/proof skills:check passes. Dropping the #254 review-lifecycle records and leaving dec-treat-page-has-more-as-pagination-only--dv24ta688adf262v as a standalone ADR is the right graph end state. No leftover ids.

Three agent-behavior holes need text fixes before this ships:

1. Eval 3 tells agents to remove records. Proof has no Delete mutation. Reads fail closed on dangling edges (PROOF_DANGLING_RELATION). This commit only stayed safe because it stripped edges on the kept Decision in the same change.
2. Eval 4 says create and accept a Decision and does not require "rejectSiblings": false. The default is true. On Effort eff-proof-and-contributor-operating-system--ahhgtafvdhg4dfve that would reject still-proposed dec-separate-execution-and-display-planes--spm2ckxvdsch6h9m.
3. The gate scores “any mutation or body edit,” which also covers AcceptDecision, ResolveIssue, SetEffortStatus, and can scare agents off proof cache prune. Recommended session workflow step 3 still tells agents to write during work with no 4/4 check.

Also decide the journal question this PR raises: the 4/4 gate is itself a durable product rule (eval 4’s pattern), and no Decision records why, what was rejected, or what would reverse it. Either write and accept that Decision on the same Effort, or say in the gate section that process rules live in the skill and must not be re-journaled.

Non-blocking: the skill description dropped WriteCitation / WriteBlob / blocking-decisions cues and put the Never-list in the routing field. Evals 2 and 3 still replay the #254 file-split and kind-correction story; one generic refuse case would do.

No packages/*/src change. The three HIGH items are skill and eval wording only.

  

_{Sent by Cursor Automation: Flatbread PR Review}

[cursor]

Stale comment

Review (b9aa6cd)

The 4/4 write gate belongs in the Proof skill, not the writer. Private scoring is the right layer: future need, durable effect, causal value, and unique signal are judgment calls. Canonical packages/proof/skills/proof/ and the .agents projection match; pnpm skills:check passes.

The journal cleanup does what the gate asks. The accepted pagination Decision (dec-treat-page-has-more-as-pagination-only--dv24ta688adf262v) keeps Context, Choice, Alternatives, Consequences, and Reversal, and scores 4/4. The deleted #254 review trail (Citations, Findings, Issue, file-split Decision) was session noise. No leftover ids. A second Decision that only restates this gate is not required: the skill, evals, changelog, and PR already carry the rule.

Three notes before merge:

1. CHANGELOG — the new Unreleased bullet replaced the oven/proof rename line instead of sitting above it. That sentence is gone from the tree.
2. Eval 3 — “Remove or fold” has no matching mutation. A git delete that leaves a stored derives_from now fails closed with PROOF_DANGLING_RELATION.
3. Eval 4 — “Create and accept” does not say rejectSiblings: false. Default accept would reject other proposed Decisions on the same Effort. This repo still has three.

YAML trigger narrowing (dropped WriteCitation / effort graph / agent memory) looks intentional. Do not attach this to iss-proof-output-retention-follow-ups-remain-open; that Issue is transcript retention, not this write gate.

Verdict: COMMENT

Domain	Verdict
Architecture	COMMENT
Quality	COMMENT
Proof journal	APPROVE
Correctness	COMMENT

  

_{Sent by Cursor Automation: Flatbread PR Review}

[cursor]

Stale comment

Review (fe367ce)

The four prior notes are fixed. The 4/4 write gate now scores only creates and body text that add claims. Lifecycle transitions and proof cache prune are exempt. Workflow step 3 points at the gate. Eval 4 requires rejectSiblings: false. Eval 3 no longer teaches a bare delete. Shipped 1.0.1 notes sit under ## 1.0.1; Unreleased keeps the gate, the stacked completeness work, and the post-1.0.1 cross-effort change.

The journal fold is right. The accepted Decision dec-treat-page-has-more-as-pagination-only--dv24ta688adf262v scores 4/4. The deleted #254 review trail was session noise. No leftover ids. Dual SKILL.md / evals.json copies match; pnpm skills:check passes. A second Decision that restates this gate is not required.

Two wording seams remain:

1. Eval 3 still offers a file-drop path that strips inbound and outbound ids. Those ids live in frontmatter. The skill forbids hand-edits, and no mutation clears edges on an existing accepted Decision. Pick one: add a one-line cleanup exception next to the frontmatter rule, or drop the strip branch and leave the Finding for maintainers.
2. The gate names creates, claim-adding body edits, and a lifecycle carve-out. Supersede and Invalidate write retained edges and sit in neither set. Say they need a 4/4 reason, or list them with lifecycle if they are mechanical once both records already scored.

No packages/*/src change. Not requesting changes.

Verdict: COMMENT

Domain	Verdict
Architecture	COMMENT
Quality	COMMENT
Proof journal	APPROVE
Correctness	COMMENT

  

_{Sent by Cursor Automation: Flatbread PR Review}

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[cursor]

Stale comment

Review (ff1d38c)

The two notes at fe367ce are fixed. Eval 3 now teaches Retract. The write gate names Retract as exempt and scores Supersede / Invalidate as creates. Dual skill copies match; pnpm skills:check passes.

Retract is the right archive layer: tombstone the file, strip that id from the same Effort in one journal transaction, omit the record from browse reads, keep proof get, refuse later writes, no Restore. Growing the enum from 15 to 16 is justified. The accepted Decision dec-retract-noise-instead-of-deleting-proof-files--k6jk0d2bdp1m9jw9 scores 4/4 (context, four rejected alternatives, consequences, reversal). The Constraint tip at sixteen mutations supersedes the fifteen-mutation bound. AcceptDecision left dec-adopt-a-bounded-status-briefing-fast-path-for-ef--kcw0rw39g3b2ym2h proposed. The earlier #254 file deletes predate this mutation and leave no stored ids.

One composition hole remains. stripRelationId deletes the last resolved_by, mitigated_by, evidence, rejected_by, or superseded_by value and does not touch status / state. Browse then shows a settled record whose closer is gone, and no mutation can reopen it. Refuse Retract in that case and name the dependents. Do not silently reopen. Do not add Restore. The happy path (noise Finding with only derives_from / supersedes) is tested; this shape is not.

Not requesting changes. The intended Retract path is session noise that never closed another record.

Verdict: COMMENT

Domain	Verdict
Architecture	COMMENT
Quality	COMMENT
Proof journal	APPROVE
Correctness	COMMENT

  

_{Sent by Cursor Automation: Flatbread PR Review}

[cursor]

Review (9878dc1)

The sole-closer hole from ff1d38c is closed. Retract now refuses before any tombstone or strip when the target is the last resolved_by, mitigated_by, evidence, rejected_by, or superseded_by value on a live same-Effort record. Retracted survivors are skipped. Multiple closers still retract and keep the survivor's status. Planner tests cover those shapes. Dual skill copies match; pnpm -F @flatbread/proof skills:check passes. All 38 planner tests pass.

Journal stays sound. The accepted Retract Decision and the sixteen-mutation Constraint tip score 4/4. The 4/4 write gate correctly has no Decision. #254 leftover ids are gone. This increment needed no new journal record: the planner error and tests already carry the refuse.

One leftover MED: isSoleCloser treats evidence as the last remaining id. SetRiskState realized only requires that some evidence id is a Finding. Retract that Finding and a realized Risk can keep state: 'realized' with only a Citation or Decision left. The writer cannot create that graph and cannot reopen it.

The skill still says Retract always strips. The refuse error says "Supersede or retract those records first," but you cannot Supersede an Issue with a Finding.

Not requesting changes. The intended Retract path is session noise that never closed another record.

Verdict: COMMENT

Domain	Verdict
Architecture	COMMENT
Quality	COMMENT
Proof journal	APPROVE
Correctness	COMMENT

  

_{Sent by Cursor Automation: Flatbread PR Review}

[cursor]

isSoleCloser returns false when any other evidence id remains. SetRiskState realized only requires that some evidence id is a Finding (planner.ts around the realized check). Retract that Finding while a Citation or Decision stays in evidence and the Risk stays realized with no Finding. The writer cannot create that graph and cannot reopen it.

Treat a live Risk with state === 'realized' as blocked when no remaining evidence id is a Finding. Keep the last-id rule for accepted. Add a planner test with mixed evidence.

[cursor]

This still says the writer always strips the id. After 9878dc1, Retract refuses when the target is the last closer on a live same-Effort record (resolved_by, mitigated_by, evidence, rejected_by, superseded_by). Name that refuse here, and in reference.md / the Unreleased changelog bullet.

Recovery is: retract the named dependents first, or add another closer. Do not reopen. The planner error also says "Supersede or retract," which is not always legal — you cannot Supersede an Issue with a Finding.