clud-bug 0.5.6 → 0.5.7

package/README.md

@@ -164,20 +164,64 @@ If you want clud-bug to review fork PRs too, you have two options:
 1. **Maintainer re-pushes the branch** to your repo as a non-fork branch, and the review runs.
 2. **Switch the trigger to `pull_request_target`** (advanced) — this gives the workflow access to secrets but runs against the *base* ref, not the PR's code. To safely review the PR's actual code, follow [`anthropics/claude-code-action` security.md](https://github.com/anthropics/claude-code-action/blob/main/docs/security.md): check out the PR head into a **subdirectory** (not the workspace root) and pass it via `--add-dir`. Skipping this is a code-execution risk.
 
-clud-bug's generated workflow uses `pull_request` by default. If you understand the trade-offs, edit the trigger yourself.
+Concretely, the safe shape:
+
+```yaml
+on:
+  pull_request_target:
+    types: [opened, synchronize]
+
+jobs:
+  clud-bug-review:
+    steps:
+      - uses: actions/checkout@v6  # base ref — trusted
+      - uses: actions/checkout@v6  # PR head — UNTRUSTED, into a subdir
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          path: pr-head
+      - uses: anthropics/claude-code-action@v1
+        with:
+          claude_args: --add-dir pr-head
+          # ... rest of args
+```
+
+The key invariant: the base checkout (with secrets in scope) lives at the workspace root; the PR head (untrusted user code) only ever lives in a subdirectory the action explicitly opts into via `--add-dir`. Any deviation — checking out the PR head at the root, running `npm install` from the subdir, etc. — re-opens the code-execution risk.
+
+clud-bug's generated workflow uses `pull_request` (not `pull_request_target`) by default. If you understand the trade-offs and want to handle fork PRs, edit the trigger yourself using the shape above.
 
 ## 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.
+> **TL;DR:** if you see `App token exchange failed: Workflow validation failed (401)` on a PR that edits a clud-bug workflow file, that's **expected and protective** — not a bug in your PR. Read on.
+
+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: without it, a PR could neuter the reviewer or exfiltrate secrets via prompt injection in the workflow file itself.
+
+### What you'll see
+
+When you push a PR that touches `.github/workflows/clud-bug-review.yml` (or any other clud-bug workflow):
+
+- The `clud-bug-review` check fails with `App token exchange failed: 401 Unauthorized — Workflow validation failed. The workflow file must exist and have identical content to the version on the repository's default branch.`
+- You'll get a GitHub email titled something like **"[thrillmot/your-repo] Run failed: Clud Bug 🐛 Crawls Your Code — `<branch-name>`"** — same wording for every workflow failure, so it doesn't visually distinguish "this is the expected self-mod guard" from "real failure."
+
+### How to merge
+
+If the PR contains **only** workflow edits, this is the expected path:
+
+1. A maintainer reviews the diff directly (the bot can't).
+2. Merge via admin override (`gh pr merge --admin` or the "Merge without waiting for requirements" button) — the failing `clud-bug-review` check is the bot refusing to review *itself*, not a real defect.
+3. Subsequent PRs on the new workflow work normally — the validation gate compares against `main`, so once your edit is on `main`, the gate passes.
+
+If the PR contains workflow edits **mixed with other code changes**, split them. The bot can't review either half while the workflow edit is in the diff, so any real findings get masked.
+
+### The helper command
 
-To make this easier, `clud-bug edit-workflow` packages the workflow change into a clean PR for you:
+`clud-bug edit-workflow` packages the workflow change into a clean PR for you, refusing to run if your working tree has any non-workflow changes:
 
 ```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.
+This keeps the merge ceremony scoped to just the workflow edit.
 
 ## Verifying it works
 

package/bin/clud-bug.js

@@ -608,16 +608,28 @@ async function runUpdateCmd(_args) {
     return;
   }
 
-  if (result.changed.length === 0) {
+  const skipped = result.skipped ?? [];
+
+  if (result.changed.length === 0 && skipped.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.changed.length > 0) {
+    log(`  ✓ Updated ${result.changed.length} file${result.changed.length === 1 ? '' : 's'}:`);
+    for (const c of result.changed) {
+      const versionNote = c.from && c.to && c.from !== c.to ? `  (${c.label}, ${c.from} → ${c.to})` : `  (${c.label})`;
+      log(`     • ${rel(cwd, c.path)}${versionNote}`);
+    }
+  }
   if (result.unchanged.length > 0) {
     log(`  ${result.unchanged.length} file${result.unchanged.length === 1 ? ' was' : 's were'} already current.`);
   }
+  if (skipped.length > 0) {
+    log('');
+    log(`  ! Skipped ${skipped.length} markerless file${skipped.length === 1 ? '' : 's'} (treated as user-customized):`);
+    for (const s of skipped) log(`     • ${rel(cwd, s.path)}  — ${s.reason}`);
+  }
   log('');
   log('Commit + push to apply the refreshed kit on the next PR.');
 }

package/lib/update.js

@@ -8,14 +8,18 @@ import { applyToRepo as applyAgentDocs } from './agents-md.js';
 // Re-render the user's workflow + refresh baseline skills using the
 // templates / baseline shipped with the currently-installed clud-bug.
 //
-// Honors three protections:
+// Honors four protections:
 //   - Custom skills (anything in .claude/skills/ not in the manifest) are
 //     never modified.
 //   - Remote skills (from skills.sh, kind: 'remote' in manifest) are left
 //     alone unless { refreshRemote: true }.
-//   - The audit workflow is also re-rendered if it's installed.
+//   - The audit + self-update workflows are also refreshed if installed.
+//   - Markerless workflow files (no `# clud-bug-template-version:` header)
+//     are treated as user-customized and left alone — the user gets a
+//     printed warning + the documented "delete + clud-bug init" recovery
+//     path. Mirrors logmind v0.2.1's refresh-mode pattern.
 //
-// Returns a diff summary with file paths and a short reason per file.
+// Returns { changed, unchanged, skipped, ourVersion }.
 export async function runUpdate({
   cwd,
   templatesDir,
@@ -35,6 +39,7 @@ export async function runUpdate({
 
   const changed = [];
   const unchanged = [];
+  const skipped = [];
 
   // 1. Re-render review workflow with the latest template.
   const signals = await detect(cwd);
@@ -43,13 +48,20 @@ export async function runUpdate({
     PROJECT_DESCRIPTION: buildDescriptionLine(signals),
     LANGUAGE_HINTS: '',
   });
-  await maybeWrite(join(cwd, '.github/workflows/clud-bug-review.yml'), newReview, changed, unchanged, 'review workflow');
+  await maybeRefreshVersioned(join(cwd, '.github/workflows/clud-bug-review.yml'), newReview, changed, unchanged, skipped, 'review workflow');
 
   // 2. Re-render audit workflow if it's installed (init from v0.3+ ships it).
   const auditPath = join(cwd, '.github/workflows/clud-bug-audit.yml');
   if (await pathExists(auditPath)) {
     const newAudit = await readFile(join(templatesDir, 'audit.yml.tmpl'), 'utf8');
-    await maybeWrite(auditPath, newAudit, changed, unchanged, 'audit workflow');
+    await maybeRefreshVersioned(auditPath, newAudit, changed, unchanged, skipped, 'audit workflow');
+  }
+
+  // 2b. Re-render self-update workflow if installed (init from v0.4+ ships it).
+  const selfUpdatePath = join(cwd, '.github/workflows/clud-bug-self-update.yml');
+  if (await pathExists(selfUpdatePath)) {
+    const newSelfUpdate = await readFile(join(templatesDir, 'self-update.yml.tmpl'), 'utf8');
+    await maybeRefreshVersioned(selfUpdatePath, newSelfUpdate, changed, unchanged, skipped, 'self-update workflow');
   }
 
   // 3. Refresh baseline skills (always controlled by clud-bug).
@@ -88,7 +100,7 @@ export async function runUpdate({
   manifest.lastUpdateVersion = ourVersion;
   await writeManifest(skillsDir, manifest);
 
-  return { changed, unchanged, ourVersion };
+  return { changed, unchanged, skipped, ourVersion };
 }
 
 async function maybeWrite(path, contents, changed, unchanged, label) {
@@ -102,6 +114,61 @@ async function maybeWrite(path, contents, changed, unchanged, label) {
   changed.push({ path, label });
 }
 
+// Refresh a versioned template (one that carries `# clud-bug-template-version:`
+// on line 1). If the installed file lacks that marker, treat it as
+// user-customized and leave it alone — recovery path is delete + `clud-bug init`.
+// Mirrors logmind v0.2.1's refresh-mode contract.
+async function maybeRefreshVersioned(path, contents, changed, unchanged, skipped, label) {
+  const tmplVersion = extractTemplateVersion(contents);
+  if (!tmplVersion) {
+    // Defensive: every versioned template is supposed to carry a marker.
+    // Falling back to byte-compare write here would silently mass-overwrite
+    // every installed file (including marker-bearing ones) the moment a
+    // future template regressed — the inverse of the protection contract
+    // this function exists to enforce. Throw so the regression surfaces
+    // in CI instead.
+    throw new Error(`Template for ${label} has no # clud-bug-template-version marker — refusing to refresh (templates must declare a marker so refresh-mode can reason about ownership).`);
+  }
+  const prior = await readSafe(path);
+  if (prior === null) {
+    // First time writing here; nothing to preserve.
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, contents);
+    changed.push({ path, label });
+    return;
+  }
+  const priorVersion = extractTemplateVersion(prior);
+  if (priorVersion === null) {
+    // Markerless installed file = customized. Preserve and warn.
+    skipped.push({
+      path,
+      label,
+      reason: 'markerless (user-customized); delete the file + run `clud-bug init` to refresh',
+    });
+    return;
+  }
+  if (prior === contents) {
+    unchanged.push({ path, label });
+    return;
+  }
+  // Marker present (current or stale) AND content drifted: refresh.
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, contents);
+  changed.push({ path, label, from: priorVersion, to: tmplVersion });
+}
+
+// Extract the template-version marker. Templates put it on line 1, but
+// scan the first 5 lines so a leading blank or stray header doesn't hide it.
+// Anchoring near the top means a stray `# clud-bug-template-version:` lower
+// in the file (in a comment inside a heredoc, say) can't be mistaken for the
+// authoritative marker. Returns null if not present.
+function extractTemplateVersion(text) {
+  if (!text) return null;
+  const head = text.split('\n', 5).join('\n');
+  const m = head.match(/^# clud-bug-template-version:\s*(\S+)/m);
+  return m ? m[1] : null;
+}
+
 async function readSafe(path) {
   try { return await readFile(path, 'utf8'); } catch { return null; }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clud-bug",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "Claude PR review with project-aware skills. CLI installs a working GitHub Actions workflow and curates skills from skills.sh.",
   "homepage": "https://cludbug.dev",
   "bugs": "https://github.com/thrillmot/clud-bug/issues",

package/templates/audit.yml.tmpl

@@ -1,3 +1,4 @@
+# clud-bug-template-version: v1
 name: Clud Bug 🐛 Audit
 
 # A scheduled / on-demand walk through the whole habitat (or a recent slice).

package/templates/self-update.yml.tmpl

@@ -1,3 +1,4 @@
+# clud-bug-template-version: v1
 name: Clud Bug 🐛 Self-Update
 
 # Weekly check for a newer published clud-bug. If one exists, runs

package/templates/skills/baseline/clud-bug-collaboration.md

@@ -71,6 +71,55 @@ When you write a custom skill, follow the SKILL.md frontmatter format
 Generic advice gets ignored; rules with examples and quoted-line evidence
 move the bot's behavior.
 
+### Example: a good custom skill
+
+Don't write generic prose like "be careful with database code." That's
+not actionable. Instead, anchor to specific files + behaviors:
+
+````markdown
+---
+name: db-query-review
+description: How to review changes under lib/db/. Always flag missing parameterization, N+1 query patterns, and missing transaction boundaries on multi-statement writes.
+---
+
+# Reviewing lib/db/ changes
+
+When the diff touches `lib/db/queries.ts` or any file under `lib/db/`,
+apply these rules:
+
+## Always flag
+
+1. **SQL string interpolation** — anything that builds a query via `+`,
+   template literals, or `string.format` rather than parameterized
+   queries. Example to flag:
+
+   ```ts
+   // BAD — flag this
+   db.query(`SELECT * FROM users WHERE id = ${userId}`)
+   // GOOD — uses parameterization
+   db.query('SELECT * FROM users WHERE id = ?', [userId])
+   ```
+
+2. **N+1 patterns** — flag any `await` inside a `for`/`map` loop that
+   calls `db.query` or `db.queryOne`. The fix is usually a single
+   `WHERE id IN (...)` query or a join.
+
+3. **Multi-statement writes without `db.transaction`** — if a diff
+   adds two or more `db.query` calls that all write, demand a
+   transaction wrapper. Quote the lines.
+
+## Style of finding
+
+Cite the specific line. "This is a SQL injection risk" alone isn't
+enough — quote the unsafe interpolation directly and propose the
+parameterized alternative.
+````
+
+That's what "evidence-anchored" looks like: specific file paths, runnable
+code examples for both bad and good, and explicit instructions on what
+to quote in the finding. The bot loads this and uses it as concrete
+review criteria, not vague guidance.
+
 ## When you edit `.github/workflows/clud-bug-*.yml`
 
 `anthropics/claude-code-action` **refuses to run on PRs that modify its

package/templates/workflow-py.yml.tmpl

@@ -1,3 +1,4 @@
+# clud-bug-template-version: v1
 name: Clud Bug 🐛 Crawls Your Code
 
 on:

package/templates/workflow-ts.yml.tmpl

@@ -1,3 +1,4 @@
+# clud-bug-template-version: v1
 name: Clud Bug 🐛 Crawls Your Code
 
 on:

package/templates/workflow.yml.tmpl

@@ -1,3 +1,4 @@
+# clud-bug-template-version: v1
 name: Clud Bug 🐛 Crawls Your Code
 
 on: