docs(forge-cli): note tea verb fallback and label id vs name in tea.md

When the invoking session is the planner, skip the launch-claim and
monitor ceremony and run the loop in place. Reconcile stale pane IDs
instead of treating them as mismatches. Require clean/pushed task
worktrees before merge, review with one independent subagent, and assert
cross-ticket checks on the integration branch. Pair start/finish events
so silent phase gaps are detectable.

README.md

@@ -28,7 +28,7 @@ Many of these skills were created or originated by the following people and orga
 - [implement-spec](skills/engineering/implement-spec/SKILL.md) — Implement the result of /to-spec and /to-tickets in code.
 - [implementation-orchestrator](skills/engineering/implementation-orchestrator/SKILL.md) — Implements ready-for-agent tracker tickets through isolated worktrees, pull requests, review, conflict resolution, and merge. Use after wayfinder and planning have produced tickets, with or without a ticket ID/URL; no ticket ID/URL means process available tickets. Does not create planning tickets.
 - [improve-codebase-architecture](skills/engineering/improve-codebase-architecture/SKILL.md) — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
-- [orchestrate-herdr](skills/engineering/orchestrate-herdr/SKILL.md) — Drive a plan from context or @file through a published spec, linked tickets, and one-at-a-time isolated implementation to a merged PR using Herdr and Pi agents.
+- [orchestrate-herdr](skills/engineering/orchestrate-herdr/SKILL.md) — Start or monitor a Herdr/Pi planner for a published spec ticket; re-invoke after an orchestrator outage.
 - [project-context-pack](skills/engineering/project-context-pack/SKILL.md) — Use when the user wants a bounded repo context pack, project map, codebase index, or cached memory file so later work uses fd/rg/tree-sitter/LSP instead of repeated browsing.
 - [recipe-diagrams](skills/engineering/recipe-diagrams/SKILL.md) — Recipe diagrams: convert any recipe into a high-resolution Cooking for Engineers-style PNG process-flow table with aligned ingredient streams, preparation branches, joins, temperatures, timings, and finish steps. Use when the user asks for a recipe diagram.
 - [security-audit](skills/engineering/security-audit/SKILL.md) — Comprehensive security and correctness audit of a branch's changes. Use for deep review requests, or branch/PR diff audits focused on bugs, breaking changes, security issues, devex regressions, and feature-gate leaks.

skills/engineering/README.md

@@ -13,7 +13,7 @@ Daily code work.
 - [implement-spec](implement-spec/SKILL.md) — Implement the result of /to-spec and /to-tickets in code.
 - [implementation-orchestrator](implementation-orchestrator/SKILL.md) — Implements ready-for-agent tracker tickets through isolated worktrees, pull requests, review, conflict resolution, and merge. Use after wayfinder and planning have produced tickets, with or without a ticket ID/URL; no ticket ID/URL means process available tickets. Does not create planning tickets.
 - [improve-codebase-architecture](improve-codebase-architecture/SKILL.md) — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
-- [orchestrate-herdr](orchestrate-herdr/SKILL.md) — Implement a published spec ticket using Herdr and Pi agents on a named worker node.
+- [orchestrate-herdr](orchestrate-herdr/SKILL.md) — Start or monitor a Herdr/Pi planner for a published spec ticket; re-invoke after an orchestrator outage.
 - [project-context-pack](project-context-pack/SKILL.md) — Use when the user wants a bounded repo context pack, project map, codebase index, or cached memory file so later work uses fd/rg/tree-sitter/LSP instead of repeated browsing.
 - [recipe-diagrams](recipe-diagrams/SKILL.md) — Recipe diagrams: convert any recipe into a high-resolution Cooking for Engineers-style PNG process-flow table with aligned ingredient streams, preparation branches, joins, temperatures, timings, and finish steps. Use when the user asks for a recipe diagram.
 - [security-audit](security-audit/SKILL.md) — Comprehensive security and correctness audit of a branch's changes. Use for deep review requests, or branch/PR diff audits focused on bugs, breaking changes, security issues, devex regressions, and feature-gate leaks.

