clud-bug 0.6.28 → 0.6.30

package/bin/clud-bug.js

@@ -33,6 +33,10 @@ function parseArgs(argv) {
     repo: null, pr: null, limit: null, json: false,
     // 0.0.O (v0.6.22): `clud-bug render` reads its payload from stdin.
     stdin: false,
+    // v0.6.30: cross-review aggregation read source for `usage --health`.
+    // Defaults to true (artifact mode); `--no-artifacts` forces local
+    // .clud-bug.json read (matches v0.6.28 behavior).
+    artifacts: true,
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -53,6 +57,7 @@ function parseArgs(argv) {
     else if (a === '--json') args.json = true;
     else if (a === '--stdin') args.stdin = true;
     else if (a === '--health') args.health = true;
+    else if (a === '--no-artifacts') args.artifacts = false;
     else args._.push(a);
   }
   return args;
@@ -80,16 +85,27 @@ Commands:
                         rate, 30-day rolling \$/LOC trend, per-repo/per-model
                         distributions, and outliers (> 2x org median).
                         Use --pr / --repo / --since / --limit / --json to filter.
-  usage --health        Deterministic skill-health dashboard (v0.6.28). Reads
-                        \`.claude/skills/.clud-bug.json\` usage block + renders
-                        archive-candidate / stale / new / healthy status per skill.
-                        Read-only — no automation acts on the output. Humans
-                        decide which skills to prune. Workflow integration ships
-                        in v0.6.29; today this command surfaces whatever data
-                        has been written manually or by future runs.
+  usage --health        Deterministic skill-health dashboard. Renders archive-
+                        candidate / stale / new / healthy status per skill, applying
+                        the v0.6.28 thresholds (citations==0 + loads>=5 → archive
+                        candidate; last cited >60d → stale; etc.). Read-only —
+                        humans decide what to prune.
+                        Read source (v0.6.30): by default, walks
+                        \`clud-bug-skill-usage-pr-*\` workflow artifacts uploaded
+                        by every clud-bug-review run and accumulates them into
+                        one org-level snapshot. Pass \`--repo owner/name\` to
+                        target a specific repo; otherwise infers from the local
+                        git remote. \`--no-artifacts\` falls back to reading the
+                        local \`.claude/skills/.clud-bug.json\` (v0.6.28 behavior).
   eval                  Run the golden-set regression gate against the rendered review
                         prompt (must-contain / must-not-contain / byte-budget). Same as
                         \`node --test test/prompts.eval.test.js\` but works from any cwd.
+  update-skill-usage    Update the .claude/skills/.clud-bug.json usage block from
+                        a structured-output JSON payload (the action's
+                        \`outputs.structured_output\`). Called as a workflow
+                        post-step alongside \`render\` (v0.6.29 / Component 4).
+                        Pipe the JSON to stdin. Idempotent + atomic write.
+                        Silent no-op on empty stdin (parity with \`render\`).
   render --stdin        Render a structured-output JSON payload (the action's
                         \`outputs.structured_output\`, piped via stdin) to the
                         GitHub-markdown summary comment shape. Invoked by the
@@ -147,6 +163,7 @@ async function main() {
     case 'usage':   return runUsage(args);
     case 'eval':    return runEval();
     case 'render':  return runRender(args);
+    case 'update-skill-usage': return runUpdateSkillUsage(args);
     default:
       process.stderr.write(`Unknown command: ${cmd || '(none)'}\n\n${HELP}`);
       process.exit(2);
@@ -193,6 +210,104 @@ async function runRender(args) {
   }
 }
 
+// v0.6.29 — Component 4. Pipe the action's structured_output through
+// the skill-usage data layer (v0.6.28) + write the merged result back
+// to .claude/skills/.clud-bug.json atomically.
+//
+// Workflow integration (post-step in workflow.yml.tmpl):
+//
+//     echo "${{ steps.review.outputs.structured_output }}" \
+//       | npx clud-bug@latest update-skill-usage --stdin
+//
+// Runs AFTER the render post-step. Silent no-op on empty stdin
+// (same contract as `render` — preserves the workflow's existing
+// "skip both if empty" branch). Idempotent: running on the same JSON
+// twice produces the same result.
+async function runUpdateSkillUsage(args) {
+  const fs = await import('node:fs/promises');
+  const path = await import('node:path');
+  const {
+    computeSkillUsageDelta,
+    mergeSkillUsage,
+  } = await import('../lib/skill-usage.js');
+
+  if (!args.stdin) {
+    process.stderr.write('clud-bug update-skill-usage: --stdin is required.\n');
+    process.exit(2);
+  }
+
+  let raw = '';
+  for await (const chunk of process.stdin) raw += chunk;
+  raw = raw.trim();
+  if (!raw) {
+    // Empty structured_output → render is also skipped → nothing to
+    // update. Match the render contract: exit 0 with a stderr note.
+    process.stderr.write('clud-bug update-skill-usage: stdin empty — no usage update.\n');
+    return;
+  }
+
+  let reviewJson;
+  try {
+    reviewJson = JSON.parse(raw);
+  } catch (e) {
+    process.stderr.write(`clud-bug update-skill-usage: invalid JSON: ${e.message}\n`);
+    process.exit(2);
+  }
+  if (!reviewJson || typeof reviewJson !== 'object') {
+    process.stderr.write('clud-bug update-skill-usage: payload must be a JSON object.\n');
+    process.exit(2);
+  }
+
+  // Compute per-review delta. Empty delta is fine — just means no
+  // skills loaded or cited (workflow-only PRs, e.g.).
+  const delta = computeSkillUsageDelta(reviewJson);
+  if (Object.keys(delta).length === 0) {
+    process.stderr.write('clud-bug update-skill-usage: no skills in payload — nothing to record.\n');
+    return;
+  }
+
+  // Read existing .clud-bug.json. The path is canonical:
+  // .claude/skills/.clud-bug.json relative to cwd (the workflow runs
+  // from the repo root).
+  const jsonPath = path.resolve(process.cwd(), '.claude', 'skills', '.clud-bug.json');
+  let parsed;
+  try {
+    const existingRaw = await fs.readFile(jsonPath, 'utf-8');
+    parsed = JSON.parse(existingRaw);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      process.stderr.write(
+        `clud-bug update-skill-usage: no .clud-bug.json at ${jsonPath} — skipping. ` +
+        `Run \`npx clud-bug init\` first.\n`
+      );
+      return;
+    }
+    process.stderr.write(`clud-bug update-skill-usage: parse failed: ${err.message}\n`);
+    process.exit(2);
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    process.stderr.write('clud-bug update-skill-usage: .clud-bug.json malformed.\n');
+    process.exit(2);
+  }
+
+  const existingUsage = parsed.usage || {};
+  const timestamp = new Date().toISOString();
+  const mergedUsage = mergeSkillUsage(existingUsage, delta, timestamp);
+  parsed.usage = mergedUsage;
+
+  // Write back ATOMICALLY: temp file + rename. Guards against a
+  // crashed write leaving the JSON half-written + unparseable on next
+  // read (which would brick the entire skill catalog).
+  const tmpPath = jsonPath + '.tmp';
+  const serialized = JSON.stringify(parsed, null, 2) + '\n';
+  await fs.writeFile(tmpPath, serialized, 'utf-8');
+  await fs.rename(tmpPath, jsonPath);
+
+  const skillCount = Object.keys(delta).length;
+  ok(`update-skill-usage: merged ${skillCount} skill${skillCount === 1 ? '' : 's'} from review`);
+}
+
+
 // 0.0.E (v0.6.17): thin wrapper around the golden-set test file. Devs
 // who follow the README invoke `clud-bug eval` — this routes to the
 // same `node --test` runner CI uses, so dev and CI verdicts match.
