IW-702: Keep the review-state card out of version control #709

Merged

mph merged 41 commits from IW-702 into main 2026-10-04 14:42:05 +00:00

Conversation 0 Commits 41 Files changed 105 +7434 -1457

claude commented 2026-10-04 14:14:47 +00:00

Member

Copy link

Summary

The review-state card moves out of the working tree into <common git dir>/iw/review-state/ (issues/<ID>.json, or efforts/<slug>/<NN>-<slice>.json for a slice). Git does not version it, and no iw command commits it any more. The merge gate now has one path: the head that CI proved green is the head that merges.

Changes

• Phase 1 (#703): card location model (ReviewStateLocation, safe slug and slice segments) and common-git-dir resolution with no git process.
• Phase 2 (#704): the CLI and the dashboard read and write the card at the new location. A one-time move takes a tracked in-tree card out of git (chore(<ID>): move review-state card out of the tree), and drops a stale copy that a reset brings back. review-state --commit, CommitPolicy and PhasePr.persist are removed.
• Phase 3 (#705): the state-only merge path (stateOnlyGatedSha, mergeGatedCommit, UnjudgedHead, the "CI not judged" note) and CiGate.snapshotCheck are removed. No command writes or reads ci_gated_sha, but the schema still accepts it. Help text, docs/review-state-cards.md, docs/commands/review-state.md, the API docs and llms.txt describe the new location.

Strict cut, no compatibility code. --commit exits 1. An explicit --input/--output is used as given. The dashboard reads only the out-of-tree card. Callers must apply contract changes 1-8 (listed in docs/review-state-cards.md). The kanon follow-up is dev-docs#439 and must land in the same release window.

Testing

Each phase PR passed the full CI suite before it merged. See project-management/issues/IW-702/implementation-log.md and review-packet.md for the test summary per phase.

Follow-ups

#706 (finished-issue cards are never removed), #707 (Small fixes: core), #708 (Small fixes: docs/plans), and the kanon comment on dev-docs#439.

Release notes

See project-management/issues/IW-702/release-notes.md (Czech).

🤖 Generated with Claude Code

https://claude.ai/code/session_01GkYxxd3DijobEs1dWRhXz3

Closes #702

## Summary The review-state card moves out of the working tree into `<common git dir>/iw/review-state/` (`issues/<ID>.json`, or `efforts/<slug>/<NN>-<slice>.json` for a slice). Git does not version it, and no iw command commits it any more. The merge gate now has one path: the head that CI proved green is the head that merges. ## Changes - **Phase 1 (#703):** card location model (`ReviewStateLocation`, safe slug and slice segments) and common-git-dir resolution with no git process. - **Phase 2 (#704):** the CLI and the dashboard read and write the card at the new location. A one-time move takes a tracked in-tree card out of git (`chore(<ID>): move review-state card out of the tree`), and drops a stale copy that a reset brings back. `review-state --commit`, `CommitPolicy` and `PhasePr.persist` are removed. - **Phase 3 (#705):** the state-only merge path (`stateOnlyGatedSha`, `mergeGatedCommit`, `UnjudgedHead`, the "CI not judged" note) and `CiGate.snapshotCheck` are removed. No command writes or reads `ci_gated_sha`, but the schema still accepts it. Help text, `docs/review-state-cards.md`, `docs/commands/review-state.md`, the API docs and `llms.txt` describe the new location. **Strict cut, no compatibility code.** `--commit` exits 1. An explicit `--input`/`--output` is used as given. The dashboard reads only the out-of-tree card. Callers must apply contract changes 1-8 (listed in `docs/review-state-cards.md`). The kanon follow-up is dev-docs#439 and must land in the same release window. ## Testing Each phase PR passed the full CI suite before it merged. See `project-management/issues/IW-702/implementation-log.md` and `review-packet.md` for the test summary per phase. ## Follow-ups #706 (finished-issue cards are never removed), #707 (Small fixes: core), #708 (Small fixes: docs/plans), and the kanon comment on dev-docs#439. ## Release notes See `project-management/issues/IW-702/release-notes.md` (Czech). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01GkYxxd3DijobEs1dWRhXz3 Closes #702

claude added 41 commits 2026-10-04 14:14:47 +00:00

workflow(wf): Create analysis for IW-702 ... 50eaa7cb3e

Keep the review-state card out of version control

Artifacts:
- analysis.md
- issue.md

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

workflow: Resolve clarifications for IW-702 ... 012cc5379b

Resolved:
- analysis.md: Per-worktree or common git dir for the card → common git dir (Option A); iw rm keeps the card
- analysis.md: Transition contract for kanon → strict cut (Option A): --commit removed, explicit paths used as given, forIssue returns Either, no dashboard fallback, kanon follow-up in the same release window

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

workflow: Record IW-702 follow-ups ... 27a61829d3

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

chore(IW-702): update review-state to tasks_ready 164b67cf8a

workflow(wf): Create task index for IW-702 ... e21dc4ce84

Keep the review-state card out of version control

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

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

Phase 1: context ready ... 566f754dd1

Issue: IW-702
Phase: 1 - Card location model + git-dir access

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

Two open questions for Phase 1 are recorded in analysis.md.

🤖 Generated with Claude Code

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

chore(IW-702): update review-state to context_ready 9b1caa1c4c

workflow: Resolve clarifications for IW-702 ... e9df8bca81

Resolved:
- analysis.md: Does ReviewStateLocation.forIssue check its key, and with what type? → String key, Either result, same one-safe-segment check as forSlice
- analysis.md: How does Phase 2 tell that an in-tree card is tracked? → new GitOps.isTracked reads the index, added in Phase 1 (+0.5h)

🤖 Generated with Claude Code

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

workflow(wf): Generate Phase 1 tasks for IW-702 ... 610671733e

Card location model + git-dir access

Artifacts:
- phase-01-tasks.md

🤖 Generated with Claude Code

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

chore(IW-702): update review-state to tasks_ready ce727990a0

chore(IW-702): update review-state for phase 01 2d8f17e1a6

phase(IW-702): phase 01 implementation, before code review 0df36e8a2f

phase(IW-702): phase 01 code review iteration 2 fixes 13faa1ebc8

phase(IW-702): phase 01 code review iteration 3 fixes f7365eb498

phase(IW-702): phase 01 code review iteration 3 fixes 85adf996cf

Card location model + git-dir access ... 48b4f373d4

- ReviewStateLocation: issue and slice card paths under <common-git-dir>/iw/review-state, with checked keys and pointers
- TrackedCardMove: pure Move / DropStale / Keep decision for the one-time move
- GitDirReader: shared .git and commondir reader, used by WorktreeServices; stateRoot requires HEAD in the common dir
- GitOps.stateRoot, untrack and isTracked (literal pathspecs), live and fake

Merge pull request 'Phase 1: Card location model + git-dir access' (#703) from IW-702-phase-01 into IW-702 ... f13d15f4f8

Reviewed-on: #703

chore(IW-702): update review-state for phase 01 946fd6bd1a

chore(IW-702): mark phase 01 complete in tasks.md dcd51514ae

Phase 2: context ready ... b110750a46

Issue: IW-702
Phase: 2 - Card moves out of the tree, no more card commits

This commit marks the checkpoint for phase 2 context generation.
Three CLARIFY decisions in analysis.md block the phase.
Use wf-implement IW-702 to return to this point.

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

chore(IW-702): update review-state to context_ready 4d0801cbc5

workflow: Resolve clarifications for IW-702 ... 709aa2791a

Resolved:
- analysis.md: When does `--commit` leave `review-state write|update`? → Phase 2 removes and rejects it, as analysis.md already stated; the phase plan line is corrected
- analysis.md: How do we run IW-702's own Phase 3 workflow? → kanon workflow, review-state steps written by hand without --input and --commit
- analysis.md: Does a card location that fails to resolve stop a phase command? → stop with exit 1 before any push, with a two-line message that tells the user to fix the cause and run again

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

workflow(wf): Generate Phase 2 tasks for IW-702 ... d25d7548fe

Card moves out of the tree, no more card commits

Artifacts:
- phase-02-tasks.md
- A1 message scope extended to phase-merge; review-state prints one line

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

chore(IW-702): update review-state to tasks_ready 6f087b09a4

chore(IW-702): update review-state for phase 02 ff9df618be

phase(IW-702): phase 02 implementation, before code review ... d87cbefed9

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

phase(IW-702): phase 02 code review iteration 2 fixes ... be37318524

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

phase(IW-702): phase 02 code review iteration 3 fixes ... 0011253fb1

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

chore(IW-702): move review-state card out of the tree 8c1e4c6a6d

Card moves out of the tree, no more card commits ... ae00d278b8

- Review-state card lives in the common git dir; a tracked in-tree card moves out once, in one commit
- Phase commands, ci-gate and review-state no longer commit the card; the --commit switch is gone
- A card location that does not resolve stops a phase command before any push (decision A1)
- Dashboard reads the card from the state root and leaks no file content in errors

Merge pull request 'Phase 2: Card moves out of the tree, no more card commits' (#704) from IW-702-phase-02 into IW-702 ... 426f1b980e

Reviewed-on: #704

chore(IW-702): mark phase 02 complete in tasks.md aebe8f6914

Phase 3: context ready ... 426bd0eab6

Issue: IW-702
Phase: 3 - Merge-gate cleanup, CLI surface, docs

This commit marks the checkpoint for phase 3 context generation.
It also records Michal's Phase 3 decisions in analysis.md: ci_gated_sha
is no longer written (contract change 8), docs/api pages for the
Phase 1-2 modules, the --commit removal as a recorded exception to the
deprecation policy, and caller migration notes in
docs/review-state-cards.md. Phase 3 estimate is now 6-8.5h.

Use wf-implement IW-702 to return to this point.

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

workflow(wf): Generate Phase 3 tasks for IW-702 ... 085c32ea32

Merge-gate cleanup, CLI surface, docs

Artifacts:
- phase-03-tasks.md

Also corrects two facts in phase-03-context.md: the drift test class is
iw.tests.CommandDocsDriftTest, and docs/commands/review-state.md does
change in this phase.

🤖 Generated with Claude Code

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

phase(IW-702): phase 03 implementation, before code review ... 61e880839d

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

phase(IW-702): phase 03 code review iteration 2 fixes ... 0ff769b638

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

Merge-gate cleanup, CLI surface, docs ... 884ca667e9

- phase-merge always runs the full CI gate; the state-only path and the CI-not-judged note are gone
- No command writes or reads ci_gated_sha; the schema still accepts it on older cards
- Help text, docs and API docs say the card lives in the common git dir and no command commits it
- docs/review-state-cards.md lists contract changes 1-8 and the --commit exception
- New API pages for ReviewStateLocation, TrackedCardMove, GitDirReader, ReviewStateMove, ReviewStatePath

Merge pull request 'Phase 3: Merge-gate cleanup, CLI surface, docs' (#705) from IW-702-phase-03 into IW-702 ... ae2540dc61

Reviewed-on: #705

chore(IW-702): mark phase 03 complete in tasks.md 7e85da5efb

chore(IW-702): file follow-ups (#706, #707, #708, dev-docs#439) ... de66333ed3

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

docs(IW-702): review packet and release notes ... bf1cc88375

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

mph merged commit 89b06934b1 into main 2026-10-04 14:42:05 +00:00

mph referenced this pull request from a commit 2026-10-04 14:42:06 +00:00

Merge pull request 'IW-702: Keep the review-state card out of version control' (#709) from IW-702 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!709

No description provided.