@jaybeeuu/agent-cortex 1.41.1 → 1.43.0

package/skills/planning/write-a-ticket/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: write-a-ticket
-description: Write a well-structured ticket for an external issue tracker (e.g. Jira) that an engineer can act on without follow-up questions. Use when asked to "write a ticket", "file this in Jira", or "create a work item" — not for creating implementation tasks in a ralph/bd loop.
+description: Write a clear, reviewable ticket for an external issue tracker (Jira, Linear, GitLab, GitHub Issues) that an engineer can act on without follow-up questions. Use when asked to "write a ticket", "file this in Jira", or "create a work item" — not for beads in a ralph/bd loop.
 argument-hint: "The work to ticket: goal, epic/initiative, constraints, or paste a draft"
 ---
 
@@ -9,104 +9,122 @@ argument-hint: "The work to ticket: goal, epic/initiative, constraints, or paste
 ## When to use
 
 - Asked to "write a ticket", "file this in Jira", or "create a work item".
-- Drafting an actionable work item for a human engineering audience in an external issue tracker (Jira, Linear, GitHub Issues).
-- Checking an existing ticket for clarity before it goes to the team.
+- Drafting an actionable work item for a human engineering audience in an external tracker.
+- Reviewing an existing ticket for clarity before it goes to the team.
 
 ## When NOT to use
 
-- Creating implementation tasks for the ralph/bd loop — those are beads executed by agents, not tickets read by engineers.
-- Writing a requirements document for a feature that is not yet actionable — run `write-a-prd` first and link the PRD from the ticket.
+- Breaking a whole PRD/RFC/spec into many tickets — use `spec-to-tickets`, which calls this skill per ticket.
+- Creating implementation tasks for the ralph/bd loop — those are beads executed by agents; use `prd-to-tasks` or `create-task`.
+- Writing a requirements document for work that is not yet actionable — run `write-a-prd` first.
 
 ## Workflow
 
-1. **Gather context.** Confirm the goal of the work, the epic/RFC/initiative it belongs to (if any), known constraints or decisions, and relevant code locations, schemas, or prior art. Outcome: you can state the ticket's purpose in one sentence. If you cannot, ask before writing.
+1. **Gather context.** Confirm the goal, the parent ticket or epic, the spec it follows, the decisions already made, and the entry point in the code. Outcome: you can state what this ticket does in one sentence. If you cannot, ask before writing.
 
-2. **Draft the ticket.** Work through the template below. Every section has a purpose — write it only if it earns its place, and never omit a required section without recording why.
+2. **Settle open questions.** Resolve every question with the human while drafting. When a question cannot be resolved now, split a blocking spike ticket and depend on it, or ask the human to find the answer. A question may stay in the body only when the human explicitly agrees to leave it open — record it under `Open questions` with the owner of the answer. Ship no question the human has not agreed to.
+
+3. **Draft the body** from the template below, then check it against the format rules and the verification checklist.
+
+4. **Hand over the draft.** Present the body for review and get the human's agreement before it is created or filed. The draft is the review artefact — nothing reaches the tracker unseen.
 
 ```markdown
 ## Context
 
-<1–3 sentences: why this work exists, and which epic/RFC/ADR it belongs to. Link to it — never copy-paste its content.>
+<1–5 sentences of pointers: parent ticket or epic, where the approach lives
+(RFC/ADR section), the decisions already made, and what this depends on.
+Reference these — do not explain them.>
 
 ## Description
 
-<What to build or change. Describe the outcome, not the implementation steps, and state scope explicitly — what is in and what is out.>
+<2–4 sentences. What this ticket does and the behaviour it produces — the goal,
+stated as the lead-in to the scope bullets. Leave detail to the sections below.>
 
-## Acceptance criteria
+## In scope
 
-- [ ] <Specific, independently verifiable criterion — e.g. "given X, the API returns Y">
-- [ ] <...>
+- <a distinct deliverable this ticket owns>
+- <...>
 
-## Technical notes
+## Out of scope
 
-<Links to relevant code, agreed schemas, architectural decisions, or upstream constraints. A pointer, not a design document — decisions that need more space belong in an ADR or RFC.>
+- <adjacent work explicitly not included — name the ticket that owns it where known>
 
-## Testing strategy
+## Acceptance criteria
 
-<Optional. Only when testing needs are non-obvious or a level was agreed — unit, integration, contract, E2E. Omit when team defaults apply.>
+- [ ] <independently verifiable check>
+- [ ] <...>
 
-## Monitoring strategy
+## Testing approach
 
-<Optional. Only when the change adds metrics, alerts, log events, dashboards, or a phased rollout. Omit when there is no meaningful observability footprint.>
+<Optional. Which specs, what they assert, and any setup gotcha. Omit when team
+defaults apply.>
 
-## Notes
+## Technical notes
 
-<Optional. Genuinely useful details with no other home. If you reach for this often, restructure the ticket.>
+- **Entry point:** `path/to/file.ts:42` (`symbol`, `symbol`)
+- <a decisive fact: a signature that changes, a library or convention to follow,
+  a field injected elsewhere>
+
+## Open questions
+
+<Optional, and only when the human has explicitly agreed to leave a question
+open. One bullet per question, each naming who owns the answer. Omit this
+section when there are none.>
 ```
 
