@marcomigozzi/trailhead 0.14.0 → 0.15.0

package/plugins/trailhead/skills/_shared/techniques/acceptance-testing.md

@@ -1,21 +1,29 @@
 # Acceptance testing
 Automated tests prove the code does what the *code* intended; acceptance testing proves it does what the *user* wanted. After tests + code review pass, decide whether the change needs acceptance testing (user-facing behaviour usually does; a pure refactor or internal util usually doesn't) and pick the cheapest sufficient path:
 
-- **Automated first, but it does NOT discharge acceptance for user-facing behaviour.** Run the ticket's test/criterion and the suite. Passing tests prove *code-intent*; they close acceptance only for a change the user never sees (refactor, internal util). For anything the user perceives (a new screen, data that now appears/updates, a changed flow) automated green is *not* "done": you still owe the drive-mode ask below, then a browser-drive, AI-driven checks, or a guided UAT.
-- **Drive mode: ask who drives the UAT.** Every UAT start puts one explicit ask to the human, **before any step runs**: AI-driven or human-driven (plus the standard delegate option, per `../choices.md`; no defer, this is now-or-never at UAT start). It fires at three start paths: `build`/`bug` Verify, when acceptance testing is owed; the Pending-UAT guard's option (a) (run the UAT now); and resolving a UAT follow-up (any ticket carrying `UAT of:` in its body). The ask must **wait for an explicit answer**: **silence or an ambiguous reply re-asks**, it never defaults to either mode. Never fires when acceptance is not owed.
-  - **One-path skip**: a step is agent-performable unless it needs something the agent cannot access this session: a physical device or hardware, credentials or accounts it does not hold, or a human sensory judgement (feel, sound, haptics, subjective look), evaluated over the checklist before asking. No step performable: skip the ask, go human-driven, and **state the reason in one line** naming the blocking class. Any step performable: ask.
-  - **AI-driven.** Per step: browser-drive when drivable (the URL resolution below), else commands, the suite, or scripted checks; record each result and its evidence in the `VERIFY` comment as it goes; ask the human only for the steps it cannot perform, one at a time, conversationally, exactly like the guided walkthrough below.
+- **Automated first, but it does NOT discharge acceptance for user-facing behaviour.** Run the ticket's test/criterion and the suite. Passing tests prove *code-intent*; they close acceptance only for a change the user never sees (refactor, internal util). For anything the user perceives (a new screen, data that now appears/updates, a changed flow) automated green is *not* "done": you still owe the drive-mode ask below, then a browser-drive, AI-driven checks, or a guided UAT, unless the user explicitly skips (waives) acceptance there.
+- **Stale-base preflight comes first.** A UAT never runs on a base that is behind the trunk or whose project checks fail (`trailhead-base-preflight.js`, **Stale-base preflight** in `../teamwork.md`). Inside `build`/`bug` Verify the preflight already ran at the start of Verify, which covers this ask; on the other start paths (Pending-UAT option (a), a `UAT of:` follow-up) run it before the drive-mode ask.
+- **UAT setup comes next.** At all three start paths (`build`/`bug` Verify, the Pending-UAT guard's option (a), a `UAT of:` follow-up), after the stale-base preflight and before the drive-mode ask, bring the target up with `trailhead-uat-setup.js`, whichever mode then drives (most real UATs are human-driven, on-device). The drive-mode ask wording is unchanged. Config: `uat.setup` / `uat.accounts`, **UAT setup** in `../configuration-reference.md`.
+  - **Run it.** `plan` first (`--repo <working-root> --config-root <original checkout>`): it lists the steps, their `note`s and which referenced `$ENV` variables are set, never a value. Honour each step's `note` before running it, and ask the human when the note says to. Then `run`; it skips a step whose `check` passes and stops at the first failure. Each `run`/`check` invocation is killed after `--step-timeout` (default 600 s) and the poll after `run` gives up after `--ready-timeout` (default 60 s); a timed-out `run` kills only its `sh`, so a child it spawned may survive. A long-lived process backgrounded in `run` must redirect its own output (for example `> /tmp/dev.log 2>&1 &`), else it keeps writing to the helper's deleted capture file. To honour a step's `note` one step at a time, run it alone with `--only <i>`. Branch on `status`, fail closed: only `ready` and `none` go on to the drive-mode ask; `unconfigured` goes to the probe below; `invalid` and `failed` stop.
+  - **Failure.** Stop and report the failing step with its output (a `missing-env` names the variable), then ask: **retry**, **the human does that step**, or **proceed without it** (the UAT steps that depend on it become explicitly pending and tracked, per the partial-run rule). Resume accordingly: retry -> `run --from <failedStep>`; the human did that step, or proceed without it -> `run --from <failedStep + 1>` (`--only <i>` runs just step `i`). When the output implicates the ticket's own code (its build or deploy fails), also offer **treat as a defect** (fix on the ticket, or a `bug`). Never a silent fallback. The output is a redacted tail, a best-effort backstop: read it before showing it and redact anything credential-like.
+  - **Unconfigured project** (`status: unconfigured`). Probe the project (package scripts, Expo/adb, docker compose, Supabase functions/migrations, an already-running server), **propose** the setup plan, run it on an explicit yes, then **offer to save** it to `uat.setup` in the original checkout's `.trailhead/config.json`, replacing machine-specific values with `$ENV` references and naming the variables to set. Nothing plausible found: ask the human what setup is needed (same save offer). A declined save offers to write `[]`; declined again, it is not re-offered this session. `[]` (`status: none`) means no setup needed: no probe, no offer.
+  - **Accounts.** Pick the `uat.accounts` role matching the step, ask when ambiguous. References resolve only inside tool inputs (a browser field, a command's environment), never into chat, issue comments or commits; in human-driven mode show the user and the reference name only.
+  - **Record.** What ran, was skipped or failed goes in the `VERIFY` comment: step names and results only, never output or values.
+- **Drive mode: ask who drives the UAT.** Every UAT start puts one explicit ask to the human, **before any step runs**: AI-driven, human-driven, or *skip (waive acceptance)* (plus the standard delegate option, per `../choices.md`; no defer, this is now-or-never at UAT start). It fires at three start paths: `build`/`bug` Verify, when acceptance testing is owed; the Pending-UAT guard's option (a) (run the UAT now); and resolving a UAT follow-up (any ticket carrying `UAT of:` in its body). The ask must **wait for an explicit answer**: **silence or an ambiguous reply re-asks**, it never defaults to a mode or to skip. Never fires when acceptance is not owed.
+  - **One-path skip**: a step is agent-performable unless it needs something the agent cannot access this session: a physical device or hardware it cannot reach (none connected, no tool to drive it), credentials or accounts it does not hold, or a human sensory judgement (feel, sound, haptics, subjective look), evaluated over the checklist before asking. No step performable: the ask drops only the AI-driven option and asks **human-driven or skip**, and **states the reason in one line** (naming the blocking class) before asking; on this reduced ask the delegate option resolves to human-driven (never skip). Any step performable: ask with all the options.
+  - **AI-driven.** Per step: browser-drive when drivable (the URL resolution below); else drive the device the session can reach (a phone or emulator over `adb`, an iOS simulator, a TV, a desktop app, through the connected tools: a device MCP, computer use, the platform's CLI), with a screenshot as evidence; else commands, the suite, or scripted checks; record each result and its evidence as it goes, gathered for part 3 of the round's single `VERIFY` comment (layout in *Malformed review report* in `../techniques.md`), which the orchestrator posts once the round's checks, including this one, are done (on the two start paths outside a Verify round, the Pending-UAT guard's option (a) and a UAT follow-up, there is no round: the orchestrator posts the results as a `VERIFY` comment of their own once the UAT ends); ask the human only for the steps it cannot perform, one at a time, conversationally, exactly like the guided walkthrough below.
+  - **Skip (waive acceptance).** Offered at all three start paths. A skip is a **waiver, not a deferral**: the user forgoes acceptance, so nothing is left owed. Record `acceptance: waived by the user (unconfirmed)` in the `VERIFY` comment (part 3 of the round's single `VERIFY`, or a standalone `VERIFY` comment on the Pending-UAT guard's option (a) and UAT-follow-up paths, which have no round), never a pass. No step runs, no follow-up is opened, and the Pending-UAT guard does not fire. The resolution comment states the waiver. On a `UAT of:` follow-up, a skip closes as waived: the resolution comment links back to the parent and states the waiver. The delegate option never picks skip and `auto` never picks skip: waiving acceptance is the human's call.
   - **Human-driven.** The guided conversational walkthrough below runs unchanged: one step at a time, wait for the human's report, never a checklist to self-serve.
   - Applies **in both modes**: the failing-step handling, the partial-run / pending tracking, and the mockup-fidelity check below apply the same way, whichever mode drove the run.
-  - **Config.** `acceptance.browser: off` disables browser-driving, not AI-driven checks run via commands or the test suite, and it does not pre-answer this ask: the ask still fires, and an AI-driven answer still runs its non-browser checks.
+  - **Config.** `acceptance.browser: off` disables browser-driving, not AI-driven checks run via commands or the test suite, and it does not pre-answer this ask or imply a waiver (only the human's explicit skip waives acceptance): the ask still fires, and an AI-driven answer still runs its non-browser checks.
   - **`auto` takes this ask as the delegate option without the confirm gate** (per `../choices.md`): AI-driven when any step is agent-performable; human-only steps stay incomplete and the ticket is set aside, listing them in the run-end summary (never faked); no performable step means the whole UAT is human-only and the ticket is set aside. Full autonomous-run behaviour lives in `../../trailhead-work/references/auto.md`.
-- **AI-driven, browser-drivable web app → drive it yourself.** Governed by `config.acceptance.browser` + `config.testing`: when it's `auto`/`on` and `testing.webapp` is set with `testing.url` set or resolvable (see below), use the browser-automation tools to exercise the actual change end-to-end (navigate, fill, click, assert visible state; capture a screenshot into the `VERIFY` comment). Prefer this over asking the human when the flow is scriptable. Never trigger native/JS dialogs that would wedge the session.
+- **AI-driven, browser-drivable web app → drive it yourself.** Governed by `config.acceptance.browser` + `config.testing`: when it's `auto`/`on` and `testing.webapp` is set with `testing.url` set or resolvable (see below), use the browser-automation tools to exercise the actual change end-to-end (navigate, fill, click, assert visible state; capture a screenshot as evidence for part 3 of the `VERIFY` comment). Prefer this over asking the human when the flow is scriptable. Never trigger native/JS dialogs that would wedge the session.
   - **Auto mode resolves the URL before falling back.** Under `acceptance.browser: auto`/`on`, when `testing.webapp` is set but `testing.url` is not, do not drop straight to asking: first try to determine the target URL from the project. Probe, cheapest first, a dev server already running (the likely local ports, or a server log / PID the project writes), package scripts (`dev`/`start`/`preview` in `package.json` or the project's task runner), dev-server and framework config (the configured host/port in e.g. Vite/Next/Astro/Expo config), and project config. When one is found, **propose it** ("acceptance will run against `http://localhost:5173`, correct?") for the user to accept or correct, then drive the browser against the accepted URL. Only when no URL can be determined fall back to asking the human, or to the guided UAT below.
-- **Human-driven, or an AI-driven step that isn't performable → guided UAT is MANDATORY, and it is CONVERSATIONAL.** This is the human-driven mode from the drive-mode ask above, and it is also what an AI-driven run falls back to for the specific step(s) it cannot perform: when `config.acceptance.browser` is `off`, or no target URL could be determined (the auto attempt above included), or the target isn't browser-drivable (a mobile/native app, a CLI, real hardware, real credentials), **`off` means "acceptance via a guided walkthrough," not "skip acceptance."** For any user-facing change you MUST **run the human through the UAT one step at a time, in the chat**: state step 1 (what to do, where to tap/look, the expected result), then **stop and wait** for the human to report what they actually saw; only then move to step 2. It is a dialogue *you* drive, turn by turn, not a list you hand over. **Anti-pattern, never do this:** post the full numbered checklist and point the user at the ticket to self-serve ("follow the 9 steps in the comment of #NN"). That is exactly the failure this rule kills: the checklist is the *record*, never the *interaction*. Mirror each step's outcome into the `VERIFY` comment as you go; don't close on green you didn't actually see.
+- **Human-driven, or an AI-driven step that isn't performable → guided UAT is MANDATORY, and it is CONVERSATIONAL.** This is the human-driven mode from the drive-mode ask above, and it is also what an AI-driven run falls back to for the specific step(s) it cannot perform: when `config.acceptance.browser` is `off`, or no target URL could be determined (the auto attempt above included), or the target can't be driven this session (a device or hardware the session cannot reach, real credentials it does not hold; a mobile/native app or a TV on a connected device or emulator *is* drivable, per the AI-driven rule above), **`off` means "acceptance via a guided walkthrough," not "skip acceptance."** For any user-facing change you MUST **run the human through the UAT one step at a time, in the chat**: state step 1 (what to do, where to tap/look, the expected result), then **stop and wait** for the human to report what they actually saw; only then move to step 2. It is a dialogue *you* drive, turn by turn, not a list you hand over. **Anti-pattern, never do this:** post the full numbered checklist and point the user at the ticket to self-serve ("follow the 9 steps in the comment of #NN"). That is exactly the failure this rule kills: the checklist is the *record*, never the *interaction*. Mirror each step's outcome into the `VERIFY` comment as you go; don't close on green you didn't actually see.
   - **On a failing step: stop, take note, open the closing ticket then and there.** A failed step is an acceptance finding, not a footnote: record expected-vs-seen, and immediately open the follow-up that will carry it to resolution: a `bug` ticket (with `Regression of:`/`Surfaced from:` as fits), or a fix on this ticket before it resolves if it's small and in-scope. Then ask the human whether to keep going through the remaining steps or stop here. Never silently log a fail and carry on to Resolve.
   - **When only some steps are runnable now** (e.g. a few need a backend deployed first), walk the runnable ones conversationally **now**, and mark the rest **explicitly pending** with what unblocks them, tracked as below. Don't defer the whole UAT just because part of it is blocked.
-  - **When the human can only run it later** (on-device, hardware you don't have right now), record the full numbered checklist in the `VERIFY` comment as the durable artifact and mark UAT **explicitly pending**, but the walkthrough stays conversational **when they come to run it**: never shrink it to a vague one-liner ("just check it on the device"), and never let "automated passed" quietly stand in for it. Deferring *where/when* the human runs it is fine; replacing the live step-by-step with a self-serve checklist is not.
-  - **Pending UAT must stay tracked: a closed ticket is not tracking.** Don't resolve/close a user-facing ticket on unconfirmed acceptance and leave the checklist as a comment on the closed issue, where nobody will look. The default is to **keep the ticket open** until the human confirms the UAT passes (closing on green you didn't see is a premature close). **When UAT hasn't been run at Resolve, pose the choice to the human and wait for an explicit answer, never decide it for them:** (a) **run the UAT now**, in this session, with no ticket (opens with the drive-mode ask above, then the guided conversational walkthrough or AI-driven checks, resolving only on a confirmed pass; a failing step becomes a fix or a `bug` follow-up and an incomplete/blocked step is marked pending and tracked, per the failing-step and partial-run rules above, never a silent close), or (b) **open a UAT ticket** to run it later. **Never open a UAT ticket without asking, and never let silence or an ambiguous reply default to either path.** Only when the human picks (b) do you **open a follow-up ticket before that close** that carries the pending UAT and links back to the parent with a `UAT of: <parent name>(link)` pointer in the body. Route it the way `../choices.md` routes a deferred choice: a **`trailhead:seed`** (kept blocked) when the run is gated on a future external trigger not yet true (hardware you don't have, a device out of reach), or a follow-up **`task`** on the frontier when it's just scheduled or batched work you could pick up any time. Either way the follow-up **carries the full numbered checklist and, when it comes to resolution, opens with the drive-mode ask above before running the guided conversational walkthrough**, never a self-serve check-off. **Never close a user-facing ticket on a chosen-deferred UAT with nothing opened**: the parent may close as agreed, but the owed UAT stays visible on the tracker as its own ticket, linked to the parent, until it is actually performed. The pending check must be visible on the tracker, not buried.
+  - **When the human can only run it later** (on-device, hardware you don't have right now), record the full numbered checklist in part 3 of the `VERIFY` comment as the durable artifact and mark UAT **explicitly pending**, but the walkthrough stays conversational **when they come to run it**: never shrink it to a vague one-liner ("just check it on the device"), and never let "automated passed" quietly stand in for it. Deferring *where/when* the human runs it is fine; replacing the live step-by-step with a self-serve checklist is not.
+  - **Pending UAT must stay tracked: a closed ticket is not tracking.** Don't resolve/close a user-facing ticket on unconfirmed acceptance by your own choice and leave the checklist as a comment on the closed issue, where nobody will look. The one exception is an explicit waiver: **a waiver is not a deferral**. The human picked skip at the drive-mode ask and forwent acceptance, recorded as unconfirmed in `VERIFY`, so nothing is owed and nothing is opened. The default is otherwise to **keep the ticket open** until the human confirms the UAT passes (closing on green you didn't see is a premature close). **When UAT hasn't been run at Resolve, pose the choice to the human and wait for an explicit answer, never decide it for them:** (a) **run the UAT now**, in this session, with no ticket (opens with the drive-mode ask above, then the guided conversational walkthrough or AI-driven checks, resolving 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 failing-step and partial-run rules above, never a silent close), or (b) **open a UAT ticket** to run it later. **Never open a UAT ticket without asking, and never let silence or an ambiguous reply default to either path.** Only when the human picks (b) do you **open a follow-up ticket before that close** that carries the pending UAT and links back to the parent with a `UAT of: [<parent name>](<parent url>)` pointer line in the body, and carries the `trailhead:uat` label: put it in the `--label` list of the `gh issue create` (next to the `trailhead:ticket` and type labels), ensuring the `trailhead:uat` label idempotently first (`substrate-commands.md`). Route it the way `../choices.md` routes a deferred choice: a **`trailhead:seed`** (kept blocked) when the run is gated on a future external trigger not yet true (hardware you don't have, a device out of reach), or a follow-up **`task`** on the frontier when it's just scheduled or batched work you could pick up any time. Either way the follow-up **carries the full numbered checklist and, when it comes to resolution, opens with the drive-mode ask above before running the guided conversational walkthrough**, never a self-serve check-off. **Never close a user-facing ticket on a chosen-deferred UAT with nothing opened**: the parent may close as agreed, but the owed UAT stays visible on the tracker as its own ticket, linked to the parent, until it is actually performed. The pending check must be visible on the tracker, not buried.
 
 **Mockup-fidelity check (when the ticket had an approved mockup).** If the change was preceded by an approved mockup (the **Prototype** technique produced one and it was approved and recorded at Execute), acceptance testing MUST check the built screen **against that approved mockup**, not merely against "what the user wanted" in the abstract. Pull the mockup's current state to compare against (re-fetch it in `artifacts` / `stitch` mode via the technique's re-fetch rule, or open the linked `disk` mockup); never compare from memory. Walk it **element by element and state by state**, layout, spacing, sizing, colour, typography, copy, and every state it shows (empty, loading, error, hover, active, disabled, and the like), enumerating from the approved mockup itself (the spec) and cross-checking the executor's recorded Execute-step fidelity list and any element it flagged infeasible, and confirm each is reproduced. Record the per-element and per-state result in the `VERIFY` comment. Any **unforced** deviation is an acceptance finding, never waved through as "close enough"; a genuinely infeasible part must already have been raised with the user at Execute (per the Prototype technique), not surface here as a silent drift.
 

package/plugins/trailhead/skills/_shared/techniques/code-review.md

@@ -18,7 +18,7 @@ Review on four axes:
 - **Reuse & simplification**: hunt the classic smells, each a *judgement call* (never a hard violation), and for each name it → say how to simplify: duplicated code (extract), mysterious name (rename), primitive obsession & data clumps (introduce a type), long parameter list, feature envy / message chains (move or collapse), repeated switches, speculative generality (delete), shotgun surgery & divergent change, middle-man / shallow pass-through (delete or deepen). Suppress any a documented standard endorses; skip what tooling enforces.
 - **Standards & spec**: does it match the repo's documented conventions AND do what the ticket actually asked (missing requirements, scope creep, plausibly-wrong implementations)? Suppress smells a documented standard endorses; skip anything tooling already enforces.
 
-Classify each finding: **Critical** (bug/security/breaks the spec) → **Warning** (should fix) → **Info** (judgement call). Before reporting ANY finding, **verify it adversarially**: re-read the actual code, confirm the failing path is reachable and the claim holds. Discard plausible-but-wrong findings; an unverified finding is worse than none. Quote the offending hunk (and the standard/spec line) per finding. **Stable finding IDs**: each verified finding gets an ID the first time it's reported, `C1`, `W1`, `I1`, ..., by severity, numbered in discovery order, and keeps that ID across every round of the fix-and-re-review loop below; a re-review that finds the same issue still open reuses its ID, a genuinely new finding takes the next number in its severity. An ID's severity is fixed at first report: if a re-review reclassifies a finding to a different severity, mark the old ID `reclassified as <new ID>` in the ledger and continue the finding under a new ID of the new severity; a `reclassified` line is a pointer, not a disposition, and is left out of the counts, so the finding counts once, under its current severity. Report in the ticket's `VERIFY` comment, **led by a machine-checkable status tag on its own first line**: `status: clean` when no **Critical** finding remains (nothing blocks Resolve), or `status: issues_found` when one or more Criticals are still open (the caller must iterate the fix-and-re-review loop below, or run the HITL checkpoint, before resolving). Warnings/Info alone leave the tag `status: clean`, since they don't gate resolution. Emit that line verbatim as the comment's first line.
+Classify each finding: **Critical** (bug/security/breaks the spec) → **Warning** (should fix) → **Info** (judgement call). Before reporting ANY finding, **verify it adversarially**: re-read the actual code, confirm the failing path is reachable and the claim holds. Discard plausible-but-wrong findings; an unverified finding is worse than none. Quote the offending hunk (and the standard/spec line) per finding. **Stable finding IDs**: each verified finding gets an ID the first time it's reported, `C1`, `W1`, `I1`, ..., by severity, numbered in discovery order, and keeps that ID across every round of the fix-and-re-review loop below; a re-review that finds the same issue still open reuses its ID, a genuinely new finding takes the next number in its severity. An ID's severity is fixed at first report: if a re-review reclassifies a finding to a different severity, mark the old ID `reclassified as <new ID>` in the ledger and continue the finding under a new ID of the new severity; a `reclassified` line is a pointer, not a disposition, and is left out of the counts, so the finding counts once, under its current severity. Return the report (the agent never posts it; the orchestrator posts it as the `VERIFY` comment after the report-status check), **led by a machine-checkable status tag on its own first line**: `status: clean` when no **Critical** finding remains (nothing blocks Resolve), or `status: issues_found` when one or more Criticals are still open (the caller must iterate the fix-and-re-review loop below, or run the HITL checkpoint, before resolving). Warnings/Info alone leave the tag `status: clean`, since they don't gate resolution. Emit that line verbatim as the report's first line.
 
 **Counts line, right under `status:`.** The comment's second line, right under `status:`, is the cumulative severity count: `critical: <n> · warning: <n> · info: <n>` (zeros written out, never omitted), the count of distinct findings (by ID, excluding `reclassified` pointers) reported on this ticket so far, across every round. Cumulative means a finding fixed in an earlier round still counts here, so the totals always match the ledger below. Below the counts comes the **findings ledger** (authoritative for this ticket), one line per finding ID with its disposition: `fixed (<commit>)`, `deferred → <ticket>` (a ticket that exists, named and linked: an already-open ticket, or one opened on the user's explicit yes per **Scope that surfaces while working a ticket** (served by the capture cluster), never unasked; when the user declines or leaves it unanswered, and under an autonomous run, where no ticket is opened unasked, use `accepted: <one-line reason>` instead), `accepted: <one-line reason>`, or `open` while the disposition is still undecided. The ledger lives in the latest `VERIFY` comment of the ticket and is rewritten each round; the resolution comment links to it rather than duplicating it. Then the findings grouped by severity with file:line and the fix, as before, so the Verify step branches on the tag without parsing prose.
 

package/plugins/trailhead/skills/_shared/techniques/codebase-map.md

@@ -9,7 +9,7 @@ One-time at project adoption. Fan out 5 read-only reader subagents in parallel (
 - **Risk & complexity hotspots**: tech debt, fragile/God files, security-sensitive paths, TODO/FIXME clusters, expensive-to-change areas.
 - **Test & build setup**: framework, test layout, mocking style, how to run tests/build/lint, coverage posture.
 
-Give each agent read-only tools only (Read/Grep/Glob, never Edit/Write), a tight facet brief, and instruction to cite concrete file paths in backticks and return a compact summary (~10–20 lines), NOT file dumps. Keep facets disjoint so contexts don't collide; while they run, wait for all five. Then **distil** (don't concatenate) into ONE compact write-up (a few lines per facet, load-bearing paths preserved) and post it as the body of the repo's **`trailhead:codebase` issue**: a single per-repo issue (label `trailhead:codebase`), created if absent, updated if present. It is **not** in any map's Notes: it's repo-scoped, so every map of the repo links it and a finished map never strands it (each map's Notes carries just a link). The raw per-facet output is throwaway scratch: mine it, discard it. Do NOT persist per-facet reports as project state, do NOT re-run per ticket or per map.
+Give each agent read-only tools only (Read/Grep/Glob, never Edit/Write), a tight facet brief, and instruction to cite concrete file paths in backticks and return an investigating report (`Return contract` in its definition) whose `answer:` is a compact summary (~10–20 lines), NOT file dumps, with `evidence:` as `file:line` paths. Keep facets disjoint so contexts don't collide; while they run, wait for all five. Run the report-status check on each report (`--technique codebase-map`, the *Malformed review report* protocol in `../techniques.md`) and read its `fields`: `status: found` -> use its `answer:`; `status: inconclusive` -> use its `answer:` too and note the gap in that facet; `status: needs_input` -> ask the user its `open questions:` once, then re-spawn that facet with the answers, or mark the facet unmapped if they cannot answer. Then **distil** the `answer:` fields (don't concatenate) into ONE compact write-up (a few lines per facet, load-bearing paths preserved) and post it as the body of the repo's **`trailhead:codebase` issue**: a single per-repo issue (label `trailhead:codebase`), created if absent, updated if present. It is **not** in any map's Notes: it's repo-scoped, so every map of the repo links it and a finished map never strands it (each map's Notes carries just a link). The raw per-facet output is throwaway scratch: mine it, discard it. Do NOT persist per-facet reports as project state, do NOT re-run per ticket or per map.
 
 **Keeping it fresh (incremental, not a re-run).** The full fan-out happens once. After that the issue is kept current **at Resolve**: when a resolved `build`/`bug` ticket materially changes the map (a new module or layer, a new dependency/integration, a new seam, a changed build/test command, a new convention), **patch just the affected facet in place**, a line or two, as part of that ticket's Resolve. Leave it untouched for cosmetic or in-facet changes. A **full re-run** is reserved for major drift (a rewrite, a stack change, an architecture the incremental patches no longer describe).
 

