@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/multi-agent-refs/features/url-enrichment.md

@@ -96,9 +96,9 @@ The extractor emits `graylog` entries from free-text trx / conversation ids (lab
 
 A feature spec arrives as a Word file at least as often as a Confluence page, and until v15.20.0 nothing in the pipeline could read one. `~/.claude/lib/fetch-document.sh <path-or-url>` extracts the text and returns the fetcher-standard JSON.
 
-- `.docx` needs no external tool: the file is a zip and `word/document.xml` is parsed with the python3 standard library, so the same code path runs on macOS, Linux and Windows.
+- `.docx` needs no external tool: the file is a zip and `word/document.xml` is parsed with the python3 standard library.
 - `.md` / `.txt` are read directly. A URL is downloaded first, then treated by extension.
-- `.pdf` has no stdlib path: `pdftotext` is used when present, and its absence is exit `6` with `degraded: true`, `converter-not-available`. That is a soft skip, not an error - on Windows it is the normal case - and the document is cited in Section 21 as "referenced but not fetched".
+- `.pdf` has no stdlib path: `pdftotext` is used when present, and its absence is exit `6` with `degraded: true`, `converter-not-available`. That is a soft skip, not an error, and the document is cited in Section 21 as "referenced but not fetched".
 - Store as `state.documentContext[]`; Phase 1 injects the text under **Referenced External Sources** and Section 21 cites it as `Doküman:<file>:<title>` (Locked 3).
 
 ##### Step 1b.4  -  Other link types (catalogued only at Phase 0; fetched at Phase 1)

package/pipeline/multi-agent-refs/features/usage-reporting.md

@@ -1,29 +1,123 @@
 # Feature: Operational Reporting
 
-**Pattern**: reporting needs two things - `usageLog.enabled` true AND a token
-that resolves - and both were arranged automatically in exactly one place:
-`/multi-agent:update`, as forty lines of shell embedded in the skill. A user who
-installed the package, ran `/multi-agent:setup` and worked for weeks never ran
-update, so they never registered, never reported, and the panel could not tell
-them apart from nobody using the pipeline at all.
-
-Registration is now one call (`$HOME/.claude/scripts/usage-register.mjs`) made
-from the three places a machine can first become real: **setup**, **update**, and
+<!-- toc -->
+- [1. What is sent, and what never is](#1-what-is-sent-and-what-never-is)
+- [2. When it is sent](#2-when-it-is-sent)
+- [3. The reporting identity](#3-the-reporting-identity)
+- [4. The server side](#4-the-server-side)
+- [5. The token](#5-the-token)
+- [6. Opting out, and the two silences](#6-opting-out-and-the-two-silences)
+- [6b. Feedback is not telemetry](#6b-feedback-is-not-telemetry)
+- [7. The half-configured case](#7-the-half-configured-case)
+- [8. Where it is NOT called](#8-where-it-is-not-called)
+<!-- /toc -->
+
+Reporting needs three things: `usageLog.enabled` true, a token that resolves,
+and a logged-in GitHub account that can read the pipeline repository. The token
+is arranged by one call (`$HOME/.claude/scripts/usage-register.mjs`) made from
+the three places a machine can first become real: **setup**, **update**, and
 **the Phase 0 exit gate** of a run on a machine that reached neither. Asserted by
 `smoke-usage-register.sh`.
 
 ## 1. What is sent, and what never is
 
-`usage-report.mjs` emits coarse run metadata: task id, phase, status, durations,
-token counts, the credential-health summary. Never prompts, never code, never
-diffs, never absolute paths. The registration call sends two fields: the
-reporting user and the short hostname.
-
-The reporting user is the **GitHub login** - `identities[0].username`, then
-`gh api user`, then the OS user. Never `identity.name`, which carries a person's
-real name and sometimes a corporate title.
-
-## 2. The token
+`usage-report.mjs` emits coarse run metadata, one record per run, upserted by
+run id. Never prompts, never code, never diffs, never token values, never
+absolute paths, never the repository name (a digest stands in for it). The
+registration call sends two fields: the reporting login and the short hostname.
+
+Each record carries:
+
+| Field | Meaning |
+|-------|---------|
+| `id`, `tt` | task id and task type (`bugfix`, `feature`, ...) |
+| `ev` | the event that sent it: `phase`, `completed`, `halted`, `parked` |
+| `st` | run status: `in_progress`, `completed`, `halted`, `parked`, `failed` |
+| `ph` | current phase, from the tracker (the phase in progress, else the last one reached) |
+| `phs` | every tracker phase with status, duration in seconds and tokens |
+| `rc` / `hr` | reason code: `<phase>:<cause>` for a halt, the waiting step for a park; reduced to `[a-z0-9:_-]` after paths are removed |
+| `pr` | whether a PR was opened |
+| `pru` | the PR URL, only when `usageLog.includePrUrl` is true (it names the repository) |
+| `ti` | a one-line task title, only when `usageLog.includeTitle` is true: at most 80 characters, code spans, markup and absolute paths removed |
+| `m`, `c` | mode and command. `m` is always one of the modes `schemas/phases.json` declares, or `unknown`; `c` is a command that still ships under `commands/multi-agent/`, otherwise the mode. A state written by an older version cannot put a mode name on the panel that the pipeline no longer has |
+| `t`, `t0`, `du` | time of this event, run start, run duration |
+| `tk`, `cost`, `models` | token totals, estimated cost, models used |
+| `os`, `cli`, `lang`, `stack`, `plug`, `apps`, `creds`, `calls`, `errs`, `v` | environment and credential-health summary |
+
+`st` comes from the event when one is given (`--event`), otherwise from the
+state file: `haltReason` or `paused` is halted, `awaiting_input` or a
+`waitingFor` step is parked, `complete` is completed, anything else is in
+progress.
+
+## 2. When it is sent
+
+| Event | Where |
+|-------|-------|
+| `phase` | `phase-tracker.sh init` and every `update` to a status other than `pending`, detached so it never blocks a boundary; plus the Phase 0 exit gate |
+| `completed` | Phase 5, after it writes `status: complete` and `finishedAt` to the state; the analysis render step |
+| `halted` | the halt-visibility step in `phases/operations.md` |
+| `parked` | the park-visibility step in `phases/operations.md`, after a run writes `awaiting_input` or `waitingFor` |
+
+The panel derives a run's status from the last event it received. A run still
+`in_progress` with no event for **6 hours** is shown as abandoned; a parked run
+is waiting on a person and is never shown as abandoned. The threshold is
+`STALE_RUN_MS` on the server side.
+
+## 3. The reporting identity
+
+The login is the GitHub login of the **logged-in account that can read the pipeline
+repository** (`usageLog.accessRepo`, default `mmerterden/multi-agent-pipeline`):
+access to that repository is what grants use of the pipeline, so it also decides
+whose name a run carries. `usage-identity.mjs` checks every github.com account
+`gh auth status` lists, in the order `usageLog.reportAs` (when logged in), the
+active account, then the rest. Each check is `gh api repos/<accessRepo>` with that
+account's token in the child's environment as `GH_TOKEN`: never on argv, never
+logged, never stored. The first account that can read the repository wins.
+
+Never `identity.name`, which carries a person's real name and sometimes a
+corporate title, and never simply the active `gh` account, which on a machine
+with a work account and a personal account is often the one without access.
+
+The answer is cached in prefs (`usageLog.login`, `loginRepo`, `loginCheckedAt`)
+for 7 days, or 1 day when no account had access, so a phase boundary costs no
+network call. Refresh it after changing accounts or being granted access:
+
+```bash
+node "$HOME/.claude/scripts/usage-identity.mjs" --refresh
+```
+
+**No account with access, no report.** The emitter sends nothing and writes one
+line to stderr (`usage-report: not sent - none of the logged-in GitHub accounts
+(...) can read ...`); registration is skipped with the same reason.
+
+## 4. The server side
+
+`/api/usage/register` requires proof that the caller owns the login it names.
+`usage-register.mjs` reads the verified account's token with
+`gh auth token --user <login>` (gh prints it on its own stdout; it is never on
+another process's argv, never logged, never stored) and sends it as
+`Authorization: Bearer <token>`. The body's `u` stays as a hint. The server
+resolves the token to a GitHub login, refuses a mismatch, then checks that login
+with a server-side token (the repository owner, or a collaborator of the
+repository) before it issues a token, and pins the login to that token.
+
+The proof is sent only over https to the default reporting host or a host listed
+in `usageLog.trustedHosts`, or plain http to loopback (`127.0.0.1`, `localhost`,
+`[::1]`) for local development; any other endpoint is refused before the gh
+token is read. Redirects are not followed by either call, so neither the gh
+token nor the ingest token can be carried to another host. A `401`, or a `403`
+for a login mismatch, leaves reporting off with a status line naming the login
+that could not be confirmed (`gh auth status` must list that account); a `403`
+for a login without access says it needs collaborator access; a decline is
+reported as `declined`; gh having no
+token for the login sends nothing. `/api/usage/ingest` reports every record
+under the pinned login and ignores the name the client sent; a pinned login that
+is no longer the owner or a collaborator is dropped. Records from any other
+account are hidden from the panel. `usage-register.mjs` replaces a stored token
+whose `registeredAs` differs from the verified login, or that predates
+verification, because a token reports under the login it was issued for.
+
+## 5. The token
 
 Requested, never shipped. `/register` mints a per-machine **write-only** token:
 append-only to the ingest endpoint, no read access, no other scope. Only its
@@ -32,31 +126,33 @@ credential, and the owner can revoke one row without touching anyone else.
 
 It lands in the OS credential store under `<user>_Usage_Ingest_Token`. Prefs hold
 the NAME of that entry (`keychainMapping.usage_ingest`) and the on-switch, never
-the secret. Resolution order at emit time: `$MULTI_AGENT_USAGE_TOKEN`, then
+the secret. Every prefs write here (the cached login, the entry name, the
+switch) holds the prefs file's lock and replaces the file atomically at mode
+`0600`, the same helper `migrate-prefs.mjs` uses. Resolution order at emit time: `$MULTI_AGENT_USAGE_TOKEN`, then
 `usageLog.token`, then the credential-store entry.
 
-## 3. Opting out, and the two silences
+## 6. Opting out, and the two silences
 
 `usageLog.optOut: true` blocks registration permanently and is checked before
-anything else - before the network call, before the credential store.
+anything else - before the identity check, the network call and any credential
+read (the credential store and `gh auth token`).
 
 The other silence is not a choice: offline, endpoint down, ingest disabled by the
-admin, or a credential store that refuses the write. That leaves reporting off
-with one status line and exit 0. **A caller is never failed over bookkeeping**,
-which is the same rule the capture hooks follow.
+admin, no account with access, or a credential store that refuses the write. That
+leaves reporting off with one status line and exit 0. **A caller is never failed
+over bookkeeping**, which is the same rule the capture hooks follow.
 
 Both are reported distinguishably (`--json` gives `status`: `skipped` with the
-reason, `unavailable` with the cause, `registered`, `enabled`, `dry-run`) because
+reason, `unavailable` with the cause, `declined`, `registered`, `enabled`, `dry-run`) because
 "you turned it off" and "we could not reach the endpoint" are different facts
 about the same empty panel.
 
 `prefs.global.usageLog.endpoint` overrides where both calls go - the register URL
 is derived from it, so a self-hosted ingest gets its own registration rather than
 this one's. Absent means the shipped default, and every shipped default names the
-same host on purpose: a machine that registers against one host and reports to
-another shows up as a token that never sends anything.
+same host, so a machine never registers against one host and reports to another.
 
-## 3b. Feedback is not telemetry
+## 6b. Feedback is not telemetry
 
 `/multi-agent:feedback` rides the same token, and `optOut` does not silence it:
 passive collection is a choice, a message somebody typed to be read is not. So a
@@ -65,14 +161,14 @@ does, it writes the credential-store entry and **leaves `usageLog.enabled` alone
 The opt-out still holds for everything it was about; the person just gets their
 message delivered.
 
-## 4. The half-configured case
+## 7. The half-configured case
 
 A token in the credential store with `enabled: false` produces exactly the same
 silence as no token at all, and it happens whenever a run is interrupted between
 the two writes. The call repairs it: when a token already resolves but the switch
 is off, it turns the switch on and says so rather than reporting "unchanged".
 
-## 5. Where it is NOT called
+## 8. Where it is NOT called
 
 The installer. `install.js` lays down files and nothing else; seeding state is the
 one thing the install contract forbids, and a fresh machine has no preferences

package/pipeline/multi-agent-refs/features/verify-by-test.md

@@ -5,7 +5,7 @@
 **Gated by `prefs.global.verifyByTest.enabled`** (default: `false`). When enabled, after triage 3.6 and before Step 4, IF the validated triage output contains at least one `accepted` blocking finding:
 
 1. Dispatch ONE verifier sub-agent for the iteration (model: `verifyByTest.model`, default `sonnet`)  -  never one dispatch per finding. Input: up to `verifyByTest.maxFindings` (default 3) accepted blocking findings, the diff hunks for their files, and the Phase 1 test conventions.
-2. Per finding, the verifier writes ONE minimal repro test asserting the correct behavior the finding claims is broken, then runs ONLY that test via the Phase 3 single-test invocation (`xcodebuild test -only-testing:`, `pytest {file}::{name}`, the resolved node command from `scripts/package-manager.mjs test` (npm/pnpm/yarn/bun, never assumed), `./gradlew test --tests`) under `acquire_build_lock`/`release_build_lock`. One green run is not trusted: the same single-test invocation runs `verifyByTest.repeatCount` times (default 3; value 1 disables the repeat) as a shell loop, each run's log tee'd to `$WORKTREE/.pipeline/verify-<i>-<k>.test.log` for `k` in `1..repeatCount`. ALL runs must pass, and each log must clear `evidence-gate.mjs --claim test --status passed`, before the outcome counts as "passes". A first run that fails as predicted ends the loop early (`confirmed` needs no repeat).
+2. Per finding, the verifier writes ONE minimal repro test asserting the correct behavior the finding claims is broken, then runs ONLY that test via the Phase 3 single-test invocation (`xcodebuild test -only-testing:`, `pytest {file}::{name}`, the resolved node command from `scripts/package-manager.mjs test` (npm/pnpm/yarn/bun, never assumed), `./gradlew test --tests`) under `build-lock.sh acquire <task-id>` and released with `build-lock.sh release <task-id>` (the same task id, or release refuses). One green run is not trusted: the same single-test invocation runs `verifyByTest.repeatCount` times (default 3; value 1 disables the repeat) as a shell loop, each run's log tee'd to `$WORKTREE/.pipeline/verify-<i>-<k>.test.log` for `k` in `1..repeatCount`. ALL runs must pass, and each log must clear `evidence-gate.mjs --claim test --status passed`, before the outcome counts as "passes". A first run that fails as predicted ends the loop early (`confirmed` needs no repeat).
 3. Stamp each processed finding with a `verification` object (triage-output schema v3.2.0) and re-run `validate-triage.mjs` on the mutated triage file under the standard 3.2.1 gate protocol.
 4. Findings beyond `maxFindings` keep their judgment-only verdict (log `verify_by_test=cap-exceeded`).
 5. The whole step is bounded by `verifyByTest.stepTimeoutSec` (default 600); on breach or verifier crash, remaining findings keep judgment-only verdicts and the pipeline proceeds. Never blocks.

package/pipeline/multi-agent-refs/features/visual-evidence.md

@@ -91,13 +91,13 @@ write their own video), and `npx --no-install` is what keeps a probe from
 installing one behind the user's back.
 
 **An empty value is still a real outcome, not an error.** A backend-only repo has
-nothing to probe, and `probe-evidence-capability.sh` rejects anything but
-`ios|android|web` with exit 2. So when `EVIDENCE_PLATFORM` is empty the probe
-**does not run**, `platform` is written as `other` from `MA_STACKS`, and the
-reason goes to `state.evidenceCapability.skippedReason` in the probe's own
-`*_REASON` idiom - "no device platform in stacks [backend]". Passing an empty
-string instead is what the probe's exit 2 exists to refuse, and swallowing that
-exit would turn a missing value into a silent skip.
+nothing to probe. Phase 0 calls `probe-evidence-capability.sh --platform auto`,
+which reads the stacks with `stack-detect.sh` and takes the first of ios,
+android, web; with none of them nothing is probed, `platform` is written as
+`other`, and the reason goes to `state.evidenceCapability.skippedReason` in the
+probe's own `*_REASON` idiom - "no device platform in stacks [backend]". An
+explicit empty `--platform` is still exit 2: swallowing that exit would turn a
+missing value into a silent skip.
 
 Every `--platform` argument in this pipeline is `$EVIDENCE_PLATFORM`, read from
 `state.visualEvidence.platform` in later phases. `$PLATFORM` is not a pipeline

package/pipeline/multi-agent-refs/keychain.md

@@ -2,7 +2,7 @@
 
 > **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
 
-Tokens live in the platform-native credential store (macOS Keychain / Linux libsecret / Windows Credential Manager). Key names are resolved via **preferences mapping**  -  never hardcoded.
+Tokens live in the macOS Keychain. Key names are resolved via **preferences mapping**  -  never hardcoded.
 
 ### Rule 1  -  Never prompt for a token *value* mid-run
 
@@ -142,7 +142,7 @@ KEY_NAME=$(jq -r '.global.keychainMapping.<service_id> // "<standard_key_name>"'
 TOKEN=$(~/.claude/lib/credential-store.sh get "$KEY_NAME" 2>/dev/null)
 ```
 
-The shell driver auto-delegates to `~/.claude/scripts/keychain.py` on macOS / Linux for deterministic behaviour (writes both `-l` (label) and `-s` (service) attributes; reads tolerate either convention so manually-added personal tokens are findable).
+The shell driver auto-delegates to `~/.claude/scripts/keychain.py` for deterministic behaviour (writes both `-l` (label) and `-s` (service) attributes; reads tolerate either convention so manually-added personal tokens are findable).
 
 **Standard key names (convention for new tokens):**
 
@@ -202,20 +202,15 @@ The shell driver auto-delegates to `~/.claude/scripts/keychain.py` on macOS / Li
 bash "$HOME/.claude/scripts/keychain-save.sh" <service-id>
 ```
 
-## Cross-platform mechanics
+## Credential store mechanics
 
 Moved out of `setup/SKILL.md`: it is reference detail every credential path shares,
 and the setup skill only needs to route to it.
 
-The credential store is platform-agnostic  -  every read/write goes through `~/.claude/lib/credential-store.sh`, which dispatches to the right backend (`security` on macOS, `secret-tool` on Linux, PowerShell `CredentialManager` on Windows). On macOS / Linux the shell driver delegates to `~/.claude/scripts/keychain.py` for deterministic behaviour. You almost never need the platform-native commands directly.
+Every read/write goes through `~/.claude/lib/credential-store.sh`, which wraps the macOS Keychain (`security`) and delegates to `~/.claude/scripts/keychain.py` for deterministic behaviour. The pipeline is macOS only (ADR-0012); on any other host the helper exits 2. You almost never need `security` directly.
 
-Clipboard helpers (`pbpaste`, `pbcopy`) are macOS-specific  -  for Copilot CLI on Linux substitute:
+Token paste uses `pbpaste`, and `pbcopy < /dev/null` clears the clipboard afterwards.
 
-| macOS command | Linux equivalent | Notes |
-|---|---|---|
-| `pbpaste` | `xclip -selection clipboard -o` (X11) or `wl-paste` (Wayland) | Install with `apt install xclip` or `apt install wl-clipboard` |
-| `pbcopy < /dev/null` | `xclip -selection clipboard < /dev/null` or `wl-copy --clear` | Same intent: clear clipboard after token paste |
-
-If you need to bypass the helper (debugging, raw inspection), the underlying platform commands are documented at the top of `$HOME/.claude/lib/credential-store.sh`. Otherwise stay on the helper  -  it keeps secrets off argv (stdin sentinel `-`) and writes both `-l` and `-s` attributes on macOS.
+If you need to bypass the helper (debugging, raw inspection), the underlying commands are documented at the top of `$HOME/.claude/lib/credential-store.sh`. Otherwise stay on the helper  -  it keeps secrets off argv (stdin sentinel `-`) and writes both `-l` and `-s` attributes.
 
 If no backend is available, setup falls back to a plain-text prompt + a warning that the token is **not persisted**  -  pipeline phases will re-ask each session.

package/pipeline/multi-agent-refs/payload-contracts.md

@@ -62,6 +62,6 @@ Non-empty `UNTRACKED` → both the agent-log report and the closing chat summary
 
 `smoke-tracker-tokens-invocation.sh` only lints that the phase docs *mention* `phase-tracker.sh tokens`. It cannot observe a run that read the doc and skipped the call, so this run-time disclosure is the only thing between a dropped `tokens` call and an invisible failure.
 
-## Fast modes are not exempt
+## Autopilot is not exempt
 
-The autopilot and local entries skip the interactive test gate. They run Phase 4 and Phase 5 **unchanged**. A short pipeline is not a licence for an improvised payload shape, a missing Test Scenarios section, or a report without numbers.
+An autopilot run skips the interactive test gate. It runs Phase 4 and Phase 5 **unchanged**. A run nobody is watching is not a licence for an improvised payload shape, a missing Test Scenarios section, or a report without numbers.

package/pipeline/multi-agent-refs/phases/log-format.md

@@ -2,7 +2,7 @@
 
 > **TLDR**  -  Canonical shape of `agent-log.md`: header block (task id, branch, status), Timeline table (phase by phase), Agent Activity Report (calls + duration per agent), ASCII phase-duration distribution, Review Iterations, Files Changed (`git diff --stat`), Review Consensus, Cost Breakdown, and Test Scenarios. Every pipeline run must produce this file at the global log path.
 
-Create at `$HOME/.claude/logs/multi-agent/{project}/{task-id}/agent-log.md`:
+Create at `${LOGS_ROOT:-$HOME/.claude/logs/multi-agent}/{project}/{task-id}/agent-log.md`:
 
 ```markdown
 # {task-id}  -  {Task Title}
@@ -89,8 +89,7 @@ Verdict: unverified (3 reviewers)
 Phase 5 MUST attempt to render the Cost Breakdown section as part of the agent-log compose step:
 
 ```bash
-COST_BLOCK=$(bash $HOME/.claude/scripts/render-agent-log-cost.sh "$TASK_ID" 2>/dev/null) && \
-  printf '%s\n' "$COST_BLOCK" >> "$AGENT_LOG"
+bash $HOME/.claude/scripts/render-agent-log-cost.sh "$TASK_ID" --append "$AGENT_LOG" 2>/dev/null
 ```
 
 Emission is best-effort  -  exit 2 (no data) is silently skipped. Never fail the pipeline on a missing cost block. The renderer reuses `cost-table.json` so any `cost-table` price update flows through to both PR-body and agent-log surfaces.

package/pipeline/multi-agent-refs/phases/modes.md

@@ -66,22 +66,20 @@ Full contract: `$HOME/.claude/multi-agent-refs/phases/phase-5-report.md` (Autopi
 
 ## Analysis Mode (`/multi-agent:analysis`)
 
-A different **output kind**, not a shorter pipeline. It produces the analysis document and stops; no code, no branch, no PR. The 6-phase contract holds, with four phases reinterpreted the same way a Short run reinterprets Phase 2.
+A different **output kind**, not a shorter pipeline. It produces the analysis document and stops; no code, no branch, no PR. The 6-phase contract holds: Phase 2 is skipped and Phases 1, 3 and 4 are reinterpreted.
 
 ```
-Phase 0: Init -> Phase 1: Plan (analysis) -> Phase 1: Plan -> Phase 3: Review -> Phase 4: Publish -> Phase 5: Report
+Phase 0: Init -> Phase 1: Plan (analysis) -> Phase 3: Review -> Phase 4: Publish -> Phase 5: Report
 ```
 
 | Phase | Analysis mode |
 |---|---|
 | 0 Init | Same intake, but **no worktree**: nothing is isolated because nothing is built, so `state.run.repoPath` is the repo itself |
-| 1 Analysis | The engine (`multi-agent-refs/analysis/*`): evidence, synthesis, render, humanizer, `validate-analysis-doc.mjs` |
-| 2 Planning | Synthesis and render finish here; **no task decomposition** - there is no code to plan |
-| 3 Dev | **SKIP** |
-| 4 Review | Document review plus the open questions still marked `Acik / Open` |
-| 5 Test | **SKIP** |
-| 6 Commit | **Publish** instead: Local file / Confluence / Jira. Locked 6 still forbids `git add` and `git commit` |
-| 7 Report | Channels, same as every mode |
+| 1 Plan | The engine (`multi-agent-refs/analysis/*`): evidence, synthesis, render, humanizer, `validate-analysis-doc.mjs`. **No task decomposition** - there is no code to plan |
+| 2 Dev | **SKIP** |
+| 3 Review | Document review plus the open questions still marked `Acik / Open` |
+| 4 Commit | **Publish** instead: Local file / Confluence / Jira. Locked 6 still forbids `git add` and `git commit` |
+| 5 Report | Channels, same as every mode |
 
 **No `autopilot` variant.** Worktree isolation buys nothing when no code is written, and the intake, the Pass B convention preview and the open-question resolution are interactive by nature; a zero-interaction analysis would be a document nobody agreed to.
 
@@ -100,7 +98,7 @@ question carries what the choice costs.
 ```
 Bu is nerede kossun? / Where should this task run?
   1. Worktree       .worktrees/{id}/ - your current checkout stays untouched
-  2. Lokal / Local  the project root, on a new branch - no Phase 3
+  2. Lokal / Local  the project root, on a new branch - no worktree checkout for the user test
 ```
 
 Two genuine options, so it meets the two-option floor in `picker-contract.md` on
@@ -121,7 +119,7 @@ unattended run therefore always gets its own checkout.
 | -------------- | ------------------------------------------------ | -------------------------------------------------------------- |
 | Phase 0 Step 8 | Creates worktree at `.worktrees/{id}/`           | `git checkout -b {branch}` directly in `$PROJECT_ROOT`         |
 | Phase 2        | Works in worktree path                           | Works in `$PROJECT_ROOT`                                       |
-| Phase 3        | WIP commit -> remove worktree -> checkout branch | **Not in the phase set**  -  nothing to check out, nothing to remove |
+| Phase 3        | Review, then the user test: WIP commit -> remove worktree -> checkout branch | Review runs unchanged; the user test skips the checkout offer  -  nothing to check out, nothing to remove |
 | Phase 4        | Commit in worktree, push                         | Commit in project root, push                                   |
 | All paths      | `{worktreePath}` references                      | All paths use `$PROJECT_ROOT` directly                         |
 
@@ -135,7 +133,7 @@ git -C $PROJECT_ROOT config user.name "{identity.name}"
 git -C $PROJECT_ROOT config user.email "{identity.email}"
 ```
 
-**Phase 3 in local mode:** it is not in the phase set. The gate exists to hand the user a change checked out of a worktree, and in local mode the code is already on the branch in `$PROJECT_ROOT` with nothing to check out or remove. `gen-mode-dispatch.mjs --mode=local` is the enforced statement of this; the row above mirrors it.
+**Phase 3 in local mode:** Review runs exactly as in a worktree. Only the user test at the tail of Phase 3 changes: its checkout offer exists to hand the user a change checked out of a worktree, and in local mode the code is already on the branch in `$PROJECT_ROOT`, with nothing to check out or remove, so the offer is skipped. The workspace is a Phase 0 answer, not a mode, so the phase set in `schemas/phases.json` is the same for both.
 
 **State tracking**: `agent-state.json` gets `"localMode": true`, `"worktreePath": null`. All path references resolve to `$PROJECT_ROOT`.
 

package/pipeline/multi-agent-refs/phases/operations.md

@@ -19,7 +19,7 @@
 
 > **Pickers follow** `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option call, and branch on the option selected, not on its text.
 
-Every task gets an auto-incremented short ID. Counter stored at `$HOME/.claude/logs/multi-agent/{project}/.counter` (persists across sessions).
+Every task gets an auto-incremented short ID. Counter stored at `${LOGS_ROOT:-$HOME/.claude/logs/multi-agent}/{project}/.counter` (persists across sessions).
 
 ```
 /multi-agent "PROJ-12345"
@@ -61,7 +61,7 @@ Every task gets an auto-incremented short ID. Counter stored at `$HOME/.claude/l
 
 ## Resume Logic
 
-1. Find state file: `$HOME/.claude/logs/multi-agent/{project}/{task-id}/agent-state.json`
+1. Find state file: `${LOGS_ROOT:-$HOME/.claude/logs/multi-agent}/{project}/{task-id}/agent-state.json`
 2. **Validate before re-entry** (required  -  a half-written or corrupt state silently resumes at the wrong phase):
    - `node $HOME/.claude/scripts/validate-state.mjs <state-file>` (resume-safety check: parseable JSON + `currentPhase` in 0..5 + well-formed `phases`; tolerant of legacy shapes, not a strict schema match). On non-zero exit, do NOT guess a phase: surface the error and stop with `ERR: agent-state.json is unsafe to resume; inspect it or 'kill #N' and restart.`
    - Confirm the worktree path on `state.worktreePath` / `state.projects[].worktreePath` exists and `git -C <wt> status` is clean-or-known. If the worktree is missing or locked, run the Phase 0 "Worktree stale-lock heal" before continuing.
@@ -143,7 +143,13 @@ that) is the last-resort ceiling for a PID that has been recycled.
 **Halt visibility (required, autopilot included).** A halt is never silent. Whenever a phase halts on a hard error (validator failed twice, no subagent returned, dispatch error past fallback, lock irrecoverable), in addition to the `agent-log.md` line: (a) write `state.status = "paused"` and `state.haltReason = "<phase>:<cause>"`; (b) record the cause on the tracker via `phase-tracker.sh meta <phase> halt "<cause>"` and `phase-tracker.sh update <phase> failed`; (c) emit one `>&2` alert line `HALT phase <N>: <cause>  -  resume with /multi-agent:resume #<id>`; (d) if `prefs.global.usageLog.enabled` is true, emit the end-of-run report so a run that never reaches Phase 5 is still recorded with the phase it stopped at (`state.currentPhase` + `haltReason`) - the emitter no-ops when it is off or unconfigured:
 
 ```bash
-node $HOME/.claude/scripts/usage-report.mjs --state "$STATE_FILE" >/dev/null 2>&1 || true
+node $HOME/.claude/scripts/usage-report.mjs --state "$STATE_FILE" --event halted >/dev/null 2>&1 || true
+```
+
+**Park visibility.** A run that stops to wait for a person (`state.status = "awaiting_input"`, or `state.waitingFor` set: a maturity decision, an open question, the channels choice) emits the same report with `--event parked` right after the state write, so the panel shows it as waiting rather than abandoned:
+
+```bash
+node $HOME/.claude/scripts/usage-report.mjs --state "$STATE_FILE" --event parked >/dev/null 2>&1 || true
 ```
 
 Autopilot suppresses *confirmations*, not *halts*  -  the user must always be able to see why an unattended run stopped without reading the log. The endpoint upserts by run id, so this halt record and a later Phase 5 record (after resume) collapse into one.
@@ -162,11 +168,11 @@ This keeps orchestrator context lean and enables programmatic routing.
 
 **Retry reflection**: Before each retry, force reflection: "What failed? What specific change fixes it? Am I repeating the same approach?"  -  prevents infinite loops on broken strategies.
 
-**Semantic revert**: Track which files each phase produces in `agent-state.json`. If Phase 3 (testing) fails, revert only Phase 3 (implementation) outputs, not Phase 1 (artifacts):
+**Semantic revert**: Track which files each phase produces in `agent-state.json`. If Phase 2 (implementation) fails its gates, revert only Phase 2 outputs, not Phase 1 (artifacts):
 
 ```json
 "phases": {
-  "4": { "status": "done", "files": ["ButtonView.swift", "ButtonConfiguration.swift"] }
+  "2": { "status": "done", "files": ["ButtonView.swift", "ButtonConfiguration.swift"] }
 }
 ```