-3. **Review against the checklist.** Work through the verification checklist below before finalising.
+### Format rules
+
+- **Link, don't copy.** Reference the spec by link or section; never paraphrase it. A reader who needs the rationale opens the source.
+- **Point at the entry, not the inventory.** Technical notes lead with the entry point — 1–3 links to where the work begins — plus only the facts that change how it is done. A full list of touched files means you have written the code in prose.
+- **Scope is the contract.** In scope and Out of scope say what the ticket owns; Technical notes only show where to begin.
+- **Every bullet is a distinct deliverable or check.** Merge any two that restate each other, and cut any that add neither.
+- **Bullets over paragraphs, and no tables in the body** — trackers render tables inconsistently and they are slow to scan.
+- **Budgets are guidance, not limits.** Context ≤ 3 sentences; Description ≤ 4 sentences; In scope ≤ 8 bullets; Out of scope ≤ 6 bullets; Acceptance criteria ≤ 12 items; Technical notes ≤ 6 bullets. Extend a section when the work genuinely needs it — a larger scope, or detail that makes the goal clearer — but treat that as the exception, not the rule. Aim for the smallest body that is still complete.
 
 ## Red Flags
 
-- Writing implementation steps into the description — describe the outcome, not the how.
+- Writing the code in prose — listing every file touched, or stepping through the edits.
+- A Description that explains the RFC or the deliberation instead of stating what this ticket does.
 - Acceptance criteria that cannot be verified: "works correctly", "is tested".
-- Copy-pasting context instead of linking to the epic, RFC, or ADR.
-- Padding sections with filler to look complete — a short, accurate ticket beats a padded one.
-- Omitting a required section without recording why.
+- Padding a section to reach a budget, or exceeding one without the work to justify it.
+- Copy-pasting spec content instead of linking to it.
+- Leaving a question, `TBD`, or "we need to decide" in the body when the human has not agreed to it — an unagreed open question is a blocked implementer.
 
 ## Common Rationalizations
 
-| Rationalization | Rebuttal |
-|---|---|
-| "The engineer will figure it out" | Skilled engineers can — but questions are a blocked ticket. The ticket must stand alone. |
-| "More detail is safer" | Detail only helps if it informs the implementer. Every extra sentence is noise to skim. |
-| "We will verify acceptance criteria in review" | Unverifiable criteria cannot be checked. Write given/outcome pairs instead. |
-| "We will discuss the details in standup" | The ticket is the record. If it cannot stand alone, the discussion is lost. |
+| Rationalization                              | Rebuttal                                                                                                                          |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| "The engineer will figure it out"            | Skilled engineers can — but questions are a blocked ticket. The ticket must stand alone.                                          |
+| "More detail is safer"                       | Detail helps only if it informs the implementer. Every extra sentence is noise to skim.                                           |
+| "The reviewer should see every file touched" | The reviewer needs the scope and somewhere to start, not an inventory. The implementer finds the rest.                            |
+| "I'll flag the open question in the ticket"  | Only if the human agrees to leave it open. Otherwise resolve it or split a spike — an unagreed question is a blocked implementer. |
 
 ## Philosophy / rationale
 
