docs(orchestrate-herdr): cover collapsed planner identity and review gaps

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.

skills/engineering/orchestrate-herdr/SKILL.md

@@ -10,6 +10,8 @@ This skill takes a tracker issue number and optional Herdr worker node. It check
 
 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.
 
+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`.
+
 Read these references before acting:
 
 - `references/dispatcher.md` — discover an existing run or safely start a planner.

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

@@ -6,8 +6,8 @@ Invocation is `/skill:orchestrate-herdr <spec-ticket> [worker]` (for example, `/
 
 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.
+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, report that it is already running; do not start another or monitor it. If the matching run exists but the label is missing, verify the run identity, add `in-progress`, comment on the reconciliation, then exit.
+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.
 

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

@@ -36,7 +36,9 @@ Start each implementer with its role, task-issue URL, worktree path, and startin
 - merge the latest integration branch into its task branch before reporting done;
 - post its handoff on the task issue; do not merge to the integration branch or open a PR.
 
-When an implementer finishes, launch **reviewer subagents** to 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 Pi worker subagent and rerun review until clear. Only then use a fresh worker subagent 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
 

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

@@ -5,7 +5,7 @@ The worker node is the source of truth. Keep state under `.orchestrate/<slug>/`
 ## Files
 
 - `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.
+- `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.
 
 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`.
 
@@ -25,7 +25,7 @@ On every invocation or restart:
 
 1. Read the parent issue, labels, and relevant comments.
 2. Inspect the worker's `run.json` and event log.
-3. Query Herdr for the planner and match its exact recorded IDs; inspect the planner's Pi subagent runs for child status. Do not infer ownership from a matching working directory.
+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.
 
 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.