clud-bug 0.6.20 → 0.6.22

package/bin/clud-bug.js

@@ -31,6 +31,8 @@ function parseArgs(argv) {
     setProtection: true, quiet: false,
     // 0.0.M.1 (v0.6.13): `clud-bug usage` flags.
     repo: null, pr: null, limit: null, json: false,
+    // 0.0.O (v0.6.22): `clud-bug render` reads its payload from stdin.
+    stdin: false,
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -49,6 +51,7 @@ function parseArgs(argv) {
     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 if (a === '--stdin') args.stdin = true;
     else args._.push(a);
   }
   return args;
@@ -79,6 +82,11 @@ Commands:
   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.
+  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
+                        workflow post-step; output is what \`gh pr comment\`
+                        receives. Empty stdin or non-object payload exits 2.
 
 Options:
   --offline             Skip skills.sh; pin only the bundled baseline specimens.
@@ -130,12 +138,53 @@ async function main() {
     case 'edit-workflow': return runEditWorkflow(args);
     case 'usage':   return runUsage(args);
     case 'eval':    return runEval();
+    case 'render':  return runRender(args);
     default:
       process.stderr.write(`Unknown command: ${cmd || '(none)'}\n\n${HELP}`);
       process.exit(2);
   }
 }
 
+// 0.0.O (v0.6.22): render a structured-output JSON payload to the
+// GitHub-markdown summary comment shape. Called by the post-step
+// in the workflow templates: it reads the action's
+// `outputs.structured_output` (one bundled JSON string), pipes it
+// to stdin here, and we emit the rendered markdown on stdout for
+// the shell to pass to `gh pr comment --body`.
+//
+// Usage: `clud-bug render --stdin` (only input source supported).
+// Exit code: 0 on success, 2 on JSON parse error or non-object payload.
+async function runRender(args) {
+  const { renderReview } = await import('../lib/render-review.js');
+  if (!args.stdin) {
+    process.stderr.write('clud-bug render: --stdin is required (the only supported input source).\n');
+    process.exit(2);
+  }
+  let raw = '';
+  for await (const chunk of process.stdin) raw += chunk;
+  raw = raw.trim();
+  if (!raw) {
+    // Empty structured_output → post-step is supposed to skip the
+    // render. Surface the situation rather than silently producing an
+    // empty comment.
+    process.stderr.write('clud-bug render: stdin was empty — nothing to render.\n');
+    process.exit(2);
+  }
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch (e) {
+    process.stderr.write(`clud-bug render: JSON parse failed: ${e.message}\n`);
+    process.exit(2);
+  }
+  try {
+    process.stdout.write(renderReview(payload));
+  } catch (e) {
+    process.stderr.write(`clud-bug render: ${e.message}\n`);
+    process.exit(2);
+  }
+}
+
 // 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.
@@ -220,6 +269,7 @@ async function runInit(args) {
   log('  drafting field kit...');
   const tmplName = pickTemplate(signals.languages);
   const tmplPath = join(TEMPLATES, tmplName);
+  // REVIEW_SCHEMA + CCA_VERSION + CLUD_BUG_VERSION come from render.js DEFAULTS.
   const workflow = await renderFile(tmplPath, {
     REVIEW_PROMPT: reviewPrompt({
       projectDescription: buildDescriptionLine(signals),

package/lib/prompts.js

@@ -68,20 +68,24 @@ cached system prefix is free at 10%; per-PR fetches are not.
     state lives in your PRIOR SUMMARY COMMENT as an HTML marker:
     \`<!-- last-reviewed-sha: <sha> -->\`.
 
-    Identifying the PRIOR SUMMARY: claude-code-action posts an
-    in-progress \`Claude Code is working…\` comment BEFORE this
-    prompt runs — claude[bot]-authored but NOT the summary (no
-    marker). Anchor on the H2 line \`## 🐛 Clud Bug review\` instead
-    of "latest claude[bot] comment" — same anchor strict-mode uses.
+    Identifying the PRIOR SUMMARY (v0.6.22+ identity note):
+    From v0.6.22 (0.0.O) onward the summary is posted by a workflow
+    post-step under the \`github-actions[bot]\` identity, not
+    claude[bot]. Inline review threads are still claude[bot] (the
+    MCP tool routes through claude-code-action). Beware: the
+    in-progress \`Claude Code is working…\` comment claude-code-action
+    posts BEFORE this prompt runs is claude[bot]-authored but is NOT
+    your prior summary (no marker). Anchor on the H2 line
+    \`## 🐛 Clud Bug review\` — same anchor strict-mode uses.
 
     Detection in three steps:
 
-      1. Fetch claude[bot] comments newest-first:
+      1. Fetch github-actions[bot] comments newest-first:
          \`gh api "repos/$REPO_OWNER/$REPO_NAME/issues/$PR_NUMBER/comments?per_page=100&sort=created&direction=desc"\`
-         Walk them in order; find the FIRST whose body starts
-         (after any \`**Claude finished …**\` preamble the action
-         prepends) with \`## 🐛 Clud Bug review\`. THAT is your prior
-         summary. In its body, look for \`last-reviewed-sha: <sha>\`.
+         Walk them in order; filter to author \`github-actions[bot]\`,
+         and find the FIRST whose body starts with
+         \`## 🐛 Clud Bug review\`. THAT is your prior summary. In
+         its body, look for \`last-reviewed-sha: <sha>\`. (Pre-v0.6.22 summaries are claude[bot]-authored — if you find a recent claude[bot] comment with the H2 anchor and no newer github-actions[bot] match, treat it as the prior summary.)
 
       2. If a SHA was found, verify it's still in HEAD's ancestry:
          \`git merge-base --is-ancestor <prior_sha> $HEAD_SHA\`
@@ -105,7 +109,7 @@ cached system prefix is free at 10%; per-PR fetches are not.
     per file (default 4,000 bytes). Baseline skills fit easily;
     bloated user-added skills get truncated.
 
-  - PR comments: \`gh api "repos/$REPO_OWNER/$REPO_NAME/issues/$PR_NUMBER/comments?per_page=20" --jq '.[] | select(.user.login != "claude[bot]")' | head -c "$MAX_COMMENT_BYTES"\`
+  - PR comments: \`gh api "repos/$REPO_OWNER/$REPO_NAME/issues/$PR_NUMBER/comments?per_page=20" --jq '.[] | select(.user.login != "claude[bot]" and .user.login != "github-actions[bot]")' | head -c "$MAX_COMMENT_BYTES"\`
     (default 20,000 bytes, 20 most-recent). Skips your own prior
     comments — the FIX-PUSH FLOW handles those via reviewThreads
     GraphQL instead.
@@ -148,7 +152,17 @@ Each SKILL.md frontmatter (first \`---\`-delimited block) has a
     API-contract, test-discipline). Each gets its own H3 section.
   - Missing → treat as \`shared\`.
 
-Read each capped: \`head -c "$MAX_SKILL_BYTES" .claude/skills/*/SKILL.md\`
+Skill applies_to (v0.6.21 / 0.0.K):
+Frontmatter may also have \`applies_to:\` with \`paths:\` (glob list)
+and/or \`extensions:\` (extension list). Scan each skill's frontmatter
+first (cheap — just the \`---\` block). If applies_to is present and
+the PR's changed files (from \`gh pr diff --name-only\`) match NONE
+of the declared paths or extensions, SKIP that skill's body — don't
+read it, don't reference it. Skills without applies_to load
+unconditionally (back-compat). Net effect: a UI-scoped skill stays
+unread on a backend-only PR.
+
+Read each applicable body capped: \`head -c "$MAX_SKILL_BYTES" .claude/skills/<name>/SKILL.md\`
 
 At review end, append a single-line footer:
   Skills referenced: [skill-name-1, skill-name-2, ...]
@@ -175,13 +189,18 @@ subsequent fix-push re-fetches only the delta since this SHA. Omit
 it and the next review falls back to full \`gh pr diff\`.
 
 Strict-mode header (opt-in): if .claude/skills/.clud-bug.json has
-\`{ "strictMode": true }\`, the H2 header MUST signal verdict:
-  - any critical issue flagged → \`## 🐛 Clud Bug review — critical findings\`
-  - otherwise → \`## 🐛 Clud Bug review — clean\`
-A post-step greps for "critical findings" and fails the check.
-
-If strictMode is unset or absent, keep the bare \`## 🐛 Clud Bug review\`
-header — strict mode is opt-in.
+\`{ "strictMode": true }\`, set the \`status_header\` schema field
+to signal verdict:
+  - any critical issue flagged → \`status_header: "critical findings"\`
+    (renderer emits \`## 🐛 Clud Bug review — critical findings\`)
+  - otherwise → \`status_header: "clean"\` (renderer emits
+    \`## 🐛 Clud Bug review — clean\`)
+The strict-mode gate post-step greps for "critical findings" and
+fails the check.
+
+If strictMode is unset or absent, set \`status_header: "bare"\` —
+the renderer emits the bare \`## 🐛 Clud Bug review\` (no suffix),
+matching the v0.6.21- visible behaviour for non-strict-mode repos.
 
 Tone: conversational, concise field-naturalist voice (you are Clud
 Bug examining specimens of code) — never at the cost of clarity,
@@ -204,17 +223,24 @@ Your review lives in TWO surfaces, in this order:
    Cross-cutting findings (no specific line) stay summary-only —
    but default to inline whenever you can name file:line.
 
-2. SUMMARY PR COMMENT — one top-level \`gh pr comment\` carrying
-   the H2 header, status line, per-skill scan, and per-skill
-   findings sections. The strict-mode gate greps the H2 for
-   "— critical findings" — keep it intact even when also using a
-   strict-mode variant.
+2. SUMMARY PR COMMENT — emitted as STRUCTURED JSON via the
+   workflow's \`--json-schema\` flag (0.0.O / v0.6.22+). Do NOT
+   post the summary yourself via \`gh pr comment\` — a post-step
+   reads your structured output and renders the comment with the
+   exact format the strict-mode gate expects. Populate every
+   schema field (\`status_header\`, \`summary_counts\`,
+   \`per_skill_scan\`, \`critical_findings\`, \`minor_findings\`,
+   \`preexisting_findings\`, \`skills_referenced\`,
+   \`last_reviewed_sha\`); \`dedicated_sections\` and
+   \`diagnostics\` are optional but emit them when applicable.
+   See workflow env for the schema; the format docs below describe
+   what each field becomes after rendering.
 
 The comment body MUST start with:
 
   ## 🐛 Clud Bug review
 
-(claude[bot] is the bot login, but the header brands it Clud Bug.)
+(The post-step renders this H2 anchor — the strict-mode gate greps it.)
 
 On the next non-empty line, emit:
 
@@ -287,14 +313,16 @@ Shared-mode skill findings stay in the combined "Critical findings"
 (e.g. a logging-PII issue belongs in both critical-issues-only and
 pii-and-compliance at once).
 
-Post the summary:
-  gh pr comment "$PR_NUMBER" --body "<your review>"
+Emit the summary as structured JSON output (the workflow's
+--json-schema captures it; a post-step renders + posts via gh pr
+comment). Do NOT post the summary yourself.
 
-Inline findings post via mcp__github_inline_comment__create_inline_comment
+Inline findings still post via mcp__github_inline_comment__create_inline_comment
 (with \`confirmed: true\`). Pass ordering: (a) post inline findings,
 (b) resolve prior threads now fixed (FIX-PUSH FLOW below — feeds
-"resolved from prior"), (c) post summary. Step (b) MUST run before
-the summary; (a)/(b) order between themselves doesn't matter.
+"resolved_from_prior" counter in the JSON), (c) emit structured
+summary output. Step (b) MUST complete before (c) so the counter
+is accurate; (a)/(b) order between themselves doesn't matter.
 
 FIX-PUSH FLOW (when prior claude[bot] threads exist):
 List prior claude[bot] inline threads, resolve the ones whose issue

package/lib/render-review.js

@@ -0,0 +1,204 @@
+// Render a clud-bug review's structured-output JSON to the GitHub-markdown
+// summary comment shape the workflow has been posting since v0.6.5.
+//
+// 0.0.O (v0.6.22): introduced as the receiver for `--json-schema` output.
+// The LLM emits structured JSON (one bundled string via the action's
+// `outputs.structured_output`); a workflow post-step pipes that JSON to
+// `clud-bug render --stdin` (CLI subcommand), which calls renderReview()
+// here, then posts the result via `gh pr comment`. Failure mode: if
+// `structured_output` is empty (max retries hit), the post-step is
+// skipped and the LLM's prior free-form behaviour stands (it had already
+// been instructed to post via `gh pr comment` directly as a fallback).
+//
+// Why an outside renderer at all: with --json-schema the LLM can no
+// longer paraphrase the comment format (good for consistency, bad if the
+// rendered shape is wrong). Centralising the markdown shape here means a
+// future format tweak edits one function rather than the prompt.
+
+const SEVERITY_EMOJI = { critical: '🔴', minor: '🟡', preexisting: '🟣' };
+const SEVERITY_LABEL = {
+  critical: 'important',
+  minor: 'nit',
+  preexisting: 'pre-existing',
+};
+
+// Render the full summary comment markdown. `data` is the parsed JSON
+// matching the schema (see schema.js). Returns a string suitable for
+// `gh pr comment --body`.
+export function renderReview(data) {
+  if (!data || typeof data !== 'object') {
+    throw new TypeError('renderReview: data must be an object');
+  }
+  const out = [];
+  out.push(renderHeader(data));
+  out.push('');
+  out.push(renderStatusLine(data.summary_counts));
+  out.push('');
+  out.push(renderStatsHeader(data.summary_counts));
+  out.push('');
+  out.push(...renderPerSkillScan(data.per_skill_scan));
+  out.push('');
+  for (const section of data.dedicated_sections || []) {
+    out.push(...renderDedicatedSection(section));
+    out.push('');
+  }
+  if (nonEmpty(data.critical_findings)) {
+    out.push('### Critical findings');
+    out.push('');
+    out.push(...renderFindings(data.critical_findings, 'critical'));
+    out.push('');
+  }
+  if (nonEmpty(data.minor_findings)) {
+    out.push('### Minor findings');
+    out.push('');
+    out.push(...renderFindings(data.minor_findings, 'minor'));
+    out.push('');
+  }
+  if (nonEmpty(data.preexisting_findings)) {
+    out.push('### Pre-existing findings');
+    out.push('');
+    out.push(...renderFindings(data.preexisting_findings, 'preexisting'));
+    out.push('');
+  }
+  if (nonEmpty(data.diagnostics)) {
+    out.push('### Diagnostics');
+    out.push('');
+    for (const line of data.diagnostics) out.push(`- ${line}`);
+    out.push('');
+  }
+  out.push(renderSkillsReferenced(data.skills_referenced));
+  out.push('');
+  if (data.last_reviewed_sha) {
+    out.push(`<!-- last-reviewed-sha: ${data.last_reviewed_sha} -->`);
+  }
+  // Trim trailing blank lines but always keep a single trailing newline so
+  // the comment ends with a final newline (markdown rendering is unchanged
+  // either way, but it matches the prior LLM-driven shape).
+  return out.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\s+$/, '') + '\n';
+}
+
+function renderHeader(data) {
+  const verdict = data.status_header;
+  const base = '## 🐛 Clud Bug review';
+  if (verdict === 'critical findings') return `${base} — critical findings`;
+  if (verdict === 'clean') return `${base} — clean`;
+  // 'bare' (non-strict-mode default) OR an unexpected verdict — render
+  // the unsuffixed H2. Strict-mode gate's anchor stays intact either way.
+  return base;
+}
+
+function renderStatusLine(counts) {
+  const c = sanitizeCounts(counts);
+  return `**This round:** ${c.critical} critical · ${c.minor} minor · ${c.resolved_from_prior} resolved from prior · ${c.still_open} still open`;
+}
+
+// Severity-emoji stats header. Counts pre-existing in 🟣 even though
+// it's not in summary_counts (the prompt counts pre-existing separately
+// in preexisting_findings.length).
+function renderStatsHeader(counts) {
+  const c = sanitizeCounts(counts);
+  return `Found: ${c.critical} 🔴 / ${c.minor} 🟡 / ${c.preexisting} 🟣`;
+}
+
+function renderPerSkillScan(scan) {
+  const out = ['### Per-skill scan'];
+  if (!Array.isArray(scan) || scan.length === 0) {
+    out.push('- (no skills loaded — review proceeded against the baseline.)');
+    return out;
+  }
+  for (const entry of scan) {
+    if (!entry || typeof entry !== 'object') continue;
+    const skill = String(entry.skill || '').trim();
+    const outcome = String(entry.outcome || '').trim();
+    if (!skill) continue;
+    out.push(`- [${skill}]: ${outcome || 'scanned (no outcome reported).'}`);
+  }
+  return out;
+}
+
+function renderDedicatedSection(section) {
+  if (!section || typeof section !== 'object') return [];
+  const name = String(section.section_name || '').trim();
+  const skill = String(section.skill || '').trim();
+  const header = skill && name
+    ? `### ${name} [${skill}]`
+    : `### ${name || skill || 'Dedicated section'}`;
+  const out = [header, ''];
+  if (Array.isArray(section.findings) && section.findings.length > 0) {
+    // Dedicated-section findings use the same emoji-prefix block.
+    // Default severity for dedicated sections is "critical" — they're
+    // domain-specific findings the skill considers important.
+    out.push(...renderFindings(section.findings, 'critical'));
+  } else {
+    out.push('No findings.');
+  }
+  return out;
+}
+
+function renderFindings(findings, severity) {
+  const emoji = SEVERITY_EMOJI[severity] || '🔴';
+  const out = [];
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    const skill = String(f.skill || '').trim();
+    const summary = String(f.summary || '').trim();
+    if (!summary) continue;
+    const skillPrefix = skill ? `[${skill}]: ` : '';
+    const anchor = locationAnchor(f);
+    const claim = anchor
+      ? `${emoji} ${skillPrefix}${stripTrailingPunctuation(summary)} (${anchor}).`
+      : `${emoji} ${skillPrefix}${summary}`;
+    out.push(claim);
+    if (f.reasoning) {
+      out.push('<details><summary>Reasoning</summary>');
+      out.push('');
+      out.push(String(f.reasoning).trim());
+      out.push('');
+      out.push('</details>');
+    }
+    out.push('');
+  }
+  // Remove the trailing empty line — renderReview adds its own separators.
+  if (out[out.length - 1] === '') out.pop();
+  return out;
+}
+
+function renderSkillsReferenced(skills) {
+  if (!Array.isArray(skills) || skills.length === 0) {
+    return 'Skills referenced: [none] — no installed skill applied to this diff.';
+  }
+  return `Skills referenced: [${skills.join(', ')}]`;
+}
+
+// --- helpers ---
+
+function nonEmpty(arr) {
+  return Array.isArray(arr) && arr.length > 0;
+}
+
+function sanitizeCounts(counts) {
+  const c = counts && typeof counts === 'object' ? counts : {};
+  return {
+    critical: numOrZero(c.critical),
+    minor: numOrZero(c.minor),
+    preexisting: numOrZero(c.preexisting),
+    resolved_from_prior: numOrZero(c.resolved_from_prior),
+    still_open: numOrZero(c.still_open),
+  };
+}
+
+function numOrZero(v) {
+  const n = Number(v);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 0;
+}
+
+function locationAnchor(f) {
+  const file = String(f.file || '').trim();
+  if (!file) return null;
+  const line = Number(f.line);
+  return Number.isFinite(line) && line > 0 ? `${file}:${line}` : file;
+}
+
+function stripTrailingPunctuation(s) {
+  return s.replace(/[.!?]+$/, '');
+}

