clud-bug 0.7.0-rc.2 → 0.7.0-rc.21

package/src/cli/main.ts

@@ -25,12 +25,14 @@ import { renderFile, pickTemplate, templateLanguage } from '../core/render.js';
 import { reviewPrompt } from '../core/prompts.js';
 import { SkillsClient, rankAndCap } from '../core/skills.js';
 import {
-  writeSkills, writeSkill, loadBaseline,
+  writeSkills, writeSkill, loadBaseline, loadDesignKit,
   readManifest, writeManifest, removeSkill, listInstalled, diffManifest,
 } from './skills.js';
 import { computeAuditFileSet } from './audit.js';
 import { renderAuditHeader } from '../core/audit.js';
 import { runUpdate } from './update.js';
+import { runReviewPrompt } from './review-prompt.js';
+import { runPostCheckRun } from './post-check-run.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';
@@ -43,6 +45,7 @@ import { computeReviewCost, costPerLOC, cacheHitRate, extractTokensFromLog, roll
 const PKG_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 const TEMPLATES = join(PKG_ROOT, 'templates');
 const BASELINE_DIR = join(TEMPLATES, 'skills', 'baseline');
+const DESIGN_DIR = join(TEMPLATES, 'skills', 'design');
 
 function parseArgs(argv) {
   const args = {
@@ -62,6 +65,25 @@ function parseArgs(argv) {
     // users get the same one-command bootstrap as Python-first users
     // (logmind v0.6.8's --with-skdd is the symmetric counterpart).
     withSkdd: false,
+    // v0.7.0 (Wave 6b): `clud-bug init --with-local-review` also scaffolds
+    // .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,
+    // rc.16: `clud-bug init --with-design` installs the design-critic kit
+    // (3 `kind: design` skills) and flips the off-by-default `design` block to
+    // enabled so the visual review lens runs (local recipe + hosted bot).
+    withDesign: false,
+    // rc.18: `clud-bug init --local-only` installs MAX MODE (skills + slash
+    // command + commit hook), but SKIPS the GitHub Action workflows (which run
+    // claude-code-action with ANTHROPIC_API_KEY). For repos that review on a
+    // Claude subscription via the in-session hook, not a billed CI Action.
+    // Implies --with-local-review + --with-hooks.
+    localOnly: false,
+    // v0.7.0-rc.4: `clud-bug configure-github` flags.
+    // --dry-run prints the diff but skips PATCH; --branch overrides "main".
+    dryRun: false,
+    branch: null,
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -84,6 +106,23 @@ function parseArgs(argv) {
     else if (a === '--health') args.health = true;
     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 === '--with-design') args.withDesign = true;
+    else if (a === '--local-only') args.localOnly = 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]);
+    // H3: `clud-bug post-check-run` flags.
+    else if (a === '--sha') args.sha = argv[++i];
+    else if (a === '--verdict') args.verdict = argv[++i];
+    else if (a === '--critical-count') args.criticalCount = Number(argv[++i]);
+    else if (a === '--source') args.source = argv[++i];
+    else if (a === '--strict') args.strict = true;
+    else if (a === '--no-strict') args.strict = false;
+    else if (a === '--owner') args.owner = argv[++i];
+    else if (a === '--details-url') args.detailsUrl = argv[++i];
     else args._.push(a);
   }
   return args;
@@ -105,6 +144,12 @@ Commands:
                         Use --since / --changed-in / --scope to narrow.
   update                Re-render workflows + refresh baseline specimens to the latest shipped
                         templates. Custom and skills.sh-installed specimens left alone.
+  configure-github <owner>/<repo>
+                        Apply the SPEC §7 canonical branch protection ruleset to a repo.
+                        Auth: GITHUB_TOKEN env first, then \`gh auth token\`. Use
+                        --dry-run to print the diff without PATCH-ing; --branch to
+                        target a non-main branch. Idempotent — already-canonical
+                        repos exit 0 with no changes.
   edit-workflow         Helper for editing .github/workflows/clud-bug-*.yml in an isolated
                         PR (the action refuses to review PRs that modify its own workflow).
   usage                 Read recent clud-bug-review run JSON + normalize cost per LOC.
@@ -138,11 +183,67 @@ Commands:
                         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.
+  select-review-event   Compute the SPEC §7.2.1 formal-review event (APPROVE /
+   --stdin               REQUEST_CHANGES / COMMENT / skip) from a structured-output
+                        JSON payload + a few env-passed PR-author fields. Used by
+                        the v0.7.0-rc.3 workflow post-step to post a formal
+                        \`pulls.createReview\` call so the canonical ruleset's
+                        \`required_approving_review_count: 1\` floor is auto-
+                        satisfied by clud-bug[bot] on clean reviews.
+                        Required env vars: PR_AUTHOR_LOGIN, PR_AUTHOR_ASSOCIATION,
+                        STRICT_MODE ("true"/"false"). Empty/malformed stdin →
+                        exits 0 with "skip" on stdout (no-op; workflow degrades
+                        gracefully to the existing comment-only behavior).
+  post-inline-threads   Post per-finding inline review threads (D.2.X). Reads a
+   --stdin               structured-output JSON payload from stdin, fetches the
+                        PR diff via \`gh api\`, posts one batched review with one
+                        comment per anchorable finding. Each comment body carries
+                        a hidden \`<!-- finding-id: <hash> --> \`marker so Wave 5b
+                        auto-resolve can re-match findings on subsequent pushes
+                        without persistent state. Required env vars: GH_TOKEN,
+                        REPO ("owner/name"), PR_NUMBER, HEAD_SHA. Output is a
+                        JSON status report \`{posted, skipped, preexisting, error?}\`.
+  resolve-threads       Auto-resolve inline review threads when a fix-push
+                        addresses the original finding (D.2.6). Fetches all
+                        bot-authored unresolved threads, asks the Anthropic
+                        Messages API per-thread whether the new commit addressed
+                        the concern, then resolves (with a marker reply)
+                        ADDRESSED threads + leaves UNCERTAIN/NOT_ADDRESSED open.
+                        Fail-closed: verifier errors route to UNCERTAIN.
+                        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.
+  post-check-run        Post the \`clud-bug-review\` GitHub check so branch
+                        protection can gate the merge (H3). --verdict
+                        clean|critical|failed --sha <sha> [--critical-count N]
+                        [--source local|ci] [--strict|--no-strict] [--dry-run].
+                        clean→success, critical+strict→failure, else neutral.
 
 Options:
   --offline             Skip skills.sh; pin only the bundled baseline specimens.
   --accept-all,-y       Accept the recommended specimens without prompting.
   --commit              git add + commit the generated kit when done (init only).
+  --with-local-review   (init) Scaffold .claude/commands/clud-bug-review.md so
+                        \`/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) Scaffold a native Claude Code \`type: command\`
+                        commit-review hook into .claude/settings.json — on every
+                        \`git commit\` / \`logmind log\`, it fetches a review recipe and
+                        surfaces it to the agent (on this session's subscription)
+                        via asyncRewake. Implies --with-local-review. Off by default.
+  --with-design         (init) Install the design-critic kit (3 \`kind: design\`
+                        skills) and enable the off-by-default visual review
+                        lens — renders changed UI and critiques it. Off by default.
+  --local-only          (init) MAX MODE: install the slash command + commit hook
+                        (implies --with-local-review + --with-hooks) but SKIP the
+                        GitHub Action workflows. Reviews run in your Claude Code
+                        session on your subscription — no API key, no per-review bill.
   --quiet,-q            Token-frugal mode for agent invocations. Suppresses
                         progress chatter; emits exactly one final
                         \`ok <key-value>\` summary line per command. Errors
@@ -152,6 +253,10 @@ Options:
                         required_conversation_resolution on the default
                         branch (init only). Use for repos that manage
                         branch protection via ruleset or org policy.
+  --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.
@@ -178,6 +283,17 @@ async function main() {
   if (args.quiet) setQuiet(true);
 
   const cmd = args._[0];
+
+  // rc.20 — update notifier (brew/gh/vercel pattern). Only on an interactive
+  // terminal, and never for the machine-consumed verbs (the hook runs
+  // review-prompt in a non-TTY subprocess, so this is doubly skipped there).
+  // Best-effort + cache-backed, so it adds no latency to the command.
+  const MACHINE_VERBS = new Set(['review-prompt', 'post-check-run', 'render', 'update-skill-usage']);
+  if (process.stderr.isTTY && !MACHINE_VERBS.has(cmd)) {
+    const { maybeNotifyUpdate } = await import('./update-notifier.js');
+    await maybeNotifyUpdate(await readPkgVersion());
+  }
+
   switch (cmd) {
     case 'init':    return runInit(args);
     case 'list':    return runList(args);
@@ -187,10 +303,16 @@ async function main() {
     case 'audit':   return runAudit(args);
     case 'update':  return runUpdateCmd(args);
     case 'edit-workflow': return runEditWorkflow(args);
+    case 'configure-github': return runConfigureGithubCmd(args);
     case 'usage':   return runUsage(args);
     case 'eval':    return runEval();
     case 'render':  return runRender(args);
     case 'update-skill-usage': return runUpdateSkillUsage(args);
+    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);
+    case 'post-check-run': return runPostCheckRun(args);
     default:
       process.stderr.write(`Unknown command: ${cmd || '(none)'}\n\n${HELP}`);
       process.exit(2);
@@ -335,6 +457,744 @@ async function runUpdateSkillUsage(args) {
 }
 
 
+// v0.7.0-rc.3 — SPEC §7.2.1 formal-review event selector for the npm
+// workflow path. Reads the action's structured_output JSON from stdin,
+// PR-author metadata from env, and emits ONE word on stdout:
+//
+//     APPROVE | REQUEST_CHANGES | COMMENT | skip
+//
+// The workflow template post-step pipes the structured_output payload
+// in, reads the verdict, then conditionally calls `gh api ... /reviews`
+// with `event=$VERDICT` (skipping the API call when verdict is "skip").
+//
+// Robustness contract: this command MUST NEVER fail the workflow on
+// caller-side problems (missing/malformed payload, missing env). Any
+// such case prints "skip" to stdout + a warning to stderr and exits 0
+// — the workflow then degrades to the existing comment-only behavior.
+// We only exit non-zero on programmer error (unknown command flags),
+// which the workflow templates don't pass.
+//
+// Required env vars (the workflow templates set all four):
+//   PR_AUTHOR_LOGIN          — github.event.pull_request.user.login
+//   PR_AUTHOR_ASSOCIATION    — github.event.pull_request.author_association
+//   STRICT_MODE              — "true" / "false" from the base-ref manifest
+// (PR_AUTHOR_ASSOCIATION missing → "CONTRIBUTOR" default which preserves
+// pre-§7.2.1 trusted-author semantics; PR_AUTHOR_LOGIN missing → "skip".)
+async function runSelectReviewEvent(args) {
+  const { selectReviewEvent } = await import('../core/formal-review.js');
+
+  if (!args.stdin) {
+    process.stderr.write(
+      'clud-bug select-review-event: --stdin is required.\n',
+    );
+    process.stdout.write('skip\n');
+    return;
+  }
+
+  let raw = '';
+  for await (const chunk of process.stdin) raw += chunk;
+  raw = raw.trim();
+  if (!raw) {
+    process.stderr.write(
+      'clud-bug select-review-event: stdin empty — emitting "skip".\n',
+    );
+    process.stdout.write('skip\n');
+    return;
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch (e) {
+    process.stderr.write(
+      `clud-bug select-review-event: JSON parse failed: ${e.message} — emitting "skip".\n`,
+    );
+    process.stdout.write('skip\n');
+    return;
+  }
+  if (!payload || typeof payload !== 'object') {
+    process.stderr.write(
+      'clud-bug select-review-event: payload must be a JSON object — emitting "skip".\n',
+    );
+    process.stdout.write('skip\n');
+    return;
+  }
+
+  // Count findings from the structured_output array shape. Each is
+  // optional — the model may emit absent / null / wrong-type arrays
+  // when its output drifts from schema; we tolerate all of those.
+  const criticalCount = Array.isArray(payload.critical_findings)
+    ? payload.critical_findings.length
+    : 0;
+  const minorCount = Array.isArray(payload.minor_findings)
+    ? payload.minor_findings.length
+    : 0;
+
+  // Env-passed metadata. Empty PR_AUTHOR_LOGIN means we have no idea
+  // who opened the PR — safer to skip than to attempt a formal review
+  // that might collide with the self-PR guard mis-routed.
+  const prAuthorLogin = String(process.env.PR_AUTHOR_LOGIN ?? '').trim();
+  if (prAuthorLogin === '') {
+    process.stderr.write(
+      'clud-bug select-review-event: PR_AUTHOR_LOGIN unset — emitting "skip".\n',
+    );
+    process.stdout.write('skip\n');
+    return;
+  }
+
+  // author_association resolution — security-critical fallback ladder.
+  //
+  // SPEC §7.2.1 + clud-bug-review #163 feedback: the §7.2.1 gate exists
+  // precisely so a future REST-API rename of an external tier doesn't
+  // silently degrade to "trusted → APPROVE". The fallback below splits
+  // the two error cases by what they MEAN:
+  //
+  //   1. EMPTY ("") — caller didn't pass author_association at all.
+  //      This is the "older webhook payload / non-GH caller" case.
+  //      Pre-§7.2.1, those callers got APPROVE on clean reviews; we
+  //      preserve that by defaulting to 'CONTRIBUTOR' (org-trusted).
+  //      Documented + tested under "missing PR_AUTHOR_ASSOCIATION".
+  //
+  //   2. NON-EMPTY UNRECOGNIZED ("FUTURE_TIER") — caller passed a
+  //      token this build doesn't know about. This is the rename
+  //      scenario the §7.2.1 gate is explicitly defending against.
+  //      Fail CLOSED: treat as external → 'NONE' → COMMENT, NEVER
+  //      APPROVE. If the rename was for a still-trusted tier (e.g.
+  //      'STAFF'), the cost is one extra COMMENT review pending
+  //      human approval; if it was a new external tier, we've closed
+  //      the drive-by exploit. Asymmetric risk → fail closed.
+  const rawAssoc = String(process.env.PR_AUTHOR_ASSOCIATION ?? '').trim();
+  const validAssociations = new Set([
+    'OWNER', 'MEMBER', 'COLLABORATOR', 'CONTRIBUTOR',
+    'FIRST_TIME_CONTRIBUTOR', 'FIRST_TIMER', 'NONE', 'MANNEQUIN',
+  ]);
+  let authorAssociation;
+  if (rawAssoc === '') {
+    // Back-compat for legacy callers without author_association.
+    authorAssociation = 'CONTRIBUTOR';
+  } else if (validAssociations.has(rawAssoc)) {
+    authorAssociation = rawAssoc;
+  } else {
+    // Fail-closed for unrecognized future tokens. 'NONE' is the
+    // weakest external tier and the safest default — selectReviewEvent
+    // routes it to COMMENT (never APPROVE, never REQUEST_CHANGES).
+    process.stderr.write(
+      `clud-bug select-review-event: unrecognized PR_AUTHOR_ASSOCIATION="${rawAssoc}" — treating as external (fail-closed per SPEC §7.2.1).\n`,
+    );
+    authorAssociation = 'NONE';
+  }
+
+  const strictMode = String(process.env.STRICT_MODE ?? '').trim() === 'true';
+
+  const event = selectReviewEvent({
+    criticalCount,
+    minorCount,
+    strictMode,
+    prAuthorLogin,
+    authorAssociation,
+  });
+  process.stdout.write(event + '\n');
+}
+
+
+// Wave 5a / 0.7.0-rc.7: post per-finding inline review threads (D.2.X)
+// to the PR.  Replaces the legacy "one summary comment listing every
+// finding" UX with first-class GitHub review threads users can reply to
+// and (in Wave 5b) the bot can auto-resolve on fix-push.
+//
+// Pipeline:
+//   1. Read the structured review JSON from stdin (same shape the
+//      `render` and `update-skill-usage` verbs consume).
+//   2. Fetch the PR's per-file diff via `gh api repos/.../pulls/N/files`.
+//   3. Call `planInlineThreads(findings, diffFiles)` from
+//      `clud-bug/core/inline-threads` to partition into anchored
+//      `comments[]` + skipped + preexisting buckets.
+//   4. If any comments survive: POST one batched review via
+//      `gh api -X POST repos/.../pulls/N/reviews` with `event: COMMENT`.
+//      Each comment body carries a hidden `<!-- finding-id: <hash> -->`
+//      marker so Wave 5b auto-resolve can re-derive the same ids on
+//      subsequent pushes without a persistent store.
+//   5. Emit a JSON summary on stdout (`{posted, skipped, preexisting}`).
+//
+// Required env vars (the workflow template provides all of them):
+//   GH_TOKEN, REPO ("owner/name"), PR_NUMBER, HEAD_SHA
+//
+// Failure posture: any `gh api` failure is logged to stderr + emitted in
+// the stdout JSON as `error`, but the verb exits 0 so the surrounding
+// workflow step's `continue-on-error: true` is the single source of
+// failure semantics. Mirrors the `render` / `update-skill-usage` posture.
+async function runPostInlineThreads(args) {
+  const { planInlineThreads } = await import('../core/inline-threads.js');
+
+  if (!args.stdin) {
+    process.stderr.write(
+      'clud-bug post-inline-threads: --stdin is required.\n',
+    );
+    process.stdout.write(JSON.stringify({ posted: 0, skipped: [], preexisting: [], error: 'no-stdin' }) + '\n');
+    return;
+  }
+
+  let raw = '';
+  for await (const chunk of process.stdin) raw += chunk;
+  raw = raw.trim();
+  if (!raw) {
+    process.stderr.write(
+      'clud-bug post-inline-threads: stdin empty — no-op.\n',
+    );
+    process.stdout.write(JSON.stringify({ posted: 0, skipped: [], preexisting: [], error: 'empty-stdin' }) + '\n');
+    return;
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch (e) {
+    process.stderr.write(
+      `clud-bug post-inline-threads: JSON parse failed: ${e.message} — no-op.\n`,
+    );
+    process.stdout.write(JSON.stringify({ posted: 0, skipped: [], preexisting: [], error: 'parse-failed' }) + '\n');
+    return;
+  }
+  if (!payload || typeof payload !== 'object') {
+    process.stderr.write(
+      'clud-bug post-inline-threads: payload must be a JSON object — no-op.\n',
+    );
+    process.stdout.write(JSON.stringify({ posted: 0, skipped: [], preexisting: [], error: 'not-object' }) + '\n');
+    return;
+  }
+
+  // Pull findings from the structured_output shape — same field names as
+  // the SPEC §1.8.1 review schema the model emits.
+  const findings = [];
+  for (const f of Array.isArray(payload.critical_findings) ? payload.critical_findings : []) {
+    if (f && typeof f === 'object') {
+      findings.push({ ...f, severity: 'critical' });
+    }
+  }
+  for (const f of Array.isArray(payload.minor_findings) ? payload.minor_findings : []) {
+    if (f && typeof f === 'object') {
+      findings.push({ ...f, severity: 'minor' });
+    }
+  }
+  // `preexisting_findings` are intentionally not threaded (informational
+  // about prior code; not a reason to block this PR). `planInlineThreads`
+  // partitions them into the `preexisting` bucket if any are included, but
+  // the workflow path doesn't ship them — keep the payload focused.
+
+  if (findings.length === 0) {
+    process.stdout.write(JSON.stringify({ posted: 0, skipped: [], preexisting: [], reason: 'no-findings' }) + '\n');
+    return;
+  }
+
+  // Required env vars.
+  const repo = String(process.env.REPO ?? '').trim();
+  const prNumberRaw = String(process.env.PR_NUMBER ?? '').trim();
+  const headSha = String(process.env.HEAD_SHA ?? '').trim();
+  const prNumber = Number(prNumberRaw);
+  if (!repo || !repo.includes('/') || !Number.isInteger(prNumber) || prNumber <= 0 || !headSha) {
+    process.stderr.write(
+      `clud-bug post-inline-threads: REPO + PR_NUMBER + HEAD_SHA env vars required (got REPO=${repo}, PR_NUMBER=${prNumberRaw}, HEAD_SHA=${headSha ? '<set>' : '<unset>'}).\n`,
+    );
+    process.stdout.write(JSON.stringify({ posted: 0, skipped: [], preexisting: [], error: 'missing-env' }) + '\n');
+    return;
+  }
+
+  // Fetch the PR's diff. `gh api repos/.../pulls/N/files --paginate`
+  // returns a JSON array of {filename, patch, status, ...}. The single
+  // -slurp on multi-page output stitches all pages into one big array.
+  const filesResult = spawnSync(
+    'gh',
+    [
+      'api',
+      `repos/${repo}/pulls/${prNumber}/files`,
+      '--paginate',
+      '--slurp',
+    ],
+    { encoding: 'utf8' },
+  );
+  if (filesResult.status !== 0) {
+    process.stderr.write(
+      `clud-bug post-inline-threads: \`gh api .../files\` failed (exit ${filesResult.status}): ${(filesResult.stderr || '').slice(0, 500)}\n`,
+    );
+    process.stdout.write(JSON.stringify({ posted: 0, skipped: [], preexisting: [], error: 'diff-fetch-failed' }) + '\n');
+    return;
+  }
+
+  let diffFiles = [];
+  try {
+    // --slurp wraps each page in an outer array; flatten one level.
+    const pages = JSON.parse(filesResult.stdout);
+    if (Array.isArray(pages)) {
+      for (const page of pages) {
+        if (Array.isArray(page)) diffFiles.push(...page);
+      }
+    }
+  } catch (e) {
+    process.stderr.write(
+      `clud-bug post-inline-threads: diff JSON parse failed: ${e.message}\n`,
+    );
+    process.stdout.write(JSON.stringify({ posted: 0, skipped: [], preexisting: [], error: 'diff-parse-failed' }) + '\n');
+    return;
+  }
+
+  const plan = planInlineThreads(findings, diffFiles);
+  if (plan.comments.length === 0) {
+    // Everything fell through to summary-comment fallback (no anchor
+    // matches). Not a failure — emit the breakdown so the workflow log
+    // explains why no inline threads were posted.
+    process.stdout.write(JSON.stringify({
+      posted: 0,
+      skipped: plan.skipped.map((f) => ({ skill: f.skill, file: f.file, line: f.line, reason: 'not-anchorable' })),
+      preexisting: plan.preexisting.map((f) => ({ skill: f.skill })),
+      reason: 'no-anchorable-findings',
+    }) + '\n');
+    return;
+  }
+
+  // Post the review. gh accepts the body as a JSON file via --input — we
+  // pipe through stdin with `--input -`. Build the body as JSON-on-one-line
+  // so stdin is a single write that `gh` reads start-to-finish.
+  const reviewBody = JSON.stringify({
+    commit_id: headSha,
+    event: 'COMMENT',
+    body: `Clud-Bug posted ${plan.comments.length} inline finding${plan.comments.length === 1 ? '' : 's'}.`,
+    comments: plan.comments,
+  });
+
+  const postResult = spawnSync(
+    'gh',
+    [
+      'api',
+      '--method', 'POST',
+      `repos/${repo}/pulls/${prNumber}/reviews`,
+      '--input', '-',
+    ],
+    { encoding: 'utf8', input: reviewBody },
+  );
+  if (postResult.status !== 0) {
+    process.stderr.write(
+      `clud-bug post-inline-threads: \`gh api -X POST .../reviews\` failed (exit ${postResult.status}): ${(postResult.stderr || '').slice(0, 500)}\n`,
+    );
+    process.stdout.write(JSON.stringify({
+      posted: 0,
+      skipped: plan.skipped.map((f) => ({ skill: f.skill, file: f.file, line: f.line, reason: 'not-anchorable' })),
+      preexisting: plan.preexisting.map((f) => ({ skill: f.skill })),
+      error: 'review-post-failed',
+    }) + '\n');
+    return;
+  }
+
+  process.stdout.write(JSON.stringify({
+    posted: plan.comments.length,
+    skipped: plan.skipped.map((f) => ({ skill: f.skill, file: f.file, line: f.line, reason: 'not-anchorable' })),
+    preexisting: plan.preexisting.map((f) => ({ skill: f.skill })),
+  }) + '\n');
+}
+
+
+// Wave 5b / 0.7.0-rc.8: D.2.6 auto-resolve on fix-push. Fetches all
+// bot-authored unresolved inline threads, asks the Anthropic Messages
+// API per-thread whether the new commit addressed the original
+// finding, and resolves ADDRESSED threads (with a marker reply) while
+// leaving UNCERTAIN/NOT_ADDRESSED open. Fail-closed throughout —
+// verifier errors route to UNCERTAIN; the surrounding workflow
+// step's `continue-on-error: true` is the single failure gate.
+//
+// Required env: GH_TOKEN, ANTHROPIC_API_KEY, REPO ("owner/name"), PR_NUMBER.
+//
+// No `--stdin` — fetches everything from `gh api graphql` itself.
+// Workflow gates this verb on `github.event.action == 'synchronize'`
+// so it only runs on fix-pushes (not initial PR opens, when there
+// are no prior threads to resolve).
+async function runResolveThreads(_args) {
+  const {
+    parseThreadBody,
+    extractAnchorContext,
+    REVIEW_THREADS_QUERY,
+    RESOLVE_THREAD_MUTATION,
+    ADD_REPLY_MUTATION,
+  } = await import('../core/inline-threads.js');
+  const {
+    readAutoResolveConfigFromCludBug,
+    runAutoResolve,
+    applyResolutionRules,
+    selectResolveAuth,
+    renderResolveMarkerTag,
+    anchorSignature,
+    latestResolveMarker,
+  } = await import('../core/auto-resolve.js');
+  const {
+    VERIFIER_SYSTEM,
+    buildVerifierPrompt,
+    parseVerifierResponse,
+  } = await import('../core/resolve-verifier.js');
+
+  // ---- Env validation ----------------------------------------------------
+  const repo = String(process.env.REPO ?? '').trim();
+  const prNumberRaw = String(process.env.PR_NUMBER ?? '').trim();
+  const prNumber = Number(prNumberRaw);
+  const ghToken = String(process.env.GH_TOKEN ?? '').trim();
+  const anthropicKey = String(process.env.ANTHROPIC_API_KEY ?? '').trim();
+  if (!repo || !repo.includes('/') || !Number.isInteger(prNumber) || prNumber <= 0 || !ghToken || !anthropicKey) {
+    process.stderr.write(
+      `clud-bug resolve-threads: REPO + PR_NUMBER + GH_TOKEN + ANTHROPIC_API_KEY env vars required.\n`,
+    );
+    process.stdout.write(JSON.stringify({ actions: [], verifierCallCount: 0, shouldRequestChanges: false, error: 'missing-env' }) + '\n');
+    return;
+  }
+  const [owner, repoName] = repo.split('/', 2);
+
+  // ---- Optional .clud-bug.json config (autoResolve block) ----------------
+  // The workflow's working dir is the PR checkout — if .clud-bug.json is
+  // present we read autoResolve from it. Otherwise defaults (mode='verified').
+  let autoResolveConfig;
+  try {
+    const cfgPath = join(process.cwd(), '.claude/skills/.clud-bug.json');
+    const cfgRaw = await readFile(cfgPath, 'utf8');
+    const cfg = JSON.parse(cfgRaw);
+    autoResolveConfig = readAutoResolveConfigFromCludBug(cfg, (msg) => {
+      process.stderr.write(`clud-bug resolve-threads: config warning: ${msg}\n`);
+    });
+  } catch (err) {
+    // Missing OR unparseable .clud-bug.json — use defaults but log the
+    // specific reason so an operator with malformed config can diagnose
+    // why their `autoResolve.mode = 'off'` is being silently ignored.
+    const code = err && typeof err === 'object' && 'code' in err ? err.code : undefined;
+    if (code !== 'ENOENT') {
+      process.stderr.write(
+        `clud-bug resolve-threads: .clud-bug.json read/parse error (${err && typeof err === 'object' && 'message' in err ? err.message : String(err)}); using defaults.\n`,
+      );
+    }
+    autoResolveConfig = readAutoResolveConfigFromCludBug(null);
+  }
+
+  if (autoResolveConfig.mode === 'off') {
+    process.stdout.write(JSON.stringify({ actions: [], verifierCallCount: 0, shouldRequestChanges: false, reason: 'mode-off' }) + '\n');
+    return;
+  }
+
+  // ---- Fetch threads via GraphQL -----------------------------------------
+  // `gh api graphql` uses `-f` for String! variables and `-F` for typed
+  // (number / bool) variables. Owner + repo are String! per the query;
+  // pr is Int!. Reviewer-flagged: passing owner/repo as `-F` would coerce
+  // numeric-looking values incorrectly.
+  const threadsResult = spawnSync(
+    'gh',
+    [
+      'api', 'graphql',
+      '-f', `query=${REVIEW_THREADS_QUERY}`,
+      '-f', `owner=${owner}`,
+      '-f', `repo=${repoName}`,
+      '-F', `pr=${prNumber}`,
+    ],
+    { encoding: 'utf8' },
+  );
+  if (threadsResult.status !== 0) {
+    process.stderr.write(`clud-bug resolve-threads: gh api graphql (threads) failed (exit ${threadsResult.status}): ${(threadsResult.stderr || '').slice(0, 500)}\n`);
+    process.stdout.write(JSON.stringify({ actions: [], verifierCallCount: 0, shouldRequestChanges: false, error: 'threads-fetch-failed' }) + '\n');
+    return;
+  }
+
+  let threadNodes;
+  try {
+    const parsed = JSON.parse(threadsResult.stdout);
+    threadNodes = parsed?.data?.repository?.pullRequest?.reviewThreads?.nodes ?? [];
+    if (!Array.isArray(threadNodes)) threadNodes = [];
+  } catch (e) {
+    process.stderr.write(`clud-bug resolve-threads: threads JSON parse failed: ${e.message}\n`);
+    process.stdout.write(JSON.stringify({ actions: [], verifierCallCount: 0, shouldRequestChanges: false, error: 'threads-parse-failed' }) + '\n');
+    return;
+  }
+
+  // ---- Filter to bot-authored unresolved threads with our marker --------
+  // The workflow's GITHUB_TOKEN posts as `github-actions[bot]`. Match both
+  // the bracketed bot form and the bare `github-actions` form (GraphQL
+  // can return either depending on the node-type field requested).
+  const BOT_AUTHORS = new Set(['github-actions', 'github-actions[bot]']);
+  const candidates = [];
+  for (const t of threadNodes) {
+    if (!t || t.isResolved) continue;
+    const c = t.comments?.nodes?.[0];
+    if (!c) continue;
+    const authorLogin = c.author?.login ?? '';
+    if (!BOT_AUTHORS.has(authorLogin)) continue;
+    const parsed = parseThreadBody(c.body ?? '');
+    if (!parsed) continue;
+    if (!c.path || (c.line === null && c.originalLine === null)) continue;
+    candidates.push({
+      threadId: t.id,
+      file: c.path,
+      line: c.line ?? c.originalLine,
+      parsed,
+      // Wave 5b.1: full comment list so idempotency can spot a prior
+      // bot reply's resolve marker (verdict + anchor sig) on this thread.
+      comments: t.comments?.nodes ?? [],
+    });
+  }
+
+  if (candidates.length === 0) {
+    process.stdout.write(JSON.stringify({ actions: [], verifierCallCount: 0, shouldRequestChanges: false, reason: 'no-bot-threads' }) + '\n');
+    return;
+  }
+
+  // ---- Fetch diff for anchor context -------------------------------------
+  const filesResult = spawnSync(
+    'gh',
+    [
+      'api',
+      `repos/${repo}/pulls/${prNumber}/files`,
+      '--paginate',
+      '--slurp',
+    ],
+    { encoding: 'utf8' },
+  );
+  if (filesResult.status !== 0) {
+    process.stderr.write(`clud-bug resolve-threads: diff fetch failed (exit ${filesResult.status}): ${(filesResult.stderr || '').slice(0, 500)}\n`);
+    process.stdout.write(JSON.stringify({ actions: [], verifierCallCount: 0, shouldRequestChanges: false, error: 'diff-fetch-failed' }) + '\n');
+    return;
+  }
+  let diffFiles = [];
+  try {
+    const pages = JSON.parse(filesResult.stdout);
+    if (Array.isArray(pages)) {
+      for (const page of pages) {
+        if (Array.isArray(page)) diffFiles.push(...page);
+      }
+    }
+  } catch (e) {
+    process.stderr.write(`clud-bug resolve-threads: diff JSON parse failed: ${e.message}\n`);
+    process.stdout.write(JSON.stringify({ actions: [], verifierCallCount: 0, shouldRequestChanges: false, error: 'diff-parse-failed' }) + '\n');
+    return;
+  }
+
+  // ---- Build PriorThread[] for runAutoResolve ----------------------------
+  const priorThreads = candidates.map((c) => {
+    const ctx = extractAnchorContext({ file: c.file, line: c.line }, diffFiles);
+    const findingBody = c.parsed.reasoning
+      ? `${c.parsed.summary}\n\n${c.parsed.reasoning}`
+      : c.parsed.summary;
+    return {
+      threadId: c.threadId,
+      finding: {
+        severity: c.parsed.severity,
+        body: findingBody,
+        skill: c.parsed.skill,
+        file: c.file,
+        line: c.line,
+      },
+      codeBefore: ctx.codeBefore,
+      codeAfter: ctx.codeAfter,
+      ...(ctx.diffAtAnchor !== undefined ? { diffAtAnchor: ctx.diffAtAnchor } : {}),
+    };
+  });
+
+  // ---- Define verifier (Anthropic Messages API via raw fetch) -----------
+  // Model is hardcoded here — the verifier needs a model that handles
+  // structured JSON output reliably. Sonnet 4.6 is the default. Override
+  // via CLUD_BUG_VERIFIER_MODEL env var if needed.
+  const verifierModel = String(process.env.CLUD_BUG_VERIFIER_MODEL ?? '').trim()
+    || 'claude-sonnet-4-6';
+
+  async function verifier(input) {
+    const userPrompt = buildVerifierPrompt(input);
+    try {
+      const resp = await fetch('https://api.anthropic.com/v1/messages', {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          'anthropic-version': '2023-06-01',
+          'x-api-key': anthropicKey,
+        },
+        body: JSON.stringify({
+          model: verifierModel,
+          max_tokens: 300,
+          system: VERIFIER_SYSTEM,
+          messages: [{ role: 'user', content: userPrompt }],
+        }),
+      });
+      if (!resp.ok) {
+        const errText = await resp.text().catch(() => '');
+        return {
+          verdict: 'UNCERTAIN',
+          source: 'api-error',
+          rationale: `Anthropic API ${resp.status}: ${errText.slice(0, 200)}`,
+        };
+      }
+      const body = await resp.json();
+      // Messages API: content is an array of blocks; pick the first text block.
+      const text = (body?.content ?? []).find((b) => b?.type === 'text')?.text ?? '';
+      return parseVerifierResponse(text);
+    } catch (err) {
+      return {
+        verdict: 'UNCERTAIN',
+        source: 'api-error',
+        rationale: `verifier fetch error: ${err?.message ?? String(err)}`,
+      };
+    }
+  }
+
+  // ---- Resolve auth (Wave 5b.1: PAT optional + graceful fallback) -------
+  // A dedicated PAT lets us actually close threads; without one the Actions
+  // GITHUB_TOKEN can't resolve, so we post a "verified fixed" reply only.
+  const auth = selectResolveAuth(process.env);
+
+  // ---- Idempotency: skip threads whose anchor is unchanged --------------
+  // For each candidate, hash the post-fix anchor and look for a prior bot
+  // reply carrying the same (verdict, sig) marker. If the anchor hasn't moved
+  // since that marker, we re-use the cached verdict — NO verifier call, NO
+  // re-post — which kills repeat replies on multi-push PRs and saves spend.
+  const verifyItems = []; // { thread, sig } — need (re)verification
+  const cachedItems = []; // { thread, action } — anchor unchanged, no I/O
+  for (let i = 0; i < priorThreads.length; i++) {
+    const thread = priorThreads[i];
+    const candidate = candidates[i];
+    if (!thread) continue;
+    const sig = anchorSignature(thread.finding, thread.codeAfter);
+    const prior = latestResolveMarker(candidate?.comments ?? [], BOT_AUTHORS);
+    if (prior && prior.sig === sig) {
+      const action = applyResolutionRules({
+        thread,
+        verdict: {
+          verdict: prior.verdict,
+          source: 'model',
+          rationale: '(unchanged since last check)',
+        },
+        config: autoResolveConfig,
+        canResolve: auth.hasDedicatedPat,
+      });
+      cachedItems.push({ thread, action });
+    } else {
+      verifyItems.push({ thread, sig });
+    }
+  }
+
+  // ---- Run pure orchestration on the threads that need (re)verification --
+  const result = await runAutoResolve({
+    priorThreads: verifyItems.map((v) => v.thread),
+    config: autoResolveConfig,
+    verifier,
+    canResolve: auth.hasDedicatedPat,
+  });
+
+  let shouldRequestChanges = result.shouldRequestChanges;
+  for (const c of cachedItems) {
+    if (c.action.kind === 'keep_open_request_changes') shouldRequestChanges = true;
+  }
+
+  // ---- Execute the actions via GraphQL mutations ------------------------
+  const actionsReport = [];
+
+  // Unchanged threads: never re-post the reply (idempotent). BUT if the
+  // thread is verified ADDRESSED and a PAT is now available, resolve it —
+  // the marker reply already exists, so this closes a thread that couldn't
+  // be resolved before (no-PAT → PAT upgrade, or a prior transient
+  // resolve-failure) WITHOUT re-verifying or re-replying.
+  for (const c of cachedItems) {
+    const baseReport = {
+      threadId: c.thread.threadId,
+      file: c.thread.finding.file,
+      line: c.thread.finding.line,
+      verdict: c.action.verdict?.verdict,
+      kind: c.action.kind,
+    };
+    if (c.action.kind === 'resolve' && auth.hasDedicatedPat) {
+      const resolveResult = spawnSync(
+        'gh',
+        [
+          'api', 'graphql',
+          '-f', `query=${RESOLVE_THREAD_MUTATION}`,
+          '-f', `threadId=${c.thread.threadId}`,
+        ],
+        { encoding: 'utf8', env: { ...process.env, GH_TOKEN: auth.token } },
+      );
+      if (resolveResult.status !== 0) {
+        process.stderr.write(`clud-bug resolve-threads: RESOLVE (cached) failed for thread ${c.thread.threadId}: ${(resolveResult.stderr || '').slice(0, 200)}\n`);
+        actionsReport.push({ ...baseReport, executed: 'resolve-failed' });
+      } else {
+        actionsReport.push({ ...baseReport, executed: 'resolved-from-cache' });
+      }
+    } else {
+      actionsReport.push({ ...baseReport, executed: 'unchanged' });
+    }
+  }
+
+  for (let i = 0; i < result.actions.length; i++) {
+    const action = result.actions[i];
+    const item = verifyItems[i];
+    if (!action || !item) continue;
+    const thread = item.thread;
+    const report = {
+      threadId: thread.threadId,
+      file: thread.finding.file,
+      line: thread.finding.line,
+      verdict: action.verdict?.verdict,
+      kind: action.kind,
+    };
+
+    if (action.kind === 'skipped') {
+      actionsReport.push({ ...report, executed: 'skipped' });
+      continue;
+    }
+
+    // Reply body carries a hidden idempotency marker (verdict + anchor sig)
+    // so a later fix-push won't re-reply while the anchor is unchanged.
+    const tag = renderResolveMarkerTag(action.verdict.verdict, item.sig);
+    const replyBody = `${action.markerBody}\n\n${tag}`;
+    const replyResult = spawnSync(
+      'gh',
+      [
+        'api', 'graphql',
+        '-f', `query=${ADD_REPLY_MUTATION}`,
+        '-f', `threadId=${thread.threadId}`,
+        '-f', `body=${replyBody}`,
+      ],
+      { encoding: 'utf8' },
+    );
+    if (replyResult.status !== 0) {
+      process.stderr.write(`clud-bug resolve-threads: ADD_REPLY failed for thread ${thread.threadId}: ${(replyResult.stderr || '').slice(0, 200)}\n`);
+      actionsReport.push({ ...report, executed: 'reply-failed' });
+      continue;
+    }
+
+    // Resolve only ADDRESSED threads, and only with a dedicated PAT — the
+    // Actions GITHUB_TOKEN can't resolve ("Resource not accessible by
+    // integration"). No PAT → marker-reply-only (graceful, no error).
+    if (action.kind === 'resolve') {
+      if (!auth.hasDedicatedPat) {
+        actionsReport.push({ ...report, executed: 'reply-only-no-pat' });
+        continue;
+      }
+      const resolveResult = spawnSync(
+        'gh',
+        [
+          'api', 'graphql',
+          '-f', `query=${RESOLVE_THREAD_MUTATION}`,
+          '-f', `threadId=${thread.threadId}`,
+        ],
+        // Scope the PAT to JUST this call; all other gh calls keep GH_TOKEN.
+        { encoding: 'utf8', env: { ...process.env, GH_TOKEN: auth.token } },
+      );
+      if (resolveResult.status !== 0) {
+        process.stderr.write(`clud-bug resolve-threads: RESOLVE failed for thread ${thread.threadId}: ${(resolveResult.stderr || '').slice(0, 200)}\n`);
+        actionsReport.push({ ...report, executed: 'resolve-failed' });
+        continue;
+      }
+      actionsReport.push({ ...report, executed: 'resolved' });
+    } else {
+      // keep_open or keep_open_request_changes — reply already posted.
+      actionsReport.push({ ...report, executed: 'kept-open' });
+    }
+  }
+
+  process.stdout.write(JSON.stringify({
+    actions: actionsReport,
+    verifierCallCount: result.verifierCallCount,
+    shouldRequestChanges,
+    resolveTokenSource: auth.source,
+  }) + '\n');
+}
+
+
 // 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.
