@mmerterden/multi-agent-pipeline 14.0.0 → 14.1.0

package/CHANGELOG.md

@@ -16,6 +16,91 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [14.1.0] - 2026-07-29
+
+Two things the pipeline was supposed to do and did not: use the skills a project's
+own toolkit says apply, and clean up after itself.
+
+### Added
+
+- **Phase 3 asks the stack toolkit which of its skills govern the task.** Each
+  `ai-<platform>-engineering-toolkit` already ships an `index` skill holding a
+  30-plus row intent-to-skill table, maintained beside the skills it points at.
+  Phase 3 dispatched to that plugin for exactly one case (`taskType == "component"`),
+  so `bugfix` / `feature` / `refactor` / `chore` had no skill dispatch at all:
+  whichever skills the host surfaced by description match were the ones used, and
+  nothing recorded or required any of them. That was the dev-side half of the gap
+  v14.0.0 closed on the review side  -  review asked "was this built to the rules it
+  was supposed to follow" while nobody had chosen any rules.
+
+  The routing table is NOT copied into this repo. A second copy would drift the
+  moment the plugin shipped a skill, and the copy here would be the stale one, so
+  the pipeline asks rather than knows. `smoke-stack-skill-routing.sh` check 5 fails
+  the build if a routing table appears in a shipped file (verified against a planted
+  6-row table). Routed skills land in `telemetry.skillCalls[]` with
+  `routedBy: "<toolkit>:index@<version>"`, so Phase 4 conformance can hold the run to
+  what its own toolkit chose. An absent or disabled toolkit is a recorded no-op, not
+  a halt  -  a backend repo has no toolkit and must still run.
+  Contract: `refs/features/stack-skill-routing.md`.
+
+- **Phase 6 removes a task's worktree once its PR is open** (`worktree-finalize.sh`,
+  gated by `prefs.global.settings.worktreeAutoRemoveOnPr`, default **true**). It
+  salvages `agent-state.json`, `phase-tracker.json`, `triage-output.json`,
+  `.pipeline/`, `.build.log`, `.test.log` and `.review-diff.txt` into the log dir
+  first, because Phase 7's triage-memory ingest, the learnings-ledger distill,
+  `render-work-summary.sh`, `:resume`, `:status` and `:log` all read them  -  and the
+  first three are `[ -f ]`-guarded, so a removal without salvage would have degraded
+  silently rather than failing.
+
+  It keeps the branch and **does not check it out**. `git worktree remove` leaves the
+  branch as an ordinary local branch, so nothing is lost, while a checkout would move
+  the user's HEAD and could collide with their own uncommitted work on another
+  branch. Phase 5 removes-then-checks-out on purpose because it is a test handoff;
+  this is not. Verified end to end: HEAD stays put, the user's uncommitted file
+  survives, the branch is still checkoutable on demand.
+
+  Every destructive path is gated and each skips with a reason rather than failing:
+  real uncommitted changes, an unpushed HEAD, `--local` mode, a cwd inside the tree,
+  an unregistered path. `--force` appears nowhere. Contract:
+  `refs/features/worktree-finalize.md`. New state: `worktreeRemovedAt`,
+  `artifactsPath`.
+
+- Gates: `smoke-stack-skill-routing.sh` (12 checks) and `smoke-worktree-finalize.sh`
+  (28 checks, exercising real git repos rather than grepping the doc).
+
+### Changed
+
+- `render-work-summary.sh` gained a log-dir fallback for state and tracker files.
+  It resolved them only from the worktree, so it exited 2 and the entire Work Summary
+  vanished from the PR body and the Jira comment. Its sibling
+  `render-agent-log-cost.sh` has had that fallback all along.
+- `:resume`, `:status` and `:log` no longer treat a missing worktree as a broken run
+  when `worktreeRemovedAt` is set: state is read from `artifactsPath`, and resume asks
+  before moving the user's HEAD.
+- `gc-worktrees.sh` and `/multi-agent:garbage-collect` both claimed the finishing
+  command owned worktree removal. That is now true rather than aspirational.
+- Token budget 52200 -> 52700, after compressing 414 tokens out of Phase 3 and
+  Phase 6 first, per the discipline recorded in `token-budget.json`.
+
+### Fixed
+
+- **Every finding the test-integrity gate produced was unattributable.** It read
+  `f.file` from the diff-risk report, which declares and emits `path`, so each
+  finding carried `file: undefined` and read "Test file 'undefined' shrinks". That
+  is useless to the developer and rejected by `reviewer-output.schema.json`, which
+  requires `file` with `minLength: 1`  -  on the one gate that deliberately has no
+  opt-out. It stayed invisible because the smoke's own fixtures used `"file"`, the
+  key the bug read: the fixture matched the bug instead of the schema. Fixtures
+  corrected, and a new assertion checks the finding names a real path (verified by
+  reintroducing the bug).
+
+- **The command inventories kept a renamed command alive.** `finish` survived the
+  v14.0.0 rename to `ship` in all three inventory lists, because
+  `smoke-command-inventory.sh` only proved nothing was MISSING and `ship` appears
+  elsewhere in those files' prose. Added check 4b: every name in an inventory must be
+  a command that exists in the tree (verified against a planted `ghostcmd`).
+
+
 ## [14.0.0] - 2026-07-29
 
 The `--dev` family reviews its own work, and review now checks the code against the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "14.0.0",
