clud-bug 0.7.0-rc.11 → 0.7.0-rc.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clud-bug",
-  "version": "0.7.0-rc.11",
+  "version": "0.7.0-rc.13",
   "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/src/cli/hooks.ts

@@ -0,0 +1,122 @@
+// Wave 6b — Claude Code `type: agent` commit-review hook scaffolding.
+//
+// `clud-bug init --with-hooks` writes a native Claude Code hook that, on every
+// `git commit` the agent makes, spawns a clud-bug review SUBAGENT in the same
+// session — so it runs on the session's subscription (no API key), in the
+// background (the commit never blocks), and surfaces findings back to the agent.
+//
+// The model (see the Wave 6b plan): clud-bug supplies the *recipe* (the
+// agent-hook `prompt`); Claude Code runs it as a subagent. This is the dynamic,
+// always-on counterpart to the `/clud-bug-review` slash command.
+//
+// `type: agent` hooks are documented as experimental; the same outcome is
+// reachable via a `type: command` hook + `additionalContext` if the API shifts.
+
+/** Stable marker embedded in our hook's prompt so re-runs replace it in place. */
+export const CLUD_BUG_HOOK_MARKER = 'clud-bug-local-review';
+
+/**
+ * Build the `prompt` of the Claude Code `type: agent` commit-review hook,
+ * pinned to the clud-bug VERSION that scaffolded it. Pinning matters: a bare
+ * `npx clud-bug` resolves to the `latest` dist-tag, which can predate the
+ * `review-prompt` verb (e.g. while v0.7 is prerelease on `next`); `@${version}`
+ * guarantees the verb exists. `clud-bug update` refreshes the pin in place.
+ *
+ * Rather than baking a static recipe (which would drift from the repo's
+ * skills/config), it tells the subagent to run `clud-bug review-prompt` — the
+ * engine-driven verb that emits a recipe tailored to THIS repo's resolved plan
+ * — and follow it. The recipe is generated fresh at commit time, always current.
+ */
+export function buildCommitReviewPrompt(version: string): string {
+  return `<!-- ${CLUD_BUG_HOOK_MARKER} v1 -->
+You are clud-bug's local commit review, running as a background subagent on this
+session's own subscription (no extra auth — you have git, gh, and file access).
+
+Step 1 — get your review recipe from clud-bug's engine:
+
+    npx clud-bug@${version} review-prompt --trigger commit
+
+That prints a structured review recipe tailored to THIS repo's skills + config (a
+fast single pass for a commit). If that command isn't available, run the repo's
+installed clud-bug CLI's \`review-prompt --trigger commit\` instead.
+
+Step 2 — follow that recipe exactly: review the commit that was just made against
+the skills it names, and surface any findings back into the session so they can be
+fixed. A clean commit needs only a one-line note.
+
+Keep it tight — this is the commit-time safety net; the deeper review runs at PR time.`;
+}
+
+/** One Claude Code hook entry: a tool matcher plus its hook list. */
+export interface HookMatcherEntry {
+  matcher?: string;
+  hooks: Array<Record<string, unknown>>;
+}
+
+/** Minimal shape of the `.claude/settings.json` we read + merge into. */
+export interface ClaudeSettings {
+  hooks?: Record<string, HookMatcherEntry[]>;
+  [key: string]: unknown;
+}
+
+/**
+ * Builds the PostToolUse entry that spawns the commit-review subagent: a native
+ * `type: agent` hook that is backgrounded (`async`), surfaces findings
+ * (`asyncRewake`), and fires only on `git commit` (`if`).
+ */
+export function buildLocalReviewHook(recipe: string): HookMatcherEntry {
+  return {
+    matcher: 'Bash',
+    hooks: [
+      {
+        type: 'agent',
+        if: 'Bash(git commit *)',
+        async: true,
+        asyncRewake: true,
+        timeout: 180,
+        prompt: recipe,
+      },
+    ],
+  };
+}
+
+function isOurHook(h: Record<string, unknown> | undefined): boolean {
+  return typeof h?.['prompt'] === 'string' && (h['prompt'] as string).includes(CLUD_BUG_HOOK_MARKER);
+}
+
+function isCludBugReviewEntry(entry: HookMatcherEntry | undefined): boolean {
+  return !!entry && Array.isArray(entry.hooks) && entry.hooks.some(isOurHook);
+}
+
+/**
+ * Merges the clud-bug commit-review hook into an existing `.claude/settings.json`
+ * object. **Idempotent** (replaces any prior clud-bug entry rather than
+ * duplicating) and **non-clobbering** (preserves every other top-level key,
+ * every other event, and every other hook). Tolerates a missing/malformed
+ * `existing` value.
+ */
+export function mergeLocalReviewHook(existing: unknown, recipe: string): ClaudeSettings {
+  const base: ClaudeSettings =
+    existing && typeof existing === 'object' ? { ...(existing as ClaudeSettings) } : {};
+  const hooks: Record<string, HookMatcherEntry[]> = { ...(base.hooks ?? {}) };
+  const priorPost = Array.isArray(hooks.PostToolUse) ? hooks.PostToolUse : [];
+
+  // Preserve every non-clud-bug hook — including any the user co-located INSIDE
+  // our own matcher entry: drop only the hook(s) carrying our marker, never the
+  // whole entry.
+  const ours = buildLocalReviewHook(recipe);
+  const otherEntries: HookMatcherEntry[] = [];
+  const coLocatedUserHooks: Array<Record<string, unknown>> = [];
+  for (const entry of priorPost) {
+    if (isCludBugReviewEntry(entry)) {
+      for (const h of entry.hooks) if (!isOurHook(h)) coLocatedUserHooks.push(h);
+    } else {
+      otherEntries.push(entry);
+    }
+  }
+  const ourEntry: HookMatcherEntry =
+    coLocatedUserHooks.length > 0 ? { ...ours, hooks: [...coLocatedUserHooks, ...ours.hooks] } : ours;
+  hooks.PostToolUse = [...otherEntries, ourEntry];
+  base.hooks = hooks;
+  return base;
+}

