clud-bug 0.6.28 → 0.6.29

package/bin/clud-bug.js

@@ -84,12 +84,18 @@ Commands:
                         \`.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.
+                        decide which skills to prune. v0.6.29 wires the workflow
+                        post-step that auto-writes per-review deltas; v0.6.30
+                        will aggregate across runs into the dashboard read path.
   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 +153,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 +200,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.

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.'
     );
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clud-bug",
-  "version": "0.6.28",
+  "version": "0.6.29",
   "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.29
         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.29
         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.29
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           # v0.6.22 / 0.0.O: the summary is now posted by the workflow