mustard-claude 3.1.30 → 3.1.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustard-claude",
-  "version": "3.1.30",
+  "version": "3.1.31",
   "description": "Framework-agnostic CLI for Claude Code project setup",
   "type": "module",
   "bin": {

package/templates/commands/mustard/metrics/SKILL.md

@@ -1,29 +1,32 @@
 ---
 name: mustard:metrics
-description: Show enforcement metrics report — hook hit rates, budget distributions, gate activity. Metrics are recorded automatically; just run this to see them.
+description: Focused view of enforcement hook events and compare-window deltas. For the superset (pipelines + hooks + RTK), use /mustard:stats.
 ---
 
-# /mustard:metrics - Show Metrics Report
+# /mustard:metrics - Hook Events & Compare
 
 ## Trigger
-`/mustard:metrics [--since <ISO date>] [--event <type>]`
+`/mustard:metrics [--since <ISO date>] [--event <type>] [--compare <from> <to>]`
 
 ## What it does
-Runs `.claude/scripts/metrics-report.js` and shows the aggregated report.
+Focused on two use cases:
 
-Metrics are recorded **automatically** by enforcement hooks on every Task dispatch — no activation needed. Just run this command whenever you want to see the current state.
+1. **Hook-level aggregation** (default) — runs `.claude/scripts/metrics-report.js` and emits a table of events from `.claude/.metrics/*.jsonl`, plus RTK token savings.
+2. **Compare window** (`--compare`) — delta between two git tags or ISO dates (reference window computed automatically from the delta).
+
+For the superset view that also includes per-pipeline metrics, orphans, Pass@1 and Last 7 Days, use **`/mustard:stats`** (cross-reference).
 
 ## Action
 1. Run `rtk node .claude/scripts/metrics-report.js $ARGS` (pass through any flags)
 2. Display output verbatim
 
-## Optional flags
+## Flags
 - `--since <ISO date>` — filter events after this date
 - `--event <type>` — filter to one event type (e.g. `budget-check`)
-- `--compare <from> <to>` — delta between two windows (git tag or ISO date)
+- `--compare <from> <to>` — delta between two windows (git tag `vX.Y.Z` or ISO date)
 
 ## Examples
-- `/mustard:metrics` — full report since beginning
+- `/mustard:metrics` — hook event aggregation since beginning
 - `/mustard:metrics --since 2026-04-09` — only recent events
 - `/mustard:metrics --event budget-check` — only budget-check events
 - `/mustard:metrics --compare v3.1.21 v3.1.22` — delta between two releases
@@ -34,3 +37,4 @@ Metrics are recorded **automatically** by enforcement hooks on every Task dispat
 - Logs auto-rotate at 10MB
 - To reset: delete files in `.claude/.metrics/` manually
 - Advanced: override mode via `CONTEXT_BUDGET_MODE` env var (`strict`|`warn`|`observe`). Default is `strict`.
+- `rtk-rewrite` events deliberately show only counts (no `tokens_saved` column) — real RTK numbers come from `rtk gain`, surfaced in the "RTK Token Savings" block.

package/templates/commands/mustard/stats/SKILL.md

@@ -2,7 +2,7 @@
 description: "Show pipeline metrics, token savings, and performance stats — use when user asks for stats, metrics, performance, or token usage"
 ---
 <!-- mustard:generated -->
-# /stats - Pipeline Metrics
+# /stats - Pipeline Metrics (superset view)
 
 ## Trigger
 
@@ -10,7 +10,7 @@ description: "Show pipeline metrics, token savings, and performance stats — us
 
 ## Description
 
-Displays pipeline metrics including duration, API calls, retries, Pass@1 success rate, tool breakdown, RTK token savings, gate saves, wave reentries, and skill hit rate per agent.
+Superset view of pipeline state + enforcement hooks + RTK token economy. This is the primary command; `/mustard:metrics` is a focused view for hook-only events and `--compare` windows.
 
 ## Action
 
@@ -18,21 +18,14 @@ Displays pipeline metrics including duration, API calls, retries, Pass@1 success
 2. Present the output to the user
 3. If no metrics found, inform user to run a pipeline first
 
-## Pass@1 Metrics
+## Sections emitted
 
-`metrics-collect.js` emits a `## Pass@1 Metrics` section at the end of completed-pipeline output:
-
-- **Pass@1**: percentage of pipelines completed without any retries (retries === 0)
-- **Avg retries**: mean retry count across all completed pipelines
-
-Example output:
-```
-## Pass@1 Metrics
-- Pass@1: 80% (4/5 completed without retries)
-- Avg retries per pipeline: 0.4
-```
-
-This section is omitted automatically when no completed pipelines exist yet.
+- **Summary** — 5–8 lines with ✓/⚠/→ prefixes (pipelines tracked, orphans, Pass@1, RTK savings, top alert)
+- **Active / Orphaned (per spec)** — duration, API calls, retries, top 3 tools, retries by phase, gate saves, wave reentries, skill hits, Pass@1 by agent (heuristic)
+- **Completed Pipelines** — archived runs from `.claude/metrics/`
+- **Last 7 Days** — events per day + current week vs prior week delta
+- **Enforcement Events (hooks)** — table of events from `.claude/.metrics/*.jsonl`
+- **RTK Token Economy** — totals from `rtk gain`
 
 ## When to Use
 

package/templates/scripts/_rtk-gain.js

@@ -0,0 +1,50 @@
+'use strict';
+/**
+ * Shared helper: normalize `rtk gain --all --format json` output.
+ *
+ * rtk emits { summary: { total_saved, avg_savings_pct, total_input,
+ * total_output, total_commands }, daily, weekly, monthly }. Different
+ * rtk versions (and earlier mustard scripts) assumed top-level
+ * `saved_tokens`/`total_saved` — neither is correct on current rtk.
+ * This helper is the single source of truth.
+ */
+
+const { execFileSync } = require('child_process');
+
+function getRtkGain(opts) {
+  const timeout = (opts && opts.timeout) || 3000;
+  let raw;
+  try {
+    raw = execFileSync('rtk', ['gain', '--all', '--format', 'json'], {
+      encoding: 'utf8',
+      timeout,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+    });
+  } catch {
+    return null;
+  }
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const s = (data && data.summary) || data || {};
+  const saved = Number(s.total_saved ?? s.saved_tokens ?? s.savedTokens ?? 0) || 0;
+  const original = Number(s.total_input ?? s.total_original ?? 0) || 0;
+  const pct = Number(s.avg_savings_pct ?? s.savings_pct ?? s.savingsPct ?? 0) || 0;
+  const commands = Number(s.total_commands ?? s.commands ?? 0) || 0;
+  if (saved <= 0 && commands <= 0) return null;
+  return {
+    saved,
+    originalTotal: original,
+    pct,
+    commands,
+    byCommand: (data && data.by_command) || null,
+    daily: (data && Array.isArray(data.daily)) ? data.daily : [],
+    weekly: (data && Array.isArray(data.weekly)) ? data.weekly : [],
+  };
+}
+
+module.exports = { getRtkGain };

package/templates/scripts/metrics-collect.js

@@ -1,227 +1,418 @@
 #!/usr/bin/env node
+'use strict';
 /**
- * METRICS-COLLECT: Collect and display pipeline metrics
+ * METRICS-COLLECT: Unified pipeline + hook + RTK metrics view.
  *
- * Reads metrics from:
- * - Active pipeline states (.pipeline-states/*.json)
- * - Completed pipeline archives (.claude/metrics/*.json)
- * - RTK gain data (if available)
+ * Sources:
+ * - .claude/.pipeline-states/{spec}.metrics.json  (sidecar written by metrics-tracker hook)
+ * - .claude/.pipeline-states/{spec}.json          (main state; optional, for orphan detection)
+ * - .claude/metrics/{spec}.json                   (archived pipelines, written by /complete)
+ * - .claude/.metrics/*.jsonl                      (hook enforcement events)
+ * - `rtk gain --all --format json`                (token economy, via _rtk-gain helper)
  *
- * Output: Formatted markdown to stdout
+ * Flags:
+ *   --hooks-only   Emit only Summary + Enforcement Events + RTK (skip per-spec sections)
  *
- * @version 1.0.0
+ * Output: Markdown to stdout. Summary block first (5–8 lines with
+ * ✓/⚠/→ prefixes), then drill-down sections.
  */
 
-const { execSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
+const { getRtkGain } = require('./_rtk-gain.js');
+
+const args = process.argv.slice(2);
+const HOOKS_ONLY = args.includes('--hooks-only');
 
 function main() {
   const cwd = process.cwd();
   const claudeDir = path.join(cwd, '.claude');
-  const parts = [];
 
+  const specs = HOOKS_ONLY ? { active: [], orphaned: [] } : collectSpecs(claudeDir);
+  const archives = HOOKS_ONLY ? [] : collectArchives(claudeDir);
+  const hookEvents = aggregateHookEvents(path.join(claudeDir, '.metrics'));
+  const rtk = safe(() => getRtkGain({ timeout: 3000 }));
+  const weekly = HOOKS_ONLY ? null : buildWeekly(path.join(claudeDir, '.metrics'));
+
+  const parts = [];
   parts.push('# Pipeline Metrics');
   parts.push('');
 
-  // Active & Orphaned pipelines
-  //
-  // A pipeline-state file is "Active" iff its spec still lives in
-  // .claude/spec/active/{name}/. If the spec has moved to completed/ or no
-  // longer exists, the state file is an orphan — reported under a separate
-  // heading so users can reconcile it via /mustard:complete or /mustard:maint.
-  const statesDir = path.join(claudeDir, '.pipeline-states');
-  const activeSpecDir = path.join(claudeDir, 'spec', 'active');
-  if (fs.existsSync(statesDir)) {
-    const files = fs.readdirSync(statesDir).filter(f => f.endsWith('.json') && !f.endsWith('.metrics.json'));
-    const activeBuckets = [];
-    const orphanedBuckets = [];
-    for (const f of files) {
-      try {
-        const state = JSON.parse(fs.readFileSync(path.join(statesDir, f), 'utf8'));
-        if (!state.metrics) continue;
-        const name = f.replace('.json', '');
-        const specPath = path.join(activeSpecDir, name);
-        const isOrphaned = !fs.existsSync(specPath);
-        const m = state.metrics;
-        const duration = m.startedAt ? formatDuration(new Date(m.startedAt), new Date()) : 'unknown';
-        const lines = [];
-        lines.push(`## ${isOrphaned ? 'Orphaned' : 'Active'}: ${name}`);
-        lines.push(`- Duration: ${duration}`);
-        lines.push(`- API calls: ${m.apiCalls || 0}`);
-        lines.push(`- Hook retries: ${m.retries || 0}`);
-        if (m.toolBreakdown && Object.keys(m.toolBreakdown).length > 0) {
-          lines.push('- Tool breakdown:');
-          for (const [tool, count] of Object.entries(m.toolBreakdown).sort((a, b) => b[1] - a[1])) {
-            lines.push(`  - ${tool}: ${count}`);
-          }
-        }
-        if (m.gate_saves !== undefined) lines.push(`- Gate saves: ${m.gate_saves}`);
-        if (m.wave_reentry !== undefined) lines.push(`- Wave reentries: ${m.wave_reentry}`);
-        if (m.skillHits && Object.keys(m.skillHits).length > 0) {
-          lines.push('- Skill hits:');
-          for (const [agent, hits] of Object.entries(m.skillHits).sort()) {
-            const pct = hits.loaded > 0 ? Math.round((hits.read / hits.loaded) * 100) + '%' : '\u2014';
-            lines.push(`  - ${agent}: ${hits.read}/${hits.loaded} (${pct})`);
-          }
-        }
-        if (isOrphaned) {
-          lines.push('- Spec: not in spec/active/ (likely completed without /mustard:complete)');
-        }
-        lines.push('');
-        (isOrphaned ? orphanedBuckets : activeBuckets).push(lines);
-      } catch {}
+  // ── Summary (always first) ───────────────────────────────────────────
+  const summaryLines = buildSummary({ specs, archives, hookEvents, rtk });
+  if (summaryLines.length > 0) {
+    parts.push('## Summary');
+    for (const l of summaryLines) parts.push(l);
+    parts.push('');
+  }
+
+  // ── Per-spec drill-down ──────────────────────────────────────────────
+  if (!HOOKS_ONLY) {
+    renderSpecs(parts, specs.active, 'Active');
+    renderSpecs(parts, specs.orphaned, 'Orphaned');
+    if (specs.orphaned.length > 0) {
+      parts.push(`> ${specs.orphaned.length} orphaned pipeline state(s) detected. Run \`/mustard:complete {spec-name}\` or \`/mustard:maint\` to reconcile.`);
+      parts.push('');
+    }
+    renderArchives(parts, archives);
+  }
+
+  // ── Last 7 Days (temporal dimension) ─────────────────────────────────
+  if (weekly && weekly.hasData) {
+    parts.push('## Last 7 Days');
+    parts.push('');
+    parts.push('| Day | Events |');
+    parts.push('|-----|--------|');
+    for (const [day, count] of weekly.days) {
+      parts.push(`| ${day} | ${count} |`);
     }
-    for (const block of activeBuckets) for (const line of block) parts.push(line);
-    for (const block of orphanedBuckets) for (const line of block) parts.push(line);
-    if (orphanedBuckets.length > 0) {
-      parts.push(`> ${orphanedBuckets.length} orphaned pipeline state(s) detected. Run \`/mustard:complete {spec-name}\` or \`/mustard:maint\` to reconcile.`);
+    parts.push('');
+    if (weekly.delta) {
+      parts.push(`- Current week: ${weekly.currentCount} events`);
+      parts.push(`- Previous week: ${weekly.prevCount} events`);
+      parts.push(`- Delta: ${weekly.delta}`);
       parts.push('');
     }
   }
-  // Completed pipelines (archived metrics)
+
+  // ── Enforcement Events (hooks) ───────────────────────────────────────
+  if (hookEvents.total > 0) {
+    parts.push('## Enforcement Events (hooks)');
+    parts.push('');
+    parts.push('| Event | Count | Tokens Affected | Tokens Saved |');
+    parts.push('|-------|-------|-----------------|--------------|');
+    let tc = 0, ta = 0, ts = 0;
+    for (const evt of Object.keys(hookEvents.byEvent).sort()) {
+      const e = hookEvents.byEvent[evt];
+      const aff = e.tokensAffected > 0 ? e.tokensAffected : '-';
+      const sav = e.tokensSaved > 0 ? e.tokensSaved : '-';
+      parts.push(`| ${evt} | ${e.count} | ${aff} | ${sav} |`);
+      tc += e.count;
+      ta += e.tokensAffected;
+      ts += e.tokensSaved;
+    }
+    parts.push('|-------|-------|-----------------|--------------|');
+    parts.push(`| **TOTAL** | ${tc} | ${ta || '-'} | ${ts || '-'} |`);
+    parts.push('');
+  }
+
+  // ── RTK Token Economy ────────────────────────────────────────────────
+  if (rtk && rtk.saved > 0) {
+    parts.push('## RTK Token Economy');
+    parts.push(`- Total saved: ${Math.round(rtk.saved / 1000)}k tokens`);
+    parts.push(`- Savings rate: ${Math.round(rtk.pct)}%`);
+    if (rtk.commands > 0) parts.push(`- Commands rewritten: ${rtk.commands}`);
+    parts.push('');
+  }
+
+  if (parts.length <= 2) {
+    parts.push('No metrics data found. Run a pipeline first.');
+  }
+
+  console.log(parts.join('\n'));
+  process.exit(0);
+}
+
+// ── Data collection ────────────────────────────────────────────────────
+
+function collectSpecs(claudeDir) {
+  const statesDir = path.join(claudeDir, '.pipeline-states');
+  const activeSpecDir = path.join(claudeDir, 'spec', 'active');
+  const out = { active: [], orphaned: [] };
+  if (!fs.existsSync(statesDir)) return out;
+
+  // Union of spec names from sidecars AND main state files. Sidecars are the
+  // primary metrics source (see metrics-tracker.js); main state may be absent
+  // after archival but sidecars can linger — we still want to surface them.
+  const seen = new Set();
+  for (const f of fs.readdirSync(statesDir)) {
+    if (f.endsWith('.metrics.json')) seen.add(f.slice(0, -'.metrics.json'.length));
+    else if (f.endsWith('.json')) seen.add(f.slice(0, -'.json'.length));
+  }
+
+  for (const name of seen) {
+    const mainPath = path.join(statesDir, `${name}.json`);
+    const sidecarPath = path.join(statesDir, `${name}.metrics.json`);
+    const sidecar = readJson(sidecarPath);
+    const main = readJson(mainPath);
+    const m = (sidecar && sidecar.metrics) || (main && main.metrics) || null;
+    if (!m) continue;
+
+    const specPath = path.join(activeSpecDir, name);
+    const isOrphaned = !fs.existsSync(specPath);
+    const entry = { name, metrics: m, isOrphaned, main };
+    (isOrphaned ? out.orphaned : out.active).push(entry);
+  }
+  return out;
+}
+
+function collectArchives(claudeDir) {
   const metricsDir = path.join(claudeDir, 'metrics');
-  if (fs.existsSync(metricsDir)) {
-    const files = fs.readdirSync(metricsDir).filter(f => f.endsWith('.json'));
-    if (files.length > 0) {
-      parts.push('## Completed Pipelines');
-      parts.push('');
+  if (!fs.existsSync(metricsDir)) return [];
+  const files = fs.readdirSync(metricsDir).filter(f => f.endsWith('.json'));
+  const out = [];
+  for (const f of files) {
+    const data = readJson(path.join(metricsDir, f));
+    if (!data) continue;
+    out.push({ name: f.replace(/\.json$/, ''), metrics: data });
+  }
+  return out;
+}
 
-      let totalCalls = 0;
-      let totalRetries = 0;
-      let totalDurationMs = 0;
-      let count = 0;
-
-      // Show last 10
-      const sorted = files.sort().reverse().slice(0, 10);
-      for (const f of sorted) {
-        try {
-          const m = JSON.parse(fs.readFileSync(path.join(metricsDir, f), 'utf8'));
-          const name = f.replace('.json', '');
-          const duration = m.durationMs ? formatMs(m.durationMs) : 'unknown';
-          parts.push(`### ${name}`);
-          parts.push(`- Duration: ${duration}`);
-          parts.push(`- API calls: ${m.apiCalls || 0}`);
-          parts.push(`- Hook retries: ${m.retries || 0}`);
-          if (m.rtkSavings) {
-            parts.push(`- RTK savings: ${m.rtkSavings.pct}% (${Math.round((m.rtkSavings.saved || 0) / 1000)}k tokens)`);
-          }
-          parts.push('');
-
-          totalCalls += m.apiCalls || 0;
-          totalRetries += m.retries || 0;
-          totalDurationMs += m.durationMs || 0;
-          count++;
-        } catch {}
+function aggregateHookEvents(metricsDir) {
+  const result = { byEvent: {}, byDay: {}, total: 0 };
+  if (!fs.existsSync(metricsDir)) return result;
+  const files = fs.readdirSync(metricsDir).filter(f => f.endsWith('.jsonl'));
+  for (const file of files) {
+    let content;
+    try { content = fs.readFileSync(path.join(metricsDir, file), 'utf8'); }
+    catch { continue; }
+    for (const raw of content.split('\n')) {
+      const line = raw.trim();
+      if (!line) continue;
+      let entry;
+      try { entry = JSON.parse(line); } catch { continue; }
+      if (!entry.event) continue;
+      const k = entry.event;
+      if (!result.byEvent[k]) result.byEvent[k] = { count: 0, tokensAffected: 0, tokensSaved: 0 };
+      result.byEvent[k].count++;
+      result.total++;
+      if (typeof entry.tokens_affected === 'number') result.byEvent[k].tokensAffected += entry.tokens_affected;
+      // PR1: rtk-rewrite tokens_saved is heuristic; real numbers come from rtk-gain.
+      if (typeof entry.tokens_saved === 'number' && entry.event !== 'rtk-rewrite') {
+        result.byEvent[k].tokensSaved += entry.tokens_saved;
       }
-
-      if (count > 0) {
-        parts.push('## Averages (last ' + count + ' pipelines)');
-        parts.push(`- Avg duration: ${formatMs(Math.round(totalDurationMs / count))}`);
-        parts.push(`- Avg API calls: ${Math.round(totalCalls / count)}`);
-        parts.push(`- Avg hook retries: ${Math.round(totalRetries / count)}`);
-        parts.push('');
+      if (entry.ts) {
+        const day = String(entry.ts).slice(0, 10);
+        result.byDay[day] = (result.byDay[day] || 0) + 1;
       }
+    }
+  }
+  return result;
+}
 
-      // Gate & Quality metrics — aggregated across all completed pipelines
-      {
-        let totalGateSaves = 0;
-        let totalWaveReentry = 0;
-        const skillHitAgg = {}; // { agentType: { loaded: N, read: M } }
-        let hasGateData = false;
-
-        for (const f of files) {
-          try {
-            const m = JSON.parse(fs.readFileSync(path.join(metricsDir, f), 'utf8'));
-            if (m.gate_saves !== undefined || m.wave_reentry !== undefined || m.skillHits) {
-              hasGateData = true;
-            }
-            totalGateSaves += m.gate_saves || 0;
-            totalWaveReentry += m.wave_reentry || 0;
-            if (m.skillHits && typeof m.skillHits === 'object') {
-              for (const [agent, hits] of Object.entries(m.skillHits)) {
-                if (!skillHitAgg[agent]) skillHitAgg[agent] = { loaded: 0, read: 0 };
-                skillHitAgg[agent].loaded += hits.loaded || 0;
-                skillHitAgg[agent].read += hits.read || 0;
-              }
-            }
-          } catch {}
-        }
-
-        parts.push('## Gate & Quality Metrics');
-        parts.push('- Gate saves: ' + (hasGateData ? totalGateSaves : '\u2014') + (hasGateData ? ' (spec revisions after /approve)' : ''));
-        parts.push('- Wave reentries: ' + (hasGateData ? totalWaveReentry : '\u2014') + (hasGateData ? ' (EXECUTE \u2192 PLAN)' : ''));
-        parts.push('- Skill hit rate:');
-        const agentKeys = Object.keys(skillHitAgg);
-        if (agentKeys.length > 0) {
-          parts.push('');
-          parts.push('| Agent | Loaded | Read | Hit rate |');
-          parts.push('|-------|--------|------|----------|');
-          for (const agent of agentKeys.sort()) {
-            const { loaded, read } = skillHitAgg[agent];
-            const hitPct = loaded > 0 ? Math.round((read / loaded) * 100) + '%' : '\u2014';
-            parts.push(`| ${agent} | ${loaded} | ${read} | ${hitPct} |`);
-          }
-        } else {
-          parts.push('  (no skill tracking data yet)');
-        }
-        parts.push('');
-      }
+function buildWeekly(metricsDir) {
+  const agg = aggregateHookEvents(metricsDir);
+  if (agg.total === 0) return { hasData: false };
+  const now = new Date();
+  const days = [];
+  for (let i = 6; i >= 0; i--) {
+    const d = new Date(now.getTime() - i * 86400000);
+    const key = d.toISOString().slice(0, 10);
+    days.push([key, agg.byDay[key] || 0]);
+  }
+  // Current week vs prior week (14-day window split in half, ending today).
+  let currentCount = 0, prevCount = 0;
+  for (let i = 0; i < 7; i++) {
+    const d = new Date(now.getTime() - i * 86400000).toISOString().slice(0, 10);
+    currentCount += agg.byDay[d] || 0;
+  }
+  for (let i = 7; i < 14; i++) {
+    const d = new Date(now.getTime() - i * 86400000).toISOString().slice(0, 10);
+    prevCount += agg.byDay[d] || 0;
+  }
+  const delta = (currentCount || prevCount) ? cell(prevCount, currentCount) : null;
+  return { hasData: days.some(d => d[1] > 0), days, currentCount, prevCount, delta };
+}
 
-      // Pass@1 metrics — computed across ALL completed pipeline files (not just last 10)
-      var pass1Count = 0;
-      var totalPipelines = 0;
-      var totalRetrySum = 0;
-      for (var i = 0; i < files.length; i++) {
-        try {
-          var m = JSON.parse(fs.readFileSync(path.join(metricsDir, files[i]), 'utf8'));
-          totalPipelines++;
-          totalRetrySum += (m.retries || 0);
-          if ((m.retries || 0) === 0) pass1Count++;
-        } catch {}
-      }
-      if (totalPipelines > 0) {
-        var pass1Pct = Math.round((pass1Count / totalPipelines) * 100);
-        var avgRetries = (totalRetrySum / totalPipelines).toFixed(1);
-        parts.push('## Pass@1 Metrics');
-        parts.push('- Pass@1 (hook-level): ' + pass1Pct + '% (' + pass1Count + '/' + totalPipelines + ' completed with zero hook retries)');
-        parts.push('- Avg hook retries per pipeline: ' + avgRetries);
-        parts.push('- Note: counts hook/sandbox events, not agent redispatches. True agent-level Pass@1 not yet tracked.');
-        parts.push('');
+// ── Summary ────────────────────────────────────────────────────────────
+
+function buildSummary({ specs, archives, hookEvents, rtk }) {
+  const lines = [];
+  const activeN = specs.active.length;
+  const orphanN = specs.orphaned.length;
+  const totalSpecs = activeN + orphanN;
+
+  if (totalSpecs > 0) {
+    lines.push(`→ ${totalSpecs} pipeline${totalSpecs === 1 ? '' : 's'} tracked (sidecar) · ${archives.length} archived`);
+  } else if (archives.length > 0) {
+    lines.push(`→ ${archives.length} archived pipeline${archives.length === 1 ? '' : 's'}`);
+  }
+
+  if (orphanN > 0) {
+    lines.push(`⚠ ${orphanN} orphaned state${orphanN === 1 ? '' : 's'} (spec not in active/) — run /mustard:maint`);
+  }
+
+  // Pass@1: percentage of tracked specs with zero hook retries.
+  if (totalSpecs > 0) {
+    let pass = 0;
+    for (const group of [specs.active, specs.orphaned]) {
+      for (const s of group) if ((s.metrics.retries || 0) === 0) pass++;
+    }
+    const pct = Math.round((pass / totalSpecs) * 100);
+    const prefix = pct >= 80 ? '✓' : pct >= 50 ? '→' : '⚠';
+    lines.push(`${prefix} Pass@1 (hook-level): ${pct}% (${pass}/${totalSpecs} without hook retries)`);
+  }
+
+  if (rtk && rtk.saved > 0) {
+    lines.push(`✓ RTK savings: ~${Math.round(rtk.saved / 1000)}k tokens (${Math.round(rtk.pct)}%)`);
+  }
+
+  // Top alert: spec with highest retry count on any single phase ≥ 3.
+  const alert = findTopAlert([...specs.active, ...specs.orphaned]);
+  if (alert) lines.push(`⚠ ${alert}`);
+
+  return lines;
+}
+
+function findTopAlert(allSpecs) {
+  let worst = null;
+  for (const s of allSpecs) {
+    const attempts = s.metrics.agentAttempts || {};
+    for (const [phase, n] of Object.entries(attempts)) {
+      if (n >= 3 && (!worst || n > worst.n)) worst = { name: s.name, phase, n };
+    }
+  }
+  if (!worst) return null;
+  return `1 pipeline with ${worst.n} retries in ${worst.phase} (${worst.name})`;
+}
+
+// ── Rendering ──────────────────────────────────────────────────────────
+
+function renderSpecs(parts, list, label) {
+  // Sort for stable output: newest date prefix first (names begin with YYYY-MM-DD).
+  const sorted = list.slice().sort((a, b) => b.name.localeCompare(a.name));
+  for (const s of sorted) {
+    const m = s.metrics;
+    const duration = m.startedAt ? formatDuration(new Date(m.startedAt), new Date(m.updatedAt || Date.now())) : 'unknown';
+    parts.push(`## ${label}: ${s.name}`);
+    parts.push(`- Duration: ${duration}`);
+    parts.push(`- API calls: ${m.apiCalls || 0}`);
+    parts.push(`- Hook retries: ${m.retries || 0}`);
+
+    if (m.toolBreakdown && Object.keys(m.toolBreakdown).length > 0) {
+      const top = Object.entries(m.toolBreakdown)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 3)
+        .map(([t, n]) => `${t}:${n}`)
+        .join(', ');
+      parts.push(`- Top tools: ${top}`);
+    }
+
+    if (m.agentAttempts && Object.keys(m.agentAttempts).length > 0) {
+      const entries = Object.entries(m.agentAttempts).map(([phase, n]) => {
+        const mark = n >= 3 ? ' ⚠' : '';
+        return `${phase}:${n}${mark}`;
+      });
+      parts.push(`- Retries by phase: ${entries.join(', ')}`);
+    }
+
+    if (m.gate_saves !== undefined) parts.push(`- Gate saves: ${m.gate_saves}`);
+    if (m.wave_reentry !== undefined) parts.push(`- Wave reentries: ${m.wave_reentry}`);
+
+    if (m.skillHits && Object.keys(m.skillHits).length > 0) {
+      parts.push('- Skill hits:');
+      for (const [agent, hits] of Object.entries(m.skillHits).sort()) {
+        const pct = hits.loaded > 0 ? Math.round((hits.read / hits.loaded) * 100) + '%' : '—';
+        parts.push(`  - ${agent}: ${hits.read}/${hits.loaded} (${pct})`);
       }
     }
+
+    // Pass@1 per agent (heuristic): cross subagent-registry with agentAttempts.
+    const pass1 = agentPass1(s);
+    if (pass1 && pass1.length > 0) {
+      parts.push('- Pass@1 by agent (heuristic):');
+      for (const row of pass1) parts.push(`  - ${row}`);
+    }
+
+    if (s.isOrphaned) {
+      parts.push('- Spec: not in spec/active/ (likely completed without /mustard:complete)');
+    }
+    parts.push('');
   }
+}
 
-  // RTK total savings
-  try {
-    const raw = execSync('rtk gain --all --format json', {
-      encoding: 'utf8',
-      timeout: 3000,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-    });
-    const rtk = JSON.parse(raw);
-    const saved = rtk.saved_tokens ?? rtk.savedTokens ?? 0;
-    const pct = rtk.savings_pct ?? rtk.savingsPct ?? 0;
-    if (saved > 0) {
-      parts.push('## RTK Token Economy');
-      parts.push(`- Total saved: ${Math.round(saved / 1000)}k tokens`);
-      parts.push(`- Savings rate: ${Math.round(pct)}%`);
-      parts.push('');
+function agentPass1(spec) {
+  const registryPath = path.join(process.cwd(), '.claude', '.subagent-registry.json');
+  const registry = readJson(registryPath);
+  if (!registry) return null;
+  const attempts = spec.metrics.agentAttempts || {};
+  const anyRetry = Object.values(attempts).some(n => n > 0);
+  const agents = new Set();
+  for (const entry of Object.values(registry)) {
+    if (entry && entry.agentType) agents.add(entry.agentType);
+  }
+  if (agents.size === 0) return null;
+  const rows = [];
+  for (const agent of [...agents].sort()) {
+    rows.push(`${agent}: ${anyRetry ? 'advisory (retries present)' : '100%'}`);
+  }
+  return rows.slice(0, 5);
+}
+
+function renderArchives(parts, archives) {
+  if (archives.length === 0) return;
+  parts.push('## Completed Pipelines');
+  parts.push('');
+
+  let totalCalls = 0;
+  let totalRetries = 0;
+  let totalDurationMs = 0;
+  let count = 0;
+  const sorted = archives.slice().sort((a, b) => b.name.localeCompare(a.name)).slice(0, 10);
+  for (const a of sorted) {
+    const m = a.metrics;
+    const duration = m.durationMs ? formatMs(m.durationMs) : 'unknown';
+    parts.push(`### ${a.name}`);
+    parts.push(`- Duration: ${duration}`);
+    parts.push(`- API calls: ${m.apiCalls || 0}`);
+    parts.push(`- Hook retries: ${m.retries || 0}`);
+    if (m.rtkSavings) {
+      parts.push(`- RTK savings: ${m.rtkSavings.pct}% (${Math.round((m.rtkSavings.saved || 0) / 1000)}k tokens)`);
     }
-  } catch {} // RTK not available
+    parts.push('');
+    totalCalls += m.apiCalls || 0;
+    totalRetries += m.retries || 0;
+    totalDurationMs += m.durationMs || 0;
+    count++;
+  }
+  if (count > 0) {
+    parts.push(`## Averages (last ${count} pipelines)`);
+    parts.push(`- Avg duration: ${formatMs(Math.round(totalDurationMs / count))}`);
+    parts.push(`- Avg API calls: ${Math.round(totalCalls / count)}`);
+    parts.push(`- Avg hook retries: ${Math.round(totalRetries / count)}`);
+    parts.push('');
+  }
 
-  if (parts.length <= 2) {
-    parts.push('No metrics data found. Run a pipeline first.');
+  // Pass@1 across all archives.
+  let pass1Count = 0;
+  let retrySum = 0;
+  for (const a of archives) {
+    if ((a.metrics.retries || 0) === 0) pass1Count++;
+    retrySum += a.metrics.retries || 0;
   }
+  const pct = Math.round((pass1Count / archives.length) * 100);
+  const avg = (retrySum / archives.length).toFixed(1);
+  parts.push('## Pass@1 Metrics (archived)');
+  parts.push(`- Pass@1 (hook-level): ${pct}% (${pass1Count}/${archives.length} completed with zero hook retries)`);
+  parts.push(`- Avg hook retries per pipeline: ${avg}`);
+  parts.push('');
+}
 
-  console.log(parts.join('\n'));
-  process.exit(0);
+// ── Small helpers ──────────────────────────────────────────────────────
+
+function readJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch { return null; }
+}
+
+function safe(fn) {
+  try { return fn(); } catch { return null; }
+}
+
+function pct(ref, cur) {
+  if (ref === 0) return cur === 0 ? '0%' : 'n/a';
+  const d = ((cur - ref) / ref) * 100;
+  const s = d > 0 ? '+' : '';
+  return `${s}${d.toFixed(1)}%`;
+}
+
+function cell(ref, cur) {
+  return `${ref}→${cur} (${pct(ref, cur)})`;
 }
 
 function formatDuration(start, end) {
-  const ms = end.getTime() - start.getTime();
-  return formatMs(ms);
+  return formatMs(end.getTime() - start.getTime());
 }
 
 function formatMs(ms) {

package/templates/scripts/metrics-report.js

@@ -12,6 +12,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
+const { getRtkGain } = require('./_rtk-gain.js');
 
 const METRICS_DIR = process.env.MUSTARD_METRICS_DIR
   ? path.resolve(process.env.MUSTARD_METRICS_DIR)
@@ -276,71 +277,49 @@ console.log(sep);
 console.log(`| **TOTAL** | ${totalCount} | ${totalAffected || '-'} | ${totalSaved || '-'} | - |`);
 
 // ── RTK Integration ────────────────────────────────────────────────────
-// Query RTK for actual savings data (if RTK is installed)
-try {
-  let rtkAvailable = false;
-  try {
-    if (process.platform === 'win32') {
-      execFileSync('where', ['rtk'], { stdio: 'ignore' });
-    } else {
-      execFileSync('which', ['rtk'], { stdio: 'ignore' });
-    }
-    rtkAvailable = true;
-  } catch (_) {}
-
-  if (rtkAvailable) {
-    const rtkRaw = execFileSync('rtk', ['gain', '--all', '--format', 'json'], {
-      encoding: 'utf8',
-      timeout: 5000,
-      stdio: ['pipe', 'pipe', 'ignore'],
-    });
-    const rtkData = JSON.parse(rtkRaw);
-
-    console.log('');
-    console.log('## RTK Token Savings');
-    console.log('');
-
-    if (rtkData.total_saved !== undefined) {
-      const totalSaved = rtkData.total_saved || 0;
-      const totalOriginal = rtkData.total_original || 0;
-      const pct = totalOriginal > 0 ? Math.round((totalSaved / totalOriginal) * 100) : 0;
-      console.log(`| Metric | Value |`);
-      console.log(`|--------|-------|`);
-      console.log(`| Total tokens saved | ${totalSaved.toLocaleString()} |`);
-      console.log(`| Total original tokens | ${totalOriginal.toLocaleString()} |`);
-      console.log(`| Savings rate | ${pct}% |`);
-      console.log(`| Commands rewritten | ${rtkData.total_commands || '-'} |`);
-    }
+// Query RTK via shared helper (handles field shape + missing binary).
+const rtk = (() => {
+  try { return getRtkGain({ timeout: 5000 }); } catch (_) { return null; }
+})();
+
+if (rtk && rtk.saved > 0) {
+  console.log('');
+  console.log('## RTK Token Savings');
+  console.log('');
+  console.log(`| Metric | Value |`);
+  console.log(`|--------|-------|`);
+  console.log(`| Total tokens saved | ${rtk.saved.toLocaleString()} |`);
+  if (rtk.originalTotal > 0) {
+    console.log(`| Total original tokens | ${rtk.originalTotal.toLocaleString()} |`);
+  }
+  console.log(`| Savings rate | ${Math.round(rtk.pct)}% |`);
+  if (rtk.commands > 0) {
+    console.log(`| Commands rewritten | ${rtk.commands} |`);
+  }
 
-    // Per-command breakdown if available
-    if (rtkData.by_command && typeof rtkData.by_command === 'object') {
-      const cmds = Object.entries(rtkData.by_command);
-      if (cmds.length > 0) {
-        console.log('');
-        console.log('### By Command');
-        console.log('| Command | Saved | Original | Rate |');
-        console.log('|---------|-------|----------|------|');
-        for (const [cmd, stats] of cmds.sort((a, b) => (b[1].saved || 0) - (a[1].saved || 0)).slice(0, 10)) {
-          const saved = stats.saved || 0;
-          const orig = stats.original || 0;
-          const rate = orig > 0 ? Math.round((saved / orig) * 100) + '%' : '-';
-          console.log(`| ${cmd} | ${saved.toLocaleString()} | ${orig.toLocaleString()} | ${rate} |`);
-        }
+  if (rtk.byCommand && typeof rtk.byCommand === 'object') {
+    const cmds = Object.entries(rtk.byCommand);
+    if (cmds.length > 0) {
+      console.log('');
+      console.log('### By Command');
+      console.log('| Command | Saved | Original | Rate |');
+      console.log('|---------|-------|----------|------|');
+      for (const [cmd, stats] of cmds.sort((a, b) => (b[1].saved || 0) - (a[1].saved || 0)).slice(0, 10)) {
+        const saved = stats.saved || 0;
+        const orig = stats.original || 0;
+        const rate = orig > 0 ? Math.round((saved / orig) * 100) + '%' : '-';
+        console.log(`| ${cmd} | ${saved.toLocaleString()} | ${orig.toLocaleString()} | ${rate} |`);
       }
     }
   }
-} catch (_) {
-  // RTK not installed or gain command failed — skip section silently
 }
 
-// ── Correlation: hook rewrites vs RTK actual savings ──────────────────
+// ── Correlation: hook rewrites (count only; tokens_saved is dropped by design). ──
 if (agg['rtk-rewrite']) {
   const hookRewrites = agg['rtk-rewrite'].count;
-  const hookEstimatedSaved = agg['rtk-rewrite'].tokensSaved;
   console.log('');
   console.log('## RTK Hook Activity');
   console.log(`| Metric | Value |`);
   console.log(`|--------|-------|`);
   console.log(`| Commands rewritten by hook | ${hookRewrites} |`);
-  console.log(`| Estimated tokens saved | ${hookEstimatedSaved > 0 ? hookEstimatedSaved.toLocaleString() : '-'} |`);
 }