@marcomigozzi/trailhead 0.15.0 → 0.16.1

package/plugins/trailhead/skills/trailhead-work/SKILL.md

@@ -1,15 +1,26 @@
 ---
 name: trailhead-work
 user-invocable: false
-description: "trailhead work cluster: the verbs that resolve tickets on the map and manage a ticket's lifecycle. Work the next frontier ticket or the one you name (work), work one ticket whole without splitting, a new whiteboard ticket or an existing one (quick), checkpoint the ticket in play (pause), resume it from its checkpoint (resume), split an oversized ticket into children (split), and run the whole frontier autonomously until a stop condition or exhaustion (auto). A cohesion cluster of the trailhead skill split, loading the shared `_shared/` core; reached through the `/trailhead:<verb>` command wrappers. Not auto-invoked: it runs only when one of these verbs is dispatched."
+description: "trailhead work cluster: the verbs that resolve tickets on the map and manage a ticket's lifecycle. Work the next frontier ticket or the one you name (work), work one ticket whole without splitting, a new whiteboard ticket or an existing one (quick), checkpoint the ticket in play (pause), resume it from its checkpoint (resume), split an oversized ticket into children (split), and run a chosen scope (one map, the whiteboard, or everything) autonomously until a stop condition or exhaustion (auto). A cohesion cluster of the trailhead skill split, loading the shared `_shared/` core; reached through the `/trailhead:<verb>` command wrappers. Not auto-invoked: it runs only when one of these verbs is dispatched."
 argument-hint: "[work|quick|pause|resume|split|auto] [ticket | \"text\" | note]"
 ---
 
-`trailhead-work` is the **work cluster** of the trailhead skill: the verbs that resolve tickets and manage a ticket's lifecycle. `work` takes the next frontier ticket (or the one you name) and resolves it with its type's engine; `quick` works one ticket whole without splitting (a new whiteboard ticket from text, or an existing ticket, which stays where it is); `pause` checkpoints the ticket in play; `resume` picks it back up; `split` breaks an oversized ticket into children; `auto` runs the map's frontier autonomously, ticket by ticket, suspending the one-ticket-per-session rule until a stop condition or exhaustion. Everything lives on the GitHub Issues; the repo holds code only.
+`trailhead-work` is the **work cluster** of the trailhead skill: the verbs that resolve tickets and manage a ticket's lifecycle. `work` takes the next frontier ticket (or the one you name) and resolves it with its type's engine; `quick` works one ticket whole without splitting (a new whiteboard ticket from text, or an existing ticket, which stays where it is); `pause` checkpoints the ticket in play; `resume` picks it back up; `split` breaks an oversized ticket into children; `auto` runs a chosen run scope autonomously, ticket by ticket, suspending the one-ticket-per-session rule until a stop condition or exhaustion. Everything lives on the GitHub Issues; the repo holds code only.
+
+## Move into the handed checkout (`--in=`)
+
+The panel starts `work` and `resume` from wherever the session stands and cannot move it, so it appends the pinned checkout to the args as a last word `--in=<token>` (base64url of the checkout root). When the args of `work` or `resume` end with such a word, this section runs first, before the load, the Preflight and anything else; with no such word it does not apply. `quick` never gets one.
+
+1. Drop the `--in=<token>` word from the args: the verb, and its ticket number if any, are what is left.
+2. Run `node <templates>/trailhead-checkout-in.js --in <token> --cwd "$PWD"`. `<templates>` is the first of `${CLAUDE_PLUGIN_ROOT}/templates/`, `${CLAUDE_CONFIG_DIR:-~/.claude}/trailhead/templates/`, `~/.codex/skills/trailhead/templates/` that contains the script (the same lookup as `trailhead-work-state.js`: try all three in order, skipping the first when `CLAUDE_PLUGIN_ROOT` is unset or empty). It prints one JSON line with a `status`. If the script is missing (none of the three has it: an outdated install), stop and report that the checkout could not be reached and the install needs an update: nothing is claimed, and never move by hand.
+3. `invalid` -> stop and report its `reason` in one line; never move, never look for another checkout.
+4. `here` -> the session is already in the checkout: no move, carry on with the args from step 1.
+5. `move` -> run the helper's `cd` field verbatim as its own Bash call (a lone `cd` is what moves the session; never join it to a read or another command, and never edit the quoting). A failed `cd` stops the verb with a report. Then re-run the helper with the new `$PWD` and require `here`; anything else means the session could not move: stop and report that, with nothing claimed.
+6. After a move, say in one result-oriented line which checkout the session is now working in, then continue with **Load first** and, for an explicit ticket number, the Preflight.
 
 ## Load first, in order
 
-Before doing anything, load `<skill base>/../_shared/load-first.md` and follow it: the shared-core load contract (the six core files, in order, then the effective config). `<skill base>` is this skill's **base directory** (Claude Code prints it as `Base directory for this skill:` when the skill loads; on another host, the directory holding this `SKILL.md`): resolve the path to an **absolute path** and open it with the **Read tool** on that absolute path. Never `cd` into a skills directory and never read a relative path from the shell (a `cd` compound followed by a read is denied by the search guard). The same rule covers every later `../_shared/...` or `references/...` path in this skill: resolve it against the base directory to an absolute path before reading. `_shared/` is a **sibling** of this cluster's own directory (at `../_shared/`), never a child of it; its absence from a listing of the cluster dir is expected, not a missing core.
+Right after the move above (when there is one) and before anything else, load `<skill base>/../_shared/load-first.md` and follow it: the shared-core load contract (the six core files, in order, then the effective config). `<skill base>` is this skill's **base directory** (Claude Code prints it as `Base directory for this skill:` when the skill loads; on another host, the directory holding this `SKILL.md`): resolve the path to an **absolute path** and open it with the **Read tool** on that absolute path. Never `cd` into a skills directory and never read a relative path from the shell (a `cd` compound followed by a read is denied by the search guard). The same rule covers every later `../_shared/...` or `references/...` path in this skill: resolve it against the base directory to an absolute path before reading. `_shared/` is a **sibling** of this cluster's own directory (at `../_shared/`), never a child of it; its absence from a listing of the cluster dir is expected, not a missing core.
 
 Config is a property of the project/map, not the working directory: an isolation workspace inherits this config, never re-resolves it from the isolated copy's own root. **For an explicit `work <n>` / `quick <n>`, the named-ticket Preflight below runs *before* this config load:** never load config, or anything else, for a ticket that turns out closed.
 
@@ -17,16 +28,16 @@ Config is a property of the project/map, not the working directory: an isolation
 
 The **first word** of the arguments is the verb; the rest is the text (a ticket number, a `"text"` seed, or a pause note).
 
-- **`work [ticket]`** to the **Work the map** engine below (Mode 2). It dispatches the chosen ticket to its type's engine in **`references/ticket-engines.md`** (`decision` / `research` / `prototype` / `build` / `bug` / `task`). Read that file when you resolve the ticket.
+- **`work [ticket]`** (after **Move into the handed checkout** when the args end with `--in=<token>`) to the **Work the map** engine below (Mode 2). It dispatches the chosen ticket to its type's engine in **`references/ticket-engines.md`** (`decision` / `research` / `prototype` / `build` / `bug` / `task`). Read that file when you resolve the ticket.
 - **`quick [ticket | "text"]`** to the **Work one ticket whole** engine below. It runs the full `build`/`bug` cycle from `references/ticket-engines.md`, without splitting (off the map only for a new `"text"` ticket; a map ticket stays on its map).
-- **`pause [note]`** / **`resume [ticket]`** / **`split [ticket]`** to the teamwork lifecycle: `../_shared/teamwork.md` (multi-cluster, so it lives in `_shared/`). Read it and follow it.
-- **`auto [map]`** to the **autonomous run** engine in **`references/auto.md`**: it runs the map's frontier ticket-by-ticket, suspending one-ticket-per-session, taking every advisory choice as delegate without the confirm gate and stopping only at the safety rail, fog, human-necessary decisions, or human interrupt. Read that file when you engage a run.
+- **`pause [note]`** / **`resume [ticket]`** / **`split [ticket]`** to the teamwork lifecycle (`resume` first goes through **Move into the handed checkout** when its args end with `--in=<token>`): `../_shared/teamwork.md` (multi-cluster, so it lives in `_shared/`). Read it and follow it.
+- **`auto [map]`** to the **autonomous run** engine in **`references/auto.md`**: it runs a chosen run scope (asked at start: one map, the whiteboard, or everything; `<n>` skips the ask) ticket-by-ticket, suspending one-ticket-per-session, taking every advisory choice as delegate without the confirm gate and stopping only at the safety rail, fog, human-necessary decisions, or human interrupt. Read that file when you engage a run.
 
 The cross-cluster situational references and the technique bodies these engines call live in `_shared/`; this cluster names each by its `../_shared/...` path where it needs one (teamwork, out-of-scope, the gh cookbook, the techniques).
 
 ## Preflight: reject a closed or missing named ticket (before anything else)
 
-**When the verb carries an explicit ticket number** (`work <n>` or `quick <n>`), the very first action, before config load, before the map load, and before any claim, scope, or isolation setup, is a single cheap state lookup of that ticket: `gh issue view <n> --json state,stateReason,title` (one call, near-free). Branch on the result:
+**When the verb carries an explicit ticket number** (`work <n>` or `quick <n>`), the first action (after the move into the handed checkout, when there is one), before config load, before the map load, and before any claim, scope, or isolation setup, is a single cheap state lookup of that ticket: `gh issue view <n> --json state,stateReason,title` (one call, near-free). Branch on the result:
 
 - **Open** → proceed into the engine (config load, selection, claim, the rest).
 - **Closed, or the issue does not exist** → **stop immediately and report it by name**, with its close reason where useful (`stateReason`, and the `trailhead:out-of-scope` / `trailhead:superseded` label distinguishes resolved vs out-of-scope vs superseded). Suggest the sensible next step: for a defect in already-closed work open a **new** `bug` per the new-bug-vs-reopen rule (`references/ticket-engines.md`), otherwise pick a frontier ticket. Do **not** load config, load the map, claim, or set up any workspace: a stale or mistyped closed number must be a near-instant, near-free rejection, not a full ramp-up wasted.
@@ -38,8 +49,8 @@ This guard is the **explicit-number paths only**. Bare `work` selects from the l
 The user invokes with a map (URL or number). A ticket is optional: without one, you pick the next decision.
 
 1. Load the **map** (the low-res view, not every ticket body). **Pick which map** if the repo has several open: use the one the user named, else the active map (`.trailhead/active-map`); if neither and more than one is open, list them and ask. Set/refresh the active-map marker to the one you're working. **Named ticket:** its map becomes the active map, a whiteboard ticket leaves it alone (see **Active map** in `../_shared/multi-map.md`, under **Multiple maps on one repo**). **Codebase issue check (greenfield, offer once):** if the repo has **no `trailhead:codebase` issue** (a greenfield map never got one) and now holds **substantial code**, **don't interrupt the work to offer now**: mark the offer **pending** and surface it **at the handoff**, just before the `/clear`-first next-step block (not as a line inside it: see the **pending codebase offer** rule in `../_shared/session-handoff.md`), exactly once. On the user's yes, generate it via the **Codebase map** technique, then pin it (one of the three permanent repo pins: dashboard, codebase, conventions) and link it from the map's Notes; if the user declines, don't nag again this session. A repo that already has the issue, or is still too thin to map, skips this.
