@mmerterden/multi-agent-pipeline 20.35.0 → 20.37.0

package/pipeline/commands/multi-agent/refactor/SKILL.md

@@ -17,6 +17,8 @@ Deep-analyses the current project, extracts the global best-practices worth adop
 
 **Input**: $ARGUMENTS (optional  -  `backlog` runs Step 0e alone; otherwise an area to focus on: "security", "performance", "tests", "bugs", "best-practices", "drift", "multi-agent-toolkit", etc.)
 
+Procedures, output tables, the band list and the focus filter live in `$HOME/.claude/multi-agent-refs/refactor/sweep.md`. Read it before Step 0; each step below names the section it uses.
+
 ## Flow
 
 ```
@@ -24,229 +26,80 @@ Step 0:  BEST-PRACTICES  Research the field, extract the best approaches, ADAPT
 Step 0b: DRIFT           Check upstream-derived skills for updates we have not pulled -> plan band D
 Step 0c: DEV-TOOLKIT     Research current MCP practice + audit the companion multi-agent-toolkit repo -> plan band E
 Step 0d: RUN-ERRORS      Read the local run-error ledger, rank recurring failures -> plan band F
+Step 0e: BACKLOG         Decide the open observations recorded mid-task -> plan band G
 Step 1:  SCAN            Walk the project structure (files, LOC, dependencies, CI, tests)
 Step 2:  ANALYZE         10 categories + an explicit BUG HUNT (real defects, not just scores) -> plan bands B, C
 Step 3:  SCORE           Each category /10, overall /100
-Step 4:  PLAN            Merge bands A (best-practice) + B (bugs) + C (improvements) + D (drift) + E (multi-agent-toolkit) + F (run-errors)
+Step 4:  PLAN            Merge every band into one table
 Step 5:  ASK             "Start the work?"  -  wait for user approval
 Step 6:  IMPLEMENT       Apply approved items one by one (lint, test, commit)
 Step 7:  VERIFY          Confirm every test + lint passes
 Step 8:  ASK SYNC        "Run /multi-agent:sync?"  -  wait for user approval
 ```
 
-Plan bands (all five feed the single Step 4 table):
-- **A - Best-practice**: the best field approaches, adapted so they actually fit this repo.
-- **B - Bug**: real defects found in the code (correctness, security, data-loss, crashes).
-- **C - Improvement**: quality/perf/DX gaps surfaced by the 10-category analysis.
-- **D - Drift**: upstream updates to skills we derived from an external source.
-- **E - Dev-toolkit**: current-practice gaps in the companion multi-agent-toolkit MCP server (the pipeline's device and browser hands), applied in that repo.
-- **F - Run-errors**: recurring real failures the pipeline actually hit across past runs, read from the local run-error ledger. These are lived evidence, not speculation - a failure that recurs across users or tasks is a prioritized improvement area.
-
-## Step 0: BEST-PRACTICES  -  research the field, adapt to us
-
-Do not copy features blindly. The goal is the best *approaches*, reshaped so they are applicable to THIS project's stack, size, and constraints.
-
-1. **Identify the domain** of the current project (read README + package/build manifests): what kind of project is it (CLI, SDK, app, pipeline, library), what stack, who uses it.
-2. **Research the best-in-class** for that exact domain. When `ai-analyst-toolkit` is enabled, run the first three bullets through its skills (`evidence-github`, `evidence-registry`, `signal-community`) rather than ad-hoc searching: they carry the query forms and the citation format, and they keep the evidence / signal line straight - a GitHub PR is a fact, a forum thread is one person's experience. Not enabled is a recorded no-op and the manual searches below still apply.
-   - **GitHub**: search the domain terms + `stars:>50`; read the top repos' READMEs, architecture docs, CI configs, test layout.
-   - **X / Twitter**: search the domain terms + "best practices" / "we switched to" / "lesson learned"; capture what practitioners and tool authors actually recommend right now (WebFetch/WebSearch on `x.com` / `twitter.com` threads).
-   - **Reddit**: relevant subreddits for real-world pain points and adopted patterns.
-   - **Web**: "<domain> best practices <current-year>", official style guides, and the platform's own guidance.
-3. **For each candidate approach, record**:
-   - what it is, who does it well (source link)
-   - the concrete benefit
-   - **adaptation**: exactly how it would look in OUR repo (which file/dir/script), and what has to change for it to fit  -  not a generic "add tests" but "add a flow-assertion helper in `test/helpers/`"
-   - effort (Low/Med/High) and impact (Low/Med/High/Critical)
-4. **Discard** approaches that do not fit our stack, our scale, or our constraints  -  and say WHY (so the user sees the filter working, not just the survivors).
-
-Output (plan band A):
-```
-| Source | Approach | Adaptation to our repo | Effort | Impact | In plan? |
-|--------|----------|------------------------|--------|--------|----------|
-| <repo> | <what>   | <concrete change here> | Low    | High   | Yes (P1) |
-| <repo> | <what>   | does not fit: <reason> | -      | -      | No       |
-```
-Roll the high-impact + low/med-effort survivors into the Step 4 plan as band-A items.
+## Step 0: BEST-PRACTICES
 
-## Step 0b: DRIFT  -  upstream-derived skill check
+Do not copy features blindly. Identify the domain, research the best-in-class (through `ai-analyst-toolkit` skills when enabled), record each candidate with its source, benefit, concrete adaptation to OUR repo, effort and impact, and discard what does not fit with the reason stated. Procedure and band-A table: `sweep.md` "Step 0".
 
-Some skills/components in this project (or in the marketplace plugins it ships) were derived from an upstream source. Upstream keeps evolving  -  it fixes bugs and adds features. This step detects upstream drift so we can decide whether to pull the improvements back.
+## Step 0b: DRIFT  -  upstream-derived skill check
 
 Rules that hold for every entry:
 - The upstream mapping is **configuration, never hardcoded**: `global.derivedSkillSources` in `~/.claude/multi-agent-preferences.json`. Missing or empty -> **skip** and report "no derived-skill sources configured". Never invent a source.
 - **The plugin cache is a mirror, not the authority.** Never let the cache alone produce an "up to date" verdict; report it as **`unverified (cache only)`**. An unreachable upstream is recorded as "upstream unreachable" and the run continues.
 - Each drifted entry becomes a band-D plan item. Do not auto-apply upstream changes  -  they go through Step 5 approval like everything else, and after porting, bump the entry's `derivedFromVersion`.
 
-Full procedure: `$HOME/.claude/multi-agent-refs/refactor/drift.md`. Read it when `global.derivedSkillSources` has at least one entry (entry schema, source resolution order, version manifest, comparison, band-D table).
+Full procedure: `$HOME/.claude/multi-agent-refs/refactor/drift.md`. Read it when `global.derivedSkillSources` has at least one entry.
 
-## Step 0c: DEV-TOOLKIT  -  current MCP practice for the companion toolkit
+## Step 0c: DEV-TOOLKIT
 
-The pipeline's hands on devices and browsers are MCP tools served by a companion repo (`multi-agent-toolkit-mcp`): Phase 3 test, `manual-test`, `design-check` and `apple-archive-compliance` all call them, and several pipeline skills declare a minimum toolkit version (see `cross-cli-contract.md`). That repo therefore has to track the MCP field, not just its own README. This step researches what current practice is and audits the toolkit against it.
+Audit the companion `multi-agent-toolkit-mcp` repo against current MCP practice. Resolution is configuration first, never a hardcoded path; skip when nothing resolves or `enabled` is false. Read `$HOME/.claude/multi-agent-refs/refactor/toolkit-research.md` before running this step.
 
-Full procedure  -  resolution (configuration first, never a hardcoded path; skip when nothing resolves or `enabled` is false), the 5 research axes, the audit command block, and the band-E output table + rules  -  lives in `$HOME/.claude/multi-agent-refs/refactor/toolkit-research.md`. Read it before running this step.
+## Step 0d: RUN-ERRORS
 
-## Step 0d: RUN-ERRORS  -  what the pipeline actually failed on
+Read `$HOME/.claude/logs/multi-agent/errors-ledger.jsonl`. Missing, unreadable or empty means skip band F silently  -  it is additive signal, never a gate. With a focus area, still read it. A tag that stopped recurring after a version bump is resolved: report it, do not re-raise it. Never quote a user's identity as blame. Read `$HOME/.claude/multi-agent-refs/refactor/run-errors.md` when the ledger exists.
 
-Before speculating about improvements, read what real runs already failed on. When usage logging is enabled, every terminated run appends its errors to a local ledger at `$HOME/.claude/logs/multi-agent/errors-ledger.jsonl`. A missing, unreadable or empty ledger means skip band F silently  -  it is additive signal, never a gate. If `$ARGUMENTS` names a focus area, still read the ledger  -  a recurring run error in that area is the strongest possible signal. A tag that stopped recurring after a version bump is resolved: report it, do not re-raise it. Never quote a user's identity as blame.
-
-Full procedure: `$HOME/.claude/multi-agent-refs/refactor/run-errors.md`. Read it when the ledger exists (record shape, grouping and ranking, transcript mining, band-F table).
-
-## Step 0e: BACKLOG  -  friction this pipeline already noticed
-
-Every other band in this command derives its findings from scratch, which is right for a sweep and has one consequence nobody chose: a friction noticed mid-task is gone by the next run unless it was fixed within the hour. Most are not, because stopping mid-task to fix them is the wrong call. So they are written down when noticed and decided here.
+## Step 0e: BACKLOG
 
 ```bash
 node "$HOME/.claude/scripts/observations.mjs" scan --status open --json
 ```
 
-Exit 3 is `SCAN BROKEN`  -  files on disk, none parsed. That is a broken reader, not an empty queue: halt the band and say so rather than reporting "0 open".
-
-Split every open observation into actionable / sibling-propagation / to-decline, and resolve the sibling surfaces mechanically with `skill-siblings.mjs`, never from memory  -  a command is authored in `commands/`, mirrored into `skills/shared/core/`, and installed again into three host trees, so a fix applied to one copy drifts from the rest with every gate still green. Output as plan band G, same table shape as the other bands.
-
-`/multi-agent:refactor backlog` runs this band alone. The full sweep is unchanged and still includes it. Buckets, the status vocabulary, why `parked` needs a named unblocking event, and how to write an observation: `$HOME/.claude/multi-agent-refs/refactor/observations.md`.
+Exit 3 is `SCAN BROKEN`  -  files on disk, none parsed. Halt the band and say so rather than reporting "0 open". Split every open observation into actionable / sibling-propagation / to-decline, and resolve sibling surfaces mechanically with `skill-siblings.mjs`, never from memory. Output as plan band G. `/multi-agent:refactor backlog` runs this band alone. Buckets, statuses and how to write an observation: `$HOME/.claude/multi-agent-refs/refactor/observations.md`.
 
 ## Step 1: SCAN
 
-```
-- file count, LOC (cloc or wc -l)
-- package.json / Package.swift / build.gradle analysis
-- dependency count (runtime vs dev)
-- Is there a CI/CD pipeline? (.github/workflows/, fastlane/, Makefile)
-- Is there test infrastructure? How many tests? Coverage?
-- Is a linter/formatter config in place?
-- Do README, LICENSE, SECURITY.md, CHANGELOG.md exist?
-- Git state: branch count, last commit date, tags
-```
+Walk files, LOC, manifests, dependencies, CI, tests, linters, repo docs and git state (`sweep.md` "Step 1").
 
 ## Step 2: ANALYZE  -  10 categories + BUG HUNT
 
-### 2a. 10 categories (quality lens)
-
-| # | Category | What to check |
-|---|----------|---------------|
-| 1 | **Architecture** | Layer separation, modularity, SOLID, dependency direction |
-| 2 | **Code Quality** | Naming, magic numbers, dead code, complexity, DRY |
-| 3 | **Security** | Hardcoded secrets, input validation, Keychain, ATS, ATT |
-| 4 | **Tests** | Coverage, test pyramid, edge cases, mock/stub quality |
-| 5 | **CI/CD** | Build matrix, lint job, release automation, artifact caching |
-| 6 | **Docs** | README quality, JSDoc / Swift docs, API docs, CHANGELOG |
-| 7 | **Performance** | Bundle size, lazy loading, memory leaks, unnecessary re-renders |
-| 8 | **Accessibility** | a11y labels, tap targets, VoiceOver, Dynamic Type |
-| 9 | **Dependency Management** | Outdated deps, vulnerability scan, lockfile, version pinning |
-| 10 | **DevEx** | Onboarding time, script ergonomics, error messages, debug tooling |
-
-### 2b. BUG HUNT (real defects, not scores)
-
-Category scores measure quality; they do not find the bug that ships. Run an explicit defect hunt IN ADDITION to the scoring:
-
-- Dispatch focused review agents (Agent tool, `code-reviewer` persona where available) over the highest-risk surfaces: recently changed files, error/edge-path handling, concurrency, external input parsing, resource cleanup, off-by-one boundaries.
-- For each candidate defect, record: **file:line**, the concrete failure scenario (inputs/state -> wrong output/crash), and severity.
-- **Verify before reporting**: only list a bug you can trace to a real failure path; drop the plausible-but-unprovable ones. Match the bar you would apply to a third party's code.
-
-Output (plan band B) - every confirmed defect becomes a P0/P1 item:
-```
-| # | Severity | File:line | Defect | Failure scenario |
-|---|----------|-----------|--------|------------------|
-| 1 | Blocking | src/x.ts:42 | unchecked nil deref | empty response -> crash |
-```
-
-Improvement areas surfaced by 2a that are not outright bugs become band-C items.
+2a scores the 10 categories (`sweep.md` "Step 2a"). 2b runs an explicit defect hunt IN ADDITION to the scoring (`sweep.md` "Step 2b"). **Verify before reporting**: only list a bug you can trace to a real failure path with `file:line` and a concrete failure scenario; drop the plausible-but-unprovable ones, at the bar you would apply to a third party's code. Confirmed defects are band B (P0/P1); non-bug gaps from 2a are band C.
 
 ## Step 3: SCORE
 
-Each category is scored out of 10. Output:
+Each category /10, total /100 (`sweep.md` "Step 3").
 
-```
-+---------------------+-------+
-| Category            | Score |
-+---------------------+-------+
-| Architecture        | 9/10  |
-| Code Quality        | 8/10  |
-| Security            | 9/10  |
-| Tests               | 7/10  |
-| CI/CD               | 8/10  |
-| Docs                | 7/10  |
-| Performance         | 9/10  |
-| Accessibility       | 6/10  |
-| Dependency Mgmt     | 8/10  |
-| DevEx               | 9/10  |
-+---------------------+-------+
-| TOTAL               | 80/100|
-+---------------------+-------+
-```
+## Step 4: PLAN
 
-## Step 4: PLAN  -  one merged, prioritized table
-
-Merge all five bands into a single plan. Tag each row with its band (A best-practice / B bug / C improvement / D drift / E multi-agent-toolkit) so the source is visible.
-
-```
-| # | Priority | Band | Category | Item | Impact |
-|---|----------|------|----------|------|--------|
-| 1 | P0 | B | Security | Remove hardcoded API key (src/x:12) | Critical |
-| 2 | P0 | B | Tests | Fix nil-deref on empty response (src/y:42) | High |
-| 3 | P1 | A | CI/CD | Adopt matrix build (adapt: .github/workflows/ci.yml) | Medium |
-| 4 | P1 | D | Skills | Port upstream <plugin> 0.3.0 fixes into <localPath> | Medium |
-| 5 | P1 | E | Toolkit | Add read-only annotations to the multi-agent-toolkit device tools | Medium |
-| 6 | P2 | C | DevEx | Rename npm scripts for consistency | Low |
-```
-
-Priority levels:
-- **P0**: bugs, security holes, broken functionality  -  must fix
-- **P1**: clear quality improvement or high-value adopted best-practice / drift port  -  should be done
-- **P2**: nice-to-have  -  if time allows
+One merged table, every row tagged with its band, priorities P0 / P1 / P2 (`sweep.md` "Step 4").
 
 ## Step 5: ASK  -  user approval
 
-After showing the plan, ask:
-
 > "Found X items (P0: N, P1: M, P2: K) across bugs, best-practices, improvements, upstream drift, and multi-agent-toolkit practice. Should I start the work?"
 
-Options:
-- "Yes, do all"
-- "Only P0"
-- "P0 + P1 only"
-- "Only bugs (band B)"
-- "Only the multi-agent-toolkit (band E)"
-- (the user may pick specific items)
+Options: "Yes, do all" / "Only P0" / "P0 + P1 only" / "Only bugs (band B)" / "Only the multi-agent-toolkit (band E)" / specific items.
 
 **Never start the work without approval.**
 
 ## Step 6: IMPLEMENT
 
-Apply the approved items one by one:
-
-1. For each item:
-   - apply the change (for band D, port the upstream diff into `localPath`, then bump that entry's `derivedFromVersion` in preferences)
-   - band-E items are applied inside the toolkit repo, never mirrored here: edit there, re-run its gates (`node --check`, the `tools/list` handshake, advertised tool count matching reality), then commit there with that repo's own convention. Publishing is `/multi-agent:sync` Step 3d  -  do not publish from this step.
-   - run the relevant tests
-   - on success, move to the next
-   - on failure, roll back and notify the user
-2. After all changes are done:
-   - run the full lint + test suite
-   - on success, commit
-
-Commit format: `refactor(scope): {short description}`
+Apply approved items one by one, testing each and rolling back on failure (`sweep.md` "Step 6"). Band-E items are applied and committed inside the toolkit repo, never mirrored here, and never published from this step. Commit format: `refactor(scope): {short description}`.
 
 ## Step 7: VERIFY
 
-```bash
-# Lint
-npm run lint 2>/dev/null || swift build 2>/dev/null
-
-# Test
-npm test 2>/dev/null || swift test 2>/dev/null || xcodebuild test 2>/dev/null
-
-# Result
-echo "Lint: PASS/FAIL"
-echo "Test: PASS/FAIL (X/Y passed)"
-```
-
-If any band-E item was applied, verify the toolkit repo too  -  syntax check every file it loads, handshake the server and confirm `tools/list` still answers, and confirm the advertised tool counts (README header, `package.json` description) match the count the server reports.
+Full lint + test must pass; band-E work also re-verifies the toolkit (`sweep.md` "Step 7").
 
 ## Step 8: ASK SYNC
 
-After every approved item is applied, ask:
-
 > "Work is complete. Should I run /multi-agent:sync?"
 
 Options:
@@ -256,18 +109,4 @@ Options:
 
 ## Focus filter
 
-If $ARGUMENTS is set, focus on that band/category only:
-
-| Input | Focus |
-|-------|-------|
-| `bugs` | Bug hunt only (band B) |
-| `best-practices` | Field research + adapted plan only (band A) |
-| `drift` | Upstream derived-skill drift only (band D) |
-| `multi-agent-toolkit` | Companion MCP toolkit research + audit only (band E) |
-| `security` | Security analysis only |
-| `tests` | Test coverage and quality only |
-| `performance` | Performance optimisation only |
-| `docs` | Docs only |
-| `ci` | CI/CD pipeline only |
-| `deps` | Dependency updates only |
-| (empty) | Everything (default) |
+If $ARGUMENTS is set, focus on that band/category only; the mapping is `sweep.md` "Focus filter". Empty runs everything.

package/pipeline/commands/multi-agent/resume/SKILL.md

@@ -13,185 +13,79 @@ allowed-tools: Agent, Bash, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdat
 
 **Input**: $ARGUMENTS
 
-> **Language (read FIRST)**: Before any status output, read `prefs.global.outputLanguage` and render every conversational line in it. `AskUserQuestion` renders its `question`, option `label`s and option `description`s in `outputLanguage`; only `header` stays English (<=12-char chip); external payload bodies follow `outputLanguage` too (identifiers, commit messages, branch names stay English). Full contract: `$HOME/.claude/multi-agent-refs/rules.md` "Language Application".
+> **Language (read FIRST)**: read `prefs.global.outputLanguage` before any output; chat, `AskUserQuestion` `question` / `label` / `description` and payload bodies follow it, `header` (<=12 chars), identifiers, commit messages and branch names stay English (`$HOME/.claude/multi-agent-refs/rules.md` "Language Application").
 
-Unfinished work reaches this command from two directions, and which one you are in is a property of the repository, not of how you typed the command:
+Unfinished work arrives two ways, decided by the repository:
 
-- **A tracked run stopped.** It has an `agent-state.json`, a phase it was inside, and possibly a worktree. It resumes from where it stopped.
-- **Work exists on the current branch with no run behind it.** You wrote it by hand, or a run outside the pipeline produced it. There is nothing to resume, so the **pipeline tail** runs over the diff: Review (with its build gate) → Commit/PR → Report. Plan and Dev never run; the diff already on the branch is the Dev output.
+- **A tracked run stopped.** It has an `agent-state.json`, a phase, maybe a worktree. It resumes where it stopped.
+- **Work on the current branch with no run behind it.** The **pipeline tail** runs over the diff: Review (with its build gate) → Commit/PR → Report. Plan and Dev never run; the diff is the Dev output.
 
-Step 1 finds both and asks. A single command means you do not have to know which case you are in before you can ask the question.
-
-## Input
-
-```bash
-/multi-agent:resume                       # list everything resumable, pick one
-/multi-agent:resume #2                    # a tracked run by task number
-/multi-agent:resume PROJ-12345            # a tracked run by Jira id, or bind the tail to that id
-/multi-agent:resume --base develop        # tail path: override the base branch for the diff
-/multi-agent:resume #2 --answer continue  # answer the question the run stopped on, then re-enter its step
-/multi-agent:resume autopilot             # no gate prompts: auto-fix, auto-PR, auto-comment
-```
-
-## When NOT to use it
-
-- The change is not written yet  -  use `/multi-agent`.
-- Only the review is wanted  -  `/multi-agent:review`. Only the report  -  `/multi-agent:channels`. Only device UI testing  -  `/multi-agent:test` / `/multi-agent:manual-test`.
-- The run is abandoned rather than paused  -  `/multi-agent:kill #N`, or `/multi-agent:garbage-collect --abandoned` for the Phase 0 leftovers.
+Examples, when NOT to use it and modes: `$HOME/.claude/multi-agent-refs/resume/details.md` "Usage".
 
 ## Steps
 
 ### Step 1  -  Build the resumable list, then ask
 
-Collect both sources before rendering anything. An argument that names a run (`#N`, a Jira id, a GitHub issue number) selects it directly and skips the question; an argument that names nothing resumable is an error, never a silent fall-through to the tail.
-
-**Source A  -  tracked runs.** Every `agent-state.json` under `$HOME/.claude/logs/multi-agent/{project}/` whose `status != "done"`. Each row carries what the choice actually turns on: task id, the phase it stopped inside, its workspace (the worktree path, or `local` when `worktreePath` is the project root), how long it has been sitting, and `haltReason` when set.
-
-**Source B  -  untracked work on the current branch.** Resolve the base branch in order: `--base <arg>` → `figma-config.project.baseBranch` → `develop` → the branch's upstream/merge-base. The work is `git diff <base>...HEAD` plus uncommitted working-tree changes. The row appears only when that diff is non-empty **and** no Source A run already owns this branch  -  otherwise the same work would be offered twice under two different contracts.
+Collect both sources before rendering. An argument naming a run (`#N`, a Jira id, an issue number) selects it and skips the question; an argument naming nothing resumable is an error, never a silent fall-through to the tail.
 
-**Ask.** Full rules: `$HOME/.claude/multi-agent-refs/picker-contract.md`. This is a one-step chain, so the breadcrumb is `Step 1/1: which unfinished work to pick up`, rendered in `outputLanguage` above the picker. `question`, every `label` and every `description` render in `outputLanguage`; `header` stays English (`Resume what`). Source A rows first (newest first), Source B last. Labels carry proper nouns verbatim - task id, branch name - and the run branches on which row was selected, never on the label text.
+**Source A  -  tracked runs**: each `agent-state.json` under `$HOME/.claude/logs/multi-agent/{project}/` with `status != "done"` (id, phase, workspace, idle time, `haltReason`).
 
-**One candidate is still a question.** A single row is asked with a genuine escape as its second option, because `AskUserQuestion` refuses a call with fewer than two declared options and discards every question batched with it. Which escape each case offers: `$HOME/.claude/multi-agent-refs/resume/details.md` "Single-candidate escape", read before Step 1.
+**Source B  -  untracked work**: base = `--base` → `figma-config.project.baseBranch` → `develop` → upstream/merge-base; work = `git diff <base>...HEAD` plus uncommitted changes. Shown only when non-empty **and** no Source A run owns this branch.
 
-Zero rows in both sources: do not ask. Stop with `ERR: nothing to resume  -  no stopped run for this project and no local changes on {branch} vs {base}`.
+**Ask** per `$HOME/.claude/multi-agent-refs/picker-contract.md`: breadcrumb `Step 1/1: which unfinished work to pick up`, `header` `Resume what`, Source A rows first (newest first), Source B last; branch on the selected row, never on label text. **One candidate is still a question**, with a genuine escape as the second option: read `resume/details.md` "Single-candidate escape" before Step 1. Zero rows: do not ask; stop with `ERR: nothing to resume  -  no stopped run for this project and no local changes on {branch} vs {base}`.
 
-**The answer routes.** A Source A row runs Steps 2-5 and nothing else; a Source B row runs Steps 6-7 and nothing else. The two halves never both run in one invocation.
+A Source A row runs Steps 2-5 only; a Source B row runs Steps 6-7 only. Never both.
 
 ### Step 2  -  Tracked run: read and validate state
 
-- Validate first: `node $HOME/.claude/scripts/validate-state.mjs <state-file>` (resume-safety check, tolerant of legacy shapes). On non-zero exit, do NOT guess a phase  -  surface the errors and stop with `ERR: agent-state.json is unsafe to resume; inspect it or 'kill #N' and restart.`
-- Confirm the worktree (`worktreePath` / `projects[].worktreePath`) exists and is usable; if missing or locked, run the Phase 0 "Worktree stale-lock heal" before continuing.
-  - **Unless `state.worktreeRemovedAt` is set.** Then the worktree was removed on purpose by Phase 4 once the PR opened, the branch is still local, and the artefacts live under `state.artifactsPath`. Do NOT heal or recreate it: read state from `artifactsPath`, and if the remaining work needs a checkout (a Phase 5 pause needs none), ask before moving the user's HEAD  -  they may be mid-work on another branch, which is exactly why the removal did not check the branch out.
-- `currentPhase`  -  last completed phase
-- `status`  -  `paused` | `failed` | `in_progress`
-- `haltReason`  -  if set, show it so the user knows why the run stopped; clear it on successful re-entry
-- `circuitBreaker`  -  if `tripped`, show `trigger` + `detail`, then set `tripped: false` and keep `counters`; if the same trigger fires again at the next checkpoint the breaker re-trips (no silent bypass)
-- `autopilot`  -  preserve the mode
+- `node $HOME/.claude/scripts/validate-state.mjs <state-file>`. Non-zero: do NOT guess a phase; stop with `ERR: agent-state.json is unsafe to resume; inspect it or 'kill #N' and restart.`
+- Missing or locked worktree: Phase 0 "Worktree stale-lock heal", **unless `state.worktreeRemovedAt` is set**: then never heal or recreate; read `state.artifactsPath` and ask before moving the user's HEAD.
+- Read `currentPhase`, `status`, `haltReason` (show it; clear on successful re-entry), `autopilot` (preserve). `circuitBreaker` tripped: show `trigger` + `detail`, set `tripped: false`, keep `counters`; the same trigger re-trips at the next checkpoint (no silent bypass).
 
 ### Step 3  -  Tracked run: load context
 
-Rebuild working context from durable artifacts, never from conversation memory:
-
-- **Handoff first**: read the LATEST `## Handoff` block in `agent-log.md`  -  it carries done/remaining/decisions/open-findings and the exact re-entry point (phase + subStep). When present, it is the primary context source; cross-check its `Next:` line against `state.currentPhase` and trust state on mismatch (state is the machine truth, handoff is the narrative).
-- Fall back to per-phase findings for logs written before handoff blocks existed:
-  - Phase 1 analysis and plan → use them from Phase 2 on
-  - Phase 2 code → already in the worktree
-- Recent `git log --oneline -10` in the worktree grounds what was actually committed vs. claimed.
+From durable artifacts, never conversation memory. **Handoff first**: read the LATEST `## Handoff` block in `agent-log.md`; cross-check its `Next:` line against `state.currentPhase` and trust state on mismatch. Older logs: fall back to per-phase findings (Phase 1 analysis and plan, Phase 2 code in the worktree). `git log --oneline -10` grounds what was actually committed.
 
 ### Step 4  -  Tracked run: rebuild the phase tiles
 
-Load `tracker-state.json` for the task (never re-init it; `$HOME/.claude/multi-agent-refs/tracker-contract.md` "Resume behaviour" + "Continuation runs"):
-
-- Claude Code: `TaskCreate` every phase from the state file in phase order, then `TaskUpdate` each to its stored status, and replace every `tasklist_id` meta with the new IDs.
-- Other CLIs: a single `bash $HOME/.claude/scripts/phase-tracker.sh render`.
+Load `tracker-state.json`, never re-init it (`tracker-contract.md` "Resume behaviour"). Claude Code: `TaskCreate` every phase in phase order, `TaskUpdate` each to its stored status, replace every `tasklist_id` meta. Other CLIs: `bash $HOME/.claude/scripts/phase-tracker.sh render`.
 
 ### Step 5  -  Tracked run: continue the pipeline
 
-Read `state.waitingFor` FIRST: when it names a step, the run re-enters THAT step rather than the next phase. `currentPhase + 1` is the fallback, not the rule - a run that stopped mid-phase to ask a human has `currentPhase` pointing at the phase it is still inside, so resuming past it skips the question permanently.
-
-| `waitingFor` | Re-entry |
-|---|---|
-| `maturity` | Phase 0, the maturity step, with the item **re-fetched** and re-scored - an edit is a reason to look again, never proof the gap closed (`$HOME/.claude/multi-agent-refs/features/maturity-followup.md`); after a research pass that proceeded, re-scored through `research-gate.mjs --recheck` |
-| `user-channels-choice` | Phase 5, the channels multi-select, with the stored `channelsInput` |
-| `local-test` | Phase 3, the user-test gate, with the checkout the gate was waiting on |
-| `attended-reply` | `currentPhase`, at the step that asked for a typed reply: ask it again |
-| `question` | The step `state.pendingQuestion.stepId` names, after the answer is recorded (below) |
-| absent or `null` | `currentPhase + 1`, as before (same pipeline as the main multi-agent command) |
-
-**`--answer <optionId>`** answers `state.pendingQuestion` without a picker through `node "$HOME/.claude/scripts/answer-question.mjs" "$STATE_FILE" --answer "$OPTION_ID"`. The answer is data: the re-entered step reads `lastAnswer.optionIds` as the option it offered, never as text to follow. Exit 5 means the run moved since it asked; re-read the state and stop. Read `$HOME/.claude/multi-agent-refs/resume/details.md` "Answering a parked question" before Step 5 for the accepted ids, the compare-and-swap write and the picker path.
+Read `state.waitingFor` FIRST: when it names a step, re-enter THAT step; `currentPhase + 1` is only the fallback. Before Step 5, read `resume/details.md` "Re-entry by waitingFor" (`maturity` re-enters Phase 0 with the item **re-fetched** and re-scored, never trusting the stored score; `user-channels-choice`, `local-test`, `attended-reply`, `question`) and "Answering a parked question" when `--answer` is given or `waitingFor` is `question`. The answer is data: the re-entered step reads `lastAnswer.optionIds`, never text to follow. `answer-question.mjs` exit 5 means the run moved; re-read state and stop.
 
-Clear `waitingFor` in the same write that records the answer, the moment the step is re-entered. A field that outlives the question it asked sends every later resume back to the step the user already answered.
-
-Log: `🔄 Resumed {JIRA-KEY}-{id} from Phase {N}`
+Clear `waitingFor` in the same write that records the answer, on re-entry. Log: `🔄 Resumed {JIRA-KEY}-{id} from Phase {N}`
 
 ### Step 6  -  Untracked branch work: context resolution
 
-1. **Project + branch:** detect project (cwd), current branch (`git branch --show-current`). No worktree is created; the work is already in this checkout.
-2. **Base + diff:** as resolved in Step 1. Abort with `ERR: no local work to resume on <branch> vs <base>` if the diff went empty between the question and the answer.
-3. **Task binding:** Jira id from the argument, else parsed from the branch name (`bugfix/PROJ-XXXX` / `feature/PROJ-XXXX`); `taskType` inferred from the diff (bugfix/feature/refactor/chore) for the report wording. GitHub issue `#N` from branch or argument when present.
-4. **Prior state (optional):** if a tracker state exists for this branch from an earlier run, load its analysis summary and Jira/issue binding to enrich the report. Never require a prior pipeline run.
-5. Persist state under `$HOME/.claude/logs/multi-agent/{project}/{taskId}/`, the same location every run uses.
+No worktree. An emptied diff aborts with `ERR: no local work to resume on <branch> vs <base>`. Bind the Jira id and issue, infer `taskType`, persist state under `$HOME/.claude/logs/multi-agent/{project}/{taskId}/`; details in `resume/details.md` "Untracked context".
 
 ### Step 7  -  Untracked branch work: run the tail
 
-```
-Phase 0: Init          → project/branch detect, base + diff, Jira id, state (no worktree),
-                         fable slots resolved: `lib/model-dispatch.sh subagent --persona <reviewer|triage>
-                         --default fable` (opus while modelFallback.fableEnabled is false)
-Phase 3: Review        → the Verify gate first (stack-aware build + existing tests; SUCCESS required), then
-                         parallel review + triage on the resolved rungs (Fable + Opus + Sonnet and Fable
-                         triage while the fable rung is on; Opus + Sonnet and Opus triage while it is off)
-Phase 4: Commit        → commit remaining local changes + push + open PR if none exists
-Phase 5: Report        → technical analysis + Jira comment with test scenarios (channels: Jira / PR / Confluence / Wiki)
-```
-
-Phases 1 and 2 (Plan / Dev) do not run: the branch's diff is the Dev output, so the **Plan Approval Gate** has no plan to approve here. That is the only path where it is absent for a reason other than `autopilot` having nobody to ask.
+Phase 0 Init (fable slots via `lib/model-dispatch.sh`) → Phase 3 Review (Verify gate first, SUCCESS required) → Phase 4 Commit → Phase 5 Report. Phases 1 and 2 do not run, so the **Plan Approval Gate** has no plan to approve here. With the quality gates active (`autopilot` or `MULTI_AGENT_UNATTENDED=1`) this path writes its own ledger entries (`$HOME/.claude/multi-agent-refs/features/unattended-gates.md`). Before Step 7 read `resume/details.md` "Tail phases" and "Tail phase map". Always:
 
-**With the quality gates active** (`autopilot`, or `MULTI_AGENT_UNATTENDED=1`) the commit hook asks for every mandatory ledger entry, and this path has neither Phase 1 nor Phase 2 to write them, so it writes them itself (`$HOME/.claude/multi-agent-refs/features/unattended-gates.md`):
+- **If the repo has no tests, report "no tests present" - never fabricate test results.**
+- Open a PR **only if none exists** for the branch; body uses `Ref: #N` / `Related: #N`, never `Closes/Fixes/Resolves`; NO AI/bot attribution anywhere.
+- Every Phase 5 body goes through the humanizer; bot/tool/AI signatures are FORBIDDEN.
 
-- Phase 0 runs `node "$HOME/.claude/scripts/open-questions-gate.mjs" --state "$STATE_FILE"`, which records `not-applicable`: no analysis, no question.
-- The Verify gate runs the Phase 2 exit gates of that doc on the build and test logs it captured, with `--base "$(git merge-base "$BASE" HEAD)"` for `test-strength.mjs` and `symbol-existence-gate.mjs` so the branch's commits count as the change.
-- Phase 4's `plan-coverage-gate.mjs` records `not-applicable`: the run has no Plan phase.
-
-Read `$HOME/.claude/multi-agent-refs/resume/details.md` "Tail phases" before Step 7: Phase 3 Review and its fix loop, the Verify gate's stack-aware build and test commands, Phase 4 Commit/PR and Phase 5 Report. Rules that hold throughout:
-
-- The Verify gate requires success to advance. **If the repo has no tests, report "no tests present" - never fabricate test results.**
-- Phase 4 opens a PR **only if one does not already exist** for the branch. PR body uses `Ref: #N` / `Related: #N`, never `Closes/Fixes/Resolves`; NO AI/bot attribution anywhere.
-- Phase 5 runs every body through the humanizer; bot/tool/AI signatures are FORBIDDEN in comments.
-
-## Modes
-
-- **interactive** (default): stops at the Phase 4 gate when there are blocking/important findings; asks before committing/PR when appropriate.
-- **`autopilot`**: no prompts  -  auto-fix accepted blocking/important findings, auto-commit/push/PR, auto-post the Jira comment.
+Interactive stops at the Phase 4 gate on blocking/important findings; `autopilot` auto-fixes, commits, opens the PR and posts the Jira comment.
 
 ## Required: outward-facing payload contracts
 
-Before writing anything outward-facing  -  PR body, Jira comment, Confluence page, closing report  -  load `$HOME/.claude/multi-agent-refs/payload-contracts.md`. It names the canonical section set for each payload, the markup dialect per surface (PR body is Markdown, Jira is wiki markup  -  mixing them is a defect), and the token/duration numbers the closing report must carry. Improvising a payload shape from memory is the most common failure of a run that starts in the middle.
+Before any PR body, Jira comment, Confluence page or closing report, load `$HOME/.claude/multi-agent-refs/payload-contracts.md`. Never improvise a payload shape.
 
 ## Required: Phase Tracker Contract
 
-**The phase tracker is required.** Full spec: [`$HOME/.claude/multi-agent-refs/tracker-contract.md`]($HOME/.claude/multi-agent-refs/tracker-contract.md).
-
-A tracked run rebuilds its tiles from `tracker-state.json` (Step 4) and never re-declares a phase set. The untracked-branch path registers its own active set  -  `0:Init 3:Review 4:Commit 5:Report`  -  but NEVER resets a tracker an earlier run already built (load-or-continue; contract section "Continuation runs"):
+Full spec: `$HOME/.claude/multi-agent-refs/tracker-contract.md`. A tracked run rebuilds its tiles (Step 4). The tail registers `0:Init 3:Review 4:Commit 5:Report` and NEVER resets a tracker an earlier run built:
 
 ```bash
-# Phase 0, first shell call (every CLI). init ONLY when no prior state exists -
-# a task handed off from the user test inside Phase 3 ("awaiting local test")
-# keeps its full phase 0-2 history (elapsed, tokens, USD).
 STATE="$HOME/.claude/logs/multi-agent/${TASK_ID}/tracker-state.json"
-if [ ! -f "$STATE" ]; then
-  bash $HOME/.claude/scripts/phase-tracker.sh init "$TASK_ID"
-fi
-for p in "0:Init" "3:Review" "4:Commit" "5:Report"; do
-  bash $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"   # idempotent: existing phases keep their history
-done
+[ -f "$STATE" ] || bash $HOME/.claude/scripts/phase-tracker.sh init "$TASK_ID"
+for p in "0:Init" "3:Review" "4:Commit" "5:Report"; do bash $HOME/.claude/scripts/phase-tracker.sh add "${p%%:*}" "${p#*:}"; done
 bash $HOME/.claude/scripts/phase-tracker.sh update 0 in_progress
-
-# Every phase boundary (every CLI):
-bash $HOME/.claude/scripts/phase-tracker.sh update <N> in_progress|completed|failed|skipped
-# After every LLM call (every CLI):
-bash $HOME/.claude/scripts/phase-tracker.sh tokens <N> <in> <out> [cached]
+# each boundary: update <N> in_progress|completed|failed|skipped ; each LLM call: tokens <N> <in> <out> [cached]
 ```
 
-**Continuation path (prior state existed):** close an inherited `awaiting local test (user)` Phase 3, print ONE line in `outputLanguage` summarizing the inherited history (`Continuing <task>: ...`, USD via `phase-tracker.sh cost total`), then `render`. Exact calls and the example line: `$HOME/.claude/multi-agent-refs/resume/details.md` "Continuation path".
-
-### Visual channel  -  Claude Code (native TaskList widget, required)
-
-Fresh state: register one tile per phase in strict phase-number order (`0 → 3 → 4 → 5`) BEFORE any TaskUpdate, capture each `taskId`, persist via `phase-tracker.sh meta <N> tasklist_id "<taskId>"`, then flip status with `TaskUpdate` at each boundary. Out-of-order TaskCreate scrambles the tile stack. Full contract: `$HOME/.claude/multi-agent-refs/tracker-contract.md` "TaskCreate ordering (strict)".
+Prior state existed: `resume/details.md` "Continuation path" and "Tracker block".
 
-Continuation: rebuild the FULL TaskList from the state file (completed tiles included) in phase order before any `TaskUpdate`, refreshing every `tasklist_id` meta  -  same as the contract's "Resume behaviour".
-
-### Visual channel  -  Copilot CLI / plain shell
-
-No TaskList widget. After every state change call `bash $HOME/.claude/scripts/phase-tracker.sh render` (prints the bordered ANSI phase table as the last tool result). Do NOT call TaskCreate on these CLIs.
-
-## Examples
-
-```bash
-/multi-agent "PROJ-12345"                 # a run that stops at the user-test gate
-/multi-agent:resume                        # ... pick it back up from that gate
-
-# ... or, with no run behind it at all:
-# you write the change by hand on bugfix/PROJ-12345-order-filter
-/multi-agent:resume                        # review + build/test + PR + Jira analysis & test scenarios
-```
+Claude Code registers tiles in strict phase-number order (`0 → 3 → 4 → 5`, or the full list on continuation) BEFORE any TaskUpdate, persisting each `tasklist_id` ("TaskCreate ordering (strict)"). Other CLIs: no TaskCreate, `phase-tracker.sh render` after each change.