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

Merged

mph merged 16 commits from IW-718 into main 2026-10-05 20:31:56 +00:00

Conversation 0 Commits 16 Files changed 20 +1652 -15

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

Member

Copy link

Summary

iw review-state update --drop-checkpoints-after N removes every phase_checkpoints entry whose phase is greater than N, in the same merge and the same write as the other flags of the call. kanon ag-revert (DEVDOCS-439) needs this to bring a card back to phase N in one update.

Changes

• ReviewStateUpdater: the drop runs after the checkpoint merge mode, so it also removes entries that --checkpoint adds in the same call. Keys compare as numbers (toIntOption): "02" is phase 2, "10" is after "9".
• D1: a key that is not a number is kept (it can never be a revert target; refusing would fail the whole update on an old card).
• D2: --clear-checkpoints wins; no refusal.
• D3: N must be a non-negative integer, else exit 1 before any write.
• Help: --checkpoint / --append-checkpoint now say they add to the list (they union); new update example.
• Docs: docs/review-state-cards.md "Array Merge Modes"; docs/commands/review-state.md regenerated.

Testing

• Unit: 17 (ReviewStateUpdaterTest 9, ReviewStateCliParserTest 8); harness: 7 (ReviewStateHarnessTest, incl. single-write and --help); ReviewStateSchemaTest fixture names the new field.
• E2E: 2 BATS cases in test/review-state.bats.
• Phase PR #720: CI green, merged. Pre-push unit suite passed on this head.

Follow-ups filed: #492 (two spellings of one phase key), #707 (card write is not crash-atomic).

Review packet: project-management/issues/IW-718/review-packet.md

Release notes

Když se práce na úkolu vrací k dřívější fázi, musí se k ní vrátit i karta, která stav práce zaznamenává a kterou ukazuje přehled (dashboard). Karta si pamatuje body návratu pro jednotlivé fáze. Po návratu k fázi N už body návratu pozdějších fází ukazují na práci, která v historii neexistuje, a případný další návrat k nim by skončil na ztraceném stavu. Nově stačí jeden příkaz: ten zároveň nastaví nový stav karty a odstraní body návratu všech fází po fázi N. Body návratu fází 1 až N zůstanou beze změny.

Dosud bylo nutné kartu nejdřív vymazat a potom do ní body návratu znovu zapsat, a to ve dvou samostatných zápisech. Pokud druhý zápis selhal, karta zůstala úplně bez bodů návratu. Teď proběhne vše v jediném zápisu, takže taková mezera už nevzniká.

Čísla fází se porovnávají jako čísla, nikoli jako text: „02“ je druhá fáze a „10“ následuje po „9“. Hodnota 0 odstraní všechny body návratu a u karty, která žádné body návratu nemá, příkaz nic nezmění. Neplatnou hodnotu, například záporné číslo nebo text, příkaz odmítne a kartu nezmění. Pokud karta obsahuje bod návratu, jehož fáze není číslo, příkaz ho ponechá, protože k takové fázi se vrátit nelze.

Opravili jsme také nápovědu příkazu. Ta dříve tvrdila, že zápis bodu návratu nahradí celý seznam, ačkoli ve skutečnosti nový bod k seznamu přidá. Pro všechny ostatní způsoby práce s kartou zůstává chování stejné jako dosud.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SnaPBgNE2C9y2EbP2A3du5

Closes #718

## Summary `iw review-state update --drop-checkpoints-after N` removes every `phase_checkpoints` entry whose phase is greater than N, in the same merge and the same write as the other flags of the call. kanon `ag-revert` (DEVDOCS-439) needs this to bring a card back to phase N in one update. ## Changes - `ReviewStateUpdater`: the drop runs after the checkpoint merge mode, so it also removes entries that `--checkpoint` adds in the same call. Keys compare as numbers (`toIntOption`): `"02"` is phase 2, `"10"` is after `"9"`. - D1: a key that is not a number is kept (it can never be a revert target; refusing would fail the whole update on an old card). - D2: `--clear-checkpoints` wins; no refusal. - D3: N must be a non-negative integer, else exit 1 before any write. - Help: `--checkpoint` / `--append-checkpoint` now say they add to the list (they union); new `update` example. - Docs: `docs/review-state-cards.md` "Array Merge Modes"; `docs/commands/review-state.md` regenerated. ## Testing - Unit: 17 (`ReviewStateUpdaterTest` 9, `ReviewStateCliParserTest` 8); harness: 7 (`ReviewStateHarnessTest`, incl. single-write and `--help`); `ReviewStateSchemaTest` fixture names the new field. - E2E: 2 BATS cases in `test/review-state.bats`. - Phase PR #720: CI green, merged. Pre-push unit suite passed on this head. Follow-ups filed: #492 (two spellings of one phase key), #707 (card write is not crash-atomic). Review packet: `project-management/issues/IW-718/review-packet.md` ## Release notes Když se práce na úkolu vrací k dřívější fázi, musí se k ní vrátit i karta, která stav práce zaznamenává a kterou ukazuje přehled (dashboard). Karta si pamatuje body návratu pro jednotlivé fáze. Po návratu k fázi N už body návratu pozdějších fází ukazují na práci, která v historii neexistuje, a případný další návrat k nim by skončil na ztraceném stavu. Nově stačí jeden příkaz: ten zároveň nastaví nový stav karty a odstraní body návratu všech fází po fázi N. Body návratu fází 1 až N zůstanou beze změny. Dosud bylo nutné kartu nejdřív vymazat a potom do ní body návratu znovu zapsat, a to ve dvou samostatných zápisech. Pokud druhý zápis selhal, karta zůstala úplně bez bodů návratu. Teď proběhne vše v jediném zápisu, takže taková mezera už nevzniká. Čísla fází se porovnávají jako čísla, nikoli jako text: „02“ je druhá fáze a „10“ následuje po „9“. Hodnota 0 odstraní všechny body návratu a u karty, která žádné body návratu nemá, příkaz nic nezmění. Neplatnou hodnotu, například záporné číslo nebo text, příkaz odmítne a kartu nezmění. Pokud karta obsahuje bod návratu, jehož fáze není číslo, příkaz ho ponechá, protože k takové fázi se vrátit nelze. Opravili jsme také nápovědu příkazu. Ta dříve tvrdila, že zápis bodu návratu nahradí celý seznam, ačkoli ve skutečnosti nový bod k seznamu přidá. Pro všechny ostatní způsoby práce s kartou zůstává chování stejné jako dosud. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01SnaPBgNE2C9y2EbP2A3du5 Closes #718

