clud-bug 0.6.12 → 0.6.14

package/bin/clud-bug.js

@@ -2,7 +2,7 @@
 import { mkdir, writeFile, readFile } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
+import { spawnSync, spawn } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 
@@ -18,6 +18,7 @@ import { runUpdate } from '../lib/update.js';
 import { getPendingWorkflowEdits, makeBranchName, git as gitCmd } from '../lib/edit-workflow.js';
 import { applyToRepo as applyAgentDocs } from '../lib/agents-md.js';
 import { detectRepo, detectDefaultBranch, getProtectionState, enableConversationResolution } from '../lib/branch-protection.js';
+import { computeReviewCost, costPerLOC, cacheHitRate, extractTokensFromLog, rollup, formatRollup } from '../lib/usage.js';
 
 const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const TEMPLATES = join(PKG_ROOT, 'templates');
@@ -28,6 +29,8 @@ function parseArgs(argv) {
     _: [], offline: false, acceptAll: false, commit: false, help: false, version: false,
     since: null, changedIn: null, scopes: [], out: null,
     setProtection: true, quiet: false,
+    // 0.0.M.1 (v0.6.13): `clud-bug usage` flags.
+    repo: null, pr: null, limit: null, json: false,
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -42,6 +45,10 @@ function parseArgs(argv) {
     else if (a === '--scope') args.scopes.push(argv[++i]);
     else if (a === '--out') args.out = argv[++i];
     else if (a === '--no-set-protection') args.setProtection = false;
+    else if (a === '--repo') args.repo = argv[++i];
+    else if (a === '--pr') args.pr = Number(argv[++i]);
+    else if (a === '--limit') args.limit = Number(argv[++i]);
+    else if (a === '--json') args.json = true;
     else args._.push(a);
   }
   return args;
@@ -64,6 +71,11 @@ Commands:
                         templates. Custom and skills.sh-installed specimens left alone.
   edit-workflow         Helper for editing .github/workflows/clud-bug-*.yml in an isolated
                         PR (the action refuses to review PRs that modify its own workflow).
+  usage                 Read recent clud-bug-review run JSON + normalize cost per LOC.
+                        Internal Q7-clud-bug enforcement dashboard. Reports cache hit
+                        rate, 30-day rolling \$/LOC trend, per-repo/per-model
+                        distributions, and outliers (> 2x org median).
+                        Use --pr / --repo / --since / --limit / --json to filter.
 
 Options:
   --offline             Skip skills.sh; pin only the bundled baseline specimens.
@@ -78,6 +90,12 @@ Options:
                         required_conversation_resolution on the default
                         branch (init only). Use for repos that manage
                         branch protection via ruleset or org policy.
+  --repo <owner/name>   Restrict \`usage\` to a single repo. Default: all repos
+                        with clud-bug-review.yml in the gh user's auth scope.
+  --pr <N>              Restrict \`usage\` to a single PR.
+  --limit <N>           Max reviews to fetch (default 50; the API caps).
+  --json                Emit JSON instead of human-readable output.
+                        Compatible with --quiet for pipeline consumption.
   --since <date>        Audit only files changed in commits after <date> (git date string).
   --changed-in <dur>    Audit only files changed in the past <dur>: 7d, 2w, 1mo, 1y. (audit only)
   --scope <glob>        Limit audit to files matching <glob>; repeatable. (audit only)
@@ -107,6 +125,7 @@ async function main() {
     case 'audit':   return runAudit(args);
     case 'update':  return runUpdateCmd(args);
     case 'edit-workflow': return runEditWorkflow(args);
+    case 'usage':   return runUsage(args);
     default:
       process.stderr.write(`Unknown command: ${cmd || '(none)'}\n\n${HELP}`);
       process.exit(2);
@@ -707,6 +726,202 @@ async function runAudit(args) {
   ok(`audit: ${files.length} file${files.length === 1 ? '' : 's'} surveyed; stub at ${rel(cwd, outPath)}`);
 }
 
+// 0.0.M.1 (v0.6.13): Q7-clud-bug $/LOC dashboard.
+//
+// Reads recent clud-bug-review run JSON via `gh run list` + per-job logs
+// (which contain the SDK result messages with token counts + model),
+// joins to `gh pr view --json additions,deletions` for the LOC denominator,
+// and reports the rollup. Internal-only — not consumer-facing.
+//
+// Default scope: 30 days, all repos with clud-bug-review.yml in the gh
+// user's auth scope. --repo / --pr / --since / --limit narrow.
+async function runUsage(args) {
+  const limit = args.limit ?? 50;
+  const since = args.since ?? '30d';
+
+  // Determine target repos. If --repo specified, just that one. Otherwise
+  // discover repos via the local gh user's auth scope (the org's repos we
+  // own clud-bug-review on).
+  const repos = args.repo
+    ? [args.repo]
+    : await discoverConsumingRepos();
+
+  if (repos.length === 0) {
+    process.stderr.write(
+      'clud-bug usage: no repos with clud-bug-review.yml found in your gh scope.\n' +
+      'Pass --repo <owner/name> to point at a specific repo.\n'
+    );
+    process.exit(2);
+  }
+
+  // Per-repo: list recent clud-bug-review runs + extract the per-run job
+  // logs + per-PR LOC counts. Filter to PR runs (drop schedule/dispatch).
+  // PR #104 fix: --pr filter must be applied AFTER resolvePrNumber
+  // (we don't have the PR # until then). prFilter on listRecentRuns was
+  // promised but never applied — bug caught by clud-bug self-review.
+  const reviews = [];
+  for (const repo of repos) {
+    const runs = await listRecentRuns(repo, limit, since, args.pr);
+    if (process.env.CLUD_BUG_DEBUG) process.stderr.write(`DBG: ${repo} runs=${runs.length}\n`);
+    for (const run of runs) {
+      const review = await fetchReviewRecord(repo, run);
+      if (process.env.CLUD_BUG_DEBUG) process.stderr.write(`DBG:   ${run.databaseId} ${run.conclusion} → ${review ? 'OK' : 'NULL'}\n`);
+      if (!review) continue;
+      // --pr filter: drop reviews whose PR doesn't match.
+      if (args.pr != null && review.pr !== args.pr) continue;
+      reviews.push(review);
+    }
+  }
+
+  if (reviews.length === 0) {
+    process.stderr.write(
+      `clud-bug usage: no clud-bug-review runs found in scope.\n` +
+      `  scope: ${repos.length} repo${repos.length === 1 ? '' : 's'}, last ${since}, limit ${limit}.\n`
+    );
+    process.exit(2);
+  }
+
+  const summary = rollup(reviews);
+  process.stdout.write(formatRollup(summary, { json: args.json }));
+  if (!args.json) {
+    ok(`usage: ${reviews.length} review${reviews.length === 1 ? '' : 's'} across ${repos.length} repo${repos.length === 1 ? '' : 's'}`);
+  }
+}
+
+// `gh repo list` won't filter by workflow file content, so we iterate
+// repos the user has access to and probe for clud-bug-review.yml. We
+// limit to 100 to avoid pagination explosions.
+async function discoverConsumingRepos() {
+  const list = await ghJson(['repo', 'list', '--limit', '100', '--json', 'nameWithOwner']);
+  if (!Array.isArray(list)) return [];
+  const owners = list.map((e) => e.nameWithOwner);
+  const found = [];
+  for (const ownerRepo of owners) {
+    const probe = await gh(['api', `repos/${ownerRepo}/contents/.github/workflows/clud-bug-review.yml`, '-q', '.size']);
+    if (probe.code === 0 && probe.stdout.trim().length > 0) {
+      found.push(ownerRepo);
+    }
+  }
+  return found;
+}
+
+// List recent clud-bug-review.yml runs in a repo. Filters to PR events
+// (drops schedule, workflow_dispatch — those have no PR LOC denominator).
+//
+// IMPORTANT (Q7 measurement integrity, fixed during PR #104 review):
+// We INCLUDE conclusion === 'failure' runs because Anthropic bills for
+// tokens regardless of GitHub workflow conclusion. A run that hit the
+// spend cap, errored mid-action, or failed strict-mode still incurred
+// real API cost — silently excluding it would underreport spend and
+// fool the Q7-clud-bug "gradient must point down" gate.
+// extractTokensFromLog() returns ok:false on logs without usable token
+// totals, which gracefully skips the cancelled/errored-too-early case
+// without losing accountability for the partially-billed runs.
+async function listRecentRuns(repo, limit, since, prFilter) {
+  const sinceDate = since.match(/^\d+[dwmy]$/) ? dateAgo(since) : null;
+  const args = [
+    'run', 'list', '-R', repo,
+    '--workflow', 'clud-bug-review.yml',
+    '--limit', String(limit),
+    '--json', 'databaseId,headSha,createdAt,event,status,conclusion',
+  ];
+  if (sinceDate) args.push('--created', `>=${sinceDate}`);
+  const runs = await ghJson(args);
+  if (!Array.isArray(runs)) return [];
+  return runs
+    .filter((r) => r.event === 'pull_request' && (r.conclusion === 'success' || r.conclusion === 'failure'))
+    .map((r) => ({ ...r, repo }))
+    .slice(0, limit);
+}
+
+async function fetchReviewRecord(repo, run) {
+  // Find the clud-bug-review JOB id within the run.
+  const jobs = await ghJson(['api', `repos/${repo}/actions/runs/${run.databaseId}/jobs`, '-q', '.jobs']);
+  if (!Array.isArray(jobs)) return null;
+  const job = jobs.find((j) => j.name === 'clud-bug-review');
+  if (!job) return null;
+
+  // Fetch the job's log dump. May be large.
+  const logs = await gh(['api', `repos/${repo}/actions/jobs/${job.id}/logs`]);
+  if (logs.code !== 0) return null;
+
+  // Extract tokens + model from the SDK result-message JSON in the log.
+  const extracted = extractTokensFromLog(logs.stdout);
+  if (!extracted.ok) return null;
+
+  // Resolve the PR number from the run's pull_requests array or by SHA.
+  const prNumber = await resolvePrNumber(repo, run);
+  if (!prNumber) return null;
+
+  // Pull LOC denominator from the PR.
+  const prMeta = await ghJson(['pr', 'view', String(prNumber), '-R', repo, '--json', 'additions,deletions,number']);
+  if (!prMeta || typeof prMeta.additions !== 'number') return null;
+
+  const tokens = extracted.tokens;
+  const model = extracted.model;
+  const costInfo = computeReviewCost(tokens, model);
+  return {
+    repo,
+    pr: prNumber,
+    createdAt: run.createdAt,
+    model: costInfo.model,                  // normalized (PRICING key)
+    modelObserved: model,                   // raw value from log (may be versioned)
+    unknownModel: costInfo.unknownModel,    // PR #104 fix: surface for dashboard warn
+    tokens,
+    additions: prMeta.additions,
+    deletions: prMeta.deletions,
+    cost: costInfo.total,
+    costPerLOC: costPerLOC(costInfo.total, prMeta.additions, prMeta.deletions),
+    cacheRate: cacheHitRate(tokens),
+  };
+}
+
+async function resolvePrNumber(repo, run) {
+  // gh's run JSON sometimes carries a `pull_requests` array; if not (or
+  // if it's empty because the PR has been merged), look up via the
+  // commits/{sha}/pulls endpoint, which includes merged/closed PRs.
+  const detail = await ghJson(['api', `repos/${repo}/actions/runs/${run.databaseId}`, '-q', '.pull_requests']);
+  if (Array.isArray(detail) && detail[0]?.number) return detail[0].number;
+  // commits/{sha}/pulls returns PRs that contain the commit — works for
+  // open AND merged/closed PRs. The default `gh pr list -S <sha>` does
+  // not search closed PRs and silently returns empty for the merged
+  // case, which made every $/LOC lookup fail on historical PRs.
+  const pulls = await ghJson(['api', `repos/${repo}/commits/${run.headSha}/pulls`, '-q', '[.[].number]']);
+  if (Array.isArray(pulls) && pulls.length > 0) return pulls[0];
+  return null;
+}
+
+function dateAgo(spec) {
+  // spec like "30d", "2w", "1m", "1y" → ISO date N units ago.
+  const m = spec.match(/^(\d+)([dwmy])$/);
+  if (!m) return null;
+  const n = Number(m[1]);
+  const unit = m[2];
+  const day = 24 * 60 * 60 * 1000;
+  const ms = n * (unit === 'd' ? day : unit === 'w' ? 7 * day : unit === 'm' ? 30 * day : 365 * day);
+  return new Date(Date.now() - ms).toISOString().slice(0, 10);
+}
+
+// gh helpers (reuse pattern from lib/branch-protection.js so callers can
+// stub `gh` in tests if they want — but for now spawn directly).
+function gh(args) {
+  return new Promise((resolve) => {
+    const child = spawn('gh', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.stderr.on('data', (d) => { stderr += d; });
+    child.on('error', () => resolve({ code: 1, stdout: '', stderr: 'gh not on PATH' }));
+    child.on('close', (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+async function ghJson(args) {
+  const { code, stdout } = await gh(args);
+  if (code !== 0) return null;
+  try { return JSON.parse(stdout); } catch { return null; }
+}
+
 function rel(from, to) {
   return to.startsWith(from + '/') ? to.slice(from.length + 1) : to;
 }

package/lib/usage.js

@@ -0,0 +1,401 @@
+// lib/usage.js — Q7-clud-bug $/LOC compute.
+//
+// Pure functions, no I/O. Driven from bin/clud-bug.js which fetches workflow
+// run JSON + PR metadata via gh CLI. Implementation of the 0.0.M.1 dashboard
+// per the Phase 0.5 plan.
+//
+// Reads:
+//   - clud-bug-review job logs (via `gh api .../jobs/<id>/logs`), which
+//     contain the SDK's `result` messages including:
+//       "model": "claude-sonnet-4-6"
+//       "input_tokens": N
+//       "output_tokens": N
+//       "cache_read_input_tokens": N
+//       "cache_creation_input_tokens": N
+//   - `gh pr view --json additions,deletions` for the LOC denominator.
+//
+// Computes:
+//   $/LOC = total_cost(tokens, model) / (additions + deletions)
+//
+// Q7-clud-bug enforcement: dashboard reports the 30-day rolling trend; the
+// next Phase 0.5 PR ships when the trend stops declining.
+
+// Anthropic pricing as of 2026-05 (per MTok). Cache write is 1.25× input
+// per Anthropic's published 5-min-TTL ephemeral cache rate.
+export const PRICING = {
+  'claude-sonnet-4-6': {
+    input: 3.0, output: 15.0, cacheRead: 0.30, cacheWrite: 3.75,
+  },
+  'claude-haiku-4-5-20251001': {
+    input: 0.80, output: 4.0, cacheRead: 0.08, cacheWrite: 1.0,
+  },
+  'claude-opus-4-7': {
+    input: 15.0, output: 75.0, cacheRead: 1.50, cacheWrite: 18.75,
+  },
+};
+
+// Fallback when the model field is missing or new. Use Sonnet pricing —
+// conservative for unknown-but-likely-Sonnet, undercounts Opus until we
+// update the table. The `unknown` flag in the result lets callers warn.
+const DEFAULT_MODEL = 'claude-sonnet-4-6';
+
+/**
+ * Compute the USD cost of a single clud-bug review from token counts +
+ * model. All four token classes are billed independently.
+ *
+ * Returns:
+ *   {
+ *     total: number  USD,
+ *     parts: { input, output, cacheRead, cacheWrite } USD breakdown,
+ *     model: string (normalized),
+ *     unknownModel: boolean (true if we used DEFAULT_MODEL pricing),
+ *   }
+ */
+export function computeReviewCost(tokens, model) {
+  const t = {
+    input: tokens.input_tokens || 0,
+    output: tokens.output_tokens || 0,
+    cacheRead: tokens.cache_read_input_tokens || 0,
+    cacheWrite: tokens.cache_creation_input_tokens || 0,
+  };
+  const normalized = model && PRICING[model] ? model : DEFAULT_MODEL;
+  const p = PRICING[normalized];
+  const parts = {
+    input: (t.input / 1e6) * p.input,
+    output: (t.output / 1e6) * p.output,
+    cacheRead: (t.cacheRead / 1e6) * p.cacheRead,
+    cacheWrite: (t.cacheWrite / 1e6) * p.cacheWrite,
+  };
+  const total = parts.input + parts.output + parts.cacheRead + parts.cacheWrite;
+  return {
+    total,
+    parts,
+    model: normalized,
+    unknownModel: !(model && PRICING[model]),
+  };
+}
+
+/**
+ * $/LOC for a single review. PR size denominator is additions + deletions
+ * — the same metric `gh pr view --json additions,deletions` returns.
+ *
+ * Returns 0 if additions + deletions === 0 (avoid div-by-zero on
+ * docs-only / empty PRs); callers can filter zero-LOC reviews out of
+ * trend lines as outliers.
+ */
+export function costPerLOC(cost, additions, deletions) {
+  const loc = (additions || 0) + (deletions || 0);
+  if (loc === 0) return 0;
+  return cost / loc;
+}
+
+/**
+ * Cache hit rate: cached_read / (cached_read + creation + input).
+ * Cached creation is the cost of WRITING new entries (paid 1.25× per
+ * Anthropic); cached read is what we get back at 10% of input price.
+ * High hit rate proves the v0.6.3 caching layer is firing on
+ * re-reviews and fix-pushes.
+ */
+export function cacheHitRate(tokens) {
+  const read = tokens.cache_read_input_tokens || 0;
+  const write = tokens.cache_creation_input_tokens || 0;
+  const input = tokens.input_tokens || 0;
+  const denom = read + write + input;
+  if (denom === 0) return 0;
+  return read / denom;
+}
+
+/**
+ * Parse the model + token counts from a clud-bug-review job log dump.
+ *
+ * PR #104 fix (token double-count): the SDK's stream-output emits a
+ * `"type": "result"` event at the end of a review with a CUMULATIVE
+ * `usage` block. It ALSO emits per-turn `"type": "assistant"` events
+ * (each with its own usage), AND the result event's usage contains an
+ * `iterations` array of per-message breakdowns. Naively summing every
+ * `"input_tokens"` occurrence in the log would triple-or-more count
+ * the same tokens.
+ *
+ * Right approach: locate the FINAL `"type": "result"` event and extract
+ * the FIRST `"usage": {`-block within it. That's the cumulative bill,
+ * the same number Anthropic charges. If no result event exists, the
+ * review didn't complete successfully — return ok:false so the caller
+ * skips this run rather than trusting partial token data.
+ *
+ * Returns:
+ *   {
+ *     model: string | null,
+ *     tokens: { input, output, cacheRead, cacheWrite } | null,
+ *     ok: boolean (false if no result event — partial / errored job),
+ *   }
+ */
+export function extractTokensFromLog(logText) {
+  if (typeof logText !== 'string' || logText.length === 0) {
+    return { model: null, tokens: null, ok: false };
+  }
+
+  // The LAST model field — final message wins (a multi-turn review
+  // uses the same model throughout). Captured before the usage parse
+  // so model is reported even when we can't find a result event.
+  const modelMatches = [...logText.matchAll(/"model"\s*:\s*"([^"]+)"/g)];
+  const model = modelMatches.length > 0
+    ? modelMatches[modelMatches.length - 1][1]
+    : null;
+
+  // Locate the final result event. There may be multiple over the
+  // life of a long-running session — take the LAST one.
+  const resultMarkerRe = /"type"\s*:\s*"result"/g;
+  let lastResultIdx = -1;
+  let m;
+  while ((m = resultMarkerRe.exec(logText)) !== null) {
+    lastResultIdx = m.index;
+  }
+
+  if (lastResultIdx < 0) {
+    // No result event — partial log or job that errored before
+    // emitting one. Don't sum the per-turn fields; the data isn't
+    // billable-equivalent.
+    return { model, tokens: null, ok: false };
+  }
+
+  // Within the result event, find the first `"usage": {` and extract
+  // its top-level token fields. We scope each field's regex to a window
+  // starting at the usage block so we don't pick up the `iterations`
+  // array's per-message fields (which are nested deeper but still
+  // appear within the same overall result block).
+  const fromResult = logText.slice(lastResultIdx);
+  const usageIdx = fromResult.search(/"usage"\s*:\s*\{/);
+  if (usageIdx < 0) {
+    return { model, tokens: null, ok: false };
+  }
+  // Slice up to the start of `"iterations"` (if present) so we don't
+  // double-count per-iteration breakdowns nested inside usage.
+  const fromUsage = fromResult.slice(usageIdx);
+  const iterationsIdx = fromUsage.search(/"iterations"\s*:/);
+  const usageOnly = iterationsIdx >= 0
+    ? fromUsage.slice(0, iterationsIdx)
+    : fromUsage;
+
+  const pluck = (re) => {
+    const match = usageOnly.match(re);
+    return match ? Number(match[1]) : 0;
+  };
+
+  const input = pluck(/"input_tokens"\s*:\s*(\d+)/);
+  const output = pluck(/"output_tokens"\s*:\s*(\d+)/);
+  const cacheRead = pluck(/"cache_read_input_tokens"\s*:\s*(\d+)/);
+  const cacheWrite = pluck(/"cache_creation_input_tokens"\s*:\s*(\d+)/);
+
+  const anyTokens = input + output + cacheRead + cacheWrite;
+  if (anyTokens === 0) {
+    return { model, tokens: null, ok: false };
+  }
+
+  return {
+    model,
+    tokens: {
+      input_tokens: input,
+      output_tokens: output,
+      cache_read_input_tokens: cacheRead,
+      cache_creation_input_tokens: cacheWrite,
+    },
+    ok: true,
+  };
+}
+
+/**
+ * Roll up an array of per-review records into a structured summary.
+ *
+ * Each review record:
+ *   {
+ *     repo: "owner/name",
+ *     pr: number,
+ *     createdAt: ISO 8601,
+ *     model: string,
+ *     tokens: { ... },
+ *     additions: number,
+ *     deletions: number,
+ *     cost: number (USD, total),
+ *     costPerLOC: number,
+ *     cacheRate: number (0..1),
+ *   }
+ *
+ * Returns:
+ *   {
+ *     total: { reviews, cost, loc, costPerLOC (median), cacheRate (median) },
+ *     perRepo: { [repo]: { ... } },
+ *     perModel: { [model]: { ... } },
+ *     trend30d: { dailyMedians: [...], slopePct (MoM) },
+ *     outliers: [{ review, severity }],
+ *   }
+ *
+ * Pre-conditions: callers should drop zero-LOC reviews before passing in.
+ */
+export function rollup(reviews) {
+  const valid = reviews.filter((r) => r.costPerLOC > 0);
+
+  const total = {
+    reviews: valid.length,
+    cost: valid.reduce((a, r) => a + r.cost, 0),
+    loc: valid.reduce((a, r) => a + (r.additions + r.deletions), 0),
+    costPerLOC: median(valid.map((r) => r.costPerLOC)),
+    cacheRate: median(valid.map((r) => r.cacheRate)),
+  };
+
+  const groupBy = (key) => {
+    const out = {};
+    for (const r of valid) {
+      const k = r[key];
+      if (!out[k]) out[k] = { reviews: 0, cost: 0, loc: 0, costPerLOCs: [], cacheRates: [] };
+      out[k].reviews += 1;
+      out[k].cost += r.cost;
+      out[k].loc += r.additions + r.deletions;
+      out[k].costPerLOCs.push(r.costPerLOC);
+      out[k].cacheRates.push(r.cacheRate);
+    }
+    for (const k of Object.keys(out)) {
+      out[k].costPerLOC = median(out[k].costPerLOCs);
+      out[k].cacheRate = median(out[k].cacheRates);
+      delete out[k].costPerLOCs;
+      delete out[k].cacheRates;
+    }
+    return out;
+  };
+
+  const perRepo = groupBy('repo');
+  const perModel = groupBy('model');
+
+  // Outliers: > 2× total.costPerLOC.
+  const outliers = valid
+    .filter((r) => r.costPerLOC > total.costPerLOC * 2)
+    .map((r) => ({
+      repo: r.repo, pr: r.pr,
+      costPerLOC: r.costPerLOC,
+      multiple: r.costPerLOC / total.costPerLOC,
+      cost: r.cost,
+      reason: r.cacheRate < 0.3 ? 'low cache hit' : 'unknown',
+    }));
+
+  // 30-day trend: median $/LOC per calendar day. Bucket by createdAt date.
+  // Slope reported as MoM % change between the most recent 30-day window's
+  // median and the previous 30-day window's median.
+  const trend30d = computeTrend(valid);
+
+  // PR #104 fix: surface reviews whose model wasn't in PRICING. The
+  // computeReviewCost fallback applied Sonnet rates to unknown models
+  // (~5× undercount of Opus), AND bucketed them under Sonnet in the
+  // per-model table — exactly the false-good signal Q7 must NOT produce.
+  // Caller renders this as a loud warning so the dashboard reader knows
+  // to update the PRICING table.
+  const unknownModelReviews = valid
+    .filter((r) => r.unknownModel === true)
+    .map((r) => ({ repo: r.repo, pr: r.pr, modelObserved: r.modelObserved }));
+
+  return { total, perRepo, perModel, trend30d, outliers, unknownModelReviews };
+}
+
+function median(nums) {
+  if (nums.length === 0) return 0;
+  const sorted = [...nums].sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0
+    ? (sorted[mid - 1] + sorted[mid]) / 2
+    : sorted[mid];
+}
+
+function computeTrend(reviews) {
+  // PR #104 fix: distinguish "no prior window" (previous bucket empty)
+  // from "exactly flat trend" (current === previous > 0). The original
+  // code returned slopePct=0 for both, which masked the dangerous case
+  // — a stable expensive month-over-month trend rendered as if there
+  // were no comparison data, hiding the very signal Q7 enforces.
+  // `previous: null` now means "no prior window"; renderer keys on this.
+  if (reviews.length === 0) {
+    return { current: 0, previous: null, slopePct: null };
+  }
+  const now = Date.now();
+  const day = 24 * 60 * 60 * 1000;
+  const currentWindow = reviews.filter((r) => now - new Date(r.createdAt).getTime() <= 30 * day);
+  const previousWindow = reviews.filter((r) => {
+    const age = now - new Date(r.createdAt).getTime();
+    return age > 30 * day && age <= 60 * day;
+  });
+  const current = median(currentWindow.map((r) => r.costPerLOC));
+  if (previousWindow.length === 0) {
+    return { current, previous: null, slopePct: null };
+  }
+  const previous = median(previousWindow.map((r) => r.costPerLOC));
+  // previous > 0 because every review in valid[] has costPerLOC > 0
+  // (zero-LOC reviews dropped upstream).
+  const slopePct = previous > 0 ? ((current - previous) / previous) * 100 : null;
+  return { current, previous, slopePct };
+}
+
+/**
+ * Render the rollup as a human-readable table. Mirrors the sample output
+ * from the Phase 0.5 plan.
+ *
+ * Pass `{ json: true }` for the machine-readable form (the same data
+ * the rollup() function returns).
+ */
+export function formatRollup(rollup, opts = {}) {
+  if (opts.json) {
+    return JSON.stringify(rollup, null, 2);
+  }
+  const lines = [];
+  const t = rollup.total;
+  const trend = rollup.trend30d;
+  // PR #104 fix: null slopePct = "no prior window" (prior 30d bucket
+  // was empty). A REAL 0% slope (flat trend) renders as "→ 0% MoM",
+  // not as "(no prior window)" — masking the latter was the bug.
+  let trendStr;
+  if (trend.slopePct === null) {
+    trendStr = '(no prior window)';
+  } else {
+    const trendArrow = trend.slopePct < 0 ? '↓' : trend.slopePct > 0 ? '↑' : '→';
+    trendStr = `${trendArrow} ${trend.slopePct.toFixed(0)}% MoM`;
+  }
+  lines.push(`ok: ${t.reviews} reviews, 30-day $/LOC trend: ${trendStr}`);
+
+  const perRepoEntries = Object.entries(rollup.perRepo)
+    .sort((a, b) => b[1].costPerLOC - a[1].costPerLOC);
+  if (perRepoEntries.length > 0) {
+    lines.push('  per-repo $/LOC (most → least expensive):');
+    for (const [repo, stats] of perRepoEntries) {
+      const cache = `${(stats.cacheRate * 100).toFixed(0)}% cached`;
+      lines.push(
+        `    ${repo.padEnd(28)} ${`$${stats.costPerLOC.toFixed(4)}/LOC`.padEnd(16)} · ${String(stats.reviews).padStart(2)} reviews · ${cache}`
+      );
+    }
+  }
+
+  lines.push(
+    `  org median $/LOC: $${t.costPerLOC.toFixed(4)} · org cache hit: ${(t.cacheRate * 100).toFixed(0)}%`
+  );
+  lines.push(`  total spend: $${t.cost.toFixed(2)} across ${(t.loc).toLocaleString()} LOC`);
+
+  if (rollup.outliers.length > 0) {
+    lines.push(`  outliers (>2× median):`);
+    for (const o of rollup.outliers) {
+      lines.push(
+        `    ${o.repo}#${o.pr} ($${o.costPerLOC.toFixed(4)}/LOC, ${o.multiple.toFixed(1)}× median — ${o.reason})`
+      );
+    }
+  }
+
+  // PR #104 fix: loud warning when one or more reviews used a model
+  // not in PRICING (we fell back to Sonnet rates — that can undercount
+  // by ~5× if the real model was an Opus variant). Update PRICING and
+  // re-run.
+  if (rollup.unknownModelReviews && rollup.unknownModelReviews.length > 0) {
+    lines.push(
+      `  ⚠️  ${rollup.unknownModelReviews.length} review${rollup.unknownModelReviews.length === 1 ? '' : 's'} used model${rollup.unknownModelReviews.length === 1 ? '' : 's'} not in PRICING; cost may be undercounted:`
+    );
+    const observed = new Set(rollup.unknownModelReviews.map((u) => u.modelObserved));
+    for (const m of observed) {
+      lines.push(`    seen: "${m}" — add to lib/usage.js PRICING table`);
+    }
+  }
+
+  return lines.join('\n') + '\n';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clud-bug",
-  "version": "0.6.12",
+  "version": "0.6.14",
   "description": "Skill-driven Claude PR review. Ship a brand-voice skill, get brand reviews. Each finding cites the skill that motivated it. CLI installs the workflow + a baseline kit; add more from skills.sh.",
   "homepage": "https://cludbug.dev",
   "bugs": "https://github.com/thrillmade/clud-bug/issues",