skills/engineering/code-quality-review/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: thermo-nuclear-code-quality-review
+name: code-quality-review
-description: Run an extremely strict maintainability review for abstraction quality, giant files, and spaghetti-condition growth. Use for a thermo-nuclear code quality review, thermonuclear review, deep code quality audit, or especially harsh maintainability review.
+description: Run an extremely strict maintainability review for abstraction quality, giant files, and spaghetti-condition growth. Use for a code quality review, deep code quality audit, or especially harsh maintainability review.
 disable-model-invocation: true
 ---
 
-# Thermo-Nuclear Code Quality Review
+# Code Quality Review
 
 Use this skill for an unusually strict review focused on implementation quality, maintainability, abstraction quality, and codebase health.
 

skills/engineering/forge-cli/references/tea.md

@@ -21,6 +21,8 @@ tea comments add ID --description "$(cat BODY_FILE)"
 tea issues close ID
 ```
 
+Prefer these CLI verbs over hand-rolled REST. If `tea` lacks a verb (check `tea pulls --help` for the current close and merge verbs), and you fall back to the Gitea REST API, note that the issue create/update payload takes label **IDs**, while the `/issues/{id}/labels` sub-resource takes **names**. Keep `curl` output out of the transcript by writing it to a file (`curl -s ... -o FILE`).
+
 ## Pull request lifecycle
 
 ```bash

skills/engineering/implementation-orchestrator/SKILL.md

@@ -44,7 +44,7 @@ Comments are the message board. Record claims, status, evidence, questions, deci
 4. **Implement.** Launch one worker per ticket with `pi-subagents` in an isolated worktree, maximum three in flight by default. Pass the complete ticket, comments, acceptance criteria, non-goals, linked context, and validation contract. Each worker makes only ticket-scoped changes, commits them, and reports changed files and checks.
 5. **Escalate.** For missing requirements, unsafe ambiguity, credentials, unrelated scope, or a product/architecture decision, stop. For human review or judgment, assign the ticket to the configured human reviewer, apply `workflow:ready-for-human`, and comment the exact request. If no human identity is configured, ask before assigning and changing the state. Use `workflow:blocked` for non-human blockers. Preserve the worktree on failure.
 6. **PR.** Run documented local checks. Push the branch and create exactly one PR/MR for the ticket. Link the ticket's tracker ID and title in the PR/MR, set `workflow:pr-open`, and comment the PR/MR URL on the ticket. Keep the worktree.
-7. **Review.** Set `workflow:review`. Run a fresh-context `code-review` review with correctness/spec and standards axes separate. Post findings through the PR/MR comment/review function. For actionable findings, set `workflow:changes-requested`, send one fix worker, rerun checks, and repeat. Allow at most three rounds.
+7. **Review.** Set `workflow:review`. Run a fresh-context `code-review` review with correctness/spec and standards axes separate. Then run the `security-audit` and `code-quality-review` both in their own `reviewer` subagent. Post findings through the PR/MR comment/review function. For actionable findings, set `workflow:changes-requested`, send one fix worker, rerun checks, and repeat. Allow at most three rounds.
 8. **Conflict.** Set `workflow:conflict`, then follow `resolving-merge-conflicts`. Inspect both intents, preserve them where possible, never invent behavior, never abort, rerun local checks, and update the PR/MR. If judgment is needed, assign the PR/MR and ticket to the configured human reviewer, apply `workflow:ready-for-human`, and comment the request in both places. If no human identity is configured, ask before assigning.
 9. **Merge.** Merge only after independent review is clean, local checks pass, forge CI is green, the target is still the expected default branch, and no human decision or blocker remains. Comment the merge receipt and outcome, close the ticket, apply `workflow:merged` when supported, verify integration, then remove the worktree.
 10. **Finish.** Report merged tickets and PR/MR URLs, human handoffs, blocked tickets, failed checks, review rounds, and remaining eligible tickets. Report `done` only when no open implementation or human tickets remain in the selected scope. If only human tickets remain, report `waiting-on-human`.

skills/engineering/orchestrate-herdr/SKILL.md

@@ -1,35 +1,29 @@
 ---
 name: orchestrate-herdr
-description: "Implement a published spec ticket using Herdr and Pi agents. Use with /skill:orchestrate-herdr <spec-ticket> [worker], such as /skill:orchestrate-herdr 32 obelix; omitted worker uses the current local worker."
+description: "Start a Herdr/Pi planner for a published spec ticket. Invocation: /skill:orchestrate-herdr ISSUE [WORKER]; omitted worker uses the current local worker."
 disable-model-invocation: true
 ---
 
 # Orchestrate a spec with Herdr
 
