Skip to content

coord item: make claim-to-done delivery and guarded landing a typed state machine #2131

Closed

Description

@EHotwagner

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

  1. Add a typed item lifecycle covering at least Claimed, Implementation, ReviewReady, ReviewActive, Accepted, Landable, MergedAwaitingObligations, Done and terminal park states.
  2. 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.
  3. PR handoff verifies the item branch, canonical closing reference, declared paths and current head before moving the board to In review.
  4. 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.
  5. A guarded land command rechecks live claim generation, exact head, acceptance, checks, mergeability and closing linkage immediately before a single REST merge.
  6. 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.
  7. Completion verifies merge reachability, satisfied obligations, closed issue, Done projection, claim release, zero pending writes and cleanup eligibility before emitting FSGG-DONE.
  8. Every mutating action is idempotent and bound to a freshness token; replay and stale-head cases cannot merge twice or stamp the wrong state.
  9. Worktree/branch cleanup and follow-up-queue routing are returned as explicit terminal actions rather than remembered prose.
  10. 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

Activity

  1. moved this to Backlog in Coordinationon Aug 2, 2026
  2. moved this from Backlog to Blocked in Coordinationon Aug 2, 2026
  3. EHotwagner commented on Aug 2, 2026

    @EHotwagner
    ContributorAuthor

    Mandatory delivery-route decision

    Decision maker: Codex filing agent
    Decision: sdd-required

    Rationale: 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.

  4. moved this from Blocked to Ready in Coordinationon Aug 2, 2026
  5. EHotwagner commented on Aug 3, 2026

    @EHotwagner
    ContributorAuthor
    No description provided.
  6. moved this from Ready to In progress in Coordinationon Aug 3, 2026
  7. moved this from In progress to In review in Coordinationon Aug 3, 2026
  8. EHotwagner commented on Aug 3, 2026

    @EHotwagner
    ContributorAuthor

    Post-merge obligations verified: PR #2174 merged as 45b93a1182f154536c36646b56ff4625c2ab0ad5; Kit 0.35.0 published 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.

  9. moved this from In review to Done in Coordinationon Aug 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions