@mmerterden/multi-agent-pipeline 20.36.0 → 20.37.1

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

@@ -13,14 +13,14 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, WebFetch
 
 **One command. Full ecosystem sync. No arguments needed.**
 
-When invoked, it synchronizes all targets in order. It detects what changed, updates only the stale ones, and returns a result report. macOS only (ADR-0012); credential access goes through `~/.claude/lib/credential-store.sh` so no call site names the keychain backend.
+It syncs all targets in order, updating only the stale ones, and reports. macOS only (ADR-0012); credential access goes through `~/.claude/lib/credential-store.sh` so no call site names the keychain backend.
 
 **Input**: $ARGUMENTS (optional)
 
 | Arg | Meaning |
 |---|---|
-| (none) | Full ecosystem sync: Claude Code, Copilot CLI, pipeline repo, website, multi-agent-toolkit MCP server. |
-| `release` | Full sync + version bump + tag + npm publish + website deploy (plus the multi-agent-toolkit ship path) |
+| (none) | Full ecosystem sync, every target |
+| `release` | Full sync + version bump + tag + npm publish + website deploy (Release Flow) |
 | `multi-agent-toolkit` | Run Step 3d only: gate, commit and publish the companion MCP server |
 | `"change description"` | Apply the description to every target at once |
 
@@ -28,43 +28,16 @@ When invoked, it synchronizes all targets in order. It detects what changed, upd
 
 - The pre-push gate is timing-sensitive: under heavy load a deadline test fails closed. Re-run it on a quiet machine; never push with `--no-verify`.
 - `npm publish` answering 202 means the registry is still processing. Verify with the registry's dist-tags before moving `required`, which is asked for every release.
-- The installed tree is localized (Turkish descriptions, `model: opus` while fable is off). Normalize before copying into the repo, or the public tree ships the local form.
+- The installed tree is localized (Turkish descriptions, `model: opus` while fable is off). Normalize to English and `model: fable` before copying into the repo.
 - Synced shell runs on BSD userland: BSD grep has no Perl-regex flag, and `sed` has no `\b` or `\|`. A pattern that silently matches nothing reads as "clean".
 
 ## Targets
 
-| # | Target | Path | Direction |
-|---|-------|-----|-----|
-| 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.claude/agents/` + `~/.claude/scripts/` + `~/.claude/lib/` | source |
-| 2 | Copilot CLI | `~/.copilot/copilot-instructions.md` + `~/.copilot/skills/` | <- from Claude |
-| 2b | Codex CLI | `~/.codex/AGENTS.md` + `~/.codex/skills/multi-agent/` + `~/.codex/multi-agent-refs/` + `~/.codex/agents/*.toml` | <- from Claude (path-rewritten) |
-| 3 | multi-agent-pipeline repo | `~/multi-agent-pipeline/pipeline/` | <- from Claude (genericized) |
-| 4 | Website | `{owner}/{website-host}` | <- version + features |
-| 5 | multi-agent-toolkit MCP server | resolved from `prefs.global.devToolkit` or the `mcpServers` registration | own repo: gate, commit, publish |
-
-## Platform Support (macOS only)
-
-Only macOS is supported (ADR-0012). `package.json` declares `os: ["darwin"]`, which npm enforces on the root package, so this tree cannot be installed elsewhere, and a detection table for other hosts would describe a case that cannot occur.
-
-**Contract for synced shell scripts.** The runtime is BSD userland and bash 3.2,
-and that is a stricter constraint than "cross-platform", not a looser one:
-
-1. Path handling: always quote (`"$f"`); use `$HOME`, never `/Users/...`.
-2. `grep -P` is banned. BSD grep has no `-P`: it exits 2, and with `2>/dev/null`
-   that reads as "found nothing". Two gates have already shipped green for
-   exactly this reason. Use `-E`.
-3. Timestamps: `stat -c %Y` FIRST, then `stat -f %m`. GNU-first ordering is
-   required because `stat -f` is a valid GNU flag (`--file-system`) that
-   succeeds and prints something that is not a timestamp.
-4. Hashes: `sha256sum || shasum`, in that order. The gate fails a file that
-   names either alone.
-5. `find` traversal: `-prune` for `node_modules`, `Pods`, `.build`,
-   `DerivedData`, `.next`.
-6. Sed / awk: POSIX-portable. `-E`, never `-r`; `sed -i ''` on BSD.
-7. Keychain I/O: always via `~/.claude/lib/credential-store.sh get|set`, never
-   `security` directly - the wrapper is what keeps a secret off argv.
-8. Verification: after Step 3 (REPO), `bash -n` every shell script in
-   `pipeline/lib/` and `pipeline/scripts/`.
+Claude Code (source of truth) -> Copilot CLI, Codex CLI (path-rewritten), the
+pipeline repo (genericized), the website (`{owner}/{website-host}`) and the
+multi-agent-toolkit MCP server (its own repo). Paths, directions, the shared
+Claude <-> Copilot sections and the token table: `$HOME/.claude/multi-agent-refs/sync/overview.md`; read it
+before Step 1.5.
 
 ## Default Behavior (no arguments)
 
@@ -74,15 +47,14 @@ Run every step automatically:
 Step 0: DOCTOR      doctor.mjs  -  exit 2 or 4 stops the sync
 Step 1.5: DETECT    Compare timestamps, find stale targets
 Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 70 sub-command skills)
-Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + sub-command specs as refs + agent TOML)
+Step 2b: CODEX      Claude Code -> Codex CLI (router skill + specs as refs + agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
-Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
-                     bump changed plugins' patch version, commit + push the plugins repo)
+Step 3c: PLUGINS    shared/external -> multi-agent-plugins marketplace (rebuild, bump, push)
 Step 3d: DEV-TOOLKIT companion MCP server -> detect movement, run the ship gates, commit + publish
 Step 3e: OFFICE      panel page is current, installed copies match it, toolkit version recorded
 Step 4: WEBSITE     Version + phase/model counts -> {website-host} (i18n + projects.ts)
 Step 5: Commit      Commit + push all changed repos
-Step 6: Report      Summary: synced targets, platform, changed files, deploy status, multi-agent-toolkit version
+Step 6: Report      Synced targets, changed files, deploy status, multi-agent-toolkit version
 ```
 
 If nothing is stale → report "All targets up to date" and stop.
@@ -93,104 +65,30 @@ Step 0 gate rules and why: `features/doctor.md`.
 
 ## Sync rules
 
-1. **Read first**  -  understand every target's current state before making any change
-2. **Preserve file structure**  -  each target has its own format:
-   - `commands/multi-agent/` SKILL tree + `multi-agent-refs/phases/`: detailed pipeline spec (frontmatter, phases, routing)
-   - `copilot-instructions.md`: general development instructions + pipeline summary section
-   - `multi-agent-pipeline/pipeline/`: generic open-source version (NO personal data)
-3. **Sync the shared sections** (Claude ↔ Copilot):
-   - Pipeline entries table (base / :autopilot)
-   - Project detection (URL-based + cwd-based)
-   - Figma pipeline flow
-   - Git conventions (author, branch, commit format)
-   - Keychain management (registry, naming convention, multi-agent pattern)
-4. **Do not duplicate**  -  summary in Copilot, full spec in Claude. Keep this distinction.
-5. **Report**  -  show a short diff summary after sync
+Read every target's current state before changing anything; keep each target's
+own format; summary in Copilot, full spec in Claude, never duplicated; finish
+with a short diff summary.
 
 ---
 
-## Pipeline Repo Sync Rules (CRITICAL)
-
-1. **Source**: `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.claude/agents/` + `~/.claude/lib/`
-2. **Target**: `~/multi-agent-pipeline/pipeline/`
-3. **Genericization** (must be applied BEFORE writing to the target):
-   - Jira project key (`prefs.global.defaultJiraKey`) -> `{JIRA_KEY}`, `PROJ` in examples
-   - Personal names/emails -> generic placeholder
-   - Branch names -> `develop`
-   - Project names -> `my-app`
-   - `{JIRA_HOST}`, `{BITBUCKET_HOST}`, `{CONFLUENCE_HOST}`, `{CORP_DOMAIN}` stay as-is
-   - **Verify**: `grep` scan for personal/corporate data inside pipeline/ -> 0 results
-4. **File mapping**:
-   ```
-   ~/.claude/commands/multi-agent/        -> pipeline/commands/multi-agent/
-   ~/.claude/multi-agent-refs/            -> pipeline/multi-agent-refs/   (refs + pickers, non-command)
-   ~/.claude/commands/sim-test.md         -> pipeline/commands/sim-test.md
-   ~/.claude/agents/*.md                  -> pipeline/agents/
-   ```
-5. **Files NOT synced** (local-only, may contain personal data):
-   - `~/.claude/multi-agent-preferences.json`
-   - `~/.claude/CLAUDE.md`, `~/.claude/rules/`, `~/.claude/knowledge/`
-   - `~/.claude/scripts/`  -  EXCEPT `pre-commit-check.sh`, `agent-guard.sh`, `agent-guard.py`, and `build-stack-plugins.mjs` (generic, synced)
-   - `~/.claude/settings.json`
-   - `~/.claude/office/`  -  the office panel flows the other way: its source is the repo (`pipeline/office-src`, built by `office-build.mjs` into `pipeline/office`), and the installer copies it to each host. Never copy it from `~/.claude` into the repo; Step 3e checks it instead
-   - `~/.claude/multi-agent-refs/registries/`  -  the installer copies gate registries there from `pipeline/skills/shared/external`; the repo already holds the source
-   - **Any `~/.claude/commands/multi-agent/*/SKILL.md` whose frontmatter has `local-only: true`** - these are user/repo-specific alias wrappers that delegate to a private marketplace plugin's skills exposed as `multi-agent:<name>`. Syncing them would leak the private plugin/skill names into the public pipeline. Skip them at copy time; the backstop below proves none reached `pipeline/commands/`.
-     ```bash
-     grep -rl "^local-only: true" ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
-       && { echo "ABORT: local-only wrapper leaked into pipeline/commands"; exit 1; } || true
-     # backstop: corporate refs only (generic ai-ios-toolkit is fine)
-     grep -rniE "ai-(ios-engineering|mobile)-toolkit:(create-ui-component|evolve-ui-component|fix-bug|branch-and-pr|backlog|code-connect|figma-utility|resource-utility|component-wiki|component-docs|figma-setup)" \
-       ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
-       && { echo "ABORT: corporate reference leaked into pipeline/commands"; exit 1; } || true
-     ```
-   - **Installed-tree artifacts.** Picker descriptions are Turkish with a
-     `description-en:` sidecar when `outputLanguage=tr`, and fable-tier agents
-     carry `model: opus` while `fableEnabled` is off. The repo always gets the
-     English form and `model: fable`, so normalize after copying:
-     ```bash
-     # normalize: restore English descriptions, strip description-en sidecars
-     node ~/multi-agent-pipeline/pipeline/scripts/localize-commands.mjs restore \
-       --dir ~/multi-agent-pipeline/pipeline/commands/multi-agent
-     grep -rl "^description-en:" ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
-       && { echo "ABORT: description-en sidecar leaked into pipeline/commands"; exit 1; } || true
-     # backstop: repo description lines must be English (Turkish-diacritics proxy)
-     grep -rn '^description:.*[çğıöşüÇĞİÖŞÜ]' ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
-       && { echo "ABORT: localized description leaked into pipeline/commands"; exit 1; } || true
-     node ~/multi-agent-pipeline/pipeline/lib/agent-model-sync.mjs --dir ~/multi-agent-pipeline/pipeline/agents --fable-on
-     ```
-
-6. **Cross-platform smoke gate** (final step of the REPO sync, before push):
-   ```bash
-   # bash -n: parse-level syntax check on every shell script
-   find ~/multi-agent-pipeline/pipeline/lib ~/multi-agent-pipeline/pipeline/scripts \
-        -name "*.sh" -type f -exec bash -n {} \;
-   # Should print nothing  -  any output is a portability regression.
-
-   # Portability grep: flag known non-portable constructs introduced post-sync.
-   grep -rnE "stat -f[^[:space:]]+[^|]|sed -i[^[:space:]'\"]" \
-        ~/multi-agent-pipeline/pipeline/lib ~/multi-agent-pipeline/pipeline/scripts || true
-   # Each hit needs an explicit GNU/BSD fallback per the Platform Support contract.
-   ```
-   Gate failure -> abort push, surface the file + line, fix in the `~/.claude/` source first, re-sync.
+## Step procedures (read each file before its step)
 
----
-
-## Codex Sync (Step 2b)
-
-Full procedure: `$HOME/.claude/multi-agent-refs/sync/codex.md`. Read it before Step 2b; it runs after Step 3.
-
-## Stack-Plugin Sync (Step 3c)
-
-Full procedure: `$HOME/.claude/multi-agent-refs/sync/stack-plugins.md`. Read it before Step 3c.
+| Step | Procedure |
+|---|---|
+| 2b CODEX (runs after Step 3) | `$HOME/.claude/multi-agent-refs/sync/codex.md` |
+| 3 REPO | `$HOME/.claude/multi-agent-refs/sync/repo.md` |
+| 3c PLUGINS | `$HOME/.claude/multi-agent-refs/sync/stack-plugins.md` |
+| 3d DEV-TOOLKIT (and `multi-agent-toolkit` arg) | `$HOME/.claude/multi-agent-refs/sync/dev-toolkit.md` |
+| 3e OFFICE (also release step 9c) | `$HOME/.claude/multi-agent-refs/sync/office.md` |
 
-## Dev-Toolkit Sync (Step 3d)
+Hard rules for Step 3, whatever `repo.md` adds:
 
-Full procedure: `$HOME/.claude/multi-agent-refs/sync/dev-toolkit.md`. Read it before Step 3d, and for `/multi-agent:sync multi-agent-toolkit`.
+- Genericize BEFORE writing to `~/multi-agent-pipeline/pipeline/`; the personal/corporate data scan must return 0 results.
+- Never sync a `local-only: true` SKILL.md, local config, or `~/.claude/office/`. A leaked wrapper, sidecar or localized description aborts the sync.
+- Synced shell follows the BSD / bash 3.2 contract in `repo.md` (`grep -P` banned, keychain I/O only via `credential-store.sh`). A failed smoke gate aborts the push; fix the `~/.claude/` source, re-sync.
 
 ## Website Sync (Step 4)
 
-Propagate version, phase and model counts and feature descriptions to the website.
-
 ```bash
 gh auth switch --user {owner}
 WEBSITE_DIR="$HOME/{website-host}"
