clud-bug 0.2.0 → 0.4.1

package/README.md

@@ -1,11 +1,11 @@
 # Clud Bug 🐛
-### Crawling all over your code
+### A field guide to specimens crawling your code
 
-> **[cludbug.dev](https://cludbug.dev)** · A field guide.
+> **[cludbug.dev](https://cludbug.dev)** · live field journal.
 
-Claude PR review for any GitHub repo, with **project-aware skills** auto-discovered from [skills.sh](https://skills.sh) and a baseline of review-discipline skills bundled in.
+Clud Bug is a Claude PR-review naturalist for your GitHub repo. It pins **project-aware skills** auto-discovered from [skills.sh](https://skills.sh) and ships a baseline kit of review discipline so reviews stay focused on what matters: bugs, security, performance, and missing tests.
 
-One command to install. The first PR you open afterwards gets a real review comment back.
+One command to install. The first PR you open afterwards gets a real review comment back — typically within two minutes.
 
 ## Quickstart
 
@@ -24,14 +24,16 @@ Open a PR. A review comment should appear within ~2 minutes.
 
 ## What `clud-bug init` does
 
-1. **Detects** your stack (Node, Python, Go, Rust, Ruby — reads `package.json`, `pyproject.toml`, `go.mod`, etc.).
-2. **Queries [skills.sh](https://skills.sh)** for review skills relevant to your dependencies (e.g. a Next.js project gets Next.js review skills).
-3. **Installs three baseline skills** that enforce review discipline regardless of stack:
+The naturalist arrives at your repo, surveys the habitat, and assembles a field kit:
+
+1. **Surveys habitat.** Reads `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc., to learn what your stack is.
+2. **Consults [skills.sh](https://skills.sh).** Pulls review skills relevant to your dependencies (e.g. a Next.js project gets Next.js review specimens).
+3. **Pins three baseline specimens** that enforce review discipline regardless of stack:
    - `critical-issues-only` — flag bugs, security, perf only. Skip nits.
    - `evidence-based-review` — every claim must quote the line being criticized.
    - `respect-existing-conventions` — don't suggest fights with the codebase's patterns.
-4. **Writes** the chosen skills to `.claude/skills/<name>/SKILL.md` (Claude Code auto-loads them in the GitHub Action).
-5. **Generates** `.github/workflows/clud-bug-review.yml` with the project description filled in and the right permissions/tool allowlist for `gh pr comment` to actually work.
+4. **Writes** the chosen specimens to `.claude/skills/<name>/SKILL.md` (Claude Code auto-loads them in the GitHub Action).
+5. **Drafts the field kit** at `.github/workflows/clud-bug-review.yml` with your project description filled in and the right permissions/tool allowlist for `gh pr comment` to actually post.
 
 ## CLI options
 
@@ -44,6 +46,70 @@ npx clud-bug init [options]
   --help,-h       Show help.
 ```
 
+## Staying up to date
+
+`clud-bug init` ships a third workflow: `clud-bug-self-update.yml`. Once a week (Mondays 12:00 UTC), it checks npm for a newer `clud-bug` version. If one exists, it runs `clud-bug update` and opens a PR titled `🐛 Clud Bug self-update: vX.Y.Z → vA.B.C`. Custom and skills.sh-installed specimens are never touched — only baseline specimens and the workflow templates get refreshed.
+
+You can also run the update manually:
+
+```bash
+clud-bug update
+```
+
+To pin a specific version and stop receiving update PRs, add `pinVersion` to `.claude/skills/.clud-bug.json`:
+
+```json
+{ "pinVersion": "0.3.0", ... }
+```
+
+## Auditing the whole repo
+
+PR reviews catch issues entering. Audits catch issues that already crossed the line.
+
+```bash
+clud-bug audit                      # walk every tracked file
+clud-bug audit --changed-in 7d      # only files touched in the last 7 days
+clud-bug audit --since 2026-01-01   # only files touched since a date
+clud-bug audit --scope 'src/**/*.ts'  # narrow by glob (repeatable)
+```
+
+The CLI prepares an `audits/YYYY-MM-DD.md` stub. For findings, `clud-bug init` also installed `.github/workflows/clud-bug-audit.yml` — go to **Actions → Clud Bug 🐛 Audit → Run workflow**. Clud Bug walks the manifest, appends findings to the same file, opens a PR you can read, act on, then merge or close.
+
+The workflow ships with `workflow_dispatch` only (manual). The cron is in the file, commented — uncomment for weekly audits.
+
+## Strict mode (default since v0.4.0)
+
+Clud Bug runs in **strict mode by default** for new installs. The workflow check fails when Clud Bug flags a critical issue (bug, security, performance, missing test coverage) — green means clean, red means the bot found something to address. Add `clud-bug-review` to your branch protection's required status checks and merging is blocked until findings are addressed.
+
+`clud-bug init` writes `{ "strictMode": true }` to `.claude/skills/.clud-bug.json`. To opt out into advisory mode (the bot still reviews; the check stays green regardless of findings), set `strictMode: false`:
+
+```json
+{ "strictMode": false, ... }
+```
+
+The toggle takes effect on PRs opened *after* the new value lands on the base branch (the gate reads the manifest from the base ref so PRs can't disable strict on themselves).
+
+**Existing installs upgrading to v0.4.0:** the new default only fires on fresh installs (manifests that have never been touched by `init` or `update`). Existing repos — including v0.3.x advisory installs that never set `strictMode` — keep their prior behavior on re-init. To enable strict mode in an existing repo, add `"strictMode": true` to `.claude/skills/.clud-bug.json` manually.
+
+## Bot-authored PRs (Dependabot, Renovate, fork PRs)
+
+GitHub deliberately doesn't pass repository secrets to workflows triggered by bot-authored PRs (`dependabot[bot]`, `renovate[bot]`) or PRs from forks. The action can't authenticate against Anthropic, so Clud Bug can't review.
+
+Rather than failing red (wrong signal), the workflow detects this case, posts a one-line advisory comment to the PR explaining the skip, and exits 0. The check stays green; the comment makes the skip visible. Reviews are your responsibility on those PRs.
+
+To enable real reviews on Dependabot PRs, [add ANTHROPIC_API_KEY to Dependabot's secret scope](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot).
+
+## How skills shape reviews
+
+Skills aren't background reading material for the bot — they're rules with authority. The workflow prompt now requires Clud Bug to:
+
+1. **Cite the skill by name** when applying its guidance: e.g. `[evidence-based-review]: this claim isn't anchored to a line`.
+2. **End every review with a footer** listing which skills shaped the findings: `Skills referenced: [critical-issues-only, next-best-practices, my-team-rules]`.
+
+The footer is your audit trail. If a review's footer is `[none]`, either the bot found nothing relevant in your installed skills (and should explain why), or your skill set isn't covering the kinds of changes you actually ship — a signal to add or write new specimens.
+
+`clud-bug init` warns when it would install only baseline specimens. Pair with at least one project-aware skill from skills.sh, or your own — that's where the wedge over stock Claude review comes from.
+
 ## Managing skills
 
 After `init`, four commands let you evolve the skill set without re-running the whole setup:
@@ -92,6 +158,19 @@ If you want clud-bug to review fork PRs too, you have two options:
 
 clud-bug's generated workflow uses `pull_request` by default. If you understand the trade-offs, edit the trigger yourself.
 
+## When you edit the workflow
+
+clud-bug uses [`anthropics/claude-code-action`](https://github.com/anthropics/claude-code-action), which **refuses to run when the PR being reviewed modifies the action's own workflow file**. That's a security guard against PRs that try to neuter the reviewer or exfiltrate secrets via prompt injection. If you edit `.github/workflows/clud-bug-review.yml` (or any clud-bug workflow), expect this check to fail with a 401 — `App token exchange failed: Workflow validation failed`. That's the documented behavior, not a bug. Merge the workflow change in isolation, and subsequent PRs work normally.
+
+To make this easier, `clud-bug edit-workflow` packages the workflow change into a clean PR for you:
+
+```bash
+# Edit .github/workflows/clud-bug-*.yml as you like, then:
+clud-bug edit-workflow
+```
+
+The command refuses to run if your working tree has any non-workflow changes — keeping the PR scoped to just the workflow edit.
+
 ## Verifying it works
 
 After install:

package/bin/clud-bug.js

@@ -12,40 +12,61 @@ import {
   SkillsClient, rankAndCap, writeSkills, writeSkill, loadBaseline,
   readManifest, writeManifest, removeSkill, listInstalled, diffManifest,
 } from '../lib/skills.js';
+import { computeAuditFileSet, renderAuditHeader } from '../lib/audit.js';
+import { runUpdate } from '../lib/update.js';
+import { getPendingWorkflowEdits, makeBranchName, git as gitCmd } from '../lib/edit-workflow.js';
 
 const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const TEMPLATES = join(PKG_ROOT, 'templates');
 const BASELINE_DIR = join(TEMPLATES, 'skills', 'baseline');
 
 function parseArgs(argv) {
-  const args = { _: [], offline: false, acceptAll: false, commit: false, help: false, version: false };
-  for (const a of argv) {
+  const args = {
+    _: [], offline: false, acceptAll: false, commit: false, help: false, version: false,
+    since: null, changedIn: null, scopes: [], out: null,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
     if (a === '--offline') args.offline = true;
     else if (a === '--accept-all' || a === '-y') args.acceptAll = true;
     else if (a === '--commit') args.commit = true;
     else if (a === '--help' || a === '-h') args.help = true;
     else if (a === '--version' || a === '-v') args.version = true;
+    else if (a === '--since') args.since = argv[++i];
+    else if (a === '--changed-in') args.changedIn = argv[++i];
+    else if (a === '--scope') args.scopes.push(argv[++i]);
+    else if (a === '--out') args.out = argv[++i];
     else args._.push(a);
   }
   return args;
 }
 
-const HELP = `clud-bug — Claude PR review with project-aware skills
+const HELP = `clud-bug 🐛 — a field guide to specimens crawling your code
 
 Usage:
   npx clud-bug <command> [options]
 
 Commands:
-  init                  First-time setup: detect repo, install skills, write workflow.
-  list                  Show currently installed skills (baseline / remote / custom).
-  add <source/name>     Install one skill from skills.sh (e.g. vercel-labs/skills/next-best-practices).
-  remove <slug>         Remove an installed skill (refuses if it's a custom skill).
-  refresh               Re-query skills.sh and diff against installed; prompt to update.
+  init                  Open field season: survey the repo, pin baseline specimens, write the workflows.
+  list                  Show your collection (baseline / from skills.sh / custom).
+  add <source/name>     Pin one new specimen from skills.sh (e.g. vercel-labs/skills/next-best-practices).
+  remove <slug>         Unpin a clud-bug-managed specimen (refuses to touch your custom ones).
+  refresh               Re-survey, diff against your collection, prompt to update.
+  audit                 Walk the whole habitat (or a recent slice) and prepare a report stub.
+                        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.
+  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).
 
 Options:
-  --offline             Skip skills.sh; only use bundled baseline skills (init/refresh).
-  --accept-all,-y       Accept recommendations without prompting.
-  --commit              git add + commit the generated files when done (init only).
+  --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).
+  --since <date>        Audit only files changed in commits after <date> (git date string).
+  --changed-in <dur>    Audit only files changed in the past <dur>: 7d, 2w, 1mo, 1y. (audit only)
+  --scope <glob>        Limit audit to files matching <glob>; repeatable. (audit only)
+  --out <path>          Where to write the audit stub. Default: audits/YYYY-MM-DD.md
   --help,-h             Show this help.
   --version,-v          Show version.
 `;
@@ -67,6 +88,9 @@ async function main() {
     case 'add':     return runAdd(args);
     case 'remove':  return runRemove(args);
     case 'refresh': return runRefresh(args);
+    case 'audit':   return runAudit(args);
+    case 'update':  return runUpdateCmd(args);
+    case 'edit-workflow': return runEditWorkflow(args);
     default:
       process.stderr.write(`Unknown command: ${cmd || '(none)'}\n\n${HELP}`);
       process.exit(2);
@@ -75,15 +99,15 @@ async function main() {
 
 async function runInit(args) {
   const cwd = process.cwd();
-  log(`🐛 clud-bug init in ${cwd}`);
+  log(`🐛 Field season opens in ${cwd}.`);
 
-  log('  detecting repo signals...');
+  log('  surveying habitat...');
   const signals = await detect(cwd);
   log(`    primary language: ${signals.primaryLanguage || '(unknown)'}`);
   log(`    search terms:     ${signals.searchTerms.join(', ') || '(none)'}`);
 
   const baseline = await loadBaseline(BASELINE_DIR);
-  log(`    baseline skills:  ${baseline.length}`);
+  log(`    baseline kit:     ${baseline.length} specimens`);
 
   let curated = [];
   let searched = [];
@@ -92,7 +116,7 @@ async function runInit(args) {
   } else {
     const client = new SkillsClient();
     try {
-      log('  querying skills.sh...');
+      log('  consulting skills.sh...');
       [curated, searched] = await Promise.all([
         client.curated().catch(err => { warn(`curated query failed: ${err.message}`); return []; }),
         client.search(signals.searchTerms).catch(err => { warn(`search failed: ${err.message}`); return []; }),
@@ -105,7 +129,7 @@ async function runInit(args) {
 
   const recommended = rankAndCap(curated, searched, baseline);
   log('');
-  log('Recommended skills:');
+  log('Specimens to pin:');
   for (const s of recommended) {
     const tag = s.kind === 'baseline' ? '[baseline]' : `[${s.source}]`;
     log(`  • ${s.name} ${tag}`);
@@ -118,12 +142,20 @@ async function runInit(args) {
     chosen = await promptForSkills(recommended);
   }
 
-  log('  installing skills into .claude/skills/...');
+  log('  pinning specimens to .claude/skills/...');
   const client = new SkillsClient();
   const written = await writeSkills(join(cwd, '.claude', 'skills'), chosen, client);
-  log(`    wrote ${written.length} skills`);
+  log(`    pinned ${written.length} specimens`);
+
+  // Empty-skills warning: clud-bug shines when paired with project-specific
+  // skills. Reviews that load only the three baselines are functional but
+  // generic; flag this so users notice.
+  const remoteCount = written.filter((w) => w.kind !== 'baseline').length;
+  if (remoteCount === 0) {
+    warn('Only baseline specimens pinned. Add project-specific skills via `clud-bug add vercel-labs/skills/<name>` or drop your own `.claude/skills/<name>/SKILL.md`.');
+  }
 
-  log('  rendering workflow...');
+  log('  drafting field kit...');
   const tmplName = pickTemplate(signals.languages);
   const tmplPath = join(TEMPLATES, tmplName);
   const workflow = await renderFile(tmplPath, {
@@ -135,24 +167,61 @@ async function runInit(args) {
   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.
+  const auditTmpl = await readFile(join(TEMPLATES, 'audit.yml.tmpl'), 'utf8');
+  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.
+  const selfUpdateTmpl = await readFile(join(TEMPLATES, 'self-update.yml.tmpl'), 'utf8');
+  const selfUpdatePath = join(cwd, '.github', 'workflows', 'clud-bug-self-update.yml');
+  await writeFile(selfUpdatePath, selfUpdateTmpl);
+  log(`    wrote ${rel(cwd, selfUpdatePath)}`);
+
+  // 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
+  // was never written and so == undefined) keep their advisory behavior
+  // because lastUpdate IS set; the strictMode default only fires on truly
+  // fresh inits. Users opt out by setting strictMode: false.
+  const skillsDirPath = join(cwd, '.claude', 'skills');
+  const manifest = await readManifest(skillsDirPath);
+  const isFreshInstall = manifest.lastUpdate === undefined;
+  manifest.lastUpdateVersion = await readPkgVersion();
+  manifest.lastUpdate = new Date().toISOString();
+  if (isFreshInstall && manifest.strictMode === undefined) {
+    manifest.strictMode = true;
+  }
+  await writeManifest(skillsDirPath, manifest);
+
   if (args.commit) {
     log('  committing...');
-    spawnSync('git', ['add', '.claude', '.github/workflows/clud-bug-review.yml'], { cwd, stdio: 'inherit' });
-    spawnSync('git', ['commit', '-m', 'Add clud-bug Claude PR review'], { cwd, stdio: 'inherit' });
+    spawnSync('git', ['add', '.claude', '.github/workflows/clud-bug-review.yml', '.github/workflows/clud-bug-audit.yml', '.github/workflows/clud-bug-self-update.yml'], { cwd, stdio: 'inherit' });
+    spawnSync('git', ['commit', '-m', 'Add clud-bug 🐛 — a field guide to specimens crawling your code'], { cwd, stdio: 'inherit' });
   }
 
   log('');
-  log('Done. Next steps:');
+  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-review.yml && git commit && git push');
-    log('  3. Open a PR — Clud Bug should comment within ~2 min.');
+    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 — Clud Bug should comment within ~2 min.');
+    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\'re auto-loaded.');
+  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.');
+  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.');
+  log('  • Opt out by setting "strictMode": false in .claude/skills/.clud-bug.json.');
 }
 
 async function promptForSkills(recommended) {
@@ -182,13 +251,13 @@ async function runList(_args) {
   const groups = await listInstalled(skillsDir);
   const total = groups.baseline.length + groups.remote.length + groups.custom.length;
   if (total === 0) {
-    log('No skills installed yet. Run `clud-bug init` to get started.');
+    log('Empty collection. Run `clud-bug init` to open field season.');
     return;
   }
-  log(`🐛 ${total} skill${total === 1 ? '' : 's'} in .claude/skills/`);
+  log(`🐛 ${total} specimen${total === 1 ? '' : 's'} pinned in .claude/skills/`);
   if (groups.baseline.length) {
     log('');
-    log('Baseline (always installed):');
+    log('Baseline (always pinned):');
     for (const s of groups.baseline) log(`  • ${s.slug}`);
   }
   if (groups.remote.length) {
@@ -198,7 +267,7 @@ async function runList(_args) {
   }
   if (groups.custom.length) {
     log('');
-    log('Custom (yours, never auto-modified):');
+    log('Custom (your own — never auto-modified):');
     for (const s of groups.custom) {
       log(`  • ${s.slug}${s.description ? `  — ${s.description}` : ''}`);
     }
@@ -220,9 +289,12 @@ async function runAdd(args) {
   const client = new SkillsClient();
   const entry = await writeSkill(skillsDir, { source, name, kind: 'remote' }, client);
   const manifest = await readManifest(skillsDir);
-  const merged = { version: 1, installed: [...manifest.installed.filter(e => e.slug !== entry.slug), entry] };
-  await writeManifest(skillsDir, merged);
-  log(`  ✓ installed ${entry.slug} → .claude/skills/${entry.slug}/SKILL.md`);
+  // Mutate in place so caller-set fields on the manifest (pinVersion,
+  // lastUpdate, lastUpdateVersion) survive the add. Building a fresh
+  // {version, installed} object would silently drop them.
+  manifest.installed = [...manifest.installed.filter((e) => e.slug !== entry.slug), entry];
+  await writeManifest(skillsDir, manifest);
+  log(`  ✓ pinned ${entry.slug} → .claude/skills/${entry.slug}/SKILL.md`);
   log('  Commit + push to apply on the next PR.');
 }
 
@@ -234,7 +306,7 @@ async function runRemove(args) {
   }
   const skillsDir = join(process.cwd(), '.claude', 'skills');
   const entry = await removeSkill(skillsDir, slug);
-  log(`  ✓ removed ${entry.slug}${entry.kind === 'baseline' ? ' (baseline — will return on next init)' : ''}`);
+  log(`  ✓ unpinned ${entry.slug}${entry.kind === 'baseline' ? ' (baseline — returns on next init)' : ''}`);
 }
 
 async function runRefresh(args) {
@@ -242,11 +314,11 @@ async function runRefresh(args) {
   const skillsDir = join(cwd, '.claude', 'skills');
   const manifest = await readManifest(skillsDir);
   if (manifest.installed.length === 0) {
-    log('No clud-bug-managed skills found. Run `clud-bug init` first.');
+    log('No clud-bug-managed specimens found. Run `clud-bug init` first.');
     return;
   }
 
-  log('  detecting repo signals...');
+  log('  re-surveying habitat...');
   const signals = await detect(cwd);
   log(`    primary language: ${signals.primaryLanguage || '(unknown)'}`);
   log(`    search terms:     ${signals.searchTerms.join(', ') || '(none)'}`);
@@ -286,7 +358,7 @@ async function runRefresh(args) {
 
   if (diff.add.length === 0 && diff.remove.length === 0) {
     log('');
-    log('Nothing to update. Skills are in sync with skills.sh recommendations.');
+    log('Collection in sync with skills.sh — nothing to update.');
     return;
   }
 
@@ -307,7 +379,134 @@ async function runRefresh(args) {
   const client = new SkillsClient();
   if (diff.add.length) await writeSkills(skillsDir, diff.add, client);
   for (const entry of diff.remove) await removeSkill(skillsDir, entry.slug);
-  log('  ✓ skills updated. Commit + push to apply on the next PR.');
+  log('  ✓ collection updated. Commit + push to apply on the next PR.');
+}
+
+async function runEditWorkflow(_args) {
+  const cwd = process.cwd();
+
+  // Validate: must have pending changes, all scoped to clud-bug workflow files.
+  let pending;
+  try {
+    pending = getPendingWorkflowEdits(cwd);
+  } catch (err) {
+    process.stderr.write(`clud-bug edit-workflow: ${err.message}\n`);
+    process.exit(2);
+  }
+
+  if (pending.files.length === 0) {
+    log('Nothing to commit. Edit your .github/workflows/clud-bug-*.yml file(s) first, then re-run.');
+    return;
+  }
+  if (!pending.allWorkflow) {
+    process.stderr.write(`clud-bug edit-workflow: working tree contains non-workflow changes:\n`);
+    for (const f of pending.nonWorkflow) process.stderr.write(`  ${f}\n`);
+    process.stderr.write(`\nThis command is for isolated workflow-only PRs. Stash or commit the\nnon-workflow changes elsewhere first, then re-run.\n`);
+    process.exit(2);
+  }
+
+  log('🐛 Preparing an isolated PR for your workflow edit.');
+  const branch = makeBranchName();
+  log(`  branch: ${branch} (rooted at origin/main)`);
+  for (const f of pending.files) log(`    • ${f}`);
+
+  // Stash the pending workflow changes, branch from origin/main explicitly
+  // (NOT from HEAD — if the user is on a feature branch with unrelated
+  // commits, those would otherwise leak into the "isolated" PR), then
+  // restore the changes onto the new branch and commit.
+  gitCmd(cwd, ['stash', 'push', '--include-untracked', '-m', 'clud-bug edit-workflow']);
+  try {
+    gitCmd(cwd, ['fetch', 'origin', 'main', '--depth=1']);
+    gitCmd(cwd, ['checkout', '-b', branch, 'origin/main']);
+  } catch (err) {
+    // Restore the user's stash before bubbling up.
+    gitCmd(cwd, ['stash', 'pop'], { allowFail: true });
+    throw err;
+  }
+  const popped = gitCmd(cwd, ['stash', 'pop'], { allowFail: true });
+  if (!popped.ok) {
+    process.stderr.write(`clud-bug edit-workflow: stash pop conflicted on origin/main — your edits are still in 'git stash'. Resolve manually:\n  git stash pop\n`);
+    process.exit(1);
+  }
+  gitCmd(cwd, ['add', ...pending.files]);
+  gitCmd(cwd, ['commit', '-m', 'Edit clud-bug workflow']);
+  gitCmd(cwd, ['push', '-u', 'origin', branch]);
+
+  log('');
+  log('Done. Open the PR:');
+  log(`  gh pr create --title "Edit clud-bug workflow" --body "Workflow tweak. The clud-bug-review check on this PR will fail with a 401 (Anthropic's self-protection against PRs that modify the reviewer's own workflow); merge once and subsequent PRs work normally."`);
+}
+
+async function runUpdateCmd(_args) {
+  const cwd = process.cwd();
+  const ourVersion = await readPkgVersion();
+  log(`🐛 Refreshing the field kit (${ourVersion}).`);
+
+  const result = await runUpdate({
+    cwd,
+    templatesDir: TEMPLATES,
+    baselineDir: BASELINE_DIR,
+    ourVersion,
+  });
+
+  if (result.missing === 'init') {
+    log('  No clud-bug installation detected. Run `clud-bug init` first.');
+    return;
+  }
+
+  if (result.changed.length === 0) {
+    log('  Already current. Nothing to update.');
+    return;
+  }
+
+  log(`  ✓ Updated ${result.changed.length} file${result.changed.length === 1 ? '' : 's'}:`);
+  for (const c of result.changed) log(`     • ${rel(cwd, c.path)}  (${c.label})`);
+  if (result.unchanged.length > 0) {
+    log(`  ${result.unchanged.length} file${result.unchanged.length === 1 ? ' was' : 's were'} already current.`);
+  }
+  log('');
+  log('Commit + push to apply the refreshed kit on the next PR.');
+}
+
+async function runAudit(args) {
+  const cwd = process.cwd();
+  const date = new Date().toISOString().slice(0, 10);
+
+  let scopeLabel;
+  if (args.since) scopeLabel = `commits since ${args.since}`;
+  else if (args.changedIn) scopeLabel = `files changed in the past ${args.changedIn}`;
+  else if (args.scopes.length) scopeLabel = `glob ${args.scopes.join(', ')}`;
+  else scopeLabel = 'all tracked files';
+
+  log(`🐛 Audit walk in ${cwd}.`);
+  log(`  scope: ${scopeLabel}`);
+
+  let files;
+  try {
+    files = computeAuditFileSet({
+      cwd,
+      since: args.since,
+      changedIn: args.changedIn,
+      scopes: args.scopes,
+    });
+  } catch (err) {
+    process.stderr.write(`clud-bug audit: ${err.message}\n`);
+    process.exit(2);
+  }
+  log(`  surveyed: ${files.length} file${files.length === 1 ? '' : 's'}`);
+
+  if (files.length === 0) {
+    log('  Nothing in scope. Try widening --scope or --changed-in.');
+    return;
+  }
+
+  const outPath = args.out || join(cwd, 'audits', `${date}.md`);
+  await mkdir(dirname(outPath), { recursive: true });
+  await writeFile(outPath, renderAuditHeader({ date, scopeLabel, files }));
+  log(`  ✓ wrote stub: ${rel(cwd, outPath)}`);
+  log('');
+  log('Stub is empty findings — populated by the GitHub Action.');
+  log('Run locally without the workflow if you want — Clud Bug review needs the action runner + ANTHROPIC_API_KEY.');
 }
 
 function rel(from, to) {

package/lib/audit.js

@@ -0,0 +1,111 @@
+import { spawnSync } from 'node:child_process';
+
+// Convert a duration like "7d", "2w", "1mo", "3mo", "1y" to a git --since arg.
+// Returns null if the input is empty/undefined; throws on malformed input.
+export function durationToGitSince(input) {
+  if (!input) return null;
+  const m = String(input).trim().match(/^(\d+)\s*(d|w|mo|m|y)$/i);
+  if (!m) {
+    throw new Error(`Unrecognized duration "${input}". Examples: 7d, 2w, 1mo, 1y.`);
+  }
+  const n = Number(m[1]);
+  const unit = m[2].toLowerCase();
+  const map = { d: 'day', w: 'week', mo: 'month', m: 'month', y: 'year' };
+  return `${n} ${map[unit]}${n === 1 ? '' : 's'} ago`;
+}
+
+// Run a git command, return stdout lines split by \n. Throws on non-zero exit
+// unless { allowFail: true }, in which case returns [].
+export function gitLines(args, opts = {}) {
+  const r = spawnSync('git', args, { encoding: 'utf8', cwd: opts.cwd || process.cwd() });
+  if (r.status !== 0) {
+    if (opts.allowFail) return [];
+    throw new Error(`git ${args.join(' ')} failed (${r.status}): ${r.stderr.trim()}`);
+  }
+  return r.stdout.split('\n').filter(Boolean);
+}
+
+// Returns the file set the audit should consider, in repo-relative paths.
+// Filters: optional --since (git date), optional --changed-in (duration string),
+// optional --scope globs (one or more, repeatable).
+export function computeAuditFileSet({ since, changedIn, scopes = [], cwd } = {}) {
+  const sinceArg = since || (changedIn ? durationToGitSince(changedIn) : null);
+
+  let files;
+  if (sinceArg) {
+    // Files touched in any commit within the window.
+    files = [...new Set(gitLines(['log', `--since=${sinceArg}`, '--name-only', '--pretty=format:'], { cwd }))];
+    // --diff-filter at the log level only excludes the delete commit; a file
+    // that was modified (and emitted by --name-only) and *later* deleted will
+    // still appear here. Intersect with the current tracked-file set so the
+    // manifest only contains paths we can actually read.
+    const tracked = new Set(gitLines(['ls-files'], { cwd }));
+    files = files.filter((f) => tracked.has(f));
+  } else {
+    files = gitLines(['ls-files'], { cwd });
+  }
+
+  if (scopes.length) {
+    const matchers = scopes.map(globToRegex);
+    files = files.filter((f) => matchers.some((rx) => rx.test(f)));
+  }
+
+  // Skip vendor / build artifacts that bloat audits without adding signal.
+  const skip = /(^|\/)(node_modules|dist|build|out|\.next|\.vercel|coverage|target|__pycache__)\//;
+  return files.filter((f) => !skip.test(f)).sort();
+}
+
+// Minimal glob → RegExp. Supports **, *, ?. Anchors at both ends so that
+// 'src/**/*.ts' matches 'src/lib/foo.ts' but not 'app/src/lib/foo.ts'.
+function globToRegex(glob) {
+  let rx = '';
+  let i = 0;
+  while (i < glob.length) {
+    const ch = glob[i];
+    if (ch === '*' && glob[i + 1] === '*') {
+      // ** = any depth (including zero) of path segments
+      rx += '.*';
+      i += 2;
+      // consume an optional trailing slash so 'src/**/*.ts' works cleanly
+      if (glob[i] === '/') i++;
+    } else if (ch === '*') {
+      rx += '[^/]*';
+      i++;
+    } else if (ch === '?') {
+      rx += '[^/]';
+      i++;
+    } else if (/[.+^$|()\[\]{}\\]/.test(ch)) {
+      rx += '\\' + ch;
+      i++;
+    } else {
+      rx += ch;
+      i++;
+    }
+  }
+  return new RegExp(`^${rx}$`);
+}
+
+// Render the audit report's initial markdown body. The Action's Claude run
+// will append findings under a "## Findings" section after this header.
+export function renderAuditHeader({ date, scopeLabel, files }) {
+  const head = `# 🐛 Clud Bug audit — ${date}
+
+A scheduled walk through the habitat. Scope: ${scopeLabel}.
+Files surveyed: **${files.length}**.
+
+<details>
+<summary>File manifest (${files.length})</summary>
+
+\`\`\`
+${files.join('\n')}
+\`\`\`
+
+</details>
+
+---
+
+## Findings
+
+`;
+  return head;
+}