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

New issue

Closed

opened 2026-10-03 20:42:30 +00:00 by claude · 0 comments

claude commented

2026-10-03 20:42:30 +00:00

Member

Problem

The review-state card (project-management/issues/<id>/review-state.json, or the active slice's card in an effort worktree) is committed on the feature branch. It is workflow status, not a product of the work:

Its truth does not depend on the branch: there is one state per issue at any moment.
No one reads it after the merge.
A run works one issue on one machine, so nothing needs to carry it between machines.

Committing it costs:

Commit noise. In kanon since 2026-06-01, 133 of 643 commits (21%) are only chore(<ID>): update review-state ..., and the file changed 169 times. last_updated and git_sha change on every write, so every write is a diff.
A special case in the merge gate. PhaseMerge.stateOnlyGatedSha exists because a card-only commit lands after a green gate. It merges that head without a verdict of its own (unjudgedHead). With the card outside the tree, the head the gate proved is the head that merges.
Dirty-tree rules. WorkflowStatePaths.partition must treat the card as state-owned so the workflow can auto-commit it.

Proposal

Store the card in the repository's git directory, not in the working tree. Git does not version it, and every process on the machine that knows the worktree can find it.

ReviewStatePath resolves to the new location for issue keys and effort (slice) keys. --path keeps working.
review-state write|update --commit, phase-pr and phase-merge stop committing the card.
The dashboard (ReviewStateService) reads the card from the new location.
stateOnlyGatedSha and the unjudgedHead trade go away, if nothing else needs them.
A one-time move: an existing tracked card is moved out of the tree and removed from git (git rm --cached) the first time a command touches it, or by a documented command.

Keep the content as it is for now. Reducing what the card stores (derivable artifact list, display text) is a separate question.

Decide during analysis

Per-worktree git dir (git rev-parse --git-dir, removed with the worktree) or the common dir (git rev-parse --git-common-dir, survives removal)? The per-worktree dir matches "no one reads it after the merge", but a redo in a new worktree then loses phase_checkpoints.
Key layout inside that dir for an issue card and a slice card (<effort>/<NN>-<slice>).
Does ci-gate or any other command read the card from a commit (e.g. git show <sha>:...) rather than from the working tree? Such a reader breaks.

Consumers outside iw-cli

kanon reads and writes the card by path: the phase-start and phase-pr gate hooks, batch-implement (Preflight, PhaseRecovery, BatchImplementation), autonomous-bootstrap, and the review_state_* blueprint snippets that pass --commit. They need a follow-up in kanon once the core resolves the new location; kanon should reach the card only through iw review-state / ReviewStatePath, never by a literal path.

Type: feature
Filed from: /home/mph/Devel/iw/iw-cli on branch main

## Problem The review-state card (`project-management/issues/<id>/review-state.json`, or the active slice's card in an effort worktree) is committed on the feature branch. It is workflow status, not a product of the work: - Its truth does not depend on the branch: there is one state per issue at any moment. - No one reads it after the merge. - A run works one issue on one machine, so nothing needs to carry it between machines. Committing it costs: - **Commit noise.** In kanon since 2026-06-01, 133 of 643 commits (21%) are only `chore(<ID>): update review-state ...`, and the file changed 169 times. `last_updated` and `git_sha` change on every write, so every write is a diff. - **A special case in the merge gate.** `PhaseMerge.stateOnlyGatedSha` exists because a card-only commit lands after a green gate. It merges that head without a verdict of its own (`unjudgedHead`). With the card outside the tree, the head the gate proved is the head that merges. - **Dirty-tree rules.** `WorkflowStatePaths.partition` must treat the card as state-owned so the workflow can auto-commit it. ## Proposal Store the card in the repository's git directory, not in the working tree. Git does not version it, and every process on the machine that knows the worktree can find it. - `ReviewStatePath` resolves to the new location for issue keys and effort (slice) keys. `--path` keeps working. - `review-state write|update --commit`, `phase-pr` and `phase-merge` stop committing the card. - The dashboard (`ReviewStateService`) reads the card from the new location. - `stateOnlyGatedSha` and the `unjudgedHead` trade go away, if nothing else needs them. - A one-time move: an existing tracked card is moved out of the tree and removed from git (`git rm --cached`) the first time a command touches it, or by a documented command. Keep the content as it is for now. Reducing what the card stores (derivable artifact list, display text) is a separate question. ## Decide during analysis 1. Per-worktree git dir (`git rev-parse --git-dir`, removed with the worktree) or the common dir (`git rev-parse --git-common-dir`, survives removal)? The per-worktree dir matches "no one reads it after the merge", but a redo in a new worktree then loses `phase_checkpoints`. 2. Key layout inside that dir for an issue card and a slice card (`<effort>/<NN>-<slice>`). 3. Does `ci-gate` or any other command read the card from a commit (e.g. `git show <sha>:...`) rather than from the working tree? Such a reader breaks. ## Consumers outside iw-cli kanon reads and writes the card by path: the `phase-start` and `phase-pr` gate hooks, `batch-implement` (`Preflight`, `PhaseRecovery`, `BatchImplementation`), `autonomous-bootstrap`, and the `review_state_*` blueprint snippets that pass `--commit`. They need a follow-up in kanon once the core resolves the new location; kanon should reach the card only through `iw review-state` / `ReviewStatePath`, never by a literal path. --- **Type:** feature **Filed from:** `/home/mph/Devel/iw/iw-cli` on branch `main`

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

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

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