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

New issue

Closed

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

john commented

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

Owner

Source: deep dive, broader design B1
Verdict: AGREE - proposal

Claim as reviewed

Four operations need the same missing primitive: phase completion (ROADMAP + REQUIREMENTS), release bump (primary manifest + sibling + changelog), milestone prune (phase directories + both documents), and renumbering (deletion/moves + three documents).

At HEAD `f354864` (v3.3.0)

Renumbering already reports partial application honestly at cadence-core/bin/planning.mjs:3227-3273, which is better than pretending it can roll back. The other three claim or imply atomicity they do not have.

Note

This is the shared fix for the prune, phase-done and release-bump issues in this batch. A common journal makes partial operations resumable and lets /cad-health and /cad-progress report them deterministically.

**Source:** deep dive, broader design B1 **Verdict:** AGREE - proposal ### Claim as reviewed Four operations need the same missing primitive: phase completion (ROADMAP + REQUIREMENTS), release bump (primary manifest + sibling + changelog), milestone prune (phase directories + both documents), and renumbering (deletion/moves + three documents). ### At HEAD f354864 (v3.3.0) Renumbering already reports partial application honestly at `cadence-core/bin/planning.mjs:3227-3273`, which is better than pretending it can roll back. The other three claim or imply atomicity they do not have. ### Note This is the shared fix for the prune, phase-done and release-bump issues in this batch. A common journal makes partial operations resumable and lets `/cad-health` and `/cad-progress` report them deterministically.

john added the

proposal

external-review

labels

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

john commented

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

Author

Owner

Rescoped: this is a DECISION task, not a build task, and it lands in v3.5.6.

Why not earlier: all four operations this would serve have local fixes that are much smaller than the primitive. #128 (v3.3.1) stops writing docs for phases whose directory op failed. #139 (v3.5.4) reads both manifests before writing either. #140 (v3.5.6) deletes a claim it cannot honour. Building a shared journal first means designing it from three defects instead of from three working fixes.

Why v3.5.6: that is where #140 lands, so it is the first moment all three local fixes exist and can be compared. Rule of three - extract after the third instance, not before it.

The decision to make there, in one sitting:

Read the three landed fixes. Do they rhyme, or did each want something different?
Note that renumber (planning.mjs:3227-3273) already handles this class WITHOUT a journal - it reports partial application honestly rather than pretending it can roll back. If the other three can do the same, resumability is a capability nobody asked for.
Decide: build the primitive, or close this with the reasoning.

Closing with reasoning is an expected outcome, not a failure. Do not carry this as open scope past v3.5.6.

Rescoped: this is a DECISION task, not a build task, and it lands in v3.5.6. Why not earlier: all four operations this would serve have local fixes that are much smaller than the primitive. #128 (v3.3.1) stops writing docs for phases whose directory op failed. #139 (v3.5.4) reads both manifests before writing either. #140 (v3.5.6) deletes a claim it cannot honour. Building a shared journal first means designing it from three defects instead of from three working fixes. Why v3.5.6: that is where #140 lands, so it is the first moment all three local fixes exist and can be compared. Rule of three - extract after the third instance, not before it. The decision to make there, in one sitting: 1. Read the three landed fixes. Do they rhyme, or did each want something different? 2. Note that renumber (planning.mjs:3227-3273) already handles this class WITHOUT a journal - it reports partial application honestly rather than pretending it can roll back. If the other three can do the same, resumability is a capability nobody asked for. 3. Decide: build the primitive, or close this with the reasoning. Closing with reasoning is an expected outcome, not a failure. Do not carry this as open scope past v3.5.6.

john added this to the v3.5.6 milestone

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

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 from a pull request that will close it,

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