+  "version": "14.1.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

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

@@ -15,7 +15,7 @@ Show the task's detailed agent-log.md report.
 1. **Parse task ID**  -  extract the `#N` form from the argument.
    - No argument → find the most recent (highest-ID) worktree.
 
-2. **Find the worktree**  -  search the known repos:
+2. **Find the worktree**  -  search the known repos. A task whose worktree was removed after its PR (Phase 6 finalize) is found under `$HOME/.claude/logs/multi-agent/<project>/<task-id>/` instead; the `agent-log.md` was always there, and `artifacts/agent-state.json` holds the state. Look there before reporting "task not found":
    ```bash
    find ~/my-ios-app/.worktrees/ ~/my-figma-app/.worktrees/ ~/my-ui-components/.worktrees/ -name "agent-state.json" -maxdepth 2 2>/dev/null
    ```

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

@@ -19,6 +19,7 @@ Resume a paused or failed task from the last successful phase.
 2. **Read + validate state**  -  parse `agent-state.json`:
    - 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 6 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 7 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

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

@@ -14,7 +14,7 @@ Show every active and completed task as a table.
    - `~/my-figma-app/.worktrees/`
    - `~/my-ui-components/.worktrees/`
 
-2. **Scan worktrees**  -  read `agent-state.json` in each worktree dir:
+2. **Scan worktrees**  -  read `agent-state.json` in each worktree dir. **Also scan the log dir**, because a task whose PR is open has no worktree any more (Phase 6 removes it and salvages its state): `find $HOME/.claude/logs/multi-agent -maxdepth 4 -name agent-state.json -path '*/artifacts/*'`. (`-maxdepth 4`, not 3: Phase 6 always passes `--project`, so the salvaged copy lands at `<project>/<task-id>/artifacts/agent-state.json`, which a depth-3 scan can never reach.) Merge both sets by `taskId`, preferring the worktree copy when both exist, and render a finalized task with its `worktreeRemovedAt` rather than omitting it  -  a task that shipped should not vanish from status.
    ```bash
    find {repo}/.worktrees/ -name "agent-state.json" -maxdepth 2
    ```

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

@@ -490,10 +490,10 @@ same 43 specs as reference files rather than as peer skills, via Step 2b -  see
 
 ```
 analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, design-check, dev,
-dev-autopilot, dev-local, dev-local-autopilot, diff-explain, finish, forget, garbage-collect,
+dev-autopilot, dev-local, dev-local-autopilot, diff-explain, forget, garbage-collect,
 help, ios-coding-standard, issue, jira, kill, language, local,
 local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
-routines, save, scan, search, setup, stack, status, sync, test, testflight-validation, uninstall, update
+routines, save, scan, search, setup, ship, stack, status, sync, test, testflight-validation, uninstall, update
 ```
 
 **NOT synced**: `$HOME/.claude/multi-agent-refs/*`  -  lazy-load references, Claude Code specific

package/pipeline/multi-agent-refs/features/stack-skill-routing.md

@@ -0,0 +1,72 @@
+# Stack skill routing  -  letting the toolkit plugin choose its own skills
+
+> **TLDR**  -  When a stack toolkit plugin is enabled, Phase 3 asks that plugin's own `index` skill which of its skills apply to this task, loads them before writing code, and records each into `state.telemetry.skillCalls[]`. The routing table lives in the plugin; the pipeline copies none of it.
+
+## Why this exists
+
+Phase 3 dispatched to the toolkit plugin for exactly one case, `taskType === "component"` (see `component-dispatch.md`). Every other task  -  `bugfix`, `feature`, `refactor`, `chore`  -  had no skill dispatch at all: whichever skills the host happened to surface by description match were the ones that got used, and nothing recorded or required any of them.
+
+That is the dev-side half of the gap `features/skill-conformance.md` closes on the review side. Review now asks "was this built to the rules it was supposed to follow"; without this step, the answer for a non-component task was "there were no declared rules, because nobody chose any".
+
+The fix is not a routing table in the pipeline. Each `ai-<platform>-engineering-toolkit` already ships one: an `index` skill whose description says *"Load this first when unsure which skill applies"*, holding a 30-plus row intent-to-skill map maintained alongside the skills it points at. A second copy in this repo would drift the moment the plugin shipped a new skill, and the pipeline's copy would be the stale one.
+
+So the pipeline's job is to **ask**, not to know.
+
+## When it runs
+
+Phase 3 pre-flight, before any code is written, for **every** `taskType`. Component tasks keep their dedicated dispatch in `component-dispatch.md`; this step runs in addition, because the reference skills (architecture, naming, file placement, tokens) apply to a component build too.
+
+## Resolution
+
+Platform comes from the same mapping component dispatch uses, so the two cannot disagree:
+
+| `state.platform` / detected stack | Toolkit |
+|---|---|
+| ios, swift | `ai-ios-engineering-toolkit` |
+| android, kotlin | `ai-android-engineering-toolkit` |
+| anything else | no toolkit  -  step is a recorded no-op |
+
+The toolkit is enabled per repo (`.claude/settings.local.json` / `~/.claude/settings.json` `enabledPlugins`). **Not enabled is not an error here**, unlike component dispatch: a backend or web repo legitimately has no toolkit, and halting would make the pipeline unusable outside mobile. Record the no-op and continue.
+
+Two marketplaces may ship the same toolkit name (a public one and a corporate one). Resolve whichever is enabled and record its **name and version** in the ledger entry, because the routing table and the skill set differ between versions  -  a finding that cites a skill has to be traceable to the version that defined it.
+
+## The call
+
+```text
+Skill(<toolkit>:index, args: "<task title + one-line intent>")
+```
+
+The index returns which `reference/` and `workflow/` skills apply. Load each via the Skill tool before writing code. A typical task pulls one workflow skill plus one or more reference skills.
+
+Emit one progress line per loaded skill per `progress-contract.md`, so the user can see which standards the run bound itself to rather than inferring it afterwards.
+
+## Recording  -  what makes this checkable
+
+Append one `state.telemetry.skillCalls[]` entry per skill actually loaded:
+
+```json
+{"skill": "ai-ios-engineering-toolkit:reference/architecture", "phase": 3,
+ "targetFiles": ["Domains/Checkin/Sources/CheckinScene.swift"],
+ "routedBy": "ai-ios-engineering-toolkit:index@0.13.0", "timestamp": "<ISO-8601>"}
+```
+
+`routedBy` names the index and version that chose it. That is the difference between "the model happened to read a skill" and "the toolkit said this skill governs this task".
+
+What Phase 4 actually does with it, precisely: Step 1.78 lists these entries in the manifest under `ledger.routedByToolkit`, so a reviewer and the Phase 7 report can see which skills the project's own toolkit selected. It does **not** give them extra weight in the coverage maths. The deterministic resolver stays primary because an unrecorded load and no load are indistinguishable in state, and no `routedBy` tag changes that  -  the tag says who chose the skill, not that the code honoured it.
+
+## Failure modes, and why none of them halt
+
+| Situation | Behaviour |
+|---|---|
+| No toolkit for this stack | recorded no-op, continue |
+| Toolkit not enabled in this repo | recorded no-op, continue (component dispatch still halts for its own case) |
+| `index` resolves but routes to a skill that does not exist in this version | record the miss with the version, load the rest, continue. A stale row in a plugin's table must not stop a run |
+| `index` itself does not resolve | record and fall back to the host's own description matching, which is the pre-v14.1.0 behaviour  -  no worse than before |
+
+Nothing here blocks Phase 3. What is downstream is visibility, not enforcement: routed skills appear in the manifest's `ledger.routedByToolkit`, and a task that recorded nothing shows up as `ledgerSource: derived` with its coverage gap stated. Enforcement over rule IDs is the registry's job (`features/skill-conformance.md`), not this step's.
+
+## What this deliberately does NOT do
+
+- It does not decide which skills apply. Copying the plugin's routing into this repo would put the authoritative table in the wrong place and guarantee drift.
+- It does not fail a run for a missing skill. The pipeline's contract is to ask and record, not to require that a third-party plugin be complete.
+- It does not replace `component-dispatch.md`. That path owns the component build itself, including the `figma-validate` pre-check and the halt-on-incomplete-state rule.