package/lib/render.js

@@ -1,7 +1,22 @@
 import { readFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { serializedReviewSchema } from './review-schema.js';
 
 const PLACEHOLDER_RE = /\{\{([A-Z_]+)\}\}/g;
 
+// CLUD_BUG_VERSION (0.0.O / v0.6.22) — read from this package's
+// package.json at module-load time. The rendered workflow uses
+// `npx --yes clud-bug@<CLUD_BUG_VERSION>` in the post-step that renders
+// structured output to markdown. Pinning to the version that ran
+// `clud-bug init` guarantees the renderer's output shape matches the
+// prompt's expectations.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_VERSION = JSON.parse(
+  readFileSync(join(__dirname, '..', 'package.json'), 'utf8'),
+).version;
+
 // Default values for substitution tokens that every template uses.
 // Callers can override per-render by passing the same key in `vars`.
 //
@@ -13,6 +28,8 @@ const PLACEHOLDER_RE = /\{\{([A-Z_]+)\}\}/g;
 // version in their own forked workflow.
 export const DEFAULTS = {
   CCA_VERSION: 'v1.0.133',
+  CLUD_BUG_VERSION: PKG_VERSION,
+  REVIEW_SCHEMA: serializedReviewSchema(),
 };
 
 // Multi-line value substitution preserves YAML/Markdown indentation by

