@marcomigozzi/trailhead 0.15.0 → 0.16.0

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

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

package/plugins/trailhead/templates/statusline-trailhead.sh

@@ -11,8 +11,12 @@
 # trailhead al work-start, porta anche il titolo) -> numero dal branch
 # `trailhead/t<N>` -> titolo via `gh` in cache/background (solo se origin GitHub).
 #
-# Contesto: barra `[BARRA] Nk/Mk (P%)`, dall'ultimo usage del transcript. Tetto:
-# $CONTEXT_LIMIT -> .model.context_window -> tabella modello -> auto-bump 1M.
+# Contesto: barra `[BARRA] Nk/Mk (P%)`, dall'ultimo usage del transcript. Tetto
+# (finestra del modello): $CONTEXT_LIMIT -> .context_window.context_window_size ->
+# tabella modello -> auto-bump 1M. La % e' contro la soglia di auto-compact di
+# Claude Code (finestra di compattazione - 20000 - 13000), non contro un 80% fisso:
+# vedi il commento sopra il blocco CTX per le regole. CONTEXT_USABLE_RATIO resta
+# solo come override manuale (0 < ratio <= 1: denominatore = tetto * ratio).
 #
 # Usage: % REALE del piano via l'API OAuth di Anthropic (come ccstatusline):
 # GET https://api.anthropic.com/api/oauth/usage con il Bearer preso da
@@ -139,12 +143,24 @@ fi
 # Fonte primaria (come ccstatusline): .context_window del JSON di Claude Code
 # (context_window_size = tetto reale, current_usage = token). Fallback: ultimo
 # usage del transcript + tabella modello. $CONTEXT_LIMIT forza il tetto.
-# Denominatore = finestra * 0.8 (soglia auto-compact, come ccstatusline); il
-# rapporto e' regolabile con CONTEXT_USABLE_RATIO (1 = tetto pieno).
+# Denominatore = soglia di auto-compact di Claude Code:
+#   finestra di compattazione = min(tetto modello, primo valido tra
+#     $CLAUDE_CODE_AUTO_COMPACT_WINDOW, autoCompactWindow dei settings, tetto);
+#   nei settings (utente < progetto < progetto.local, vince il piu' specifico)
+#   modelSettings.<model id senza [..]>.autoCompactWindow batte autoCompactWindow;
+#   soglia = finestra - 20000 (output riservato, massimo) - 13000 (buffer), min 1;
+#   $CLAUDE_AUTOCOMPACT_PCT_OVERRIDE (0 < pct <= 100) puo' solo abbassarla:
+#   min(soglia, floor(finestra * pct / 100)).
+# Con DISABLE_AUTO_COMPACT / DISABLE_COMPACT truthy il denominatore e' il tetto pieno.
+# CONTEXT_USABLE_RATIO (0 < r <= 1), se impostato, e' un override manuale:
+# denominatore = tetto * r, senza calcolo di compattazione.
 CTX="$(
   { [ -n "$TRANSCRIPT" ] && [ -f "$TRANSCRIPT" ] && tail -n 300 "$TRANSCRIPT" 2>/dev/null | tac | grep -m1 'cache_read_input_tokens'; } | \
   CTX_MODEL_ID="$(j '.model.id')" \
   CTX_CW_SIZE="$(j '.context_window.context_window_size')" \
+  CTX_PROJECT_DIR="$(j '.workspace.project_dir')" \
+  CTX_CURRENT_DIR="$(j '.workspace.current_dir')" \
+  CTX_CWD="$(j '.cwd')" \
   CTX_USAGE="$(printf '%s' "$input" | jq -c '.context_window.current_usage // empty' 2>/dev/null)" \
   python3 -c '
 import sys, os, json, re
@@ -192,16 +208,65 @@ if not limit:
     if tok > limit and limit <= 200000:   # auto-bump 1M solo nel fallback
         limit = 1000000
 
-# soglia usabile (auto-compact): denominatore = finestra * ratio (0.8 come ccstatusline)
-try:
-    ratio = float(os.environ.get("CONTEXT_USABLE_RATIO") or 0.8)
-except Exception:
-    ratio = 0.8
-denom = round(limit * ratio) if limit else 0
-pct = min(100, round(tok*100/denom)) if denom else 0   # % contro la soglia 0.8
+def pos_num(x):
+    # numero finito > 0, altrimenti None (bool e stringhe non numeriche scartati)
+    if isinstance(x, bool) or x is None: return None
+    try: v = float(x)
+    except Exception: return None
+    return v if v == v and v not in (float("inf"),) and v > 0 else None
+
+def truthy(name):
+    return (os.environ.get(name) or "").strip().lower() in ("1", "true", "yes", "on")
+
+def load_settings():
+    # utente < progetto < progetto.local; file illeggibili/invalidi saltati
+    cfg = os.environ.get("CLAUDE_CONFIG_DIR") or os.path.join(os.path.expanduser("~"), ".claude")
+    proj = os.environ.get("CTX_PROJECT_DIR") or os.environ.get("CTX_CURRENT_DIR") or os.environ.get("CTX_CWD")
+    paths = [os.path.join(cfg, "settings.json")]
+    if proj:
+        paths += [os.path.join(proj, ".claude", "settings.json"),
+                  os.path.join(proj, ".claude", "settings.local.json")]
+    out = []
+    for p in paths:
+        try:
+            d = json.load(open(p))
+            if isinstance(d, dict): out.append(d)
+        except Exception:
+            pass
+    return out  # dal meno al piu prioritario
+
+def setting_window(model):
+    files = load_settings()[::-1]  # piu prioritario per primo
+    for d in files:   # per-modello batte top-level: prima cerco il per-modello
+        ms = d.get("modelSettings")
+        v = pos_num((ms.get(model) or {}).get("autoCompactWindow")) if isinstance(ms, dict) and isinstance(ms.get(model), dict) else None
+        if v: return v
+    for d in files:
+        v = pos_num(d.get("autoCompactWindow"))
+        if v: return v
+    return None
+
+def threshold_for(limit):
+    model = re.sub(r"\[[^\]]*\]\s*$", "", os.environ.get("CTX_MODEL_ID") or "")
+    w = pos_num(os.environ.get("CLAUDE_CODE_AUTO_COMPACT_WINDOW")) or setting_window(model) or limit
+    w = int(min(w, limit))
+    thr = max(1, w - 20000 - 13000)
+    p = pos_num(os.environ.get("CLAUDE_AUTOCOMPACT_PCT_OVERRIDE"))
+    if p is not None and p <= 100:
+        thr = max(1, min(thr, int(w * p // 100)))
+    return thr
+
+ratio = pos_num(os.environ.get("CONTEXT_USABLE_RATIO"))
+if ratio is not None and ratio <= 1:
+    denom = round(limit * ratio)                 # override manuale
+elif truthy("DISABLE_AUTO_COMPACT") or truthy("DISABLE_COMPACT"):
+    denom = limit                                # niente compattazione: tetto pieno
+else:
+    denom = threshold_for(limit)
+pct = min(100, round(tok*100/denom)) if denom else 0
 n = 10; filled = round(pct*n/100)
 bar = "█"*filled + "░"*(n-filled)
-# numeri REALI: token effettivi / tetto pieno; la percentuale riflette auto-compact 0.8
+# numeri REALI: token effettivi / tetto pieno; la percentuale e contro la soglia di compattazione
 print(f"[{bar}] {round(tok/1000)}k/{round(limit/1000)}k ({pct}%)")
 ' 2>/dev/null
 )"

package/plugins/trailhead/templates/trailhead-auto-merge.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead auto-merge helper (self-contained, ships in templates/ so it reaches every
+// install channel). Merges a verified slot branch of an autonomous run into the local
+// trunk (never a push), recovers an interrupted merge, and removes a merged slot. #286.
+//
+// CLI (every command runs against the MAIN checkout, which is on the trunk):
+//   node trailhead-auto-merge.js merge   --repo <main-checkout> --ticket <n> [--trunk <name>]
+//   node trailhead-auto-merge.js recover --repo <main-checkout>
+//   node trailhead-auto-merge.js remove  --repo <main-checkout> --ticket <n> [--trunk <name>]
+//
+// Trunk: --trunk, else the remote default branch (refs/remotes/origin/HEAD), else the
+// first existing of main / master (the base-preflight rule); none -> error.
+// Every git-state path (MERGE_HEAD, MERGE_MSG, rebase-merge, ...) is resolved with
+// `git rev-parse --git-path`, never assumed under .git/.
+//
+// merge: preconditions first, each a distinct status with nothing touched:
+//   not-on-trunk     HEAD of the main checkout is not refs/heads/<trunk>
+//   in-progress      a merge / rebase / cherry-pick is already under way (run recover)
+//   dirty            tracked changes in the main checkout (untracked files are fine)
+//   slot-dirty       the branch's slot worktree has uncommitted tracked work
+//   error            the branch does not exist, or the trunk cannot be resolved
+// Then: already-merged when the tip is an ancestor of the trunk (an idempotent retry);
+// otherwise `git merge --no-edit -m "chore(auto): merge trailhead/t<n>" -m "Refs: #<n>"`
+// (fast-forward when possible, else a merge commit). The main checkout's
+// .trailhead/session-ticket (never written or rewritten here) does not block a merge: a
+// fast-forward creates no commit, so the commit-msg hook never runs; a true merge commit
+// adds --no-verify only when the marker names a ticket other than the merged one (the
+// hook would demand that ticket's Refs trailer, and the helper already builds the whole
+// message). No marker, or the same ticket: the hook stays active.
+//   merged         method ff|merge, from (trunk before), head (trunk after)
+//   conflict       conflicting paths in `conflicts`; the merge is aborted
+//   merge-failed   any other failure (hook refusal, untracked file in the way); aborted
+// An abort that does not leave HEAD at its pre-merge commit with a clean tracked tree
+// falls back to `git reset --merge <pre>` (safe: the preconditions guarantee a clean
+// tracked tree); only when that fails too is the result error "main left mid-merge",
+// the one case the caller must stop on. Never --force, never reset --hard.
+// On merged / already-merged, `behind` lists every OTHER trailhead/t* worktree slot with
+// trunk commits not in its branch ({ticket, path, behind}), informational.
+//
+// recover: no merge under way -> clean; a merge whose MERGE_MSG first line is
+// "chore(auto): merge trailhead/t<n>" -> aborted (same abort / fallback), with `ticket`;
+// anything else (a human's merge, a rebase, a cherry-pick) -> foreign, untouched.
+//
+// remove: only for a branch already merged into the trunk (else not-merged). A worktree
+// slot is removed with `git worktree remove` (no --force: a dirty one is an error and
+// stays) and the branch deleted with `git branch -d`; a clone slot is never deleted
+// (kept). Idempotent: a worktree already gone or a branch already deleted is skipped.
+// removed carries worktreeRemoved / branchDeleted (what THIS call did).
+//
+// One orchestrator runs merges one at a time. Two autonomous runs on the same main
+// checkout are not supported (no lock file); the in-progress precondition keeps this
+// helper from touching a merge it did not start.
+//
+// Prints exactly one JSON line on stdout: {"status":"...", ...}. Exit 0 whenever the
+// status is a result (parked statuses included), 1 on status error, 2 on a usage error.
+
+const { spawnSync } = require('child_process');
+const nodeFs = require('fs');
+const path = require('path');
+
+function defaultGit(args) {
+  const env = { ...process.env, GIT_EDITOR: 'true', GIT_TERMINAL_PROMPT: '0' };
+  const r = spawnSync('git', args, { encoding: 'utf8', env, maxBuffer: 64 * 1024 * 1024 });
+  return { status: r.status === null ? 1 : r.status, stdout: r.stdout || '', stderr: r.stderr || (r.error ? String(r.error.message) : '') };
+}
+
+const firstLine = (s) => String(s || '').split('\n').find((l) => l.trim()) || '';
+const branchOf = (n) => `trailhead/t${n}`;
+const BRANCH_RE = /^refs\/heads\/trailhead\/t(\d+)$/;
+const MERGE_SUBJECT = /^chore\(auto\): merge trailhead\/t(\d+)$/;
+const IN_PROGRESS = ['MERGE_HEAD', 'rebase-merge', 'rebase-apply', 'CHERRY_PICK_HEAD'];
+
+// --- args ---------------------------------------------------------------------
+
+const FLAGS = { merge: ['--repo', '--ticket', '--trunk'], recover: ['--repo'], remove: ['--repo', '--ticket', '--trunk'] };
+
+function parseArgs(argv) {
+  const cmd = argv[0];
+  if (!Object.prototype.hasOwnProperty.call(FLAGS, cmd)) return { error: `usage: expected merge, recover or remove, got: ${cmd === undefined ? '(nothing)' : cmd}` };
+  const o = { cmd, repo: null, ticket: null, trunk: null };
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    if (!FLAGS[cmd].includes(flag)) return { error: `usage: unknown argument: ${flag}` };
+    i++;
+    if (i >= argv.length) return { error: `usage: ${flag} requires a value` };
+    const v = argv[i];
+    if (flag === '--ticket') {
+      if (!/^[1-9]\d*$/.test(v)) return { error: `usage: --ticket must be a positive integer, got: ${v}` };
+      o.ticket = Number(v);
+    } else if (!v.trim()) {
+      return { error: `usage: ${flag} requires a non-empty value` };
+    } else if (flag === '--repo') {
+      o.repo = v;
+    } else {
+      o.trunk = v;
+    }
+  }
+  if (!o.repo) return { error: `usage: ${cmd} requires --repo` };
+  if (cmd !== 'recover' && !o.ticket) return { error: `usage: ${cmd} requires --ticket` };
+  return o;
+}
+
+// --- git helpers --------------------------------------------------------------
+
+// [{ path, branch|null }] from `git worktree list --porcelain`, main checkout first.
+function parseWorktrees(text) {
+  const out = [];
+  for (const block of String(text).split(/\n\s*\n/)) {
+    let wt = null;
+    let branch = null;
+    for (const line of block.split('\n')) {
+      if (line.startsWith('worktree ')) wt = line.slice('worktree '.length);
+      else if (line.startsWith('branch ')) branch = line.slice('branch '.length);
+    }
+    if (wt) out.push({ path: wt, branch });
+  }
+  return out;
+}
+
+const realOr = (fs, p) => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
+
+// Absolute path of a git-state file of the main checkout (via --git-path).
+function statePath(ctx, name) {
+  const r = ctx.G(['rev-parse', '--git-path', name]);
+  return r.status === 0 && r.stdout.trim() ? path.resolve(ctx.main, r.stdout.trim()) : null;
+}
+
+const stateExists = (ctx, name) => { const p = statePath(ctx, name); return p !== null && ctx.fs.existsSync(p); };
+const inProgress = (ctx) => IN_PROGRESS.filter((n) => stateExists(ctx, n));
+const head = (ctx) => ctx.G(['rev-parse', 'HEAD']).stdout.trim();
+const trackedDirty = (ctx, dir) => ctx.git(['-C', dir || ctx.main, 'status', '--porcelain', '--untracked-files=no']).stdout.trim() !== '';
+const hasRef = (ctx, ref) => ctx.G(['rev-parse', '--verify', '--quiet', ref]).status === 0;
+const isAncestor = (ctx, a, b) => ctx.G(['merge-base', '--is-ancestor', a, b]).status === 0;
+
+// Trunk name per the base-preflight rule, or null.
+function detectTrunk(ctx, requested) {
+  if (requested) return requested;
+  const h = ctx.G(['symbolic-ref', '-q', '--short', 'refs/remotes/origin/HEAD']);
+  if (h.status === 0 && h.stdout.trim().startsWith('origin/')) return h.stdout.trim().slice('origin/'.length);
+  for (const name of ['main', 'master']) {
+    if (hasRef(ctx, `refs/heads/${name}`) || hasRef(ctx, `refs/remotes/origin/${name}`)) return name;
+  }
+  return null;
+}
+
+// The main checkout's state is exactly the pre-merge one: HEAD at pre, no merge, clean tracked tree.
+const settled = (ctx, pre) => head(ctx) === pre && !stateExists(ctx, 'MERGE_HEAD') && !trackedDirty(ctx);
+
+// Puts the main checkout back at `pre`. Abort first, reset --merge as the fallback.
+function undoMerge(ctx, pre) {
+  if (stateExists(ctx, 'MERGE_HEAD')) ctx.G(['merge', '--abort']);
+  if (settled(ctx, pre)) return true;
+  ctx.G(['reset', '--merge', pre]);
+  return settled(ctx, pre);
+}
+
+const stuck = (ctx, fail) => fail('main left mid-merge: the merge could not be aborted; resolve or abort it by hand in ' + ctx.main);
+
+// Slot worktrees other than `ticket`, with trunk commits their branch lacks.
+function behindList(ctx, trunk, ticket) {
+  const wl = ctx.G(['worktree', 'list', '--porcelain']);
+  if (wl.status !== 0) return [];
+  const out = [];
+  for (const w of parseWorktrees(wl.stdout)) {
+    const m = w.branch && BRANCH_RE.exec(w.branch);
+    if (!m || Number(m[1]) === ticket || realOr(ctx.fs, w.path) === ctx.main || !ctx.fs.existsSync(w.path)) continue;
+    const c = ctx.G(['rev-list', '--count', `${branchOf(m[1])}..refs/heads/${trunk}`]);
+    const n = Number(c.stdout.trim());
+    if (c.status === 0 && Number.isInteger(n) && n > 0) out.push({ ticket: Number(m[1]), path: w.path, behind: n });
+  }
+  return out.sort((a, b) => a.ticket - b.ticket);
+}
+
+// The marker's ticket number, or null (absent, unreadable or unparseable: the hook ignores it too).
+function markerTicket(ctx) {
+  try {
+    const raw = String(ctx.fs.readFileSync(path.join(ctx.main, '.trailhead', 'session-ticket'), 'utf8')).replace(/^\uFEFF/, '');
+    const m = raw.split('\n')[0].replace(/\r$/, '').match(/^#([1-9]\d*)(?:\s|$)/);
+    return m ? Number(m[1]) : null;
+  } catch { return null; }
+}
+
+// --- merge --------------------------------------------------------------------
+
+function mergeBranch(ctx, o) {
+  const { fail, emit } = ctx;
+  const branch = branchOf(o.ticket);
+  const ref = `refs/heads/${branch}`;
+  const trunk = detectTrunk(ctx, o.trunk);
+  if (!trunk) return fail('no trunk found (no remote default branch, main or master); pass --trunk');
+  if (!hasRef(ctx, `refs/heads/${trunk}`)) return fail(`trunk ${trunk} has no local branch`);
+  const result = (status, extra) => { emit({ status, ticket: o.ticket, branch, trunk, ...extra }); return 0; };
+
+  const sym = ctx.G(['symbolic-ref', '-q', 'HEAD']);
+  if (sym.stdout.trim() !== `refs/heads/${trunk}`) return result('not-on-trunk', { reason: `the main checkout is on ${sym.stdout.trim() || 'a detached HEAD'}, not ${trunk}` });
+  const busy = inProgress(ctx);
+  if (busy.length) return result('in-progress', { reason: `${busy.join(', ')} present in the main checkout; run recover first` });
+  if (trackedDirty(ctx)) return result('dirty', { reason: 'tracked changes in the main checkout' });
+  if (!hasRef(ctx, ref)) return fail(`branch ${branch} does not exist`);
+
+  const wl = ctx.G(['worktree', 'list', '--porcelain']);
+  const slot = wl.status === 0 ? parseWorktrees(wl.stdout).find((w) => w.branch === ref && realOr(ctx.fs, w.path) !== ctx.main) : null;
+  if (slot && ctx.fs.existsSync(slot.path) && trackedDirty(ctx, slot.path)) return result('slot-dirty', { path: slot.path, reason: `uncommitted tracked work in ${slot.path} would be left out of the merge` });
+
+  if (isAncestor(ctx, ref, `refs/heads/${trunk}`)) return result('already-merged', { head: head(ctx), behind: behindList(ctx, trunk, o.ticket) });
+
+  const pre = head(ctx);
+  // marker di un altro ticket: l'hook commit-msg rifiuterebbe il merge commit, lo saltiamo
+  const marker = markerTicket(ctx);
+  const skipHook = marker !== null && marker !== o.ticket;
+  const m = ctx.G(['merge', '--no-edit', ...(skipHook ? ['--no-verify'] : []), '-m', `chore(auto): merge ${branch}`, '-m', `Refs: #${o.ticket}`, branch]);
+  if (m.status === 0) {
+    if (!isAncestor(ctx, ref, 'HEAD')) return fail(`git merge reported success but ${branch} is not in the trunk`);
+    const method = ctx.G(['rev-parse', '--verify', '--quiet', 'HEAD^2']).status === 0 ? 'merge' : 'ff';
+    return result('merged', { method, from: pre, head: head(ctx), behind: behindList(ctx, trunk, o.ticket) });
+  }
+
+  const conflicts = ctx.G(['diff', '--name-only', '--diff-filter=U']).stdout.split('\n').filter(Boolean);
+  const reason = firstLine(m.stderr) || firstLine(m.stdout) || `git merge exited ${m.status}`;
+  if (!undoMerge(ctx, pre)) return stuck(ctx, fail);
+  if (conflicts.length > 0) return result('conflict', { conflicts });
+  return result('merge-failed', { reason });
+}
+
+// --- recover ------------------------------------------------------------------
+
+function recoverMerge(ctx) {
+  const { fail, emit } = ctx;
+  const busy = inProgress(ctx);
+  if (!busy.length) { emit({ status: 'clean' }); return 0; }
+  if (!busy.includes('MERGE_HEAD')) { emit({ status: 'foreign', reason: `${busy.join(', ')} in progress, not started by a run` }); return 0; }
+  let msg = '';
+  try { msg = String(ctx.fs.readFileSync(statePath(ctx, 'MERGE_MSG'), 'utf8')); } catch { /* unreadable: foreign */ }
+  const m = MERGE_SUBJECT.exec(firstLine(msg).trim());
+  if (!m) { emit({ status: 'foreign', reason: 'a merge not started by a run is in progress' }); return 0; }
+  if (!undoMerge(ctx, head(ctx))) return stuck(ctx, fail);
+  emit({ status: 'aborted', ticket: Number(m[1]), branch: branchOf(m[1]) });
+  return 0;
+}
+
+// --- remove -------------------------------------------------------------------
+
+// True when dir is an independent checkout (its git dir lives inside it) on `branch`.
+function cloneOnBranch(ctx, dir, branch) {
+  const g = ctx.git(['-C', dir, 'rev-parse', '--absolute-git-dir']);
+  if (g.status !== 0) return false;
+  const gitDir = realOr(ctx.fs, g.stdout.trim());
+  const root = realOr(ctx.fs, dir);
+  if (gitDir !== root && !gitDir.startsWith(root + path.sep)) return false;
+  const b = ctx.git(['-C', dir, 'symbolic-ref', '--quiet', 'HEAD']);
+  return b.status === 0 && b.stdout.trim() === `refs/heads/${branch}`;
+}
+
+function removeSlot(ctx, o) {
+  const { fail, emit } = ctx;
+  const branch = branchOf(o.ticket);
+  const ref = `refs/heads/${branch}`;
+  const trunk = detectTrunk(ctx, o.trunk);
+  if (!trunk) return fail('no trunk found (no remote default branch, main or master); pass --trunk');
+  if (!hasRef(ctx, `refs/heads/${trunk}`)) return fail(`trunk ${trunk} has no local branch`);
+
+  const wl = ctx.G(['worktree', 'list', '--porcelain']);
+  if (wl.status !== 0) return fail(`git worktree list failed: ${firstLine(wl.stderr) || 'exit ' + wl.status}`);
+  const slot = parseWorktrees(wl.stdout).find((w) => w.branch === ref && realOr(ctx.fs, w.path) !== ctx.main);
+
+  if (!slot) {
+    const sibling = path.join(path.dirname(ctx.main), `${path.basename(ctx.main)}-t${o.ticket}`);
+    if (ctx.fs.existsSync(sibling) && cloneOnBranch(ctx, sibling, branch)) { emit({ status: 'kept', ticket: o.ticket, kind: 'clone', path: sibling, reason: 'a clone slot is never deleted' }); return 0; }
+  }
+
+  const branchExists = hasRef(ctx, ref);
+  if (branchExists && !isAncestor(ctx, ref, `refs/heads/${trunk}`)) {
+    emit({ status: 'not-merged', ticket: o.ticket, branch, reason: `${branch} is not merged into ${trunk}; nothing removed` });
+    return 0;
+  }
+
+  let worktreeRemoved = false;
+  if (slot && ctx.fs.existsSync(slot.path)) {
+    const rm = ctx.G(['worktree', 'remove', slot.path]);
+    if (rm.status !== 0) return fail(`git worktree remove failed for ${slot.path}, kept: ${firstLine(rm.stderr) || 'exit ' + rm.status}`);
+    worktreeRemoved = true;
+  } else if (slot) {
+    return fail(`stale worktree of ${branch}: ${slot.path} is gone from disk but git still lists it; run git worktree prune and retry`);
+  }
+
+  let branchDeleted = false;
+  if (branchExists) {
+    const d = ctx.G(['branch', '-d', branch]);
+    if (d.status !== 0) return fail(`git branch -d ${branch} failed: ${firstLine(d.stderr) || 'exit ' + d.status}`);
+    branchDeleted = true;
+  }
+  emit({ status: 'removed', ticket: o.ticket, branch, worktreeRemoved, branchDeleted });
+  return 0;
+}
+
+function main(argv, { git, stdout, stderr, fs } = {}) {
+  const out = stdout || process.stdout;
+  const err = stderr || process.stderr;
+  const o = parseArgs(argv || []);
+  if (o.error) { err.write(o.error + '\n'); return 2; }
+  const fsx = fs || nodeFs;
+  const emit = (obj) => out.write(JSON.stringify(obj) + '\n');
+  const fail = (reason, extra) => { emit({ status: 'error', reason, ...extra }); return 1; };
+  const run = git || defaultGit;
+  const mainDir = realOr(fsx, o.repo);
+  const ctx = { git: run, G: (args) => run(['-C', mainDir, ...args]), fs: fsx, main: mainDir, fail, emit };
+  if (ctx.G(['rev-parse', '--git-dir']).status !== 0) return fail(`${o.repo} is not a git repository`);
+  if (o.cmd === 'merge') return mergeBranch(ctx, o);
+  if (o.cmd === 'recover') return recoverMerge(ctx);
+  return removeSlot(ctx, o);
+}
+
+module.exports = { main, parseArgs, parseWorktrees };
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2), {}));
+}