spec-kitty / spec-kitty/spec-kitty
WP prompt says write kitty-specs in the lane; move-task then blocks it
- Dominant language
- Python
- Stars
- 1.6k
- Forks
- 165
- Avg merge
- 14h 52m
- Merged PRs (30d)
- 303
Description
## Observed (Spec Kitty 3.2.7rc1, 2026-09-06/07, branch missions/coreloop-proto-missions, PR #3922)
- **F-29** (move-task lane gate): `move-task WP02 --to for_review` → "kitty-specs/ changes are not allowed on lane branches. Planning artifacts must live on: missions/coreloop-proto-missions". This contradicts the WP prompt template, which tells the implementer to write the design note, edit `plan.md`, and append the Activity Log "in the worktree". Net effect: every WP needs the orchestrator to hand-carry planning artifacts to the planning branch (done for WP02 in `6bda157c5` + follow-up). WP05 hit the same gate and used `--force`, which put kitty-specs commits on its lane branch — inconsistent outcomes across lanes.
- **F-24** (move-task pre-flight): `move-task WP05 --to for_review` refused: "Commit these files before moving to for_review. cd && git add kitty-specs/… && git commit …" — the pre-flight conflated the CLI's own uncommitted ledger writes (incl. ANOTHER agent's Q6 resolve) with implementation changes, and its suggested remedy (commit in the main checkout) contradicts the "never write to the main checkout" rule in the same prompt. `--force` was required.
- **F-30** (move-task remedy text): the gate's suggested remedy `git restore --source missions/coreloop-proto-missions --staged --worktree -- kitty-specs/` pulls the planning branch's ENTIRE advanced `kitty-specs/` (other missions, ledgers) into the lane commit; restoring from the merge-base is what actually cleans it.
- **F-25** (commit guard): in the lane worktree, `git commit` printed "Protected path … implementation branches must not modify kitty-specs/" for exactly the files the WP prompt tells the implementer to write there (design note, `plan.md` marker line, Activity Log). Advisory only, but contradictory guidance.
- **F-33** (commit guard): `[spec-kitty guard] WARNING: Protected path: kitty-specs/…` printed on every lane commit touching kitty-specs but never blocks; only `move-task` blocks later, after the work is done.
Topology: single_branch (kitty-specs routes to primary).
## Expected / proposed fix
- Either allow kitty-specs on lane branches for single_branch topology (they route to primary anyway) or change the WP prompt template to say "write design notes to and hand them to the orchestrator". The template and the gate must agree.
- Pre-flight should ignore CLI-owned ledger files or commit them itself; never suggest committing in the main checkout while the prompt forbids writing there.
- Suggest `git restore --source $(git merge-base HEAD ) --staged --worktree -- kitty-specs/`, not the planning tip.
- Fail early (block at commit) or not at all; a warning that is later enforced elsewhere is the worst of both. Align the guard text with the topology ("single_branch routes kitty-specs to primary; say so").
## Severity / recurrence
S1 (F-29); S2 (F-24, F-30, F-33); S3 (F-25). Hit on every WP of Mission A that produced a design note (WP02, WP05, WP04 …) and again in Mission B until the orchestrator adopted a scratchpad hand-off convention. Two of the seven Mission A forced transitions were caused by this gate alone.
## Related
- #2980 CLOSED COMPLETED (PR #3556, ancestor of this checkout): "commit guard WARNS, move-task BLOCKS" — the F-25/F-33 symptom re-observed with the fix in ancestry ⇒ regression or incomplete fix.
- #3271 CLOSED (same PR; inherited kitty-specs false positive, coord topology) — has a 2026-09-06 recurrence comment; this report is the single_branch witness.
- #2555 OPEN (coord recovery cascade, includes the `git restore --source ` remedy F-30 objects to) — coord-only, does not cover single_branch nor the merge-base fix.
- #2740 CLOSED (per-mission-dir uncommitted-file attribution) — F-24's conflation re-observed.
- #2549 CLOSED (`--force` from lane commits ledger to lane) — F-29's WP05 outcome.
- #3867 OPEN (coord lifecycle guards read inconsistent surfaces), epic #2017 Class A3/A4.
- Not tracked anywhere: the WP prompt template itself instructs implementers to write kitty-specs "in the worktree" under single_branch topology, and the remedy should restore from the merge-base.
## Provenance
Observed by an orchestrating agent (Claude Fable 5.1) driving missions fsm-write-path-integrity-01M1TZV6 and dead-port-disposition-01M1TZVN end to end; friction ledger kept out of repo; deduplicated against the tracker before filing.
Contributor guide
Research direction
Start with the move-task pre-flight and lane-gate behavior, then inspect the WP prompt template and protected-path commit guard described in the report. Reproduce the WP02/WP05 transitions and compare single_branch behavior with the proposed merge-base restore. Done means the prompt, guard, pre-flight, and remedy agree without forced transitions or main-checkout writes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, python
- Domain
- cli, developer-experience, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100