package/pipeline/multi-agent-refs/features/worktree-finalize.md

@@ -0,0 +1,66 @@
+# Worktree finalize  -  removing a task's worktree once its PR is open
+
+> **TLDR**  -  Phase 6 step 9. Once the PR exists the worktree is dead weight, so it is removed: artefacts are salvaged into the log dir first, the branch is kept and deliberately NOT checked out, and every destructive path is gated. Gated by `prefs.global.settings.worktreeAutoRemoveOnPr` (default **true**). Script: `worktree-finalize.sh`.
+
+## Why it exists
+
+A finished task's worktree is a full second checkout that nobody needs after the PR is open, and removing it is the step people forget. `.worktrees/` then accumulates copies of the repo until `/multi-agent:kill` or `:garbage-collect` is run by hand.
+
+Removing it at PR-open is only safe because of the salvage, so the two are one step and not two.
+
+## What it will not do
+
+**No `git checkout` of the task branch.** `git worktree remove` leaves the branch as an ordinary local branch: the ref, its commits, and the ability to `git checkout <branch>` later all survive untouched. Checking it out here would move the user's HEAD out from under them and can collide with their own uncommitted work on another branch. Phase 5 removes-then-checks-out on purpose, because it is handing the branch over for manual testing; this step is not.
+
+**No `git branch -D`.** The branch is the deliverable.
+
+**No `--force`, ever.** `git worktree remove` refusing is a safety feature. The clean-tree check runs before it, so a refusal at that point means something unexpected (a lock, a submodule, permissions) and forcing past unexpected dirt is how work gets lost.
+
+## Preconditions  -  each one skips with a reason, none is an error
+
+| Condition | Why it blocks |
+|---|---|
+| `worktreePath == projectRoot` (`--local` mode) | there is no worktree; removing it would delete the user's checkout |
+| cwd is inside the worktree | a shell left on a deleted inode is worse than a leftover directory, and Phase 6 legitimately `cd`s into the worktree earlier |
+| not a registered worktree of the project root | a mistyped path must not delete an unrelated directory |
+| real uncommitted changes | never discarded; see the artefact carve-out below |
+| HEAD not on the remote | removing a worktree whose commits exist nowhere else is data loss, not cleanup |
+
+Exit codes: `0` removed, `3` skipped with a reason (report and continue to Phase 7), `1` usage error.
+
+### The artefact carve-out, and why `--untracked-files=no` is wrong
+
+The pipeline's own artefacts live inside the worktree and are untracked, so a raw `git status --porcelain` is never empty at PR-open. Left unhandled the removal would never fire and the feature would look implemented while doing nothing.
+
+So exactly these paths are forgiven, and nothing else:
+
+```
+agent-state.json  phase-tracker.json  triage-output.json
+.review-diff.txt  .build.log  .test.log  .pipeline/
+```
+
+Suppressing all untracked files instead (`--untracked-files=no`) would have been shorter and wrong: a source file the developer created but never `git add`ed is invisible to it, and that file would be destroyed silently.
+
+## Salvage
+
+Copied into `$HOME/.claude/logs/multi-agent/<project>/<task-id>/artifacts/` before removal, each only if present  -  a task that never reached Phase 4 has no triage output and that is not an error.
+
+This is why the removal is safe:
+
+| Consumer | Reads | Without salvage |
+|---|---|---|
+| Phase 7 triage-memory ingest | `triage-output.json` | `[ -f ]`-guarded, so it degrades **silently**: the triage corpus and learnings ledger stop being fed and no error appears |
+| Phase 7 learnings-ledger distill | same file | same silent degradation |
+| `render-work-summary.sh` | `agent-state.json`, `phase-tracker.json` | exits 2, so the Work Summary vanishes from the PR body and the Jira comment |
+| `:resume` | `agent-state.json` | cannot continue a Phase 7 pause |
+| `:status`, `:log` | `agent-state.json` | the task becomes invisible |
+
+`state.worktreeRemovedAt` and `state.artifactsPath` record the outcome. The timestamp is what tells a reader that a worktree-less task was finished-and-tidied rather than killed  -  without it, a missing worktree is indistinguishable from a broken run.
+
+## Multi-repo
+
+Run serially per repo, and only **after** `update_sibling_links`: that function issues an update per PR and the loop `cd`s per repo, so removing repo 1's worktree mid-loop breaks repos 2..N.
+
+## Interaction with the existing removal sites
+
+`gc-worktrees.sh` and `/multi-agent:garbage-collect` never touch a registered, healthy worktree  -  they sweep orphans. Both name this step as the owner of finishing-a-task removal, which is now true rather than aspirational.