@@ -198,14 +96,10 @@ WEBSITE_DIR="$HOME/{website-host}"
 cd "$WEBSITE_DIR" && git pull origin main
 ```
 
-| File | What to sync |
-|-------|--------------|
-| `src/lib/i18n.tsx` | Phase count, model count, feature descriptions (EN + TR) |
-| `src/data/projects.ts` | Version number, tagline, description, feature list |
+Files: `src/lib/i18n.tsx` (counts, feature copy EN + TR) and `src/data/projects.ts` (version, features); detail in `overview.md`.
 
 ```bash
-# A commit the platform does not recognise is pushed fine and never built, so the site
-# keeps the old version. {identity} is the one routed to {owner}, not the run's own.
+# {identity} is the one routed to {owner}, not the run's own.
 # Why, signature, recovery: `$HOME/.claude/multi-agent-refs/website-deploy.md`.
 bash "$HOME/.claude/scripts/website-deploy-commit.sh" "{identity.name}" "{identity.email}" "{VERSION}" "$WEBSITE_DIR"
 ```
@@ -219,8 +113,7 @@ When invoked with the `release` argument:
 ```
 1. REPO          Claude Code -> pipeline repo (genericized)
 2. VERIFY        Personal data scan -> 0 results; config-hygiene scan (scan-agent-config.sh) -> 0 HIGH