package/plugins/trailhead/skills/_shared/techniques/debug.md

@@ -3,6 +3,8 @@ A bug is a science problem: observe, hypothesize, test, confirm, verify. Never p
 
 When run as a subagent, dispatch the **`trailhead-debug`** agent (full tools: it adds instrumentation and regression tests, so it needs Write), passing `config.models.debug` as the model override; **never** an external-plugin debugger agent that another installed tool registered.
 
+**Report.** The agent returns an investigating report (`Return contract` in its definition): `answer:` the confirmed cause stated as a falsifiable hypothesis, `evidence:` the falsification test and its result, `open questions:` what stays unsettled. It never commits or creates a branch: the orchestrator turns the report into the `DIAGNOSIS`.
+
 **Redact as you go.** These notes are posted on public Issues. When you show a command, output, or artifact, replace every secret with `<REDACTED>` and run loops against env vars, never inlined credentials; quote only the signal-carrying lines, not whole dumps. If a redacted artifact isn't enough to move forward, say so and ask the user; never paste the raw one to compensate.
 
 1. **Reproduce: build a feedback loop.** Get ONE command you've actually run that goes red on *this exact symptom* and green when fixed: a failing test at the nearest seam, a curl against a dev server, a CLI diff vs a known-good snapshot, a replayed trace. Tighten it: faster, sharper (assert the specific symptom), deterministic (pin time, seed RNG, freeze network). No red-capable command → do NOT hypothesize; say so, list what you tried, ask for env access or a redacted artifact. For flaky bugs, chase a *higher* repro rate (loop 100×, parallelize, widen timing windows). 50% is debuggable, 1% is not.

