@mmerterden/multi-agent-pipeline 16.9.0 → 16.10.1

package/CHANGELOG.md

@@ -26,6 +26,31 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 - **`smoke-website-deploy-identity.sh` (20 assertions).** It runs the script against throwaway repos with real remotes rather than grepping the doc: the happy path lands and pushes, an exported `GIT_AUTHOR_EMAIL` halts with the commit still local, an unchanged tree makes no empty commit, a matching config is preserved while a wrong name is corrected, and missing or non-repository arguments exit 2. Wiring is asserted separately, since a correct script nothing calls is its own failure mode.
 
+## [16.10.1] - 2026-08-26
+
+### Fixed
+
+- **`write-state.mjs` could delete a live lock and lose a writer's update.** The stale-lock reclaim deleted by path: between judging a lock stale and unlinking it, the holder can release and a third writer can acquire a fresh one, so the unlink removed a *live* lock and two writers then held it. It is the same failure the PID-window comment in that file already describes, at a different point in the acquire loop, and it survived because it only reproduces under load - `smoke-write-state.sh` failed inside a full gate run and passed 12/12 when run alone. Reclaim is now by identity: the inode and mtime judged stale must still be the file at that path, otherwise it belongs to somebody else and is left alone. Twelve runs under artificial load are clean, which is evidence and not proof - a race cannot be proven absent.
+
+- **Counts that had drifted from the tree.** `skills-index.md` and `skills/shared/README.md` still said 208 skills against 210 on disk; both are generated, so they were regenerated rather than hand-edited. `/multi-agent:update` quoted "245 scripts, 208 skills" for what an install lays down; it is 263 and 210. A comment in `smoke-command-inventory.sh` used "51 commands" as its example, which is the kind of number that goes stale the moment a command lands - it now says what it means without pinning a figure.
+
+## [16.10.0] - 2026-08-26
+
+Three debts the last few releases kept naming, closed.
+
+### Added
+
+- **`smoke-help-sync.sh` pairs each command's own description with the line `/multi-agent:help` shows for it.** Three releases running shipped the same defect: 16.7.1 (two commands absent from help entirely), 16.8.1 (the analysis entry describing behaviour from two releases earlier), 16.9.0 (a telemetry block still saying "optional, opt-in" after the default flipped). Every other gate was green through all three, because none of them asked whether the sentence a user reads still matches what the command does. The gate hashes both sides and fails when one moved without the other. Its limit is written into the file: it cannot tell whether either text is *correct* - a maintainer who edits both to say something equally wrong still passes. What it forces is that the pair gets looked at together, which is exactly what did not happen those three times.
+
+### Changed
+
+- **The telemetry self-registration path no longer needs `jq`.** It read preferences through `jq` behind a `command -v jq` guard, so a machine without jq silently never registered and never reported - which in the panel is indistinguishable from nobody using the pipeline. Reads now go through `node`, a declared engine (>=20.11), so the path cannot be skipped for a missing tool. Thirteen other shell helpers still use jq; the install now prints one note when it is absent, naming what degrades (cost summaries, the tracker's JSON reads, convention extraction, skill signing) instead of leaving each to fail quietly. Both READMEs gained a prerequisites section.
+- **The phase-doc token budget has room again.** The token-telemetry instructions were repeated verbatim in four phase docs while the canonical text already lived in `progress-contract.md`; the phases now point at it. Total goes 57599 -> 57059 against a 57600 ceiling, so headroom moves from 1 token to 541. The ceiling was not raised - the space came back from text that had more than its share, the same rule 16.7.1 followed for `help`.
+
+### Fixed
+
+- Six phase docs cited `progress-contract.md#token-telemetry-forwarding-v83`; the heading anchors as `#token-telemetry-forwarding`, so none of those links resolved.
+
 ## [16.9.0] - 2026-08-25
 
 ### Added

package/README.md

@@ -14,6 +14,12 @@ Runs natively on Claude Code, Copilot CLI and Codex CLI. macOS / Linux / Windows
 
 📐 **[Architecture diagrams](./docs/architecture.md)** - the 8-phase flow, operating modes, review/triage, Figma subphases, component layout. **[Ecosystem diagram](./docs/ecosystem.md)** - how this repo, the `multi-agent-plugins` marketplace and `multi-agent-toolkit-mcp` compose.
 
+### Prerequisites
+
+- **Node.js >= 20.11** - required; the pipeline's own tooling runs on it.
+- **`jq`** - optional but recommended. Thirteen shell helpers reach for it and skip in silence without it: cost summaries, the phase tracker's JSON reads, convention extraction, skill signing. The install prints a note when it is missing.
+- **`gh`** - for GitHub issue and PR work. Its built-in `--jq` is independent of the `jq` binary.
+
 ## Quick Start
 
 ```bash

package/README.tr.md

@@ -14,6 +14,12 @@ Claude Code, Copilot CLI ve Codex CLI üzerinde native çalışır. macOS / Linu
 
 📐 **[Mimari diyagramları](./docs/architecture.md)** - 8 faz akışı, çalışma modları, review/triage, Figma subphase'leri, component yapısı. **[Ekosistem diyagramı](./docs/ecosystem.md)** - bu repo, `multi-agent-plugins` marketplace'i ve `multi-agent-toolkit-mcp`'nin nasıl bir araya geldiği.
 
+### Önkoşullar
+
+- **Node.js >= 20.11** - zorunlu; pipeline'ın kendi araçları bunun üzerinde koşuyor.
+- **`jq`** - opsiyonel ama önerilir. On üç kabuk yardımcısı ona başvuruyor ve yokken sessizce atlıyor: maliyet özetleri, faz izleyicisinin JSON okumaları, konvansiyon çıkarımı, skill imzalama. Kurulum, eksikse bir not basıyor.
+- **`gh`** - GitHub issue ve PR işleri için. Kendi dahili `--jq`'su, `jq` ikilisinden bağımsız.
+
 ## Hızlı Başlangıç
 
 ```bash

package/install/index.mjs

@@ -9,6 +9,7 @@
  */
 
 import { dirname } from "path";
+import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "url";
 
 import { readFileSync } from "fs";
@@ -144,6 +145,17 @@ export function writeVersionMarkers({ home, forClaude, forCopilot, forCodex }) {
  * @param {string[]} flags
  * @returns {"ios"|"android"|"all"}
  */
+// Presence check only - never a hard requirement. The pipeline's own engine is
+// node; jq is a convenience several shell helpers reached for.
+function hasJq() {
+  try {
+    execFileSync("jq", ["--version"], { stdio: "ignore", timeout: 3000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function parsePlatformFlag(flags) {
   const raw = flags.find((f) => f.startsWith("--platform="));
   if (!raw) return "all";
@@ -203,6 +215,19 @@ function printSummary(opts) {
     "    Skipped only when the host CLI is not on PATH - the command to run is printed above.",
   );
   console.log("");
+  // jq is not a declared engine and macOS did not always ship it, yet thirteen
+  // runtime paths guard on it and skip in silence when it is missing. Silence is
+  // the problem: a cost summary that never renders and a tracker that never
+  // updates look like bugs, not like an absent tool. Say it once, here, where
+  // somebody can act on it.
+  if (!hasJq()) {
+    console.log("  Note: jq was not found on PATH.");
+    console.log("    Everything installs and the pipeline runs, but a few shell");
+    console.log("    helpers degrade quietly without it: cost summaries, the phase");
+    console.log("    tracker's JSON reads, convention extraction and skill signing.");
+    console.log("    Install it (brew install jq / apt install jq) to get them back.");
+    console.log("");
+  }
   console.log("  Uninstall everything: npx @mmerterden/multi-agent-pipeline uninstall");
   console.log("  (Personal access tokens in keychain are preserved.)");
   console.log("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "16.9.0",
+  "version": "16.10.1",
   "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/update/SKILL.md

@@ -113,29 +113,34 @@ A git clone of the pipeline repo is a maintainer workspace, kept in sync by `/mu
    self-registration permanently; print the opt-out hint on first auto-enable.
    ```bash
    PREFS="$HOME/.claude/multi-agent-preferences.json"
-   if [ -f "$PREFS" ] && command -v jq >/dev/null 2>&1; then
-     ENABLED=$(jq -r '.global.usageLog.enabled // false' "$PREFS" 2>/dev/null)
-     OPTOUT=$(jq -r '.global.usageLog.optOut // false' "$PREFS" 2>/dev/null)
+   # Reads go through node, not jq. node is a declared engine (>=20.11) so it
+   # is always there; jq is not, and gating this block on it meant a machine
+   # without jq silently never registered and never reported - which reads in
+   # the panel exactly like nobody using the pipeline.
+   if [ -f "$PREFS" ]; then
+     pref() { node -e 'const fs=require("fs");let v;try{v=process.argv[2].split(".").reduce((a,k)=>a?.[k],JSON.parse(fs.readFileSync(process.argv[1],"utf8")))}catch{};process.stdout.write(v==null?"":String(v))' "$PREFS" "$1" 2>/dev/null; }
+     ENABLED=$(pref global.usageLog.enabled)
+     OPTOUT=$(pref global.usageLog.optOut)
      if [ "$ENABLED" != "true" ] && [ "$OPTOUT" != "true" ]; then
        TOK="${MULTI_AGENT_USAGE_TOKEN:-}"
-       [ -z "$TOK" ] && TOK=$(jq -r '.global.usageLog.token // empty' "$PREFS" 2>/dev/null)
+       [ -z "$TOK" ] && TOK=$(pref global.usageLog.token)
        if [ -z "$TOK" ]; then
-         KNAME=$(jq -r '.global.keychainMapping.usage_ingest // empty' "$PREFS" 2>/dev/null)
+         KNAME=$(pref global.keychainMapping.usage_ingest)
          [ -n "$KNAME" ] && TOK=$(bash "$HOME/.claude/lib/credential-store.sh" get "$KNAME" 2>/dev/null)
        fi
        if [ -z "$TOK" ]; then
-         EP=$(jq -r '.global.usageLog.endpoint // "https://mmerterden.vercel.app/api/usage/ingest"' "$PREFS" 2>/dev/null)
+         EP=$(pref global.usageLog.endpoint); [ -z "$EP" ] && EP="https://mmerterden.vercel.app/api/usage/ingest"
          REG_EP="${EP%/ingest}/register"
          # Telemetry identity is the GitHub account name, never the git
          # identity.name (which can carry a corporate title). username -> live
          # gh login -> OS user.
-         RUSER=$(jq -r '.global.identities[0].username // empty' "$PREFS" 2>/dev/null)
+         RUSER=$(pref global.identities.0.username)
          [ -z "$RUSER" ] && RUSER=$(gh api user --jq .login 2>/dev/null || echo "")
          [ -z "$RUSER" ] && RUSER="$USER"
          RESP=$(curl -sSL -m 10 -X POST -H "Content-Type: application/json" \
            --data "{\"u\":\"$RUSER\",\"c\":\"$(hostname -s 2>/dev/null || echo unknown)\"}" \
            "$REG_EP" 2>/dev/null)
-         TOK=$(printf '%s' "$RESP" | jq -r '.token // empty' 2>/dev/null)
+         TOK=$(printf '%s' "$RESP" | node -e 'let b="";process.stdin.on("data",d=>b+=d).on("end",()=>{try{process.stdout.write(String(JSON.parse(b).token||""))}catch{}})' 2>/dev/null)
          if [ -n "$TOK" ]; then
            printf '%s' "$TOK" | bash "$HOME/.claude/lib/credential-store.sh" set "${USER}_Usage_Ingest_Token" "$(cat)"
            node -e 'const fs=require("fs"),p=process.argv[1];const j=JSON.parse(fs.readFileSync(p,"utf8"));j.global=j.global||{};j.global.keychainMapping=j.global.keychainMapping||{};j.global.keychainMapping.usage_ingest=process.argv[2];fs.writeFileSync(p,JSON.stringify(j,null,2)+"\n");' "$PREFS" "${USER}_Usage_Ingest_Token"
@@ -179,7 +184,7 @@ A git clone of the pipeline repo is a maintainer workspace, kept in sync by `/mu
 ```
 Current: v15.6.0   Latest: v15.6.1
   -> npm pack @{npm-scope}/multi-agent-pipeline@15.6.1
-  -> node install.js --all (53 commands, 245 scripts, 208 skills)
+  -> node install.js --all (53 commands, 263 scripts, 210 skills)
   -> migrate-prefs.mjs (0 changes  -  already v2.6.0)
 
 ✓ Updated: v15.6.0 → v15.6.1

package/pipeline/multi-agent-refs/phases/phase-1-analysis.md

@@ -215,7 +215,7 @@ LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 1
   model=opus tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
 ```
 
-Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding-v83` for the canonical contract.
+Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding` for the canonical contract.
 
 #### Prior-Art Enrichment (advisory)
 
@@ -234,12 +234,9 @@ Treat hits as **context only**  -  they are past Phase 4 verdicts, not prescript
 
 ## Token telemetry  -  invoke after every LLM call
 
-After every LLM call in this phase (analysis, plan generation, code/diff write, review verdict, triage), invoke:
-
 ```bash
 bash $HOME/.claude/scripts/phase-tracker.sh tokens 1 <input_count> <output_count>
 ```
 
-The tracker accumulates the totals additively, so multiple calls in the same phase compound. The render output then shows live cost on the active phase tile (e.g. `Phase 1  Dev   2m 14s · 12.4k tok`). This satisfies the contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` and the `smoke-tracker-tokens-invocation.sh` enforcement gate. Skipping this call is the #1 cause of "I can't see how much it cost" complaints.
+Contract and rationale: `progress-contract.md` -> Token telemetry forwarding.
 
-If you do not have access to the model's reported token counts, pass best-effort estimates derived from input length / output length  -  partial cost data is better than none.

package/pipeline/multi-agent-refs/phases/phase-2-planning.md

@@ -327,18 +327,15 @@ LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 2
   model=opus tokens_in=$IN tokens_out=$OUT duration_ms=$DUR iteration=$N
 ```
 
-Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding-v83`.
+Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding`.
 
 ---
 
 ## Token telemetry  -  invoke after every LLM call
 
-After every LLM call in this phase (analysis, plan generation, code/diff write, review verdict, triage), invoke:
-
 ```bash
 bash $HOME/.claude/scripts/phase-tracker.sh tokens 2 <input_count> <output_count>
 ```
 
-The tracker accumulates the totals additively, so multiple calls in the same phase compound. The render output then shows live cost on the active phase tile (e.g. `Phase 2  Dev   2m 14s · 12.4k tok`). This satisfies the contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` and the `smoke-tracker-tokens-invocation.sh` enforcement gate. Skipping this call is the #1 cause of "I can't see how much it cost" complaints.
+Contract and rationale: `progress-contract.md` -> Token telemetry forwarding.
 
-If you do not have access to the model's reported token counts, pass best-effort estimates derived from input length / output length  -  partial cost data is better than none.

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

@@ -345,21 +345,17 @@ LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 3
   tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
 ```
 
-Model resolves from the active mode: a Full run uses Sonnet, a Short run uses Opus. Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding-v83`.
+Model resolves from the active mode: a Full run uses Sonnet, a Short run uses Opus. Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding`.
 
 ---
 
 ## Token telemetry  -  invoke after every LLM call
 
-After every LLM call in this phase (analysis, plan generation, code/diff write, review verdict, triage), invoke:
-
 ```bash
 bash $HOME/.claude/scripts/phase-tracker.sh tokens 3 <input_count> <output_count>
 ```
 
-The tracker accumulates the totals additively, so multiple calls in the same phase compound. The render output then shows live cost on the active phase tile (e.g. `Phase 3  Dev   2m 14s · 12.4k tok`). This satisfies the contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` and the `smoke-tracker-tokens-invocation.sh` enforcement gate. Skipping this call is the #1 cause of "I can't see how much it cost" complaints.
-
-If you do not have access to the model's reported token counts, pass best-effort estimates derived from input length / output length  -  partial cost data is better than none.
+Contract and rationale: `progress-contract.md` -> Token telemetry forwarding.
 
 
 #### Generated trees are not yours to edit

package/pipeline/multi-agent-refs/phases/phase-4-review.md

@@ -565,7 +565,7 @@ bash "$M" "$TASK_ID" 4 review.completed raw_count=$RAW accepted=$ACC \
   deferred=$DEF rejected=$REJ approved=$APPROVED duration_ms=$DURATION
 ```
 
-`LOG_METRIC_FORWARD_TO_TRACKER=1` mirrors `tokens_in`/`tokens_out`/`model` into `phase-tracker.sh` (see `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding-v83`). On non-zero validator exit (1/2/3), also emit `triage.edge_case` with cause. Omit `tokens_in`/`tokens_out` if unavailable. Best-effort  -  never fails the pipeline.
+`LOG_METRIC_FORWARD_TO_TRACKER=1` mirrors `tokens_in`/`tokens_out`/`model` into `phase-tracker.sh` (see `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding`). On non-zero validator exit (1/2/3), also emit `triage.edge_case` with cause. Omit `tokens_in`/`tokens_out` if unavailable. Best-effort  -  never fails the pipeline.
 
 ##### 3.5 Optional cross-check (single-point-of-failure mitigation)
 
@@ -630,12 +630,11 @@ Log: "Phase 4: Review  -  raw={N1+N2} accepted={Na} deferred={Nd} rejected={Nr}
 
 ## Token telemetry  -  invoke after every LLM call
 
-After every LLM call in this phase (analysis, plan generation, code/diff write, review verdict, triage), invoke:
-
 ```bash
 bash $HOME/.claude/scripts/phase-tracker.sh tokens 4 <input_count> <output_count> [cached_count]
 ```
 
 The optional 4th `cached_count` is the prompt-cache-read token count when the host reports it (Anthropic `cache_read_input_tokens`); it defaults to 0 and is priced at the cheaper `cacheReadPerMtok` rate in the Phase 7 cost ledger. The tracker accumulates the totals additively, so multiple calls in the same phase compound. The render output then shows live cost on the active phase tile (e.g. `Phase 4  Dev   2m 14s · 12.4k tok`). This satisfies the contract in `$HOME/.claude/multi-agent-refs/tracker-contract.md` and the `smoke-tracker-tokens-invocation.sh` enforcement gate. Skipping this call is the #1 cause of "I can't see how much it cost" complaints.
 
-If you do not have access to the model's reported token counts, pass best-effort estimates derived from input length / output length  -  partial cost data is better than none.
+Contract and rationale: `progress-contract.md` -> Token telemetry forwarding.
+

package/pipeline/multi-agent-refs/phases/phase-5-test.md

@@ -158,4 +158,4 @@ LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 5
   model=opus tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
 ```
 
-If Phase 5 is purely user-driven (no sub-agent ran), no token forwarding is required and the cost block stays empty for this phase. Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding-v83`.
+If Phase 5 is purely user-driven (no sub-agent ran), no token forwarding is required and the cost block stays empty for this phase. Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding`.

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

@@ -345,4 +345,4 @@ LOG_METRIC_FORWARD_TO_TRACKER=1 $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 6
   model=<sonnet|opus> tokens_in=$IN tokens_out=$OUT duration_ms=$DUR
 ```
 
-Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding-v83`.
+Best-effort. See `$HOME/.claude/multi-agent-refs/progress-contract.md#token-telemetry-forwarding`.

package/pipeline/scripts/write-state.mjs

@@ -100,12 +100,26 @@ async function acquireLock(
         /* already gone */
       }
       if (err.code !== "EEXIST") throw err;
-      if (isLockStale(lockPath, staleMs)) {
-        // Holder crashed or the lock outlived any plausible writer  -  reclaim it.
+      // Reclaim by identity, never by path. Between judging a lock stale and
+      // deleting it, the holder can release and a THIRD writer can acquire a
+      // fresh one - and an unlink by path deletes that live lock, after which
+      // two writers hold it and one update is lost. Same failure the PID window
+      // above once caused, at a different point in the loop; it survived because
+      // it only reproduces under load, where the gap is wide enough to lose.
+      //
+      // The inode is the identity: a newly acquired lock is a different file
+      // even at the same path. Delete only if the file we judged is still the
+      // file that is there.
+      const stale = lockIdentityIfStale(lockPath, staleMs);
+      if (stale) {
         try {
-          unlinkSync(lockPath);
+          const now = statSync(lockPath);
+          if (now.ino === stale.ino && now.mtimeMs === stale.mtimeMs) {
+            unlinkSync(lockPath);
+          }
+          // Changed under us: somebody else's live lock. Leave it and retry.
         } catch {
-          /* another writer won the race  -  fall through and retry */
+          /* vanished on its own  -  fall through and retry */
         }
         continue;
       }
@@ -128,28 +142,32 @@ async function acquireLock(
  * @param {number} staleMs
  * @returns {boolean}
  */
-function isLockStale(lockPath, staleMs) {
+function lockIdentityIfStale(lockPath, staleMs) {
   let pid;
   let mtimeMs;
+  let ino;
   try {
     pid = parseInt(readFileSync(lockPath, "utf-8").trim(), 10);
-    mtimeMs = statSync(lockPath).mtimeMs;
+    const st = statSync(lockPath);
+    mtimeMs = st.mtimeMs;
+    ino = st.ino;
   } catch {
     // Lock vanished between EEXIST and our read  -  let the retry re-open it.
-    return false;
+    return null;
   }
-  if (Date.now() - mtimeMs > staleMs) return true;
+  const identity = { ino, mtimeMs };
+  if (Date.now() - mtimeMs > staleMs) return identity;
   // An unreadable PID is NOT proof of staleness. Treating it as such is what
   // let a writer delete a live lock and lose another writer's update. With the
   // link-based acquire above a lock is never observable without its PID, so
   // this can only be genuine corruption - which the staleMs check reclaims
   // anyway, without racing a writer that is merely mid-flight.
-  if (!Number.isInteger(pid) || pid <= 0) return false;
+  if (!Number.isInteger(pid) || pid <= 0) return null;
   try {
     process.kill(pid, 0); // probe liveness without signalling
-    return false; // holder alive
+    return null; // holder alive
   } catch (err) {
-    return err.code === "ESRCH"; // no such process  -  stale
+    return err.code === "ESRCH" ? identity : null; // no such process  -  stale
   }
 }
 

package/pipeline/skills/.skills-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "skillCount": 208,
+  "skillCount": 210,
   "entries": [
     {
       "name": "accessibility-compliance-accessibility-audit",
@@ -961,7 +961,7 @@
     },
     {
       "name": "multi-agent-analysis",
-      "description": "Standalone feature-spec analysis (v3 template). Platform-agnostic concept layer with repo-driven convention extraction and per-platform Pass B render. 23 sections in Full mode; 8 of them in Lite mode (auto for small features). Collects Figma / Swagger / Confluence / Jira / Standards / Firebase / rep",
+      "description": "Standalone feature-spec analysis. Two profiles picked at intake: global (23-section development handoff, 8 of them in Lite mode) or corporate (IG/UC/FG requirements document with traceability matrices). Platform-agnostic concept layer with repo-driven convention extraction and per-platform Pass B re",
       "platform": null,
       "group": "core",
       "plugin": null,
@@ -1102,6 +1102,17 @@
       "triggerPaths": [],
       "relativePath": "shared/core/multi-agent-diff-explain/SKILL.md"
     },
+    {
+      "name": "multi-agent-feedback",
+      "description": "Send one message to the maintainer: a bug, an idea or a question. Only the text you type is sent - no logs, no repo names, no paths. Shows the payload and asks before sending. Use when a run went wrong and the maintainer should know.",
+      "platform": null,
+      "group": "core",
+      "plugin": null,
+      "invokeAs": "multi-agent-feedback",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/core/multi-agent-feedback/SKILL.md"
+    },
     {
       "name": "multi-agent-forget",
       "description": "Remove a saved /multi-agent routine (created by /multi-agent:save): deletes its local-only command and its registry entry. Asks which one and confirms. Use when a saved routine is no longer wanted and should be removed.",
@@ -1311,6 +1322,17 @@
       "triggerPaths": [],
       "relativePath": "shared/core/multi-agent-review/SKILL.md"
     },
+    {
+      "name": "multi-agent-review-analysis",
+      "description": "Review a written analysis document instead of a diff: resolve it from a path, a Confluence page or a Jira issue, run the deterministic gates first, then a parallel model review. Findings cite the Locked rule they break. Never edits the document. Use when an analysis needs judging before development ",
+      "platform": null,
+      "group": "core",
+      "plugin": null,
+      "invokeAs": "multi-agent-review-analysis",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/core/multi-agent-review-analysis/SKILL.md"
+    },
     {
       "name": "multi-agent-review-issue",
       "description": "Assess whether a GitHub issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack readiness, then (after confirm) post the gaps as an issue comment. Read-only on code. Use when deciding whether a GitHub issue is specified well enough to ha",

package/pipeline/skills/shared/README.md

@@ -2,11 +2,11 @@
 
 Single source of truth for skills delivered to both Claude Code (`~/.claude/skills/`) and Copilot CLI (`~/.copilot/skills/`) by the installer.
 
-**Total:** 208 skills (54 core + 154 external). Auto-generated by `scripts/gen-skills-index.mjs`  -  do not edit by hand.
+**Total:** 210 skills (56 core + 154 external). Auto-generated by `scripts/gen-skills-index.mjs`  -  do not edit by hand.
 
 ## Directory layout
 
-- **`core/`**  -  54 `multi-agent*` orchestration skills that are pipeline-critical. Edits here are core-code changes.
+- **`core/`**  -  56 `multi-agent*` orchestration skills that are pipeline-critical. Edits here are core-code changes.
 - **`external/`**  -  154 iOS / Android / generic skills imported from the upstream skill library. Mirrors of third-party guidance.
 - Install destinations (ADR-0009): Claude Code gets NO local copy of `external/` - it loads those skills from the `multi-agent-plugins` marketplace, namespaced (`ai-<stack>-toolkit:<name>`); only the two compliance catalogs from `core/` land in `~/.claude/skills/`. Copilot CLI and Codex CLI receive a flat copy filtered to the enabled stacks. `external/` remains the single authoring source that `build-stack-plugins.mjs` publishes from.
 
@@ -14,7 +14,7 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 
 ## Categories
 
-- [Pipeline Orchestration](#pipeline-orchestration)  -  54
+- [Pipeline Orchestration](#pipeline-orchestration)  -  56
 - [iOS / Apple Ecosystem](#ios-apple-ecosystem)  -  90
 - [Android / Kotlin](#android-kotlin)  -  13
 - [Web / Frontend](#web-frontend)  -  10
@@ -28,7 +28,7 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 | [`apple-archive-compliance`](./core/apple-archive-compliance/) | `core` | Apple App Store Review compliance  -  wraps the multi-agent-toolkit-mcp `ios_app_store_audit` tool (18-rule deep scan) with ITMS error code  |
 | [`google-play-compliance`](./core/google-play-compliance/) | `core` | Google Play Store publication compliance  -  bundletool + aapt2 + apksigner orchestration + 21-rule policy catalog with Play Console error c |
 | [`multi-agent`](./core/multi-agent/) | `core` | Task orchestrator: runs the full pipeline from a Jira ID or GitHub Issue URL  -  analysis → plan → TDD development → parallel review (Fable  |
-| [`multi-agent-analysis`](./core/multi-agent-analysis/) | `core` | Standalone feature-spec analysis (v3 template). Platform-agnostic concept layer with repo-driven convention extraction and per-platform Pass |
+| [`multi-agent-analysis`](./core/multi-agent-analysis/) | `core` | Standalone feature-spec analysis. Two profiles picked at intake: global (23-section development handoff, 8 of them in Lite mode) or corporat |
 | [`multi-agent-analysis-resolve`](./core/multi-agent-analysis-resolve/) | `core` | Resolve the Section 20 Risks and Open Questions of an analysis v3 document one row at a time: up to 3 source-labeled answer candidates per r |
 | [`multi-agent-autopilot`](./core/multi-agent-autopilot/) | `core` | Launch any task in autopilot mode: skips every confirmation, runs end-to-end autonomously. Use when a task should run end to end with no con |
 | [`multi-agent-build-optimize`](./core/multi-agent-build-optimize/) | `core` | Wrapper that dispatches to xcode-build-orchestrator on iOS repos. Benchmarks the current Xcode build, runs compilation / project / SPM analy |
@@ -41,6 +41,7 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 | [`multi-agent-dev-local`](./core/multi-agent-dev-local/) | `core` | Removed in v16.0.0. Its worktree-free twin is /multi-agent:local, which asks the same depth question; answer Short there. Invoke only to see |
 | [`multi-agent-dev-local-autopilot`](./core/multi-agent-dev-local-autopilot/) | `core` | Retired alongside its worktree twin in v16.0.0, with nothing standing in for it. Invoke only to be pointed at /multi-agent:local-autopilot o |
 | [`multi-agent-diff-explain`](./core/multi-agent-diff-explain/) | `core` | Map Phase 4 triage findings to branch diff lines. Read-only post-hoc command, used after review to answer 'which finding lines up with which |
+| [`multi-agent-feedback`](./core/multi-agent-feedback/) | `core` | Send one message to the maintainer: a bug, an idea or a question. Only the text you type is sent - no logs, no repo names, no paths. Shows t |
 | [`multi-agent-forget`](./core/multi-agent-forget/) | `core` | Remove a saved /multi-agent routine (created by /multi-agent:save): deletes its local-only command and its registry entry. Asks which one an |
 | [`multi-agent-garbage-collect`](./core/multi-agent-garbage-collect/) | `core` | Sweep leftover /tmp scratch (picker state, review diffs, channel payloads, analysis drafts) from past runs. Dry-run first; confirms before d |
 | [`multi-agent-help`](./core/multi-agent-help/) | `core` | Multi-agent pipeline usage guide  -  renders in EN or TR per prefs.global.outputLanguage (falls back to promptLanguage for backward compatib |
@@ -60,6 +61,7 @@ Source layout is logical grouping only  -  skill discovery at runtime is unchang
 | [`multi-agent-resume`](./core/multi-agent-resume/) | `core` | Resume a stopped or failed task from the phase where it left off. Use when a task stopped or failed and should carry on from where it left o |
 | [`multi-agent-resume-local`](./core/multi-agent-resume-local/) | `core` | Continue already-done LOCAL work through the pipeline tail: Review → Build+Test → Commit/PR → Report (technical analysis + Jira test-scenari |
 | [`multi-agent-review`](./core/multi-agent-review/) | `core` | Run parallel review on a branch diff or a Pull Request: 2 models on Claude Code (Fable + Sonnet), 3 models on Copilot CLI (GPT + Opus + Sonn |
+| [`multi-agent-review-analysis`](./core/multi-agent-review-analysis/) | `core` | Review a written analysis document instead of a diff: resolve it from a path, a Confluence page or a Jira issue, run the deterministic gates |
 | [`multi-agent-review-issue`](./core/multi-agent-review-issue/) | `core` | Assess whether a GitHub issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / sta |
 | [`multi-agent-review-jira`](./core/multi-agent-review-jira/) | `core` | Assess whether a Jira issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack |
 | [`multi-agent-routines`](./core/multi-agent-routines/) | `core` | List your saved /multi-agent routines (from /multi-agent:save) with what each one does, rendered in outputLanguage. Use when asked which sav |

package/pipeline/skills/skills-index.md

@@ -3,7 +3,7 @@
 > Auto-generated by `pipeline/scripts/build-skills-index.mjs`  -  do not hand-edit.
 > Regenerate with `node pipeline/scripts/build-skills-index.mjs`.
 
-**208 skills** across 2 groups.
+**210 skills** across 2 groups.
 
 | Group | Name | Platform | Description |
 |-------|------|----------|-------------|
@@ -94,7 +94,7 @@
 | external | `metrickit-diagnostics` |  -  | Collect and analyze on-device performance metrics and crash diagnostics using MetricKit. Use when setting up MXMetricManager, handling MXMet |
 | external | `monorepo-architect` |  -  | Expert in monorepo architecture, build systems, and dependency management at scale. Masters Nx, Turborepo, Bazel, and Lerna for efficient mu |
 | core | `multi-agent` |  -  | Task orchestrator: runs the full pipeline from a Jira ID or GitHub Issue URL  -  analysis → plan → TDD development → parallel review (Fable  |
-| core | `multi-agent-analysis` |  -  | Standalone feature-spec analysis (v3 template). Platform-agnostic concept layer with repo-driven convention extraction and per-platform Pass |
+| core | `multi-agent-analysis` |  -  | Standalone feature-spec analysis. Two profiles picked at intake: global (23-section development handoff, 8 of them in Lite mode) or corporat |
 | core | `multi-agent-analysis-resolve` |  -  | Resolve the Section 20 Risks and Open Questions of an analysis v3 document one row at a time: up to 3 source-labeled answer candidates per r |
 | core | `multi-agent-autopilot` |  -  | Launch any task in autopilot mode: skips every confirmation, runs end-to-end autonomously. Use when a task should run end to end with no con |
 | core | `multi-agent-build-optimize` |  -  | Wrapper that dispatches to xcode-build-orchestrator on iOS repos. Benchmarks the current Xcode build, runs compilation / project / SPM analy |
@@ -107,6 +107,7 @@
 | core | `multi-agent-dev-local` |  -  | Removed in v16.0.0. Its worktree-free twin is /multi-agent:local, which asks the same depth question; answer Short there. Invoke only to see |
 | core | `multi-agent-dev-local-autopilot` |  -  | Retired alongside its worktree twin in v16.0.0, with nothing standing in for it. Invoke only to be pointed at /multi-agent:local-autopilot o |
 | core | `multi-agent-diff-explain` |  -  | Map Phase 4 triage findings to branch diff lines. Read-only post-hoc command, used after review to answer 'which finding lines up with which |
+| core | `multi-agent-feedback` |  -  | Send one message to the maintainer: a bug, an idea or a question. Only the text you type is sent - no logs, no repo names, no paths. Shows t |
 | core | `multi-agent-forget` |  -  | Remove a saved /multi-agent routine (created by /multi-agent:save): deletes its local-only command and its registry entry. Asks which one an |
 | core | `multi-agent-garbage-collect` |  -  | Sweep leftover /tmp scratch (picker state, review diffs, channel payloads, analysis drafts) from past runs. Dry-run first; confirms before d |
 | core | `multi-agent-help` |  -  | Multi-agent pipeline usage guide  -  renders in EN or TR per prefs.global.outputLanguage (falls back to promptLanguage for backward compatib |
@@ -126,6 +127,7 @@
 | core | `multi-agent-resume` |  -  | Resume a stopped or failed task from the phase where it left off. Use when a task stopped or failed and should carry on from where it left o |
 | core | `multi-agent-resume-local` |  -  | Continue already-done LOCAL work through the pipeline tail: Review → Build+Test → Commit/PR → Report (technical analysis + Jira test-scenari |
 | core | `multi-agent-review` |  -  | Run parallel review on a branch diff or a Pull Request: 2 models on Claude Code (Fable + Sonnet), 3 models on Copilot CLI (GPT + Opus + Sonn |
+| core | `multi-agent-review-analysis` |  -  | Review a written analysis document instead of a diff: resolve it from a path, a Confluence page or a Jira issue, run the deterministic gates |
 | core | `multi-agent-review-issue` |  -  | Assess whether a GitHub issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / sta |
 | core | `multi-agent-review-jira` |  -  | Assess whether a Jira issue is ready for multi-agent development: fetch it, grade scope / acceptance criteria / repro / design / API / stack |
 | core | `multi-agent-routines` |  -  | List your saved /multi-agent routines (from /multi-agent:save) with what each one does, rendered in outputLanguage. Use when asked which sav |