package/pipeline/multi-agent-refs/phases/phase-3-dev.md

@@ -8,7 +8,7 @@ Per Locked decision 30, Phase 3 Dev consumes the analysis document as the sole d
 
 Pre-flight steps (run in order, abort on failure).
 
-**Steps 1, 2, 3, 5 and 6 apply only when Phase 1 ran.** In the `--dev` family (`state.onlyDevelop === true`) there is no analysis document by design, so those steps are recorded as `not-applicable (no Phase 1 in this mode)` and skipped  -  an unconditional abort here would make every fast mode impossible, which is the contradiction the modes have always carried in practice. Steps 4, 7 and 8 apply in every mode.
+**Steps 1, 2, 3, 5 and 6 apply only when Phase 1 ran.** In the `--dev` family (`state.onlyDevelop === true`) there is no analysis doc by design, so they are recorded `not-applicable (no Phase 1 in this mode)` and skipped  -  an unconditional abort there would make every fast mode impossible. Steps 4, 7, 8 and 9 apply in every mode.
 
 1. **Analysis document presence** (Phase 1 modes only): locate `analysis/<feature-slug>-<platform>.md` for the active platform.
    - Path resolution: `state.run.repoPath` + `/analysis/<feature>-<platform>.md`
@@ -28,7 +28,7 @@ Pre-flight steps (run in order, abort on failure).
 
 6. **Conventions handoff**: read `analysis Section 13.1 Concept Table` (Pass B output with footnotes). Persist concept-to-realization mapping into `state.dev.conventions[<concept>]`. Phase 3 implementation uses these names verbatim (e.g., if Section 13.1 says "State holder: PassengerFlightViewModel", Phase 3 names the class exactly `PassengerFlightViewModel`).
 
-7. **MCP forbidden**: any attempt to call `mcp__claude_ai_Figma__*` in Phase 3 is a violation. The smoke gate `smoke-no-mcp-in-dev-phases.sh` (see CHANGELOG [9.0.0]) checks `state.telemetry.mcpCalls[]` after run and fails if Phase 3 contributed any entry.
+7. **MCP forbidden**: calling `mcp__claude_ai_Figma__*` in Phase 3 is a violation. `smoke-no-mcp-in-dev-phases.sh` reads `state.telemetry.mcpCalls[]` after the run and fails if Phase 3 contributed an entry.
 
 8. **Criteria ledger (required, every mode)**: the moment this phase consults a skill, a marketplace plugin skill, a stack guide or a module `CLAUDE.md` in order to write code, append an entry to `state.telemetry.skillCalls[]`:
 
