@mmerterden/multi-agent-pipeline 15.0.0 → 15.2.0

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

@@ -71,6 +71,33 @@ Update the pipeline in one command. Existing preferences are preserved; only ski
    fi
    ```
 
+5b. **Auto-enable usage logging when a token is already onboarded.** The private
+   usage dashboard is opt-in and off by default. This step flips it ON only when a
+   token can be resolved - it NEVER fabricates a secret or ships one, so a machine
+   that was never given the token stays silent. Resolution order: env
+   `MULTI_AGENT_USAGE_TOKEN`, then `usageLog.token`, then the Keychain item named by
+   `keychainMapping.usage_ingest`. Endpoint is left to the emitter's default.
+   ```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)
+     if [ "$ENABLED" != "true" ]; then
+       TOK="${MULTI_AGENT_USAGE_TOKEN:-}"
+       [ -z "$TOK" ] && TOK=$(jq -r '.global.usageLog.token // empty' "$PREFS" 2>/dev/null)
+       if [ -z "$TOK" ]; then
+         KNAME=$(jq -r '.global.keychainMapping.usage_ingest // empty' "$PREFS" 2>/dev/null)
+         [ -n "$KNAME" ] && TOK=$(bash "$HOME/.claude/lib/credential-store.sh" get "$KNAME" 2>/dev/null)
+       fi
+       if [ -n "$TOK" ]; then
+         node -e 'const fs=require("fs"),p=process.argv[1];const j=JSON.parse(fs.readFileSync(p,"utf8"));j.global=j.global||{};j.global.usageLog=j.global.usageLog||{};j.global.usageLog.enabled=true;fs.writeFileSync(p,JSON.stringify(j,null,2)+"\n");' "$PREFS"
+         echo "  -> usage logging activated (ingest token found)"
+       else
+         echo "  -> usage logging left off (no ingest token onboarded)"
+       fi
+     fi
+   fi
+   ```
+
 6. **Show the new version**:
    ```bash
    NEW_VERSION=$(node -p "require('$PIPE_DIR/package.json').version" 2>/dev/null || echo "unknown")
@@ -99,12 +126,12 @@ Update the pipeline in one command. Existing preferences are preserved; only ski
 ## Output
 
 ```
-Current: v3.6.0
+Current: v14.2.2
   -> git pull origin main
-  -> node install.js --all (50 commands, 80 scripts, 203 skills)
-  -> migrate-prefs.mjs (0 changes  -  already v2.1.0)
+  -> node install.js --all (51 commands, 228 scripts, 205 skills)
+  -> migrate-prefs.mjs (0 changes  -  already v2.6.0)
 
-✓ Updated: v3.6.0 → v3.7.0
+✓ Updated: v14.2.2 → v15.0.0
 
 Changes:
   e3f883e fix(dev): Phase 6 must show local test prompt

package/pipeline/lib/parse-complaints.sh

@@ -64,9 +64,13 @@ REDACT="true"
 
 while [ $# -gt 0 ]; do
   case "$1" in
-    --file)      FILE="$2"; shift 2 ;;
+    --file)
+      [ $# -ge 2 ] || { echo "ERR: --file needs a value" >&2; exit 4; }
+      FILE="$2"; shift 2 ;;
     --stdin)     USE_STDIN="true"; shift ;;
-    --format)    FORMAT="$2"; shift 2 ;;
+    --format)
+      [ $# -ge 2 ] || { echo "ERR: --format needs a value" >&2; exit 4; }
+      FORMAT="$2"; shift 2 ;;
     --no-redact) REDACT="false"; shift ;;
     -h|--help)
       echo "usage: $0 --file <path> [--format csv|xlsx|txt|json|auto] [--no-redact] | --stdin [--format text]" >&2
@@ -150,6 +154,12 @@ REDACTIONS = [
     (re.compile(r"\b\d{11}\b"), "[REDACTED:national-id]"),
     (re.compile(r"(?<![\w.-])\+?\d(?:[ ()-]?\d){8,14}\b"), "[REDACTED:phone]"),
     (re.compile(r"\b(?=[A-Z0-9]{6}\b)(?=[A-Z0-9]*[A-Z])(?=[A-Z0-9]*\d)[A-Z0-9]{6}\b"), "[REDACTED:pnr]"),
+    # All-letter PNRs exist too, but a bare 6-letter uppercase word is far too
+    # common to redact blind - only take one that follows a PNR-ish keyword.
+    (
+        re.compile(r"\b(?P<kw>pnr|rezervasyon kodu|booking (?:ref|reference|code))(?P<sep>[^A-Za-z0-9\n]{0,3})[A-Z]{6}\b", re.IGNORECASE),
+        lambda m: m.group("kw") + m.group("sep") + "[REDACTED:pnr]",
+    ),
 ]
 
 def redact(text):

package/pipeline/multi-agent-refs/complaint-analysis-template.md

@@ -44,7 +44,7 @@ Then the coverage table - every selected repo appears, including the ones that c
 
 ## 2. Triage Tablosu / Triage Table
 
-One row per complaint. Verdict tokens are the English enum: `client:ios`, `client:android`, `client:web`, `bff:mobile-bff`, `bff:web-bff`, `core`, `insufficient-evidence`. The validator requires every row carrying a `C-NN` id to contain one of these tokens.
+One row per complaint. Verdict tokens are the English enum: `client:ios`, `client:android`, `client:web`, `bff:mobile-bff`, `bff:web-bff`, `core`, `insufficient-evidence`. The validator requires every row in this section whose FIRST cell is a `C-NN` id to carry one of these tokens in a cell of its own (cell-exact; the Section 1 coverage table citing ids in its last column is exempt by scope).
 
 ```
 | Id | Özet (redakte) | trx/conv | Verdict | Confidence | Routing |

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