@@ -426,29 +1286,114 @@ async function runInit(args) {
       language: templateLanguage(tmplName),
     }),
   });
-  const workflowPath = join(cwd, '.github', 'workflows', 'clud-bug-review.yml');
-  await mkdir(dirname(workflowPath), { recursive: true });
-  await writeFile(workflowPath, workflow);
-  log(`    wrote ${rel(cwd, workflowPath)}`);
-
-  // Install the audit workflow alongside the per-PR review one.
-  // Manual-trigger by default; users opt into the cron by uncommenting.
-  // Routed through renderFile so {{CCA_VERSION}} substitution pins
-  // claude-code-action consistently with the review workflow.
-  const auditTmpl = await renderFile(join(TEMPLATES, 'audit.yml.tmpl'), {});
-  const auditPath = join(cwd, '.github', 'workflows', 'clud-bug-audit.yml');
-  await writeFile(auditPath, auditTmpl);
-  log(`    wrote ${rel(cwd, auditPath)}`);
-
-  // Install the self-update workflow. Cron weekly Mondays 12:00 UTC; opens
-  // a PR if a newer clud-bug version is published. Disable by deleting the
-  // file or pinning via .claude/skills/.clud-bug.json.
-  // Routed through renderFile for parity (no CCA ref today but future
-  // tokens should propagate uniformly).
-  const selfUpdateTmpl = await renderFile(join(TEMPLATES, 'self-update.yml.tmpl'), {});
-  const selfUpdatePath = join(cwd, '.github', 'workflows', 'clud-bug-self-update.yml');
-  await writeFile(selfUpdatePath, selfUpdateTmpl);
-  log(`    wrote ${rel(cwd, selfUpdatePath)}`);
+  // --local-only (max mode): SKIP the GitHub Action workflows entirely. The
+  // review + audit workflows run `claude-code-action` with ANTHROPIC_API_KEY
+  // (per-token cost); max mode reviews on the session's own subscription, so a
+  // local-only install must never add a token-billing Action. (self-update is
+  // benign but skipped too — local-only means no clud-bug CI workflows at all.)
+  if (args.localOnly) {
+    log('    skipped GitHub Action workflows (--local-only: max mode runs on the session subscription, no API key)');
+  } else {
+    const workflowPath = join(cwd, '.github', 'workflows', 'clud-bug-review.yml');
+    await mkdir(dirname(workflowPath), { recursive: true });
+    await writeFile(workflowPath, workflow);
+    log(`    wrote ${rel(cwd, workflowPath)}`);
+
+    // Install the audit workflow alongside the per-PR review one.
+    // Manual-trigger by default; users opt into the cron by uncommenting.
+    // Routed through renderFile so {{CCA_VERSION}} substitution pins
+    // claude-code-action consistently with the review workflow.
+    const auditTmpl = await renderFile(join(TEMPLATES, 'audit.yml.tmpl'), {});
+    const auditPath = join(cwd, '.github', 'workflows', 'clud-bug-audit.yml');
+    await writeFile(auditPath, auditTmpl);
+    log(`    wrote ${rel(cwd, auditPath)}`);
+
+    // Install the self-update workflow. Cron weekly Mondays 12:00 UTC; opens
+    // a PR if a newer clud-bug version is published. Disable by deleting the
+    // file or pinning via .claude/skills/.clud-bug.json.
+    // Routed through renderFile for parity (no CCA ref today but future
+    // tokens should propagate uniformly).
+    const selfUpdateTmpl = await renderFile(join(TEMPLATES, 'self-update.yml.tmpl'), {});
+    const selfUpdatePath = join(cwd, '.github', 'workflows', 'clud-bug-self-update.yml');
+    await writeFile(selfUpdatePath, selfUpdateTmpl);
+    log(`    wrote ${rel(cwd, selfUpdatePath)}`);
+  }
+
+  // v0.7.0 (Wave 6b): optional local-review slash command. Scaffolds
+  // `.claude/commands/clud-bug-review.md` so `/clud-bug-review` works inside a
+  // 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).
+  // --local-only IS the max-mode install: the slash command + the commit hook,
+  // minus the GitHub Action workflows (gated above).
+  if (args.localOnly) {
+    args.withLocalReview = true;
+    args.withHooks = true;
+  }
+  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 });
+    const commandContent = await renderFile(join(TEMPLATES, 'clud-bug-review.md.tmpl'), {});
+    await writeFile(commandPath, commandContent);
+    log(`    wrote ${rel(cwd, commandPath)}`);
+  }
+
+  // v0.7.0 (Wave 6b; rc.17 fix): optional native commit-review hook. Merges a
+  // Claude Code `type: command` PostToolUse hook into `.claude/settings.json`
+  // (preserving any existing settings + hooks) that, on every `git commit`, runs
+  // `clud-bug review-prompt` and surfaces the recipe back to the session so the
+  // agent reviews the commit on the session's subscription, in the background.
+  // (`type: command`, not `type: agent` — agent hooks get no Bash, so they could
+  // never run the CLI; see hooks.ts.)
+  if (args.withHooks) {
+    const { mergeLocalReviewHook, buildCommitReviewCommand } = await import('./hooks.js');
+    // Floating @next pin (default) — the hook auto-fetches the latest recipe.
+    const hookCommand = buildCommitReviewCommand();
+    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, hookCommand);
+      await writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n');
+      log(`    wrote ${rel(cwd, settingsPath)} (commit-review hook)`);
+    }
+  }
+
+  // rc.16: --with-design installs the bundled design-critic kit (3 `kind:
+  // design` skills) and enables the off-by-default design lens. writeSkills
+  // writes the SKILL.md files + merges the manifest entries; the `design` block
+  // is flipped on the manifest read below so the local recipe + hosted bot both
+  // run the visual pass. Idempotent — re-runs replace the skills in place.
+  if (args.withDesign) {
+    const designKit = await loadDesignKit(DESIGN_DIR);
+    if (designKit.length > 0) {
+      await writeSkills(join(cwd, '.claude', 'skills'), designKit, client);
+      log(`    pinned ${designKit.length} design specimens (visual review lens enabled)`);
+    } else {
+      warn('No design-kit skills found to install (templates/skills/design/ empty?).');
+    }
+  }
 
   // Stamp the manifest. Sets strictMode: true ONLY on fresh installs —
   // a manifest that's never been touched by clud-bug init/update has no
