@mmerterden/multi-agent-pipeline 16.9.0 → 16.10.0

package/CHANGELOG.md

@@ -26,6 +26,23 @@ 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.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.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/commands/multi-agent/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"

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`.