@marcomigozzi/trailhead 0.13.0 → 0.15.0

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

@@ -6,8 +6,10 @@ Every ticket is **HITL** (human in the loop, speaking for themselves) or **AFK**
 
 Technique names below (**Grilling**, **Domain vocabulary**, **Prototype**, **Research**, **TDD**, **Code review**, **Acceptance testing**, **Debug**) are indexed in `../../_shared/techniques.md`; their full protocols live in `_shared/`, read from `../../_shared/techniques/<name>.md`.
 
+**Work state (every type).** Keep `.trailhead/work-state.json` current with the `set --step` call in the **Work state file** paragraph of `../../_shared/teamwork.md`: `build` Discuss/Plan/Execute/Verify/Resolve set `discuss`/`plan`/`execute`/`verify`/`resolve`; `bug` Repro and Diagnose set `discuss`, Fix `execute`, Verify `verify`, Resolve `resolve`; `decision`, `prototype` and `task` stay `discuss` until `resolve`. A loop back from Verify to Execute (or Fix) sets `execute` again, and a UAT follow-up (`UAT of:`) sets `verify`. `research` tickets never write it: they run AFK and possibly in parallel, and the single file tracks only the one ticket in play.
+
 ## UAT follow-ups (any type)
-A ticket whose body carries `UAT of: <parent>` is a UAT follow-up, **whatever its type label**, including a graduated seed (a `trailhead:seed` that dropped `trailhead:seed` + `trailhead:blocked` on graduating, keeping whatever type label it had, or none). `work`, `quick`, and `auto` all dispatch through this file, so this check runs **before** the per-type engines below. It resolves via the **Acceptance testing** technique (`../../_shared/techniques/acceptance-testing.md`), starting with the drive-mode ask; the record is a `VERIFY` comment on the follow-up itself, never on the parent. It closes only on a confirmed pass, with a resolution comment linking back to the parent.
+A ticket whose body carries a `UAT of: [<parent name>](<parent url>)` line is a UAT follow-up (it also carries the `trailhead:uat` label, a marker that never changes the frontier; the body line stays the authority, since a ticket opened before the label existed is tagged by the backfill), **whatever its type label**, including a graduated seed (a `trailhead:seed` that dropped `trailhead:seed` + `trailhead:blocked` on graduating, keeping whatever type label it had, or none). `work`, `quick`, and `auto` all dispatch through this file, so this check runs **before** the per-type engines below. It resolves via the **Acceptance testing** technique (`../../_shared/techniques/acceptance-testing.md`), starting with the stale-base preflight (`trailhead-base-preflight.js`, **Stale-base preflight** in `../../_shared/teamwork.md`), then the UAT setup (`trailhead-uat-setup.js`, **UAT setup comes next** in the technique), and then the drive-mode ask; the record is a `VERIFY` comment on the follow-up itself, never on the parent. It closes only on a confirmed pass or an explicit waiver (the user's skip at the drive-mode ask, recorded in the `VERIFY` comment as unconfirmed; the follow-up closes as waived), with a resolution comment linking back to the parent and stating the waiver when there was one.
 
 ## `decision`: HITL, *default for decision tickets*
 Close a choice, but widen before you narrow:
@@ -18,7 +20,7 @@ Close a choice, but widen before you narrow:
 The two phases are distinct on purpose: divergence generates, grilling chooses. Never let the agent invent the options *and* pick for the human: the choice stays theirs.
 
 ## `research`: AFK
-Reading docs, third-party APIs, or local resources to surface a fact a decision waits on. Resolved by the **Research** technique. The only type that runs in parallel and more than one per session.
+Reading docs, third-party APIs, or local resources to surface a fact a decision waits on. Resolved by the **Research** technique, whose `trailhead-research` report the orchestrator checks and posts as a `RESEARCH` comment (see the technique). The only type that runs in parallel and more than one per session.
 
 ## `prototype`: HITL
 Raise the fidelity of the discussion with a rough, concrete artifact to react to: the **Prototype** technique. Link the prototype as an asset.
@@ -29,10 +31,18 @@ The ticket that *builds*. Lean cycle, all in **ticket comments**:
 **Size triage (`effort`-gated, before Discuss).** When `config.effort` is `lean`, run the **size triage and ask-to-skip offer defined canonically under effort in `../../_shared/configuration-reference.md`** before Discuss: classify the change, and on trivial/small surface the one consolidated offer (its skippable steps here: the plan subagent -> a short inline plan; TDD; Cross-AI plan review; the full Code-review subagent -> a lighter inline pass; the Goal-backward verification subagent -> a quick inline goal check), going lean **only on an explicit yes**. On `normal`, on a no/silence/ambiguity, and always under `effort: standard` (the default), run the full cycle below unchanged. The correctness spine (atomic `Refs:` commits, the tests / the plan's criterion, the post-commit self-check, Resolve) is never in the offer.
 
 1. **Discuss**: **never auto-grill.** Start from Plan. If reading the ticket surfaces blocking ambiguity, **stop and ask the user** whether they want a **Grilling** round: don't launch it on your own initiative. Only on their assent run the short round and post a `DISCUSS` comment with the closed choices. The user may also ask for it themselves at any time. Advisory choices raised here **offer** the delegate/defer options, per the injection recipe in `../../_shared/choices.md`.
-2. **Plan**: a `PLAN` comment: the steps, the seams, the files touched, the verification criteria. Apply **TDD** per `config.tdd` (`seams`/`on`/`off`). Produce this plan via a *planner subagent* on `config.models.plan` (dispatch the **`trailhead-plan`** agent, read-only, passing `config.models.plan` as the model override; inline when the model is unset or equals the session model; Execute then runs as its own subagent, see below). If `config.plan_review` is on, run **Cross-AI plan review** before Execute: send the plan to external AI CLIs and converge on their concerns. Now that the files/seam are known, run the **undeclared-coupling check** (`../../_shared/teamwork.md`) against in-progress tickets. **Plan to sufficiency:** stop once you can name the steps, seams, and files with confidence, and never re-read a file already read in this planning pass; act when you have enough to plan, rather than re-deriving what the pass already established. **The single exception:** under an accepted `lean` skip (see the Size triage above), produce a short inline plan here instead of the planner subagent, and skip Cross-AI plan review; absent that accepted skip, this step runs in full as described.
-3. **Execute**: **if this ticket changes user-facing UI (a new screen, a redesign, a changed layout), run the Prototype technique FIRST, before any real UI code**: surface a mockup to react to (its clickable link always in the same message as the approval question, per the Prototype technique), routed by `config.design` (disk / artifacts / stitch) and gated by `config.design.approval` (`explicit` waits for a go-ahead, `auto` proceeds after surfacing). **Route by `config.design` and never shortcut a hosted mode to a local disk mockup**: when `config.design` is `artifacts` (or the legacy `claude.ai/design`) or `stitch`, the mockup is built there (reusing a cached `design.project`); `disk` is only for `config.design: disk` or the technique's explicit, announced fallback, never a convenience default. Read `config.design` before producing anything. For a redesign or new screen the default is to offer mockups; don't jump straight to code on a UI ticket. **Once the mockup is approved, reproduce it with 100% fidelity** (layout, spacing, sizing, colour, type, copy, and every state), never a loose approximation "in the spirit of" it; if part of the approved mockup is genuinely infeasible, stop and raise it rather than silently deviate (full statement in the **Prototype** technique, `../../_shared/techniques/prototype.md`). **Make fidelity verifiable, not a hope:** before finishing Execute, enumerate the approved mockup's elements and states, confirm each is reproduced, and **record that enumerated fidelity list as a ticket comment** (noting any element raised as infeasible with its resolution), so Verify works from a durable checklist instead of reconstructing intent. At Verify, **Acceptance testing** checks the built screen against the approved mockup (element by element, state by state) and **Goal-backward verification** carries fidelity as an explicit goal claim (see `../../_shared/techniques/acceptance-testing.md` and `../../_shared/techniques/verify.md`). Then implement with **atomic commits** (conventional commits, each with a `Refs: #<n>` trailer for this ticket, see **Principles** in `../../_shared/principles.md`; the trailer is also what scopes Verify's review and goal check, per **Ticket diff** in `../../_shared/techniques/code-review.md`), following the repo's `trailhead:conventions` `git:`, straight to `main` by default, or a feature branch + PR when `git: pr`. **Under `isolation: worktree`, do the work in this ticket's `git worktree`** (`trailhead/t<n>` branch), integrating to the trunk at Resolve (see `../../_shared/teamwork.md`). One commit = one verifiable step. Run this via an **executor subagent on `config.models.execute`** (dispatch the **`trailhead-executor`** agent, full tools that can Edit/Write/commit, passing `config.models.execute` as the model override; inline when the model is unset or equals the session model); the commits land on `main`, visible. **Before installing any new dependency, run the verify-before-install gate** (slopsquatting barrier): check the package's legitimacy (name / typosquat similarity to popular packages, age / first-seen date, download counts, repository metadata present and matching) and **stop and ask the user on a suspicious result** (block-and-ask), never installing on your own judgement. On a host with a hook bus the `trailhead-install-guard` `PreToolUse` hook enforces this, blocking a named public-registry install (npm / PyPI / crates.io / Go / RubyGems) until it is vetted; once vetted, proceed by re-running the exact install command prefixed with `TRAILHEAD_VERIFIED_INSTALL=1`. New scope surfacing mid-execute is captured/split, not worked here.
-4. **Verify**: a `VERIFY` comment: run the tests / the plan's criterion; then the **Code review** technique, scoped to the ticket's own commits per its **Ticket diff** rule (`../../_shared/techniques/code-review.md`: the `Refs: #<n>` set, read per commit, recomputed each round, an empty set surfaced as an error, never a `<base>...HEAD` range) (its subagent reviews *adversarially*: it doesn't defer to a `CLAUDE.md` convention or a "settled decision" memory), and carries the review's counts line and findings ledger, per code-review.md, **run in the background and collected by polling, never a blind blocking wait** (a hard engine default on every host, see *Reviews never block the session* in `../../_shared/techniques.md`); **read the review's leading `status:` tag to branch deterministically: `status: clean` -> proceed to Resolve, `status: issues_found` -> iterate the fix-and-re-review loop (or run the HITL checkpoint) before resolving**; then the **Goal-backward verification** technique on `config.models.verify` (does the change deliver what the ticket promised, backward from its `Question` and the `PLAN`'s criteria; the read-only `trailhead-verify` subagent, on the same **Ticket diff** set), **run in the background and collected by polling** like Code review, branching on its leading `status:` tag (`status: met` -> proceed, `status: gaps_found` -> loop back to Execute for the gap or run the HITL checkpoint before resolving, `status: inconclusive` as the leading tag (all gaps cleared) -> a per-reason-class HITL checkpoint with no auto-retry, never auto-resolving over the unevaluated goal); then **Acceptance testing** if the change is user-facing, opening with the drive-mode ask (`../../_shared/techniques/acceptance-testing.md`): AI-driven, or **walk the user through a guided UAT conversationally, one step at a time**, never a checklist dumped in a comment: interactive by design, so it runs inline, not backgrounded. Report the outcome honestly (if a test fails, say so). **The single exception:** under an accepted `lean` skip, run a lighter inline review pass instead of the full Code-review subagent and a quick inline goal check instead of the full Goal-backward verification subagent (or skip either only when the change is truly cosmetic); the lighter inline review still uses the same finding IDs, counts line, and ledger, and the same no-`open` gate, per code-review.md; the tests / criterion and the honest outcome report still run regardless. At a HITL checkpoint here, an advisory sub-choice (which fix, how to proceed) **offers** the delegate option, per the injection recipe in `../../_shared/choices.md`; the accept/resolve decision stays the human's.
-5. **Resolve**: a resolution comment with what was done → `gh issue close` → update `Decisions so far` on the map (a body read-modify-write: obey the **Fail-safe body rewrites** rule in `../../_shared/substrate.md`). **Disposition gate (before the close)**: the latest `VERIFY` comment's findings ledger covers every finding the counts line counts and none of them is `open`; the resolution comment links that ledger rather than duplicating it; otherwise do not `gh issue close` (per code-review.md's Disposition gate). **Pending-UAT guard (before the close).** If Verify left acceptance testing **not yet run** (it would otherwise be deferred), **pose the two-way choice to the user and wait for an explicit answer, never open a ticket unilaterally**: (a) run the UAT now, in this session, with no ticket (opens with the drive-mode ask, `../../_shared/techniques/acceptance-testing.md`), or (b) open a UAT follow-up ticket to run it later. On (a), run the guided walkthrough now and resolve **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 guided-UAT rules in `../../_shared/techniques/acceptance-testing.md`, not a silent close); on (b), **open the follow-up ticket carrying the owed UAT first**, linked back to this parent (a `task` on the frontier or a `trailhead:seed` gated on the run, per *Pending UAT must stay tracked* in `../../_shared/techniques/acceptance-testing.md`). **Never open a UAT ticket without asking, never `gh issue close` on a chosen-deferred UAT with nothing opened, and never let silence or an ambiguous reply default to either path.** When acceptance was already completed at Verify, this guard doesn't fire. **Post-commit self-check (before the comment goes out).** For each commit the comment cites, confirm the hash resolves (`git cat-file -e <hash>^{commit}`, or `git show --stat <hash>`) and that every file the comment names as touched actually appears in that commit's diff (`git -c core.quotepath=false show --name-only --format= <hash>`, with `core.quotepath=false` so a non-ASCII filename compares plainly instead of in git's C-quoted form); correct or drop any citation that fails the check, so a hallucinated or mis-stated commit never lands in the tracker record. **If this change materially altered the codebase** (a new module/layer, dependency, seam, or build/test command), **patch the affected facet of the `trailhead:codebase` issue** (see **Codebase** in `../../_shared/substrate.md`) in place (a line or two, not a re-map). Then close the session with the **Session handoff** ritual (`../../_shared/session-handoff.md`): `/clear` + next command.
+2. **Plan**: a `PLAN` comment: the steps, the seams, the files touched, the verification criteria. Apply **TDD** per `config.tdd` (`seams`/`on`/`off`). Produce this plan via a *planner subagent* on `config.models.plan` (dispatch the **`trailhead-plan`** agent, read-only, passing `config.models.plan` as the model override; inline when the model is unset or equals the session model; Execute then runs as its own subagent, see below). **Report (orchestrator).** Run the report-status check on the planner's report (`--technique plan`, the *Malformed review report* protocol in `../../_shared/techniques.md`) and branch on the checker's `verdict`: `status: ready` -> post the checker's `body` verbatim as the `PLAN` comment; `status: needs_input` -> ask the user the `questions:` (the checker's `fields`), then re-spawn the planner with the answers; never answer them yourself or guess. If `config.plan_review` is on, run **Cross-AI plan review** before Execute: send the plan to external AI CLIs and converge on their concerns. Now that the files/seam are known, run the **undeclared-coupling check** (`../../_shared/teamwork.md`) against in-progress tickets. **Plan to sufficiency:** stop once you can name the steps, seams, and files with confidence, and never re-read a file already read in this planning pass; act when you have enough to plan, rather than re-deriving what the pass already established. **The single exception:** under an accepted `lean` skip (see the Size triage above), produce a short inline plan here instead of the planner subagent, and skip Cross-AI plan review; absent that accepted skip, this step runs in full as described.
+3. **Execute**: the orchestrator runs the HITL and tracker moves around an **executor subagent on `config.models.execute`**; the implementing protocol itself lives in `executor-brief.md` (this directory), the only protocol text the agent receives from this step. The agent cannot ask the user and never writes to the tracker, pushes or creates a branch.
+   - **Prototype FIRST (orchestrator).** **If this ticket changes user-facing UI (a new screen, a redesign, a changed layout), run the Prototype technique FIRST, before any real UI code**: surface a mockup to react to (its clickable link always in the same message as the approval question, per the Prototype technique; the guard also accepts a link inside the approval question itself, the prose stays preferred), routed by `config.design` (disk / artifacts / stitch) and gated by `config.design.approval` (`explicit` waits for a go-ahead, `auto` proceeds after surfacing). **Route by `config.design` and never shortcut a hosted mode to a local disk mockup**: when `config.design` is `artifacts` (or the legacy `claude.ai/design`) or `stitch`, the mockup is built there (reusing a cached `design.project`); `disk` is only for `config.design: disk` or the technique's explicit, announced fallback, never a convenience default. Read `config.design` before producing anything. For a redesign or new screen the default is to offer mockups; don't jump straight to code on a UI ticket (full statement in the **Prototype** technique, `../../_shared/techniques/prototype.md`).
+   - **Branch and worktree (orchestrator).** Following the repo's `trailhead:conventions` `git:`, straight to `main` by default, or a feature branch + PR when `git: pr` (the orchestrator creates the branch before the spawn and opens the PR; the executor only commits, never pushes, switches branch or writes to the tracker). **Under `isolation: worktree`, the work happens in this ticket's `git worktree`** (`trailhead/t<n>` branch), integrating to the trunk at Resolve (see `../../_shared/teamwork.md`).
+   - **Dispatch.** Spawn the **`trailhead-executor`** agent (full tools that can Edit/Write/commit), passing `config.models.execute` as the model override and `executor-brief.md` as the only protocol text, plus the runtime inputs: the ticket number, the PLAN, the base SHA, the `config.tdd` value, the approved mockup link if any, the accepted mockup deviations, and, for a resumed spawn, the packages the user approved. Inline when the model is unset or equals the session model: the session then does both parts. Inline, the session reads `executor-brief.md` and applies it, asking the user directly at the points the brief says to report. The agent implements with **atomic commits** (conventional commits, each with a `Refs: #<n>` trailer for this ticket, see **Principles** in `../../_shared/principles.md`; the trailer is also what scopes Verify's review and goal check, per **Ticket diff** in `../../_shared/techniques/code-review.md`; one commit = one verifiable step); the commits land on `main`, visible.
+   - **Fidelity (orchestrator).** The approved mockup is reproduced with **100% fidelity** (layout, spacing, sizing, colour, type, copy, and every state), never a loose approximation. **Make fidelity verifiable, not a hope:** the executor returns the enumerated fidelity list in its report and the orchestrator posts it as a ticket comment (noting any element raised as infeasible with its resolution), so Verify works from a durable checklist instead of reconstructing intent. At Verify, **Acceptance testing** checks the built screen against the approved mockup (element by element, state by state) and **Goal-backward verification** carries fidelity as an explicit goal claim (see `../../_shared/techniques/acceptance-testing.md` and `../../_shared/techniques/verify.md`).
+   - **Infeasible element (orchestrator).** When the report marks an element infeasible, raise it with the user and settle it: revise and re-approve the mockup, or the user accepts a named deviation. Then re-spawn the executor with the settled mockup and the accepted deviations; never let it deviate silently.
+   - **Flagged package (orchestrator).** The **verify-before-install gate** (slopsquatting barrier) runs in the executor (legitimacy, typosquat similarity, age, downloads, repository metadata). On a flagged package in the report, block-and-ask: stop and ask the user, never installing on your own judgement. Only on an explicit yes, re-spawn the executor with that package passed as user-approved (it then re-runs the exact install command prefixed with `TRAILHEAD_VERIFIED_INSTALL=1`); on a no it is not installed and the plan is revisited with the user. On a host with a hook bus the `trailhead-install-guard` `PreToolUse` hook enforces the gate, blocking a named public-registry install (npm / PyPI / crates.io / Go / RubyGems) until it is vetted.
+   - **Surfaced scope (orchestrator).** New scope surfacing mid-execute, reported by the executor in `surfaced scope:`, is captured/split, not worked here.
+   - **Report (orchestrator).** Run the report-status check on the agent's report (`--technique executor`, the *Malformed review report* protocol in `../../_shared/techniques.md`) and branch on the checker's `verdict`, reading its `fields`: never reconstruct a result from the prose. `status: done` -> Verify. `status: partial` or `blocked` -> act on each `blockers:` entry with the moves above (flagged package, infeasible element; a foreign change in the way is raised with the user), then re-spawn. Post `fidelity:` as the fidelity comment and route `surfaced scope:` as below. Check `commits:` against the repo: it must equal the `Refs: #<n>` commit set since the base SHA, in both directions, and every SHA must resolve (`git cat-file -e <sha>^{commit}`); a mismatch is surfaced to the user, never patched over.
+4. **Verify**: a `VERIFY` comment: **start with the Stale-base preflight** (`trailhead-base-preflight.js --sync`, **Stale-base preflight** in `../../_shared/teamwork.md`): preflight, then sync, then re-run the tests, all before anything is reviewed (a rebase rewrites SHAs the review ledger cites, and the Code review and goal check must see the synced tree); then run the tests / the plan's criterion; then the **Code review** technique, scoped to the ticket's own commits per its **Ticket diff** rule (`../../_shared/techniques/code-review.md`: the `Refs: #<n>` set, read per commit, recomputed each round, an empty set surfaced as an error, never a `<base>...HEAD` range) (its subagent reviews *adversarially*: it doesn't defer to a `CLAUDE.md` convention or a "settled decision" memory), and carries the review's counts line and findings ledger, per code-review.md, **run in the background and collected by polling, never a blind blocking wait** (a hard engine default on every host, see *Reviews never block the session* in `../../_shared/techniques.md`); run the report-status check before branching on status (each report, from the subagent or inline, goes through the *Malformed review report* protocol in `../../_shared/techniques.md`, which also fixes the layout of the round's single `VERIFY` comment); **read the review's leading `status:` tag to branch deterministically: `status: clean` -> proceed to Resolve, `status: issues_found` -> iterate the fix-and-re-review loop (or run the HITL checkpoint) before resolving**; then the **Goal-backward verification** technique on `config.models.verify` (does the change deliver what the ticket promised, backward from its `Question` and the `PLAN`'s criteria; the read-only `trailhead-verify` subagent, on the same **Ticket diff** set), **run in the background and collected by polling** like Code review, branching on its leading `status:` tag (`status: met` -> proceed, `status: gaps_found` -> loop back to Execute for the gap or run the HITL checkpoint before resolving, `status: inconclusive` as the leading tag (all gaps cleared) -> a per-reason-class HITL checkpoint with no auto-retry, never auto-resolving over the unevaluated goal); then **Acceptance testing** if the change is user-facing, opening with the UAT setup (`trailhead-uat-setup.js`, after the preflight) and then the drive-mode ask (`../../_shared/techniques/acceptance-testing.md`): AI-driven, or **walk the user through a guided UAT conversationally, one step at a time**, never a checklist dumped in a comment (or skip (waive acceptance), recorded as waived, if the user so chooses): interactive by design, so it runs inline, not backgrounded. Report the outcome honestly (if a test fails, say so). **The single exception:** under an accepted `lean` skip, run a lighter inline review pass instead of the full Code-review subagent and a quick inline goal check instead of the full Goal-backward verification subagent (or skip either only when the change is truly cosmetic); the lighter inline review still uses the same finding IDs, counts line, and ledger, and the same no-`open` gate, per code-review.md; the tests / criterion and the honest outcome report still run regardless. At a HITL checkpoint here, an advisory sub-choice (which fix, how to proceed) **offers** the delegate option, per the injection recipe in `../../_shared/choices.md`; the accept/resolve decision stays the human's.
+5. **Resolve**: a resolution comment with what was done → `gh issue close` → update `Decisions so far` on the map (default path: `node <templates>/trailhead-issue-body.js append --issue <map> --section "Decisions so far" --line "<pointer>"`, a body read-modify-write that obeys the **Fail-safe body rewrites** rule in `../../_shared/substrate.md` for you; `<templates>` is the same three-dir lookup as for `trailhead-work-state.js` (**Work state file** in `../../_shared/teamwork.md`); when the helper is missing, do the read-modify-write by hand per that rule). **Disposition gate (before the close)**: the latest `VERIFY` comment's findings ledger covers every finding the counts line counts and none of them is `open`; the resolution comment links that ledger rather than duplicating it; otherwise do not `gh issue close` (per code-review.md's Disposition gate). **Stale-base preflight (before integrating).** Run the preflight per **Stale-base preflight** in `../../_shared/teamwork.md` (`git: main`: right before the trunk push; `git: pr` without isolation: on the ticket branch, immediately before the push and PR; `worktree`/`clone`: on the main checkout, then on the ticket branch) and integrate only on `current`/`synced` with the tests green and `checksOk`. **Pending-UAT guard (before the close).** If Verify left acceptance testing **not yet run** (it would otherwise be deferred), **pose the two-way choice to the user and wait for an explicit answer, never open a ticket unilaterally**: (a) run the UAT now, in this session, with no ticket (the stale-base preflight first, then the UAT setup, then the drive-mode ask, `../../_shared/techniques/acceptance-testing.md`), or (b) open a UAT follow-up ticket to run it later. On (a), run the guided walkthrough now and resolve on a confirmed pass, or on an explicit waiver if the user skips at the ask (recorded as unconfirmed; the resolution comment states it) (a failing step becomes a fix or a `bug` follow-up and an incomplete/blocked step is marked pending and tracked, per the guided-UAT rules in `../../_shared/techniques/acceptance-testing.md`, not a silent close); on (b), **open the follow-up ticket carrying the owed UAT first**, linked back to this parent (a `task` on the frontier or a `trailhead:seed` gated on the run, per *Pending UAT must stay tracked* in `../../_shared/techniques/acceptance-testing.md`). **Never open a UAT ticket without asking, never `gh issue close` on a chosen-deferred UAT with nothing opened, and never let silence or an ambiguous reply default to either path.** When acceptance was already completed at Verify, or was **explicitly waived** by the user at the drive-mode ask (a waiver is not a deferral: nothing is owed, so nothing is opened; the resolution comment states the waiver), this guard doesn't fire. **Post-commit self-check (before the comment goes out).** For each commit the comment cites, confirm the hash resolves (`git cat-file -e <hash>^{commit}`, or `git show --stat <hash>`) and that every file the comment names as touched actually appears in that commit's diff (`git -c core.quotepath=false show --name-only --format= <hash>`, with `core.quotepath=false` so a non-ASCII filename compares plainly instead of in git's C-quoted form); correct or drop any citation that fails the check, so a hallucinated or mis-stated commit never lands in the tracker record. **If this change materially altered the codebase** (a new module/layer, dependency, seam, or build/test command), **patch the affected facet of the `trailhead:codebase` issue** (see **Codebase** in `../../_shared/substrate.md`) in place (a line or two, not a re-map). When a structural event is due (a whiteboard ticket resolved, a map exhausted), refresh the dashboard with `node <templates>/trailhead-dashboard.js` (one call, whole body from the live tracker; by hand per `../../_shared/substrate-commands.md` when the helper is missing). Then close the session with the **Session handoff** ritual (`../../_shared/session-handoff.md`): one `node <templates>/trailhead-work-state.js clear --repo <working-root>` removes the work state and the session-ticket marker, then `/clear` + next command.
 
 New scope that surfaces mid-build (while planning, executing, or testing) → **capture or split, never expand this ticket in flight** (see **Scope that surfaces while working a ticket**, served by the capture cluster). If the user defers that in-the-moment choice rather than settling it, mark the follow-up **pending** so the **Pending follow-up guard** re-poses it at handoff (`../../_shared/session-handoff.md`), instead of losing it to scrollback.
 
@@ -48,10 +58,18 @@ Then run the cycle, all in ticket comments:
 **Size triage (`effort`-gated).** Under `config.effort: lean`, run the **size triage and ask-to-skip offer defined canonically under effort in `../../_shared/configuration-reference.md`**, classifying the fix as in the `build` engine. On trivial/small, offer to skip only the *heavy verification* a tiny fix does not warrant: lighten or skip **TDD**, run a **lighter inline Code review** instead of the full subagent, and a **quick inline goal check** instead of the full **Goal-backward verification** subagent, going lean **only on an explicit yes**. **Diagnose is never in the offer**: a bug always needs a confirmed root cause before Fix, whatever its size. On a no/silence/ambiguity, and under `effort: standard` (default), the full cycle runs.
 
 1. **Repro**: a `REPRO` comment: how to reproduce, expected vs observed behaviour.
-2. **Diagnose**: run the **Debug** technique. A `DIAGNOSIS` comment with the root cause **stated as a falsifiable hypothesis plus the falsification test that confirmed it**. **Pre-fix checkpoint: only a confirmed cause proceeds to Fix** (a cause that has not survived its falsification test stays in diagnosis, looping the hypothesis steps); the full gate lives in the **Debug** technique (`../../_shared/techniques/debug.md`).
-3. **Fix**: implement the correction with **atomic commits** (each with a `Refs: #<n>` trailer for this ticket, see **Principles** in `../../_shared/principles.md`; the trailer is also what scopes Verify's review and goal check, per **Ticket diff** in `../../_shared/techniques/code-review.md`; per the repo's `trailhead:conventions` `git:`, `main` by default, else a branch + PR; in this ticket's `git worktree` under `isolation: worktree`), via an **executor subagent on `config.models.execute`** (dispatch the **`trailhead-fix`** agent, full tools, passing `config.models.execute` as the model override; inline when unset/same as session). Where sensible, a test that fails before and passes after (**TDD**). The **verify-before-install gate** from the `build` Execute step applies here too: vet any new dependency (typosquat similarity, age, downloads, repository metadata) and stop and ask the user on a suspicious result, before installing. **For a user-facing fix that changes UI, the `build` Execute step's Prototype + approved-mockup fidelity rule applies here too:** where the fix changes a screen, surface a mockup, and once approved reproduce it with 100% fidelity with the same enumerated, Verify-checked fidelity list.
-4. **Verify**: a `VERIFY` comment: the repro now passes, no regressions; **Code review** on the fix, scoped to the ticket's own commits per its **Ticket diff** rule (`../../_shared/techniques/code-review.md`: the `Refs: #<n>` set, read per commit, recomputed each round, an empty set surfaced as an error, never a `<base>...HEAD` range), and carries the review's counts line and findings ledger, per code-review.md, **run in the background and collected by polling, never a blind blocking wait** (a hard engine default on every host, see *Reviews never block the session* in `../../_shared/techniques.md`); **read the review's leading `status:` tag to branch deterministically (`status: clean` -> Resolve, `status: issues_found` -> iterate the loop or run the checkpoint first)**; then the **Goal-backward verification** technique on `config.models.verify` (does the fix deliver what the ticket promised, backward from its `Question`; the read-only `trailhead-verify` subagent, on the same **Ticket diff** set), background and collected by polling, branching on its leading `status:` tag (`status: met` -> proceed, `status: gaps_found` -> loop back to Fix for the gap or run the checkpoint, `status: inconclusive` as the leading tag (all gaps cleared) -> a per-reason-class HITL checkpoint with no auto-retry, never auto-resolving over the unevaluated goal); **Acceptance testing** if the bug was user-facing, opening with the drive-mode ask (`../../_shared/techniques/acceptance-testing.md`): AI-driven, or **walk the user through a guided UAT conversationally, step by step**, not a checklist to self-serve: interactive by design, so it runs inline, not backgrounded. At a HITL checkpoint here, an advisory sub-choice (which fix, how to proceed) **offers** the delegate option, per the injection recipe in `../../_shared/choices.md`; the accept/resolve decision stays the human's.
-5. **Resolve**: a resolution comment (cause + fix) → `gh issue close` → update `Decisions so far` (a body read-modify-write: obey the **Fail-safe body rewrites** rule in `../../_shared/substrate.md`). **Disposition gate (before the close)**: the latest `VERIFY` comment's findings ledger covers every finding the counts line counts and none of them is `open`; the resolution comment links that ledger rather than duplicating it; otherwise do not `gh issue close` (per code-review.md's Disposition gate). **Pending-UAT guard (before the close).** If Verify left acceptance testing **not yet run** (it would otherwise be deferred), **pose the two-way choice to the user and wait for an explicit answer, never open a ticket unilaterally**: (a) run the UAT now, in this session, with no ticket (opens with the drive-mode ask, `../../_shared/techniques/acceptance-testing.md`), or (b) open a UAT follow-up ticket to run it later. On (a), run the guided walkthrough now and resolve **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 guided-UAT rules in `../../_shared/techniques/acceptance-testing.md`, not a silent close); on (b), **open the follow-up ticket carrying the owed UAT first**, linked back to this parent (a `task` on the frontier or a `trailhead:seed` gated on the run, per *Pending UAT must stay tracked* in `../../_shared/techniques/acceptance-testing.md`). **Never open a UAT ticket without asking, never `gh issue close` on a chosen-deferred UAT with nothing opened, and never let silence or an ambiguous reply default to either path.** When acceptance was already completed at Verify, this guard doesn't fire. **Run the post-commit self-check before posting, exactly as in the `build` Resolve step** (each cited hash resolves and the files it names appear in that commit's diff; correct or drop any citation that fails). **If the fix materially altered the codebase**, patch the affected facet of the `trailhead:codebase` issue (see **Codebase** in `../../_shared/substrate.md`; also a body read-modify-write, same **Fail-safe body rewrites** rule) in place (a line or two). Then close the session with the **Session handoff** ritual (`../../_shared/session-handoff.md`): `/clear` + next command.
+2. **Diagnose**: run the **Debug** technique. Dispatch `trailhead-debug` and run the report-status check on its report (`--technique debug`, the *Malformed review report* protocol in `../../_shared/techniques.md`); branch on the checker's `verdict`, reading its `fields`: `status: found` -> its `answer:` (the cause) and `evidence:` (the falsification test and its result) feed the `DIAGNOSIS`; `status: inconclusive` -> the ticket stays in diagnosis, next hypotheses, never on to Fix; `status: needs_input` -> ask the user the `open questions:`, then re-spawn with the answers. A `DIAGNOSIS` comment with the root cause **stated as a falsifiable hypothesis plus the falsification test that confirmed it**. **Pre-fix checkpoint: only a confirmed cause proceeds to Fix** (a cause that has not survived its falsification test stays in diagnosis, looping the hypothesis steps); the full gate lives in the **Debug** technique (`../../_shared/techniques/debug.md`).
+3. **Fix**: the orchestrator runs the HITL and tracker moves around an **executor subagent on `config.models.execute`**; the implementing protocol itself lives in `executor-brief.md` (this directory), the only protocol text the agent receives from this step. The agent cannot ask the user and never writes to the tracker, pushes or creates a branch.
+   - **Dispatch.** Spawn the **`trailhead-fix`** agent (full tools), passing `config.models.execute` as the model override and `executor-brief.md` as the only protocol text, plus the runtime inputs: the ticket number, the base SHA, the confirmed `DIAGNOSIS`, the `config.tdd` value, the approved mockup link if any, the accepted mockup deviations, and, for a resumed spawn, the packages the user approved. Inline when unset/same as session: the session then does both parts. Inline, the session reads `executor-brief.md` and applies it, asking the user directly at the points the brief says to report. The agent implements the correction with **atomic commits** (each with a `Refs: #<n>` trailer for this ticket, see **Principles** in `../../_shared/principles.md`; the trailer is also what scopes Verify's review and goal check, per **Ticket diff** in `../../_shared/techniques/code-review.md`), and where sensible a test that fails before and passes after (**TDD**).
+   - **Branch and worktree (orchestrator).** Per the repo's `trailhead:conventions` `git:`, `main` by default, else a branch + PR: the orchestrator creates the branch before the spawn and opens the PR under `git: pr`; the agent only commits. Under `isolation: worktree`, the work happens in this ticket's `git worktree`.
+   - **UI fix: Prototype and approval (orchestrator).** Where the fix changes a screen (a user-facing UI fix), run the Prototype technique FIRST, before any real UI code: surface a mockup, routed by `config.design` (never shortcut a hosted mode to a local disk mockup) and gated by `config.design.approval`, per the technique (`../../_shared/techniques/prototype.md`). Once approved, the executor reproduces it with 100% fidelity.
+   - **Fidelity (orchestrator).** The executor returns the enumerated fidelity list in its report and the orchestrator posts it as a ticket comment, so Verify (Acceptance testing and Goal-backward verification) checks against a durable list.
+   - **Infeasible element (orchestrator).** When the report marks an element infeasible, raise it with the user and settle it: revise and re-approve the mockup, or the user accepts a named deviation; then re-spawn the executor with the settled mockup and the accepted deviations.
+   - **Flagged package (orchestrator).** The **verify-before-install gate** runs in the executor (typosquat similarity, age, downloads, repository metadata). On a flagged package in the report, block-and-ask: stop and ask the user before anything is installed. Only on an explicit yes, re-spawn the executor with that package passed as user-approved; on a no it is not installed and the plan is revisited with the user.
+   - **Surfaced scope (orchestrator).** New scope the executor reports in `surfaced scope:` is captured/split, never worked in this ticket.
+   - **Report (orchestrator).** Run the report-status check on the agent's report (`--technique fix`, the *Malformed review report* protocol in `../../_shared/techniques.md`) and branch on the checker's `verdict`, reading its `fields`: never reconstruct a result from the prose. `status: done` -> Verify. `status: partial` or `blocked` -> act on each `blockers:` entry with the moves above (flagged package, infeasible element; a foreign change in the way is raised with the user), then re-spawn. Post `fidelity:` as the fidelity comment and route `surfaced scope:` as below. Check `commits:` against the repo: it must equal the `Refs: #<n>` commit set since the base SHA, in both directions, and every SHA must resolve (`git cat-file -e <sha>^{commit}`); a mismatch is surfaced to the user, never patched over.
+4. **Verify**: a `VERIFY` comment: **start with the Stale-base preflight** (`trailhead-base-preflight.js --sync`, **Stale-base preflight** in `../../_shared/teamwork.md`): preflight, then sync, then re-run the tests, all before anything is reviewed (a rebase rewrites SHAs the review ledger cites, and the Code review and goal check must see the synced tree); then the repro now passes, no regressions; **Code review** on the fix, scoped to the ticket's own commits per its **Ticket diff** rule (`../../_shared/techniques/code-review.md`: the `Refs: #<n>` set, read per commit, recomputed each round, an empty set surfaced as an error, never a `<base>...HEAD` range), and carries the review's counts line and findings ledger, per code-review.md, **run in the background and collected by polling, never a blind blocking wait** (a hard engine default on every host, see *Reviews never block the session* in `../../_shared/techniques.md`); run the report-status check before branching on status (each report, from the subagent or inline, goes through the *Malformed review report* protocol in `../../_shared/techniques.md`, which also fixes the layout of the round's single `VERIFY` comment); **read the review's leading `status:` tag to branch deterministically (`status: clean` -> Resolve, `status: issues_found` -> iterate the loop or run the checkpoint first)**; then the **Goal-backward verification** technique on `config.models.verify` (does the fix deliver what the ticket promised, backward from its `Question`; the read-only `trailhead-verify` subagent, on the same **Ticket diff** set), background and collected by polling, branching on its leading `status:` tag (`status: met` -> proceed, `status: gaps_found` -> loop back to Fix for the gap or run the checkpoint, `status: inconclusive` as the leading tag (all gaps cleared) -> a per-reason-class HITL checkpoint with no auto-retry, never auto-resolving over the unevaluated goal); **Acceptance testing** if the bug was user-facing, opening with the UAT setup (`trailhead-uat-setup.js`, after the preflight) and then the drive-mode ask (`../../_shared/techniques/acceptance-testing.md`): AI-driven, or **walk the user through a guided UAT conversationally, step by step**, not a checklist to self-serve (or skip (waive acceptance), recorded as waived, if the user so chooses): interactive by design, so it runs inline, not backgrounded. At a HITL checkpoint here, an advisory sub-choice (which fix, how to proceed) **offers** the delegate option, per the injection recipe in `../../_shared/choices.md`; the accept/resolve decision stays the human's.
+5. **Resolve**: a resolution comment (cause + fix) → `gh issue close` → update `Decisions so far` (default path: `node <templates>/trailhead-issue-body.js append --issue <map> --section "Decisions so far" --line "<pointer>"`, same helper and fallback as the `build` Resolve step; a body read-modify-write that obeys the **Fail-safe body rewrites** rule in `../../_shared/substrate.md`). **Disposition gate (before the close)**: the latest `VERIFY` comment's findings ledger covers every finding the counts line counts and none of them is `open`; the resolution comment links that ledger rather than duplicating it; otherwise do not `gh issue close` (per code-review.md's Disposition gate). **Stale-base preflight (before integrating).** Run the preflight per **Stale-base preflight** in `../../_shared/teamwork.md` (`git: main`: right before the trunk push; `git: pr` without isolation: on the ticket branch, immediately before the push and PR; `worktree`/`clone`: on the main checkout, then on the ticket branch) and integrate only on `current`/`synced` with the tests green and `checksOk`. **Pending-UAT guard (before the close).** If Verify left acceptance testing **not yet run** (it would otherwise be deferred), **pose the two-way choice to the user and wait for an explicit answer, never open a ticket unilaterally**: (a) run the UAT now, in this session, with no ticket (the stale-base preflight first, then the UAT setup, then the drive-mode ask, `../../_shared/techniques/acceptance-testing.md`), or (b) open a UAT follow-up ticket to run it later. On (a), run the guided walkthrough now and resolve on a confirmed pass, or on an explicit waiver if the user skips at the ask (recorded as unconfirmed; the resolution comment states it) (a failing step becomes a fix or a `bug` follow-up and an incomplete/blocked step is marked pending and tracked, per the guided-UAT rules in `../../_shared/techniques/acceptance-testing.md`, not a silent close); on (b), **open the follow-up ticket carrying the owed UAT first**, linked back to this parent (a `task` on the frontier or a `trailhead:seed` gated on the run, per *Pending UAT must stay tracked* in `../../_shared/techniques/acceptance-testing.md`). **Never open a UAT ticket without asking, never `gh issue close` on a chosen-deferred UAT with nothing opened, and never let silence or an ambiguous reply default to either path.** When acceptance was already completed at Verify, or was **explicitly waived** by the user at the drive-mode ask (a waiver is not a deferral: nothing is owed, so nothing is opened; the resolution comment states the waiver), this guard doesn't fire. **Run the post-commit self-check before posting, exactly as in the `build` Resolve step** (each cited hash resolves and the files it names appear in that commit's diff; correct or drop any citation that fails). **If the fix materially altered the codebase**, patch the affected facet of the `trailhead:codebase` issue (see **Codebase** in `../../_shared/substrate.md`; also a body read-modify-write, same **Fail-safe body rewrites** rule) in place (a line or two; the same `trailhead-issue-body.js` helper does it with `--section "<facet>"`). When a structural event is due, refresh the dashboard with `node <templates>/trailhead-dashboard.js`. Then close the session with the **Session handoff** ritual (`../../_shared/session-handoff.md`): one `node <templates>/trailhead-work-state.js clear --repo <working-root>` removes the work state and the session-ticket marker, then `/clear` + next command.
 
 A **blocking** bug that halts other work is worked immediately; an isolated one is a normal frontier ticket. New scope surfacing while fixing → capture or split, never expand this ticket in flight (see **Scope that surfaces while working a ticket**). A follow-up raised but left unopened is carried to the **Pending follow-up guard** at handoff (`../../_shared/session-handoff.md`), re-posed at Resolve rather than dropped.
 

package/plugins/trailhead/templates/trailhead-base-preflight.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead base preflight (self-contained, ships in templates/ so it reaches every
+// install channel: bin/trailhead.js copies templates/ wholesale for Claude/npm
+// and Codex). Measures how far the working base is behind the trunk, optionally
+// syncs it, and runs the project's own preflight checks. #243.
+//
+// CLI:
+//   node trailhead-base-preflight.js --repo <working-root> [--config-root <project-root>]
+//        [--trunk <name>] [--sync] [--no-fetch]
+// --config-root is the original checkout the effective config was loaded from
+// (defaults to --repo); a worktree/clone workspace never re-resolves config.
+//
+// Trunk: --trunk, else the remote default branch (refs/remotes/origin/HEAD), else
+// the first existing of main / master; none found -> status skipped.
+// Fetch: an explicit destination refspec so origin/<trunk> really advances. A
+// failed fetch is never tolerated silently: status unverified (distance on local refs).
+// Base (one ref, deterministic): no remote ref -> local <trunk>; HEAD is the trunk ->
+// origin/<trunk>; HEAD on a ticket branch -> origin/<trunk> unless the local trunk is
+// strictly ahead (then the local trunk); both moved -> status trunk-diverged.
+// Sync (--sync, only when behind): refuses a dirty tracked tree (dirty); on the trunk
+// ff-only (rebase --rebase-merges when it has diverged, merge commits are kept); on a ticket branch rebase when unpublished,
+// merge when it has an upstream. Any failed sync is aborted and HEAD verified back at
+// its pre-sync commit: conflict (paths listed) or sync-failed (git's message).
+// Checks: `preflight.checks` (array of shell commands), nested ({"preflight":
+// {"checks":[...]}}) or flat ({"preflight.checks":[...]}); nested wins when a file
+// carries both. The project file (read from --config-root) wins over the global one
+// (${CLAUDE_CONFIG_DIR:-~/.claude}/trailhead/config.json) as a whole value. Each
+// command runs with `sh -c` at --repo after any sync. Not run on unverified,
+// trunk-diverged, error, conflict, dirty, sync-failed.
+// Prints one JSON line:
+//   {"status","trunk","base","behind","ahead","method"?,"pulled"?,"testsRequired",
+//    "conflicts":[],"checks":[{command,ok,code,output}],"checksOk","checksError"?,"warnings":[],"message"?}
+//   status: current | behind | synced | unverified | trunk-diverged | dirty | conflict |
+//           sync-failed | error | skipped
+// Fail closed: only current and synced (with checksOk) let the caller go on.
+// Exit 0 whenever a JSON line is printed; exit 2 only on a usage error.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const CONFIG_REL = path.join('.trailhead', 'config.json');
+const CHECK_TIMEOUT_MS = 300000;
+const OUTPUT_TAIL = 2000;
+const FLAGS = ['sync', 'no-fetch'];
+const VALUED = ['repo', 'config-root', 'trunk'];
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const name = a.startsWith('--') ? a.slice(2) : null;
+    if (name && VALUED.includes(name)) {
+      const v = argv[++i];
+      if (v === undefined || v.startsWith('--')) return { error: `usage: ${a} needs a value` };
+      out[name] = v;
+    } else if (name && FLAGS.includes(name)) {
+      out[name] = true;
+    } else {
+      return { error: `usage: unknown argument ${a}` };
+    }
+  }
+  if (!out.repo) return { error: 'usage: missing --repo <working-root>' };
+  return out;
+}
+
+// Reads preflight.checks out of one config file.
+// { state: 'unset' } | { state: 'set', list, warnings } | { state: 'invalid', message }
+function readChecks(file, fs_) {
+  let text;
+  try {
+    text = fs_.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { state: 'unset' };
+    return { state: 'invalid', message: `cannot read ${file}: ${err && err.message ? err.message : err}` };
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(text);
+  } catch (err) {
+    return { state: 'invalid', message: `${file} is not valid JSON` };
+  }
+  if (cfg === null || typeof cfg !== 'object' || Array.isArray(cfg)) {
+    return { state: 'invalid', message: `${file} is not a JSON object` };
+  }
+  const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+  const nested = cfg.preflight !== null && typeof cfg.preflight === 'object' && !Array.isArray(cfg.preflight) && has(cfg.preflight, 'checks');
+  const flat = has(cfg, 'preflight.checks');
+  if (!nested && !flat) return { state: 'unset' };
+  const warnings = [];
+  if (nested && flat) warnings.push(`${file} sets preflight.checks in both nested and flat form; the nested form wins`);
+  const value = nested ? cfg.preflight.checks : cfg['preflight.checks'];
+  if (!Array.isArray(value)) return { state: 'invalid', message: `preflight.checks in ${file} must be an array of shell commands` };
+  if (value.some((e) => typeof e !== 'string' || e.trim() === '')) {
+    return { state: 'invalid', message: `preflight.checks in ${file} must hold only non-empty strings` };
+  }
+  return { state: 'set', list: value, warnings };
+}
+
+function globalConfigPath(env) {
+  const base = env.CLAUDE_CONFIG_DIR || path.join(env.HOME || os.homedir(), '.claude');
+  return path.join(base, 'trailhead', 'config.json');
+}
+
+function tail(text) {
+  const t = String(text || '');
+  return t.length > OUTPUT_TAIL ? '...' + t.slice(t.length - OUTPUT_TAIL) : t;
+}
+
+// Runs git at `repo`; never throws on a non-zero exit.
+function makeGit(repo, env) {
+  const gitEnv = { ...process.env, ...env, GIT_EDITOR: 'true', GIT_TERMINAL_PROMPT: '0' };
+  const G = (args) => {
+    const r = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', env: gitEnv, maxBuffer: 64 * 1024 * 1024 });
+    if (r.error) throw r.error;
+    const res = { ok: r.status === 0, out: (r.stdout || '').trim(), err: (r.stderr || '').trim() };
+    G.last = res;
+    return res;
+  };
+  return G;
+}
+
+function detectTrunk(requested, G) {
+  if (requested) return requested;
+  const head = G(['symbolic-ref', '-q', '--short', 'refs/remotes/origin/HEAD']);
+  if (head.ok && head.out.startsWith('origin/')) return head.out.slice('origin/'.length);
+  for (const name of ['main', 'master']) {
+    if (G(['show-ref', '--verify', '-q', `refs/heads/${name}`]).ok || G(['show-ref', '--verify', '-q', `refs/remotes/origin/${name}`]).ok) return name;
+  }
+  return null;
+}
+
+// Commit count of a range; null when git fails (the caller reports the error, never a 0).
+const count = (G, range) => {
+  const r = G(['rev-list', '--count', range]);
+  const n = Number(r.out);
+  return r.ok && r.out !== '' && Number.isInteger(n) ? n : null;
+};
+
+const gitFailure = (G, what) => `${what}: ${(G.last && (G.last.err || G.last.out)) || 'git failed'}`;
+
+// Picks the one base ref. { base, diverged } or { error } when a comparison fails.
+function pickBase(G, trunk, head, hasLocal, hasRemote) {
+  const remote = `origin/${trunk}`;
+  if (!hasRemote) return { base: trunk, diverged: false };
+  if (!hasLocal || head === trunk) return { base: remote, diverged: false };
+  const what = `cannot compare ${trunk} with ${remote}`;
+  const localBehind = count(G, `${trunk}..${remote}`);
+  if (localBehind === null) return { error: gitFailure(G, what) };
+  const localAhead = count(G, `${remote}..${trunk}`);
+  if (localAhead === null) return { error: gitFailure(G, what) };
+  if (localBehind > 0 && localAhead > 0) return { base: remote, diverged: true };
+  return { base: localAhead > 0 ? trunk : remote, diverged: false };
+}
+
+// Puts HEAD and the tree back at `pre` after a failed sync.
+function restore(G, pre, warnings) {
+  G(['rebase', '--abort']);
+  G(['merge', '--abort']);
+  if (G(['rev-parse', 'HEAD']).out !== pre) {
+    G(['reset', '--hard', pre]);
+    warnings.push('the failed sync left HEAD moved; it was reset to the pre-sync commit');
+  }
+  const back = G(['rev-parse', 'HEAD']).out === pre && G(['status', '--porcelain', '--untracked-files=no']).out === '';
+  if (!back) warnings.push('could not verify the tree is back at its pre-sync state; inspect it before going on');
+}
+
+// Syncs the working base onto `base`. Returns fields for the result.
+function sync(G, { trunk, head, base, ahead, behind, warnings }) {
+  if (G(['status', '--porcelain', '--untracked-files=no']).out !== '') {
+    return { status: 'dirty', message: 'tracked changes in the working tree; commit or stash them before syncing' };
+  }
+  if (!head) return { status: 'sync-failed', message: 'detached HEAD: nothing to sync' };
+  const pre = G(['rev-parse', 'HEAD']).out;
+  let method;
+  let r;
+  if (head === trunk) {
+    method = ahead === 0 ? 'ff' : 'rebase';
+    r = method === 'ff' ? G(['merge', '--ff-only', '-q', base]) : G(['rebase', '-q', '--rebase-merges', base]);
+  } else if (G(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}']).ok) {
+    method = 'merge';
+    r = G(['merge', '--no-edit', '-q', base]);
+  } else {
+    method = 'rebase';
+    r = G(['rebase', '-q', '--rebase-merges', base]);
+  }
+  if (r.ok) return { status: 'synced', method, pulled: behind, testsRequired: true };
+  const conflicts = G(['diff', '--name-only', '--diff-filter=U']).out.split('\n').filter(Boolean);
+  restore(G, pre, warnings);
+  if (conflicts.length > 0) return { status: 'conflict', method, conflicts, message: `${method} onto ${base} conflicts; aborted, the tree is unchanged` };
+  return { status: 'sync-failed', method, message: r.err || r.out || `${method} failed` };
+}
+
+function runChecks(list, repo, env) {
+  const results = list.map((command) => {
+    const r = spawnSync('sh', ['-c', command], { cwd: repo, encoding: 'utf8', env: { ...process.env, ...env }, timeout: CHECK_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 });
+    const timedOut = r.error && r.error.code === 'ETIMEDOUT';
+    const output = (r.stdout || '') + (r.stderr || '') + (timedOut ? `\n(timed out after ${CHECK_TIMEOUT_MS / 1000}s)` : r.error && !timedOut ? `\n${r.error.message}` : '');
+    return { command, ok: r.status === 0, code: r.status, output: tail(output) };
+  });
+  return results;
+}
+
+const NO_CHECKS = new Set(['unverified', 'trunk-diverged', 'error', 'skipped', 'conflict', 'dirty', 'sync-failed']);
+
+function preflight(parsed, cwd, env, fs_) {
+  const repo = path.resolve(cwd, parsed.repo);
+  const configRoot = path.resolve(cwd, parsed['config-root'] || parsed.repo);
+  const G = makeGit(repo, env);
+  const warnings = [];
+  const result = { status: 'error', trunk: null, base: null, behind: 0, ahead: 0, testsRequired: false, conflicts: [], checks: [], checksOk: false, warnings };
+
+  if (!G(['rev-parse', '--git-dir']).ok) return { ...result, message: `${repo} is not a git repository` };
+  const trunk = detectTrunk(parsed.trunk, G);
+  if (!trunk) return { ...result, status: 'skipped', message: 'no trunk found (no remote default branch, main or master)' };
+  result.trunk = trunk;
+
+  let fetchFailed = false;
+  const hasOrigin = G(['remote', 'get-url', 'origin']).ok;
+  if (!hasOrigin) {
+    const remotes = G(['remote']).out.split('\n').filter(Boolean);
+    if (remotes.length > 0) warnings.push(`no remote named origin (found: ${remotes.join(', ')}); distance measured on local refs`);
+  }
+  if (hasOrigin && !parsed['no-fetch']) {
+    const f = G(['fetch', '--quiet', 'origin', `+refs/heads/${trunk}:refs/remotes/origin/${trunk}`]);
+    if (!f.ok) {
+      fetchFailed = true;
+      warnings.push(`fetch of origin/${trunk} failed, distance measured on local refs: ${f.err || 'unknown error'}`);
+    }
+  }
+  if (parsed['no-fetch']) warnings.push('--no-fetch: distance measured on local refs');
+
+  const hasLocal = G(['show-ref', '--verify', '-q', `refs/heads/${trunk}`]).ok;
+  const hasRemote = G(['show-ref', '--verify', '-q', `refs/remotes/origin/${trunk}`]).ok;
+  if (!hasLocal && !hasRemote) return { ...result, status: 'skipped', message: `trunk ${trunk} has no local or remote ref` };
+  const headName = G(['symbolic-ref', '-q', '--short', 'HEAD']);
+  const head = headName.ok ? headName.out : null;
+  const picked = pickBase(G, trunk, head, hasLocal, hasRemote);
+  if (picked.error) return { ...result, message: picked.error };
+  result.base = picked.base;
+  const behind = count(G, `HEAD..${picked.base}`);
+  const ahead = behind === null ? null : count(G, `${picked.base}..HEAD`);
+  if (behind === null || ahead === null) return { ...result, message: gitFailure(G, `cannot measure HEAD against ${picked.base}`) };
+  result.behind = behind;
+  result.ahead = ahead;
+  result.status = fetchFailed ? 'unverified' : picked.diverged ? 'trunk-diverged' : result.behind > 0 ? 'behind' : 'current';
+  if (fetchFailed) result.message = `could not fetch origin/${trunk}; the distance is not verified`;
+  if (picked.diverged) result.message = `local ${trunk} and origin/${trunk} have diverged; reconcile the trunk first`;
+
+  if (parsed.sync && result.status === 'behind') {
+    const s = sync(G, { trunk, head, base: picked.base, ahead: result.ahead, behind: result.behind, warnings });
+    Object.assign(result, s);
+    if (s.status === 'synced') {
+      // The sync succeeded; a failed recount is reported, never turned into a 0.
+      result.behind = count(G, `HEAD..${picked.base}`);
+      result.ahead = count(G, `${picked.base}..HEAD`);
+      if (result.behind === null || result.ahead === null) warnings.push(gitFailure(G, `cannot recount HEAD against ${picked.base} after the sync`));
+    }
+  }
+
+  if (!NO_CHECKS.has(result.status)) {
+    let cfg = readChecks(path.join(configRoot, CONFIG_REL), fs_);
+    if (cfg.state === 'unset') cfg = readChecks(globalConfigPath(env), fs_);
+    if (cfg.state === 'invalid') {
+      result.checksError = cfg.message;
+    } else {
+      if (cfg.state === 'set') {
+        warnings.push(...cfg.warnings);
+        result.checks = runChecks(cfg.list, repo, env);
+      }
+      result.checksOk = result.checks.every((c) => c.ok);
+    }
+  }
+  return result;
+}
+
+function main(argv, { cwd, stdout, env, fs: fsMod } = {}) {
+  const cwd_ = cwd || process.cwd();
+  const out = stdout || process.stdout;
+  const env_ = env || process.env;
+  const fs_ = fsMod || fs;
+
+  const parsed = parseArgs(argv || []);
+  if (parsed.error) {
+    process.stderr.write(parsed.error + '\n');
+    return 2;
+  }
+  let result;
+  try {
+    result = preflight(parsed, cwd_, env_, fs_);
+  } catch (err) {
+    result = { status: 'error', trunk: null, base: null, behind: 0, ahead: 0, testsRequired: false, conflicts: [], checks: [], checksOk: false, warnings: [], message: 'error: ' + (err && err.message ? err.message : String(err)) };
+  }
+  out.write(JSON.stringify(result) + '\n');
+  return 0;
+}
+
+module.exports = { parseArgs, readChecks, main };
+
+if (require.main === module) {
+  const code = main(process.argv.slice(2), { cwd: process.cwd(), stdout: process.stdout, env: process.env });
+  process.exit(code);
+}