git:20260728.761e80e to git:20260825.b4e66d9

+ description: "Headless follow-up to /speq-plan-pr. Continues a plan on its feat/plan-name branch and runs it end-to-end: implements via /speq-implement, bumps the version, commits and pushes, runs the real test suites, records only if green, then opens/updates the PR and marks it ready. Resumes from the PR Lifecycle checkpoint in the plan's tasks.md if a prior run was cut off mid-flight. Arg: plan name, PR number, or branch name."

+ You are a thin orchestrator layered on top of `speq-implement`, and you run the pipeline end-to-end in one session. Your goal is:

+ - Survive involuntary interruption: write a checkpoint mark after each phase, so a fresh invocation resumes from the correct phase if this session is cut off (usage-limit reset, crash). The checkpoint is crash recovery, never a reason to stop deliberately.

+ The checkpoint schema, writer table, entry-dispatch table, red path, gate/resume messages, and driver contract live in `references/checkpoint-protocol.md`. Read it before step 2. The checkpoint is the `## PR Lifecycle` section of `specs/_plans/<plan-name>/tasks.md`; you write every lifecycle mark except `recorded` (written by `recorder-agent`, verified by you).

+

+ Three phases, run consecutively in this session:

+

+ | Phase | Work | Then |

+ |-------|------|------|

+ | A | blocker check → `/speq-implement` → version bump + build → commit + push evidence | continue to B |

+ | B | real test suites → `/speq-record` (green only) | continue to C |

+ | C | `ship-ready` → verification comment → `pr-ready` mark | final report (terminal) |

+

+ - Delegate implementation to `/speq-implement`, spec merge to `/speq-record`, and every git/`gh` action to `git-agent`; your own work is resolving the branch, gating, bumping the version, writing checkpoint marks, and sequencing those calls.

+ ### 2. Checkpoint Dispatch (orchestrator)

+ Read the checkpoint and enter at the phase the entry-dispatch table in `references/checkpoint-protocol.md` selects. When the table calls for it, pre-create `specs/_plans/<plan-name>/tasks.md` with only the H1 and the `## PR Lifecycle` section, and mark `[x] resolved`. The dispatch decides where execution enters, not where it stops: from the entry phase, run each remaining phase in order in this same session. If dispatch finds marks already set (a prior run was cut off), report which marks are `[x]` and which phase this run resumes into, then continue normally.

+ ### Phase A: Implement + Commit

+ **A1. Blocker check** — read `specs/_plans/<plan-name>/open-questions.md`. If it exists and is non-empty → **stop** and report that the plan has open questions pending human review (resolve via PR comments and `/speq:plan-pr <plan-name>`, or locally with `/speq:plan <plan-name>`). The human-in-the-loop point lives exactly here.

+ **A2. Implement** — invoke `/speq-implement <plan-name>` and let it run to completion — unchanged, reused as-is. It fills `tasks.md` below the lifecycle section, spawns `implementer-agent` / `implementer-expert-agent`, runs `code-reviewer`, and produces `verification-report.md`. When it returns and `verification-report.md` is present, mark `[x] implemented`.

+ **A3. Bump version** — bump the workspace version per the plan's `workspace/version` spec delta if it specifies one; otherwise apply the conventional next version per Conventional Commits semantics (this plan's changes are `feat` → minor bump, unless the plan is purely a `fix` → patch). Run a build to keep the lockfile in sync, redirecting its output to a log: `mkdir -p target && <build-command> > target/speq-build.log 2>&1`. Branch on the exit code; if a report quotes output, quote at most `tail -n 30` of the log — raw build output never lands verbatim in the transcript. Then mark `[x] version-bumped`.

+ **A4. Commit evidence** — commit and push now, so the evidence artifacts reach git history before `/speq-record`'s archive `mv` moves the plan directory out of tracked space, and so the branch survives workspace loss:

+ paths: implementation files, version bump, specs/_plans/<plan-name>/

+ (the whole plan directory — not an itemized subset, so new

+ artifacts ride along automatically)

+ **A5. Continue** — proceed directly into Phase B in this same session.

+ ### Phase B: Test + Record

+ **B1. Run suites** — run the project's real test suites (per `specs/mission.md § Commands` — typically an integration suite and an end-to-end suite), redirecting each suite's output to a log: `mkdir -p target && <suite-command> > target/speq-<suite>.log 2>&1`. Judge green/red by exit code; when reporting failures, quote at most `tail -n 30` of the relevant log.

+ - **All green** → mark `[x] tested-green`, continue with B2.

+ - **Any suite red** → mark `- [!] tested-green — red: <failed suites> (logs: target/speq-<suite>.log)`, report the failures, and **stop** — leave the plan unrecorded.

+ - On red-path re-entry (`[!]` at dispatch), re-run the suites only, per the protocol — never re-enter `/speq-implement` from here.

+ **B2. Record** — invoke `/speq-record <plan-name>`. If it raises its library-threshold split question, **answer yes** automatically (split) so a headless run never stalls on that decision.

+ **B3. Verify the recorded mark** — parse the `Archive:` path from `/speq-record`'s return. Check that `<archive-path>/tasks.md` has `- [x] recorded`; write the mark yourself if it is absent (covers a stale `recorder-agent`).

+ **B4. Continue** — proceed directly into Phase C in this same session.

+

+ ### Phase C: Ship

+

+ **C1. Ship** — one composite call. Phase A already committed the implementation and evidence artifacts, so this commit covers only what `/speq-record` produced — the merge results and the archive's removal of the plan directory:

+

+ ```

+ `ship-ready`'s create-pr step returns the draft PR `speq-plan-pr` opened (or opens one if the plan was only implemented locally), and its ready-pr step marks it ready.

+

+ **C2. Comment** — post the verification summary. Compose the comment body per `speq-writing-guardrails`' PR-facing content rule before calling `comment-pr`:

+

+ ```

+ **C3. Finish** — mark `[x] pr-ready` at `specs/_recorded/*-<plan-name>/tasks.md`, then report the finished PR and leave it for human review. Re-entry after a crash between C1 and C3 is safe: `ship-ready`'s commit no-ops on nothing-to-commit, and its create-pr/ready-pr steps reuse the existing PR.

+ ├── _plans/<plan-name>/ # Active until recorded — committed whole at Phase A, not as an itemized subset

+ │ ├── tasks.md # Pre-created here (§ PR Lifecycle checkpoint); WBS filled by speq-implement

+ │ ├── review/round-N.md # Created by plan-reviewer

+ │ ├── notes/<group-letter>.md # Rotation hand-off notes, created by implementer agents

+ | Target resolution, gating, checkpoint marks, coordination | This skill (pins Sonnet) | Tool-call heavy, reasoning light |

+ | Spec merge, archive, `recorded` mark | `speq-record` (unchanged) | Already the right split — not duplicated here |

+ | Treating `## PR Lifecycle` entries as work items | They are checkpoints; they are unnumbered exactly so task dispatch skips them |

+ | Letting a sub-agent write lifecycle marks | Marks are orchestrator-written, except `recorded` (recorder-agent, per the writer table) |

+ | Proceeding past a non-empty open-questions.md | The human-in-the-loop gate lives at A1 |

+ | Skipping the A4 commit | Evidence artifacts silently never reach git history once `/speq-record`'s archive `mv` moves them out of tracked space |

+ | Re-entering `/speq-implement` on the red path | The red path re-runs suites only; new implementation work is an explicit, separate invocation |