@mmerterden/multi-agent-pipeline 8.6.2 → 10.0.6

package/pipeline/scripts/README.md

@@ -1,104 +1,104 @@
-# Pipeline Scripts — Category Index
+# Pipeline Scripts  -  Category Index
 
-The `pipeline/scripts/` directory holds 59 shell scripts + 12 Node.js `.mjs` scripts in a flat layout. v6.0.0 evaluated moving them into `smoke/`, `hooks/`, `runtime/` subdirs and decided against it: each path change would need to propagate through `package.json` globs, `install.js` deploy logic, npm scripts, sibling script calls, and CI workflow references — a 40+ file touch radius with high regression risk for minor polish value.
+The `pipeline/scripts/` directory holds 59 shell scripts + 12 Node.js `.mjs` scripts in a flat layout. v6.0.0 evaluated moving them into `smoke/`, `hooks/`, `runtime/` subdirs and decided against it: each path change would need to propagate through `package.json` globs, `install.js` deploy logic, npm scripts, sibling script calls, and CI workflow references  -  a 40+ file touch radius with high regression risk for minor polish value.
 
 Instead, this README is the category index. Use it to navigate.
 
-## Smoke scripts (42 files — `smoke-*.sh`)
+## Smoke scripts (42 files  -  `smoke-*.sh`)
 
 Validate contracts. Each emits `══ <name> smoke: N passed, M failed ══` on completion (the `smoke-personal-data.sh` + `smoke-token-budget.sh` suites use `PASS:` / `warnings:` variants). Run via `npm test` (chained) or individually.
 
 ### Cross-CLI contract + parity
-- `smoke-cross-cli-behavior.sh` — parent parity smoke, agent/skill deployment on both sides
-- `smoke-commands-skills-parity.sh` — colon-form command ↔ dash-form skill directory parity (50 assertions)
-- `smoke-compliance-skills.sh` — v5.8.1+ store-compliance wiring contract (45 assertions)
-- `smoke-figma-cross-cli-inventory.sh` — figma skill cross-CLI source-tree parity (39 assertions)
+- `smoke-cross-cli-behavior.sh`  -  parent parity smoke, agent/skill deployment on both sides
+- `smoke-commands-skills-parity.sh`  -  colon-form command ↔ dash-form skill directory parity (50 assertions)
+- `smoke-compliance-skills.sh`  -  v5.8.1+ store-compliance wiring contract (45 assertions)
+- `smoke-figma-cross-cli-inventory.sh`  -  figma skill cross-CLI source-tree parity (39 assertions)
 
 ### Figma pipeline (see `pipeline/scripts/README-figma-smokes.md` for the full index)
 - `smoke-figma-android-parity.sh`, `smoke-figma-config-schema.sh`, `smoke-figma-dispatch.sh`, `smoke-figma-skill-import.sh`, `smoke-figma-sync.sh`
 
 ### Phase contracts
-- `smoke-phase-0-multi-repo.sh` — Phase 0 multi-repo mode fetch + worktree atomicity
-- `smoke-phase-6-multi.sh` — Phase 6 multi-repo commit/PR cross-linking
-- `smoke-phase-banner.sh` + `smoke-phase-tracker.sh` — Phase UI output contracts
-- `smoke-phase4-triage.sh` — Phase 4 reviewer → triage flow
+- `smoke-phase-0-multi-repo.sh`  -  Phase 0 multi-repo mode fetch + worktree atomicity
+- `smoke-phase-6-multi.sh`  -  Phase 6 multi-repo commit/PR cross-linking
+- `smoke-phase-banner.sh` + `smoke-phase-tracker.sh`  -  Phase UI output contracts
+- `smoke-phase4-triage.sh`  -  Phase 4 reviewer → triage flow
 
 ### Schema + state
-- `smoke-schema-validation.sh` — all JSON schemas validate
-- `smoke-migrate-state.sh` — `migrate-state.mjs` runner behavior
-- `smoke-pref-migration.sh` — prefs 2.0.0 → 2.1.0 → 2.2.0 migration chain (22 assertions)
-- `smoke-write-state.sh` — atomic state writer concurrency
+- `smoke-schema-validation.sh`  -  all JSON schemas validate
+- `smoke-migrate-state.sh`  -  `migrate-state.mjs` runner behavior
+- `smoke-pref-migration.sh`  -  prefs 2.0.0 → 2.1.0 → 2.2.0 migration chain (22 assertions)
+- `smoke-write-state.sh`  -  atomic state writer concurrency
 
 ### Quality + security