package/lib/review-schema.js

@@ -0,0 +1,159 @@
+// JSON Schema for clud-bug review structured output (0.0.O / v0.6.22).
+//
+// Passed to claude-code-action via `claude_args: --json-schema '<JSON>'`.
+// The Agent SDK validates the LLM's emitted JSON against this schema and
+// re-prompts on mismatch (internal retry; not a clud-bug-level loop).
+//
+// Schema design choices:
+//   - Flat top-level — composite-action outputs are a single string, so we
+//     fromJSON() once and pluck fields. No deep nesting that would force
+//     extra path traversal in the post-step shell.
+//   - Word/char caps in `description:` — the SDK doc names these as the
+//     primary lever for keeping output cheap. They're advisory (the SDK
+//     does not enforce numeric caps; the LLM treats them as instruction).
+//     0.0.X already lives in the prompt, so the schema description here is
+//     a complementary belt-and-suspenders signal.
+//   - Required minimum — only the fields a renderer absolutely needs to
+//     produce a valid summary comment. Counts are always required (the
+//     stats header + status block depend on them); finding arrays are
+//     required but may be empty (a clean review has 0 findings, not
+//     missing arrays).
+//   - `additionalProperties: false` on every object — schema-strict mode.
+//     Anthropic's structured-outputs doc explicitly recommends this to
+//     keep the model from inventing fields.
+//
+// Bumped via deliberate edit; not derived from a TypeScript type. The
+// rendering side (lib/render-review.js) treats unknown fields permissively
+// — schema and renderer can drift up to one minor version safely.
+
+const FINDING_ITEM = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    skill: {
+      type: 'string',
+      description: 'The skill name in brackets, e.g. "critical-issues-only". Must match a loaded skill or "(none)".',
+    },
+    file: {
+      type: 'string',
+      description: 'Path of the affected file relative to repo root. Optional when the finding is cross-cutting.',
+    },
+    line: {
+      type: 'integer',
+      minimum: 1,
+      description: 'Line number in the affected file. Required when `file` is set.',
+    },
+    summary: {
+      type: 'string',
+      description: 'One sentence stating the claim. Max ~20 words; no trailing period (the renderer adds one).',
+    },
+    reasoning: {
+      type: 'string',
+      description: 'Evidence anchor + suggested fix. Max ~80 words. Rendered inside <details> block; can be omitted for self-evident findings.',
+    },
+  },
+  required: ['skill', 'summary'],
+};
+
+const PER_SKILL_SCAN_ITEM = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    skill: { type: 'string' },
+    outcome: {
+      type: 'string',
+      description: 'One sentence describing what the skill found. Max ~15 words. Examples: "scanned all paths. 2 critical findings below.", "0 findings.", "not applicable to this diff."',
+    },
+  },
+  required: ['skill', 'outcome'],
+};
+
+export const REVIEW_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    status_header: {
+      type: 'string',
+      enum: ['critical findings', 'clean', 'bare'],
+      description: 'Strict-mode opt-in repos: `critical findings` when ANY 🔴 finding exists, otherwise `clean`. Non-strict-mode repos (the default): emit `bare` — the renderer produces a `## 🐛 Clud Bug review` H2 with no suffix, matching the v0.6.21- behaviour. Check .claude/skills/.clud-bug.json for `strictMode: true` to pick critical/clean vs bare.',
+    },
+    summary_counts: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        critical: { type: 'integer', minimum: 0 },
+        minor: { type: 'integer', minimum: 0 },
+        preexisting: { type: 'integer', minimum: 0 },
+        resolved_from_prior: { type: 'integer', minimum: 0 },
+        still_open: { type: 'integer', minimum: 0 },
+      },
+      required: ['critical', 'minor', 'preexisting', 'resolved_from_prior', 'still_open'],
+    },
+    per_skill_scan: {
+      type: 'array',
+      description: 'One entry per LOADED skill — even silent ones. Empty when no skills are installed.',
+      items: PER_SKILL_SCAN_ITEM,
+    },
+    critical_findings: {
+      type: 'array',
+      description: 'NEW 🔴 findings (bugs, security, perf, missing test coverage). May be empty.',
+      items: FINDING_ITEM,
+    },
+    minor_findings: {
+      type: 'array',
+      description: 'NEW 🟡 findings (nits, style, observations). May be empty.',
+      items: FINDING_ITEM,
+    },
+    preexisting_findings: {
+      type: 'array',
+      description: 'NEW 🟣 findings (issues that pre-date this PR). May be empty.',
+      items: FINDING_ITEM,
+    },
+    dedicated_sections: {
+      type: 'array',
+      description: 'Per-dedicated-mode-skill section blocks. Each item carries the section header text and its findings.',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          section_name: { type: 'string', description: 'Human-readable section title, e.g. "Brand voice".' },
+          skill: { type: 'string', description: 'The dedicated skill name.' },
+          findings: { type: 'array', items: FINDING_ITEM },
+        },
+        required: ['section_name', 'skill', 'findings'],
+      },
+    },
+    diagnostics: {
+      type: 'array',
+      description: '0.0.T tee-hint diagnostics. One line per `head -c` cap that fired during fetch. Empty when no truncation occurred.',
+      items: { type: 'string' },
+    },
+    skills_referenced: {
+      type: 'array',
+      description: 'Names of every skill cited in any finding. Empty list (or ["(none)"]) when no skill applied.',
+      items: { type: 'string' },
+    },
+    last_reviewed_sha: {
+      type: 'string',
+      description: 'The HEAD SHA at review time, used by the incremental-diff handshake. Set to the literal value of the workflow env var $HEAD_SHA.',
+    },
+  },
+  required: [
+    'status_header',
+    'summary_counts',
+    'per_skill_scan',
+    'critical_findings',
+    'minor_findings',
+    'preexisting_findings',
+    'skills_referenced',
+    'last_reviewed_sha',
+  ],
+};
+
+// Serialize the schema for inclusion in workflow templates as the
+// `--json-schema '<JSON>'` argument. Single-line (the workflow YAML uses
+// the pipe block; single-quoted JSON inside that needs to stay flat to
+// avoid YAML parser surprises with embedded newlines).
+export function serializedReviewSchema() {
+  return JSON.stringify(REVIEW_SCHEMA);
+}