@@ -880,39 +995,119 @@ async function runUsage(args) {
 // v0.6.28 — `clud-bug usage --health` implementation. Reads the local
 // .claude/skills/.clud-bug.json usage block, applies deterministic
 // thresholds, renders a read-only dashboard. No I/O beyond the JSON
-// read. Workflow integration that POPULATES the usage block ships in
-// v0.6.29; today this command is the consumer half of the contract.
-async function runUsageHealth(_args) {
-  const fs = await import('node:fs/promises');
-  const path = await import('node:path');
+// read.
+//
+// v0.6.30 — read accumulated usage from workflow artifacts (uploaded
+// by v0.6.29's post-step). Defaults to artifact mode when --repo is
+// passed OR an `owner/name` can be inferred from `git remote`. Falls
+// back to the local-file path otherwise. The `--no-artifacts` flag
+// forces the v0.6.28 local-only behavior (handy for tests + offline).
+async function runUsageHealth(args) {
   const { assessSkillHealth, formatHealthDashboard } = await import('../lib/skill-usage.js');
 
-  const jsonPath = path.resolve(process.cwd(), '.claude', 'skills', '.clud-bug.json');
+  // Decide read source. Priority: explicit --no-artifacts → local;
+  // explicit --repo OR inferred owner/repo → artifacts; else local.
+  const wantArtifacts = args.artifacts !== false;
+  let ownerRepo = null;
+  if (wantArtifacts) {
+    ownerRepo = args.repo || await inferOwnerRepoFromGit();
+  }
 
-  let parsed;
+  let usage;
+  let source;
+  if (wantArtifacts && ownerRepo) {
+    const result = await loadUsageFromArtifacts(ownerRepo, args);
+    if (result) {
+      usage = result.usage;
+      source = `${result.artifactCount} artifact${result.artifactCount === 1 ? '' : 's'} from ${ownerRepo}`;
+    }
+  }
+
+  // Fallback to local .clud-bug.json (v0.6.28 behavior).
+  if (usage == null) {
+    const localResult = await loadUsageFromLocalFile();
+    if (localResult == null) {
+      // Both paths failed. The local helper has already written its
+      // own stderr explanation; we just exit.
+      process.exit(1);
+    }
+    usage = localResult;
+    source = `local .clud-bug.json`;
+  }
+
+  const rows = assessSkillHealth(usage, new Date());
+  process.stdout.write(formatHealthDashboard(rows) + '\n');
+
+  // Exit code semantics: 0 (informational). The dashboard is read-only;
+  // archive-candidates being present is NOT a failure mode — humans
+  // decide. CI gates should NOT block on this.
+  ok(`skill health: ${rows.length} skill${rows.length === 1 ? '' : 's'} tracked (source: ${source})`);
+}
+
+// Helpers split out from runUsageHealth so the two read paths are
+// independently testable + composable in future commands.
+
+async function loadUsageFromArtifacts(ownerRepo, args) {
+  const { fetchUsageArtifacts, aggregateUsageStream } = await import('../lib/skill-usage.js');
+  const [owner, repo] = ownerRepo.split('/');
+  if (!owner || !repo) {
+    process.stderr.write(`clud-bug usage --health: --repo must be in owner/name form, got "${ownerRepo}".\n`);
+    return null;
+  }
+  const since = parseSinceArg(args.since);
+  let artifacts;
+  try {
+    artifacts = await fetchUsageArtifacts({ owner, repo, since });
+  } catch (err) {
+    process.stderr.write(`::notice::clud-bug usage --health: artifact fetch failed (${err.message}) — falling back to local .clud-bug.json\n`);
+    return null;
+  }
+  if (artifacts.length === 0) {
+    process.stderr.write(`::notice::clud-bug usage --health: no skill-usage artifacts found in ${ownerRepo} — falling back to local .clud-bug.json\n`);
+    return null;
+  }
+  return {
+    usage: aggregateUsageStream(artifacts),
+    artifactCount: artifacts.length,
+  };
+}
+
+async function loadUsageFromLocalFile() {
+  const fs = await import('node:fs/promises');
+  const path = await import('node:path');
+  const jsonPath = path.resolve(process.cwd(), '.claude', 'skills', '.clud-bug.json');
   try {
     const raw = await fs.readFile(jsonPath, 'utf-8');
-    parsed = JSON.parse(raw);
+    const parsed = JSON.parse(raw);
+    return (parsed && parsed.usage) ? parsed.usage : {};
   } catch (err) {
     if (err.code === 'ENOENT') {
       process.stderr.write(
         `clud-bug usage --health: no .claude/skills/.clud-bug.json found in ${process.cwd()}.\n` +
-        `Run \`npx clud-bug init\` first to install the catalog state.\n`
+        `Run \`npx clud-bug init\` first OR pass --repo owner/name to read from workflow artifacts.\n`
       );
-      process.exit(1);
+      return null;
     }
     process.stderr.write(`clud-bug usage --health: failed to parse .clud-bug.json: ${err.message}\n`);
-    process.exit(1);
+    return null;
   }
+}
 
-  const usage = parsed && parsed.usage ? parsed.usage : {};
-  const rows = assessSkillHealth(usage, new Date());
-  process.stdout.write(formatHealthDashboard(rows) + '\n');
+async function inferOwnerRepoFromGit() {
+  // `gh repo view --json nameWithOwner` reads the current dir's git
+  // remote AND respects gh's config. Returns null on non-git dirs.
+  const result = await ghJson(['repo', 'view', '--json', 'nameWithOwner']);
+  return result && result.nameWithOwner ? result.nameWithOwner : null;
+}
 
-  // Exit code semantics: 0 (informational). The dashboard is read-only;
-  // archive-candidates being present is NOT a failure mode — humans
-  // decide. CI gates should NOT block on this.
-  ok(`skill health: ${rows.length} skill${rows.length === 1 ? '' : 's'} tracked`);
+function parseSinceArg(since) {
+  if (!since) return null;
+  if (since instanceof Date) return since;
+  const m = String(since).match(/^(\d+)([dwmy])$/);
+  if (!m) return null;
+  const n = Number(m[1]);
+  const unitMs = { d: 86400e3, w: 7 * 86400e3, m: 30 * 86400e3, y: 365 * 86400e3 }[m[2]];
+  return new Date(Date.now() - n * unitMs);
 }
 
 // limit to 100 to avoid pagination explosions.

package/lib/skill-usage.js

@@ -225,8 +225,9 @@ export function formatHealthDashboard(rows) {
     return (
       'Skill health: no usage data yet.\n\n' +
       'Usage data accumulates after clud-bug reviews land in your repo.\n' +
-      'Workflow integration ships in v0.6.29 — until then this command is\n' +
-      'a structural placeholder.'
+      'v0.6.29 wires up per-review delta writes via the workflow post-step\n' +
+      'and uploads them as 90-day artifacts. v0.6.30 will add cross-review\n' +
+      'aggregation so this dashboard reads the full artifact stream.'
     );
   }
 
@@ -259,3 +260,173 @@ export function formatHealthDashboard(rows) {
   lines.push('  healthy           = cited within 60 days');
   return lines.join('\n');
 }
+
+// ---------------------------------------------------------------------------
+// v0.6.30 — cross-review aggregation
+//
+// The v0.6.29 workflow post-step uploads `.clud-bug.json` as a per-PR
+// artifact named `clud-bug-skill-usage-pr-<N>` (90-day retention). This
+// section walks the artifact stream + accumulates into one dashboard read.
+//
+// Artifact persistence design choice (recap from v0.6.29): we picked
+// artifacts over commit-back-to-main because commit-back required
+// `contents: write` permission expansion — v0.6.23 hit a regression
+// from a similar expansion. Artifacts are GitHub-native, zero perm
+// widening, zero commit noise. v0.6.30 reads them back here.
+// ---------------------------------------------------------------------------
+
+/**
+ * Default `gh` runner — spawns the local gh CLI. Tests inject a mock.
+ *
+ * The runner has two methods:
+ *   - json(args): returns parsed JSON stdout, or null on error.
+ *   - run(args): returns {code, stdout, stderr}. For commands that
+ *     download files etc. — no JSON parsing.
+ */
+async function defaultGhJson(args) {
+  const { spawn } = await import('node:child_process');
+  return new Promise((resolve) => {
+    const child = spawn('gh', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    child.stdout.on('data', (d) => { stdout += d; });
+    child.on('error', () => resolve(null));
+    child.on('close', (code) => {
+      if (code !== 0) return resolve(null);
+      try { resolve(JSON.parse(stdout)); } catch { resolve(null); }
+    });
+  });
+}
+
+async function defaultGhRun(args) {
+  const { spawn } = await import('node:child_process');
+  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 }));
+  });
+}
+
+export const DEFAULT_GH_RUNNER = {
+  json: defaultGhJson,
+  run: defaultGhRun,
+};
+
+/**
+ * Fetch all per-PR skill-usage artifacts from a repo. Each artifact is
+ * downloaded to a temp dir, its `.clud-bug.json` is parsed, and the
+ * usage block is returned.
+ *
+ * @param {object} opts
+ * @param {string} opts.owner - GitHub repo owner.
+ * @param {string} opts.repo - GitHub repo name.
+ * @param {Date|null} opts.since - Filter to artifacts created on/after this date.
+ * @param {object} opts.ghRunner - Injected gh CLI runner (see DEFAULT_GH_RUNNER).
+ *
+ * @returns {Promise<{prNumber: number, artifactId: number, usage: object, fetchedAt: string}[]>}
+ */
+export async function fetchUsageArtifacts({ owner, repo, since = null, ghRunner = DEFAULT_GH_RUNNER }) {
+  if (!owner || !repo) {
+    throw new Error('fetchUsageArtifacts: owner + repo are required');
+  }
+
+  // List artifacts in one call. We deliberately do NOT use `--paginate`:
+  // `gh api --paginate --jq <expr>` applies the jq filter to EACH page
+  // independently and concatenates the outputs with newlines, which
+  // produces `[...]\n[...]` — invalid as a single JSON document.
+  // `JSON.parse` returns null and the dashboard silently shows nothing
+  // for repos with >30 artifacts (default page size). Caught by
+  // clud-bug-review on PR #127.
+  //
+  // `?per_page=100` covers up to 100 artifacts in one call. The 90-day
+  // artifact retention means most repos won't hit that ceiling (>100
+  // PR reviews in 90 days = >1/day sustained). If a future repo
+  // saturates this, paginate manually in v0.6.31+ (per_page=100 +
+  // explicit `?page=N` loop, parse each response as JSON, concatenate).
+  const list = await ghRunner.json([
+    'api',
+    `repos/${owner}/${repo}/actions/artifacts?per_page=100`,
+    '--jq',
+    '[.artifacts[] | select(.name | startswith("clud-bug-skill-usage-pr-")) | select(.expired == false) | {id, name, workflow_run_id: .workflow_run.id, created_at}]',
+  ]);
+
+  // `--jq '[...]'` wraps the stream into a single array. If the runner
+  // returns null (404, no auth, etc.), bail to empty list.
+  if (!Array.isArray(list)) return [];
+
+  const filtered = since
+    ? list.filter((a) => new Date(a.created_at) >= since)
+    : list;
+
+  const fs = await import('node:fs/promises');
+  const path = await import('node:path');
+  const os = await import('node:os');
+
+  const results = [];
+  for (const art of filtered) {
+    const prMatch = art.name.match(/^clud-bug-skill-usage-pr-(\d+)$/);
+    if (!prMatch) continue;
+    const prNumber = Number(prMatch[1]);
+
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'clud-bug-art-'));
+    try {
+      const dl = await ghRunner.run([
+        'run', 'download', String(art.workflow_run_id),
+        '-R', `${owner}/${repo}`,
+        '-n', art.name,
+        '-D', tmpDir,
+      ]);
+      if (dl.code !== 0) continue;
+
+      // The workflow uploaded `.clud-bug.json` (single file under the
+      // path key). `gh run download -D <dir>` writes it to the dest as
+      // `<dir>/.clud-bug.json` (preserves the source path).
+      const jsonPath = path.join(tmpDir, '.clud-bug.json');
+      let parsed;
+      try {
+        const raw = await fs.readFile(jsonPath, 'utf-8');
+        parsed = JSON.parse(raw);
+      } catch {
+        continue; // artifact corrupted or layout unexpected
+      }
+      const usage = parsed && parsed.usage ? parsed.usage : {};
+      results.push({
+        prNumber,
+        artifactId: art.id,
+        usage,
+        fetchedAt: art.created_at,
+      });
+    } finally {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Reduce an array of per-PR artifact records into a single accumulated
+ * usage block by left-folding `mergeSkillUsage` over them, ordered by
+ * `fetchedAt` ascending so the last_cited timestamp is deterministic.
+ *
+ * Because `mergeSkillUsage` is commutative for loads + citations counts
+ * AND keeps the LATEST timestamp it sees as last_cited (we sort
+ * ascending so newest wins on the final pass), out-of-order input
+ * produces an identical result.
+ *
+ * @param {{usage: object, fetchedAt: string}[]} artifacts
+ * @returns {object} accumulated usage block, shape matches mergeSkillUsage output
+ */
+export function aggregateUsageStream(artifacts) {
+  if (!Array.isArray(artifacts) || artifacts.length === 0) return {};
+  const sorted = [...artifacts].sort(
+    (a, b) => new Date(a.fetchedAt) - new Date(b.fetchedAt)
+  );
+  return sorted.reduce(
+    (acc, art) => mergeSkillUsage(acc, art.usage || {}, art.fetchedAt),
+    {}
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clud-bug",
-  "version": "0.6.28",
+  "version": "0.6.30",
   "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

@@ -283,6 +283,30 @@ jobs:
 
           $CALIBRATION"
 
+      # v0.6.29 / Component 4 — see workflow.yml.tmpl for design notes.
+      - name: Update skill-usage tracking
+        if: success() && steps.clud-bug-review.outputs.structured_output != ''
+        continue-on-error: true
+        env:
+          STRUCTURED: ${{ steps.clud-bug-review.outputs.structured_output }}
+        run: |
+          set -euo pipefail
+          mkdir -p .claude/skills
+          if [ ! -f .claude/skills/.clud-bug.json ]; then
+            echo '{"version": 1}' > .claude/skills/.clud-bug.json
+          fi
+          printf '%s\n' "$STRUCTURED" | npx --yes clud-bug@{{CLUD_BUG_VERSION}} update-skill-usage --stdin
+          echo "::notice title=skill-usage::recorded review delta to ephemeral .clud-bug.json (v0.6.30 will add cross-review aggregation)"
+
+      - name: Upload skill-usage artifact
+        if: success() && steps.clud-bug-review.outputs.structured_output != ''
+        continue-on-error: true
+        uses: actions/upload-artifact@v4
+        with:
+          name: clud-bug-skill-usage-pr-${{ github.event.pull_request.number }}
+          path: .claude/skills/.clud-bug.json
+          retention-days: 90
+
       # v0.6.26 / §5.5 Layer 6 fallback render-from-inlines — see workflow.yml.tmpl for design notes.
       - name: Fallback summary (structured_output empty)
         if: success() && steps.clud-bug-review.outputs.structured_output == ''
@@ -339,7 +363,7 @@ 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.28
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.30
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           # v0.6.22 / 0.0.O: summary now posted by github-actions[bot].

package/templates/workflow-ts.yml.tmpl

@@ -283,6 +283,30 @@ jobs:
 
           $CALIBRATION"
 
+      # v0.6.29 / Component 4 — see workflow.yml.tmpl for design notes.
+      - name: Update skill-usage tracking
+        if: success() && steps.clud-bug-review.outputs.structured_output != ''
+        continue-on-error: true
+        env:
+          STRUCTURED: ${{ steps.clud-bug-review.outputs.structured_output }}
+        run: |
+          set -euo pipefail
+          mkdir -p .claude/skills
+          if [ ! -f .claude/skills/.clud-bug.json ]; then
+            echo '{"version": 1}' > .claude/skills/.clud-bug.json
+          fi
+          printf '%s\n' "$STRUCTURED" | npx --yes clud-bug@{{CLUD_BUG_VERSION}} update-skill-usage --stdin
+          echo "::notice title=skill-usage::recorded review delta to ephemeral .clud-bug.json (v0.6.30 will add cross-review aggregation)"
+
+      - name: Upload skill-usage artifact
+        if: success() && steps.clud-bug-review.outputs.structured_output != ''
+        continue-on-error: true
+        uses: actions/upload-artifact@v4
+        with:
+          name: clud-bug-skill-usage-pr-${{ github.event.pull_request.number }}
+          path: .claude/skills/.clud-bug.json
+          retention-days: 90
+
       # v0.6.26 / §5.5 Layer 6 fallback render-from-inlines — see workflow.yml.tmpl for design notes.
       - name: Fallback summary (structured_output empty)
         if: success() && steps.clud-bug-review.outputs.structured_output == ''
@@ -339,7 +363,7 @@ 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.28
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.30
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           # v0.6.22 / 0.0.O: summary now posted by github-actions[bot].

package/templates/workflow.yml.tmpl

@@ -494,6 +494,44 @@ jobs:
 
           $CALIBRATION"
 
+      # v0.6.29 / Component 4: pipe structured_output through
+      # `clud-bug update-skill-usage` to compute the per-skill loads +
+      # citations delta from this one review. Writes to the ephemeral
+      # workspace .clud-bug.json AND uploads as a workflow artifact
+      # (90-day retention). v0.6.30 will add aggregation logic so
+      # `clud-bug usage --health` reads + merges artifacts across runs.
+      #
+      # Why artifact instead of committing back to main: committing
+      # would require `contents: write` permission (private-repo
+      # trigger-firing regression risk per v0.6.23 hotfix) + race
+      # handling. Artifacts are GitHub-native persistence with zero
+      # permission expansion + zero commit noise.
+      - name: Update skill-usage tracking
+        if: success() && steps.clud-bug-review.outputs.structured_output != ''
+        continue-on-error: true  # don't fail the whole review if usage update flakes
+        env:
+          STRUCTURED: ${{ steps.clud-bug-review.outputs.structured_output }}
+        run: |
+          set -euo pipefail
+          mkdir -p .claude/skills
+          # If a .clud-bug.json already exists in the workspace (PR's
+          # snapshot), keep it. Otherwise initialize an empty shell so
+          # update-skill-usage has something to merge into.
+          if [ ! -f .claude/skills/.clud-bug.json ]; then
+            echo '{"version": 1}' > .claude/skills/.clud-bug.json
+          fi
+          printf '%s\n' "$STRUCTURED" | npx --yes clud-bug@{{CLUD_BUG_VERSION}} update-skill-usage --stdin
+          echo "::notice title=skill-usage::recorded review delta to ephemeral .clud-bug.json (v0.6.30 will add cross-review aggregation)"
+
+      - name: Upload skill-usage artifact
+        if: success() && steps.clud-bug-review.outputs.structured_output != ''
+        continue-on-error: true
+        uses: actions/upload-artifact@v4
+        with:
+          name: clud-bug-skill-usage-pr-${{ github.event.pull_request.number }}
+          path: .claude/skills/.clud-bug.json
+          retention-days: 90
+
       # Fallback comment when the model couldn't produce schema-valid
       # output after max retries (structured_output is empty). Keeps a
       # bare H2 header so the strict-mode gate sees a comment and falls
@@ -589,7 +627,7 @@ 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.28
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.30
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           # v0.6.22 / 0.0.O: the summary is now posted by the workflow