-- `smoke-personal-data.sh` — guards against corporate hostname / private Jira key / personal domain leaks (13 patterns; full catalog in the script itself)
-- `smoke-pat-audit.sh` — PAT lookup telemetry contract
-- `smoke-token-budget.sh` — per-phase token budget enforcement (9 phases)
-- `smoke-skill-scan.sh` — skill security scanner tiered pattern catalog
+- `smoke-personal-data.sh`  -  guards against corporate hostname / private Jira key / personal domain leaks (13 patterns; full catalog in the script itself)
+- `smoke-pat-audit.sh`  -  PAT lookup telemetry contract
+- `smoke-token-budget.sh`  -  per-phase token budget enforcement (9 phases)
+- `smoke-skill-scan.sh`  -  skill security scanner tiered pattern catalog
 
 ### Command / Feature contracts
-- `smoke-channels-flow.sh` — `/multi-agent:channels` multi-select + humanizer + Bitbucket PUT (44 assertions)
-- `smoke-wiki-integration.sh` — v5.7+ wiki Case A/B + 4-adapter contract
-- `smoke-add-detail.sh` — legacy Bitbucket PUT reviewer-preservation
-- `smoke-issue-jira-triad.sh` — Issue → Jira → Wiki triad
-- `smoke-url-enrichment.sh` — Phase 0 Step 1b URL context parsing
-- `smoke-plan-approval-gate.sh` — Phase 2 clarification + free-text edit loop
-- `smoke-push-retry.sh` — 5-retry policy + 4-option fail flow
-- `smoke-identity-isolation.sh` — cross-identity PAT leak guard
-- `smoke-sync-delegation.sh`, `smoke-sync-parity.sh` — `/multi-agent:sync` behavior
+- `smoke-channels-flow.sh`  -  `/multi-agent:channels` multi-select + humanizer + Bitbucket PUT (44 assertions)
+- `smoke-wiki-integration.sh`  -  v5.7+ wiki Case A/B + 4-adapter contract
+- `smoke-add-detail.sh`  -  legacy Bitbucket PUT reviewer-preservation
+- `smoke-issue-jira-triad.sh`  -  Issue → Jira → Wiki triad
+- `smoke-url-enrichment.sh`  -  Phase 0 Step 1b URL context parsing
+- `smoke-plan-approval-gate.sh`  -  Phase 2 clarification + free-text edit loop
+- `smoke-push-retry.sh`  -  5-retry policy + 4-option fail flow
+- `smoke-identity-isolation.sh`  -  cross-identity PAT leak guard
+- `smoke-sync-delegation.sh`, `smoke-sync-parity.sh`  -  `/multi-agent:sync` behavior
 
 ### Sub-systems
-- `smoke-multi-repo-integration.sh` — v5.6.0 integration build + learn-once registry (20 assertions)
-- `smoke-multi-repo-worktree.sh` — serial worktree creation with atomicity rollback
-- `smoke-prefs-language.sh` — `prefs.global.promptLanguage` contract
-- `smoke-progress-contract.sh` — progress-line quiet/normal/verbose
-- `smoke-search.sh` — `/multi-agent:search` log search + smart ranking
-- `smoke-stack-swap.sh` — `/multi-agent:stack` auto-detect + manual override
-- `smoke-subagent-validators.sh` — Phase 1/2 validator schemas
-- `smoke-telemetry.sh` — opt-in telemetry contract
-- `smoke-validator-contradiction.sh` — Phase 4 approved/blocking contradiction detection
-- `smoke-pre-commit.sh` — pre-commit hook integration
+- `smoke-multi-repo-integration.sh`  -  v5.6.0 integration build + learn-once registry (20 assertions)
+- `smoke-multi-repo-worktree.sh`  -  serial worktree creation with atomicity rollback
+- `smoke-prefs-language.sh`  -  `prefs.global.promptLanguage` contract
+- `smoke-progress-contract.sh`  -  progress-line quiet/normal/verbose
+- `smoke-search.sh`  -  `/multi-agent:search` log search + smart ranking
+- `smoke-stack-swap.sh`  -  `/multi-agent:stack` auto-detect + manual override
+- `smoke-subagent-validators.sh`  -  Phase 1/2 validator schemas
+- `smoke-telemetry.sh`  -  opt-in telemetry contract
+- `smoke-validator-contradiction.sh`  -  Phase 4 approved/blocking contradiction detection
+- `smoke-pre-commit.sh`  -  pre-commit hook integration
 
 ## Hook scripts (3 files)
 Installed into `~/.claude/scripts/` and invoked by settings.json hook configuration.
 
