Repository navigation
coord item: make claim-to-done delivery and guarded landing a typed state machine #2131
Description
Parent: #2130
Observed behavior
pnext-item is documented as a worker state machine, but its executable boundary stops at individual verbs. The worker and host still manually correlate the claim, worktree, item branch, PR number, closing reference, declared paths, critic identity, exact reviewed SHA, review-round chain, host acceptance, landability, REST merge, post-merge obligations, done stamp and cleanup. The protocol occupies the main skill plus a 1,652-line deep-detail reference, and recent live runs required host repair when a critic marker was malformed and when a worker returned before its claim reached a terminal state.
Root cause
The engine owns isolated decisions (take, verify-paths, landable, done) but not the transitions between them. There is no typed aggregate saying what phase the live item is in, which evidence is current, or the one legal next action.
Acceptance
- Add a typed item lifecycle covering at least
Claimed,Implementation,ReviewReady,ReviewActive,Accepted,Landable,MergedAwaitingObligations,Doneand terminal park states. - An inspect/advance surface binds item ref, live claim generation, worker/executor identity, branch/worktree, PR, current head SHA and board state, returning exactly one next action or a fail-closed no-verdict.
- PR handoff verifies the item branch, canonical closing reference, declared paths and current head before moving the board to
In review. - Review acceptance consumes the typed review-chain result delivered by coord driver: make wave rollover and housekeeping a deterministic state machine #2127; prose or a stale/mismatched SHA cannot advance.
- A guarded land command rechecks live claim generation, exact head, acceptance, checks, mergeability and closing linkage immediately before a single REST merge.
- Post-merge obligations are declared before landing and become typed pending obligations. The issue/board remains visibly nonterminal and the claim stays live until every required release, publication, registry, dispatch or deployment receipt verifies.
- Completion verifies merge reachability, satisfied obligations, closed issue, Done projection, claim release, zero pending writes and cleanup eligibility before emitting
FSGG-DONE. - Every mutating action is idempotent and bound to a freshness token; replay and stale-head cases cannot merge twice or stamp the wrong state.
- Worktree/branch cleanup and follow-up-queue routing are returned as explicit terminal actions rather than remembered prose.
- End-to-end tests cover a clean no-obligation item, a package release item, changed head after acceptance, missing closing linkage, stale claim generation, merge success followed by pending obligations, and cleanup refusal before Done.
Sequencing
This slice consumes the reusable driver/review-chain types from #2127 and should remain blocked until that contract lands.
Class: hardening
Paths: src/FS.GG.Coord.Cli src/FS.GG.Coord.Core src/FS.GG.Coord.GitHub tests/FS.GG.Coord.Cli.Tests tests/FS.GG.Coord.Core.Tests tests/FS.GG.Coord.GitHub.Tests .agents/skills/pnext-item .claude/skills/pnext-item work/2131-claim-to-done-lifecycle readiness/2131-claim-to-done-lifecycle src/FS.GG.Kit/FS.GG.Kit.csproj registry/driver-skill-manifest.json registry/coordination-kit-skill-manifest.json registry/repos.lock tests/coord-engine/writes.sh tests/coord-engine-e2e/writes.sh scripts/fsgg-coord-guards.sh
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsDone
Activity
EHotwagner commentedon Aug 2, 2026
Mandatory delivery-route decision
Decision maker: Codex filing agent
Decision:
sdd-requiredRationale: The item defines a multi-phase claim/review/merge/obligation state machine, changes CLI and coordination contracts, and must preserve recovery and idempotency across external GitHub effects.
Until #2137 provides the typed receipt, this comment is the durable manual decision. A worker must run the full SDD lifecycle inside the claim-to-done envelope and bind its work/spec evidence to this item; this is not an advisory. Material scope changes require a new route decision.
EHotwagner commentedon Aug 3, 2026
EHotwagner commentedon Aug 3, 2026
Post-merge obligations verified: PR #2174 merged as
45b93a1182f154536c36646b56ff4625c2ab0ad5; Kit0.35.0published byte-identically to both feeds in release run 30817923084; all 7 receivers reached (0 undetermined, 0 findings); public nuget.org index serves 0.35.0; coherence rerun 30817837269 passed. The separate Coord Engine release window is durably owned by existing.github#2113.release(kit): FS.GG.Kit 0.36.0 -> 0.37.0 for the gate-inversion contr…
coord: a closed, UNSTAMPED item is still in flight (#2225) (#2235)