phase-done claims all-or-nothing over two independent writes #140

New issue

Closed

opened 2026-08-15 14:33:41 +00:00 by john · 1 comment

john commented

2026-08-15 14:33:41 +00:00

Owner

Source: deep dive F8
Verdict: AGREE - low

Claim as reviewed

cmdPhaseDone validates both edits and comments "all-or-nothing", then performs separate atomic renames for ROADMAP.md and REQUIREMENTS.md. An atomic rename protects one file from torn bytes; it cannot create a transaction across files.

At HEAD `f354864` (v3.3.0)

cadence-core/bin/planning.mjs:572-575:

// Both edits validated before either write - all-or-nothing.
atomicWrite(roadmapFile, boxed.text);
if (newReqText !== null) atomicWrite(reqFile, newReqText);

If the second write throws, the roadmap marks the phase complete while its traceability rows stay Pending.

Note

Low consequence: /cad-audit reports the divergence and a re-run repairs it. The defect is the claim, not the damage.

Minimum fix: drop the all-or-nothing wording. Better fix: fold into the shared journal proposal.

**Source:** deep dive F8 **Verdict:** AGREE - low ### Claim as reviewed `cmdPhaseDone` validates both edits and comments "all-or-nothing", then performs separate atomic renames for ROADMAP.md and REQUIREMENTS.md. An atomic rename protects one file from torn bytes; it cannot create a transaction across files. ### At HEAD f354864 (v3.3.0) `cadence-core/bin/planning.mjs:572-575`: ``` // Both edits validated before either write - all-or-nothing. atomicWrite(roadmapFile, boxed.text); if (newReqText !== null) atomicWrite(reqFile, newReqText); ``` If the second write throws, the roadmap marks the phase complete while its traceability rows stay Pending. ### Note Low consequence: `/cad-audit` reports the divergence and a re-run repairs it. The defect is the claim, not the damage. Minimum fix: drop the all-or-nothing wording. Better fix: fold into the shared journal proposal.

john added the

bug

external-review

labels

2026-08-15 14:33:41 +00:00

john added this to the v3.5.6 milestone

2026-08-15 15:09:30 +00:00

john referenced this issue

2026-08-15 15:14:18 +00:00

Add a journal/recovery primitive for multi-file state transitions #145

john referenced this issue

2026-08-20 15:26:09 +00:00

v3.5.6: the machinery that records what a run did #226

john referenced this issue from a commit

2026-08-20 15:29:35 +00:00

docs: open v3.5.6 and add phase 1

john modified the milestone from v3.5.6 to v3.5.8

2026-08-20 15:34:10 +00:00

john referenced this issue

2026-08-22 17:55:08 +00:00

v3.5.8 - the transition that claims to be one #229

john commented

2026-08-22 19:41:47 +00:00

Author

Owner

Shipped in v3.5.8 as JRN-02, merged via #229.

cmdPhaseDone now runs its whole write set through the runTransition primitive: every edit is validated before the first atomicWrite, and the envelope carries a wrote field naming which of ROADMAP.md and REQUIREMENTS.md actually moved. The "all-or-nothing" comment is gone rather than qualified - sed -n '/^function cmdPhaseDone/,/^}/p' cadence-core/bin/planning.mjs | grep -c "all-or-nothing" prints 0.

REQUIREMENTS.md is read as a three-state fact: absent keeps the roadmap-only write, present-but-unreadable refuses before ROADMAP.md is touched. A test drives a directory at REQUIREMENTS.md and asserts ROADMAP.md's sha256 is byte-identical across the run.

Known gap: the partial-flip arm - the envelope for a write that fails past the pre-flight - is probe-proven only and ships with no committed regression test.

Shipped in v3.5.8 as JRN-02, merged via #229. `cmdPhaseDone` now runs its whole write set through the `runTransition` primitive: every edit is validated before the first `atomicWrite`, and the envelope carries a `wrote` field naming which of ROADMAP.md and REQUIREMENTS.md actually moved. The "all-or-nothing" comment is gone rather than qualified - `sed -n '/^function cmdPhaseDone/,/^}/p' cadence-core/bin/planning.mjs | grep -c "all-or-nothing"` prints 0. REQUIREMENTS.md is read as a three-state fact: absent keeps the roadmap-only write, present-but-unreadable refuses before ROADMAP.md is touched. A test drives a directory at REQUIREMENTS.md and asserts ROADMAP.md's sha256 is byte-identical across the run. Known gap: the `partial-flip` arm - the envelope for a write that fails past the pre-flight - is probe-proven only and ships with no committed regression test.

john closed this issue

2026-08-22 19:41:51 +00:00