@@ -36,9 +36,9 @@ Pre-flight steps (run in order, abort on failure).
    {"skill": "ios-coding-standard", "phase": 3, "targetFiles": ["Sources/Login/LoginViewModel.swift"], "timestamp": "<ISO-8601>"}
    ```
 
-   `targetFiles` is required: a skill applied to the wrong files still reads as "applied" without it, so coverage could not be attributed. Append at the moment of consultation, not retrospectively at the end of the phase.
+   `targetFiles` is required  -  without it a skill applied to the wrong files still reads as "applied". Append at the moment of consultation, not at the end of the phase. Phase 4 Step 1.78 treats this as self-report only and resolves criteria independently; it is the one signal separating "applied to the wrong files" from "never opened".
 
-   This is a **self-report**, and Phase 4 treats it as such. Step 1.78 resolves the criteria independently and defaults `ledger.source` to `derived`; a skill named here that the resolver cannot bind to a changed file is flagged rather than believed. The record still earns its keep, because it is the only signal that separates "this skill was applied to the wrong files" from "this skill was never opened"  -  and because a phase that has to name what it followed tends to follow something.
+9. **Stack skill routing (every `taskType`, when a stack toolkit plugin is enabled)**: ask the enabled `ai-<platform>-engineering-toolkit`'s own `index` skill which skills govern this task, load them BEFORE writing code, and record each into `state.telemetry.skillCalls[]` with `routedBy: "<toolkit>:index@<version>"`. The routing table stays in the plugin  -  a copy here would be the stale one. No toolkit, or none enabled, is a recorded no-op, not a halt. Contract: [`features/stack-skill-routing.md`]($HOME/.claude/multi-agent-refs/features/stack-skill-routing.md).
 
 The analysis document is the SOLE design source in Phase 3. Variant choices, padding values, color tokens, copy strings, accessibility identifiers, and test method names all come from the rendered Pass B cells. If something is missing in the analysis doc, the fix is to re-run `/multi-agent:analysis`, not to fetch from Figma.
 

package/pipeline/multi-agent-refs/phases/phase-6-commit.md

@@ -89,9 +89,20 @@ Branch **deterministically**, no implicit fallback. Read `agent-state.json` and
    - In mixed mode (some local, some remote), only prompt for the remote-backed repos; local ones auto-skip.
    - No -> Phase 7
    - Yes -> Create PR with technical description (see below)
-9. **Issue body update** (GitHub Issue only): if the issue body has a `### Pull Requests` section and/or a `### Progress` table, fill in the PR URL(s) (one row per submodule  -  e.g. `- **common:** {url}`, `- **uicomponents:** {url}`) and flip the Implementation / Testing / Code Connect flags from Pending to Done using whatever marker the template uses (match in place, do NOT introduce new markers). Apply with `gh issue edit {issueNo} --body "{updated body}"` and preserve every other section unchanged.
-10. **NEVER close or resolve the issue**  -  neither GitHub Issue nor Jira. Issues require team review (4 approvals) before closing. Only post a comment with commit/PR URLs.
-11. Log: "Phase 6: Commit {sha}  -  PR #{number}"
+9. **Worktree finalize (gated by `settings.worktreeAutoRemoveOnPr`, default true)**: run **from the project root**  -  step 3 leaves the shell inside the worktree and the script refuses there.
+
+   ```bash
+   cd "$PROJECT_ROOT"
+   FIN=$(bash $HOME/.claude/scripts/worktree-finalize.sh --json \
+     --worktree "$WT_PATH" --project-root "$PROJECT_ROOT" \
+     --task-id "$TASK_ID" --project "$PROJECT" --branch "$BRANCH")
+   ```
+
+   The script salvages before removing, keeps the branch, and does **not** check it out  -  the user's HEAD and uncommitted work stay put. On success it stamps `worktreeRemovedAt`, `artifactsPath` and `worktreePath: null` into the **salvaged** `agent-state.json` itself. Do NOT write those via `write-state.mjs "$STATE_FILE"`: in single-repo mode that path went away with the worktree, so the write fails, the fields land nowhere, and Phase 7 reads a dead path and silently skips the triage ingest. After a removal re-point `STATE_FILE` at `$(jq -r .artifactsPath <<< "$FIN")/agent-state.json`. Exit 3 is a safe skip (uncommitted changes, unpushed or detached HEAD, `--local`, cwd inside the tree, preference off): report and continue. Never `--force`. Contract: [`features/worktree-finalize.md`]($HOME/.claude/multi-agent-refs/features/worktree-finalize.md).
+
+10. **Issue body update** (GitHub Issue only): if the issue body has a `### Pull Requests` section and/or a `### Progress` table, fill in the PR URL(s) (one row per submodule  -  e.g. `- **common:** {url}`, `- **uicomponents:** {url}`) and flip the Implementation / Testing / Code Connect flags from Pending to Done using whatever marker the template uses (match in place, do NOT introduce new markers). Apply with `gh issue edit {issueNo} --body "{updated body}"` and preserve every other section unchanged.
+11. **NEVER close or resolve the issue**  -  neither GitHub Issue nor Jira. Issues require team review (4 approvals) before closing. Only post a comment with commit/PR URLs.
+12. Log: "Phase 6: Commit {sha}  -  PR #{number}, worktree {removed|kept: <reason>}"
 
 #### Step 3  -  PR Description (technical detail for reviewers)
 