-2. Choose the ticket. **If the user named a ticket, the Preflight above already confirmed it is open** (a closed, superseded, out-of-scope, or nonexistent number stopped there, before any setup ran). If the user names one, use it (a **named** ticket may be a `trailhead:whiteboard` one: `work <n>` works it whole, off the map, with the normal cycle and split allowed; use `quick <n>` for the no-split variant; a **named** ticket may also be a `trailhead:paused` one, which `work <n>` / `quick <n>` takes back). Otherwise take a frontier ticket to act on, **scoped to this map** (add its `trailhead:map-<n>` label to the frontier query when several maps are live), **never a `trailhead:paused` ticket** (it is off the frontier: `/trailhead:resume` takes it back) and **never a whiteboard ticket** (bare `work` stays on the map; the whiteboard frontier is reached via `/trailhead:whiteboard` and `quick`). Bare `work` may act on the first ticket the query returns, but that order is `gh`'s newest-first, not a priority: present several independent tickets as a **set to choose from**, not the graph's natural next step (see **Frontier order carries no priority** in `../_shared/substrate.md`). **Claim** it: assign it to yourself before any work, then re-read the assignee before starting; on a collision, stop and ask the user (see `../_shared/teamwork.md`). A claimed ticket that carries `trailhead:paused` drops it at the claim (`gh issue edit <n> --remove-label trailhead:paused`): working it is resuming it. If the ticket proves too big once you're in it, propose a **split** rather than grind, but never split on your own: present the children you would create and wait for the user's go-ahead before creating anything (same file).
-   - **First, resolve the effective isolation mode.** The `isolation:` header defaults to **`auto`** (an absent key means `auto`; the engine never writes the key). Under **`auto`**, at work-start **before any file edit or diagnostic probe**, first run the read-only **assigned-ticket pre-check** (full rule in `../_shared/teamwork.md`): other open tickets already assigned to you **pre-bias** the ask toward `worktree`/`clone` (still asking, easy neutral), and the ask is **skipped** only when the session is already inside this ticket's own linked worktree (`trailhead/t<N>`, `N` the current ticket). Then run the remembered-answer reuse: `node <templates>/trailhead-isolation-answer.js check --repo <project root> --others <csv|none|unavailable>`; on `reuse` print the one-line note and resolve as that answer without asking, otherwise (`ask` or `skipped`) ask the user once whether they will work more than one ticket at once on this machine this session, then `node <templates>/trailhead-isolation-answer.js record --repo <project root> --answer yes|no --others <csv|none>` (sequence, 8-hour idle window and exclusions in `../_shared/teamwork.md`). **No** (a lone ticket): the mode resolves to the current checkout, exactly like `none` (the scope-free check below applies). **Yes**: resolve by repo shape, a plain repo -> `worktree`, a **superrepo** (a `.gitmodules` at the checkout root declaring at least one submodule) -> `clone`; that "yes" **is** the clone gate's answer, so the resolved `clone` path proceeds without re-asking. This asks at most once per ticket work-start (a within-session ticket switch re-asks at the new ticket's work-start), and a remembered answer may suppress even that. An autonomous run (`/trailhead:auto`) never asks and never runs the pre-check (sequential work, no concurrency) and resolves to the current checkout. If the header carries an **explicit** `none`/`worktree`/`clone`, honour it as-is (never subject it to auto's ask): explicit `clone` keeps its own gate, explicit `worktree` is eager. See `../_shared/teamwork.md`.
+2. Choose the ticket. **If the user named a ticket, the Preflight above already confirmed it is open** (a closed, superseded, out-of-scope, or nonexistent number stopped there, before any setup ran). If the user names one, use it (a **named** ticket may be a `trailhead:whiteboard` one: `work <n>` works it whole, off the map, with the normal cycle and split allowed; use `quick <n>` for the no-split variant; a **named** ticket may also be a `trailhead:paused` one, which `work <n>` / `quick <n>` takes back). Otherwise take a frontier ticket to act on, **scoped to this map** (add its `trailhead:map-<n>` label to the frontier query when several maps are live), **never a `trailhead:paused` ticket** (it is off the frontier: `/trailhead:resume` takes it back) and **never a whiteboard ticket** (bare `work` stays on the map; the whiteboard frontier is reached via `/trailhead:whiteboard` and `quick`). Bare `work` may act on the first ticket the query returns, but that order is `gh`'s newest-first, not a priority: present several independent tickets as a **set to choose from**, not the graph's natural next step (see **Frontier order carries no priority** in `../_shared/substrate.md`). **Claim** it: assign it to yourself before any work, then re-read the assignee before starting; on a collision, stop and ask the user (see `../_shared/teamwork.md`). A claimed ticket that carries `trailhead:paused` drops it at the claim (`gh issue edit <n> --remove-label trailhead:paused`): working it is resuming it. Likewise a claimed ticket that carries `trailhead:needs-you` (an autonomous run parked it for the human) has the mark cleared at the claim: `node <templates>/trailhead-needs-you.js clear --issue <n> --repo <owner/name>` (fallback by hand: `gh issue edit <n> --remove-label trailhead:needs-you`). A failed `clear` is reported to the user in one line but never blocks the claim. If the ticket proves too big once you're in it, propose a **split** rather than grind, but never split on your own: present the children you would create and wait for the user's go-ahead before creating anything (same file).
+   - **First, resolve the effective isolation mode.** The `isolation:` header defaults to **`auto`** (an absent key means `auto`; the engine never writes the key). Under **`auto`**, at work-start **before any file edit or diagnostic probe**, first run the read-only **assigned-ticket pre-check** (full rule in `../_shared/teamwork.md`): other open tickets already assigned to you **pre-bias** the ask toward `worktree`/`clone` (still asking, easy neutral), and the ask is **skipped** only when the session is already inside this ticket's own linked worktree (`trailhead/t<N>`, `N` the current ticket). Then run the remembered-answer reuse: `node <templates>/trailhead-isolation-answer.js check --repo <project root> --others <csv|none|unavailable>`; on `reuse` print the one-line note and resolve as that answer without asking, otherwise (`ask` or `skipped`) ask the user once whether they will work more than one ticket at once on this machine this session, then `node <templates>/trailhead-isolation-answer.js record --repo <project root> --answer yes|no --others <csv|none>` (sequence, 8-hour idle window and exclusions in `../_shared/teamwork.md`). **No** (a lone ticket): the mode resolves to the current checkout, exactly like `none` (the scope-free check below applies). **Yes**: resolve by repo shape, a plain repo -> `worktree`, a **superrepo** (a `.gitmodules` at the checkout root declaring at least one submodule) -> `clone`; that "yes" **is** the clone gate's answer, so the resolved `clone` path proceeds without re-asking. This asks at most once per ticket work-start (a within-session ticket switch re-asks at the new ticket's work-start), and a remembered answer may suppress even that. An autonomous run (`/trailhead:auto`) never asks and never runs the pre-check; it resolves to the current checkout with one parallel slot and to a worktree per ticket above one (see `references/auto.md`). If the header carries an **explicit** `none`/`worktree`/`clone`, honour it as-is (never subject it to auto's ask): explicit `clone` keeps its own gate, explicit `worktree` is eager. See `../_shared/teamwork.md`.
    - **When the resolved mode is the current checkout (`isolation: none`, or `auto` answered no), check the scope is free before starting** (this is how a submodule/package gets serialised when worktrees don't fit): scan the other in-progress tickets' `Scope:` lines, and if one **overlaps** this ticket's scope, **stop and tell the user** the scope is busy (name the ticket + holder) and offer a disjoint-scope frontier ticket or to wait. See `../_shared/teamwork.md`.
    - **Write the session-ticket marker**: at the **working root** (the checkout, worktree, or clone you'll edit in), write `.trailhead/session-ticket` as **one line** `#<n> <ticket title>`. **Keep it gitignored** (add `.trailhead/session-ticket` to that repo's `.gitignore` if absent): it's per-session local state, **never committed**. It lets an external tool show "what am I on" offline (the tracker stays the source of truth), but it is not merely that cheap hint: while it is present, the git commit-msg hook also requires every commit to carry a `Refs: #<n>` trailer matching it, so a stale marker left behind would wrongly demand that trailer on unrelated commits. Remove it at Resolve/handoff (see `../_shared/session-handoff.md`); on **Pause** it may stay (you'll return) or be cleared if you release the claim. The **`.trailhead/active-map`** marker (which map this session works) follows the same rules: gitignored, per-session, never committed; see **Multiple maps on one repo** in `../_shared/multi-map.md`.
    - **Sync the commit-msg hook**: at the working root, run `node <templates>/trailhead-commit-msg-sync.js --repo <working-root>` (where `<templates>` lives and what each status means: the commit-msg hook paragraph in `../_shared/teamwork.md`). Stay silent when it reports installed or current. On **upgraded**, give the user one result-oriented line: this clone's commit-msg hook was updated to the current rules. On **foreign**, one line that the user's own hook was left untouched and git does not enforce trailhead's rules here. On **skipped**, one line that nothing was set up here (a `core.hooksPath` without a trailhead hook, or a working root that is not a git repo) and git does not enforce trailhead's rules. On a missing script or a node error (missing means none of the three template dirs has it: try them all before concluding that), inspect the hooks dir (`git rev-parse --git-path hooks`) and report per the fallback in that same paragraph of `../_shared/teamwork.md` (trailhead hook present and executable: enforced but freshness unchecked, and only while node is on the PATH git runs with, update the install; present but not executable: git skips it, not enforced; foreign hook: untouched, not enforced; no hook: not enforced, update the install), never a blind "not enforced"; it never blocks the work.