@@ -458,6 +1403,12 @@ async function runInit(args) {
   // fresh inits. Users opt out by setting strictMode: false.
   const skillsDirPath = join(cwd, '.claude', 'skills');
   const manifest = await readManifest(skillsDirPath);
+  if (args.withDesign) {
+    // Flip the off-by-default design lens on; preserve any existing knobs
+    // (gate / themes / viewports) the user already set.
+    const prior = (manifest.design as Record<string, unknown> | undefined) ?? {};
+    manifest.design = { ...prior, enabled: true };
+  }
   const isFreshInstall = manifest.lastUpdate === undefined;
   manifest.lastUpdateVersion = await readPkgVersion();
   manifest.lastUpdate = new Date().toISOString();
@@ -487,9 +1438,14 @@ async function runInit(args) {
     log('  committing...');
     const toAdd = [
       '.claude',
-      '.github/workflows/clud-bug-review.yml',
-      '.github/workflows/clud-bug-audit.yml',
-      '.github/workflows/clud-bug-self-update.yml',
+      // No GitHub Action workflows under --local-only (none were written).
+      ...(args.localOnly
+        ? []
+        : [
+            '.github/workflows/clud-bug-review.yml',
+            '.github/workflows/clud-bug-audit.yml',
+            '.github/workflows/clud-bug-self-update.yml',
+          ]),
       ...agentDocs.created,
       ...agentDocs.touched,
     ];
@@ -506,21 +1462,40 @@ async function runInit(args) {
 
   log('');
   log('Field kit assembled. Next:');
-  log('  1. Set ANTHROPIC_API_KEY in your repo secrets:');
-  log('     Settings → Secrets and variables → Actions → New repository secret');
-  if (!args.commit) {
-    log('  2. git add .claude .github/workflows/clud-bug-*.yml && git commit && git push');
-    log('  3. Open a PR — the naturalist arrives within ~2 minutes.');
+  if (args.localOnly) {
+    log('  Max mode — reviews run inside your Claude Code session on your own');
+    log('  subscription. No API key, no GitHub Action, no per-review bill. On every');
+    log('  commit the hook surfaces a review recipe; or run /clud-bug-review on demand.');
+    if (!args.commit) {
+      log('  → git add .claude && git commit && git push');
+    } else {
+      log('  → git push.');
+    }
   } else {
-    log('  2. git push, then open a PR — the naturalist arrives within ~2 minutes.');
+    log('  1. Set ANTHROPIC_API_KEY in your repo secrets:');
+    log('     Settings → Secrets and variables → Actions → New repository secret');
+    if (!args.commit) {
+      log('  2. git add .claude .github/workflows/clud-bug-*.yml && git commit && git push');
+      log('  3. Open a PR — the naturalist arrives within ~2 minutes.');
+    } else {
+      log('  2. git push, then open a PR — the naturalist arrives within ~2 minutes.');
+    }
   }
   log('');
   log('Drop your own .claude/skills/<name>/SKILL.md files anytime — they get pinned automatically.');
-  log('For a whole-repo walk: Actions tab → Clud Bug 🐛 Audit → Run workflow.');
-  log('Self-update is on (weekly Mondays 12:00 UTC). Pin via "pinVersion" in .claude/skills/.clud-bug.json.');
+  // These reference the GitHub Action workflows, which --local-only does not write.
+  if (!args.localOnly) {
+    log('For a whole-repo walk: Actions tab → Clud Bug 🐛 Audit → Run workflow.');
+    log('Self-update is on (weekly Mondays 12:00 UTC). Pin via "pinVersion" in .claude/skills/.clud-bug.json.');
+  }
   log('');
-  log('Strict mode is ON by default (clud-bug-review fails the check on critical findings).');
-  log('  • Add `clud-bug-review` to your branch protection required checks for full enforcement.');
+  if (args.localOnly) {
+    log('Strict mode + branch-protection enforcement apply to the GitHub Action path; max mode is');
+    log('advisory by design — findings surface in your session for you to act on.');
+  } else {
+    log('Strict mode is ON by default (clud-bug-review fails the check on critical findings).');
+    log('  • Add `clud-bug-review` to your branch protection required checks for full enforcement.');
+  }
   log('  • Opt out by setting "strictMode": false in .claude/skills/.clud-bug.json.');
 
   // v0.6.33 — opt-in unified install (mirror of logmind v0.6.8). When
@@ -988,6 +1963,25 @@ async function runUpdateCmd(_args) {
   ok(`updated: @v${ourVersion}, ${result.changed.length} changed, ${result.unchanged.length} unchanged${skipped.length ? `, ${skipped.length} skipped` : ''}`);
 }
 
+// v0.7.0-rc.4 — `clud-bug configure-github <owner>/<repo>`. Pulls in the
+// SPEC §7 canonical ruleset applier from src/cli/configure-github.ts;
+// thin wrapper here just maps CLI args into the typed entry point. The
+// command is idempotent — re-runs on a converged repo exit 0 with no
+// PATCH calls. See `src/core/configure-github.ts` for the diff + rule
+// table.
+async function runConfigureGithubCmd(args) {
+  const { runConfigureGithub } = await import('./configure-github.js');
+  const target = args._[1] ?? null;
+  const code = await runConfigureGithub({
+    target,
+    branch: args.branch || 'main',
+    dryRun: Boolean(args.dryRun),
+    quiet: QUIET,
+    json: Boolean(args.json),
+  });
+  if (code !== 0) process.exit(code);
+}
+
 async function runAudit(args) {
   const cwd = process.cwd();
   const date = new Date().toISOString().slice(0, 10);