-3. LINT + TEST   ESLint + smoke tests (stale .skill-manifest.json fails here; re-sign
-                 it with sign-skills.sh whenever a SKILL.md moved)
+3. LINT + TEST   ESLint + smoke tests (re-sign .skill-manifest.json with sign-skills.sh when a SKILL.md moved)
 4. VERSION       package.json version bump (patch/minor/major)
 5. Commit + TAG  git commit + git tag v{VERSION}
 6. PUSH          git push --tags; publish is local (release.yml off)
@@ -232,26 +125,13 @@ When invoked with the `release` argument:
 10. Report       Summary: version, touched repos, deploy status
 ```
 
-### Step 3e: OFFICE (every sync, and step 9c of a release)
-
-The office panel ships with the pipeline, so a sync carries it by checking it, not by copying it:
-
-1. `node ~/multi-agent-pipeline/pipeline/scripts/office-build.mjs --check`: the committed page is what `pipeline/office-src` builds to, and `office/toolkit.json` carries the toolkit version in `docs/facts.json`. Either stale fails the sync until it is rebuilt and committed; a release that regenerates facts rebuilds the office right after.
-2. After the install steps, compare `pipeline/office/index.html` with the installed copies (`~/.claude/office/`, and the Copilot and Codex trees when installed), byte for byte, plus the asset list. A difference means the install is behind: run `node install.js --installed` and compare again.
-3. Report the toolkit version the installed `office/toolkit.json` carries: it is what the office Tools window starts, and it moves forward with every release.
-4. An office server that is already running picks the update up by itself: the open page shows a reload banner, and `/multi-agent:office-on` replaces a server whose code changed. Nothing to restart by hand.
-
 ---
 
 ## Sub-Command Sync (Claude Code <-> Copilot CLI Skills)
 
-This runs on the Claude <-> Copilot axis. Codex is NOT synced here: it receives the
-same specs as reference files rather than as peer skills, via Step 2b -  see
-`cross-cli-contract.md` 2.6 for why the parity axis differs per host.
+Claude <-> Copilot axis only; Codex takes Step 2b (`cross-cli-contract.md` 2.6).
 
-| Claude Code | Copilot CLI |
-|-------------|-------------|
-| `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
+`~/.claude/commands/multi-agent/{cmd}/SKILL.md` <-> `~/.copilot/skills/multi-agent-{cmd}/SKILL.md`.
 
 **70 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