package/lib/skills.js

@@ -383,6 +383,113 @@ export function readReviewMode(skillContent) {
   return value === 'dedicated' ? 'dedicated' : 'shared';
 }
 
+// 0.0.K (v0.6.21): parse the optional `applies_to:` frontmatter block.
+//
+// Schema:
+//   applies_to:
+//     paths:
+//       - "src/ui/**"
+//       - "lib/components/**"
+//     extensions: [".tsx", ".jsx"]
+//
+// Returns `{paths: string[], extensions: string[]}` if the field is
+// present (either sub-list optional, both default to empty array), or
+// `null` if absent. Skills without applies_to are scope-universal —
+// the caller should treat null as "load unconditionally."
+//
+// Hand-rolled YAML parser scoped to this exact shape. The frontmatter
+// is otherwise opaque (review_mode is parsed elsewhere with a similar
+// single-key regex), so pulling in a YAML dep would be overkill.
+export function readAppliesTo(skillContent) {
+  if (typeof skillContent !== 'string') return null;
+  const fm = skillContent.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return null;
+  const block = fm[1];
+  // Anchor on `applies_to:` at start of line (the body of a SKILL.md
+  // could mention the term in prose; only the frontmatter key fires).
+  const head = block.match(/^applies_to:\s*$/m);
+  if (!head) return null;
+  // Slice from after the `applies_to:` line; the block ends at the
+  // next top-level key (a line starting with a word character + `:`)
+  // OR end-of-block.
+  const startIdx = head.index + head[0].length;
+  const rest = block.slice(startIdx);
+  const stop = rest.search(/^\w[\w-]*:/m);
+  const scoped = stop === -1 ? rest : rest.slice(0, stop);
+  const paths = parseYamlList(scoped, 'paths');
+  const extensions = parseYamlList(scoped, 'extensions');
+  if (paths.length === 0 && extensions.length === 0) return null;
+  return { paths, extensions };
+}
+
+// Parse a YAML list under `<key>:`, handling both the inline-array
+// form (`extensions: [".tsx", ".jsx"]`) and the block form
+// (`paths:` followed by `  - "src/ui/**"` lines).
+function parseYamlList(block, key) {
+  const inline = block.match(new RegExp(`^\\s{2}${key}:\\s*\\[(.*?)\\]\\s*$`, 'm'));
+  if (inline) {
+    return inline[1]
+      .split(',')
+      .map((s) => s.trim().replace(/^["']|["']$/g, ''))
+      .filter(Boolean);
+  }
+  const headerRe = new RegExp(`^\\s{2}${key}:\\s*$`, 'm');
+  const head = block.match(headerRe);
+  if (!head) return [];
+  const after = block.slice(head.index + head[0].length);
+  const items = [];
+  for (const line of after.split('\n')) {
+    const item = line.match(/^\s{4,}-\s*(.+?)\s*$/);
+    if (item) {
+      items.push(item[1].replace(/^["']|["']$/g, ''));
+      continue;
+    }
+    // Anything that isn't a list item (or blank) ends the list.
+    if (line.trim() !== '' && !item) break;
+  }
+  return items;
+}
+
+// 0.0.K: does `prPaths` contain at least one file matching the skill's
+// applies_to? Skills without applies_to ALWAYS apply (back-compat).
+//
+// `prPaths` is the list of changed files in the PR (e.g. from
+// `gh pr diff --name-only`). Match semantics:
+//   - paths: any glob in `paths` matches any of `prPaths`
+//   - extensions: any extension in `extensions` matches any of `prPaths`
+//   - paths OR extensions (NOT AND) — a single hit is enough
+//
+// Skill `paths` use the minimal glob set logmind already uses
+// (`*` matches non-slash, `**` matches across slashes, `?` single
+// char). Anything fancier would need a real glob lib.
+export function appliesToPr(skillContent, prPaths) {
+  const rule = readAppliesTo(skillContent);
+  if (rule === null) return true;  // back-compat: no rule → applies
+  if (!Array.isArray(prPaths)) return true;  // be permissive on bad input
+  for (const path of prPaths) {
+    if (typeof path !== 'string') continue;
+    for (const ext of rule.extensions) {
+      if (path.endsWith(ext)) return true;
+    }
+    for (const glob of rule.paths) {
+      if (globMatch(glob, path)) return true;
+    }
+  }
+  return false;
+}
+
+// Minimal glob → regex: `**` → `.*`, `*` → `[^/]*`, `?` → `.`,
+// everything else escaped. Anchored full-string match.
+function globMatch(glob, path) {
+  const escaped = glob
+    .replace(/([.+^${}()|[\]\\])/g, '\\$1')
+    .replace(/\*\*/g, '__DOUBLESTAR__')
+    .replace(/\*/g, '[^/]*')
+    .replace(/__DOUBLESTAR__/g, '.*')
+    .replace(/\?/g, '.');
+  return new RegExp(`^${escaped}$`).test(path);
+}
+
 // Partition a set of loaded skills into {shared, dedicated} buckets per
 // each skill's review_mode frontmatter. Expects skills with a `content`
 // field (SKILL.md text). Skills without content default to `shared`.

package/lib/update.js

@@ -45,6 +45,7 @@ export async function runUpdate({
   // 1. Re-render review workflow with the latest template.
   const signals = await detect(cwd);
   const tmplName = pickTemplate(signals.languages);
+  // REVIEW_SCHEMA + CCA_VERSION + CLUD_BUG_VERSION come from render.js DEFAULTS.
   const newReview = await renderFile(join(templatesDir, tmplName), {
     REVIEW_PROMPT: reviewPrompt({
       projectDescription: buildDescriptionLine(signals),

package/package.json

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

@@ -108,7 +108,7 @@ jobs:
           if $IS_FORK || $IS_BOT; then
             REASON=$($IS_BOT && echo "bot author ($PR_AUTHOR)" || echo "fork ($HEAD_REPO)")
             EXISTING=$(gh api "repos/${BASE_REPO}/issues/${PR_NUMBER}/comments?per_page=100" \
-              --jq '[.[] | select(.user.login == "claude[bot]" and (.body | startswith("## 🐛 Clud Bug skipped")))] | length')
+              --jq '[.[] | select(.user.login == "github-actions[bot]" and (.body | startswith("## 🐛 Clud Bug skipped")))] | length')
             if [ "${EXISTING:-0}" = "0" ]; then
               BODY=$(printf '## 🐛 Clud Bug skipped\n\nThis PR is from a %s. GitHub deliberately does not pass repository secrets to such workflows, so Clud Bug could not authenticate against Anthropic. Review the diff manually.' "$REASON")
               gh pr comment "$PR_NUMBER" --body "$BODY" || true
@@ -143,19 +143,56 @@ jobs:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           track_progress: true
           show_full_output: true
+          # v0.6.22 / 0.0.O: --json-schema captures the summary as
+          # structured output; post-step renders + posts. See workflow.yml.tmpl for design notes.
           claude_args: |
             --model ${{ needs.paths-check.outputs.model }}
             --max-turns 15
-            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh api graphql:*),Bash(gh api repos/:*),Bash(git show:*),Bash(git diff:*),Bash(git merge-base:*),Bash(cat .claude/skills/.clud-bug.json),Bash(cat .claude/skills/*/SKILL.md),Bash(head:*)"
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh api graphql:*),Bash(gh api repos/:*),Bash(git show:*),Bash(git diff:*),Bash(git merge-base:*),Bash(cat .claude/skills/.clud-bug.json),Bash(cat .claude/skills/*/SKILL.md),Bash(head:*)"
+            --json-schema '{{REVIEW_SCHEMA}}'
           prompt: |
             Review this pull request following the discipline in your
             system prompt — every rule about skill routing, comment
             format, the strict-mode header, the two-surface review
             shape, and the FIX-PUSH FLOW applies.
+        id: clud-bug-review
+
+      # v0.6.22 / 0.0.O: render structured output → post via gh pr comment.
+      - name: Render + post structured review
+        if: success() && steps.clud-bug-review.outputs.structured_output != ''
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          STRUCTURED: ${{ steps.clud-bug-review.outputs.structured_output }}
+        run: |
+          set -euo pipefail
+          BODY=$(printf '%s\n' "$STRUCTURED" | npx --yes clud-bug@{{CLUD_BUG_VERSION}} render --stdin)
+          gh pr comment "$PR_NUMBER" --body "$BODY"
+
+      # Fallback when structured_output is empty (max-retries hit).
+      - name: Fallback summary (structured_output empty)
+        if: success() && steps.clud-bug-review.outputs.structured_output == ''
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+          gh pr comment "$PR_NUMBER" --body "## 🐛 Clud Bug review
+
+          **This round:** 0 critical · 0 minor · 0 resolved from prior · 0 still open
+
+          Found: 0 🔴 / 0 🟡 / 0 🟣
+
+          ⚠️ Structured output (\`--json-schema\`) returned empty — likely max-retries hit on schema validation. Investigate the action logs.
+
+          Skills referenced: [none]"
 
       # 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.20
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.22
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
+          # v0.6.22 / 0.0.O: summary now posted by github-actions[bot].
+          # See workflow.yml.tmpl for design notes.
+          bot-login: 'github-actions[bot]'

package/templates/workflow-ts.yml.tmpl

@@ -108,7 +108,7 @@ jobs:
           if $IS_FORK || $IS_BOT; then
             REASON=$($IS_BOT && echo "bot author ($PR_AUTHOR)" || echo "fork ($HEAD_REPO)")
             EXISTING=$(gh api "repos/${BASE_REPO}/issues/${PR_NUMBER}/comments?per_page=100" \
-              --jq '[.[] | select(.user.login == "claude[bot]" and (.body | startswith("## 🐛 Clud Bug skipped")))] | length')
+              --jq '[.[] | select(.user.login == "github-actions[bot]" and (.body | startswith("## 🐛 Clud Bug skipped")))] | length')
             if [ "${EXISTING:-0}" = "0" ]; then
               BODY=$(printf '## 🐛 Clud Bug skipped\n\nThis PR is from a %s. GitHub deliberately does not pass repository secrets to such workflows, so Clud Bug could not authenticate against Anthropic. Review the diff manually.' "$REASON")
               gh pr comment "$PR_NUMBER" --body "$BODY" || true
@@ -143,19 +143,56 @@ jobs:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           track_progress: true
           show_full_output: true
+          # v0.6.22 / 0.0.O: --json-schema captures the summary as
+          # structured output; post-step renders + posts. See workflow.yml.tmpl for design notes.
           claude_args: |
             --model ${{ needs.paths-check.outputs.model }}
             --max-turns 15
-            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh api graphql:*),Bash(gh api repos/:*),Bash(git show:*),Bash(git diff:*),Bash(git merge-base:*),Bash(cat .claude/skills/.clud-bug.json),Bash(cat .claude/skills/*/SKILL.md),Bash(head:*)"
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh api graphql:*),Bash(gh api repos/:*),Bash(git show:*),Bash(git diff:*),Bash(git merge-base:*),Bash(cat .claude/skills/.clud-bug.json),Bash(cat .claude/skills/*/SKILL.md),Bash(head:*)"
+            --json-schema '{{REVIEW_SCHEMA}}'
           prompt: |
             Review this pull request following the discipline in your
             system prompt — every rule about skill routing, comment
             format, the strict-mode header, the two-surface review
             shape, and the FIX-PUSH FLOW applies.
+        id: clud-bug-review
+
+      # v0.6.22 / 0.0.O: render structured output → post via gh pr comment.
+      - name: Render + post structured review
+        if: success() && steps.clud-bug-review.outputs.structured_output != ''
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          STRUCTURED: ${{ steps.clud-bug-review.outputs.structured_output }}
+        run: |
+          set -euo pipefail
+          BODY=$(printf '%s\n' "$STRUCTURED" | npx --yes clud-bug@{{CLUD_BUG_VERSION}} render --stdin)
+          gh pr comment "$PR_NUMBER" --body "$BODY"
+
+      # Fallback when structured_output is empty (max-retries hit).
+      - name: Fallback summary (structured_output empty)
+        if: success() && steps.clud-bug-review.outputs.structured_output == ''
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+          gh pr comment "$PR_NUMBER" --body "## 🐛 Clud Bug review
+
+          **This round:** 0 critical · 0 minor · 0 resolved from prior · 0 still open
+
+          Found: 0 🔴 / 0 🟡 / 0 🟣
+
+          ⚠️ Structured output (\`--json-schema\`) returned empty — likely max-retries hit on schema validation. Investigate the action logs.
+
+          Skills referenced: [none]"
 
       # 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.20
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.22
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
+          # v0.6.22 / 0.0.O: summary now posted by github-actions[bot].
+          # See workflow.yml.tmpl for design notes.
+          bot-login: 'github-actions[bot]'

package/templates/workflow.yml.tmpl

@@ -158,7 +158,7 @@ jobs:
             # pull_request: synchronize on a long-running Dependabot PR would
             # otherwise stack one identical comment per rebase.
             EXISTING=$(gh api "repos/${BASE_REPO}/issues/${PR_NUMBER}/comments?per_page=100" \
-              --jq '[.[] | select(.user.login == "claude[bot]" and (.body | startswith("## 🐛 Clud Bug skipped")))] | length')
+              --jq '[.[] | select(.user.login == "github-actions[bot]" and (.body | startswith("## 🐛 Clud Bug skipped")))] | length')
             if [ "${EXISTING:-0}" = "0" ]; then
               BODY=$(printf '## 🐛 Clud Bug skipped\n\nThis PR is from a %s. GitHub deliberately does not pass repository secrets to such workflows, so Clud Bug could not authenticate against Anthropic. Review the diff manually.' "$REASON")
               gh pr comment "$PR_NUMBER" --body "$BODY" || true
@@ -222,15 +222,58 @@ jobs:
           # the PR as trivial (Haiku) or default (Sonnet). Override
           # per-repo by editing the rendered workflow if you want a
           # specific model for a specific repo.
+          # v0.6.22 / 0.0.O: --json-schema captures the summary as
+          # structured output (action exposes outputs.structured_output).
+          # The model emits findings as schema fields; a post-step
+          # renders to markdown and posts. The schema is rendered into
+          # this template at `clud-bug init` time via {{REVIEW_SCHEMA}}.
           claude_args: |
             --model ${{ needs.paths-check.outputs.model }}
             --max-turns 15
-            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh api graphql:*),Bash(gh api repos/:*),Bash(git show:*),Bash(git diff:*),Bash(git merge-base:*),Bash(cat .claude/skills/.clud-bug.json),Bash(cat .claude/skills/*/SKILL.md),Bash(head:*)"
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh api graphql:*),Bash(gh api repos/:*),Bash(git show:*),Bash(git diff:*),Bash(git merge-base:*),Bash(cat .claude/skills/.clud-bug.json),Bash(cat .claude/skills/*/SKILL.md),Bash(head:*)"
+            --json-schema '{{REVIEW_SCHEMA}}'
           prompt: |
             Review this pull request following the discipline in your
             system prompt — every rule about skill routing, comment
             format, the strict-mode header, the two-surface review
             shape, and the FIX-PUSH FLOW applies.
+        id: clud-bug-review
+
+      # v0.6.22 / 0.0.O: render the structured output to the summary
+      # comment shape, post via gh pr comment. Guarded so we only run
+      # when the action returned a non-empty structured payload
+      # (max-retries hit → empty → fall through to the next step).
+      - name: Render + post structured review
+        if: success() && steps.clud-bug-review.outputs.structured_output != ''
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          STRUCTURED: ${{ steps.clud-bug-review.outputs.structured_output }}
+        run: |
+          set -euo pipefail
+          BODY=$(printf '%s\n' "$STRUCTURED" | npx --yes clud-bug@{{CLUD_BUG_VERSION}} render --stdin)
+          gh pr comment "$PR_NUMBER" --body "$BODY"
+
+      # 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
+      # open (advisory) rather than panicking on a missing summary.
+      - name: Fallback summary (structured_output empty)
+        if: success() && steps.clud-bug-review.outputs.structured_output == ''
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+          gh pr comment "$PR_NUMBER" --body "## 🐛 Clud Bug review
+
+          **This round:** 0 critical · 0 minor · 0 resolved from prior · 0 still open
+
+          Found: 0 🔴 / 0 🟡 / 0 🟣
+
+          ⚠️ Structured output (\`--json-schema\`) returned empty — likely max-retries hit on schema validation. Investigate the action logs.
+
+          Skills referenced: [none]"
 
       # Strict-mode gate. Fails the check when the BASE ref's manifest
       # has { "strictMode": true } AND the latest clud-bug review's first
@@ -247,6 +290,13 @@ 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.20
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.6.22
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
+          # v0.6.22 / 0.0.O: the summary is now posted by the workflow
+          # post-step under the github-actions[bot] identity (was
+          # claude[bot] when claude-code-action did the posting).
+          # Without this override the gate's default (claude[bot])
+          # never matches the new summary author → strict mode falls
+          # open advisory for every install that opted in.
+          bot-login: 'github-actions[bot]'