@@ -49,8 +60,8 @@ The user invokes with a map (URL or number). A ticket is optional: without one,
 3. **Brief the ticket and confirm scope, before the engine runs.** With the ticket claimed, read it and give the user a **brief, result-oriented summary of what resolving it will do** (its goal and the shape of the work, not a plan yet), then **ask whether to proceed or change something as an `AskUserQuestion` menu, never as free text**: **Proceed** (Recommended) first, **Change something** second (the user types the change through the menu's built-in "Other" or in a follow-up message), plus the **delegate** option (this gate is a process choice, see `../_shared/choices.md`). On a host with no structured question tool (Codex), the same options are a plain-text numbered list, per its adapter. This is a HITL confirm gate: on **Proceed**, proceed to the engine. **If the user asks for a change, hold it against the ticket.** A change **consistent** with the ticket is folded in and the engine proceeds. A change that **diverges** from the ticket is surfaced as a mismatch, and the user is **asked, never forced**, whether to (a) work the ticket **as-is**, or (b) open a **separate new ticket** for the divergent request, as an `AskUserQuestion` menu **without the delegate option** (routing a scope change is the human's, per the one-line test in `../_shared/choices.md`). Offer both and decide neither: open the separate ticket **only if the user chooses it** (via **Scope that surfaces while working a ticket**, served by the capture cluster, the same capture-or-split path used for scope that surfaces mid-work), never automatically. **If the user defers the choice rather than settling it here, mark the divergent follow-up pending for the Pending follow-up guard (`../_shared/session-handoff.md`), so it is re-posed at the handoff rather than lost.** **Under an autonomous run (`auto`) this is a process confirm gate**, so it follows the advisory boundary in `references/auto.md`: `auto` proceeds (takes the delegate option) without stopping to brief.
    - **Skip the confirm on a ticket this session already shaped.** Skip the brief menu when, in this same session (before any `/clear`), (a) the agent created this ticket from the user's own request for it, one ticket at a time (a capture `todo`/`bug`/`idea`/`seed`, `ticket`, `quick "<text>"`, or a `split` child the user approved), or (b) a Grilling round on this ticket concluded (`grill <ticket>`): the user just stated or settled its scope, so asking again is redundant. Not a trigger: tickets created in bulk as a side effect (`new`/`adopt` charting, `inbox` triage, follow-ons spawned by a grill on another topic), where no one confirmed this ticket's own scope. Skipping replaces the menu with a **one-line**, result-oriented note (e.g. "working <name> (#n), scope as just agreed"), so the user can still interrupt with a change; a change typed then follows the same consistent/divergent handling as the menu's **Change something**. Still asked: a ticket created or grilled in an earlier session, by someone else, or before a `/clear` (a fresh session has no memory of it), a `resume`d ticket, a ticket only read or mentioned this session. `auto` is unchanged (it already takes the confirm as delegate). The evidence is the session's own context, never inferred from tracker metadata (an issue's author or creation time does not prove this session made it).
 4. Resolve it with its type's engine in **`references/ticket-engines.md`**, **zoom as needed**: fetch the full body of related/closed tickets on demand. If in doubt on a `decision` ticket, run **Grilling** + **Domain vocabulary**. If in doubt on a `build`, **stop and ask** (see the Discuss step): never auto-grill.
-5. Record the resolution: a comment with the answer, `gh issue close`, add the pointer to *Decisions so far* (default path: `node <templates>/trailhead-issue-body.js append --issue <map> --section "Decisions so far" --line "<pointer>"`, which does the fail-safe read-modify-write, the concurrent-edit checks and the secret scan in one call; when the helper is missing, do it by hand per the Fail-safe body rewrites rule in `../_shared/substrate.md`). Then **unblock dependents**: for every ticket this one was blocking, if it was the last open blocker, remove its `trailhead:blocked` label so it graduates onto the frontier.
-6. Add newly-surfaced tickets (create-then-wire, labelling blocked ones `trailhead:blocked`); graduate the fog that became specifiable, clearing the patch from *Not yet specified* (default path: `node <templates>/trailhead-issue-body.js remove --issue <map> --section "Not yet specified" --match "<unique text of the entry>"`, which drops exactly one list entry (no match is a reported no-op, several matches abort); when the helper is missing, do the fail-safe read-modify-write by hand). If the answer reveals a ticket sits beyond the destination, apply the **out-of-scope vs deferred** test (`../_shared/out-of-scope.md`): if it's really deferred on something outside the map, ask the user to route it to a `seed`/`idea`/`todo`; only if it's truly beyond the destination rule it **out of scope** (label, then **drop its native sub-issue edge** to reclaim a slot, then close: the eager drop in `../_shared/substrate-commands.md`, 404-tolerant, references intact) instead of resolving it. If the decision invalidates other parts of the map, update or delete them.
+5. Record the resolution: a comment with the answer (for a `decision`, carrying the `Builds:` line of its engine's **Carry it into build** step, with the build tickets created before the close), `gh issue close`, add the pointer to *Decisions so far* (default path: `node <templates>/trailhead-issue-body.js append --issue <map> --section "Decisions so far" --line "<pointer>"`, which does the fail-safe read-modify-write, the concurrent-edit checks and the secret scan in one call; when the helper is missing, do it by hand per the Fail-safe body rewrites rule in `../_shared/substrate.md`). Then **unblock dependents**: for every ticket this one was blocking, if it was the last open blocker, remove its `trailhead:blocked` label so it graduates onto the frontier.
+6. Add newly-surfaced tickets (create-then-wire, labelling blocked ones `trailhead:blocked`); graduate the fog that became specifiable: re-read **every entry** of *Not yet specified* (not just the ones this ticket names) against the answer, apply the **Ticket or fog** test of charting (`../trailhead-chart/references/charting.md`, Mode 1 step 4) to each, and propose all the entries that pass as **one batch** (title, type, blockers per ticket), created on a yes, so the user never has to dissolve ripe fog one entry per session. For each graduated entry, clear the patch from *Not yet specified* (default path: `node <templates>/trailhead-issue-body.js remove --issue <map> --section "Not yet specified" --match "<unique text of the entry>"`, which drops exactly one list entry (no match is a reported no-op, several matches abort); when the helper is missing, do the fail-safe read-modify-write by hand). If the answer reveals a ticket sits beyond the destination, apply the **out-of-scope vs deferred** test (`../_shared/out-of-scope.md`): if it's really deferred on something outside the map, ask the user to route it to a `seed`/`idea`/`todo`; only if it's truly beyond the destination rule it **out of scope** (label, then **drop its native sub-issue edge** to reclaim a slot, then close: the eager drop in `../_shared/substrate-commands.md`, 404-tolerant, references intact) instead of resolving it. If the decision invalidates other parts of the map, update or delete them.
 7. **Hand off.** Close the session with the **Session handoff** ritual (`../_shared/session-handoff.md`): confirm the ticket is resolved by name, then the scannable **next-step block with `/clear` first** (never the next command without it), naming the next frontier ticket and giving its number (or, when several mutually independent tickets sit on the frontier, presenting them as a **set to choose from** rather than crowning the first-listed), or `/trailhead:map` if the frontier is empty/ambiguous. This holds in any later follow-up too, not only at the moment of resolution. **If this resolution leaves the map exhausted** (no open tickets and no fog left: the destination is reached), say so; but **before closing it out, if *Out of scope* holds any deferred line** (apply the out-of-scope-vs-deferred tells in `../_shared/out-of-scope.md`), **stop and ask the user what to do with each** (a `seed` gated on its trigger, an `idea`, or a `todo`, in this or another map), so nothing wanted-later is lost when the map goes quiet. Only once the deferred items are routed (or the user says leave them), **ask the user whether to close the map issue** now that the destination is reached: `gh issue close` it on a yes (it stays the record), leave it open on a no; never close a map unprompted. Either way **refresh the dashboard** so an exhausted/closed map drops off (a structural event): `node <templates>/trailhead-dashboard.js` regenerates the whole body from the live tracker in one call (`--dry-run` previews it); when the helper is missing, regenerate it by hand per `../_shared/substrate-commands.md`. The `clear` of the work state (`node <templates>/trailhead-work-state.js clear --repo <working-root>`) also removes the session-ticket marker, so the handoff needs just that one call. Maps aren't pinned, so there's no pin to free; the dashboard, codebase, and conventions stay pinned regardless.
 
 ## Work one ticket whole, without splitting: `quick`
@@ -62,7 +73,7 @@ It runs the **full engine** (the `build`/`bug` cycle in `references/ticket-engin
 - **Grill only if needed** (Discuss): never auto-grill; start from Plan and stop to ask only if a blocking ambiguity surfaces, exactly as the `build` Discuss. The user may ask to grill at any time.
 - **Never splits.** If the ticket turns out large, work it whole anyway: that is the point of `quick`. Do not `split` it and do not spin children. (New scope that surfaces mid-work is still captured out, never folded in, see **Scope that surfaces while working a ticket**, served by the capture cluster.)
 - **No map narrative book-keeping.** A whiteboard ticket has no map, so there is no `Decisions so far` update, no fog to graduate, no frontier re-scan. Everything else holds: atomic commits with `Refs: #<n>`, TDD / Code review / Acceptance testing per the cycle, the resolution comment + `gh issue close`, and the **Session handoff** (`../_shared/session-handoff.md`). **Exception, `quick <n>` on a *map* ticket: dependent-unblocking still runs** (remove `trailhead:blocked` from any dependent whose last blocker just closed, **Work the map** step 5 above); skipping it would strand those dependents off the frontier for good. Only the *narrative* book-keeping above and the split are skipped, so prefer `work <n>` for a map ticket that has dependents or belongs in the map record.
-- **Same isolation setup as `work`.** A claimed ticket that carries `trailhead:paused` drops it at the claim, exactly as in **Work the map** step 2. `quick` **writes the `.trailhead/session-ticket` marker at the working root in every isolation mode** (exactly as **Work the map** step 2, so tooling like the statusline shows what's in play; the active-map marker follows the same rule as `work`: a named ticket's map becomes the active map, a whiteboard ticket leaves it alone, see **Active map** in `../_shared/multi-map.md`). Under `auto` it runs the same work-start concurrency ask (with the same `check`/`record` answer reuse) **before any edit** and resolves to current-checkout / worktree / clone by the same rule; under an explicit `isolation: worktree`/`clone` it sets up the ticket's `trailhead/t<n>` workspace before any edit (including the submodule-forces-`clone` escalation and submodule provisioning) and re-checks the claim; under `isolation: none` (or `auto` answered no), the scope-free check applies too. Under `worktree`/`clone` it also runs the same gitignored-file copy (`trailhead-isolation-copy.js --from <main-checkout> --to <working-root>`) right after creating the workspace. `quick` also runs the same commit-msg hook sync at the working root, exactly as **Work the map** step 2. It also writes the work state last, exactly as **Work the map** step 2, with `--map none` for a whiteboard ticket.
+- **Same isolation setup as `work`.** A claimed ticket that carries `trailhead:paused` drops it at the claim, exactly as in **Work the map** step 2. It clears `trailhead:needs-you` the same way (`node <templates>/trailhead-needs-you.js clear --issue <n> --repo <owner/name>`); a failed `clear` is reported to the user in one line but never blocks the claim. `quick` **writes the `.trailhead/session-ticket` marker at the working root in every isolation mode** (exactly as **Work the map** step 2, so tooling like the statusline shows what's in play; the active-map marker follows the same rule as `work`: a named ticket's map becomes the active map, a whiteboard ticket leaves it alone, see **Active map** in `../_shared/multi-map.md`). Under `auto` it runs the same work-start concurrency ask (with the same `check`/`record` answer reuse) **before any edit** and resolves to current-checkout / worktree / clone by the same rule; under an explicit `isolation: worktree`/`clone` it sets up the ticket's `trailhead/t<n>` workspace before any edit (including the submodule-forces-`clone` escalation and submodule provisioning) and re-checks the claim; under `isolation: none` (or `auto` answered no), the scope-free check applies too. Under `worktree`/`clone` it also runs the same gitignored-file copy (`trailhead-isolation-copy.js --from <main-checkout> --to <working-root>`) right after creating the workspace. `quick` also runs the same commit-msg hook sync at the working root, exactly as **Work the map** step 2. It also writes the work state last, exactly as **Work the map** step 2, with `--map none` for a whiteboard ticket.
 - **Refreshes the dashboard at the handoff, not mid-work.** A `quick "<text>"` whiteboard ticket is born and resolved in the **same** session, so its dashboard refresh rides with the session's end, not with ticket creation: **do not refresh right after the ticket exists** (that lands a structural pinned-issue write ahead of the work `quick` exists to just-get-done, and only duplicates the resolution refresh a moment later). Refresh at **Resolve** (the handoff), as a **full regeneration from the live tracker** (`node <templates>/trailhead-dashboard.js`, never a partial patch that leaves other sections knowingly stale), so the whiteboard ticket lands on the dashboard as the session closes. **If the session pauses before Resolve** (`/trailhead:pause`), refresh there instead, so a deliberately-unfinished quick still shows (the read-only renders never rewrite the dashboard body, so nothing else would surface it). `quick <n>` on a *map* ticket does **not** refresh (map ticket progress shows via the native bar). See **The dashboard** and its freshness rule in `../_shared/substrate.md`.
 - **Always size-triages, independent of `config.effort`.** `quick` is the home of the cost-aware path: reaching for `quick` is itself the signal the piece is small, so it runs the **same size triage and ask-to-skip offer defined canonically under effort in `../_shared/configuration-reference.md`** (the same one the `build`/`bug` engine runs, `references/ticket-engines.md`) **every time, at the start before planning, whatever `config.effort` is set to**. `quick` does not wait for `effort: lean`, and an explicit `effort: standard` does not suppress it: `effort` governs `work` / the map cycle, not `quick`. On a trivial/small ticket it surfaces the one consolidated offer (the plan pass, TDD, cross-AI review, the full code review, the goal-backward verify) and goes lean **only on an explicit yes**; on a large ticket there is no offer and the full cycle runs. The correctness spine (atomic `Refs:` commits, tests/criterion, post-commit self-check, Resolve) is never in the offer, whatever the size or the answer.
 

package/plugins/trailhead/skills/trailhead-work/references/auto.md

@@ -1,13 +1,25 @@
 # The autonomous run: `auto`
 
-`auto` runs a map's **frontier autonomously**, ticket by ticket, until a stop condition fires or the frontier is exhausted. It is the one verb that **suspends the one-ticket-per-session rule**: while engaged it chains `build` / `bug` / `task` tickets in a single run. It is invoked explicitly, per run, as `/trailhead:auto [map]`; it **never re-engages on its own**. The run itself is an **autonomous run** (the noun); `auto` is the verb. Everything else about the engine (the substrate, the per-type engines, claiming, the session handoff) is unchanged: `auto` orchestrates the existing cycle, it does not replace it.
+`auto` runs a chosen **run scope** autonomously (one map, the whiteboard, or everything), ticket by ticket, until a stop condition fires or the scope's frontier is exhausted. It is the one verb that **suspends the one-ticket-per-session rule**: while engaged it chains `build` / `bug` / `task` tickets in a single run. It is invoked explicitly, per run, as `/trailhead:auto [map]` (the optional `<n>` is the scope shortcut below); it **never re-engages on its own**. The run itself is an **autonomous run** (the noun); `auto` is the verb. Everything else about the engine (the substrate, the per-type engines, claiming, the session handoff) is unchanged: `auto` orchestrates the existing cycle, it does not replace it.
 
 Load the same shared core the cluster loads (`../../_shared/principles.md`, `substrate.md`, `session-handoff.md`, `configuration.md`, `techniques.md`, `ticket-language.md`), then this file.
 
 ## Preconditions and engagement
-1. **Pick the map** exactly as bare `work` does: the map named in the argument, else the active map (`.trailhead/active-map`); if neither and more than one is open, list them and ask.
-2. **Resume an interrupted ticket first.** Before scanning the frontier, check for **each** ticket you own (assigned to you) on this map that carries `trailhead:paused`, or whose latest checkpoint is a `PAUSED` comment (a ticket paused before the label existed), from a prior interrupted or stuck run. A paused ticket is off the frontier, so this step is the only way a run picks one back up, never the frontier scan. For each one, pick it back up via the **`resume`** engine (`../../_shared/teamwork.md`) and carry it to resolution first, then continue into the loop below. This is how an interrupted run is continued: the human re-invokes `/trailhead:auto`, and auto resumes the in-flight ticket before taking anything new.
-3. **Load config once** from the map's project root, as every session does. `auto` reads no config of its own (there is none, per the decisions).
+1. **Pick the run scope.** The queue is built by `node <templates>/trailhead-auto-queue.js` (self-contained helper, one JSON line on stdout; `<templates>` uses the same three-dir lookup as `trailhead-work-state.js`).
+   - **Read the run record first.** Run `node <templates>/trailhead-auto-run.js read --repo <main-checkout>` before any ask (one JSON line). The record `<main-checkout>/.trailhead/auto-run.json` holds the run's start-up choices (scope, slots, review) and its skip and unmerged lists, so a compaction or a crash does not lose them (`sameSession` is always false on a host with no session id (Codex): there a re-invocation after a crash always gets the resume-or-fresh ask below, the accepted fallback, while a mid-run compaction never does, per the compaction rule in "The run loop"); it is written at the main checkout only and is gitignored (add `.trailhead/auto-run.json` to the repo's `.gitignore` if absent).
+     - `found` with `sameSession: true`: the record is this session's own run seen again after a compaction, so reuse it without asking: no scope, slot or review ask. The reuse is announced in one chat line naming the reused scope, slots and review choice, so the human sees what is being reused. An Esc/Stop interrupt does not clear the record (nothing is written at interrupt time, see "Reporting, interruption, resume"), so re-invoking `/trailhead:auto` in the same session after an Esc reuses the record with its choices, which is expected; to be asked again, re-invoke from a new session (the record then reads as another session's, which gets the resume-or-fresh ask below) or give an explicit `/trailhead:auto <n>` for a different map.
+     - `found` with `sameSession: false`: the record belongs to another session, either a crashed run or **a run still active elsewhere**, which the helper cannot tell apart, so ask once (`AskUserQuestion`, a numbered list without a structured question tool; no delegate option, the human's like the start-up asks) whether to resume that run with its recorded choices (only if no other session is still running it) or to start fresh (`start --replace` after the usual asks). This is the one start-up question a resumed run may pose, and it replaces the three asks. On resume, reload the record's skip and unmerged lists.
+     - An explicit `/trailhead:auto <n>` whose map differs from a found `map:<n>` scope (or a found non-map scope) starts a fresh run: ask as usual, then `start --replace`.
+     - `absent`: ask as below, then run `node <templates>/trailhead-auto-run.js start --repo <main-checkout> --scope <s> --slots <n> --review <r>` right after the last start-up ask and before anything is claimed (`<s>` is `map:<n>`, `whiteboard` or `everything`; `<r>` is the review choice token, or `skip` when the ask was skipped). `corrupt` (reported in one line) is treated like `absent`, but the write is `start --replace`, since a plain `start` would answer `exists` over the corrupt file.
+     - Any `skipped` result (an I/O error on any subcommand) is reported in one chat line and the run continues: a skipped `read` is treated as `absent` (ask, then `start --replace`), and a skipped `start`, `skip`, `unmerged` or `clear` leaves the record stale or missing, nothing else changes. The record is a safety net, not a gate.
+   - `/trailhead:auto <n>` runs map `<n>` **without asking** (the helper's `queue` validates it: a closed or non-map `<n>` is reported, not run).
+   - With no argument, ask **once** via `AskUserQuestion`: one map, the whiteboard, or everything, with the options and their frontier counts from `node <templates>/trailhead-auto-queue.js scopes`. When one map is chosen, then ask which map (skipped when only one map is open; the active map, if open, is the recommended option). This start-up ask is the human's: the scope is not advisory, so there is no delegate option, and it is asked before anything is claimed. On a host without a structured question tool, the same options go as a numbered list.
+   - **Parallel slots: 1, 2, 3 or 4.** Right after the run scope, ask **once** via `AskUserQuestion` how many tickets the run keeps in flight at once: 1, 2, 3 or 4, with **2 proposed** as the Recommended first option (a numbered list on a host without a structured question tool). `/trailhead:auto <n>` skips only the scope ask: it **still asks the slot count**. Like the scope, this ask is the human's: there is no delegate option, and it is asked before anything is claimed. With **1 slot** the run is the sequential run in the current checkout; above 1 it follows "Parallel slots" below.
+   - **External review rounds.** Right after the slot ask, run `node <templates>/trailhead-plan-review-rounds.js ask --repo <project-root>` (add `--host codex` on Codex; one JSON line). Any non-empty `warnings` (an `unknown` reviewer name, a bad `plan_review.rounds`) is printed in chat first, before the ask or the skip. On `skip` (plan review off, or no independent reviewer CLI installed, the host's own CLI not counting) there is no ask. On `ask`, pose one `AskUserQuestion` with the helper's `options` (at most four, **as in config** Recommended first; the full five as a numbered list, the helper's `fallback`, on a host without a structured question tool): as in config, 1, 2, 3, or until convergence (stop on a round with no progress, hard ceiling 5). On `error` (an unreadable or invalid config, a failed probe) the run reports it and hands back before any claim, like a queue helper error. Like the scope and the slot count, this ask is the human's: there is no delegate option, and it is asked before any claim, also under `/trailhead:auto <n>`. The choice holds for every `build` ticket of the run (each slot's plan step included) and overrides `plan_review.rounds` for that run; after each review round the plan step calls `node <templates>/trailhead-plan-review-rounds.js round --choice <choice> --configured <n> --history <file>` (see `../../_shared/techniques/plan-review.md`).
+   - **Order.** Under everything the run works one map at a time by ascending map number, the whiteboard last; inside a scope the oldest workable ticket first (lowest number), blockers respected through the frontier (`trailhead:blocked` tickets are never queued). The queue also skips every `trailhead:needs-you` ticket (one the run parked for the human, see "Parking a ticket for the human" below); the run only ever takes `next` and re-queries with `--skip` as it marks tickets needs-you or stops on them.
+   - **A helper error stops the run** (non-zero exit, `status: error`, unparseable output, including a truncated read): before any claim, the run reports it and hands back; mid-run, it stops taking new tickets and goes to the run-end summary. It never treats an error as a drained scope. Tickets the helper lists under `drift` (on more than one open map) are never worked and are listed in the run-end summary; `drift` can include a paused ticket you own, which is then neither resumed nor claimed, so the summary names it as your own paused work to fix by hand.
+2. **Resume an interrupted ticket first.** Before taking anything new, resume **each** ticket you own that carries `trailhead:paused` **within the scope** (the `resume` lists of `queue`'s groups), in queue order, plus any owned ticket in the scope whose latest checkpoint is a `PAUSED` comment (a ticket paused before the label existed), from a prior interrupted or stuck run. A paused ticket is off the frontier, so this step is the only way a run picks one back up, never the frontier scan. For each one, pick it back up via the **`resume`** engine (`../../_shared/teamwork.md`) and carry it to resolution first, then continue into the loop below. An owned, open, in-scope ticket named by a leftover work state file (`node <templates>/trailhead-work-state.js`) whose work state has `auto: true` (an interactive session writes `auto: false`, and a handback resets it, so `auto: true` left behind is the crash signature) and is not `trailhead:paused`, and whose latest checkpoint is not a `PAUSED` comment (no `PAUSED` at all, or engine comments after the last one, as for a ticket interrupted twice): the in-flight ticket of a crash or of a host interrupt, which leave the same trace, is resumed first too, from its latest engine comment. **Reconstruct the missing checkpoint first.** Before the normal resume, the run posts a `PAUSED` checkpoint comment on that ticket (the contents of the pause checkpoint in `../../_shared/teamwork.md`, "Pausing & resuming": what is done, the exact next step, the local state, naming the slot workspace path and branch when it has one) that notes it was reconstructed at resume after an interrupt or crash, then adds `trailhead:paused` (after the comment, so a failed comment never leaves a label without a checkpoint), and then resumes the ticket through the `resume` engine, which drops the label. It is idempotent: reconstruction is skipped only when the latest checkpoint is already a `PAUSED` comment or the label is present, so no second checkpoint is posted. Reconstruction happens when the ticket is actually resumed (when it takes a slot), so an extra waiting for a free slot is untouched until then. A slot ticket whose work state step is `resolve` is exempt from reconstruction: it is re-driven through Resolve directly (below). **Known limit:** a crash in the instant between the claim and the work-state write leaves the ticket claimed with no local trace; it stays visible as your own open ticket and is not resumed automatically (resuming every owned open ticket would grab work done by hand in another session). **Where it resumes.** Also run `node <templates>/trailhead-auto-slot.js list --repo <main-checkout>` (the slot workspaces, worktrees and sibling clones, each with its own work state). A ticket that meets the conditions above (the resume conditions are unchanged: owned, in scope, not needs-you, and paused / latest checkpoint `PAUSED`, or crashed with `auto: true` and a latest checkpoint that is not a `PAUSED` comment) and that has a slot workspace (its own work state found there, or the path its `PAUSED` checkpoint names) is resumed **in that workspace**, whatever the slot count chosen for this run. A workspace whose ticket fails the conditions (a manual branch, a needs-you ticket) is left alone. Resumed tickets take slots first; extras wait for a free slot. **An interrupted merge first.** Before resuming anything, run `node <templates>/trailhead-auto-merge.js recover --repo <main-checkout>`: `clean` means nothing was under way; `aborted` (it names the ticket) means a run's merge was cut short and has been aborted, so that ticket's merge is retried (its Resolve re-runs from the preflight); `foreign` (a human's merge, a rebase) hands the run back without touching it. **A slot ticket whose work state step is `resolve`** is re-driven through Resolve idempotently, whatever its branch state: `merge` answers `already-merged` when the merge landed before a crash, and every later Resolve move checks before acting (the resolution comment is posted only if none exists, the close only if the ticket is open, the `Decisions so far` pointer appended only if absent, and `trailhead-unblock.js` and `remove` are idempotent). This is how an interrupted run is continued: the human re-invokes `/trailhead:auto`, and auto resumes the in-flight ticket before taking anything new.
+3. **Load config once** from the project root, as every session does. `auto` reads no config of its own (there is none, per the decisions).
 
 ## The safety rail (always on, checked FIRST)
 Independent of and **above** the advisory boundary below, `auto` **never performs an irreversible or outward-facing action without an explicit human go-ahead**. Before any automatic choice handling, check the rail. The rail stops on:
@@ -17,42 +29,78 @@ Independent of and **above** the advisory boundary below, `auto` **never perform
 - a **delete / force** (`git push --force`, `rm -rf` of tracked work, a force-delete of a branch or remote ref);
 - any other **outward-facing** action (posting outside the tracker, calling an external service that mutates state).
 
-When the next step of a ticket would trip the rail, auto **sets that ticket aside and continues** (it does not perform the action and does not block the whole run): it hands the outward action back to the human, recorded in the run-end summary. **Atomic local commits to `main` are not rail-tripping**: they are the normal Execute and continue automatically. The rail is **hardcoded**, not a disableable toggle.
+When the next step of a ticket would trip the rail, auto **marks that ticket needs-you and continues** (it does not perform the action and does not block the whole run): it hands the outward action back to the human with a `NEEDS YOU` comment naming it, recorded in the run-end summary. **Atomic local commits to `main` are not rail-tripping**: they are the normal Execute and continue automatically. **A local merge of a verified slot branch into the trunk is not rail-tripping either** (like atomic local commits, see "Integration under `git: main`"); the push stays the human's. The rail is **hardcoded**, not a disableable toggle.
 
-**Under a `git: pr` convention the rail bites at integration (by design).** When the repo's `trailhead:conventions` sets `git: pr` (or a ticket works in an `isolation: worktree`/`clone` branch), finishing a `build`/`bug` ticket ends in a **branch push + opening a PR**, both rail actions. So on such a repo auto drives each ticket through its **whole local cycle** (discuss / plan / execute / verify, atomic commits on the ticket's branch) and then **sets the push / PR / integration step aside for the human**, listing every ready-to-integrate branch in the run-end summary. The dependents of a ticket whose PR is not yet merged stay blocked until the human integrates, so a run on a `git: pr` repo drains less of the frontier per invocation than one on `git: main` (where a resolved ticket closes and unblocks immediately). This is the rail working as intended, not a failure; auto is simply most productive under `git: main`. **The stale-base preflight never auto-resolves.** A `conflict`, `trunk-diverged`, `unverified`, `dirty` or `sync-failed` status, or a failing preflight check, is a stop for that ticket (set aside for the human with the status named in the run-end summary); auto never resolves a merge conflict itself. **Isolation under a run:** `isolation: auto` (the default) resolves to the **current checkout** during an autonomous run without asking (the run is sequential, one ticket at a time, so there is no concurrency and no process question to put to the human); an explicit `worktree`/`clone` still applies as the conventions set it, and its branch push/PR is a rail action set aside for the human exactly as above.
+**Under a `git: pr` convention the rail bites at integration (by design).** When the repo's `trailhead:conventions` sets `git: pr` (or a ticket works in an `isolation: worktree`/`clone` branch), finishing a `build`/`bug` ticket ends in a **branch push + opening a PR**, both rail actions. So on such a repo auto drives each ticket through its **whole local cycle** (discuss / plan / execute / verify, atomic commits on the ticket's branch) and then **marks the ticket needs-you for the push / PR / integration step**, listing every ready-to-integrate branch in the run-end summary. The dependents of a ticket whose PR is not yet merged stay blocked until the human integrates, so a run on a `git: pr` repo drains less of the frontier per invocation than one on `git: main` (where a resolved ticket closes and unblocks immediately). This is the rail working as intended, not a failure; auto is simply most productive under `git: main`. **The stale-base preflight never auto-resolves.** A `conflict`, `trunk-diverged`, `unverified`, `dirty` or `sync-failed` status, or a failing preflight check, is a stop for that ticket (marked needs-you with the status named in the comment and the run-end summary); auto never resolves a merge conflict itself. **Isolation under a run:** with **1 slot** (the sequential run), `isolation: auto` (the default) and `none` resolve to the **current checkout** during an autonomous run without asking (one ticket at a time, so there is no concurrency and no process question to put to the human); an explicit `worktree`/`clone` still applies as the conventions set it, and its branch push/PR is a rail action marked needs-you exactly as above. **Above 1 slot** the run gives each ticket **a worktree whatever `isolation:` says** (`none` and `auto` included), `clone` stays `clone`, and a superrepo (a `.gitmodules` declaring a submodule) escalates to `clone`; see "Parallel slots".
 
 ## The advisory boundary (the `choices.md` one-line test, no confirm gate)
 Wherever the engine would put a **forced choice** to the human, apply the one-line test in `../../_shared/choices.md`:
-- **Advisory / process choice** (the test's Positive side: the delegate option is offered): `auto` **takes the delegate option WITHOUT its confirm gate**. It picks the best option with the same honest rationale delegate would state, and proceeds. This is the whole of auto's autonomy: "take delegate, skip the confirm." No new confidence threshold, no separate allowlist, so the boundary can never drift from the tested convention.
-- **Human-necessary decision** (the test's Negative side: delegate is withheld): a `decision`-ticket convergence, a destination or scope change, an out-of-scope ruling, routing a deferred line to seed/idea/todo, closing an exhausted map, a claim collision. `auto` **sets that ticket aside and continues** (it does not decide). Likewise **fog** that needs dissolving into tickets (a human grilling act) is set aside.
+- **Advisory / process choice** (the test's Positive side: the delegate option is offered): `auto` **takes the delegate option WITHOUT its confirm gate**. It picks the best option with the same honest rationale delegate would state, stress-tested first per **Stress-test the pick before offering it** in `../../_shared/choices.md` (no human checks it here, so the pass is never skipped on a non-trivial choice), records the pick with its `Weak point:` line in the ticket comment of the step the choice belongs to (the run-end summary when it belongs to no ticket), and proceeds. This is the whole of auto's autonomy: "take delegate, skip the confirm." No new confidence threshold, no separate allowlist, so the boundary can never drift from the tested convention.
+- **Human-necessary decision** (the test's Negative side: delegate is withheld): a `decision`-ticket convergence, a destination or scope change, an out-of-scope ruling, routing a deferred line to seed/idea/todo, closing an exhausted map, a claim collision. `auto` **marks that ticket needs-you and continues** (it does not decide). Likewise **fog** that needs dissolving into tickets (a human grilling act) is marked needs-you.
 
-**The Acceptance testing drive-mode ask (AI-driven, human-driven, or skip) is advisory too, and is taken without the confirm gate**: `auto` picks AI-driven whenever any step is agent-performable; it never fakes a human-only step, so when the UAT includes one it leaves that step incomplete and sets the ticket aside, listing the human-only steps in the run-end summary. `auto` never picks skip (waiving acceptance is the human's call). **UAT setup in `auto`** runs the configured `uat.setup` only: no probe, no proposal, no save offer. A failing step (or an `invalid` config) sets the ticket aside and lists the failure in the run-end summary, like a human-only UAT step. Full protocol in `../../_shared/techniques/acceptance-testing.md`.
+**The Acceptance testing drive-mode ask (AI-driven, human-driven, or skip) is advisory too, and is taken without the confirm gate**: `auto` picks AI-driven whenever any step is agent-performable, runs those steps and records them in the round's `VERIFY`, and never fakes a human-only step. A failing agent-performable step is still an acceptance finding (fix it or open a `bug`), never waved through. `auto` never picks skip (waiving acceptance is the human's call). **Human-only UAT steps no longer stall the ticket.** When human-only steps remain (or the whole UAT is human-only), the run takes the Pending-UAT guard's option (b) as its own choice: the run itself is the human's go-ahead, decided in the map's design ticket, and it is the one exception to "never open a UAT ticket without asking". First `node <templates>/trailhead-uat-followup.js find --parent <n> --repo <owner/name>`; when `reuse` names an open follow-up, reuse it and open nothing (a resume never opens a second one). Otherwise open one (a `task` on the same map, or on the whiteboard for a whiteboard ticket, or a `trailhead:seed` when the human steps are gated on an external trigger, per the routing in `acceptance-testing.md`), carrying `trailhead:uat`, the `UAT of: [<parent name>](<parent url>)` line and the human-only steps as the full numbered checklist. THEN Resolve the parent (its resolution comment names the follow-up), unblock dependents and continue. Only an open follow-up is reused (the lowest-numbered when several); closed ones never count; the run never closes duplicates. find-then-create is not atomic, which is safe because the run claims the parent before its UAT and one orchestrator makes every tracker call of the run, so two follow-ups are never opened at once. **A helper error is not a "none found"**: the run does not open a follow-up blind, it marks the parent needs-you (naming the helper error) and continues. **UAT setup in `auto`** runs the configured `uat.setup` only: no probe, no proposal, no save offer. A failing setup (or an `invalid` config) marks the ticket needs-you and lists the failure in the run-end summary. Full protocol in `../../_shared/techniques/acceptance-testing.md`.
 
-**A human-only step is also a stop, even though it is not a choice.** A **HITL `task`** whose next step is a checklist only the human can perform (manual plumbing the agent cannot do: signing up for a service, provisioning access, a physical action) is neither a forced choice nor fog nor a rail action, so the tests above do not catch it, but auto still **cannot execute it alone**. Auto **sets such a ticket aside and continues**, handing the precise checklist to the human in the run-end summary; it never fabricates the human's part. An **AFK `task`** the agent can drive alone chains normally.
+**A human-only step is also a stop, even though it is not a choice.** A **HITL `task`** whose next step is a checklist only the human can perform (manual plumbing the agent cannot do: signing up for a service, provisioning access, a physical action) is neither a forced choice nor fog nor a rail action, so the tests above do not catch it, but auto still **cannot execute it alone**. Auto **marks such a ticket needs-you and continues**, handing the precise checklist to the human in the `NEEDS YOU` comment and the run-end summary; it never fabricates the human's part. A UAT follow-up (`trailhead:uat`) whose remaining steps are human-only is exactly such a HITL `task`: the run never works it and it joins the skip list. An **AFK `task`** the agent can drive alone chains normally.
 
 ## The run loop (a fixpoint, not one pass)
-Repeat until a full scan finds nothing auto-workable left:
-1. **Scan the frontier** for this map (the normal frontier query, scoped to the map). Skip any ticket whose immediate next step is a human-necessary decision, fog, a HITL `task`'s human-only step, or a rail action (those are set aside for the human).
-2. **Take the next auto-workable ticket**, claim it, and resolve it with its type's engine in `ticket-engines.md`. The types the agent can drive alone chain automatically: `build`, `bug`, an **AFK** `task`, and an AFK `research` (already exempt from one-ticket-per-session, so it needs no special suspension). Set aside a `decision` or `prototype` that needs the human, and a **HITL** `task` whose next step is a human-only checklist. The per-ticket engine runs its **normal configured cycle** (TDD, Code review, Goal-backward verification per config): auto is **orthogonal to `effort` and `models.*`** and changes neither. The run loop is orchestrated by the session model.
-3. **On resolution**, do the normal Resolve book-keeping, then **unblock dependents** (remove `trailhead:blocked` from any dependent whose last blocker just closed) and **re-scan**. A ticket that graduates onto the frontier this way is picked up in a later pass: this is why the loop is a fixpoint, not a single sweep.
+Repeat until the queue's `next` is null (nothing auto-workable left in the scope):
+1. **Query the queue**: `node <templates>/trailhead-auto-queue.js queue --scope <scope> --skip <csv>` with the run's skip list (the tickets already marked needs-you or stopped on this run), and take `next` (the lowest-numbered ticket of the first group that still has one). Do not take a ticket whose immediate next step is a human-necessary decision, fog, a HITL `task`'s human-only step, or a rail action (those are marked needs-you for the human).
+2. **Take `next`** if it is auto-workable, claim it, and resolve it with its type's engine in `ticket-engines.md`. The types the agent can drive alone chain automatically: `build`, `bug`, an **AFK** `task`, and an AFK `research` (already exempt from one-ticket-per-session, so it needs no special suspension). Mark needs-you a `decision` or `prototype` that needs the human, a **HITL** `task` whose next step is a human-only checklist, and a UAT follow-up (`trailhead:uat`) whose remaining steps are human-only: a ticket judged not auto-workable joins the skip list (and is marked needs-you for the human) and the loop re-queries, so the run leaves a map only once every frontier ticket of that map is resolved or skipped. With 1 slot the active-map marker follows the map in play (above 1 no slot writes it, see "Parallel slots"); a whiteboard ticket writes work state with `--map none` and leaves the marker alone. The per-ticket engine runs its **normal configured cycle** (TDD, Code review, Goal-backward verification per config): auto is **orthogonal to `effort` and `models.*`** and changes neither. The run loop is orchestrated by the session model.
+3. **On resolution**, do the normal Resolve book-keeping, then **unblock dependents** with `node <templates>/trailhead-unblock.js --issue <n> --repo <owner/name>` (it removes `trailhead:blocked` from any dependent whose last blocker just closed) and **re-query**. A ticket that graduates onto the frontier this way comes back through the next `queue`, so a map drains before the run moves on to the next one: this is why the loop is a fixpoint, not a single sweep.
 4. **Emit a live chat progress line** as the run advances (below).
 
-The run ends only when a full scan finds **nothing auto-workable** (the auto-workable frontier is exhausted), or on **human interrupt** (below). There is **no cap** on tickets, wall-clock, or tokens: a human wall never ends the run, it only shrinks the auto-workable set (auto **drains** rather than halts).
+**After a context compaction mid-run, whatever the slot count** (a sequential run included), the orchestrator re-reads the record with `node <templates>/trailhead-auto-run.js read --repo <main-checkout>` and reuses its scope, slots, review choice, skip and unmerged lists whatever `sameSession` says, without asking. It knows it is mid-run from its own context (the compaction summary of an active run). The `sameSession` ask applies only at engagement, that is, a fresh `/trailhead:auto` invocation. With slots it also rebuilds the slot table (see "Parallel slots").
+
+**Persisting the skip list.** Every time a ticket joins the run's skip list (marked needs-you, paused by the failure budget, stopped on), run `node <templates>/trailhead-auto-run.js skip --repo <main-checkout> --ticket <n>` (idempotent), so the list survives a compaction.
+
+The run ends only when the queue finds **nothing auto-workable** (the auto-workable frontier is exhausted), or on **human interrupt** (below). There is **no cap** on tickets, wall-clock, or tokens: a human wall never ends the run, it only shrinks the auto-workable set (auto **drains** rather than halts).
+
+## Parallel slots
+With more than one slot the run keeps up to that many tickets in flight at once, each in its own workspace on a `trailhead/t<n>` branch. The run stays **one orchestrating session**: the only one that talks to the tracker for the run, claims, and fills slots.
+
+- **Background dispatch, never inline.** Every engine step that has a technique agent (plan, execute, fix, debug, code review, goal-backward verify) is dispatched as a **background subagent** with the slot's **absolute workspace path as its working root**, even when its model equals the session model: with more than one slot nothing runs inline, or one slot would freeze the others. The orchestrator advances whichever slot's step finished: that slot's tracker moves (comments, labels, close), its preflight and its acceptance steps, then it dispatches the slot's next step.
+- **Filling a free slot.** A slot frees when its ticket resolves, is parked needs-you, or is paused by the failure budget. The orchestrator then runs `queue --scope <scope> --skip <csv>` with the run's skip list **plus every in-flight ticket**, and takes `next`. Tickets of different maps can therefore run together while oldest-first holds. Under the plan-time coupling check (advisory), worktrees isolate the tickets and a conflict surfaces at integration, not before.
+- **Opening a slot.** At claim, capture the trunk SHA (the local trunk HEAD at that moment), then run `node <templates>/trailhead-auto-slot.js open --repo <main-checkout> --ticket <n> --base <sha>`. The workspace is `<parent of the main checkout>/<repo>-t<n>` on `trailhead/t<n>`, created at exactly `--base`. The output carries a `kind` (`worktree` or `clone`). The status is `created`, `reentered` (the branch already has a workspace: a worktree, or an existing clone at the slot path; a `reentered` clone is used as is, nothing is cloned over it) or `reattached` (the branch existed without a worktree). `error` is a helper error for that ticket: the slot path exists and is not a checkout of the branch, the base does not resolve, or the branch's worktree is a stale worktree (git still lists it but its directory was deleted by hand; the reason names it and says to run `git worktree prune`, which the helper never does itself). The ticket is not worked: park it needs-you with `trailhead-needs-you.js park` naming the reason, and it joins the skip list and the run-end summary. `list` reports a stale worktree as a warning, not as a slot. On `clone-required` (a superrepo, and only when the slot path does not exist yet) nothing was created: set the clone up at the same sibling path per the `clone` setup in `../../_shared/teamwork.md` (`git clone --recurse-submodules`, or the folder copy, git-independence checked), then `git -C <clone> checkout -b trailhead/t<n> <base>` and `git -C <clone> submodule update --init --recursive`, so a clone slot carries the same path, branch and base as a worktree slot (and `list` finds it).
+- **Per-workspace state.** Right after `open`, write the slot's work state: `env -u CLAUDE_CODE_SESSION_ID node <templates>/trailhead-work-state.js set --repo <workspace> --map <map|none> ... --auto true --auto-done <n>`, and the `.trailhead/session-ticket` marker at the workspace root; only then the `trailhead-isolation-copy.js` copy and the commit-msg sync (so a crash after setup still leaves the `auto: true` resume signal; the gap between the claim and `open` stays the known limit). The commit-msg hook (shared `.git/hooks`) reads the marker of the workspace it commits in. **The slot work states are sessionless on every write**: every `set` on a slot workspace (the first one, each per-step update with `--auto true --auto-done <n>`, and the run-end reset) uses the same `env -u CLAUDE_CODE_SESSION_ID` form (`CLAUDE_CODE_SESSION_ID` unset for that call), because one session-bearing write would let the mod adopt that slot as the ticket in play: the mod's prompt hint adopts only a state naming this session, so several slot states of one session would be ambiguous and never pick one slot as "the ticket in play"; crash detection keys on `auto: true`, not on the session.
+- **Active map.** A slot never writes the `.trailhead/active-map` marker of the main checkout (slots of different maps would overwrite each other). Each slot's map lives in its own work state (`--map`) and in the orchestrator's slot table, and every map-scoped call (frontier `queue`, `Decisions so far`, unblock) names the map explicitly. With 1 slot the marker follows the map in play, as before.
+- **The slot table.** The orchestrator keeps the table (ticket, map, workspace, branch, current step) in its own context. After a context compaction it rebuilds the slot table from `trailhead-auto-slot.js list` and the slot work states, on top of the run's choices and lists restored by the general compaction rule in "The run loop".
+- **Integration under `git: main`.** After Verify passes in a worktree slot, the orchestrator merges the slot branch into the local trunk (never a push), one merge at a time. First the Resolve stale-base preflight, unchanged from `../../_shared/teamwork.md`: the main checkout `--sync`, then the ticket branch `--sync` against it, with a re-review when a rebase rewrote the ticket's commits. Then `node <templates>/trailhead-auto-merge.js merge --repo <main-checkout> --ticket <n>` (one JSON line; it merges `trailhead/t<n>` into the trunk as a fast-forward when possible, else as a merge commit `chore(auto): merge trailhead/t<n>` carrying `Refs: #<n>`; another ticket's `.trailhead/session-ticket` marker in the main checkout never blocks it: a fast-forward creates no commit, and a true merge commit skips the commit-msg hook with `--no-verify` only when the marker names another ticket). The result decides the move:
+  - `merged` or `already-merged`: post the resolution comment naming the merge, close the ticket, append the `Decisions so far` pointer, **unblock its dependents** with `node <templates>/trailhead-unblock.js --issue <n> --repo <owner/name>`, then `node <templates>/trailhead-auto-merge.js remove --repo <main-checkout> --ticket <n>` and free the slot. Dependents that graduate onto the frontier open their slot at the new trunk SHA. The `behind` list in the result names the other slots now behind the trunk (informational).
+  - `conflict`: the branch stays **separate** and the workspace is kept (the helper already aborted the merge, the trunk is untouched). Right after the abort, **before any tracker call**, persist the branch: `node <templates>/trailhead-auto-run.js unmerged --repo <main-checkout> --ticket <n> --branch trailhead/t<n> --file <path> [--file <path> ...]` (one `--file` per conflicting path). Next, right after the abort, before parking, record the branch on the **merge ticket**: `node <templates>/trailhead-merge-ticket.js add --scope <map-<n>|whiteboard> --ticket <n> --file <path> [--file <path> ...] --workspace <path> --repo <owner/name>` (one `--file` per path in the merge result's `conflicts`; `--scope` is the ticket's map, or `whiteboard` for a loose ticket). Then park the ticket needs-you: the park reason names the branch, the workspace, the conflicting files and the merge ticket. Then, after the merge-ticket `add` succeeds, repeat the same `unmerged` call with `--merge-ticket <n>` (an upsert). A crash or a failed `add` in between still leaves the branch on the persisted unmerged list, with no merge ticket, which the run-end `add` retry reads. Add the branch to the run's in-memory **unmerged list** (branch, files), which the run-end summary reads, and keep the merge tickets the run touched (per scope) for the summary. The ticket stays open, so its dependents stay blocked. A helper error is reported in chat and named in the park reason; the branch stays on the unmerged list and the `add` is retried once at run end, and a retry that still fails is listed in the summary as no merge ticket written (never read an error as a success).
+  - `dirty`, `not-on-trunk`, `slot-dirty`, `in-progress` and `merge-failed`: park the ticket needs-you naming the status; the branch and the workspace are kept.
+  - `error`: hand back at once, with no further merge (an `error` can mean the main checkout was left mid-merge).
+  **The merge ticket.** Each unmerged branch is recorded on one merge ticket per map (or the whiteboard), opened at the first unmerged branch of that scope and updated after each later one, right when the `conflict` arises, never only at run end. It is a needs-you `task` (labels `trailhead:ticket`, `trailhead:task`, `trailhead:needs-you` and the scope label; a sub-issue of the map), so no run takes it, and it is closed by the human once every listed branch is merged or dropped. It lists each branch with its ticket, workspace and conflicting files, and suggests a merge order (oldest ticket first). The helper finds an existing one itself and reuses it; a map or the whiteboard with no unmerged branch gets no merge ticket. Held branches (`git: pr`, clone slots) and the other parked merge statuses are not on the unmerged list and open none.
+  Other in-flight slots are never rebased mid-step: each picks up the new trunk at its next stale-base preflight (Verify start, Resolve), which for an unpublished ticket branch syncs onto the local trunk once it is strictly ahead of `origin`.
+- **A `remove` failure after the close is a cleanup error, not a park.** Any `remove` result other than `removed` (`error`, `not-merged`, `kept`) comes after the ticket is already resolved: never park or reopen it; free the slot, list the workspace and the branch in the run-end summary for the human to remove, and a later `remove` retry finishes it (`remove` is idempotent).
+- **Integration stays held under `git: pr`, and for a clone slot.** Under `git: pr`, or for a clone slot (a superrepo: publishing a gitlink is a rail action), the run does not merge. A slot ticket that completes its whole local cycle on its branch is parked needs-you for integration with `node <templates>/trailhead-needs-you.js park`, the reason naming its branch and its workspace path; the branch and the workspace are **kept**, and both are listed in the run-end summary.
+
+## Parking a ticket for the human (the needs-you mark)
+Every path above that hands a ticket to the human parks it **at once** with `node <templates>/trailhead-needs-you.js park --issue <n> --reason <text> --repo <owner/name>` (see `../../_shared/substrate-commands.md`): a human-necessary decision, fog, a HITL human-only checklist, a rail action, a stale-base stop, a failing UAT setup, a helper error on the UAT follow-up find, and a surviving blocking review concern (the same call). The trigger is the plan review not converging: when `trailhead-plan-review-rounds.js round` returns `exhausted`, `no-progress` or `ceiling`, the blocking concerns survive the rounds, and the ticket is parked after the `PLAN` and `PLAN-REVIEW` comments are posted, the reason quoting the full `text` of each concern in `surviving` (never just its key); the ticket joins the skip list (its slot frees) and the run continues. The helper secret-scans the reason, writes the `NEEDS YOU` comment (first line `NEEDS YOU`, then what the human must do), unassigns the run and adds `trailhead:needs-you` last. There are no new parking triggers: only the paths auto already hands back. The ticket joins the run's skip list.
+
+A needs-you ticket is a mark for autonomous runs only: it stays on the frontier and the map for the human, and `/trailhead:work` still offers it. The queue skips it, and a re-invocation of `/trailhead:auto` does not reconsider it; it comes back to a run only after the human clears the label (a `work`/`quick` claim clears it, or `gh issue edit <n> --remove-label trailhead:needs-you`). A helper error from `park` is reported in chat and the ticket still joins the skip list for this run; never read it as a success.
 
 ## Per-ticket failure budget (a ticket that will not verify)
 On the green path a ticket resolves and the loop continues. On a **Verify failure**, auto does not hand back at the would-be checkpoint. Instead it **extends past the engine's normal bounded fix-and-re-review rounds**, taking the advisory "which fix" sub-choice as **delegate** (the accept / resolve-anyway decision still stays the human's, so at true exhaustion it does not silently resolve a red ticket). The per-ticket **failure budget** is: a **no-progress rule** (stop iterating once a round makes no measurable progress) **plus a hardcoded ceiling of 3 extra rounds** (tunable only in code; there is no config surface). At budget exhaustion, still red, auto **pauses the stuck ticket keeping its claim** (a `PAUSED` checkpoint) and **skips to the next frontier ticket** (skip-and-continue, not stop-the-run). A single stuck ticket never ends the run; its dependents stay blocked naturally. Skipped / stuck tickets are reported at run end. The accepted cost is stranded dependents and accumulated paused tickets.
 
+## Records as it goes
+Each record the human needs is written on the tracker **when it arises**, never held for the run end: the per-ticket engine comments and resolution, the UAT follow-up (opened before the parent closes), the merge ticket (opened at the first unmerged branch of a scope and updated after each later one), the `PAUSED` checkpoint of a stuck ticket (written at budget exhaustion), and a `NEEDS YOU` comment on every needs-you ticket naming what the human must do (written the moment it is marked: for a rail action, the action to authorise; for a stale-base stop, the status), unless the ticket's latest `NEEDS YOU` comment already names the same action (the helper posts nothing new for it); a UAT follow-up (`trailhead:uat`) is exempt, since its own checklist is already the record. The chat progress line is a mirror, not a record. The run-end summary therefore only summarises records that already exist.
+
+**Hard stop.** Every record that has arisen is already on the tracker (engine comments as each step posts them, atomic commits, the UAT follow-up, `NEEDS YOU` comments, `PAUSED` checkpoints), so a hard stop (closed terminal, crash) loses nothing that has arisen. The in-flight ticket of a crash has no `PAUSED` checkpoint, but it keeps its claim, its posted comments, its commits and the leftover work state (`auto: true`), which engagement step 2 resumes from.
+
 ## Reporting, interruption, resume
-- **In-run reporting = both.** The per-ticket engine comments (`DISCUSS`/`PLAN`/`VERIFY`/resolution, etc.) land on the Issues **as usual**, and auto **also emits a live chat progress line** as it advances (e.g. which ticket it just resolved and what it is taking next), so the human can watch a run without reading the tracker.
-- **Interruption = the host interrupt (Stop/Esc), the only mid-run halt.** There is no separate "stop after this ticket". Atomic commits plus ticket-boundary checkpoints make interruption **safe by construction**: on interrupt the in-flight ticket **keeps its claim and gets a `PAUSED` checkpoint** (per `../../_shared/teamwork.md`), cleanly resumable.
-- **Resume = the human re-invokes.** `auto` never resumes on its own. The human runs `/trailhead:auto` again; engagement step 2 above picks the interrupted ticket back up via `/trailhead:resume` before scanning, and the run's earlier set-aside (human-necessary) tickets are back on the frontier for this fresh run to reconsider. Paused or stuck tickets are not: they stay off the frontier until resumed (owned ones through step 2, the rest by `/trailhead:resume`).
+- **In-run reporting = both.** The per-ticket engine comments (`DISCUSS`/`PLAN`/`VERIFY`/resolution, etc.) land on the Issues **as usual**, and auto **also emits a live chat progress line** as it advances (e.g. which ticket it just resolved and what it is taking next), so the human can watch a run without reading the tracker. With parallel slots the line names the tickets in the slots.
+- **Interruption = the host interrupt (Stop/Esc), the only mid-run halt.** There is no separate "stop after this ticket". Atomic commits plus ticket-boundary checkpoints make interruption **safe by construction**: the host ends the turn at once and fires no hook, so **nothing is written at interrupt time**: no `PAUSED` checkpoint, no run-record clear, no run-end summary. On disk an Esc is the same as a crash: the in-flight tickets (every slot ticket, with parallel slots) keep their claim, their posted comments and commits, the leftover run record and their `auto: true` work states, which are the signature of both an Esc and a crash. The next `/trailhead:auto` writes the missing `PAUSED` checkpoint at resume (engagement step 2, naming the slot workspace path and branch) and resumes the ticket. A hard stop (closed terminal, crash) is covered by "Records as it goes": nothing that arose is lost, and the in-flight ticket is resumed from its work state (with slots, each slot's own work state survives in its workspace). `PAUSED` checkpoints the run itself decides (the failure budget, a stuck ticket) are still written when they arise.
+- **Resume = the human re-invokes.** `auto` never resumes on its own. The human runs `/trailhead:auto` again; engagement step 2 above picks the interrupted ticket back up via `/trailhead:resume` before scanning, and the run's earlier needs-you tickets are not reconsidered: they stay marked, and the fresh run skips them until the human clears the label (a `work`/`quick` claim clears it). Paused or stuck tickets are not: they stay off the frontier until resumed (owned ones through step 2, the rest by `/trailhead:resume`).
 
 ## Run-end summary (every terminus)
-Whatever ends the run (frontier drained or human interrupt), auto emits **one run-end summary**, in **two places**: a **chat block** for the human, and the **same summary posted as a comment on the map issue** (the durable tracker record). The summary states:
-- **why it stopped** (auto-workable frontier exhausted, or human interrupt);
+Whatever ends the run by itself (frontier drained), auto emits **one run-end summary**, **in full in chat** for the human, as a summary of records already on the tracker, never the only record (each line links the record it summarises: the ticket, its UAT follow-up, its checkpoint or `NEEDS YOU` comment). It is posted to the tracker too: under a one-map scope, the summary is posted as a comment on the map issue; under everything, each touched map gets a comment with **only its own part** (no other map's part, no whiteboard part); the whiteboard part stays in chat only (it has no issue), and a map the run never touched gets no comment. The summary states:
+- **why it stopped** (auto-workable frontier exhausted; after a host interrupt the summary is not emitted at the interrupt, the resumed run's own summary covers it);
 - **what resolved** (the tickets auto closed this run);
-- **what remains**: the **set-aside** tickets (fog, `decision` convergences, out-of-scope rulings, HITL `task` checklists, human-only UAT steps, and rail actions including any **ready-to-integrate branch / PR** under `git: pr`) and **why each needs the human**, the **paused / stuck** tickets from the failure budget, and any **blocked dependents** still waiting.
+- **what merged**: the tickets merged into the local trunk (under `git: main` with parallel slots), the branches **left unmerged** with their conflicting files (the run's unmerged list), the **merge tickets** the run opened or updated (one per map or whiteboard that had an unmerged branch, each linked; a branch whose `add` failed is listed as no merge ticket written), and that the local trunk is ahead of `origin` by N commits (pushing is the human's);
+- **what remains**: the **needs-you tickets** (fog, `decision` convergences, out-of-scope rulings, HITL `task` checklists, and rail actions including any **ready-to-integrate branch / PR** under `git: pr`) and **why each needs the human**, the **paused / stuck** tickets from the failure budget, and any **blocked dependents** still waiting. Human-only UAT steps are not a needs-you reason: list instead the **UAT follow-ups opened this run** (what resolved can note them).
+
+**The run record at the end.** The summary's skip and unmerged lists come from the run's in-memory skip and unmerged lists as the primary source, united with the record's (`read`), so entries lost to a compaction come back and entries whose write was `skipped` are not lost. Once the summary is posted, run `node <templates>/trailhead-auto-run.js clear --repo <main-checkout>`, then reset the work states (`--auto false`, below). Clearing first means a crash between the two leaves `auto: true` work states and no record (the next run asks again and still resumes the tickets), never a stale record with no crash evidence. A host interrupt clears nothing (it is the same on disk as a crash), so a record left behind is the signature of both an Esc and a crash mid-run, and the next `/trailhead:auto` resumes with its choices. A crash after the summary but before the `clear` leaves a record of a drained run: reusing it only re-drains the same scope (nothing left, the run ends again), announced by the reuse line.
 
-Before handing back, if a work state file remains (an interrupted or paused ticket), run `node <templates>/trailhead-work-state.js set --repo <working-root> --auto false`. During the run every work-state `set` adds `--auto true --auto-done <n>`, `n` being the tickets resolved so far in this run (`autoDone` in the file).
+Before handing back, if a work state file remains (an interrupted or paused ticket), run `node <templates>/trailhead-work-state.js set --repo <working-root> --auto false`; with parallel slots, do it on each remaining workspace's work state: `env -u CLAUDE_CODE_SESSION_ID node <templates>/trailhead-work-state.js set --repo <workspace> --auto false`. During the run every work-state `set` adds `--auto true --auto-done <n>`, `n` being the tickets resolved so far in this run (`autoDone` in the file).
 
 Then hand back to the human with the normal session handoff framing (`../../_shared/session-handoff.md`): the human decides what to take next (dissolve fog, make a held decision, authorise a rail action, then re-invoke `/trailhead:auto` to drain more).

package/plugins/trailhead/skills/trailhead-work/references/ticket-engines.md

@@ -14,8 +14,9 @@ A ticket whose body carries a `UAT of: [<parent name>](<parent url>)` line is a
 ## `decision`: HITL, *default for decision tickets*
 Close a choice, but widen before you narrow:
 
-1. **Diverge (only if the option space isn't already clear).** Mapping the frontier usually framed the options already; skip straight to grilling when it did. When it didn't (the ticket names a question but the candidate answers aren't laid out) open the space *first*: brainstorm the plausible options, name each concretely, and post them as an `OPTIONS` comment. Divergence has no judgement yet: surface possibilities, don't rank them. If a missing **fact** is what's blocking clarity, spin a `research` ticket and block on it; if the question is "how could it look/behave", spin a `prototype`. Don't grill a space you haven't opened.
-2. **Converge.** Run the **Grilling** + **Domain vocabulary** techniques over the options to pick one. Record the decision and the why. The delegate option (agent picks) is never offered here, the choice stays the human's, but **defer is offered** (in prose, per the recipe in `../../_shared/choices.md`) when the choice is genuinely blocked on a prerequisite.
+1. **Diverge (only if the option space isn't already clear).** Mapping the frontier usually framed the options already; when it did, check that the framed set is still current and complete before grilling: re-read it against the ticket and against what has landed since (the map's `Decisions so far`, tickets closed after it was framed), add any missing candidate (the status quo, "leave it as it is", included when it is a real option), post the additions as an `OPTIONS` comment, then grill. When it didn't (the ticket names a question but the candidate answers aren't laid out) open the space *first*: brainstorm the plausible options, name each concretely, and post them as an `OPTIONS` comment. Divergence has no judgement yet: surface possibilities, don't rank them. If a missing **fact** is what's blocking clarity, spin a `research` ticket and block on it; if the question is "how could it look/behave", spin a `prototype`. Don't grill a space you haven't opened.
+2. **Converge.** Run the **Grilling** + **Domain vocabulary** techniques over the options to pick one. Before the final confirmation, run the **Holistic review before the final confirmation** (Grilling technique). Record the decision and the why. The delegate option (agent picks) is never offered here, the choice stays the human's, but **defer is offered** (in prose, per the recipe in `../../_shared/choices.md`) when the choice is genuinely blocked on a prerequisite.
+3. **Carry it into build.** A decision that only gets recorded builds nothing: when a fog area graduated into this ticket, its entry left *Not yet specified*, so once the ticket closes the work it implies lives nowhere unless a ticket carries it. So, before the close, list the work the answer makes buildable (the code, the content, the setup it commits the project to) and give every piece a home: an **existing** open ticket that already covers it (a `build`, `bug` or `task` on the map, its body extended with a `Decided in: <name+link>` line when it lacks one), or a **new `build` ticket** on the same map (on the whiteboard for a whiteboard decision), create-then-wire per `../../_shared/substrate.md`, its `## Question` naming the deliverable and its body a `Decided in: <name+link>` line back to this ticket, labelled `trailhead:blocked` and wired to the open tickets it really waits on (another unresolved decision, the build it extends). Size each one to a session, as at charting; a sprawling answer gets several builds, not one. Put the proposed split (titles, one line of scope each, blockers) in front of the human inside the **final confirmation** of step 2, so the scope of what gets built is theirs too, then create the tickets. The resolution comment carries one `Builds: <name+link>, <name+link>` line listing every ticket (new or existing) that carries the work. Only a decision whose answer builds nothing (a pure policy, a naming, a ruling that a feature is dropped) writes `Builds: none (<why>)` instead, with the reason. **Never `gh issue close` a decision whose resolution comment lacks the `Builds:` line**: the line is what lets the map, and `/trailhead:audit`, tell a carried decision from a stranded one.
 
 The two phases are distinct on purpose: divergence generates, grilling chooses. Never let the agent invent the options *and* pick for the human: the choice stays theirs.
 
@@ -30,8 +31,8 @@ The ticket that *builds*. Lean cycle, all in **ticket comments**:
 
 **Size triage (`effort`-gated, before Discuss).** When `config.effort` is `lean`, run the **size triage and ask-to-skip offer defined canonically under effort in `../../_shared/configuration-reference.md`** before Discuss: classify the change, and on trivial/small surface the one consolidated offer (its skippable steps here: the plan subagent -> a short inline plan; TDD; Cross-AI plan review; the full Code-review subagent -> a lighter inline pass; the Goal-backward verification subagent -> a quick inline goal check), going lean **only on an explicit yes**. On `normal`, on a no/silence/ambiguity, and always under `effort: standard` (the default), run the full cycle below unchanged. The correctness spine (atomic `Refs:` commits, the tests / the plan's criterion, the post-commit self-check, Resolve) is never in the offer.
 
-1. **Discuss**: **never auto-grill.** Start from Plan. If reading the ticket surfaces blocking ambiguity, **stop and ask the user** whether they want a **Grilling** round: don't launch it on your own initiative. Only on their assent run the short round and post a `DISCUSS` comment with the closed choices. The user may also ask for it themselves at any time. Advisory choices raised here **offer** the delegate/defer options, per the injection recipe in `../../_shared/choices.md`.
-2. **Plan**: a `PLAN` comment: the steps, the seams, the files touched, the verification criteria. Apply **TDD** per `config.tdd` (`seams`/`on`/`off`). Produce this plan via a *planner subagent* on `config.models.plan` (dispatch the **`trailhead-plan`** agent, read-only, passing `config.models.plan` as the model override; inline when the model is unset or equals the session model; Execute then runs as its own subagent, see below). **Report (orchestrator).** Run the report-status check on the planner's report (`--technique plan`, the *Malformed review report* protocol in `../../_shared/techniques.md`) and branch on the checker's `verdict`: `status: ready` -> post the checker's `body` verbatim as the `PLAN` comment; `status: needs_input` -> ask the user the `questions:` (the checker's `fields`), then re-spawn the planner with the answers; never answer them yourself or guess. If `config.plan_review` is on, run **Cross-AI plan review** before Execute: send the plan to external AI CLIs and converge on their concerns. Now that the files/seam are known, run the **undeclared-coupling check** (`../../_shared/teamwork.md`) against in-progress tickets. **Plan to sufficiency:** stop once you can name the steps, seams, and files with confidence, and never re-read a file already read in this planning pass; act when you have enough to plan, rather than re-deriving what the pass already established. **The single exception:** under an accepted `lean` skip (see the Size triage above), produce a short inline plan here instead of the planner subagent, and skip Cross-AI plan review; absent that accepted skip, this step runs in full as described.
+1. **Discuss**: **never auto-grill.** Start from Plan. If reading the ticket surfaces blocking ambiguity, **stop and ask the user** whether they want a **Grilling** round: don't launch it on your own initiative. Only on their assent run the short round (ending with the **Holistic review before the final confirmation** of the Grilling technique) and post a `DISCUSS` comment with the closed choices, recorded after the review. The user may also ask for it themselves at any time. Advisory choices raised here **offer** the delegate/defer options, per the injection recipe in `../../_shared/choices.md`.
+2. **Plan**: a `PLAN` comment: the steps, the seams, the files touched, the verification criteria. Apply **TDD** per `config.tdd` (`seams`/`on`/`off`). Produce this plan via a *planner subagent* on `config.models.plan` (dispatch the **`trailhead-plan`** agent, read-only, passing `config.models.plan` as the model override; inline when the model is unset or equals the session model; Execute then runs as its own subagent, see below). **Report (orchestrator).** Run the report-status check on the planner's report (`--technique plan`, the *Malformed review report* protocol in `../../_shared/techniques.md`) and branch on the checker's `verdict`: `status: ready` -> post the checker's `body` verbatim as the `PLAN` comment; `status: needs_input` -> ask the user the `questions:` (the checker's `fields`), then re-spawn the planner with the answers; never answer them yourself or guess. If `config.plan_review` is on, run **Cross-AI plan review** before Execute: send the plan to external AI CLIs and converge on their concerns. Now that the files/seam are known, run the **undeclared-coupling check** (`../../_shared/teamwork.md`) against in-progress tickets. **Plan to sufficiency:** stop once you can name the steps, seams, and files with confidence, and never re-read a file already read in this planning pass; act when you have enough to plan, rather than re-deriving what the pass already established. **Coverage check before `ready`.** Before the PLAN is returned (the short inline plan too), map every `Done when` criterion of the ticket (its `Question` when it has none) to the step(s) and the verification criterion that deliver it, and keep that mapping in the PLAN's verification criteria: a criterion no step delivers is a gap, so add the step, or return `needs_input` when closing it needs a decision. Where the PLAN picks between approaches, the pick is stress-tested per **Stress-test the pick before offering it** in `../../_shared/choices.md`, its `Weak point:` line kept in the PLAN. **The single exception:** under an accepted `lean` skip (see the Size triage above), produce a short inline plan here instead of the planner subagent, and skip Cross-AI plan review; absent that accepted skip, this step runs in full as described.
 3. **Execute**: the orchestrator runs the HITL and tracker moves around an **executor subagent on `config.models.execute`**; the implementing protocol itself lives in `executor-brief.md` (this directory), the only protocol text the agent receives from this step. The agent cannot ask the user and never writes to the tracker, pushes or creates a branch.
    - **Prototype FIRST (orchestrator).** **If this ticket changes user-facing UI (a new screen, a redesign, a changed layout), run the Prototype technique FIRST, before any real UI code**: surface a mockup to react to (its clickable link always in the same message as the approval question, per the Prototype technique; the guard also accepts a link inside the approval question itself, the prose stays preferred), routed by `config.design` (disk / artifacts / stitch) and gated by `config.design.approval` (`explicit` waits for a go-ahead, `auto` proceeds after surfacing). **Route by `config.design` and never shortcut a hosted mode to a local disk mockup**: when `config.design` is `artifacts` (or the legacy `claude.ai/design`) or `stitch`, the mockup is built there (reusing a cached `design.project`); `disk` is only for `config.design: disk` or the technique's explicit, announced fallback, never a convenience default. Read `config.design` before producing anything. For a redesign or new screen the default is to offer mockups; don't jump straight to code on a UI ticket (full statement in the **Prototype** technique, `../../_shared/techniques/prototype.md`).
    - **Branch and worktree (orchestrator).** Following the repo's `trailhead:conventions` `git:`, straight to `main` by default, or a feature branch + PR when `git: pr` (the orchestrator creates the branch before the spawn and opens the PR; the executor only commits, never pushes, switches branch or writes to the tracker). **Under `isolation: worktree`, the work happens in this ticket's `git worktree`** (`trailhead/t<n>` branch), integrating to the trunk at Resolve (see `../../_shared/teamwork.md`).
@@ -42,7 +43,7 @@ The ticket that *builds*. Lean cycle, all in **ticket comments**:
    - **Surfaced scope (orchestrator).** New scope surfacing mid-execute, reported by the executor in `surfaced scope:`, is captured/split, not worked here.
    - **Report (orchestrator).** Run the report-status check on the agent's report (`--technique executor`, the *Malformed review report* protocol in `../../_shared/techniques.md`) and branch on the checker's `verdict`, reading its `fields`: never reconstruct a result from the prose. `status: done` -> Verify. `status: partial` or `blocked` -> act on each `blockers:` entry with the moves above (flagged package, infeasible element; a foreign change in the way is raised with the user), then re-spawn. Post `fidelity:` as the fidelity comment and route `surfaced scope:` as below. Check `commits:` against the repo: it must equal the `Refs: #<n>` commit set since the base SHA, in both directions, and every SHA must resolve (`git cat-file -e <sha>^{commit}`); a mismatch is surfaced to the user, never patched over.
 4. **Verify**: a `VERIFY` comment: **start with the Stale-base preflight** (`trailhead-base-preflight.js --sync`, **Stale-base preflight** in `../../_shared/teamwork.md`): preflight, then sync, then re-run the tests, all before anything is reviewed (a rebase rewrites SHAs the review ledger cites, and the Code review and goal check must see the synced tree); then run the tests / the plan's criterion; then the **Code review** technique, scoped to the ticket's own commits per its **Ticket diff** rule (`../../_shared/techniques/code-review.md`: the `Refs: #<n>` set, read per commit, recomputed each round, an empty set surfaced as an error, never a `<base>...HEAD` range) (its subagent reviews *adversarially*: it doesn't defer to a `CLAUDE.md` convention or a "settled decision" memory), and carries the review's counts line and findings ledger, per code-review.md, **run in the background and collected by polling, never a blind blocking wait** (a hard engine default on every host, see *Reviews never block the session* in `../../_shared/techniques.md`); run the report-status check before branching on status (each report, from the subagent or inline, goes through the *Malformed review report* protocol in `../../_shared/techniques.md`, which also fixes the layout of the round's single `VERIFY` comment); **read the review's leading `status:` tag to branch deterministically: `status: clean` -> proceed to Resolve, `status: issues_found` -> iterate the fix-and-re-review loop (or run the HITL checkpoint) before resolving**; then the **Goal-backward verification** technique on `config.models.verify` (does the change deliver what the ticket promised, backward from its `Question` and the `PLAN`'s criteria; the read-only `trailhead-verify` subagent, on the same **Ticket diff** set), **run in the background and collected by polling** like Code review, branching on its leading `status:` tag (`status: met` -> proceed, `status: gaps_found` -> loop back to Execute for the gap or run the HITL checkpoint before resolving, `status: inconclusive` as the leading tag (all gaps cleared) -> a per-reason-class HITL checkpoint with no auto-retry, never auto-resolving over the unevaluated goal); then **Acceptance testing** if the change is user-facing, opening with the UAT setup (`trailhead-uat-setup.js`, after the preflight) and then the drive-mode ask (`../../_shared/techniques/acceptance-testing.md`): AI-driven, or **walk the user through a guided UAT conversationally, one step at a time**, never a checklist dumped in a comment (or skip (waive acceptance), recorded as waived, if the user so chooses): interactive by design, so it runs inline, not backgrounded. Report the outcome honestly (if a test fails, say so). **The single exception:** under an accepted `lean` skip, run a lighter inline review pass instead of the full Code-review subagent and a quick inline goal check instead of the full Goal-backward verification subagent (or skip either only when the change is truly cosmetic); the lighter inline review still uses the same finding IDs, counts line, and ledger, and the same no-`open` gate, per code-review.md; the tests / criterion and the honest outcome report still run regardless. At a HITL checkpoint here, an advisory sub-choice (which fix, how to proceed) **offers** the delegate option, per the injection recipe in `../../_shared/choices.md`; the accept/resolve decision stays the human's.
-5. **Resolve**: a resolution comment with what was done → `gh issue close` → update `Decisions so far` on the map (default path: `node <templates>/trailhead-issue-body.js append --issue <map> --section "Decisions so far" --line "<pointer>"`, a body read-modify-write that obeys the **Fail-safe body rewrites** rule in `../../_shared/substrate.md` for you; `<templates>` is the same three-dir lookup as for `trailhead-work-state.js` (**Work state file** in `../../_shared/teamwork.md`); when the helper is missing, do the read-modify-write by hand per that rule). **Disposition gate (before the close)**: the latest `VERIFY` comment's findings ledger covers every finding the counts line counts and none of them is `open`; the resolution comment links that ledger rather than duplicating it; otherwise do not `gh issue close` (per code-review.md's Disposition gate). **Stale-base preflight (before integrating).** Run the preflight per **Stale-base preflight** in `../../_shared/teamwork.md` (`git: main`: right before the trunk push; `git: pr` without isolation: on the ticket branch, immediately before the push and PR; `worktree`/`clone`: on the main checkout, then on the ticket branch) and integrate only on `current`/`synced` with the tests green and `checksOk`. **Pending-UAT guard (before the close).** If Verify left acceptance testing **not yet run** (it would otherwise be deferred), **pose the two-way choice to the user and wait for an explicit answer, never open a ticket unilaterally**: (a) run the UAT now, in this session, with no ticket (the stale-base preflight first, then the UAT setup, then the drive-mode ask, `../../_shared/techniques/acceptance-testing.md`), or (b) open a UAT follow-up ticket to run it later. On (a), run the guided walkthrough now and resolve on a confirmed pass, or on an explicit waiver if the user skips at the ask (recorded as unconfirmed; the resolution comment states it) (a failing step becomes a fix or a `bug` follow-up and an incomplete/blocked step is marked pending and tracked, per the guided-UAT rules in `../../_shared/techniques/acceptance-testing.md`, not a silent close); on (b), **open the follow-up ticket carrying the owed UAT first**, linked back to this parent (a `task` on the frontier or a `trailhead:seed` gated on the run, per *Pending UAT must stay tracked* in `../../_shared/techniques/acceptance-testing.md`). **Never open a UAT ticket without asking, never `gh issue close` on a chosen-deferred UAT with nothing opened, and never let silence or an ambiguous reply default to either path.** When acceptance was already completed at Verify, or was **explicitly waived** by the user at the drive-mode ask (a waiver is not a deferral: nothing is owed, so nothing is opened; the resolution comment states the waiver), this guard doesn't fire. **Post-commit self-check (before the comment goes out).** For each commit the comment cites, confirm the hash resolves (`git cat-file -e <hash>^{commit}`, or `git show --stat <hash>`) and that every file the comment names as touched actually appears in that commit's diff (`git -c core.quotepath=false show --name-only --format= <hash>`, with `core.quotepath=false` so a non-ASCII filename compares plainly instead of in git's C-quoted form); correct or drop any citation that fails the check, so a hallucinated or mis-stated commit never lands in the tracker record. **If this change materially altered the codebase** (a new module/layer, dependency, seam, or build/test command), **patch the affected facet of the `trailhead:codebase` issue** (see **Codebase** in `../../_shared/substrate.md`) in place (a line or two, not a re-map). When a structural event is due (a whiteboard ticket resolved, a map exhausted), refresh the dashboard with `node <templates>/trailhead-dashboard.js` (one call, whole body from the live tracker; by hand per `../../_shared/substrate-commands.md` when the helper is missing). Then close the session with the **Session handoff** ritual (`../../_shared/session-handoff.md`): one `node <templates>/trailhead-work-state.js clear --repo <working-root>` removes the work state and the session-ticket marker, then `/clear` + next command.
+5. **Resolve**: a resolution comment with what was done → `gh issue close` → update `Decisions so far` on the map (default path: `node <templates>/trailhead-issue-body.js append --issue <map> --section "Decisions so far" --line "<pointer>"`, a body read-modify-write that obeys the **Fail-safe body rewrites** rule in `../../_shared/substrate.md` for you; `<templates>` is the same three-dir lookup as for `trailhead-work-state.js` (**Work state file** in `../../_shared/teamwork.md`); when the helper is missing, do the read-modify-write by hand per that rule). **Disposition gate (before the close)**: the latest `VERIFY` comment's findings ledger covers every finding the counts line counts and none of them is `open`; the resolution comment links that ledger rather than duplicating it; otherwise do not `gh issue close` (per code-review.md's Disposition gate). **Stale-base preflight (before integrating).** Run the preflight per **Stale-base preflight** in `../../_shared/teamwork.md` (`git: main`: right before the trunk push; `git: pr` without isolation: on the ticket branch, immediately before the push and PR; `worktree`/`clone`: on the main checkout, then on the ticket branch) and integrate only on `current`/`synced` with the tests green and `checksOk`. **Pending-UAT guard (before the close).** If Verify left acceptance testing **not yet run** (it would otherwise be deferred), **pose the two-way choice to the user and wait for an explicit answer, never open a ticket unilaterally**: (a) run the UAT now, in this session, with no ticket (the stale-base preflight first, then the UAT setup, then the drive-mode ask, `../../_shared/techniques/acceptance-testing.md`), or (b) open a UAT follow-up ticket to run it later. (Under an autonomous run the guard takes option (b) itself for the human-only steps, reusing an open follow-up instead of opening a second one: see `auto.md`.) On (a), run the guided walkthrough now and resolve on a confirmed pass, or on an explicit waiver if the user skips at the ask (recorded as unconfirmed; the resolution comment states it) (a failing step becomes a fix or a `bug` follow-up and an incomplete/blocked step is marked pending and tracked, per the guided-UAT rules in `../../_shared/techniques/acceptance-testing.md`, not a silent close); on (b), **open the follow-up ticket carrying the owed UAT first**, linked back to this parent (a `task` on the frontier or a `trailhead:seed` gated on the run, per *Pending UAT must stay tracked* in `../../_shared/techniques/acceptance-testing.md`). **Never open a UAT ticket without asking, never `gh issue close` on a chosen-deferred UAT with nothing opened, and never let silence or an ambiguous reply default to either path.** When acceptance was already completed at Verify, or was **explicitly waived** by the user at the drive-mode ask (a waiver is not a deferral: nothing is owed, so nothing is opened; the resolution comment states the waiver), this guard doesn't fire. **Post-commit self-check (before the comment goes out).** For each commit the comment cites, confirm the hash resolves (`git cat-file -e <hash>^{commit}`, or `git show --stat <hash>`) and that every file the comment names as touched actually appears in that commit's diff (`git -c core.quotepath=false show --name-only --format= <hash>`, with `core.quotepath=false` so a non-ASCII filename compares plainly instead of in git's C-quoted form); correct or drop any citation that fails the check, so a hallucinated or mis-stated commit never lands in the tracker record. **If this change materially altered the codebase** (a new module/layer, dependency, seam, or build/test command), **patch the affected facet of the `trailhead:codebase` issue** (see **Codebase** in `../../_shared/substrate.md`; look it up per its singleton fail-closed rule) in place (a line or two, not a re-map). When a structural event is due (a whiteboard ticket resolved, a map exhausted), refresh the dashboard with `node <templates>/trailhead-dashboard.js` (one call, whole body from the live tracker; by hand per `../../_shared/substrate-commands.md` when the helper is missing). Then close the session with the **Session handoff** ritual (`../../_shared/session-handoff.md`): one `node <templates>/trailhead-work-state.js clear --repo <working-root>` removes the work state and the session-ticket marker, then `/clear` + next command.
 
 New scope that surfaces mid-build (while planning, executing, or testing) → **capture or split, never expand this ticket in flight** (see **Scope that surfaces while working a ticket**, served by the capture cluster). If the user defers that in-the-moment choice rather than settling it, mark the follow-up **pending** so the **Pending follow-up guard** re-poses it at handoff (`../../_shared/session-handoff.md`), instead of losing it to scrollback.
 
@@ -69,7 +70,7 @@ Then run the cycle, all in ticket comments:
    - **Surfaced scope (orchestrator).** New scope the executor reports in `surfaced scope:` is captured/split, never worked in this ticket.
    - **Report (orchestrator).** Run the report-status check on the agent's report (`--technique fix`, the *Malformed review report* protocol in `../../_shared/techniques.md`) and branch on the checker's `verdict`, reading its `fields`: never reconstruct a result from the prose. `status: done` -> Verify. `status: partial` or `blocked` -> act on each `blockers:` entry with the moves above (flagged package, infeasible element; a foreign change in the way is raised with the user), then re-spawn. Post `fidelity:` as the fidelity comment and route `surfaced scope:` as below. Check `commits:` against the repo: it must equal the `Refs: #<n>` commit set since the base SHA, in both directions, and every SHA must resolve (`git cat-file -e <sha>^{commit}`); a mismatch is surfaced to the user, never patched over.
 4. **Verify**: a `VERIFY` comment: **start with the Stale-base preflight** (`trailhead-base-preflight.js --sync`, **Stale-base preflight** in `../../_shared/teamwork.md`): preflight, then sync, then re-run the tests, all before anything is reviewed (a rebase rewrites SHAs the review ledger cites, and the Code review and goal check must see the synced tree); then the repro now passes, no regressions; **Code review** on the fix, scoped to the ticket's own commits per its **Ticket diff** rule (`../../_shared/techniques/code-review.md`: the `Refs: #<n>` set, read per commit, recomputed each round, an empty set surfaced as an error, never a `<base>...HEAD` range), and carries the review's counts line and findings ledger, per code-review.md, **run in the background and collected by polling, never a blind blocking wait** (a hard engine default on every host, see *Reviews never block the session* in `../../_shared/techniques.md`); run the report-status check before branching on status (each report, from the subagent or inline, goes through the *Malformed review report* protocol in `../../_shared/techniques.md`, which also fixes the layout of the round's single `VERIFY` comment); **read the review's leading `status:` tag to branch deterministically (`status: clean` -> Resolve, `status: issues_found` -> iterate the loop or run the checkpoint first)**; then the **Goal-backward verification** technique on `config.models.verify` (does the fix deliver what the ticket promised, backward from its `Question`; the read-only `trailhead-verify` subagent, on the same **Ticket diff** set), background and collected by polling, branching on its leading `status:` tag (`status: met` -> proceed, `status: gaps_found` -> loop back to Fix for the gap or run the checkpoint, `status: inconclusive` as the leading tag (all gaps cleared) -> a per-reason-class HITL checkpoint with no auto-retry, never auto-resolving over the unevaluated goal); **Acceptance testing** if the bug was user-facing, opening with the UAT setup (`trailhead-uat-setup.js`, after the preflight) and then the drive-mode ask (`../../_shared/techniques/acceptance-testing.md`): AI-driven, or **walk the user through a guided UAT conversationally, step by step**, not a checklist to self-serve (or skip (waive acceptance), recorded as waived, if the user so chooses): interactive by design, so it runs inline, not backgrounded. At a HITL checkpoint here, an advisory sub-choice (which fix, how to proceed) **offers** the delegate option, per the injection recipe in `../../_shared/choices.md`; the accept/resolve decision stays the human's.
-5. **Resolve**: a resolution comment (cause + fix) → `gh issue close` → update `Decisions so far` (default path: `node <templates>/trailhead-issue-body.js append --issue <map> --section "Decisions so far" --line "<pointer>"`, same helper and fallback as the `build` Resolve step; a body read-modify-write that obeys the **Fail-safe body rewrites** rule in `../../_shared/substrate.md`). **Disposition gate (before the close)**: the latest `VERIFY` comment's findings ledger covers every finding the counts line counts and none of them is `open`; the resolution comment links that ledger rather than duplicating it; otherwise do not `gh issue close` (per code-review.md's Disposition gate). **Stale-base preflight (before integrating).** Run the preflight per **Stale-base preflight** in `../../_shared/teamwork.md` (`git: main`: right before the trunk push; `git: pr` without isolation: on the ticket branch, immediately before the push and PR; `worktree`/`clone`: on the main checkout, then on the ticket branch) and integrate only on `current`/`synced` with the tests green and `checksOk`. **Pending-UAT guard (before the close).** If Verify left acceptance testing **not yet run** (it would otherwise be deferred), **pose the two-way choice to the user and wait for an explicit answer, never open a ticket unilaterally**: (a) run the UAT now, in this session, with no ticket (the stale-base preflight first, then the UAT setup, then the drive-mode ask, `../../_shared/techniques/acceptance-testing.md`), or (b) open a UAT follow-up ticket to run it later. On (a), run the guided walkthrough now and resolve on a confirmed pass, or on an explicit waiver if the user skips at the ask (recorded as unconfirmed; the resolution comment states it) (a failing step becomes a fix or a `bug` follow-up and an incomplete/blocked step is marked pending and tracked, per the guided-UAT rules in `../../_shared/techniques/acceptance-testing.md`, not a silent close); on (b), **open the follow-up ticket carrying the owed UAT first**, linked back to this parent (a `task` on the frontier or a `trailhead:seed` gated on the run, per *Pending UAT must stay tracked* in `../../_shared/techniques/acceptance-testing.md`). **Never open a UAT ticket without asking, never `gh issue close` on a chosen-deferred UAT with nothing opened, and never let silence or an ambiguous reply default to either path.** When acceptance was already completed at Verify, or was **explicitly waived** by the user at the drive-mode ask (a waiver is not a deferral: nothing is owed, so nothing is opened; the resolution comment states the waiver), this guard doesn't fire. **Run the post-commit self-check before posting, exactly as in the `build` Resolve step** (each cited hash resolves and the files it names appear in that commit's diff; correct or drop any citation that fails). **If the fix materially altered the codebase**, patch the affected facet of the `trailhead:codebase` issue (see **Codebase** in `../../_shared/substrate.md`; also a body read-modify-write, same **Fail-safe body rewrites** rule) in place (a line or two; the same `trailhead-issue-body.js` helper does it with `--section "<facet>"`). When a structural event is due, refresh the dashboard with `node <templates>/trailhead-dashboard.js`. Then close the session with the **Session handoff** ritual (`../../_shared/session-handoff.md`): one `node <templates>/trailhead-work-state.js clear --repo <working-root>` removes the work state and the session-ticket marker, then `/clear` + next command.
+5. **Resolve**: a resolution comment (cause + fix) → `gh issue close` → update `Decisions so far` (default path: `node <templates>/trailhead-issue-body.js append --issue <map> --section "Decisions so far" --line "<pointer>"`, same helper and fallback as the `build` Resolve step; a body read-modify-write that obeys the **Fail-safe body rewrites** rule in `../../_shared/substrate.md`). **Disposition gate (before the close)**: the latest `VERIFY` comment's findings ledger covers every finding the counts line counts and none of them is `open`; the resolution comment links that ledger rather than duplicating it; otherwise do not `gh issue close` (per code-review.md's Disposition gate). **Stale-base preflight (before integrating).** Run the preflight per **Stale-base preflight** in `../../_shared/teamwork.md` (`git: main`: right before the trunk push; `git: pr` without isolation: on the ticket branch, immediately before the push and PR; `worktree`/`clone`: on the main checkout, then on the ticket branch) and integrate only on `current`/`synced` with the tests green and `checksOk`. **Pending-UAT guard (before the close).** If Verify left acceptance testing **not yet run** (it would otherwise be deferred), **pose the two-way choice to the user and wait for an explicit answer, never open a ticket unilaterally**: (a) run the UAT now, in this session, with no ticket (the stale-base preflight first, then the UAT setup, then the drive-mode ask, `../../_shared/techniques/acceptance-testing.md`), or (b) open a UAT follow-up ticket to run it later. (Under an autonomous run the guard takes option (b) itself for the human-only steps, reusing an open follow-up instead of opening a second one: see `auto.md`.) On (a), run the guided walkthrough now and resolve on a confirmed pass, or on an explicit waiver if the user skips at the ask (recorded as unconfirmed; the resolution comment states it) (a failing step becomes a fix or a `bug` follow-up and an incomplete/blocked step is marked pending and tracked, per the guided-UAT rules in `../../_shared/techniques/acceptance-testing.md`, not a silent close); on (b), **open the follow-up ticket carrying the owed UAT first**, linked back to this parent (a `task` on the frontier or a `trailhead:seed` gated on the run, per *Pending UAT must stay tracked* in `../../_shared/techniques/acceptance-testing.md`). **Never open a UAT ticket without asking, never `gh issue close` on a chosen-deferred UAT with nothing opened, and never let silence or an ambiguous reply default to either path.** When acceptance was already completed at Verify, or was **explicitly waived** by the user at the drive-mode ask (a waiver is not a deferral: nothing is owed, so nothing is opened; the resolution comment states the waiver), this guard doesn't fire. **Run the post-commit self-check before posting, exactly as in the `build` Resolve step** (each cited hash resolves and the files it names appear in that commit's diff; correct or drop any citation that fails). **If the fix materially altered the codebase**, patch the affected facet of the `trailhead:codebase` issue (see **Codebase** in `../../_shared/substrate.md`, looked up per its singleton fail-closed rule; also a body read-modify-write, same **Fail-safe body rewrites** rule) in place (a line or two; the same `trailhead-issue-body.js` helper does it with `--section "<facet>"`). When a structural event is due, refresh the dashboard with `node <templates>/trailhead-dashboard.js`. Then close the session with the **Session handoff** ritual (`../../_shared/session-handoff.md`): one `node <templates>/trailhead-work-state.js clear --repo <working-root>` removes the work state and the session-ticket marker, then `/clear` + next command.
 
 A **blocking** bug that halts other work is worked immediately; an isolated one is a normal frontier ticket. New scope surfacing while fixing → capture or split, never expand this ticket in flight (see **Scope that surfaces while working a ticket**). A follow-up raised but left unopened is carried to the **Pending follow-up guard** at handoff (`../../_shared/session-handoff.md`), re-posed at Resolve rather than dropped.