@@ -268,20 +148,11 @@ testflight-validation, uninstall, update
 
 **NOT synced**: `$HOME/.claude/multi-agent-refs/*`  -  lazy-load references, Claude Code specific
 
-**Claude -> Copilot**: add SKILL.md frontmatter (`name`, `description`, `user-invocable: true`, `argument-hint`)
-**Copilot -> Claude**: simplify the frontmatter (`description` + `allowed-tools`), add `$ARGUMENTS`
+Frontmatter conversion between the two forms: `overview.md`, "Sub-command paths".
 
 ---
 
 ## Keychain Token Access
 
-| Operation | Token Source |
-|-------|---------------|
-| `gh` CLI (personal) | `{owner}` gh auth (Keychain) |
-| `gh` CLI (work) | `{user}_<work-label>` gh auth (Keychain)  -  see `prefs.global.accounts[]` |
-| npm publish | `NODE_AUTH_TOKEN`  -  `GITHUB_TOKEN` in CI, Keychain PAT locally |
-| multi-agent-toolkit publish (Step 3d) | `npm` logical Keychain key -> throwaway `--userconfig`, registry from that repo's `publishConfig` |
-
-```bash
-gh auth switch --user {owner}  # for personal repos
-```
+Token sources per operation: `overview.md`. Personal repos run under
+`gh auth switch --user {owner}`; tokens are read only through `credential-store.sh`.

package/pipeline/commands/multi-agent/test-gen/SKILL.md

@@ -75,10 +75,8 @@ Scripts: `test-gen-gate.mjs` (artefact, handle and write gates),
    (`tracker-contract.md`, "Call pattern").
 2. Toolkit: `test_results_classify`, `coverage_gap` and `ui_locator_codegen`
    need `@mmerterden/multi-agent-toolkit-mcp` >= v3.25.0. Check the tool list
-   once. Each missing tool has a fallback in `stages.md` (classify from the
-   repeats, the analyst matches coverage itself with every match `inferred`,
-   locators written by hand from the handles); say which fallbacks are in use,
-   once.
+   once. Each missing tool has a fallback in `stages.md` (stages 3, 5 and 7);
+   say which fallbacks are in use, once.
 3. Change base. `TG_STATE="$HOME/.claude/knowledge/<project>/test-gen-state.json"`:
 
    ```bash

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

@@ -14,9 +14,7 @@ confirm: none
 node "$HOME/.claude/scripts/doctor.mjs"
 ```
 
-An update is the moment the layout changes, so it is the moment a layout check is
-worth most: a script that moved, a host tree that did not get the copy, a version
-stamp that disagrees with the package. Report the result in `outputLanguage`.
+Report the result in `outputLanguage`.
 Exit 2 means the update left the install in a state a run will fail from - say
 that, do not report "updated" and stop.
 
@@ -24,7 +22,10 @@ that, do not report "updated" and stop.
 
 Update the pipeline in one command. The npm registry is the single update channel: the latest published release is downloaded and installed. Existing preferences are preserved; only skill / script / schema files are refreshed.
 
-A git clone of the pipeline repo is a maintainer workspace, kept in sync by `/multi-agent:sync` - it is never consulted here. A fix that only exists on `main` reaches users when a release is published, not before.
+Reasoning behind the steps, the step 6 summary format and a sample output:
+`$HOME/.claude/multi-agent-refs/update/details.md`; read it before step 6.
+
+A git clone of the pipeline repo is a maintainer workspace (`/multi-agent:sync`) and is never consulted here.
 
 ## Steps
 
@@ -40,7 +41,7 @@ and every later block that needs them starts by sourcing it.
    UPD_DIR="${TMPDIR:-/tmp}/multi-agent-update"
    CUR=$(tr -d '[:space:]' < "$HOME/.claude/.pipeline-version" 2>/dev/null)
    [ -n "$CUR" ] || CUR="unknown"
-   # Read the registry directly - `npm view` can answer from a stale local cache.
+   # Read the registry directly, never `npm view`.
    LATEST=$(curl -fsS "$REG/$(printf '%s' "$PKG" | sed 's|/|%2F|')/latest" \
      | node -pe 'JSON.parse(require("fs").readFileSync(0,"utf8")).version' 2>/dev/null)
    if [ -z "$LATEST" ]; then
@@ -71,10 +72,7 @@ and every later block that needs them starts by sourcing it.
    ```bash
    . "${TMPDIR:-/tmp}/multi-agent-update.env" || { echo "Run step 1 first."; exit 1; }
    rm -rf "$UPD_DIR" && mkdir -p "$UPD_DIR"
-   # `--registry` does NOT override a scope mapping. A user-level .npmrc line
-   # like `@scope:registry=https://npm.pkg.github.com` wins over it, so the
-   # download hits the wrong registry, fails with `notarget`, and `--silent`
-   # hides why. Pin the SCOPE, which is the setting that actually loses.
+   # Pin the SCOPE: `--registry` alone loses to an .npmrc scope mapping.
    SCOPE=$(printf '%s' "$PKG" | sed -n 's|^@\([^/]*\)/.*|\1|p')
    PACK_OUT=$(npm pack "$PKG@$LATEST" ${SCOPE:+"--@${SCOPE}:registry=$REG"} \
      --registry "$REG" --pack-destination "$UPD_DIR" 2>&1) || {
@@ -83,20 +81,16 @@ and every later block that needs them starts by sourcing it.
      echo "  npm config get @${SCOPE}:registry"
      exit 1
    }
-   # Never glob into tar: an older tarball left in $UPD_DIR would be extracted
-   # instead, and the run would install the version it was trying to leave.
+   # Never glob into tar: take the path npm pack printed.
    TGZ="$UPD_DIR/$(printf '%s' "$PACK_OUT" | tail -1 | tr -d '[:space:]')"
    [ -f "$TGZ" ] || { echo "npm pack reported no tarball; aborting."; exit 1; }
    tar -xzf "$TGZ" -C "$UPD_DIR"
    node "$UPD_DIR/package/install.js" --installed
    ```
 
-   `--installed` refreshes exactly the CLI targets that already carry a version
-   stamp (`$HOME/.claude/.pipeline-version`, `$HOME/.copilot/.pipeline-version`,
-   `$HOME/.codex/.pipeline-version`) and adds none: an update never installs
-   Copilot CLI or Codex CLI on a machine that only had Claude Code. With no stamp
-   at all it installs Claude Code. Each refreshed target gets the new version
-   stamp.
+   `--installed` refreshes only the CLI targets that already carry a version
+   stamp and adds none: an update never installs a CLI target the machine did
+   not have.
 
 4b. **Update the stack plugins** (catalog refresh, then every installed plugin in its own scope):
    ```bash
@@ -108,10 +102,8 @@ and every later block that needs them starts by sourcing it.
    ```
    A non-zero exit means a step failed and the CLI's own error is already on screen. Report it to the user; do not retry silently. The log feeds step 6, which tells the user what each updated plugin brought.
 
-4c. **Prune retired adapter files** (Cursor / Antigravity / Copilot Chat were removed in v10.7.0 - the pipeline targets Claude Code, Copilot CLI and Codex CLI):
+4c. **Prune retired adapter files** (per-project adapter files are left untouched; see `details.md`):
    ```bash
-   # Per-project adapter files (.cursor/, .agent/, .github/copilot-instructions.md)
-   # live in your repos and are left untouched - remove them manually if you like.
    echo "  -> no global adapter files to prune"
    ```
 
@@ -156,27 +148,11 @@ and every later block that needs them starts by sourcing it.
      --plugin-refresh-log "${TMPDIR:-/tmp}/multi-agent-plugin-refresh.log"
    ```
 
-   The JSON holds every release between the old and the new version (not only
-   the last one) and, for each plugin the refresh moved, that plugin's releases.
-   Turn it into a short note in `outputLanguage`, written for the person using
-   the pipeline, not for its maintainers:
-
-   - First line: `✓ Updated: v<CUR> → v<NEW>`, then one line per updated plugin
-     (`ai-ios-toolkit 0.20.0 → 0.21.0`).
-   - Then up to four groups, each only when it has entries: **New** (added),
-     **Fixed**, **Changed**, **Removed** (Turkish: Yeni, Düzeltilen, Değişen,
-     Kaldırılan). Put security entries first under Fixed.
-   - One plain sentence per item about what the user notices or can now do.
-     Merge items that say the same thing; leave out internal-only entries
-     (smoke tests, CI, refactors, budgets, docs) unless they change what a user
-     sees. At most about eight items per group; when more were dropped, say how
-     many and that the full list is in the CHANGELOG.
-   - Use only what the JSON says. Never invent a feature or a fix, and never
-     guess why something changed.
-   - Last line, when anything needs action: what to do (restart Claude Code for
-     plugin changes, run a command a release asks for).
-
-   With empty notes and no plugin updates, print only the version line.
+   Turn the JSON into a short note in `outputLanguage` for the person using the
+   pipeline, in the format of `details.md`, "Writing the step 6 summary" (version
+   line, plugin lines, New / Fixed / Changed / Removed groups). Use only what the
+   JSON says. Never invent a feature or a fix, and never guess why something
+   changed. With empty notes and no plugin updates, print only the version line.
 
 7. **Smoke test (optional)** - the release tarball ships exactly two smokes for this purpose:
    ```bash
@@ -190,22 +166,4 @@ and every later block that needs them starts by sourcing it.
 
 ## Output
 
-```
-Current: v15.6.0   Latest: v15.7.0
-  -> npm pack @{npm-scope}/multi-agent-pipeline@15.7.0
-  -> node install.js --installed (Claude Code; no Copilot CLI or Codex CLI stamp, not installed)
-  -> migrate-prefs.mjs (0 changes  -  already v2.6.0)
-
-✓ Updated: v15.6.0 → v15.7.0
-  ai-ios-toolkit 0.19.0 → 0.20.0
-
-New
-  - iOS design review: critiques a screen against the HIG from screenshots.
-Fixed
-  - The usage report reads the tracker as it is written.
-Restart Claude Code to load the updated plugins.
-
-Verification:
-  schema-validation: 27/27 pass
-  cross-cli-behavior: 14/14 pass
-```
+See the sample in `details.md`.

package/pipeline/contract/CHANGELOG.md

@@ -3,6 +3,15 @@
 Versions of the client contract (`manifest.json` `contractVersion`), separate
 from the package version. See `README.md` for what counts as minor and major.
 
+## 1.8.0
+
+Added. Nothing existing changes shape.
+
+- `runs-index` 1.4.0 (`GET /v1/runs`, `/v1/runs/{id}`, `/v1/phone/runs`): `group`
+  can be `done`, for a run whose status is complete, completed, done, abandoned
+  or cancelled. Such a run was grouped by phase before, so a finished run could
+  read as waiting. A client that does not know a group shows it neutrally.
+
 ## 1.7.0
 
 Added. Nothing existing changes shape.

package/pipeline/contract/fixtures/error-invalid-request.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.7.0",
+  "contractVersion": "1.8.0",
   "error": "invalid-request",
   "message": "the launch request was refused",
   "errors": [

package/pipeline/contract/fixtures/error-unauthorized.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.7.0",
+  "contractVersion": "1.8.0",
   "error": "unauthorized",
   "message": "a bearer token is required"
 }

package/pipeline/contract/fixtures/error-unsigned.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.7.0",
+  "contractVersion": "1.8.0",
   "error": "unsigned",
   "message": "a device signature is required"
 }

package/pipeline/contract/fixtures/runs-awaiting-question.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.3.0",
+  "contractVersion": "1.4.0",
   "logsRoot": "/Users/example/.claude/logs/multi-agent",
   "count": 1,
   "runs": [

package/pipeline/contract/fixtures/runs-empty.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.3.0",
+  "contractVersion": "1.4.0",
   "logsRoot": "/Users/example/.claude/logs/multi-agent",
   "count": 0,
   "runs": []

package/pipeline/contract/fixtures/runs-failed.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.3.0",
+  "contractVersion": "1.4.0",
   "logsRoot": "/Users/example/.claude/logs/multi-agent",
   "count": 1,
   "runs": [

package/pipeline/contract/fixtures/runs-pr-opened-redacted.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.3.0",
+  "contractVersion": "1.4.0",
   "count": 1,
   "runs": [
     {

package/pipeline/contract/fixtures/runs-pr-opened.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.3.0",
+  "contractVersion": "1.4.0",
   "logsRoot": "/Users/example/.claude/logs/multi-agent",
   "count": 1,
   "runs": [

package/pipeline/contract/fixtures/runs-running.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.3.0",
+  "contractVersion": "1.4.0",
   "logsRoot": "/Users/example/.claude/logs/multi-agent",
   "count": 1,
   "runs": [

package/pipeline/contract/manifest.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.7.0",
+  "contractVersion": "1.8.0",
   "supportedMajors": [1],
   "description": "The pipeline's client contract: every surface a client reads or writes, the CLI invocation and the HTTP route that carry it, and the schema its JSON follows. Schemas are not copied here; schemasDir points at the one tree the producers validate against. Paths in cli are relative to the pipeline directory (installed: ~/.claude).",
   "schemasDir": "../schemas",
@@ -120,7 +120,7 @@
       "query": ["group", "redact"],
       "cli": ["node", "scripts/runs-index.mjs", "--json", "[--group <group>]", "[--redact]"],
       "schema": "runs-index.schema.json",
-      "version": "1.3.0",
+      "version": "1.4.0",
       "remote": "read",
       "risk": "read"
     },
@@ -131,7 +131,7 @@
       "query": ["redact"],
       "cli": ["node", "scripts/runs-index.mjs", "--json", "--task-id", "{id}", "[--redact]"],
       "schema": "runs-index.schema.json",
-      "version": "1.3.0",
+      "version": "1.4.0",
       "remote": "read",
       "risk": "read"
     },
@@ -378,7 +378,7 @@
       "scope": "read",
       "cli": ["node", "scripts/runs-index.mjs", "--json", "[--group <group>]", "--redact"],
       "schema": "runs-index.schema.json",
-      "version": "1.3.0",
+      "version": "1.4.0",
       "note": "Always redacted; redact=0 is refused.",
       "risk": "read"
     },
@@ -391,7 +391,7 @@
       "scope": "read",
       "cli": ["node", "scripts/runs-index.mjs", "--json", "--task-id", "{id}", "--redact"],
       "schema": "runs-index.schema.json",
-      "version": "1.3.0",
+      "version": "1.4.0",
       "note": "Always redacted; redact=0 is refused.",
       "risk": "read"
     },

package/pipeline/contract/types/index.d.ts

@@ -1,7 +1,7 @@
 // Generated by pipeline/contract/build.mjs from pipeline/schemas/*.schema.json.
 // Do not edit: change the schema and run `node pipeline/contract/build.mjs --write`.
 
-export type ContractVersion = "1.7.0";
+export type ContractVersion = "1.8.0";
 export type SurfaceId = "runs" | "run" | "commands" | "questions" | "issues" | "worktrees" | "launch-spec" | "repos" | "repo-add" | "repo-remove" | "launch" | "answer" | "run-log" | "resume" | "kill" | "gc" | "autopilot" | "autopilot-off" | "phone-runs" | "phone-run" | "phone-answer" | "phone-launch" | "autopilot-on" | "steer" | "activity" | "activity-stream" | "agent-chat" | "routines" | "routine-delete" | "jobs" | "job-start" | "stack" | "stack-set" | "ledger" | "system" | "prune-logs" | "settings" | "settings-set" | "credentials" | "memory" | "run-results" | "run-evidence" | "review-verdict" | "issue-maturity" | "prs" | "prs-reach" | "tools" | "tool-call" | "service-confluence" | "service-crashlytics" | "service-figma" | "permissions";
 
 /** What `runs-index.mjs --json` prints: every run under the log root and the unattended log root (one record per task id), grouped per status/SKILL.md 3b. Fields are only ever added - a decoder ignores keys it does not know. `--redact` drops every x-sensitivity local field (and `logsRoot`) and scrubs the free text in the title, `now`, sub-step names, task subjects and the pending question. */
@@ -42,7 +42,8 @@ export interface RunsIndexRun {
   waitingFor?: string | null;
   /** The question the run stopped on, present only with waitingFor question. Answer it with one of options[].id through `answer-question.mjs` or POST /v1/runs/{id}/answer. text and labels are scrubbed under --redact. Added in 1.1.0. */
   pendingQuestion?: null | RunsIndexQuestion;
-  group: "waiting" | "stopped" | "question" | "unknown";
+  /** done (added in 1.4.0): the run's status is complete, completed, done, abandoned or cancelled; it is placed before every other test, so a finished run is never offered resume. */
+  group: "waiting" | "stopped" | "question" | "unknown" | "done";
   phases: Array<RunsIndexPhase>;
   tokens: {
     in: number;