package/plugins/trailhead/skills/_shared/techniques/research.md

@@ -1,5 +1,5 @@
 # Research
-Spawn a focused subagent (AFK, parallelisable) with exactly ONE clear question: sharp enough that the answer is a decision, not a survey. Vague scope breeds rabbit holes; a narrow question is its own leash. Dispatch the **`trailhead-research`** agent (full tools: it writes findings to a throwaway `research/<name>` branch, so it needs Write), passing `config.models.research` as the model override; **never** an external-plugin researcher agent that another installed tool registered.
+Spawn a focused subagent (AFK, parallelisable) with exactly ONE clear question: sharp enough that the answer is a decision, not a survey. Vague scope breeds rabbit holes; a narrow question is its own leash. Dispatch the **`trailhead-research`** agent (it commits nothing and creates no branch: the report is the artifact), passing `config.models.research` as the model override; **never** an external-plugin researcher agent that another installed tool registered.
 
 - **Treat your own prior knowledge as hypothesis, not fact**: training is stale. "As of my training" is a warning flag, not a citation.
 - **Chase primary, high-trust sources**: official docs, source code, specs, first-party APIs; never a secondary write-up. Follow every claim back to the source that owns it; resolve *current* docs rather than reciting from memory.
@@ -8,5 +8,7 @@ Spawn a focused subagent (AFK, parallelisable) with exactly ONE clear question:
 - **Distinguish verified fact from inference explicitly.** Assign honest confidence (LOW when only training data backs a claim). "I couldn't find X", "sources contradict", "LOW confidence" are valuable findings, not failures; never hide uncertainty behind confident prose.
 - **Investigation, not confirmation:** gather evidence, then conclude; don't start from the answer you want and collect support.
 - **Stop at sufficiency; no redundant re-reads.** Once the evidence is decision-ready, conclude: gathering past a confident answer is analysis paralysis, not rigour. Don't re-open a source you have already extracted from in this pass (re-reading the same file to re-derive a fact you already hold); cross-referencing a *new* source for confirmation is different, and still required.