package/templates/workflow-py.yml.tmpl

@@ -6,7 +6,40 @@ on:
     types: [opened, synchronize]
 
 jobs:
+  # Pre-flight (v0.6.14 / 0.0.W) — see workflow.yml.tmpl for design notes.
+  paths-check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      is_workflow_only: ${{ steps.classify.outputs.is_workflow_only }}
+    steps:
+      - name: Classify PR diff
+        id: classify
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+        run: |
+          CHANGED=$(gh pr diff "$PR_NUMBER" -R "$REPO" --name-only)
+          if [ -z "$CHANGED" ]; then echo "is_workflow_only=false" >> "$GITHUB_OUTPUT"; exit 0; fi
+          IS_WORKFLOW_ONLY=true
+          while IFS= read -r f; do
+            case "$f" in
+              .github/workflows/clud-bug-*.yml) ;;
+              .github/actions/strict-mode-gate/*) ;;
+              *) IS_WORKFLOW_ONLY=false; break ;;
+            esac
+          done <<< "$CHANGED"
+          echo "is_workflow_only=$IS_WORKFLOW_ONLY" >> "$GITHUB_OUTPUT"
+          if [ "$IS_WORKFLOW_ONLY" = "true" ]; then
+            echo "::notice title=Clud Bug 🐛::Skipping LLM review — workflow-only PR."
+          fi
+
   clud-bug-review:
+    needs: paths-check
+    if: needs.paths-check.outputs.is_workflow_only != 'true'
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -85,6 +118,6 @@ jobs:
       # Strict-mode gate — composite action; see workflow.yml.tmpl for design notes.
       - name: Strict mode — fail check on critical findings
         if: success()
-        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.12
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.14
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}

package/templates/workflow-ts.yml.tmpl

@@ -6,7 +6,40 @@ on:
     types: [opened, synchronize]
 
 jobs:
+  # Pre-flight (v0.6.14 / 0.0.W) — see workflow.yml.tmpl for design notes.
+  paths-check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      is_workflow_only: ${{ steps.classify.outputs.is_workflow_only }}
+    steps:
+      - name: Classify PR diff
+        id: classify
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+        run: |
+          CHANGED=$(gh pr diff "$PR_NUMBER" -R "$REPO" --name-only)
+          if [ -z "$CHANGED" ]; then echo "is_workflow_only=false" >> "$GITHUB_OUTPUT"; exit 0; fi
+          IS_WORKFLOW_ONLY=true
+          while IFS= read -r f; do
+            case "$f" in
+              .github/workflows/clud-bug-*.yml) ;;
+              .github/actions/strict-mode-gate/*) ;;
+              *) IS_WORKFLOW_ONLY=false; break ;;
+            esac
+          done <<< "$CHANGED"
+          echo "is_workflow_only=$IS_WORKFLOW_ONLY" >> "$GITHUB_OUTPUT"
+          if [ "$IS_WORKFLOW_ONLY" = "true" ]; then
+            echo "::notice title=Clud Bug 🐛::Skipping LLM review — workflow-only PR."
+          fi
+
   clud-bug-review:
+    needs: paths-check
+    if: needs.paths-check.outputs.is_workflow_only != 'true'
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -85,6 +118,6 @@ jobs:
       # Strict-mode gate — composite action; see workflow.yml.tmpl for design notes.
       - name: Strict mode — fail check on critical findings
         if: success()
-        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.12
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.14
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}

package/templates/workflow.yml.tmpl

@@ -6,7 +6,51 @@ on:
     types: [opened, synchronize]
 
 jobs:
+  # Pre-flight (v0.6.14 / 0.0.W): if the PR ONLY touches clud-bug workflow
+  # files or the strict-mode-gate composite action, skip the LLM review
+  # entirely. claude-code-action would refuse to run on such a PR anyway
+  # (self-modification guard — required for security), and a template
+  # re-render has no useful review surface. Skipping turns a previously
+  # required-admin-bypass merge into a normal one, AND saves the LLM
+  # call cost. Security: the classifier requires ALL changed files to
+  # match the allow-list — a mixed PR (workflow + code) still runs the
+  # review normally.
+  paths-check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      is_workflow_only: ${{ steps.classify.outputs.is_workflow_only }}
+    steps:
+      - name: Classify PR diff
+        id: classify
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+        run: |
+          CHANGED=$(gh pr diff "$PR_NUMBER" -R "$REPO" --name-only)
+          if [ -z "$CHANGED" ]; then
+            echo "is_workflow_only=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          IS_WORKFLOW_ONLY=true
+          while IFS= read -r f; do
+            case "$f" in
+              .github/workflows/clud-bug-*.yml) ;;
+              .github/actions/strict-mode-gate/*) ;;
+              *) IS_WORKFLOW_ONLY=false; break ;;
+            esac
+          done <<< "$CHANGED"
+          echo "is_workflow_only=$IS_WORKFLOW_ONLY" >> "$GITHUB_OUTPUT"
+          if [ "$IS_WORKFLOW_ONLY" = "true" ]; then
+            echo "::notice title=Clud Bug 🐛::Skipping LLM review — PR only touches workflow files (claude-code-action would refuse anyway due to self-modification guard)."
+          fi
+
   clud-bug-review:
+    needs: paths-check
+    if: needs.paths-check.outputs.is_workflow_only != 'true'
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -145,6 +189,6 @@ jobs:
       # Letting the action's own failure fail the check is louder and right.
       - name: Strict mode — fail check on critical findings
         if: success()
-        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.12
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.14
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}