@@ -294,11 +305,13 @@ done
 update_sibling_links "${PR_URLS[@]}"
 ```
 
+**Then finalize each repo's worktree**, serially and only now  -  `update_sibling_links` updates one PR per repo and the loop `cd`s per repo, so removing repo 1's worktree mid-loop breaks 2..N. Run `worktree-finalize.sh` once per repo with that repo's `--worktree` / `--project-root` / `--project`; each skips or removes independently.
+
 `update_sibling_links` does an UPDATE call per PR (Bitbucket: PUT with `version+1`; GitHub: `gh pr edit --body-file`). Idempotent: re-running with the same set is a no-op.
 
 ##### GitHub issue body  -  list all PRs
 
-Step 9's "Issue body update" extends to multi-repo: instead of a single `### Pull Requests` line, write one row per repo:
+Step 10's "Issue body update" extends to multi-repo: instead of a single `### Pull Requests` line, write one row per repo:
 
 ```
 ### Pull Requests

package/pipeline/multi-agent-refs/phases/phase-7-report.md

@@ -212,7 +212,10 @@ This is independent of the channels-side `reportContent.costSummary` (which gate
 **Triage memory ingest (mandatory):** after Phase 4 produces a final triage output, persist the accepted/deferred/rejected rows into the per-repo triage corpus so Phase 1 enrichment and Phase 4 prior-art lookup can recall them on future tasks. Idempotent  -  re-running on the same task writes 0 rows.
 
 ```bash
-TRIAGE_PATH="$WORKTREE/triage-output.json"
+# Salvaged copy first: Phase 6 removes the worktree once the PR is open, and this
+# reader is `[ -f ]`-guarded, so a wrong path degrades SILENTLY.
+TRIAGE_PATH="$(jq -r '.artifactsPath // empty' "$STATE_FILE" 2>/dev/null)/triage-output.json"
+[ -f "$TRIAGE_PATH" ] || TRIAGE_PATH="$WORKTREE/triage-output.json"
 if [ -f "$TRIAGE_PATH" ]; then
   node $HOME/.claude/scripts/triage-memory.mjs ingest \
     --triage "$TRIAGE_PATH" \

package/pipeline/preferences-template.json

@@ -29,7 +29,8 @@
       "repoScanDays": 90,
       "identityRoutingEnabled": false,
       "multiRepoEnabled": false,
-      "pushMustSucceed": true
+      "pushMustSucceed": true,
+      "worktreeAutoRemoveOnPr": true
     },
     "defaultJiraKey": null,
     "reportChannels": {

package/pipeline/schemas/agent-state.schema.json

@@ -162,6 +162,10 @@
               "timestamp": {
                 "type": "string",
                 "description": "ISO-8601 time of the consultation."
+              },
+              "routedBy": {
+                "type": "string",
+                "description": "Set when a stack toolkit's own index skill chose this skill, as '<toolkit>:index@<version>'. Recorded so a finding can be traced to the index version that selected it  -  the skill set differs between plugin versions. Phase 4 Step 1.78 surfaces these separately in the manifest ledger; it does NOT grant them extra trust, because the resolver stays primary either way."
               }
             }
           }
@@ -685,6 +689,15 @@
           }
         }
       }
+    },
+    "worktreeRemovedAt": {
+      "type": ["string", "null"],
+      "format": "date-time",
+      "description": "Set when Phase 6 removed the worktree after opening the PR. Its presence is what tells :resume, :status and :log that a worktree-less task is finished-and-tidied rather than broken  -  without it a missing worktree is indistinguishable from a killed run."
+    },
+    "artifactsPath": {
+      "type": ["string", "null"],
+      "description": "Directory the worktree's artefacts were salvaged into before removal (agent-state, phase-tracker, triage-output, .pipeline/, build+test logs, review diff). Phase 7 and :resume read from here when worktreePath is gone."
     }
   }
 }