-- Capture findings as a durable Markdown artifact on a throwaway `research/<name>` branch (out of main), each claim carrying its source URL; leave a pointer on the ticket. Return a **decision-ready answer** (verdict, tradeoffs, confidence, citations) not a raw data dump.
+- Return a **decision-ready answer** (verdict, tradeoffs, confidence, citations), not a raw data dump, as the agent's investigating report (`Return contract` in its definition): `answer:` holds the verdict, tradeoffs and confidence; `evidence:` holds every claim with its source URL; `open questions:` what stays unsettled. No branch, no committed artifact: parallel research agents share one checkout, so the report is the artifact.
+
+**Report (orchestrator).** Run the report-status check on each report (`--technique research`, the *Malformed review report* protocol in `../techniques.md`) and branch on the checker's `verdict`, reading its `fields`. Post the report as a `RESEARCH` comment on the research ticket (every claim with its URL in `evidence:`). `status: found` -> post, then resolve the ticket. `status: inconclusive` -> post, then ask the user: accept the answer at that confidence, narrow the question, or run another round. `status: needs_input` -> ask the user the `open questions:`, then re-spawn with the answers.
 

package/plugins/trailhead/skills/_shared/techniques/verify.md

@@ -7,7 +7,7 @@ Run it in the `build`/`bug` **Verify** step, after the tests / the plan's criter
 1. **Restate the goal.** From the ticket's `## Question` and the `PLAN`'s verification criteria, list what "done" means as concrete, checkable claims. If the ticket named acceptance criteria, those are the claims. **When the ticket had an approved mockup**, add one explicit claim: the built UI is faithful to the approved mockup (layout, spacing, sizing, colour, typography, copy, and every state it shows). Being read-only and running before Acceptance testing, check it to the extent statically evaluable: does the built code carry the mockup's specified copy, states, and structural elements? A dropped element or missing state surfaces as `gaps_found`, and **defer the visual, pixel-level verdict to Acceptance testing's mockup-fidelity check** (a screenshot, not the diff, settles that) rather than forcing it here.
 2. **Work backward from each claim to the ticket's own commits.** Take the change from the **Ticket diff** rule (canonical in `code-review.md`; restated here because this protocol is loaded on its own): the commits carrying this ticket's `Refs: #<n>` trailer, computed with exactly `git -C <repo> log --reverse --basic-regexp --grep='^Refs: #<n>$' --format=%H HEAD` and read per commit, oldest first, with `git -C <repo> show --remerge-diff <sha>`; recompute it on every run, never use a `<base>...HEAD` range, and treat an empty set as an error surfaced to the caller, never a `met`. For every claim, find the commit(s) and lines that satisfy it, record it as **unmet** if the code does not satisfy it, or as **inconclusive** (with a reason-class, see the Verdict) if you could not actually evaluate it: the check would not run, the evidence was unreadable, or the criterion is not falsifiable as written. Read the actual diff and the resulting code, not the commit messages.
 3. **Check for silent gaps.** A task marked done whose criterion no code satisfies; a criterion the tests do not actually exercise; a partial implementation that passes the tests but misses an edge the ticket called out. A claim you **could not evaluate at all** is not a gap: it is `inconclusive` (step 4), never forced to `gaps_found`.
-4. **Verdict.** Post the result with a leading `status:` tag the engine branches on, one of three:
+4. **Verdict.** Return the verdict with a leading `status:` tag the engine branches on; the orchestrator posts it under the `## Goal-backward verification` heading of the round's `VERIFY` comment (layout in *Malformed review report* in `../techniques.md`). One of three:
    - `status: met`: every claim was evaluated and satisfied.
    - `status: gaps_found`: at least one claim was **evaluated and the code does not satisfy it** (list each unmet or partial claim with its evidence).
    - `status: inconclusive`: at least one claim **could not be evaluated at all**, and none is an outright gap. Every inconclusive claim carries **exactly one** mandatory `reason:` from this closed set:

package/plugins/trailhead/skills/_shared/techniques.md

@@ -2,10 +2,20 @@
 
 The ticket engines call these by name. Each technique's full protocol lives in its own file under `techniques/`: **read that file the first time a session needs the technique**, so only the ones in play load into context (don't preload them). They are `trailhead`'s own, self-contained; each technique is dispatched to its **trailhead-owned agent** (`trailhead-<technique>`, shipped as committed `agents/trailhead-*.md`) via the `Agent` tool, with the technique's full protocol injected at spawn.
 
-**Dispatch each technique to its trailhead-owned agent.** Every technique subagent carries its full protocol in the prompt (from its `techniques/` file), so the agent definition stays **thin**: identity + tool policy, model-agnostic. Dispatch each technique to **its own `trailhead-<technique>` agent** (set `subagent_type` accordingly): the Plan step → `trailhead-plan`, Execute → `trailhead-executor`, Research → `trailhead-research`, Code review → `trailhead-code-review`, Debug → `trailhead-debug`, Fix → `trailhead-fix`, Codebase map → `trailhead-codebase-map`, Goal-backward verification → `trailhead-verify`. These agents ship with trailhead (committed `agents/trailhead-*.md`) and are registered wherever trailhead is installed as a Claude Code **plugin** (its `agents/` load automatically), or its agent files are otherwise present as subagent types. **If a `trailhead-<technique>` agent is NOT registered in the current environment** (the `Agent`/`Task` tool reports the type unknown, or it is absent from the available-agents list, as on a skills-only install that did not register the agents), **run that technique inline in the main session**, following its `techniques/` protocol directly. Do **not** divert to a host built-in (`general-purpose`/`Explore`) or any external-plugin agent as the engine target. Inline is a graceful degradation: the technique still runs, only on the session model rather than its `config.models.<key>` pin (the same inline path used when that model equals the session model). The dispatch rule is therefore: the real `trailhead-<technique>` agent when it is registered, else inline in the main session, never a foreign agent. **Pass the `config.models.<key>` model as the `Agent`-tool `model` override at spawn** so config stays authoritative (the `.md` is model-agnostic; the override wins), running inline instead when that model is unset or equals the session model. On Claude Code the `Agent` tool's `model` parameter accepts only the short family aliases (`opus` / `sonnet` / `haiku` / `fable`), not the full ids `config.models.*` stores, so **map the configured id to its family alias only for the literal `model` value passed at spawn**: `claude-opus-*` -> `opus`, `claude-sonnet-*` -> `sonnet`, `claude-haiku-*` -> `haiku`, `claude-fable-*` -> `fable`; if an id matches none of these, don't guess: warn and inherit the session model (per `configuration-reference.md`). The alias names a family, not a version, so the host resolves it to that family's current model: the exact version the id pinned cannot be conveyed to the `Agent` tool and is not honoured at subagent spawn. **Keep the inline-vs-subagent decision on the full id**, running inline only when `config.models.<key>` is unset or its full id equals the session model's, never on the alias, so a deliberate same-family but different-version pin (e.g. `claude-opus-5` under a `claude-opus-4-8` session) still dispatches instead of collapsing to inline. (Codex projects `models.codex.*`, OpenAI ids, separately and is unaffected by this.) **Never dispatch to an external-plugin agent** (a `gsd-*`, `*-reviewer`, `*-researcher`, `*-mapper`, or similarly named agent another installed tool registered): it follows *its own* protocol and artifact conventions (a foreign code-review agent writes its own review file, not trailhead's `VERIFY` ticket comment), silently swapping trailhead's engine for another tool's. Host built-ins (`Explore` / `general-purpose`) stay available in general but are **no longer the engine-dispatch target**. The tool policy is baked into each agent's `tools:` field, mirroring the old split: **read-only** (`trailhead-plan`, `trailhead-code-review`, `trailhead-codebase-map`, `trailhead-verify`: reads, searches, runs tests; no Edit/Write) vs **full** (`trailhead-executor`, `trailhead-research`, `trailhead-debug`, `trailhead-fix`: can Edit/Write/commit). **Search-command hygiene (every fan-out subagent, and any built-in `Explore`/`general-purpose` fan-out the engine leans on).** Prefer the Grep and Read tools over shelling out to search or read a file; when a Bash `grep`/read is genuinely needed, pass the path as an **explicit argument** (`grep -niE "<patterns>" <abs>/<file>`, `wc -l <abs>/<file>`) and run git as `git -C <abs> ...`. **Never `cd` (or `pushd`/`env -C`) into the target directory first, in any shape**: not `cd <abs> && grep <relative>`, not a bare `cd <abs>` line followed by a relative `grep`/`wc` on the next line or after a `;`, not inside a heredoc or any other multi-statement block, and not as its own separate Bash call or turn (the shell working directory persists across Bash calls, so a standalone `cd <abs>` still leaves a later relative read non-static). Any `cd` makes the post-`cd` working directory non-static, so under bypass permissions with a `Read()` deny rule the harness cannot resolve the read target against the allow rules and falls back to a manual approval prompt (defeating headless operation); a path-explicit target (absolute-path argument, `git -C`) stays statically determinable and runs uninterrupted regardless of how the statements are separated. When the engine spawns a built-in `Explore`/`general-purpose` search, state this rule in its spawn prompt. On a `subagentToolkit == none` host there is no fan-out and this is moot: every technique runs inline in the one session. (Codex is **not** such a host: it has the native multi_agent toolkit, so techniques fan out there too, dispatched by `agent_type` to the projected `~/.codex/agents/trailhead-*.toml`; see the Codex adapter's §D.)
+**Dispatch each technique to its trailhead-owned agent.** Every technique subagent carries its full protocol in the prompt (from its `techniques/` file), so the agent definition stays **thin**: identity + tool policy, model-agnostic. Dispatch each technique to **its own `trailhead-<technique>` agent** (set `subagent_type` accordingly): the Plan step → `trailhead-plan`, Execute → `trailhead-executor`, Research → `trailhead-research`, Code review → `trailhead-code-review`, Debug → `trailhead-debug`, Fix → `trailhead-fix`, Codebase map → `trailhead-codebase-map`, Goal-backward verification → `trailhead-verify`. These agents ship with trailhead (committed `agents/trailhead-*.md`) and are registered wherever trailhead is installed as a Claude Code **plugin** (its `agents/` load automatically), or its agent files are otherwise present as subagent types. **If a `trailhead-<technique>` agent is NOT registered in the current environment** (the `Agent`/`Task` tool reports the type unknown, or it is absent from the available-agents list, as on a skills-only install that did not register the agents), **run that technique inline in the main session**, following its `techniques/` protocol directly. Do **not** divert to a host built-in (`general-purpose`/`Explore`) or any external-plugin agent as the engine target. Inline is a graceful degradation: the technique still runs, only on the session model rather than its `config.models.<key>` pin (the same inline path used when that model equals the session model). The dispatch rule is therefore: the real `trailhead-<technique>` agent when it is registered, else inline in the main session, never a foreign agent. **Pass the `config.models.<key>` model as the `Agent`-tool `model` override at spawn** so config stays authoritative (the `.md` is model-agnostic; the override wins), running inline instead when that model is unset or equals the session model. Execute and Fix inject `trailhead-work/references/executor-brief.md` into their agent as the protocol text, not the whole step (the orchestrator part of the step stays with the session). On Claude Code the `Agent` tool's `model` parameter accepts only the short family aliases (`opus` / `sonnet` / `haiku` / `fable`), not the full ids `config.models.*` stores, so **map the configured id to its family alias only for the literal `model` value passed at spawn**: `claude-opus-*` -> `opus`, `claude-sonnet-*` -> `sonnet`, `claude-haiku-*` -> `haiku`, `claude-fable-*` -> `fable`; if an id matches none of these, don't guess: warn and inherit the session model (per `configuration-reference.md`). The alias names a family, not a version, so the host resolves it to that family's current model: the exact version the id pinned cannot be conveyed to the `Agent` tool and is not honoured at subagent spawn. **Keep the inline-vs-subagent decision on the full id**, running inline only when `config.models.<key>` is unset or its full id equals the session model's, never on the alias, so a deliberate same-family but different-version pin (e.g. `claude-opus-5` under a `claude-opus-4-8` session) still dispatches instead of collapsing to inline. (Codex projects `models.codex.*`, OpenAI ids, separately and is unaffected by this.) **Never dispatch to an external-plugin agent** (a `gsd-*`, `*-reviewer`, `*-researcher`, `*-mapper`, or similarly named agent another installed tool registered): it follows *its own* protocol and artifact conventions (a foreign code-review agent writes its own review file, not trailhead's `VERIFY` ticket comment), silently swapping trailhead's engine for another tool's. Host built-ins (`Explore` / `general-purpose`) stay available in general but are **no longer the engine-dispatch target**. The tool policy is baked into each agent's `tools:` field, mirroring the old split: **read-only** (`trailhead-plan`, `trailhead-code-review`, `trailhead-codebase-map`, `trailhead-verify`: reads, searches, runs tests; no Edit/Write) vs **full** (`trailhead-executor`, `trailhead-research`, `trailhead-debug`, `trailhead-fix`: can Edit/Write/commit). **Search-command hygiene (every fan-out subagent, and any built-in `Explore`/`general-purpose` fan-out the engine leans on).** Prefer the Grep and Read tools over shelling out to search or read a file; when a Bash `grep`/read is genuinely needed, pass the path as an **explicit argument** (`grep -niE "<patterns>" <abs>/<file>`, `wc -l <abs>/<file>`) and run git as `git -C <abs> ...`. **Never `cd` (or `pushd`/`env -C`) into the target directory first, in any shape**: not `cd <abs> && grep <relative>`, not a bare `cd <abs>` line followed by a relative `grep`/`wc` on the next line or after a `;`, not inside a heredoc or any other multi-statement block, and not as its own separate Bash call or turn (the shell working directory persists across Bash calls, so a standalone `cd <abs>` still leaves a later relative read non-static). Any `cd` makes the post-`cd` working directory non-static, so under bypass permissions with a `Read()` deny rule the harness cannot resolve the read target against the allow rules and falls back to a manual approval prompt (defeating headless operation); a path-explicit target (absolute-path argument, `git -C`) stays statically determinable and runs uninterrupted regardless of how the statements are separated. When the engine spawns a built-in `Explore`/`general-purpose` search, state this rule in its spawn prompt. On a `subagentToolkit == none` host there is no fan-out and this is moot: every technique runs inline in the one session. (Codex is **not** such a host: it has the native multi_agent toolkit, so techniques fan out there too, dispatched by `agent_type` to the projected `~/.codex/agents/trailhead-*.toml`; see the Codex adapter's §D.)
 
 **Reviews never block the session (engine-wide, every host).** The three **review** techniques, **Code review** (build/bug Verify), **Goal-backward verification** (build/bug Verify), and **Cross-AI plan review** (build Plan), always run as a **background job collected by polling**, never a blind open-ended blocking wait. This is a hard default: not a `config` toggle, and not a Codex-only or fallback posture. Because trailhead works one ticket at a time and Resolve depends on the review's outcome, "background" here means a **poll loop with a one-line progress note, the session responsive and interruptible between polls**, the outcome always awaited; what is banned is the blind freeze, never "proceed without the result." On Claude Code the `Agent` tool already backgrounds the review and notifies on completion, so poll its progress instead of awaiting it blindly; on Codex, collect it through the §D bounded-wait poll loop (external plan-review CLIs via §H). **Acceptance testing is excluded**: it is interactive by design (guided UAT / browser-drive with the user in the loop), not a blind wait to background.
 
+**Malformed review report (every engine-agent report).** The leading `status:` line, and the fields each report must carry, are machine-checked before the engine branches on them. This MUST run on every Code review and Goal-backward verification report and on every plan, executor, fix, debug, research and codebase-map report, whether it came from the subagent, an inline pass, or the lean inline pass; the report-status checker is `trailhead-report-status.js`, one JSON line `{"action","verdict","problem","report","fields","body"}` with `action` one of `accept` / `normalise` / `reask`. The return contract of each family (statuses, required fields, invariants) is stated once in the agents' `Return contract` blocks; the checker enforces it.
+
+1. **Check.** Per report run `mktemp -d` once (a private 0700 random directory); write the raw report to `<that dir>/report.md` with the Write tool at the literal printed path; run `node <templates>/trailhead-report-status.js --technique <verify|code-review|plan|executor|fix|debug|research|codebase-map> --file <that dir>/report.md`, where `<templates>` is the first of `${CLAUDE_PLUGIN_ROOT}/templates/` (skipped when unset), `~/.claude/trailhead/templates/` and `~/.codex/skills/trailhead/templates/` that contains it; then `rm -rf <that dir>` with the literal absolute path. Cleanup runs after every path: accept, normalise, each re-ask check, a second failure, and a checker failure. Never a fixed or predictable path, never reused. The checker also reads stdin, but this protocol does not use it (a heredoc would put the report into the shell-scanned command and needs a delimiter the report cannot contain).
+2. **Accept or normalise.** The checker-returned `report` replaces the raw report where the technique places it (the layout below); the engine branches only on the returned `verdict`, and reads the returned `fields` (and, for a `ready` plan, `body`) instead of re-deriving them from the prose of the report.
+3. **Reask.** Ask once: continue the same agent where the host allows it, else re-dispatch the same `trailhead-<technique>` agent on the same model override with the malformed report quoted, using this corrective prompt verbatim (placeholders filled): "Your report could not be accepted: `<problem>` (missing: no `status:` line; unknown-token: `<found>` is not an allowed token; conflicting: more than one `status:` line, so quote or reword any status text in the body, which must not start a line with `status:` outside a code fence or blockquote; counts: the counts line is missing or repeated; fields: a required field is missing or an invariant is broken). Return the complete report again with its first line exactly `status: <token>`, where `<token>` is one of `<allowed tokens>`, and no other `status:` line<for code-review: , and its second line exactly `critical: <n> · warning: <n> · info: <n>`><for fields: , with each of `<required fields>` as a top-level `<label>:` line and `<the broken invariant>` holding, with nothing after the last field>. Do not post it anywhere." For code-review the prompt always restates both required lines; for `fields` it names the missing or empty fields and the invariant that broke.
+4. **Re-check the reply** the same way. Still a reask: no verdict, nothing posted for that round, no third ask, no inference from the body. Surface a HITL checkpoint in the chat naming the technique and the problem; Resolve stays blocked, and so does any step that needed the report; for a review the previous `VERIFY` comment stays latest.
+5. **No checker.** If the checker is missing, fails with exit 2, or prints non-JSON, apply the same rules by hand: the prose above stays the spec. Never guess a verdict.
+
+**VERIFY comment layout (the reviewing pair only).** There is one `VERIFY` comment per Verify round, in this order: (1) the checker-returned code-review report verbatim (`status:` line 1, counts line 2, ledger, findings); (2) a `## Goal-backward verification` heading followed by the checker-returned verify report verbatim (its own `status:` first); (3) the test/criterion outcome, then any acceptance-testing results. A code-review round ending `issues_found` posts parts 1 and 3 only. A round re-running only goal verification repeats the latest checker-returned code-review report verbatim as part 1, so the latest `VERIFY` comment always holds the authoritative counts line and ledger (where the Disposition gate reads them). The engine branches on the checker `verdict`, never by reading the comment back.
+
 | Technique | File | In one line |
 |---|---|---|
 | **Grilling** | `techniques/grilling.md` | interrogate the human, one question at a time, to converge on a decision |
@@ -17,5 +27,5 @@ The ticket engines call these by name. Each technique's full protocol lives in i
 | **Debug** | `techniques/debug.md` | scientific method: reproduce → localise → falsifiable hypotheses → confirm cause → verify |
 | **Code review** | `techniques/code-review.md` | review the ticket's own commits (its `Refs: #<n>` set) on 4 axes, adversarially verify each finding before reporting |
 | **Goal-backward verification** | `techniques/verify.md` | check the change delivers what the ticket promised, working backward from its stated goal |
-| **Acceptance testing** | `techniques/acceptance-testing.md` | prove it does what the *user* wanted: ask who drives (AI or human), then automated → browser-drive → guided UAT |
+| **Acceptance testing** | `techniques/acceptance-testing.md` | prove it does what the *user* wanted: ask who drives (AI or human, or skip), then automated → browser-drive → guided UAT |
 | **Cross-AI plan review** | `techniques/plan-review.md` | send a PLAN to external AI CLIs, converge on their concerns (opt-in via `config.plan_review`) |

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

@@ -8,7 +8,7 @@ argument-hint: "[new|adopt|work|quick|whiteboard|ticket|inbox|map|dashboard|conf
 
 ## Load first, in order
 
-Before doing anything, read `../_shared/load-first.md` and follow it: the shared-core load contract (the six core files, in order, then the effective config). `_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.
+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.
 
 ## Routing: verb to engine
 

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

@@ -9,7 +9,7 @@ argument-hint: "[bug|todo|idea|seed|note] [--of <ticket>] <text>"
 
 ## Load first, in order
 
-Before doing anything, read `../_shared/load-first.md` and follow it: the shared-core load contract (the six core files, in order, then the effective config). `_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.
+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.
 
 A capture writes at most one issue; no isolation workspace is set up.
 

package/plugins/trailhead/skills/trailhead-capture/references/capture.md

@@ -6,12 +6,12 @@ Capture without breaking flow, but with the **tracker** as destination, not scat
 
 **Language (do not skip):** the captured ticket (title + body) is written in `config.ticket.language` (default `en`), **regardless of the language you are chatting in**. A capture fired in Italian still lands as an English ticket. This is the easiest place to slip, because a capture echoes the user's one-line phrasing; translate it, do not mirror it. See the *Ticket language* rule in `../../_shared/ticket-language.md`.
 
-**Map or whiteboard:** a capture that produces a **ticket** (`todo`, `bug`, `seed`, and `idea` when it is sharp enough) must land on a **map** or on the **whiteboard** (map-less). **When a map is open, ask the user which** before creating it (active map vs whiteboard; several maps open -> the ask also picks the map). **Map eligibility is "is the map open", not "is it still in progress".** An **exhausted** map (destination reached) that is **still open** stays a valid capture target: a capture thematically tied to it is offered that map on the which-map ask, never silently dropped to the whiteboard just because the destination was reached (that would sever the thematic link). The exhausted state is a reason to *offer to close the map* (the dashboard's `exhausted · closeable` flag, see the dashboard freshness rule in `../../_shared/substrate.md`), never a reason to drop it as a capture target. Only a **closed** map is no longer eligible: then the whiteboard is the right fallback. Whiteboard tickets get the `trailhead:whiteboard` label and **no** map label or `Parent:`; map tickets get the map's `trailhead:map-<n>` label + native sub-issue edge. **No map open at all -> whiteboard, no ask** (nowhere else to go). `note` and a non-sharp `idea` stay map-fog and skip this; with no open map they fall back to the global notes location (`$HOME/.claude/notes/`), or a now-sharp `idea` becomes a whiteboard ticket. **When a capture creates a whiteboard ticket, refresh the pinned dashboard** afterwards (a structural event: the whiteboard surface the dashboard indexes grew, and a whiteboard ticket has no native progress bar, so the dashboard is the only place it shows); a capture landing on a *map* does not (native sub-issue progress bars track map tickets). See *The whiteboard* and the dashboard freshness rule in `../../_shared/substrate.md`.
+**Map or whiteboard:** a capture that produces a **ticket** (`todo`, `bug`, `seed`, and `idea` when it is sharp enough) must land on a **map** or on the **whiteboard** (map-less). **When a map is open, ask the user which** before creating it (active map vs whiteboard; several maps open -> the ask also picks the map). **Map eligibility is "is the map open", not "is it still in progress".** An **exhausted** map (destination reached) that is **still open** stays a valid capture target: a capture thematically tied to it is offered that map on the which-map ask, never silently dropped to the whiteboard just because the destination was reached (that would sever the thematic link). The exhausted state is a reason to *offer to close the map* (the dashboard's `exhausted · closeable` flag, see the dashboard freshness rule in `../../_shared/substrate.md`), never a reason to drop it as a capture target. Only a **closed** map is no longer eligible: then the whiteboard is the right fallback. Whiteboard tickets get the `trailhead:whiteboard` label and **no** map label or `Parent:`; map tickets get the map's `trailhead:map-<n>` label + native sub-issue edge. **No map open at all -> whiteboard, no ask** (nowhere else to go). The ask is also skipped for a `bug --of` whose origin resolves to an open map or the whiteboard (see the `bug` bullet in the capture forms). `note` and a non-sharp `idea` stay map-fog and skip this; with no open map they fall back to the global notes location (`$HOME/.claude/notes/`), or a now-sharp `idea` becomes a whiteboard ticket. **When a capture creates a whiteboard ticket, refresh the pinned dashboard** afterwards (a structural event: the whiteboard surface the dashboard indexes grew, and a whiteboard ticket has no native progress bar, so the dashboard is the only place it shows); a capture landing on a *map* does not (native sub-issue progress bars track map tickets). See *The whiteboard* and the dashboard freshness rule in `../../_shared/substrate.md`.
 
 - **`note`** → a verbatim line in `## Not yet specified` (outside a project → `$HOME/.claude/notes/`). No questions, no rewriting.
 - **`idea`** → fog by default in `## Not yet specified`; becomes a ticket only if already phrasable as a sharp question. An idea in the fog is **not executable**: to work it, it must first **graduate** into a ticket (which happens when the frontier reaches it, or when you can now phrase it sharply). A `todo`, by contrast, is born a `build` ticket and is workable immediately.
 - **`todo`** → a small `trailhead:build` ticket on the frontier (defined work you will do: a todo is just a small build ticket). If it's a parking spot *beyond* the destination, it goes in `## Out of scope` instead.
-- **`bug`** → a `trailhead:bug` ticket on the frontier; the repro in the body if you know it. If it blocks the ticket you're working, add it to that ticket's `## Blocked by` and label that ticket `trailhead:blocked`. Pass **`--of <ticket>`** (a number, `#n`, name, or URL) to record it as a `Regression of: <ticket>` pointer in the body; use it for a bug in already-closed work, which is always a *new* ticket, never a reopen (see the `bug` engine for the reopen exception). **Don't derail**: capture and continue; you resolve it in a dedicated session.
+- **`bug`** → a `trailhead:bug` ticket on the frontier; the repro in the body if you know it. If it blocks the ticket you're working, add it to that ticket's `## Blocked by` and label that ticket `trailhead:blocked`. Pass **`--of <ticket>`** (a number, `#n`, name, or URL) to record it as a `Regression of: <ticket>` pointer in the body; use it for a bug in already-closed work, which is always a *new* ticket, never a reopen (see the `bug` engine for the reopen exception). **`--of` also inherits the origin's destination instead of asking** "whiteboard or which map?". Resolve the origin to an issue number first (a number, `#n` or URL parses directly; a name is resolved by a title search, `gh issue list --state all --search "<name> in:title"`, asking the user when it matches none or several), then read its labels: `gh issue view <origin> --json labels,title`. If the origin carries exactly one `trailhead:map-<n>`, check that map's state, `gh issue view <n> --json state,title`: **open** -> land on map `<n>` (its label + native sub-issue edge + `Parent:`), no ask; **closed** -> fall back. If it carries `trailhead:whiteboard` (and no map label), land on the whiteboard, no ask (dashboard refresh as for any whiteboard capture). Fall back to the existing Map or whiteboard rule (ask when a map is open, whiteboard when none) when the origin map is closed, when the origin carries neither label (a pre-whiteboard ticket, a map, a non-trailhead issue), when the labels are contradictory (both whiteboard and a map label, or several map labels), or when any lookup fails; never guess between conflicting labels. **Confirmation line** on an inheriting capture: name the destination as inherited from the origin, the map by name and number (or the whiteboard), and the origin by name and number; on a fallback say nothing about inheritance. **Don't derail**: capture and continue; you resolve it in a dedicated session.
 - **`seed`** → a ticket labelled `trailhead:seed` + `trailhead:blocked`, kept in its own `## Blocked by` until the trigger fires; note the trigger in the body. When the trigger fires, drop both labels to graduate it onto the frontier.
 
 **note · idea · seed · todo form a spectrum** of commitment and timing (`bug` is separate: a defect, not a capture-tier):

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

@@ -9,7 +9,7 @@ argument-hint: "[new|adopt|ticket|inbox|grill] [idea | <type> <title> | issue |
 
 ## Load first, in order
 
-Before doing anything, read `../_shared/load-first.md` and follow it: the shared-core load contract (the six core files, in order, then the effective config). `_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.
+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.
 
 ## Routing: verb to engine
 

package/plugins/trailhead/skills/trailhead-chart/references/charting.md

@@ -10,7 +10,7 @@ The user invokes with a loose idea.
 2. **Map the frontier.** Grill again, **breadth-first**: **enumerate every functional area the destination implies** and **capture each one (headed for a fog entry under *Not yet specified* at minimum) before deep-diving any single area**. Fan out across the whole space rather than deep on one thread, surfacing the open decisions and the first steps takeable now. **The deliverable is the coverage the map will carry, not the grilling transcript: every area the destination implies must land on the map at step 3, as fog or as a ticket, so nothing is silently missing.** **If no fog surfaces** (the way is already clear, the whole thing fits one session) you don't need a map: stop and ask how to proceed. **Harvest parked work:** from **earlier maps on this repo**, gather the artifacts their *Out of scope* `→ future map` breadcrumbs point at (**parked seeds/todos**, see **Out of scope**) **and the ideas** left in their *Not yet specified* fog, then **ask the user which belong in *this* map**; pull the chosen seeds/todos in as tickets and the chosen ideas in as fog (or as tickets, if now sharp enough), and leave (or update the destination on) the rest.
 3. **Create the map** (`trailhead:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into *Not yet specified*. **Every functional area enumerated in step 2 must appear here, as a fog entry or a ticket, before moving on: the map is the coverage deliverable.** Run the **first-use repo setup** (see **Substrate** → `../../_shared/substrate-commands.md`) now: labels **and** the label-guard check/install. Once the map issue has its number `<n>`, **create its per-map label `trailhead:map-<n>`** (every ticket of this map carries it and is a native sub-issue of the map; the map issue itself is found by its number, so it does **not** carry the label; see **Multiple maps on one repo**). **If this repo already has another open `trailhead:map`**, tell the user the new map runs concurrently (its own scoped frontier) and set it as the active map (`.trailhead/active-map`). Then set up **conventions**: if no `trailhead:conventions` issue exists, run a **brief conventions brainstorming** (breadth-first, in the spirit of grilling but short: a handful of questions, not a full session) to surface the project's way of working: `git:` `main`|`pr`, `release:` `command`|`auto`, and `isolation:` `auto`|`none`|`worktree`|`clone` (default **`auto`**, which decides per ticket at work-start by asking *"will more than one ticket be worked at once on this machine this session?"* and picking `worktree` for a plain repo or `clone` for a submodule superrepo; a project can force `none`/`worktree`/`clone` explicitly), **plus** the narrative a new contributor would need: release/deploy specifics (environments, manual steps, OTA vs full build, versioning), tooling that must be driven a certain way (a specific MCP/CLI, e.g. a Lovable project piloted via its MCP), code & style rules, testing/UAT norms. Distil into the issue (header + prose); link it from the map's Notes. Don't invent: leave out or ask what you can't determine. If one already exists, just link it (reuse across maps). Finally, **ensure the repo's `trailhead:dashboard` index issue exists** (see **The dashboard**): create and pin it if missing (the fixed 3rd pinned slot, alongside codebase + conventions), then **write it to list this map** (charting a map is a structural event); if it already exists, refresh it.
 4. **Create the tickets you can specify now** as child issues (each with `trailhead:ticket` + its type + this map's `trailhead:map-<n>` label, **plus `trailhead:blocked` when the mapped dependency graph already shows it has a blocker**, and set as a **native sub-issue** of the map, see **Child→map link** under Substrate), then wire the blocking in a **second pass** (issues need ids before they can reference each other): for each ticket **read its Question and wire a blocker for every still-open ticket whose output it consumes** (don't stop at the first/obvious one) by wiring its `## Blocked by` line + native dependency together (moves 1-2 of the three-move wiring; the `trailhead:blocked` label, move 3, already rode in at creation, see **Substrate**). **Set the blocked label at creation, not via a post-creation `--add-label` pass:** a bulk `--add-label` burst spawns one repo-side label-guard run per ticket and reddens the Actions history with sheddable no-op runs; riding the label in the ticket's `issues.opened` event avoids that entirely. Wiring sorts them into frontier (unblocked) and blocked; the rest stays fog.
-5. **Fire the research subagents.** For each `research` ticket created, run the **Research** technique in parallel, findings on a `research/<name>` branch with a pointer from the ticket.
+5. **Fire the research subagents.** For each `research` ticket created, run the **Research** technique in parallel; each agent returns its report, and the orchestrator posts it on the ticket as a `RESEARCH` comment (no branch: the report is the artifact; see the technique for the `found` / `inconclusive` / `needs_input` branches).
 6. **Offer config, then stop.** Charting is one session's work; it hand-resolves nothing. Before ending, make the **first-time config offer** (see **First-time config offer** in `../SKILL.md`): the project now has a fresh map and no `.trailhead/config.json`, so put the **two-way choice** to the user, **accept as-is** (writes `{}`) or **run `/trailhead:config`** for the guided menu, and let them pick. Name both paths; don't pre-fill the config keys and ask for an inline edit, and don't interview them key-by-key here (that's `/trailhead:config`'s job). Once the file exists it's never offered again. **No `trailhead:codebase` issue is created here**: greenfield has no code to map yet. It's created later, once the repo has substantial code (see Mode 2 step 1 and the **Codebase** row under Substrate), so at chart two of the three permanent pins (the dashboard + conventions) are filled and the codebase slot fills in later. Maps are never pinned.
 
 **Next-step block (the close of chart, and of adopt).** Charting hand-resolves nothing, so the **Session handoff** ritual (`../../_shared/session-handoff.md`) does not fire here; render this codified next-step block instead, **right after the first-time config offer above**, styled on the handoff's own next-step block and written in the user's conversation language. Newly charted tickets are **map-frontier** tickets, so the primary move is `/trailhead:work` (the full engine: it can split and keeps the map record), with `/trailhead:quick` only as the off-map alternative. Every bullet below is a thing to do **after** the `/clear`, which leads; never point at the next command without it, and never demote `/clear` to a trailing parenthetical.

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

@@ -9,7 +9,7 @@ argument-hint: "[config|update|prune|audit] [get|set … | map | --all]"
 
 ## Load first, in order
 
-Before doing anything, read `../_shared/load-first.md` and follow it: the shared-core load contract (the six core files, in order, then the effective config). `_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.
+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.
 
 These admin verbs resolve no ticket and set up no isolation workspace.
 

package/plugins/trailhead/skills/trailhead-manage/references/auditing.md

@@ -123,7 +123,7 @@ The marker advance is the **last proposal** of the run, shown with its value and
 - The value is the **cutoff captured in step 2**, never the completion time, so a ticket closed mid-run falls into the next window.
 - An **unchanged** or **evolved** ticket never rewinds the marker.
 - If any ticket was flagged **unverifiable**, in whole or in part (step 4 or step 6), write instead the earliest unverifiable ticket's `closedAt` minus one second (never past the cutoff), so the next default run picks it up again. No extra state, nothing silently dropped.
-- Write it into the dashboard body with the fail-safe read-modify-write (see Body generation in `../../_shared/substrate-commands.md`). `--all` advances it the same way.
+- Write it into the dashboard body: default path `node <templates>/trailhead-dashboard.js --set-last-audit <ISO-8601 UTC>` (the only writer path for the marker; `<templates>` is the same three-dir lookup as `trailhead-work-state.js`, see **Work state file** in `../../_shared/teamwork.md`), or, when the helper is missing, by hand with the fail-safe read-modify-write (see Body generation in `../../_shared/substrate-commands.md`). `--all` advances it the same way.
 
 ## Notes
 

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

@@ -9,7 +9,7 @@ argument-hint: "[map|dashboard|whiteboard] [map]"
 
 ## Load first, in order
 
-Before doing anything, read `../_shared/load-first.md` and follow it: the shared-core load contract (the six core files, in order, then the effective config). `_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.
+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.
 
 These are read-only renders: no isolation workspace is set up.
 
@@ -31,8 +31,9 @@ A single `trailhead:map` issue is the canonical artifact: an **index**, not a st
 
 Render, by name:
 - **Destination**: the one-line where-we're-headed.
-- **Frontier**: takeable now (open, unassigned, not blocked/unverified, and **not** `trailhead:whiteboard`, which has its own view), each with its type. Present independent tickets as a **set to choose from**, not a crowned first (see **Frontier order carries no priority** in `../_shared/substrate.md`).
+- **Frontier**: takeable now (open, unassigned, not blocked/unverified, **not** `trailhead:paused`, and **not** `trailhead:whiteboard`, which has its own view), each with its type. Present independent tickets as a **set to choose from**, not a crowned first (see **Frontier order carries no priority** in `../_shared/substrate.md`).
 - **In progress**: claimed tickets, with who holds each.
+- **Paused**: tickets set aside on a `PAUSED` checkpoint (`trailhead:paused`), shown once here whatever their assignee or blocked state, with the holder if any; take one back with `/trailhead:resume <n>`.
 - **Blocked**: with what each waits on; flag any **blocked-by drift** (prose `## Blocked by` differs from the native dependency, see **Blocked-by reconciliation** in `../_shared/substrate.md`) as an advisory line.
 - **Decisions so far**: the index of what's settled.
 - **Not yet specified** + **parked fog**: the coarse fog with **each top-level entry numbered** (`1.`, `2.`, ...; one number per top-level bullet or line, numbered top-to-bottom in displayed order and restarting at 1 on every render, nested sub-points not numbered separately), and a count/link of open `trailhead:fog` issues. The numbers are a **render-time handle**, stable within a single render and never persisted into the map body: they exist so a specific fog point can be named by its number when offering to dissolve or graduate one. Resolve any number the user gives against the **current** render's list; if the map changed since it was rendered, re-render and confirm the point before graduating it.
@@ -70,11 +71,11 @@ A repo's trailhead surface is spread across issues: one or more maps, a whiteboa
 
 It holds:
 - a link to **every open `trailhead:map`** (found via the `trailhead:map` label); GitHub renders each map's sub-issue **progress bar natively**, so the dashboard only links, it never recomputes per-ticket progress. **Per open map it also runs one cheap `0 open scoped issues?` pre-filter** and, for a candidate confirmed to have no remaining fog (see the exhaustion check in `../_shared/substrate-commands.md`), flags an **exhausted-but-open** map (destination reached, map issue never closed) as `exhausted · closeable`, so the render can offer to close it (below). It also flags each open map **`near cap · <total>/100`** (total >= 90) or **`at cap`** (total >= 100) from `sub_issues_summary.total`, appending **`· prunable`** when the map has closed edges to reclaim, so the render can offer `/trailhead:prune` (below);
-- the **whiteboard** as its own section (frontier / in-progress / blocked, or a link to the `whiteboard` view);
+- the **whiteboard** as its own section (frontier / in-progress / paused / blocked, or a link to the `whiteboard` view);
 - dynamic **counts**: untriaged inbox size, whiteboard frontier size.
 - a hidden `<!-- trailhead:last-audit <ISO-8601 UTC> -->` line, when the body already has one, is **preserved verbatim** on every regeneration (it is the `/trailhead:audit` window marker; see Body generation in `../_shared/substrate-commands.md`).
 
-**`dashboard`** regenerates the pinned issue body from the live tracker and shows it, both the render and the on-demand refresh, consistent with `map` and `whiteboard`. It creates and pins the issue if the repo doesn't have one yet (ensuring the `trailhead:dashboard` label first, idempotently). The exact gh commands (find, pin/re-pin/unpin, self-heal, body generation with the count queries) are in `../_shared/substrate-commands.md`.
+**`dashboard`** regenerates the pinned issue body from the live tracker and shows it, both the render and the on-demand refresh, consistent with `map` and `whiteboard`. The default path is the template helper `node <templates>/trailhead-dashboard.js` (`<templates>`: the same three-dir lookup as `trailhead-work-state.js`, see **Work state file** in `../_shared/teamwork.md`; `--dry-run` previews the outcome and the old and new body sizes without writing): it gathers the tracker data, renders the whole body deterministically (the body is fully generated, so hand-written prose from an older dashboard is replaced by tracker data and stays in the issue's edit history), self-heals the label and pin, and writes through the guarded body write; the agent then shows the result and makes the offers below. When the helper is missing, do it by hand per the spec below. It creates and pins the issue if the repo doesn't have one yet (ensuring the `trailhead:dashboard` label first, idempotently). The exact gh commands (find, pin/re-pin/unpin, self-heal, body generation with the count queries) are in `../_shared/substrate-commands.md`.
 
 **Exhausted-but-open maps: flag and offer to close.** The one-shot "close this map?" prompt fires only at the exhaustion moment (a `work` handoff, or a `map` render on the exhausted map). If that moment was skipped, or the user chose to leave the map open, an exhausted map lingers with nothing re-surfacing it. So the dashboard is the recurring surface that catches it: for every open map flagged `exhausted · closeable` (the `0 open scoped issues?` pre-filter confirmed against remaining fog, see `../_shared/substrate-commands.md`), the render **offers to close it** (route any un-parked deferred *Out of scope* line first, exactly as the `map` exhaustion check does), `gh issue close` on a yes, leave it open on a no. Never auto-close: flag + offer only. The count runs per map, but the body read (fog confirm + deferred routing) is bounded to the exhausted candidates, so this stays within the dashboard-only-links spirit.
 
@@ -98,12 +99,13 @@ Not all work belongs to a map. A **bug**, a **todo**, or a one-off **task** may
 It has its **own frontier**, off every map's (see **Map frontier vs whiteboard frontier** in `../_shared/substrate.md`):
 ```bash
 gh issue list --label "trailhead:ticket" --label "trailhead:whiteboard" --state open \
-  --search "no:assignee -label:trailhead:blocked -label:trailhead:unverified"
+  --search "no:assignee -label:trailhead:blocked -label:trailhead:unverified -label:trailhead:paused"
 ```
 
 **`whiteboard`** renders this as a read-only view, a mirror of the `map` render minus destination, decisions, and fog (the whiteboard has no direction, only loose work), by name:
-- **Frontier**: takeable now (open, unassigned, not blocked/unverified whiteboard tickets), each with its type. Present independent tickets as a **set to choose from**, not a crowned first (see **Frontier order carries no priority** in `../_shared/substrate.md`).
+- **Frontier**: takeable now (open, unassigned, not blocked/unverified and **not** `trailhead:paused` whiteboard tickets), each with its type. Present independent tickets as a **set to choose from**, not a crowned first (see **Frontier order carries no priority** in `../_shared/substrate.md`).
 - **In progress**: claimed whiteboard tickets, with who holds each.
+- **Paused**: whiteboard tickets set aside on a `PAUSED` checkpoint (`trailhead:paused`), shown once here whatever their assignee or blocked state, with the holder if any; take one back with `/trailhead:resume <n>`.
 - **Blocked**: any blocked whiteboard ticket, with what it waits on (a whiteboard ticket can still block on another).
 
 **Dashboard self-heal.** Like the `map` render, ensure the repo's pinned `trailhead:dashboard` index exists and is pinned before rendering (create + pin only if missing, re-pin if the pin was dropped; never rewrite its body here). See the **Render the dashboard** self-heal above.

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

@@ -9,7 +9,7 @@ argument-hint: "[work|quick|pause|resume|split|auto] [ticket | \"text\" | note]"
 
 ## Load first, in order
 
-Before doing anything, read `../_shared/load-first.md` and follow it: the shared-core load contract (the six core files, in order, then the effective config). `_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.
+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.
 
 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.
 
@@ -38,30 +38,32 @@ 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). 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) 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`). 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 ask the user once whether they will work more than one ticket at once on this machine this session. **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. Because trailhead resolves one ticket per session, this asks at most once per ticket work-start (so once per session in normal work; a within-session ticket switch re-asks at the new ticket's work-start), and 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. 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`.
    - **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, 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.
-   - **When the resolved mode is `worktree` or `clone` (explicit, or `auto` answered yes), set up the isolated workspace NOW, before any file edit or diagnostic probe** (not later at Execute/Fix): **if the repo has submodules (a `.gitmodules`), `isolation: worktree` is escalated to `clone`** (a superproject worktree cannot safely carry submodule state; see `../_shared/teamwork.md`). For `worktree` (no submodules), create/enter this ticket's `git worktree` on a `trailhead/t<n>` branch for the package/path the ticket's `Scope:` names (a submodule-bearing repo would have escalated to `clone` above), e.g. `git worktree add ../<repo>-t<n> -b trailhead/t<n>`; for `clone`, make an independent working copy at `../<repo>-t<n>` (branch `trailhead/t<n>`) by whichever is faster: `git clone` (add `--recurse-submodules` when the repo has submodules) + the install step, or a **folder copy that brings `node_modules`** (and the submodule working trees) to skip the reinstall (then verify the copy's git is independent, `git -C <copy> rev-parse --absolute-git-dir` resolves inside it, and the same inside every submodule, else commits leak back to the original); a clone with submodules is provisioned via `git submodule update --init --recursive` (nested included), each scoped submodule pinned at the superproject's recorded commit. **If this `clone` was reached via `auto`'s work-start ask (answered yes), that ask already served as the clone gate: do not re-ask, proceed to set up the clone. Under an explicit `isolation: clone`, run the gate as follows.** **Because `clone` is heavy (a full clone + an install), gate it, every time, before cloning: ask the user whether they expect to work more than one ticket at once on this machine this session.** If **no**, **skip the clone** and work this ticket in the current checkout (isolation only exists to stop concurrent workspaces from colliding; a lone ticket has nothing to collide with, so the shared-checkout caveats apply and that is fine, and `git:` still decides the branch as usual); if **yes**, clone as above. The gate is **`clone`-only**: `worktree` is cheap, so set it up without asking. Do every subsequent step in whatever workspace you ended up in. This is the whole point of isolation: if you diagnose and edit in the shared checkout "just to start" while a concurrent workspace exists, you are already colliding. Set the workspace up silently (the `clone` gate-question is the one exception you voice); it's undone at Resolve when the branch integrates and the worktree/clone is removed. See `../_shared/teamwork.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.
+   - **Backfill the UAT label once per clone**: at the working root, run `node <templates>/trailhead-uat-backfill.js --repo <owner/name> --marker <working-root>/.trailhead/uat-backfill` (same `<templates>` lookup as the commit-msg sync; pass the marker as an absolute path, since the shell may not sit at the working root). It tags any open ticket with a `UAT of:` line with `trailhead:uat` (a pending UAT follow-up opened before the label existed), and writes the `.trailhead/uat-backfill` marker itself only on a clean run, so later work-starts exit `skipped` with no `gh` call. **Keep the marker gitignored** (add `.trailhead/uat-backfill` to that repo's `.gitignore` if absent): per-clone local state, never committed. Stay silent when it tagged nothing or skipped; when it tagged tickets, one result-oriented line saying how many pending UAT follow-ups now carry the label; on `failed` entries or an `error` status, one line saying the backfill did not finish and will retry at the next work-start.
+   - **When the resolved mode is `worktree` or `clone` (explicit, or `auto` answered yes), set up the isolated workspace NOW, before any file edit or diagnostic probe** (not later at Execute/Fix): **if the repo has submodules (a `.gitmodules`), `isolation: worktree` is escalated to `clone`** (a superproject worktree cannot safely carry submodule state; see `../_shared/teamwork.md`). For `worktree` (no submodules), create/enter this ticket's `git worktree` on a `trailhead/t<n>` branch for the package/path the ticket's `Scope:` names (a submodule-bearing repo would have escalated to `clone` above), e.g. `git worktree add ../<repo>-t<n> -b trailhead/t<n>`; for `clone`, make an independent working copy at `../<repo>-t<n>` (branch `trailhead/t<n>`) by whichever is faster: `git clone` (add `--recurse-submodules` when the repo has submodules) + the install step, or a **folder copy that brings `node_modules`** (and the submodule working trees) to skip the reinstall (then verify the copy's git is independent, `git -C <copy> rev-parse --absolute-git-dir` resolves inside it, and the same inside every submodule, else commits leak back to the original); a clone with submodules is provisioned via `git submodule update --init --recursive` (nested included), each scoped submodule pinned at the superproject's recorded commit. **If this `clone` was reached via `auto`'s work-start ask (answered yes), that ask already served as the clone gate: do not re-ask, proceed to set up the clone. Under an explicit `isolation: clone`, run the gate as follows.** **Because `clone` is heavy (a full clone + an install), gate it, every time, before cloning: ask the user whether they expect to work more than one ticket at once on this machine this session.** If **no**, **skip the clone** and work this ticket in the current checkout (isolation only exists to stop concurrent workspaces from colliding; a lone ticket has nothing to collide with, so the shared-checkout caveats apply and that is fine, and `git:` still decides the branch as usual); if **yes**, clone as above. The gate is **`clone`-only**: `worktree` is cheap, so set it up without asking. Do every subsequent step in whatever workspace you ended up in. This is the whole point of isolation: if you diagnose and edit in the shared checkout "just to start" while a concurrent workspace exists, you are already colliding. Right after creating the workspace (before any install or build step), copy the declared gitignored files into it with `node <templates>/trailhead-isolation-copy.js --from <main-checkout> --to <working-root>`, per **Gitignored files in a new workspace** in `../_shared/teamwork.md`. Set the workspace up silently (the `clone` gate-question is the one exception you voice); it's undone at Resolve when the branch integrates and the worktree/clone is removed. See `../_shared/teamwork.md`.
    - **Write the work state, last** (the working root is final only now): `node <templates>/trailhead-work-state.js set --repo <working-root> --map <n> --ticket <n> --title "<title>" --step discuss`, and add `.trailhead/work-state.json` to that repo's `.gitignore` if absent. It is updated at every step change and cleared at Resolve; the canonical description, the `<templates>` lookup, and the silent-on-failure rule are the **Work state file** paragraph in `../_shared/teamwork.md`, and the step mapping per type is in `references/ticket-engines.md`.
-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 they want to change anything**. This is a HITL confirm gate: on assent, 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. 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.
+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*. 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*. 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). Maps aren't pinned, so there's no pin to free; the dashboard, codebase, and conventions stay pinned regardless.
+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.
+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`
 
 A streamlined way to just get one ticket done, without map ceremony. `quick "<text>"` opens a **whiteboard** ticket (a `build`, or a `bug` when the text is clearly a defect) and works it end to end now; `quick <n>` works an **existing** ticket (whiteboard or map) the same way. For `quick <n>`, the **Preflight** above runs first: a closed, out-of-scope, superseded, or nonexistent ticket stops immediately, before config, claim, or isolation setup. Claim it first; still one ticket per session. **Bare `/trailhead:quick`** (no argument, e.g. offered in a Session handoff) asks for the piece to work, like a capture missing its text, then proceeds as `quick "<text>"`.
 
 It runs the **full engine** (the `build`/`bug` cycle in `references/ticket-engines.md`: Discuss → Plan → Execute → Verify → Resolve), differing from `work` on these points:
-- **Briefs and confirms scope first, exactly as Work the map step 3.** With the ticket claimed, summarise what resolving it will do and ask whether to change anything, applying the same consistency rule (a divergent request is offered as work-as-is vs a separate new ticket, opened only if the user chooses it, never forced; via **Scope that surfaces while working a ticket**), and, exactly as Work the map step 3, if the user defers that 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. A just-written `quick "<text>"` needs only a one-line confirmation; `quick <n>` on an existing ticket gets the full brief.
+- **Briefs and confirms scope first, exactly as Work the map step 3.** Whether the menu is posed at all follows **Skip the confirm on a ticket this session already shaped** (Work the map step 3). When it is, with the ticket claimed, summarise what resolving it will do and pose the same scope-confirm menu (`AskUserQuestion`: **Proceed** (Recommended), **Change something**, delegate; numbered list on Codex), applying the same consistency rule (a divergent request is offered as work-as-is vs a separate new ticket, as the same no-delegate menu, opened only if the user chooses it, never forced; via **Scope that surfaces while working a ticket**), and, exactly as Work the map step 3, if the user defers that 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. Whether the menu is skipped follows **Skip the confirm on a ticket this session already shaped**: a `quick "<text>"` ticket gets the one-line note, no menu; `quick <n>` follows the same rule as `work`.
 - **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`.** `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 **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. `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** (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`.
+- **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.
+- **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.
 
 Type follows the ticket: `quick "<text>"` defaults to `build` (`bug` if a defect); `quick <n>` uses the existing type and its matching engine.