-- `pre-commit-check.sh` — runs before `git commit` (secret scan + personal-data leak check)
-- `pre-push-check.sh` — runs before `git push` (smoke-cross-cli-behavior + smoke-personal-data)
-- `output-quality-check.sh` — runs after PR body / Jira comment generation (newline / HTML entity guard)
+- `pre-commit-check.sh`  -  runs before `git commit` (secret scan + personal-data leak check)
+- `pre-push-check.sh`  -  runs before `git push` (smoke-cross-cli-behavior + smoke-personal-data)
+- `output-quality-check.sh`  -  runs after PR body / Jira comment generation (newline / HTML entity guard)
 
 ## Runtime helpers (13 files)
 Shell scripts invoked during pipeline execution.
 
-- `phase-banner.sh` — renders phase headers
-- `phase-tracker.sh` — live tracker state + tokens accumulation + render
-- `stack-swap.sh` — stack detection + skill set swap
-- `keychain-save.sh` — store PAT in macOS Keychain
-- `audit-log.sh` + `audit-log-rotate.sh` — opt-in audit trail
-- `log-metric.sh` — opt-in metric capture
-- `search-logs.sh` — backs `/multi-agent:search`
-- `scan-skills.sh` — backs `/multi-agent:scan`
-- `benchmark-phase-0.sh` — Phase 0 perf harness
-- `sync-figma-source.sh` — WS-9 source sync (figma)
-- `import-figma-skills.sh` — developer-only import harness (not run at runtime)
-- `github-ssh-setup.sh` — first-run SSH key setup helper
-- `sync-parity-check.sh` — manual parity verification helper
+- `phase-banner.sh`  -  renders phase headers
+- `phase-tracker.sh`  -  live tracker state + tokens accumulation + render
+- `stack-swap.sh`  -  stack detection + skill set swap
+- `keychain-save.sh`  -  store PAT in macOS Keychain
+- `audit-log.sh` + `audit-log-rotate.sh`  -  opt-in audit trail
+- `log-metric.sh`  -  opt-in metric capture
+- `search-logs.sh`  -  backs `/multi-agent:search`
+- `scan-skills.sh`  -  backs `/multi-agent:scan`
+- `benchmark-phase-0.sh`  -  Phase 0 perf harness
+- `sync-figma-source.sh`  -  WS-9 source sync (figma)
+- `import-figma-skills.sh`  -  developer-only import harness (not run at runtime)
+- `github-ssh-setup.sh`  -  first-run SSH key setup helper
+- `sync-parity-check.sh`  -  manual parity verification helper
 
 ## Node.js helpers (12 `.mjs` files)
 
-- `aggregate-metrics.mjs` — collects telemetry aggregates
-- `eval-triage.mjs` — runs the 10 triage eval fixtures
-- `gen-skills-index.mjs` — regenerates `pipeline/skills/shared/README.md` skill catalog
-- `migrate-prefs.mjs` — preference migration driver (v2.0.0 → v2.1.0 → v2.2.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
-- `validate-schemas.mjs` — top-level schema validity gate (runs every schema through AJV)
-- `write-state.mjs` — atomic state writer with concurrency safety
+- `aggregate-metrics.mjs`  -  collects telemetry aggregates
+- `eval-triage.mjs`  -  runs the 10 triage eval fixtures
+- `gen-skills-index.mjs`  -  regenerates `pipeline/skills/shared/README.md` skill catalog
+- `migrate-prefs.mjs`  -  preference migration driver (v2.0.0 → v2.1.0 → v2.2.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
+- `validate-schemas.mjs`  -  top-level schema validity gate (runs every schema through AJV)
+- `write-state.mjs`  -  atomic state writer with concurrency safety
 
 ## Why flat layout (not `smoke/`, `hooks/`, `runtime/`)
 
 The audit (v6.0.0 W3.3) considered moving files into subdirs for clarity. Tradeoffs:
 
 - **Pro:** easier navigation in file tree viewers; clearer categorization at a glance.
-- **Con:** every path reference would need updating — `npm test` glob (`pipeline/scripts/smoke-*.sh`), `install.js` `pipeline/scripts` deploy logic, every smoke's `$HERE/../..` root resolution, sibling calls between scripts, CI workflow references. 40+ file touch radius with no runtime behavior change.
+- **Con:** every path reference would need updating  -  `npm test` glob (`pipeline/scripts/smoke-*.sh`), `install.js` `pipeline/scripts` deploy logic, every smoke's `$HERE/../..` root resolution, sibling calls between scripts, CI workflow references. 40+ file touch radius with no runtime behavior change.
 
 Verdict: flat layout kept, this README plays the navigator role. If the script count doubles and the ratio shifts, revisit.

package/pipeline/scripts/aggregate-metrics.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// aggregate-metrics.mjs — read metrics.jsonl and print a human-readable summary.
+// aggregate-metrics.mjs  -  read metrics.jsonl and print a human-readable summary.
 //
 // Zero-dep (Node built-ins only). Reads $METRICS_FILE or
 // $HOME/.claude/logs/multi-agent/metrics.jsonl by default, optionally filtered
@@ -15,6 +15,7 @@
 //   - Triage edge-case occurrences (high-rejection-rate, failed-json-parse, etc.)
 //   - Phase 3 retry distribution
 //   - Language preference distribution
+//   - Per-model token cost + prompt-cache reuse ratio (cached / total input)
 //
 // Usage:
 //   node aggregate-metrics.mjs
@@ -56,7 +57,7 @@ if (!existsSync(METRICS_FILE)) {
       JSON.stringify({ ok: false, reason: "metrics file not found", path: METRICS_FILE }),
     );
   } else {
-    console.error(`No metrics yet — file not found: ${METRICS_FILE}`);
+    console.error(`No metrics yet  -  file not found: ${METRICS_FILE}`);
     console.error("Pipeline runs after v2.3.0 will populate it.");
   }
   process.exit(0);
@@ -122,7 +123,7 @@ for (const e of reviewCompleted) {
   totalRaw += Number(e.details?.raw_count || 0);
 }
 
-// Cost / token telemetry — aggregate per model.
+// Cost / token telemetry  -  aggregate per model.
 // Convention: emitters add `model=<name>`, `tokens_in=<N>`,
 // `tokens_out=<N>` to events that involve a model call. We sum across all
 // events per model. Approximate cost is left to the caller (rates change);
@@ -137,14 +138,40 @@ for (const e of filtered) {
       duration_ms: 0,
       tokens_in: 0,
       tokens_out: 0,
+      tokens_cached: 0,
     };
   }
   perModel[m].calls += 1;
   perModel[m].duration_ms += Number(e.details?.duration_ms || 0);
   perModel[m].tokens_in += Number(e.details?.tokens_in || 0);
   perModel[m].tokens_out += Number(e.details?.tokens_out || 0);
+  perModel[m].tokens_cached += Number(e.details?.tokens_cached || 0);
 }
 
+// Prompt-cache reuse ratio. `tokens_in` is freshly-billed input; `tokens_cached`
+// is input served from the host prompt cache at the discounted rate. The ratio
+// is cached / (in + cached) = the share of input tokens that hit the cache.
+// This is the single number that tells us whether cache-friendly prompt
+// structuring is actually paying off; surfaced per model and overall.
+const cacheRatio = (cached, fresh) => {
+  const denom = cached + fresh;
+  return denom > 0 ? Number((cached / denom).toFixed(2)) : null;
+};
+for (const t of Object.values(perModel)) {
+  t.cache_ratio = cacheRatio(t.tokens_cached, t.tokens_in);
+}
+let totalIn = 0;
+let totalCached = 0;
+for (const t of Object.values(perModel)) {
+  totalIn += t.tokens_in;
+  totalCached += t.tokens_cached;
+}
+const overallCache = {
+  tokens_in: totalIn,
+  tokens_cached: totalCached,
+  cache_ratio: cacheRatio(totalCached, totalIn),
+};
+
 // Edge cases
 const edgeCases = filtered
   .filter((e) => e.event === "triage.edge_case")
@@ -190,6 +217,7 @@ const summary = {
   rework_iterations: retryCounts,
   language_preference: langs,
   cost_per_model: perModel,
+  cache_reuse: overallCache,
   events_by_type: byEvent,
 };
 
@@ -209,17 +237,17 @@ if (opts.markdown) {
   lines.push(`| Metric | Value |`);
   lines.push(`|--------|-------|`);
   lines.push(`| Completed | ${summary.reviews_completed} |`);
-  lines.push(`| Cycles per task (avg) | ${summary.review_cycles.avg ?? "—"} |`);
-  lines.push(`| Cycles per task (p95) | ${summary.review_cycles.p95 ?? "—"} |`);
+  lines.push(`| Cycles per task (avg) | ${summary.review_cycles.avg ?? " - "} |`);
+  lines.push(`| Cycles per task (p95) | ${summary.review_cycles.p95 ?? " - "} |`);
   lines.push(``);
   lines.push(`## Triage Classification`);
   lines.push(``);
   lines.push(`| Category | Count | Rate |`);
   lines.push(`|----------|-------|------|`);
-  lines.push(`| Raw findings | ${summary.triage_totals.raw} | — |`);
-  lines.push(`| Accepted | ${summary.triage_totals.accepted} | ${summary.triage_totals.accept_rate ?? "—"} |`);
-  lines.push(`| Deferred | ${summary.triage_totals.deferred} | — |`);
-  lines.push(`| Rejected | ${summary.triage_totals.rejected} | ${summary.triage_totals.reject_rate ?? "—"} |`);
+  lines.push(`| Raw findings | ${summary.triage_totals.raw} |  -  |`);
+  lines.push(`| Accepted | ${summary.triage_totals.accepted} | ${summary.triage_totals.accept_rate ?? " - "} |`);
+  lines.push(`| Deferred | ${summary.triage_totals.deferred} |  -  |`);
+  lines.push(`| Rejected | ${summary.triage_totals.rejected} | ${summary.triage_totals.reject_rate ?? " - "} |`);
 
   if (Object.keys(summary.edge_cases).length) {
     lines.push(``);
@@ -236,19 +264,24 @@ if (opts.markdown) {
     lines.push(``);
     lines.push(`## Cost Per Model`);
     lines.push(``);
-    lines.push(`| Model | Calls | Duration (ms) | Tokens In | Tokens Out |`);
-    lines.push(`|-------|-------|---------------|-----------|------------|`);
+    lines.push(`| Model | Calls | Duration (ms) | Tokens In | Tokens Out | Cached | Cache % |`);
+    lines.push(`|-------|-------|---------------|-----------|------------|--------|---------|`);
     for (const [m, t] of Object.entries(summary.cost_per_model).sort((a, b) => b[1].calls - a[1].calls)) {
-      lines.push(`| \`${m}\` | ${t.calls} | ${t.duration_ms} | ${t.tokens_in} | ${t.tokens_out} |`);
+      const pct = t.cache_ratio === null ? " - " : `${Math.round(t.cache_ratio * 100)}%`;
+      lines.push(`| \`${m}\` | ${t.calls} | ${t.duration_ms} | ${t.tokens_in} | ${t.tokens_out} | ${t.tokens_cached} | ${pct} |`);
     }
+    const oc = summary.cache_reuse;
+    const ocPct = oc.cache_ratio === null ? " - " : `${Math.round(oc.cache_ratio * 100)}%`;
+    lines.push(``);
+    lines.push(`_Overall prompt-cache reuse: ${oc.tokens_cached.toLocaleString()} cached / ${(oc.tokens_in + oc.tokens_cached).toLocaleString()} total input tokens = **${ocPct}**._`);
   }
   console.log(lines.join("\n"));
   process.exit(0);
 }
 
 // Plain-text rendering
-const fmt = (n) => (n === null ? "—" : String(n));
-console.log(`Multi-Agent Pipeline — metrics summary`);
+const fmt = (n) => (n === null ? " - " : String(n));
+console.log(`Multi-Agent Pipeline  -  metrics summary`);
 console.log(`source: ${summary.source}`);
 console.log(`events: ${summary.total_events} (${summary.parse_errors} parse errors)`);
 console.log(`unique tasks: ${summary.unique_tasks}`);
@@ -298,13 +331,19 @@ if (Object.keys(summary.cost_per_model).length) {
   console.log(``);
   console.log(`Cost / token telemetry (per model):`);
   console.log(
-    `  ${"model".padEnd(20)} ${"calls".padStart(6)} ${"duration_ms".padStart(13)} ${"tokens_in".padStart(11)} ${"tokens_out".padStart(11)}`,
+    `  ${"model".padEnd(20)} ${"calls".padStart(6)} ${"duration_ms".padStart(13)} ${"tokens_in".padStart(11)} ${"tokens_out".padStart(11)} ${"cached".padStart(11)} ${"cache%".padStart(7)}`,
   );
   for (const [m, t] of Object.entries(summary.cost_per_model).sort(
     (a, b) => b[1].calls - a[1].calls,
   )) {
+    const pct = t.cache_ratio === null ? " - " : `${Math.round(t.cache_ratio * 100)}%`;
     console.log(
-      `  ${m.padEnd(20)} ${String(t.calls).padStart(6)} ${String(t.duration_ms).padStart(13)} ${String(t.tokens_in).padStart(11)} ${String(t.tokens_out).padStart(11)}`,
+      `  ${m.padEnd(20)} ${String(t.calls).padStart(6)} ${String(t.duration_ms).padStart(13)} ${String(t.tokens_in).padStart(11)} ${String(t.tokens_out).padStart(11)} ${String(t.tokens_cached).padStart(11)} ${pct.padStart(7)}`,
     );
   }
+  const oc = summary.cache_reuse;
+  const ocPct = oc.cache_ratio === null ? " - " : `${Math.round(oc.cache_ratio * 100)}%`;
+  console.log(
+    `  overall prompt-cache reuse: ${oc.tokens_cached} / ${oc.tokens_in + oc.tokens_cached} input tokens = ${ocPct}`,
+  );
 }

package/pipeline/scripts/audit-log-rotate.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# audit-log-rotate.sh — daily rotation for ~/.claude/logs/multi-agent/audit.jsonl.
+# audit-log-rotate.sh  -  daily rotation for ~/.claude/logs/multi-agent/audit.jsonl.
 #
-# Per §18.2.4 of REFACTOR_PLAN_v3.7.md: audit log rotates daily, keeps 30 days
+# Per section18.2.4 of REFACTOR_PLAN_v3.7.md: audit log rotates daily, keeps 30 days
 # of compressed history, drops anything older.
 #
 # Install via launchd on macOS (preferred) or cron on Linux:
@@ -49,7 +49,7 @@ if [ -s "$AUDIT_FILE" ]; then
     gzip -f "$ROTATED" 2>/dev/null || true
   fi
 
-  # Reset live file (mode 0600 — sensitive)
+  # Reset live file (mode 0600  -  sensitive)
   : > "$AUDIT_FILE"
   chmod 600 "$AUDIT_FILE" 2>/dev/null || true
 fi

package/pipeline/scripts/audit-log.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
-# audit-log.sh — append a single PAT-lookup audit event.
+# audit-log.sh  -  append a single PAT-lookup audit event.
 #
-# Per §18 of REFACTOR_PLAN_v3.7.md: every PAT lookup writes a structured event
+# Per section18 of REFACTOR_PLAN_v3.7.md: every PAT lookup writes a structured event
 # to ~/.claude/logs/multi-agent/audit.jsonl. Repo URLs are SHA-256 hashed
 # (corporate paths are sensitive). Identity is logged by name (user's own debug).
 #
@@ -13,7 +13,7 @@
 #   audit-log.sh pat_lookup github mmerterden git@github.com:user/repo.git true scope=repo,read:org
 #   audit-log.sh pat_missing jira ${USER} "" false reason=keychain_empty
 #
-# Failure mode: silent — telemetry must never block the pipeline.
+# Failure mode: silent  -  telemetry must never block the pipeline.
 
 set -uo pipefail
 
@@ -27,11 +27,24 @@ SERVICE="$1"; shift
 IDENTITY="$1"; shift
 REPO_URL="${1:-}"; [ "$#" -gt 0 ] && shift
 SUCCESS="${1:-true}"; [ "$#" -gt 0 ] && shift
+# success is emitted as a raw JSON boolean at line ~70. A non-bool 5th arg
+# would produce invalid JSON ("success":yes-please) and break json.loads on
+# the whole line. Coerce anything that isn't a literal bool to the documented
+# default (true) so the audit line always parses.
+case "$SUCCESS" in
+  true|false) ;;
+  *) SUCCESS=true ;;
+esac
 
 AUDIT_FILE="${AUDIT_FILE:-$HOME/.claude/logs/multi-agent/audit.jsonl}"
 mkdir -p "$(dirname "$AUDIT_FILE")" 2>/dev/null || exit 0
 
-# SHA-256 hash the repo URL (never log plaintext per §18.2.2)
+# Escape a string for embedding inside a JSON double-quoted value.
+json_escape() {
+  printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'
+}
+
+# SHA-256 hash the repo URL (never log plaintext per section18.2.2)
 hash_url() {
   local url="$1"
   [ -z "$url" ] && { echo ""; return; }
@@ -55,14 +68,14 @@ for kv in "$@"; do
   VAL="${kv#*=}"
   case "$VAL" in
     true|false) JSON_VAL="$VAL" ;;
-    ''|*[!0-9]*) JSON_VAL="\"$(printf '%s' "$VAL" | sed 's/\\/\\\\/g; s/"/\\"/g')\"" ;;
+    ''|*[!0-9]*) JSON_VAL="\"$(json_escape "$VAL")\"" ;;
     *) JSON_VAL="$VAL" ;;
   esac
-  EXTRAS="${EXTRAS}${SEP}\"${KEY}\":${JSON_VAL}"
+  EXTRAS="${EXTRAS}${SEP}\"$(json_escape "$KEY")\":${JSON_VAL}"
   SEP=","
 done
 
-LINE="{\"ts\":\"${TS}\",\"event\":\"${EVENT}\",\"service\":\"${SERVICE}\",\"identity\":\"${IDENTITY}\",\"repo_url_sha\":\"${REPO_SHA}\",\"success\":${SUCCESS}"
+LINE="{\"ts\":\"${TS}\",\"event\":\"$(json_escape "$EVENT")\",\"service\":\"$(json_escape "$SERVICE")\",\"identity\":\"$(json_escape "$IDENTITY")\",\"repo_url_sha\":\"${REPO_SHA}\",\"success\":${SUCCESS}"
 [ -n "$EXTRAS" ] && LINE="${LINE},${EXTRAS}"
 LINE="${LINE}}"
 

package/pipeline/scripts/benchmark-phase-0.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# benchmark-phase-0.sh — measures Phase 0 latency (single-repo + multi-repo)
+# benchmark-phase-0.sh  -  measures Phase 0 latency (single-repo + multi-repo)
 # and writes a baseline / comparison row to benchmarks/v3.7-phase-0.jsonl.
 #
 # Usage:
@@ -8,11 +8,11 @@
 #   benchmark-phase-0.sh --label baseline  # tag the row (e.g. "baseline" / "post-refactor")
 #   benchmark-phase-0.sh --multi-repo      # exercise the multi-repo path
 #
-# What it measures (proxy — actual Phase 0 needs a live task):
+# What it measures (proxy  -  actual Phase 0 needs a live task):
 #   1. Preferences load (read + JSON parse)
-#   2. Schema validation (validate prefs against prefs.schema.json — node + ajv if present)
-#   3. Project scan ($HOME maxdepth 2 with marker globs — same as Phase 0 Step 2)
-#   4. Branch listing (no remote — uses local $HOME repo if available)
+#   2. Schema validation (validate prefs against prefs.schema.json  -  node + ajv if present)
+#   3. Project scan ($HOME maxdepth 2 with marker globs  -  same as Phase 0 Step 2)
+#   4. Branch listing (no remote  -  uses local $HOME repo if available)
 #   5. Recents read + TTL prune simulation
 #
 # Best-effort: missing tools (node, jq) cause the section to skip rather than fail.
@@ -107,7 +107,7 @@ bench_one() {
     "$prefs_load_ms" "$schema_ms" "$scan_ms" "$branch_ms" "$recents_ms" "$total_ms"
 }
 
-echo "Running $RUNS bench iteration(s) — label=$LABEL mode=$([ "$MULTI" = true ] && echo multi || echo single)"
+echo "Running $RUNS bench iteration(s)  -  label=$LABEL mode=$([ "$MULTI" = true ] && echo multi || echo single)"
 TOTALS=()
 for i in $(seq 1 "$RUNS"); do
   ROW=$(bench_one)

package/pipeline/scripts/build-skills-index.mjs

@@ -1,26 +1,26 @@
 #!/usr/bin/env node
-// build-skills-index.mjs — v7.0.I
+// build-skills-index.mjs  -  v7.0.I
 //
 // Walks all SKILL.md files and emits a lightweight index so the pipeline can
-// dynamically inject only the skills relevant to a task — instead of relying
-// on Claude Code's eager-load of all 192 skills on every session.
+// dynamically inject only the skills relevant to a task  -  instead of relying
+// on Claude Code's eager-load of all 206 skills on every session.
 //
 // Outputs (both written to pipeline/skills/):
-//   .skills-index.json — machine-readable, consumed by match-skills.mjs
-//   skills-index.md    — human-readable, can be browsed in-repo
+//   .skills-index.json  -  machine-readable, consumed by match-skills.mjs
+//   skills-index.md     -  human-readable, can be browsed in-repo
 //
 // For each SKILL.md we extract:
-//   name          — frontmatter `name:` (fallback: directory name)
-//   description   — frontmatter `description:` (first 300 chars)
-//   platform      — frontmatter `platform:` if set (ios / android / generic)
-//   group         — derived from path: core / figma-ios / figma-android /
+//   name           -  frontmatter `name:` (fallback: directory name)
+//   description    -  frontmatter `description:` (first 300 chars)
+//   platform       -  frontmatter `platform:` if set (ios / android / generic)
+//   group          -  derived from path: core / figma-ios / figma-android /
 //                    figma-common / external
-//   triggerKeywords — frontmatter `trigger-keywords:` (comma-separated
-//                    values lowercased) — authors can add these to tighten
+//   triggerKeywords  -  frontmatter `trigger-keywords:` (comma-separated
+//                    values lowercased)  -  authors can add these to tighten
 //                    match score. Missing → empty list.
-//   triggerPaths  — frontmatter `trigger-paths:` (glob patterns) — missing
+//   triggerPaths   -  frontmatter `trigger-paths:` (glob patterns)  -  missing
 //                    → empty list.
-//   relativePath  — path relative to pipeline/skills/
+//   relativePath   -  path relative to pipeline/skills/
 //
 // Usage: build-skills-index.mjs [--root <dir>]   # default: ./pipeline/skills
 
@@ -119,7 +119,7 @@ writeFileSync(jsonPath, JSON.stringify(json, null, 2) + "\n");
 const mdLines = [
   "# Skills index",
   "",
-  `> Auto-generated by \`pipeline/scripts/build-skills-index.mjs\` — do not hand-edit.`,
+  `> Auto-generated by \`pipeline/scripts/build-skills-index.mjs\`  -  do not hand-edit.`,
   `> Regenerate with \`node pipeline/scripts/build-skills-index.mjs\`.`,
   "",
   `**${entries.length} skills** across ${new Set(entries.map((e) => e.group)).size} groups.`,
@@ -129,7 +129,7 @@ const mdLines = [
 ];
 for (const e of entries) {
   const desc = e.description.replace(/\|/g, "\\|").slice(0, 140);
-  mdLines.push(`| ${e.group} | \`${e.name}\` | ${e.platform || "—"} | ${desc} |`);
+  mdLines.push(`| ${e.group} | \`${e.name}\` | ${e.platform || " - "} | ${desc} |`);
 }
 mdLines.push("");
 const mdPath = join(root, "skills-index.md");

package/pipeline/scripts/check-md-links.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// Internal markdown link checker for the user-facing docs surface.
+//
+// Scope: root *.md + docs/**/*.md + examples/**/*.md. Verifies that every
+// relative link target ([text](./path) or [text](path#anchor)) resolves to
+// an existing file or directory. External (http/https/mailto) links and
+// pure #anchors are skipped - this is a drift gate for file moves/renames,
+// not a network crawler.
+
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+function mdFiles(dir, acc = []) {
+  for (const entry of readdirSync(dir)) {
+    if (entry === "node_modules" || entry.startsWith(".")) continue;
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) mdFiles(full, acc);
+    else if (entry.endsWith(".md")) acc.push(full);
+  }
+  return acc;
+}
+
+const targets = [
+  ...readdirSync(repoRoot).filter((f) => f.endsWith(".md")).map((f) => join(repoRoot, f)),
+  ...["docs", "examples"].filter((d) => existsSync(join(repoRoot, d))).flatMap((d) => mdFiles(join(repoRoot, d))),
+  // CHANGELOG-archive.md is frozen history - it legitimately references docs
+  // that were deleted in later releases.
+].filter((f) => !f.endsWith("CHANGELOG-archive.md"));
+
+const LINK_RE = /\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+const errors = [];
+
+for (const file of targets) {
+  // Drop fenced blocks and inline code spans - links inside code are
+  // illustrative placeholders, not navigation.
+  const text = readFileSync(file, "utf-8")
+    .replace(/```[\s\S]*?```/g, "")
+    .replace(/`[^`\n]*`/g, "");
+  for (const match of text.matchAll(LINK_RE)) {
+    const raw = match[1];
+    if (/^(https?:|mailto:|#)/.test(raw)) continue;
+    const target = raw.split("#")[0];
+    if (target === "") continue;
+    const resolved = resolve(dirname(file), decodeURIComponent(target));
+    if (!existsSync(resolved)) {
+      errors.push(`${file.slice(repoRoot.length + 1)}: broken link -> ${raw}`);
+    }
+  }
+}
+
+if (errors.length > 0) {
+  console.error(`check-md-links: ${errors.length} broken internal link(s)`);
+  for (const e of errors) console.error("  " + e);
+  process.exit(1);
+}
+console.log(`check-md-links: ${targets.length} files OK`);