-- **Write for clarity, not coverage.** A ticket is not a specification. One well-chosen sentence beats three that say the same thing.
-- **Describe the outcome, not the implementation.** The ticket owns the what and why; the implementer owns the how.
-- **A ticket must stand alone.** Link, don't copy — readers who need the full rationale should open the linked document, not a paraphrase.
+- **Write for clarity, not coverage.** Every line carries a fact; a long ticket of facts beats a short one of filler. Aim for the smallest body that is still complete, and extend a section only when the work demands it.
+- **Scope is the contract.** In scope and Out of scope make the boundary reviewable at a glance.
+- **Describe the behaviour, not the implementation.** The ticket owns the what and why; the implementer owns the how.
+- **A ticket must stand alone.** Link, don't copy — readers who need the full rationale open the linked document, not a paraphrase.
 
 ## Cross-skill references
 
-| When you need… | Use this skill |
-|---|---|
-| Tone, structure, and concision for human-facing writing | `style-comms` |
-| A requirements document that precedes the ticket | `write-a-prd` |
-
-## Examples
-
-### Vague vs verifiable acceptance criteria
-
-| Instead of… | Write… |
-|---|---|
-| "The export feature works" | "Given exports enabled, selecting 'Export CSV' downloads `<account>-export-<date>.csv`" |
-| "Adds tests for the new endpoint" | "POST /v1/orders returns 201 with the created order for valid input and 422 with field errors for schema violations" |
-
-### Context that links vs context that copies
+| When you need…                                          | Use this skill    |
+| ------------------------------------------------------- | ----------------- |
+| To break a spec into a map of tickets                   | `spec-to-tickets` |
+| Tone, structure, and concision for human-facing writing | `style-comms`     |
+| A requirements document that precedes the ticket        | `write-a-prd`     |
 
-| Instead of… | Write… |
-|---|---|
-| Four paragraphs paraphrasing the ADR | "Follows ADR-014 (token refresh). This ticket adds only the retry path — see ADR link." |
+See [EXAMPLES.md](./EXAMPLES.md) for worked before/after rewrites.
 
 ## Verification checklist
 
-- [ ] Context explains why the work exists; the reader needs no other tab open
-- [ ] Description states the outcome, not implementation steps, and defines scope
-- [ ] Acceptance criteria are independently verifiable — no "works correctly" or "is tested"
-- [ ] Technical notes link to code or schemas without prescribing the solution
-- [ ] Testing/Monitoring/Notes present only when they add non-obvious information
-- [ ] Every sentence passes the "does this add information?" test
-- [ ] A skilled engineer can start immediately with zero follow-up questions
+- [ ] Context points at the parent, the approach, and the dependencies without explaining them
+- [ ] Description states the goal and behaviour and leads into the scope bullets
+- [ ] In scope and Out of scope are explicit, with every bullet a distinct deliverable
+- [ ] Acceptance criteria are independently verifiable and none restate another
+- [ ] Technical notes lead with the entry point and give only decisive facts
+- [ ] Testing approach and Technical notes appear only when they add non-obvious information
+- [ ] Every section is within its guidance budget, or the extra is justified by the work
+- [ ] Any open question is one the human explicitly agreed to, listed under `Open questions` with an owner
+- [ ] A skilled engineer can start immediately with zero follow-up questions
+- [ ] The human reviewed the drafted body before it was created

package/skills/productivity/bd-tool/SKILL.md

@@ -43,13 +43,13 @@ For new tasks with pipeline expansion:
 
 ```bash
 # use the create-task skill, or manually:
-bd create "<title>" -d "<description>" -p <0-3>
+bd create "<title>" -d "<description>" -p <0-3> --validate
 ```
 
 For parent-child relationships (create with `--parent`):
 
 ```bash
-bd create "<title>" --parent <parent-id>
+bd create "<title>" --parent <parent-id> --validate
 ```
 
 For blocking dependencies between beads:
@@ -58,6 +58,31 @@ For blocking dependencies between beads:
 bd dep add <id> <blocked-by-id> --type blocks
 ```
 
+### Required sections
+
+Create substantive beads with `--validate` so a section-less bead is rejected before it is
+recorded. `bd create --validate` requires these sections per type (matching is case-insensitive);
+`bd lint` checks the same contract on existing beads and exits non-zero when any are missing:
+
+| Type | Required sections |
+|---|---|
+| `task`, `feature` | `## Acceptance Criteria` |
+| `epic` | `## Success Criteria` |
+| `bug` | `## Steps to Reproduce`, `## Acceptance Criteria` |
+| `chore` | none |
+
+Plan what you write: the type's required sections are the target of the planning interview
+(`write-a-prd`, `request-refactor-plan`, `plan`, `grill-me`, …). Do not invent section content —
+surface an assumption and confirm it with the human. Chore beads carry no required sections; their
+description should reference the parent/requirements bead rather than restating criteria.
+
+Review after creating — lint the beads you just made and fix any flagged ones:
+
+```bash
+bd lint <new-id>...      # scoped to your beads; exits non-zero on missing sections
+bd lint                  # the whole open backlog (may flag pre-existing beads)
+```
+
 ## Completing work
 
 ```bash

package/skills/productivity/grill-me/SKILL.md

@@ -8,3 +8,14 @@ Interview me relentlessly about every aspect of this plan until we reach a share
 Ask the questions one at a time.
 
 If a question can be answered by exploring the codebase, explore the codebase instead.
+
+## Completion: the bead's required sections
+
+When this interview feeds a bead, the bead type's required sections are the target — their
+contract is in the `bd-tool` skill's "Required sections" table (task/feature → `## Acceptance
+Criteria`; epic → `## Success Criteria`; bug → Steps to Reproduce + Acceptance Criteria). The
+interview is complete only when there is enough agreed detail to fill every required section.
+
+Never invent section content. If you must infer an answer, state it as an assumption and get the
+human to confirm it before it becomes bead content. Leave unresolved branches open — an open
+question is better than a fabricated answer.

package/skills/workflow/git-workflow/SKILL.md

@@ -66,7 +66,41 @@ git pull
 
 This avoids avoidable merge conflicts.
 
-### 5. Worktree lifecycle
+### 5. Bring a behind branch up to date — merge, don't rebase
+
+When the base branch moves and the PR reports `BEHIND` or `CONFLICTING`, update
+the branch before anything else:
+
+```bash
+git fetch origin
+git merge origin/main
+```
+
+**Never rebase a branch that contains a merge commit.** `git rebase` drops merge
+commits and the patches they carry, so rebasing a branch that already merged the
+base silently reverts what that merge resolved — the conflict resolutions, and
+any fix from the base the merge brought in. The result usually looks like a
+regression in your own change. `--rebase-merges` preserves the structure, but
+it re-opens the same conflicts; only worth it when the branch's history is
+itself the deliverable.
+
+Rebase only a **linear branch that has not been reviewed yet**. Rewriting
+commits under review discards the review context and invalidates approvals, and
+it requires `git push --force-with-lease` — never `--force`, which overwrites
+work you have not seen.
+
+Which one you owe the repository depends on its landing method, not on taste:
+
+- **Squash merge**: the branch is collapsed on landing, so its shape never
+  reaches the base branch. Merge the base in and move on — rebasing here is
+  cosmetic, and the risky kind of cosmetic.
+- **Rebase-and-merge**: a linear branch is mandatory, so rebase *before* the
+  first review. Once a merge has landed on the branch, that option is gone.
+
+After any update, re-run the checks. A merge that resolved conflicts by hand is
+not verified by the base branch's green CI.
+
+### 6. Worktree lifecycle
 
 After the PR is merged or closed, clean up the worktree:
 

package/skills/workflow/plan/SKILL.md

@@ -47,6 +47,10 @@ Establish what needs to be built through investigation and collaborative design.
    - Technical constraints and trade-offs
    - How each change will be verified
 
+The epic's required sections — `## Success Criteria` for the PRD epic — are the interview's target:
+it is complete only when every required section can be filled from agreed answers. Never invent
+section content; surface assumptions and confirm them with the user.
+
 4. Sketch the major modules that will be built or modified. Look for opportunities to extract deep modules — ones that encapsulate significant behaviour behind a simple, testable interface.
 
 5. Draft a PRD using the template from `write-a-prd`. Include:
@@ -60,8 +64,9 @@ Establish what needs to be built through investigation and collaborative design.
 7. Create an epic bead from the approved PRD:
    ```bash
    bd create "<Feature Title> — PRD" --type epic \
-     --description "<rendered PRD as markdown>" --priority p2
+     --description "<rendered PRD as markdown>" --priority p2 --validate
    bd tag <epic-id> workflow:plan
+   bd lint <epic-id>
    ```
 
 #### Phase 1 gate
@@ -70,7 +75,7 @@ Establish what needs to be built through investigation and collaborative design.
 - [ ] Design decisions resolved through interview
 - [ ] Modules sketched and reviewed with the user
 - [ ] PRD drafted and approved by the user
-- [ ] Epic bead created from approved PRD
+- [ ] Epic bead created from approved PRD and lints clean (`bd lint <epic-id>`)
 
 ### Phase 2 — Break into tasks
 
@@ -82,13 +87,14 @@ Take the approved PRD and produce a set of epics and tasks using tracer-bullet v
    - **Title**: short descriptive name
    - **User stories covered**: which PRD stories this phase addresses
    - **What to build**: end-to-end behaviour description
-   - **Acceptance criteria**: verifiable outcomes
+   - **Success criteria**: verifiable outcomes — the epic's required `## Success Criteria`
 
 10. If the work is small enough for a single epic (one phase, a few tasks), skip epics and proceed directly to Phase 3. A single epic with a few tasks dispatches through ralph more efficiently than creating unnecessary epic hierarchy. If the work has multiple distinct phases, create epics:
     ```bash
     bd create "<Phase Title>" --type epic \
-      --description "<epic body with scope, criteria, dependencies>" --priority <same as parent>
+      --description "<epic body with scope, success criteria, dependencies>" --priority <same as parent> --validate
     bd tag <epic-id> workflow:plan
+    bd lint <epic-id>
     bd dep add <epic-id> <parent-epic-id> --type parent-child
     ```
 
@@ -146,8 +152,13 @@ Deliver a handoff bead and instructions for running ralph.
     - **Multiple independent epics**: create a parent meta-epic that groups them:
       ```bash
       bd create "<Feature Title> — Implementation" --type epic \
-        --description "Meta-epic grouping all phases for execution. See child epics for detail." \
-        --priority <same>
+        --description "Meta-epic grouping all phases for execution. See child epics for detail.
+
+## Success Criteria
+
+- [ ] All child epics complete and the feature verified end-to-end." \
+        --priority <same> --validate
+      bd lint <meta-epic>
       bd dep add <epic-1> <meta-epic> --type parent-child
       bd dep add <epic-2> <meta-epic> --type parent-child
       ```
@@ -187,13 +198,14 @@ Deliver a handoff bead and instructions for running ralph.
 #### Phase 4 gate
 
 - [ ] Handoff bead identified and tagged `workflow:ralph`
+- [ ] Every handoff-path bead lints clean (`bd lint`)
 - [ ] Bead state pushed with `bd dolt push`
 - [ ] Handoff summary presented with the exact instruction to give an agent
 
 ## Phase-gate checklist
 
-- [ ] Phase 1: PRD drafted and approved, epic bead created
-- [ ] Phase 2: Task breakdown approved, epics created (if needed)
+- [ ] Phase 1: PRD drafted and approved, epic bead created and validated
+- [ ] Phase 2: Task breakdown approved, epics created (if needed) and validated
 - [ ] Phase 3: All tasks created, classified, expanded, tree presented
 - [ ] Phase 4: Handoff bead prepared, state pushed, summary delivered
 

package/skills/workflow/ralph/REFERENCE.md