package/src/cli/main.ts

@@ -31,6 +31,7 @@ import {
 import { computeAuditFileSet } from './audit.js';
 import { renderAuditHeader } from '../core/audit.js';
 import { runUpdate } from './update.js';
+import { runReviewPrompt } from './review-prompt.js';
 import { getPendingWorkflowEdits, makeBranchName, git as gitCmd } from './edit-workflow.js';
 import { applyToRepo as applyAgentDocs } from './agents-md.js';
 import { detectRepo, detectDefaultBranch, getProtectionState, enableConversationResolution } from './branch-protection.js';
@@ -66,6 +67,7 @@ function parseArgs(argv) {
     // .claude/commands/clud-bug-review.md so `/clud-bug-review` works in a
     // Claude Code session (reviews the current PR with the session's tokens).
     withLocalReview: false,
+    withHooks: false,
     // v0.7.0-rc.4: `clud-bug configure-github` flags.
     // --dry-run prints the diff but skips PATCH; --branch overrides "main".
     dryRun: false,
@@ -93,8 +95,11 @@ function parseArgs(argv) {
     else if (a === '--no-artifacts') args.artifacts = false;
     else if (a === '--with-skdd') args.withSkdd = true;
     else if (a === '--with-local-review') args.withLocalReview = true;
+    else if (a === '--with-hooks') args.withHooks = true;
     else if (a === '--dry-run') args.dryRun = true;
     else if (a === '--branch') args.branch = argv[++i];
+    else if (a === '--trigger') args.trigger = argv[++i];
+    else if (a === '--diff-size') args.diffSizeBytes = Number(argv[++i]);
     else args._.push(a);
   }
   return args;
@@ -185,6 +190,11 @@ Commands:
                         Required env vars: GH_TOKEN, ANTHROPIC_API_KEY,
                         REPO ("owner/name"), PR_NUMBER. Output: JSON
                         \`{actions, verifierCallCount, shouldRequestChanges}\`.
+  review-prompt         Emit the local-review recipe — the structured prompt a
+                        Claude Code agent/hook runs to review the current diff on
+                        the session's own subscription. Plans via the shared
+                        engine: --trigger commit (default) → a fast single pass;
+                        push/pr → the full multi-pass plan. Prints to stdout.
 
 Options:
   --offline             Skip skills.sh; pin only the bundled baseline specimens.
@@ -194,6 +204,11 @@ Options:
                         \`/clud-bug-review\` works in a Claude Code session —
                         reviews the current branch's PR using that session's
                         own tokens (no hosted App, no extra auth).
+  --with-hooks          (init) Also scaffold a native Claude Code \`type: agent\`
+                        commit-review hook into .claude/settings.json — on every
+                        \`git commit\` the agent makes, a backgrounded clud-bug
+                        review subagent runs on the session's subscription.
+                        Implies --with-local-review. Off by default.
   --quiet,-q            Token-frugal mode for agent invocations. Suppresses
                         progress chatter; emits exactly one final
                         \`ok <key-value>\` summary line per command. Errors
@@ -206,6 +221,7 @@ Options:
   --dry-run             Print the canonical-v1 diff without PATCH-ing
                         (configure-github only).
   --branch <name>       Target branch for configure-github (default: main).
+  --trigger <ctx>       review-prompt context: commit (default) | push | pr.
   --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.
@@ -249,6 +265,7 @@ async function main() {
     case 'select-review-event': return runSelectReviewEvent(args);
     case 'post-inline-threads': return runPostInlineThreads(args);
     case 'resolve-threads': return runResolveThreads(args);
+    case 'review-prompt': return runReviewPrompt(args);
     default:
       process.stderr.write(`Unknown command: ${cmd || '(none)'}\n\n${HELP}`);
       process.exit(2);
@@ -1251,6 +1268,10 @@ async function runInit(args) {
   // Claude Code session — the agent reviews the current branch's open PR using
   // THAT session's own tokens (Max or API), no hosted App or new auth required.
   // `.claude/` is already in the --commit add-list below, so it's staged too.
+  // `--with-hooks` implies `--with-local-review` — the auto hook and the manual
+  // `/clud-bug-review` command are complementary (the hook auto-runs the engine
+  // recipe on each commit; the command runs it on demand against the PR).
+  if (args.withHooks) args.withLocalReview = true;
   if (args.withLocalReview) {
     const commandPath = join(cwd, '.claude', 'commands', 'clud-bug-review.md');
     await mkdir(dirname(commandPath), { recursive: true });
@@ -1259,6 +1280,41 @@ async function runInit(args) {
     log(`    wrote ${rel(cwd, commandPath)}`);
   }
 
+  // v0.7.0 (Wave 6b): optional native commit-review hook. Merges a Claude Code
+  // `type: agent` PostToolUse hook into `.claude/settings.json` (preserving any
+  // existing settings + hooks) that, on every `git commit` the agent makes,
+  // spawns a clud-bug review subagent on the session's subscription, in the
+  // background — the hook's prompt runs `clud-bug review-prompt` and follows it.
+  if (args.withHooks) {
+    const { mergeLocalReviewHook, buildCommitReviewPrompt } = await import('./hooks.js');
+    const hookPrompt = buildCommitReviewPrompt(await readPkgVersion());
+    const settingsPath = join(cwd, '.claude', 'settings.json');
+    await mkdir(dirname(settingsPath), { recursive: true });
+    // Read-then-parse so we can tell "no file yet" (fresh merge) from "file
+    // exists but is invalid JSON" (leave it ALONE — never clobber user content).
+    let raw: string | undefined;
+    try {
+      raw = await readFile(settingsPath, 'utf8');
+    } catch {
+      raw = undefined; // no settings.json yet → fresh
+    }
+    let existing: unknown;
+    let proceed = true;
+    if (raw !== undefined) {
+      try {
+        existing = JSON.parse(raw);
+      } catch {
+        proceed = false;
+        log(`    skipped ${rel(cwd, settingsPath)} (existing file is not valid JSON; left untouched)`);
+      }
+    }
+    if (proceed) {
+      const merged = mergeLocalReviewHook(existing, hookPrompt);
+      await writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n');
+      log(`    wrote ${rel(cwd, settingsPath)} (commit-review hook)`);
+    }
+  }
+
   // Stamp the manifest. Sets strictMode: true ONLY on fresh installs —
   // a manifest that's never been touched by clud-bug init/update has no
   // lastUpdate field. Existing v0.3.x advisory installs (where strictMode

package/src/cli/review-prompt.ts

@@ -0,0 +1,206 @@
+// `clud-bug review-prompt` — emits the local-review RECIPE: a highly-structured
+// prompt the in-session Claude Code agent (or a `type: agent` hook) runs to
+// review the current diff, on the session's own subscription. It is the dynamic,
+// planReview-driven counterpart of the rc.11 static slash-command prompt: the
+// recipe is rendered FROM the shared engine (`core/planReview`), so a commit
+// gets a single fast pass and a PR gets the full multi-pass plan — clud-bug
+// writes the recipe, Claude Code's subagent is the runtime.
+
+import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+import {
+  planReview,
+  roleForPass,
+  readReviewPassesConfig,
+  parseFrontmatter,
+  type ReviewPlan,
+  type ReviewPlanSkill,
+  type ReviewTrigger,
+  type ReviewPassMode,
+} from '../core/index.js';
+import { readManifest } from './skills.js';
+
+/** Marker that identifies a clud-bug local-review recipe (idempotency + hook detection). */
+export const CLUD_BUG_RECIPE_MARKER = 'clud-bug-local-review';
+
+const MODE_AGGREGATION: Record<ReviewPassMode, string> = {
+  'cross-check':
+    "Pass 1 reviews the diff against all the skills; each later pass re-reviews AND checks pass 1's findings (agree / disagree), adding any new ones it finds.",
+  consensus:
+    'Run all passes independently against all the skills, then keep only findings that two or more passes agree on.',
+  independent:
+    'Run all passes independently against all the skills, then take the union of their findings, each attributed to its pass.',
+};
+
+const TRIGGER_INTRO: Record<ReviewTrigger, string> = {
+  commit: 'a fast review of the commit you just made',
+  push: 'a review of the branch you are about to push',
+  pr: "a review of this branch's open PR",
+};
+
+/**
+ * Render the local-review recipe from a resolved plan. Pure — all I/O (loading
+ * skills + config) happens in `runReviewPrompt`; this turns a `ReviewPlan` into
+ * the prompt text. The number of passes, the aggregation mode, the role tiers,
+ * and the skills all come from the plan, so the recipe scales from a single
+ * fast commit pass up to the full multi-pass PR review without branching here.
+ */
+export function renderReviewRecipe(input: { plan: ReviewPlan; trigger: ReviewTrigger }): string {
+  const { plan, trigger } = input;
+  const slugs = plan.perSkill.map((p) => p.slug);
+  const maxPasses = plan.perSkill.length
+    ? Math.max(...plan.perSkill.map((p) => p.count))
+    : 1;
+  // Use the aggregation mode of the skill that drives the pass depth, not just
+  // the first skill (which may be configured for a single pass).
+  const mode: ReviewPassMode =
+    plan.perSkill.find((p) => p.count === maxPasses)?.mode ?? 'cross-check';
+
+  const diffStep =
+    trigger === 'commit'
+      ? 'The commit you just made:\n\n```bash\ngit show --no-color --format=medium HEAD\n```'
+      : 'If an open PR exists for this branch, review it; otherwise diff the branch against its base:\n\n' +
+        '```bash\n' +
+        'PR=$(gh pr list --head "$(git branch --show-current)" --state open --json number --jq \'.[0].number\')\n' +
+        'if [ -n "$PR" ]; then\n' +
+        '  gh pr diff "$PR"\n' +
+        'else\n' +
+        '  git remote set-head origin --auto >/dev/null 2>&1 || true  # make sure origin/HEAD resolves\n' +
+        '  git diff --no-color origin/HEAD...HEAD\n' +
+        'fi\n' +
+        '```';
+
+  const skillsList =
+    slugs.length > 0
+      ? slugs.map((s) => `  - \`.claude/skills/${s}/SKILL.md\``).join('\n')
+      : '  - (no skills resolved — apply the baseline discipline below)';
+
+  let reviewStep: string;
+  if (maxPasses <= 1) {
+    reviewStep =
+      'Review the diff against every loaded skill in a single pass. For each REAL issue, ' +
+      'record `file`, `line`, `severity` (`critical` | `minor` | `preexisting`), the `skill` ' +
+      'that motivated it, and a one-line `summary` with the quoted offending line. Finding ' +
+      'nothing is the normal outcome — be precise, not exhaustive.';
+  } else {
+    const passLines = Array.from({ length: maxPasses }, (_, i) => {
+      const role = roleForPass(plan.roles, i, 'Reviewer');
+      const tier = role.tier ? ` · ${role.tier} tier` : '';
+      return `  ${i + 1}. **${role.name}**${tier}`;
+    }).join('\n');
+    reviewStep =
+      `Dispatch ${maxPasses} reviewer sub-agents — a ${maxPasses}-pass **${mode}** review on this ` +
+      `session's subscription (bind each tier to a Claude Code model: a fast model for \`beetle\`, ` +
+      `a strong model for \`wasp\`/\`mantis\`):\n\n${passLines}\n\n${MODE_AGGREGATION[mode]}`;
+  }
+
+  const surface =
+    trigger === 'commit'
+      ? 'Surface the findings back into this session so the agent can fix them immediately. ' +
+        'If the commit is clean, report a single line: `clud-bug: commit <short-sha> — clean.`'
+      : 'Surface the findings into the session, and — if an open PR exists — post or edit (in ' +
+        'place, by integer comment id) the clud-bug summary comment on it.';
+
+  return `<!-- ${CLUD_BUG_RECIPE_MARKER} v1 -->
+You are **clud-bug**, running ${TRIGGER_INTRO[trigger]} inside this Claude Code session, on
+this session's own model tokens — no hosted App, no extra auth (you already have \`git\`,
+\`gh\`, and file access).
+
+## The plan
+clud-bug resolved this review from the repo's skills + \`.clud-bug.json\`:
+**${plan.summary}**
+
+## 1. Get the diff
+${diffStep}
+
+## 2. Load the review skills
+Read each skill's discipline from the checkout:
+${skillsList}
+
+Apply them strictly — at minimum **critical-issues-only** (flag only correctness, security,
+or performance bugs — skip nits), **evidence-based-review** (quote the exact line you flag),
+and **respect-existing-conventions** (don't fight the codebase's patterns).
+
+## 3. Review
+${reviewStep}
+
+## 4. Report
+Render the body in clud-bug's standard shape (§1.8.1) — omit any empty section:
+
+\`\`\`
+## 🐛 Clud Bug review — <clean | critical findings>
+
+**This round:** N critical · N minor · N resolved from prior · N still open
+
+Found: N 🔴 / N 🟡 / N 🟣
+
+<per-finding: 🔴 [skill]: <summary> (file:line) — with the quoted line + a one-line fix>
+
+Skills referenced: [<the skills you applied>]
+
+<!-- written-by: @<login> (clud-bug local-mode) -->
+\`\`\`
+
+${surface}
+
+Keep it tight — this is the local safety net; the deeper review still happens at PR time.
+`;
+}
+
+interface ReviewPromptArgs {
+  trigger?: string;
+  cwd?: string;
+  diffSizeBytes?: number;
+  _?: string[];
+}
+
+/**
+ * `clud-bug review-prompt [--trigger commit|push|pr]` — load the repo's skills +
+ * config, plan the review through `core/planReview`, and print the recipe to
+ * stdout. Defaults to the `commit` trigger (the primary hook consumer).
+ */
+export async function runReviewPrompt(args: ReviewPromptArgs): Promise<void> {
+  const cwd = args.cwd ?? process.cwd();
+  const trigger = normalizeTrigger(args.trigger);
+
+  const skillsDir = join(cwd, '.claude', 'skills');
+  const manifest = await readManifest(skillsDir);
+
+  // Load each installed skill's frontmatter (for `review_mode`), tolerating a
+  // skill whose SKILL.md is missing or unparseable (skip it, don't crash).
+  const skills: ReviewPlanSkill[] = [];
+  // Keep the raw SKILL.md text so `planReview` can honor a skill author's
+  // `review_passes:` frontmatter override (precedence layer 2) — without this
+  // that layer is silently dead in local mode.
+  const rawSkillMd: Record<string, string> = {};
+  for (const entry of manifest.installed) {
+    try {
+      const raw = await readFile(join(skillsDir, entry.slug, 'SKILL.md'), 'utf8');
+      skills.push({ slug: entry.slug, frontmatter: parseFrontmatter(raw) });
+      rawSkillMd[entry.slug] = raw;
+    } catch {
+      // Skill body unreadable/unparseable — omit from the plan.
+    }
+  }
+
+  const config = readReviewPassesConfig(manifest);
+  const plan = planReview({
+    skills,
+    config,
+    trigger,
+    rawSkillMd,
+    ...(args.diffSizeBytes !== undefined ? { diffSizeBytes: args.diffSizeBytes } : {}),
+  });
+
+  process.stdout.write(renderReviewRecipe({ plan, trigger }) + '\n');
+}
+
+function normalizeTrigger(raw: string | undefined): ReviewTrigger {
+  if (raw === undefined || raw === 'commit') return 'commit';
+  if (raw === 'push' || raw === 'pr') return raw;
+  process.stderr.write(
+    `clud-bug review-prompt: unrecognized --trigger "${raw}" (expected commit|push|pr); using commit.\n`,
+  );
+  return 'commit';
+}

package/src/cli/update.ts

@@ -5,6 +5,7 @@ import { reviewPrompt } from '../core/prompts.js';
 import { detect, buildDescriptionLine } from '../core/detect.js';
 import { loadBaseline, readManifest, writeManifest, type LoadBaselineOptions } from './skills.js';
 import { applyToRepo as applyAgentDocs } from './agents-md.js';
+import { mergeLocalReviewHook, buildCommitReviewPrompt, CLUD_BUG_HOOK_MARKER } from './hooks.js';
 
 // Re-render the user's workflow + refresh baseline skills using the
 // templates / baseline shipped with the currently-installed clud-bug.
@@ -162,6 +163,27 @@ export async function runUpdate(opts: RunUpdateOptions): Promise<RunUpdateResult
     }
   }
 
+  // 5c. Refresh the native commit-review hook (Wave 6b) in place when it was
+  //     scaffolded via `clud-bug init --with-hooks` and our entry is intact (the
+  //     `clud-bug-local-review` marker). settings.json is user-managed — we only
+  //     re-merge OUR marked hook, never touching the user's other hooks/settings.
+  const settingsPath = join(cwd, '.claude', 'settings.json');
+  if (await pathExists(settingsPath)) {
+    const prior = await readSafe(settingsPath);
+    if (prior && prior.includes(CLUD_BUG_HOOK_MARKER)) {
+      try {
+        const merged = mergeLocalReviewHook(JSON.parse(prior), buildCommitReviewPrompt(ourVersion));
+        await maybeWrite(settingsPath, JSON.stringify(merged, null, 2) + '\n', changed, unchanged, 'commit-review hook');
+      } catch {
+        skipped.push({
+          path: settingsPath,
+          label: 'commit-review hook',
+          reason: 'settings.json is not valid JSON; left untouched',
+        });
+      }
+    }
+  }
+
   // 6. Stamp the manifest with the version that ran the update.
   manifest['lastUpdate'] = new Date().toISOString();
   manifest['lastUpdateVersion'] = ourVersion;