claude added 16 commits 2026-10-05 20:07:54 +00:00

workflow(wf): Create analysis for IW-718 ... f679983ec7

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

Artifacts:
- analysis.md
- issue.md

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnaPBgNE2C9y2EbP2A3du5

workflow(wf): Create task index for IW-718 ... b4050df2fa

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

Artifacts:
- tasks.md
- review-state.json (tasks_ready)

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnaPBgNE2C9y2EbP2A3du5

Phase 1: context ready ... 7938b5f45e

Issue: IW-718
Phase: 1 - Drop checkpoints after N (parser + merge + help + docs)

This commit marks the checkpoint for phase 1 context generation.
Use wf-implement IW-718 to return to this point.

analysis.md: the gate leaf goes in updateOtherArgs, the drop step runs
outside the phaseCheckpoints block, and the Risk 3 mitigation uses the
harness help test (the generated page shows only the synopsis).

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnaPBgNE2C9y2EbP2A3du5

workflow(wf): Phase 1 context ready for IW-718 ... f0af65c0ed

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnaPBgNE2C9y2EbP2A3du5

workflow(wf): Record review-state --commit follow-up for IW-718 ... bccc32c9ea

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnaPBgNE2C9y2EbP2A3du5

workflow(wf): Generate Phase 1 tasks for IW-718 ... c0987f88e3

Drop checkpoints after N (parser + merge + help + docs)

Artifacts:
- phase-01-tasks.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnaPBgNE2C9y2EbP2A3du5

workflow(wf): Phase 1 tasks ready for IW-718 ... 567c9a5bc0

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnaPBgNE2C9y2EbP2A3du5

chore(IW-718): move review-state card out of the tree 78019bba92

phase(IW-718): phase 01 implementation, before code review ... e2fcda7c36

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnaPBgNE2C9y2EbP2A3du5

phase(IW-718): phase 01 code review iteration 2 fixes ... ca92bb66d3

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnaPBgNE2C9y2EbP2A3du5

Drop checkpoints after N (parser + merge + help + docs) ... 7165bb893f

- review-state update --drop-checkpoints-after N removes every checkpoint whose phase is greater than N, in the same write
- Drop runs after the checkpoint mode: clear wins, appended entries are filtered too, non-numeric keys are kept
- Parser refuses a negative or non-integer N; checkpoint help text tells the truth about union semantics
- Docs: review-state-cards.md merge rules and regenerated command page

phase(IW-718): name dropCheckpointsAfter in the schema test fixture ... 4fe56d4356

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnaPBgNE2C9y2EbP2A3du5

Merge pull request 'Phase 1: Drop checkpoints after N (parser + merge + help + docs)' (#720) from IW-718-phase-01 into IW-718 ... fdfe339516

Reviewed-on: #720

chore(IW-718): mark phase 01 complete in tasks.md e6bba9a1f3

chore(IW-718): file follow-ups, add review packet ... 019c12416e

Follow-ups went to #492 and #707; the --commit line is in DEVDOCS-439 scope.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnaPBgNE2C9y2EbP2A3du5

docs(IW-718): release notes ... b56d0cdcd8

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnaPBgNE2C9y2EbP2A3du5

mph merged commit 110831e959 into main 2026-10-05 20:31:56 +00:00

mph referenced this pull request from a commit 2026-10-05 20:31:58 +00:00

Merge pull request 'IW-718: review-state update --drop-checkpoints-after N' (#722) from IW-718 into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

agent-ready

  

bug

Something isn't working

  

contract

Run the tool-contract suite on this PR

  

documentation

Improvements or additions to documentation

  

duplicate

This issue or pull request already exists

  

enhancement

New feature or request

  

good first issue

Good for newcomers

  

help wanted

Extra attention is needed

  

invalid

This doesn't seem right

  

needs-human

  

needs-input

Intake asked the human a question on the issue; waiting for the answer

  

question

Further information is requested

  

wontfix

This will not be worked on

No labels

agent-ready

bug

contract

documentation

duplicate

enhancement

good first issue

help wanted

invalid

needs-human

needs-input

question

wontfix

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

iterative-works/iw-cli!722

No description provided.