-Invocation requires `<spec-ticket>` and optionally accepts `[worker]`. Example: `/skill:orchestrate-herdr 32 obelix`. If the worker is omitted or blank, use the current local worker; otherwise resolve it against `herdr machine list`. Always start a fresh agent for this invocation and for each dispatched task; never reuse or resume an existing agent. The selected worker owns execution and persisted run state.
+This skill takes a tracker issue number and optional Herdr worker node. It checks whether a planner is already running for that spec; if so, it reports that and exits. Otherwise it starts a planner and exits after confirming startup. The planner runs independently; there is no need to monitor it.
 
-**Start by reading the spec ticket and its linked tickets.** Follow the `implement-spec` flow: understand the task graph, create one integration branch, implement ready tickets in isolated worktrees, merge completed work onto the integration branch, and continue as the frontier advances. If there are no linked implementation tickets forming an actionable frontier, invoke `/to-tickets` and follow its approval and publishing process; otherwise, don't create or rewrite tickets.
+The **planner**  runs on the worker node and coordinates the spec workflow. It delegates implementation, review, and merge work to subagents—not separate CLI agents or Herdr-launched agents. Never attach to, prompt, or resume an existing agent.
 
-This skill is a routing and safety contract. Read the relevant reference before acting:
+When the invoking session is itself the planner — the local worker started the planner in this session, or no saved or matching machine and pane exists — the two identities collapse. Do not go looking for a planner to monitor: run the run-loop directly in this session, skip the launch-claim and monitor ceremony, and record the session as both orchestrator and planner in `run.json`.
 
-- `references/dispatcher.md` — validate the named worker and discover the exact Herdr session and pane.
+Read these references before acting:
-- `references/run-loop.md` — spec-first, integration-branch implementation flow.
-- `references/state.md` — persisted state, recovery, cross-system sync, and cleanup.
 
-## Prerequisites and roles
+- `references/dispatcher.md` — discover an existing run or safely start a planner.
+- `references/run-loop.md` — implement and close the spec.
+- `references/state.md` — worker-side run metadata, event log, claims, and recovery.
 
-The selected worker must have this skill, Herdr, Pi, Git, the target repository and credentials, and an authenticated forge CLI (`tea`, `gh`, or `glab`). Run the `forge-cli` preflight there. If anything is missing or ambiguous, stop with actionable guidance; do not guess or dispatch. Start a fresh agent in a newly created pane; do not route work to an existing agent.
+## Prerequisites
 
-- **Orchestrator** invokes and observes the workflow.
+The selected worker must have Herdr, Git, the target repository and credentials, this skill, and an authenticated forge CLI (`tea`, `gh`, or `glab`). Run the `forge-cli` preflight there. If a prerequisite, machine, or run identity is missing or ambiguous, stop with actionable guidance; do not guess or dispatch.
-- **Worker node** is the named machine and source of truth for run state.
-- **Planner** coordinates and verifies; it does not edit product code or merge.
-- **Implementer/merger agents** work only in assigned scopes; no worker merges unless assigned the merger task.
 
-## Run and finish
+## Workflow
 
-1. Validate the spec ticket and optional worker. Read the spec, all associated tickets, and relevant comments before creating agents or branches.
+1. Validate the spec issue and worker, then follow `references/dispatcher.md` to find or start its planner.
-2. Follow `references/run-loop.md`; keep all work within the spec and linked tickets. Preserve state and evidence on blockers, failures, or human decisions.
+2. If a planner is already active for the spec, report that and exit. Do not attach, prompt, resume, or monitor it.
-3. On restart, follow `references/state.md` and reconcile worker-side state before resuming; never duplicate work because the planner restarted.
+3. If starting a planner, confirm it reaches `working`, then report the run identity and exit. The planner owns the workflow from there; retain run metadata and logs unless the user explicitly asks to delete them.
-4. At completion, clean only clean implementer worktrees and run-owned Herdr panes. Retain state unless the user explicitly asks to delete it.
-
-Report the integration branch or PR, completed tickets, verification/review evidence, blockers, human handoffs, and remaining work. Say `done` only when all tickets are complete and the final review has passed.

skills/engineering/orchestrate-herdr/agents/openai.yaml

@@ -1,5 +1,5 @@
 interface:
-  display_name: "Orchestrate plans to merged PRs with Herdr"
+  display_name: "Start a spec with Herdr"
-  short_description: "Drive planned work from context through tickets to a merged PR"
+  short_description: "Start its planner and exit after startup confirmation"
 policy:
   allow_implicit_invocation: false

skills/engineering/orchestrate-herdr/references/dispatcher.md

@@ -1,26 +1,27 @@
-# Dispatcher: resolve the worker and start fresh
+# Dispatcher: find or start the planner
 
-Invocation is `/skill:orchestrate-herdr <spec-ticket> [worker]` (for example, `/skill:orchestrate-herdr 32 obelix`). The spec ticket is required; the worker is optional. If the worker is omitted or blank, use the current local worker and spawn the agent there. If a worker is named, resolve it from `herdr machine list`; if it is missing or ambiguous, stop and ask. Do not silently select a different worker.
+Invocation is `/skill:orchestrate-herdr <spec-ticket> [worker]` (for example, `/skill:orchestrate-herdr 34 obelix`). The spec issue is required. A named worker is the preferred node for a new planner; if omitted or blank, use the current local worker. Never silently select a different machine.
 
-Always start a **new agent** for this orchestration and each dispatched task. Never reuse or resume an existing agent, even if one appears idle or already in the right repository.
+## Find an existing run first
 
-## Validate the target
+1. Confirm the issue exists, is the parent/spec ticket, and is open. If closed, report completion and do not launch anything.
+2. Resolve the named worker with `herdr machine list`; it is the target for a new run. To find an existing run, inspect enabled saved machines using their exact labels/IDs and `herdr --machine <machine> agent list`.
+3. Read the issue's `in-progress` label and locate its `.orchestrate/<slug>/run.json` on candidate worker checkouts. Match exact recorded Herdr workspace/pane/agent IDs. Agent listings show runtime identity and status, not the spec issue; use a working directory only to locate a candidate checkout, never as proof of ownership. If the recorded pane no longer exists, match the live `herdr agent list` entry and rewrite `run.json` to it, logging the reconciliation; a stale ID is a reconciliation event, not a mismatch. `herdr machine list` reporting no saved machines means the local session is the worker.
+4. If a matching planner is active, monitor it; do not start another. If that planner is this session, the identities have collapsed: continue the run loop here instead of monitoring. If the matching run exists but the label is missing, verify the run identity, add `in-progress`, comment on the reconciliation, and monitor.
+5. If `in-progress` is set but no matching agent can be found, do not start a planner. Refresh Herdr and run state to account for propagation delay; if still unmatched, comment on the parent issue with the mismatch and evidence, then stop for human direction. Do not clear the label automatically.
+6. If there is no matching agent and no `in-progress` label, reconcile any existing run metadata, issue comments, and Git state. If there is no active or ambiguous work, proceed to start a planner. If anything is uncertain, stop rather than risk duplicate work.
 
-1. For a named worker, run `herdr machine list` and match it to an available saved machine. Use that exact label or ID with `herdr --machine <worker> ...`; do not treat arbitrary SSH hostnames as valid machine selectors. For the default local worker, stay on the current worker and spawn the agent locally.
+For an untracked agent, do not attach to it or assume it belongs to this spec. Flag it for human review if it appears relevant; otherwise leave it untouched.
-2. For a named worker, confirm the machine is reachable; for the default local worker, inspect the current local Herdr session. In either case, inspect workspaces, panes, and agents. Discover the target repository and ref; do not guess pane IDs, repo paths, or agent kinds.
-3. Confirm the spec ticket exists on the target repository's tracker and is the parent/spec ticket. The new planner must read the spec, linked tickets, and relevant comments before creating work.
-4. Confirm the target has this skill, Pi, Git, repository credentials, and an authenticated forge CLI (run the `forge-cli` preflight). Stop with actionable guidance if not.
-
-Run `herdr --skill` to discover the installed Herdr skills and follow the relevant skill for CLI workflows; use CLI help for exact command syntax. Machine commands require a configured, enabled machine profile and a reachable, API-compatible Herdr server. A connection failure does not prove a mutation failed; inspect remote state before retrying.
 
 ## Start a new planner
 
-Choose a pane in the target repository only as the source for creating a **new sibling pane**. Do not send work to any existing agent pane. Create the new pane with the confirmed repository working directory, read its returned pane ID, then start a fresh Pi agent there using the installed agent kind. If there is no suitable source pane or no available shell in the new pane, stop rather than commandeering an unrelated pane.
+1. On the selected worker, acquire a per-spec launch claim using an atomic exclusive create under `.orchestrate/`. If another invocation holds the claim, reconcile its owner and run state; never steal an uncertain claim.
+2. Create a new sibling pane in the confirmed repository checkout and start a fresh Pi planner agent there. Never use an existing agent pane as the planner. Give the planner the issue number, worker identity, repository path, and references to `run-loop.md` and `state.md`.
+3. The planner's first action is to set/verify the spec's `in-progress` label, before reading tickets or dispatching agents. It then records its Herdr IDs in `run.json` and begins the run loop.
+4. Confirm the planner reaches `working` and the label is set. Release the launch claim only after confirmed startup. If startup failure is confirmed, release the claim and report the failure. If the outcome is uncertain, retain the claim and stop; do not retry blindly.
 
-Submit the exact invocation to that new agent, using the spec ticket and resolved worker (omit the worker when using the current local worker):
+## Start confirmation and failures
 
-```text
+After launching, confirm the planner reaches `working` and the `in-progress` label is set. Then report its run identity and exit; do not wait for later state changes or monitor its agents. If the machine is unreachable, check it with `herdr machine status`; when authentication is needed, run `herdr machine reconnect <label-or-id>` and verify connectivity. Retry transient connection failures at most twice after the first attempt. If the run cannot be safely identified, comment with the blocker and stop; do not dispatch to a different worker.
-/skill:orchestrate-herdr <spec-ticket> [worker]
-```
 
-Confirm the fresh agent reaches `working` before reporting kickoff success. If startup or submission is uncertain, inspect that new pane/agent before retrying; do not create a duplicate agent blindly. Once the planner is working, report the worker, spec ticket, and new agent/pane, then stop monitoring the full workflow.
+Herdr machine commands require an enabled saved machine and reachable, API-compatible Herdr server. A failed connection does not prove a mutation failed; reconcile remote state before retrying.

skills/engineering/orchestrate-herdr/references/run-loop.md

@@ -1,42 +1,50 @@
 # Run loop: implement a spec ticket
 
-The spec and its linked tickets define scope; the tracker is source of truth. Begin by reading the spec ticket, every associated ticket, blockers, and relevant comments. If the spec has no linked implementation tickets forming an actionable frontier, invoke `/to-tickets` and follow its approval and publishing process before implementation. If existing tickets are blocked, don't invent additional work.
+The spec and linked tickets define scope; the tracker is the source of truth. The planner's first action is to set/verify the parent issue's `in-progress` label. Then read the spec, every associated ticket, blockers, and relevant comments. If the spec has no linked implementation tickets forming an actionable frontier, invoke `/to-tickets` and follow its approval and publishing process before implementation. If tickets are blocked, don't invent extra work.
 
-The issue tracker should have been provided to you. If not, tell the user to run `/setup-skills`.
+The issue tracker should have been provided. If not, tell the user to run `/setup-skills`.
 
-The goal is the entire spec implemented on a single **integration branch**, with every ticket resolved the way the issue tracker closes work.
+The goal is the entire spec implemented on one **integration branch**, with each ticket resolved according to tracker semantics. Treat tickets as a dependency graph; re-query the tracker as the ready frontier changes. If no ticket is actionable, report the blocker rather than guessing.
 
-The tickets are not a list of steps. They are a **task graph** with blocking relationships between them. This means there is always a **frontier** of tickets which are ready to be grabbed.
+## Communication
 
-Communication to and from subagents should be sparse. Communicate primarily through **context pointers**: to the spec, tickets, research notes, and previous commits. Don't duplicate information already available via pointers.
+All agent communication and handoffs go through tracker or PR comments; `.orchestrate/<slug>/events.jsonl` is only the operational event log. Keep comments concise and link to context rather than copying ticket bodies or pane output.
+
+- Implementers post their completion handoff or blocker on the task issue, including branch/commit, changed files, acceptance evidence, checks, and concerns.
+- Reviewers put review discussion on the PR. Record the review outcome on the task issue.
+- The planner posts parent-spec comments at meaningful milestones: implementation ready, review outcome, merge, actionable blocker, and completion. Don't repeat comments already posted by a worker.
 
 ## 1. Read and establish the integration branch
 
-- Confirm the supplied ticket is the spec/parent ticket and identify its linked implementation tickets.
+- Confirm the supplied issue is the parent/spec ticket and identify linked implementation tickets.
-- Understand the ticket graph and its current frontier. Re-query tracker state as work advances.
+- Understand the task graph and current frontier. Re-query tracker state as work advances.
-- When tickets require codebase or external-documentation exploration, dispatch an exploration subagent before implementation. Have it save concise Markdown notes outside the repo in a directory accessible to all future subagents; pass those notes as context pointers to implementers.
+- When tickets require codebase or external-documentation exploration, use a subagent and put concise findings in the relevant tracker comment for later subagents to reference.
 - Create one integration branch from the intended target branch. If a PR is required, open a draft after the first implementation merge and link it to close the spec and tickets.
-- If a ticket or its dependencies are ambiguous, stop and ask rather than inferring.
+- If a ticket or its dependencies are ambiguous, stop and ask rather than infer.
 
 ## 2. Implement the frontier
 
-For each open, unblocked ticket, start a **new implementer subagents** in its own worktree and branch. Independent frontier tickets may run concurrently; never parallel-write a shared checkout. Start a fresh merger agent for each merge as well.
+Use the `subagents` skill and native subagent workflow for every child role. Do not use Herdr agent commands or launch separate CLI processes for implementers, reviewers, fixers, or mergers.
 
-Each implementer gets the full ticket and acceptance criteria, relevant context pointers, scope boundaries, worktree path, and starting branch. Require the implementer to:
+For each open, unblocked ticket, start a **worker subagent** from the planner using the native subagent workflow, with its own worktree and branch. Independent frontier tickets may run concurrently; never parallel-write a shared checkout. Do not launch implementers, reviewers, fixers, or mergers as separate CLI or Herdr agents; the planner is the only full CLI agent. Start a fresh worker subagent for each merge.
+
+Start each implementer with its role, task-issue URL, worktree path, and starting branch; the issue itself holds scope and acceptance criteria. Put any later clarification or handoff in tracker/PR comments, not agent-to-agent chat. Require the implementer to:
 
 - confirm its worktree starts from the current integration branch (reset/rebase onto it if needed);
 - use the `tdd` skill and run focused checks;
 - commit its ticket work on its task branch;
 - merge the latest integration branch into its task branch before reporting done;
-- report changed files, commit, checks, and any blockers; do not merge to the integration branch or open a PR.
+- post its handoff on the task issue; do not merge to the integration branch or open a PR.
 
-When an implementer finishes, have a **new independent reviewer agent** run the `code-review` skill against that task branch, using the current integration branch as the base. Resolve all actionable findings in a fresh scoped fix agent and rerun the review until clear. Only then use a fresh merger agent to merge the task branch into the integration branch. Verify the merge and update tracker state before dispatching newly unblocked tickets. Reconcile uncertain Git or tracker outcomes before retrying.
+When an implementer finishes, have a **new independent reviewer subagent** run the `code-review`, `security-audit`, and `code-quality-review` skills against that task branch, using the current integration branch as the base. Put review discussion on the PR and summarize its outcome on the task issue. Resolve actionable findings in a fresh scoped worker subagent and rerun review until clear. Only then use a fresh worker subagent to merge the task branch into the integration branch. Before dispatching the merger, confirm the task worktree is clean (`git status --porcelain` empty) and the task branch is fully pushed; recover unpushed or uncommitted work rather than merging around it. Verify the merge and update tracker state before dispatching newly unblocked tickets. Reconcile uncertain Git or tracker outcomes before retrying.
+
+When a check spans tickets — for example one coverage threshold covering several modules — an individual task branch can be red because it owns only part of the check, not because of a defect. Review still runs against the task branch, but assert the shared check after merge, on the integration branch; merge-then-fix is the allowed order in that case. Before deviating from green-before-merge, decide whether the check or the branch is mis-scoped, and record that decision.
  
 ## 3. Final review and completion
 
-After all tickets are implemented and merged, run `code-review` against the entire integration branch as a final integration review. Have a fresh implementer fix all actionable findings in a scoped worktree; merge the fixes and rerun review until clear. Do not report completion until this review is clear and final checks pass; do not merge around unresolved findings or failed checks.
+After all tickets are implemented and merged, have a **reviewer subagent** run `code-review` against the entire integration branch as a final integration review. Have a fresh worker subagent fix actionable findings in a scoped worktree; merge the fixes and rerun review until clear. Do not report completion until this review is clear and final checks pass; do not merge around unresolved findings or failed checks.
 
-If a draft PR exists, mark it ready for review after final checks. Otherwise, resolve each ticket according to the tracker's close semantics and report the integration branch. Close the parent spec ticket only when all work is complete, verified, and merged. Clean up implementer worktrees only after confirming they are clean; retain unresolved work.
+If a draft PR exists, mark it `needs-review` after final checks. Otherwise, resolve each ticket according to tracker close semantics and report the integration branch. Close the parent spec ticket only when all work is complete, verified, and merged. As part of closing it, remove the `in-progress` label. Clean only confirmed-clean implementer worktrees and issue branch that have been merged successfully in draft PR; retain unresolved work and the worker-side run log.
 
 ## Retry and escalation rules
 

skills/engineering/orchestrate-herdr/references/state.md

@@ -1,48 +1,33 @@
-# State, recovery, and cleanup
+# Worker-side run state and recovery
 
-Run state lives under a run-scoped `.orchestrate/<slug>` directory in the worker node's repository checkout. The worker node is the source of truth. Keep this state out of product commits and PRs.
+The worker node is the source of truth. Keep state under `.orchestrate/<slug>/` in the target repository checkout, outside product commits and PRs. Use a stable issue-derived slug such as `spec-34`; do not mirror state on the orchestrator node.
 
-## State directory
+## Files
 
-Create `.orchestrate/<slug>/` on the worker node:
+- `run.json` — minimal recovery metadata: spec issue ID/URL, repository identity, worker label/ID, planner's Herdr agent/pane/workspace IDs, and each tracked child subagent's role, issue ID, subagent run ID, branch, and worktree.
+- `events.jsonl` — append-only structured operational events: timestamp, actor/task, action, outcome, and relevant Herdr/Git/tracker IDs. No pane transcripts, copied ticket bodies, plans, or handoff prose. Record a start and finish event for every phase (worktree created, implementer handoff, review dispatched, review completed, merge completed); a phase with only one of the pair is a detectable gap, whereas a silent absence is not.
 
-- `plan.json` — the original goal, repo path/URL, base ref, acceptance criteria, and task definitions (name, type, scoped goal, dependencies, path boundaries, acceptance, verification recipe, retry cap).
+The issue tracker is canonical for ticket status, acceptance criteria, decisions, and communication. Keep agent handoffs and blockers in comments on the relevant task issue; use PR comments for review discussion; use parent-spec comments for milestone rollups. Do not create local handoff files or duplicate tracker content in `run.json`.
-- `state.json` — each task's status, attempt count, worktree path, branch, Herdr session/workspace/pane IDs, and handoff path.
-- `handoffs/<task>.md` — each agent's final response, saved verbatim with task, branch, and execution metadata.
-- `recovery.log` — spawns, recovery, reconciliation, and operator decisions.
 
-Use kebab-case task names. Validate that dependencies and verifier targets exist and that the dependency graph has no cycles before starting work.
+## Claim and label
 
-## Persist immediately
+Before creating a planner, acquire a per-spec launch claim under `.orchestrate/` with an atomic exclusive create. The claim only serializes startup; it is not a second progress record. Record its owner and issue ID. Never steal an uncertain claim.
 
-Persist state immediately after every side effect and record enough Herdr, branch, worktree, and task identity to reconcile execution after interruption. On restart, inspect persisted state and native Herdr status before creating or restarting agents. Never duplicate work solely because a planner session restarted.
+The new planner's first action is to set/verify the parent's `in-progress` label, before reading tickets or dispatching work. After confirmed startup and recording the planner's Herdr IDs, release the launch claim. Release a claim after startup failure only when failure and absence of a running planner are confirmed. Keep it and escalate when the result is uncertain.
 
-A new orchestrator system reconnects to the worker node and syncs from it before resuming; a local copy is not authoritative. Do not create a separate Git branch solely to transfer this state.
+If the parent has `in-progress` but no matching agent is found, do not start a replacement or clear the label. Comment with the mismatch and wait for the user's explicit retry decision. If a matching agent exists but the label is missing, verify the run record, add the label, and comment on the repair.
 
-## Recovery
+## Persist and recover
 
-On restart, in order:
+Append a structured event after each consequential side effect and enough identity data to match the run to Herdr. The worker log records activity while the orchestrator is unavailable; agents continue posting comments to the tracker.
 
-1. Read `plan.json`, `state.json`, and `handoffs/`.
+On every invocation or restart:
-2. Discover native Herdr state and reconcile stored IDs with what Herdr actually reports.
-3. Reconcile tracker and Git state.
-4. Reattach to running agents; never duplicate a task just because the session restarted.
 
-If reconciliation cannot resolve a state mismatch, stop and escalate rather than guessing.
+1. Read the parent issue, labels, and relevant comments.
+2. Inspect the worker's `run.json` and event log.
+3. Query Herdr agent state and match exact recorded IDs; do not infer ownership from a matching working directory. If the recorded pane was recreated or removed between sessions, match the live entry, rewrite `run.json` to it, and log the reconciliation.
+4. Reconcile tracker and Git state before deciding to start a planner. If the worker is unreachable or identities/state disagree, report the blocker and stop rather than guessing.
 
-## Handoffs
+If a matching live planner exists, report that it is already running and exit; do not attach to, prompt, or resume it. The planner manages its own subagents. If there is no matching agent and no `in-progress` label, reconcile any stale run record; start a fresh planner only when no active or ambiguous work remains and a new atomic claim is acquired.
 
-Handoffs are the only information channel between workers and planners. Save each final response verbatim; add a short metadata comment above it with task, branch, worktree, and Herdr identifiers. Do not paraphrase the evidence.
+Retain `run.json` and `events.jsonl` after completion. The planner removes `in-progress` while closing the parent spec only after all tickets are complete, verified, and merged. Delete retained run state only at the user's explicit request.
-
-- **Worker** — status (`success`/`partial`/`blocked`), actual branch, what it did, acceptance with evidence, verification tier, commands run, concerns, suggested follow-ups. A worker commits to its task branch and does not merge/rebase/open a PR unless the task requires it. Do not accept `success` if stated acceptance is unmet or evidence is absent.
-- **Verifier** — verification tier, target, execution, findings per criterion (met/not met/n/a) with severity, and environment limits. `verifier-blocked` means the environment prevented a meaningful check; `verifier-failed` means the check ran and the target did not pass. Do not downgrade a failure to a blocked verdict.
-- **Planner** — an aggregated handoff to the parent: status, actual deliverable branch, one bullet per meaningful slice, strongest evidence actually produced, risks, and parent-scope follow-ups.
-
-## Cleanup
-
-At completion, remove only what this run owns and leave everything else untouched.
-
-- **Remove** clean task worktrees (via `git worktree remove`, after accounting for every staged, unstaged, and untracked change) and close only Herdr panes created by this run.
-- **Preserve** dirty or unresolved worktrees — cleanup cannot destroy unfinished work or recovery evidence.
-- **Retain** the worker node's canonical checkout, `.orchestrate/<slug>` state, handoffs, and logs. Never delete retained state automatically. Cleanup of retained state requires an explicit user action.
-- Leave unrelated Herdr panes, tickets, repositories, branches, and PRs untouched.

skills/engineering/security-audit/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: security-audit
 description: Comprehensive security and correctness audit of a branch's changes. Use for deep review requests, or branch/PR diff audits focused on bugs, breaking changes, security issues, devex regressions, and feature-gate leaks.
-disable-model-invocation: true
 ---
 
 # Security Audit Skill

skills/pstack/reflect/SKILL.md

@@ -42,6 +42,7 @@ Show the complete Accepted / Rejected / Backlog output and wait for explicit use
 
 For each approved item, follow its Routing field:
 
+- Package-installed skill (for example under `node_modules` or a marketplace directory): do not edit it — the change is lost on update. Route the lesson to project-level config or a project skill, or report it as a backlog item instead.
 - Trivial edit to an existing skill: edit it directly.
 - Substantive edit to an existing skill: use the harness's established skill-authoring workflow, if available; otherwise draft and validate the smallest clear change.
 - Description needs tuning: improve the target skill's routing description using its supported metadata format.