@@ -95,7 +95,13 @@ halt per the halt-visibility rule), `3` I/O error.
 Reads need no wrapper; the rename makes any read see either the old or the new
 document, never a truncated one.
 
-**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>`. Autopilot suppresses *confirmations*, not *halts*  -  the user must always be able to see why an unattended run stopped without reading the log.
+**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 usage ping so a run that never reaches Phase 7 is still recorded with the phase it stopped at (`state.currentPhase` + `haltReason`) - the emitter no-ops when logging is off or unconfigured:
+
+```bash
+node $HOME/.claude/scripts/usage-report.mjs --state "$STATE_FILE" >/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 dashboard upserts by run id, so this halt event and a later Phase 7 event (after resume) collapse into one record.
 
 ### Pipeline Best Practices
 

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

@@ -196,6 +196,12 @@ $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 7 task.completed \
   duration_ms=$TOTAL_DURATION
 ```
 
+**Usage ping (optional, private dashboard).** When `prefs.global.usageLog.enabled` is true, emit one end-of-run activity event to the configured private dashboard. One POST per run (never per phase), fire-and-forget, activity metadata only  -  who, command, mode, input type, repo, phase reached, outcome, halt cause, review-iteration count, duration, token spend, cost, version. No prompts, code, diffs, or absolute paths. The script no-ops when `usageLog.enabled` is not true or no ingest token resolves, so the call is unconditional and never blocks the run.
+
+```bash
+node $HOME/.claude/scripts/usage-report.mjs --state "$STATE_FILE" >/dev/null 2>&1 || true
+```
+
 **Aggregate before reporting**: run `aggregate-metrics.mjs --since=$(date -u -v-30d +%Y-%m-%d)` and embed output in agent-log.md. Use `--json` for Jira. Aggregator handles missing files gracefully.
 
 **Per-run outcome metrics (evidence corpus):** also emit `run-metrics.mjs --state <agent-state.json>` and append/persist its JSON. It records the numbers that actually answer "did this run go well" - review iterations (rework loops), first-pass-clean, reviewer signal-to-noise (accepted / raw findings), consensus verdict, build outcome. Accumulating these across real runs is the real-world validation that golden tasks + benchmarks only approximate; keep the corpus so the pipeline's quality can be measured, not asserted.

package/pipeline/multi-agent-refs/tracker-contract.md

@@ -135,7 +135,8 @@ Mode-specific phase sets:
 
 | Mode | TaskCreate set (in order) |
 |---|---|
-| Full pipeline (`/multi-agent`, `:autopilot`, `:local`, `:local-autopilot`) | 0 → 1 → 2 → 3 → 4 → 5 → 6 → 7 (all 8) |
+| Full interactive (`/multi-agent`) | 0 → 1 → 2 → 3 → 4 → 5 → 6 → 7 (all 8) |
+| `:autopilot`, `:local`, `:local-autopilot` | 0 → 1 → 2 → 3 → 4 → 6 → 7 (7 phases  -  the interactive Phase 5 test gate is dropped in every autopilot/local variant) |
 | `:dev` | 0 → 3 → 4 → 5 → 6 → 7 (6 phases  -  1/2 omitted entirely) |
 | `:dev-autopilot`, `:dev-local`, `:dev-local-autopilot` | 0 → 3 → 4 → 6 → 7 (5 phases  -  1/2/5 omitted entirely; the autopilot/local variants drop the interactive Phase 5 test gate) |
 

package/pipeline/preferences-template.json

@@ -12,6 +12,7 @@
       "figma_mcp": null,
       "fortify": null,
       "graylog": null,
+      "usage_ingest": null,
       "firebase": null,
       "jenkins": null
     },
@@ -74,6 +75,11 @@
       "onExceed": "warn",
       "pricingModel": "opus"
     },
+    "usageLog": {
+      "enabled": false,
+      "endpoint": "https://mmerterden.vercel.app/api/usage/ingest",
+      "token": ""
+    },
     "derivedSkillSources": [],
     "devToolkit": {
       "enabled": true,

package/pipeline/schemas/prefs.schema.json

@@ -188,6 +188,13 @@
                 "null"
               ]
             },
+            "usage_ingest": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "Keychain item holding the shared ingest token for the private usage dashboard. When set, usage-report.mjs reads the token from here (never from a synced file), and /multi-agent:update auto-enables usageLog once the token is onboarded. Absent = usage logging stays off."
+            },
             "figma_pat": {
               "type": [
                 "string",
@@ -1077,6 +1084,26 @@
             }
           }
         },
+        "usageLog": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Optional end-of-run usage ping to a private dashboard. When enabled, Phase 7 emits ONE activity event per run (never per phase) via pipeline/scripts/usage-report.mjs: who, command, mode, input type, repo, phase reached, outcome, halt cause, review-iteration count, duration, token spend, cost, version. Never prompts, code, diffs, or absolute paths. Off by default; the emitter no-ops unless enabled is true AND a token resolves (from token below or env MULTI_AGENT_USAGE_TOKEN), so it is inert for anyone who has not configured it.",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": false,
+              "description": "Master switch. When false the emitter exits silently and nothing leaves the machine."
+            },
+            "endpoint": {
+              "type": "string",
+              "description": "Ingest URL that receives the activity event. The token is sent in the X-Usage-Token header."
+            },
+            "token": {
+              "type": "string",
+              "description": "Shared ingest token the receiving endpoint validates. May be left empty here and supplied via env MULTI_AGENT_USAGE_TOKEN instead. Local prefs only, never synced."
+            }
+          }
+        },
         "reviewWatch": {
           "type": "object",
           "additionalProperties": false,

package/pipeline/scripts/README.md

@@ -82,13 +82,14 @@ Shell scripts invoked during pipeline execution.
 - `github-ssh-setup.sh`  -  first-run SSH key setup helper
 - `sync-parity-check.sh`  -  manual parity verification helper
 
-## Node.js helpers (45 `.mjs` files)
+## Node.js helpers (54 `.mjs` files)
 
 - `aggregate-metrics.mjs`  -  collects telemetry aggregates
 - `learning-curve.mjs`  -  time-bucketed trend over `metrics.jsonl` (first-pass clean rate, review cycles, rework/task, tokens/task, cache ratio); `--bucket`, `--since`, `--json`, `--markdown`
-- `eval-triage.mjs`  -  runs the 10 triage eval fixtures
+- `eval-triage.mjs`  -  runs the 11 triage eval fixtures
+- `eval-mine-corpus.mjs`  -  manual maintainer CLI: mines `~/.claude/memory/multi-agent/<repo-slug>/triage-corpus.jsonl` from real runs into new triage eval fixtures (dev-only, excluded from the npm package; not part of `npm test`)
 - `gen-skills-index.mjs`  -  regenerates `pipeline/skills/shared/README.md` skill catalog
-- `migrate-prefs.mjs`  -  preference migration driver (v2.0.0 through v2.4.0)
+- `migrate-prefs.mjs`  -  preference migration driver (v2.0.0 through v2.6.0)
 - `migrate-state.mjs`  -  generic migration runner (reads `schemas/migrations/`)
 - `token-budget-report.mjs`  -  per-phase token usage report
 - `validate-analysis.mjs`, `validate-planning.mjs`, `validate-reviewer.mjs`, `validate-triage.mjs`  -  per-phase output validators

package/pipeline/scripts/check-derived-drift.mjs

@@ -179,8 +179,11 @@ for (const entry of entries) {
   // An acknowledged drift is a conscious "port pending" decision, pinned to the
   // upstream version it was made against: it stays visible but does not fail
   // the gate, and the moment upstream moves past the pin it is plain drift
-  // again.
-  const acknowledged = drifted && entry.driftAcknowledged === resolved.version;
+  // again. The pin only counts against an AUTHORITATIVE resolution - a cache
+  // that happens to hold the pinned version proves nothing about upstream and
+  // must not silence the unverified state.
+  const acknowledged =
+    drifted && resolved.authoritative && entry.driftAcknowledged === resolved.version;
   const status = acknowledged
     ? "drift (acknowledged)"
     : drifted

package/pipeline/scripts/match-skills.mjs

@@ -52,6 +52,10 @@ function defaultIndexCandidates() {
   const repoRoot = resolve(here, "..", ".."); // <repo> when here is <repo>/pipeline/scripts
   return [
     join(installRoot, "skills", ".skills-index.json"),
+    // Codex CLI keeps skills under multi-agent-refs/skills (install/codex.mjs
+    // writes the index there); without this candidate every dynamic-skill
+    // dispatch on Codex exited 1 with "cannot read index".
+    join(installRoot, "multi-agent-refs", "skills", ".skills-index.json"),
     join(repoRoot, "pipeline", "skills", ".skills-index.json"),
   ];
 }

package/pipeline/scripts/migrate-prefs.mjs

@@ -94,7 +94,11 @@ function readMigratableVersions(target) {
   }
   // Schema unreadable: refusing to migrate would be worse than migrating from a
   // version this build cannot enumerate, so fall back to the known history.
-  return new Set(["2.0.0", "2.1.0", "2.2.0", "2.3.0", "2.4.0"]);
+  // Every released schemaVersion below TARGET_VERSION belongs here - the
+  // 2.4.0->2.5.0 and 2.5.0->2.6.0 bumps both shipped without extending it,
+  // which made a schema-less install throw "unknown schemaVersion" on a prefs
+  // file one version behind.
+  return new Set(["2.0.0", "2.1.0", "2.2.0", "2.3.0", "2.4.0", "2.5.0"]);
 }
 
 function defaultKeychainMapping() {

package/pipeline/scripts/phase-tracker.sh

@@ -115,6 +115,23 @@ need_jq() {
   }
 }
 
+# Live usage ping (best-effort). Emits one per-phase update to the private
+# dashboard via usage-report.mjs, always status=running so per-phase updates
+# never fold the run into rollup counters - the terminal fold comes only from
+# the Phase 7 / halt emit that reads the real run status. The emitter no-ops
+# unless prefs.global.usageLog.enabled; detached so it never blocks a boundary.
+usage_live_ping() {
+  local task="$1" phase="$2"
+  local script="$HOME/.claude/scripts/usage-report.mjs"
+  local prefs="$HOME/.claude/multi-agent-preferences.json"
+  [ -n "$task" ] && [ -f "$script" ] || return 0
+  # Cheap gate: only spawn the emitter when usage logging is actually on, so a
+  # user who never enabled it pays nothing per phase boundary. jq is already a
+  # hard dependency of this script.
+  jq -e '.global.usageLog.enabled == true' "$prefs" >/dev/null 2>&1 || return 0
+  ( node "$script" --task-id "$task" --phase "$phase" --status running >/dev/null 2>&1 & ) 2>/dev/null || true
+}
+
 # Decode HTML entities in a tile title.
 #
 # `rules.md` forbids entities in "titles, commit messages, task subjects, or body
@@ -681,6 +698,7 @@ case "$ACTION" in
     # subsequent tracker call (the pointer flips on the most recent init).
     echo "$TRACKER_FILE" > "$HOME/.claude/logs/multi-agent/.tracker-current"
     render
+    usage_live_ping "$TASK_ID" 0
     if [ "${MULTI_AGENT_QUIET:-0}" != "1" ]; then
       echo "phase-tracker: tracker initialized for task=$TASK_ID" >&2
       echo "phase-tracker: TIP  -  for concurrent-safe resolution, set:" >&2
@@ -733,6 +751,7 @@ case "$ACTION" in
     release_state_lock
     emit_otel_span "phase.update" "$PID" "$STATUS" "{\"status\": \"$STATUS\"}"
     render
+    usage_live_ping "$(basename "$TRACKER_DIR")" "$PID"
     ;;
 
   sub)

package/pipeline/scripts/uninstall.mjs

@@ -353,7 +353,9 @@ function rmExternalDeliveredSkills(skillsDir) {
   if (!names) {
     console.log(
       `    note: no ${EXTERNAL_SKILLS_MANIFEST} under ${skillsDir} - external skill dirs left in ` +
-        `place (cannot tell pipeline-delivered from user-authored; re-run install once, then uninstall)`,
+        `place (cannot tell pipeline-delivered from user-authored; ` +
+        `node install.js --claude prunes copies identical to the shipped catalog, ` +
+        `--prune-external removes the rest)`,
     );
     return 0;
   }