review-state update --drop-checkpoints-after N #718

New issue

Closed

opened 2026-10-05 12:39:24 +00:00 by claude · 0 comments

claude commented

2026-10-05 12:39:24 +00:00

Member

Problem

A workflow that reverts a branch to the checkpoint of phase N (kanon ag-revert: git reset --hard <phase N context sha>) must bring the review-state card back to phase N. The card must keep the checkpoints of phases 1..N and lose those of phases after N: after the reset, those checkpoints name commits that are no longer in the branch history, and a later revert to one of them would reset to an orphaned commit.

update cannot do this in one call. --checkpoint and --append-checkpoint are synonyms that union into the card (core/model/ReviewStateCliParser.scala:171, unionOnAppend = true at :281; deliberate since a16b79fd, "must never lose an earlier phase"). --clear-checkpoints drops all of them and wins over both. So the caller must clear and re-add in two writes, filtering the checkpoints itself — logic that belongs in the tool, and a window where a failed second write leaves the card with no checkpoints.

Change

iw review-state update --drop-checkpoints-after N removes every entry of phase_checkpoints whose phase is greater than N, in the same merge and the same atomic write as the other flags of the call.

Phase keys compare as numbers ("02" and "2" are phase 2; "10" is after "9"). A key that is not a number: decide and document (refuse the update, or keep the entry).
--checkpoint / --append-checkpoint in the same call still union in; the drop applies to the existing card's entries and to the added ones alike, so the result never holds a phase after N.
With --clear-checkpoints in the same call: refuse as conflicting flags, or let clear win — decide and document.
N must be a non-negative integer; anything else is an argument error (exit 1).
The union rule stays as it is for every other caller.
Fix the help text: --checkpoint is described as replacing the list, but it unions.

Acceptance

Card with checkpoints 1, 2, 3; update --status context_ready --phase 2 --step context --drop-checkpoints-after 2 leaves checkpoints 1 and 2 with their SHAs, and the other fields updated.
--drop-checkpoints-after 0 leaves no checkpoints.
A card with no checkpoints: the flag is a no-op.
Keys "02" and "10" are compared as numbers.

Context

Consumer: kanon DEVDOCS-439 Phase 2, ag-revert Step 5b: one update after the reset, with no checkpoint filtering in the agent's code (decided by Michal, 2026-10-05). DEVDOCS-439's final PR waits for the iw-cli release that ships this and IW-715.

Type: feature
Filed from: /home/mph/ops/kanon-DEVDOCS-439 on branch DEVDOCS-439-phase-02

## Problem A workflow that reverts a branch to the checkpoint of phase N (kanon `ag-revert`: `git reset --hard <phase N context sha>`) must bring the review-state card back to phase N. The card must keep the checkpoints of phases 1..N and lose those of phases after N: after the reset, those checkpoints name commits that are no longer in the branch history, and a later revert to one of them would reset to an orphaned commit. `update` cannot do this in one call. `--checkpoint` and `--append-checkpoint` are synonyms that union into the card (`core/model/ReviewStateCliParser.scala:171`, `unionOnAppend = true` at `:281`; deliberate since `a16b79fd`, "must never lose an earlier phase"). `--clear-checkpoints` drops all of them and wins over both. So the caller must clear and re-add in two writes, filtering the checkpoints itself — logic that belongs in the tool, and a window where a failed second write leaves the card with no checkpoints. ## Change `iw review-state update --drop-checkpoints-after N` removes every entry of `phase_checkpoints` whose phase is greater than N, in the same merge and the same atomic write as the other flags of the call. - Phase keys compare as numbers (`"02"` and `"2"` are phase 2; `"10"` is after `"9"`). A key that is not a number: decide and document (refuse the update, or keep the entry). - `--checkpoint` / `--append-checkpoint` in the same call still union in; the drop applies to the existing card's entries and to the added ones alike, so the result never holds a phase after N. - With `--clear-checkpoints` in the same call: refuse as conflicting flags, or let clear win — decide and document. - N must be a non-negative integer; anything else is an argument error (exit 1). - The union rule stays as it is for every other caller. - Fix the help text: `--checkpoint` is described as replacing the list, but it unions. ## Acceptance - Card with checkpoints 1, 2, 3; `update --status context_ready --phase 2 --step context --drop-checkpoints-after 2` leaves checkpoints 1 and 2 with their SHAs, and the other fields updated. - `--drop-checkpoints-after 0` leaves no checkpoints. - A card with no checkpoints: the flag is a no-op. - Keys `"02"` and `"10"` are compared as numbers. ## Context Consumer: kanon DEVDOCS-439 Phase 2, `ag-revert` Step 5b: one `update` after the reset, with no checkpoint filtering in the agent's code (decided by Michal, 2026-10-05). DEVDOCS-439's final PR waits for the iw-cli release that ships this and IW-715. --- **Type:** feature **Filed from:** `/home/mph/ops/kanon-DEVDOCS-439` on branch `DEVDOCS-439-phase-02`

claude referenced this issue from a pull request that will close it,

2026-10-05 20:07:54 +00:00

IW-718: review-state update --drop-checkpoints-after N #722