@@ -19,7 +19,23 @@ Detailed procedures for the ralph orchestration workflow. See [SKILL.md](./SKILL
    - For `verify`, `review`, `document` stages: `SUMMARY` and `FILES_CHANGED` from the preceding stage's report
    - Log file path `.agent-cortex/ralph/ralph-<parent-id>.log` — logs are keyed by **parent** bead ID, so every stage chore of a feature appends to the same file
 7. **Call the {{TOOL:task}} tool** with the filled prompt as `prompt` and the worktree path as `cwd`. Store the returned agentId — you need it for step 8 and for log polling.
-8. **Map** the agent ID to the bead ID in memory for lookup on completion.
+
+   If this session has no subagent tool, **stop and say so**. Do not substitute a backgrounded CLI run (`pi -p … &`): that launch has no completion signal, so a finished worker and a killed one look identical, which is how stages came to be reported complete over uncommitted trees. Record the bead for the shutdown summary and tell the human the session needs restarting with the subagent extension loaded.
+8. **Record the base commit** before the worker starts — you verify delivery against it (_Verified Completion_ below):
+   ```bash
+   git -C .agent-cortex/worktrees/<parent-id> rev-parse HEAD
+   ```
+9. **Map** the agent ID to the bead ID in memory for lookup on completion.
+
+### Verified Completion
+
+A worker's `---REPORT---` is a claim about the worktree, not evidence of it. Verify the delivery before advancing the parent:
+
+```bash
+node scripts/lib/verify-worker-tree.mjs --worktree .agent-cortex/worktrees/<parent-id> --base <base>
+```
+
+Exit code 0 means a clean tree with at least one commit ahead of the recorded base. A non-zero exit reports `worktree is dirty` or `no commit ahead of base`, and the stage did **not** deliver whatever its `OUTCOME` line says. Re-dispatch the same chore, or record the failure for the fix chain — never advance the parent, close the chore, or open a feature PR over uncommitted work.
 
 ---
 
@@ -79,7 +95,9 @@ When a verify or review stage fails:
    ```bash
    fix_id=$(bd create "[<parent-id>] Fix (round <N>)" --type chore \
      --priority <same as parent> \
-     --description "<CHANGES_REQUESTED list or VERIFY_FAILURES list from the triggering REPORT>" -q)
+     --description "Requirements: see <parent-id> acceptance criteria (`bd show <parent-id>`).
+
+<CHANGES_REQUESTED list or VERIFY_FAILURES list from the triggering REPORT>" -q)
    bd tag $fix_id stage:fix
    bd dep add $fix_id <parent-id> --type parent-child   # fix-chore is child of parent
    ```

package/skills/workflow/ralph/SKILL.md

@@ -49,7 +49,7 @@ On each completion notification (background agent finished, or the poll timer fi
 
 1. Poll that parent's log for new lines — `tail -n +<nextLine> .agent-cortex/ralph/ralph-<parent-id>.log` (logs are keyed by parent bead ID, so every stage of a feature shares one file) — and post only new key events (stage transitions, test/lint results), never empty updates.
 2. Read the completed agent's output with {{TOOL:read_agent}} and parse its `---REPORT---` block for `BEAD_ID`, `STAGE_COMPLETED`, and the outcome.
-3. Close the chore bead: `bd close <bead-id>`.
+3. **Verify the delivery, then close the chore bead.** Run `node scripts/lib/verify-worker-tree.mjs --worktree .agent-cortex/worktrees/<parent-id> --base <base>` (REFERENCE.md, _Verified Completion_) and close only when it exits 0: `bd close <bead-id>`.
 4. Advance the parent per the dispatch table:
 
    | Stage completed | Condition | Next action |
@@ -82,6 +82,8 @@ On each completion notification (background agent finished, or the poll timer fi
 
 - Running as a background or delegated subagent instead of the interactive foreground agent.
 - Spawning a stage runner via {{TOOL:bash}} or running a stage inline instead of {{TOOL:task}}.
+- Substituting a backgrounded CLI run for a missing subagent tool — stop and report instead; that launch has no completion signal.
+- Advancing a parent on a worker's `OUTCOME: SUCCESS` without verifying the worktree — the report is a claim, not evidence.
 - Editing bead files directly instead of using `bd` commands.
 - Auto-merging a PR, or continuing past a feature/epic gate before a human merge.
 
@@ -114,6 +116,7 @@ On each completion notification (background agent finished, or the poll timer fi
 
 - [ ] Init ran once with observable results: `state.json` exists, `bd ready` was parsed, and the first chore beads are claimed.
 - [ ] Every stage runner was spawned with {{TOOL:task}} from the parent's feature worktree, with the `---REPORT---` instruction in its prompt.
+- [ ] Every stage delivery was confirmed with `scripts/lib/verify-worker-tree.mjs` before the parent advanced, and no stage was dispatched from a session with no subagent tool.
 - [ ] In-flight count never exceeded 5, and fix loops respect `maxFixRounds` from `pipeline.json`.
 - [ ] Feature and epic PRs were pushed and reported immediately at their gates, and nothing was auto-merged.
 - [ ] `bd dolt push` and a final `progress.md` regeneration ran before HITL Pause/Shutdown, and the chat received no empty poll updates.

package/skills/workflow/run-pipeline-stage/SKILL.md

@@ -36,10 +36,11 @@ workspace="/absolute/path/to/worktree"
 pnpm --prefix skills/workflow/run-pipeline-stage/scripts exec tsx generate-progress.ts --workspace "$workspace" > "$workspace/.agent-cortex/ralph/progress.md"
 ```
 
-7. Dispatch one subagent per stage with the composed prompt — spawn it with {{TOOL:task}} and end the prompt with the REPORT contract below.
-8. Route the REPORT through the Dispatch Rules: advance to the next stage, create a feedback bead, or close the parent.
+7. Dispatch one subagent per stage with the composed prompt — spawn it with {{TOOL:task}} and end the prompt with the REPORT contract below. A session with no subagent tool cannot dispatch: stop and say so rather than substituting a backgrounded CLI run, which has no completion signal.
+8. Verify the delivery against the worktree — `node scripts/lib/verify-worker-tree.mjs --worktree <abs-worktree> --base <base>` exits 0 only for a clean tree with a commit ahead of base. A worker whose REPORT claims `OUTCOME: SUCCESS` over a dirty tree has not delivered; re-dispatch it instead of advancing.
+9. Route the REPORT through the Dispatch Rules: advance to the next stage, create a feedback bead, or close the parent.
 
-Each step leaves observable state — a claimed bead, a `stage:` tag, a regenerated progress doc, and a REPORT that drives the next action.
+Each step leaves observable state — a claimed bead, a `stage:` tag, a regenerated progress doc, a verified commit, and a REPORT that drives the next action.
 
 ## Dispatch Rules
 
@@ -61,12 +62,17 @@ On stage failure, create a chore bead whose description carries the feedback so
 
 ```bash
 new_id=$(bd create "[<parent-id>] <title>" --type chore \
-  --description "<feedback content from REPORT>" --priority <parent-priority> -q)
+  --description "Requirements: see <parent-id> acceptance criteria (`bd show <parent-id>`).
+
+<feedback content from REPORT>" --priority <parent-priority> -q)
 bd tag $new_id stage:<next-stage>
 bd tag $new_id workflow:ralph
 bd dep add $new_id <parent-id> --type parent-child
 ```
 
+Chore beads carry no required sections, so the feedback description must point at the
+parent/requirements bead (`<parent-id>`) rather than restating its acceptance criteria.
+
 | Triggering outcome | Suggested title | Next stage tag | Description content |
 |---|---|---|---|
 | `OUTCOME: BLOCKED` from verify | `Fix: verify failures` | `stage:code` | Full BLOCKING_ISSUES list |
@@ -109,13 +115,18 @@ Every subagent prompt must end with the REPORT instruction:
 > STAGE_COMPLETED: <code|verify|review|document>
 > SUMMARY: <2-3 sentence summary of what was done>
 > FILES_CHANGED: <comma-separated list, or "none">
+> COMMIT: <sha of the stage commit, or "none">
+> PUSHED: <yes|no>
+> PR: <feature PR url, or "none">
 > OUTCOME: <SUCCESS|BLOCKED>
 > BLOCKING_ISSUES:                              ← only if OUTCOME is BLOCKED
 > - <specific blocking issue>
 > ---
 > ```
 
-Subagents report facts — do not ask them to suggest or predict the next step.
+Subagents report facts — do not ask them to suggest or predict the next step. A REPORT claiming
+`OUTCOME: SUCCESS` with `PUSHED: no`, or a `COMMIT` that is not on the branch, records a failed
+stage: the commit is the evidence, the report is the claim.
 
 ## Red Flags
 
@@ -123,6 +134,7 @@ Subagents report facts — do not ask them to suggest or predict the next step.
 - Composing a subagent prompt without the REPORT contract — the output cannot be routed.
 - Creating a feedback bead and then dispatching anyway — bypasses the fix-round accounting and parent-child dependency graph.
 - Skipping the playbook "because the stage is simple" — playbooks carry the per-stage discipline the pipeline relies on.
+- Advancing on `OUTCOME: SUCCESS` without verifying the worktree — the commit is the evidence, the report is the claim.
 - Leaving bead notes to the end of the stage — a session that dies mid-stage then loses the whole trail.
 
 ## Common Rationalizations

package/skills/workflow/run-pipeline-stage/playbooks/code.md

@@ -11,7 +11,9 @@
 
 ## Stage Outcome
 
+- Commit and push the stage's work before reporting (see the stage-runner prompt, _Deliver before reporting_).
 - Set `OUTCOME: SUCCESS` when implementation passes all tests and meets requirements.
 - Set `OUTCOME: BLOCKED` if tests fail or requirements cannot be met.
 - If blocked, list issues under `BLOCKING_ISSUES`.
 - `FILES_CHANGED` lists all modified source/test files.
+- Report `COMMIT`, `PUSHED`, and `PR` (`PR: none` outside the document stage).

package/skills/workflow/run-pipeline-stage/playbooks/document.md

@@ -12,7 +12,10 @@
 
 ## Stage Outcome
 
+- Commit and push the docs before reporting (see the stage-runner prompt, _Deliver before reporting_).
+- Open or update the feature PR (`gh pr create --base <base> --head <branch>` when none is open yet).
 - Set `OUTCOME: SUCCESS` when docs are updated as needed (or none needed).
 - Set `OUTCOME: BLOCKED` if unable to update or content guidance is unclear.
 - If blocked, list issues under `BLOCKING_ISSUES`.
 - `FILES_CHANGED` lists docs touched, or `none` if no doc change is needed.
+- Report `COMMIT`, `PUSHED`, and the feature `PR` URL.

package/skills/workflow/run-pipeline-stage/playbooks/fix.md

@@ -11,7 +11,9 @@
 
 ## Stage Outcome
 
+- Commit and push the fix before reporting (see the stage-runner prompt, _Deliver before reporting_).
 - Set `OUTCOME: SUCCESS` when requested changes are successfully applied.
 - Set `OUTCOME: BLOCKED` if unable to apply changes or guidance is unclear.
 - If blocked, list issues under `BLOCKING_ISSUES`.
 - `FILES_CHANGED` lists files updated to address requested changes.
+- Report `COMMIT`, `PUSHED`, and `PR` (`PR: none`).

package/skills/workflow/run-pipeline-stage/prompts/stage-runner.md

@@ -26,6 +26,17 @@ Use `--append-notes` — plain `--notes` overwrites the trail. Record start, mil
 (with rejected options), blocks, and discoveries. One or two lines per entry: a checkpoint trail,
 not a transcript. The REPORT below remains the authoritative stage outcome.
 
+## Deliver before reporting
+
+A stage is delivered when its work is committed and pushed — not when the REPORT says so. The
+orchestrator opens the feature PR from this branch, so uncommitted work never reaches review, and a
+dirty worktree counts as a failed stage whatever the outcome line claims.
+
+1. Commit on the current branch: `git add -A && git commit -m "<stage>(<parent-id>): <summary>"`.
+2. Push the branch: `git push -u origin HEAD`.
+3. Report `COMMIT`, `PUSHED`, and `PR`. The `document` stage also opens or updates the feature PR
+   and reports its URL; every earlier stage reports `PR: none`.
+
 ## Instructions
 1. Read and follow the playbook file listed above.
 2. Treat the bead as the source-of-truth specification (not a prompt script).

package/skills/workflow/using-agent-skills/SKILL.md

@@ -23,6 +23,7 @@ Task arrives
     ├── Have a rough idea? ─────────────────→ record-idea
     ├── New feature / PRD needed? ──────────→ write-a-prd
     ├── PRD approved, need tasks? ──────────→ prd-to-tasks
+    ├── Spec approved, need tickets? ───────→ spec-to-tickets
     ├── Need a single task tracked? ────────→ create-task
     ├── Need to plan a feature end-to-end? ─→ plan
     ├── Running beads / task execution? ────→ ralph