clud-bug 0.2.0 → 0.4.1

package/lib/edit-workflow.js

@@ -0,0 +1,47 @@
+import { spawnSync } from 'node:child_process';
+
+// Validates that the working tree's pending changes are scoped to
+// .github/workflows/clud-bug-*.yml. If yes, creates a branch, commits,
+// pushes, and prints the gh command for opening a PR. Mixed changes are
+// refused — the whole point is to keep workflow edits in an isolated PR
+// so claude-code-action's workflow-self-mod guard doesn't bundle them
+// with other reviewable work.
+
+export function getPendingWorkflowEdits(cwd = process.cwd()) {
+  // --untracked-files=all so new files in new directories are reported as
+  // individual paths instead of being collapsed to the parent dir (default
+  // 'normal' mode would emit '.github/' for a brand-new clud-bug-review.yml).
+  const r = spawnSync('git', ['status', '--porcelain', '--untracked-files=all'], { cwd, encoding: 'utf8' });
+  if (r.status !== 0) {
+    throw new Error(`git status failed: ${r.stderr.trim()}`);
+  }
+  const lines = r.stdout.split('\n').filter(Boolean);
+  if (lines.length === 0) return { allWorkflow: true, files: [], nonWorkflow: [] };
+
+  const files = [];
+  const nonWorkflow = [];
+  for (const line of lines) {
+    // porcelain format: XY <space> <path> ; rename: XY old -> new
+    const path = line.slice(3).split(' -> ').pop().trim();
+    files.push(path);
+    if (!isWorkflowFile(path)) nonWorkflow.push(path);
+  }
+  return { allWorkflow: nonWorkflow.length === 0, files, nonWorkflow };
+}
+
+export function isWorkflowFile(path) {
+  return /^\.github\/workflows\/clud-bug-.*\.ya?ml$/.test(path);
+}
+
+export function makeBranchName(date = new Date()) {
+  const stamp = date.toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  return `clud-bug/edit-workflow-${stamp}`;
+}
+
+export function git(cwd, args, opts = {}) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  if (r.status !== 0 && !opts.allowFail) {
+    throw new Error(`git ${args.join(' ')} failed (${r.status}): ${r.stderr.trim()}`);
+  }
+  return { ok: r.status === 0, stdout: r.stdout.trim(), stderr: r.stderr.trim() };
+}

package/lib/skills.js

@@ -133,6 +133,7 @@ export async function readManifest(targetDir) {
     const text = await readFile(join(targetDir, MANIFEST_FILE), 'utf8');
     const data = JSON.parse(text);
     return {
+      ...data,
       version: data.version || MANIFEST_VERSION,
       installed: Array.isArray(data.installed) ? data.installed : [],
     };
@@ -143,7 +144,10 @@ export async function readManifest(targetDir) {
 
 export async function writeManifest(targetDir, manifest) {
   await mkdir(targetDir, { recursive: true });
+  // Preserve any additional fields callers want to stamp (e.g. lastUpdate,
+  // lastUpdateVersion, pinVersion). Only `version` and `installed` are normalized.
   const out = {
+    ...manifest,
     version: manifest.version || MANIFEST_VERSION,
     installed: manifest.installed || [],
   };
@@ -158,7 +162,10 @@ export function mergeManifest(existing, newEntries) {
   for (const entry of newEntries) {
     byKey.set(entryKey(entry), entry);
   }
-  return { version: MANIFEST_VERSION, installed: [...byKey.values()] };
+  // Spread `existing` so caller-set fields (pinVersion, lastUpdate,
+  // lastUpdateVersion, etc.) survive merges performed by writeSkills /
+  // refresh / add. Only `installed` is rebuilt; everything else carries.
+  return { ...existing, version: MANIFEST_VERSION, installed: [...byKey.values()] };
 }
 
 function entryKey(entry) {

package/lib/update.js

@@ -0,0 +1,98 @@
+import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { renderFile, pickTemplate } from './render.js';
+import { detect, buildDescriptionLine } from './detect.js';
+import { loadBaseline, readManifest, writeManifest } from './skills.js';
+
+// Re-render the user's workflow + refresh baseline skills using the
+// templates / baseline shipped with the currently-installed clud-bug.
+//
+// Honors three 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.
+//
+// Returns a diff summary with file paths and a short reason per file.
+export async function runUpdate({
+  cwd,
+  templatesDir,
+  baselineDir,
+  ourVersion,
+  refreshRemote = false,
+} = {}) {
+  if (!cwd || !templatesDir || !baselineDir || !ourVersion) {
+    throw new Error('runUpdate requires cwd, templatesDir, baselineDir, ourVersion');
+  }
+  const skillsDir = join(cwd, '.claude', 'skills');
+  const manifest = await readManifest(skillsDir);
+  if (manifest.installed.length === 0 && !(await pathExists(join(cwd, '.github/workflows/clud-bug-review.yml')))) {
+    return { changed: [], unchanged: [], missing: 'init' };
+  }
+
+  const changed = [];
+  const unchanged = [];
+
+  // 1. Re-render review workflow with the latest template.
+  const signals = await detect(cwd);
+  const tmplName = pickTemplate(signals.languages);
+  const newReview = await renderFile(join(templatesDir, tmplName), {
+    PROJECT_DESCRIPTION: buildDescriptionLine(signals),
+    LANGUAGE_HINTS: '',
+  });
+  await maybeWrite(join(cwd, '.github/workflows/clud-bug-review.yml'), newReview, changed, unchanged, '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');
+  }
+
+  // 3. Refresh baseline skills (always controlled by clud-bug).
+  const baseline = await loadBaseline(baselineDir);
+  for (const skill of baseline) {
+    const skillPath = join(skillsDir, sanitize(skill.name), 'SKILL.md');
+    await maybeWrite(skillPath, skill.content, changed, unchanged, `baseline ${skill.name}`);
+  }
+
+  // 4. Optionally refresh remote skills (off by default).
+  // Custom skills are never touched.
+  // (Remote refresh is intentionally minimal here — `clud-bug refresh`
+  // already covers add/remove diffs against skills.sh.)
+  if (refreshRemote) {
+    // Placeholder for parity with the flag; full logic remains in
+    // `clud-bug refresh`. We just emit an advisory.
+  }
+
+  // 5. Stamp the manifest with the version that ran the update.
+  manifest.lastUpdate = new Date().toISOString();
+  manifest.lastUpdateVersion = ourVersion;
+  await writeManifest(skillsDir, manifest);
+
+  return { changed, unchanged, ourVersion };
+}
+
+async function maybeWrite(path, contents, changed, unchanged, label) {
+  const prior = await readSafe(path);
+  if (prior === contents) {
+    unchanged.push({ path, label });
+    return;
+  }
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, contents);
+  changed.push({ path, label });
+}
+
+async function readSafe(path) {
+  try { return await readFile(path, 'utf8'); } catch { return null; }
+}
+
+async function pathExists(path) {
+  try { await stat(path); return true; } catch { return false; }
+}
+
+function sanitize(name) {
+  return name.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clud-bug",
-  "version": "0.2.0",
+  "version": "0.4.1",
   "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",
@@ -20,9 +20,7 @@
     "ai",
     "skills"
   ],
-  "bin": {
-    "clud-bug": "./bin/clud-bug.js"
-  },
+  "bin": "bin/clud-bug.js",
   "files": [
     "bin",
     "lib",

package/templates/audit.yml.tmpl

@@ -0,0 +1,134 @@
+name: Clud Bug 🐛 Audit
+
+# A scheduled / on-demand walk through the whole habitat (or a recent slice).
+# Output lands as a PR titled "🐛 Clud Bug audit — YYYY-MM-DD" containing a
+# single audits/<date>.md file with findings.
+#
+# Triggers:
+#   workflow_dispatch — manual button in the Actions tab. Default.
+#   schedule (commented) — uncomment for weekly Mondays 09:00 UTC.
+
+on:
+  workflow_dispatch:
+    inputs:
+      changed_in:
+        description: "Audit files changed in (e.g. 7d, 2w, 1mo). Blank = full repo."
+        required: false
+        default: ""
+      scope:
+        description: "Glob to limit scope (e.g. src/**/*.ts). Blank = no scope filter."
+        required: false
+        default: ""
+  # Uncomment for a weekly Monday 09:00 UTC audit:
+  # schedule:
+  #   - cron: '0 9 * * 1'
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0   # full history needed for git --since
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '20'
+
+      # Audit runs on workflow_dispatch / schedule — no PR context, so the
+      # fork-PR carve-out doesn't apply. Just fail loud if the secret is missing.
+      - name: Guard — require ANTHROPIC_API_KEY
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          if [ -z "$ANTHROPIC_API_KEY" ]; then
+            echo "::error title=Clud Bug 🐛::ANTHROPIC_API_KEY secret is not set."
+            echo "::error::Set it: Settings → Secrets and variables → Actions → New repository secret."
+            exit 1
+          fi
+
+      - name: Compute audit scope and create branch
+        id: prep
+        env:
+          CHANGED_IN: ${{ inputs.changed_in }}
+          SCOPE: ${{ inputs.scope }}
+        run: |
+          DATE=$(date -u +%Y-%m-%d)
+          # Add a run-number suffix so same-day re-runs don't collide on the
+          # remote branch (push would otherwise be rejected as non-fast-forward).
+          BRANCH="clud-bug/audit-${DATE}-${{ github.run_number }}"
+          echo "branch=$BRANCH" >> "$GITHUB_OUTPUT"
+          echo "date=$DATE" >> "$GITHUB_OUTPUT"
+
+          # Use github-actions[bot]'s real identity (clud-bug isn't a registered
+          # GitHub App, so its name wouldn't resolve to a recognizable bot).
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$BRANCH"
+
+          ARGS=()
+          [ -n "$CHANGED_IN" ] && ARGS+=("--changed-in" "$CHANGED_IN")
+          [ -n "$SCOPE" ]      && ARGS+=("--scope" "$SCOPE")
+
+          npx -y clud-bug@latest audit "${ARGS[@]}"
+
+          if [ ! -f "audits/$DATE.md" ]; then
+            echo "::warning::clud-bug audit produced no stub file — nothing in scope."
+            echo "stub_written=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          git add audits/
+          git commit -m "🐛 Clud Bug audit — $DATE (stub)"
+          git push -u origin "$BRANCH"
+          echo "stub_written=true" >> "$GITHUB_OUTPUT"
+
+      - uses: anthropics/claude-code-action@v1
+        if: steps.prep.outputs.stub_written == 'true'
+        env:
+          AUDIT_DATE: ${{ steps.prep.outputs.date }}
+          AUDIT_BRANCH: ${{ steps.prep.outputs.branch }}
+          FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          track_progress: true
+          claude_args: |
+            --allowedTools "Bash(gh pr create:*),Bash(gh pr edit:*),Bash(gh pr view:*),Bash(cat:*),Bash(head:*),Bash(tail:*),Bash(rg:*),Bash(grep:*),Bash(sed:*),Bash(git:*),Bash(ls:*),Bash(wc:*)"
+          prompt: |
+            You are Clud Bug 🐛 conducting a habitat audit. The branch
+            ${{ steps.prep.outputs.branch }} contains a stub file at
+            audits/${{ steps.prep.outputs.date }}.md listing the file manifest
+            for this audit.
+
+            Procedure:
+              1. Read audits/${{ steps.prep.outputs.date }}.md to see the manifest.
+              2. Walk the manifest. For each file, look for critical issues only:
+                 bugs / logic errors, security vulnerabilities (injection, secrets,
+                 unsafe shell, etc.), performance defects, and broken or missing
+                 test coverage on logic that needs it. Skip style nits.
+              3. Append a "## Findings" section to the audit file with one
+                 entry per issue: file:line, the offending snippet, and the fix.
+                 Group by severity. Cite skills from .claude/skills/ where relevant.
+              4. End the file with `Skills referenced: [...]`.
+              5. Commit your changes to the audit file:
+                   git add audits/${{ steps.prep.outputs.date }}.md
+                   git commit -m "🐛 Clud Bug audit — $AUDIT_DATE (findings)"
+                   git push
+              6. Open a PR from this branch to the default branch:
+                   gh pr create \
+                     --title "🐛 Clud Bug audit — $AUDIT_DATE" \
+                     --body "Findings from a habitat walk on $AUDIT_DATE. Review and act on each item; merge if you want the report committed, close otherwise."
+
+            Tone: concise field-naturalist voice — you are documenting specimens.
+            Don't perform the bit; let the precision speak.
+
+            If you find no critical issues, still open the PR with the audit
+            file noting "No critical issues observed." Maintainers will close it.

package/templates/self-update.yml.tmpl

@@ -0,0 +1,92 @@
+name: Clud Bug 🐛 Self-Update
+
+# Weekly check for a newer published clud-bug. If one exists, runs
+# `clud-bug update` (which re-renders the workflow templates and refreshes
+# the bundled baseline specimens, leaving custom and skills.sh-installed
+# specimens alone), then opens a PR titled
+# "🐛 Clud Bug self-update: vX.Y.Z → vA.B.C".
+#
+# To pin to a specific clud-bug version and stop self-updates, add a
+# "pinVersion" field to .claude/skills/.clud-bug.json:
+#   { "pinVersion": "0.3.0", ... }
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 12 * * 1'   # Mondays 12:00 UTC
+
+permissions:
+  contents: write
+  pull-requests: write
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '20'
+
+      - name: Compare installed vs npm latest
+        id: compare
+        run: |
+          MANIFEST=".claude/skills/.clud-bug.json"
+          INSTALLED="(none)"
+          PIN=""
+          if [ -f "$MANIFEST" ]; then
+            INSTALLED=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$MANIFEST','utf8')).lastUpdateVersion || '(unknown)')")
+            PIN=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$MANIFEST','utf8')).pinVersion || '')")
+          fi
+          LATEST=$(npm view clud-bug version)
+          echo "installed=$INSTALLED" >> "$GITHUB_OUTPUT"
+          echo "latest=$LATEST" >> "$GITHUB_OUTPUT"
+          echo "pin=$PIN" >> "$GITHUB_OUTPUT"
+          echo "Installed: $INSTALLED  Latest: $LATEST  Pin: ${PIN:-(none)}"
+
+          if [ -n "$PIN" ]; then
+            echo "Pinned to $PIN — skipping update check."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if [ "$INSTALLED" = "$LATEST" ]; then
+            echo "Already on latest. Nothing to do."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "skip=false" >> "$GITHUB_OUTPUT"
+
+      - name: Run clud-bug update + open PR
+        if: steps.compare.outputs.skip == 'false'
+        env:
+          INSTALLED: ${{ steps.compare.outputs.installed }}
+          LATEST: ${{ steps.compare.outputs.latest }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BRANCH="clud-bug/self-update-${LATEST}"
+          # Use github-actions[bot]'s real identity so commits resolve to a
+          # recognizable bot in the GitHub UI. (A "clud-bug[bot]" identity
+          # would only resolve if we registered an actual GitHub App for
+          # clud-bug — out of scope today.)
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$BRANCH"
+
+          npx -y "clud-bug@${LATEST}" update
+
+          # Note: runUpdate always stamps lastUpdate / lastUpdateVersion in
+          # the manifest, so there will always be at least one diff in this
+          # branch. We rely on `git diff` simply to detect *real* file changes
+          # outside the manifest, and let the PR open either way.
+          git add -A
+          git commit -m "🐛 Clud Bug self-update: ${INSTALLED} → ${LATEST}"
+          git push -u origin "$BRANCH"
+          gh pr create \
+            --title "🐛 Clud Bug self-update: ${INSTALLED} → ${LATEST}" \
+            --body "Automated update from clud-bug ${INSTALLED} → ${LATEST}. Custom and skills.sh-installed specimens were left alone; only baseline specimens and the workflow templates were refreshed.
+
+Review the diff. To stay on this version permanently, add \`\"pinVersion\": \"${INSTALLED}\"\` to \`.claude/skills/.clud-bug.json\` before merging."

package/templates/workflow-py.yml.tmpl

@@ -13,16 +13,50 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0   # strict-mode gate reads base ref's manifest
+
+      # Three-way guard — see workflow.yml.tmpl for full design notes.
+      - name: Guard — require ANTHROPIC_API_KEY
+        id: guard
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_AUTHOR: ${{ github.event.pull_request.user.login }}
+          HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+          BASE_REPO: ${{ github.repository }}
+        run: |
+          if [ -n "$ANTHROPIC_API_KEY" ]; then echo "skip=false" >> "$GITHUB_OUTPUT"; exit 0; fi
+          IS_FORK=false; [ "$HEAD_REPO" != "$BASE_REPO" ] && IS_FORK=true
+          IS_BOT=false; case "$PR_AUTHOR" in *\[bot\]) IS_BOT=true ;; esac
+          if $IS_FORK || $IS_BOT; then
+            REASON=$($IS_BOT && echo "bot author ($PR_AUTHOR)" || echo "fork ($HEAD_REPO)")
+            EXISTING=$(gh api "repos/${BASE_REPO}/issues/${PR_NUMBER}/comments?per_page=100" \
+              --jq '[.[] | select(.user.login == "claude[bot]" and (.body | startswith("## 🐛 Clud Bug skipped")))] | length')
+            if [ "${EXISTING:-0}" = "0" ]; then
+              BODY=$(printf '## 🐛 Clud Bug skipped\n\nThis PR is from a %s. GitHub deliberately does not pass repository secrets to such workflows, so Clud Bug could not authenticate against Anthropic. Review the diff manually.' "$REASON")
+              gh pr comment "$PR_NUMBER" --body "$BODY" || true
+            fi
+            echo "::warning title=Clud Bug 🐛::Skipped — $REASON cannot access repository secrets."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "::error title=Clud Bug 🐛::ANTHROPIC_API_KEY secret is not set on this repository."
+          echo "::error::Set it: Settings → Secrets and variables → Actions → New repository secret."
+          exit 1
 
       - uses: anthropics/claude-code-action@v1
+        if: steps.guard.outputs.skip != 'true'
         env:
           PR_NUMBER: ${{ github.event.pull_request.number }}
+          FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           track_progress: true
           claude_args: |
-            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr review:*),Bash(gh api graphql:*),Bash(gh api repos/:*)"
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh api graphql:*),Bash(gh api repos/:*),Bash(cat .claude/skills/.clud-bug.json)"
           prompt: |
             {{PROJECT_DESCRIPTION}}
 
@@ -39,8 +73,38 @@ jobs:
             Skip style suggestions, minor naming issues, or anything that
             doesn't affect correctness, security, or performance.
 
-            Any project-specific skills loaded from .claude/skills/ should
-            shape your review — defer to their guidance over generic advice.
+            Skills are not background context — they are review rules with
+            authority. Before flagging any finding, scan the loaded skills in
+            .claude/skills/ for relevant guidance. If a skill applies, your
+            review MUST reference it by name in the finding (e.g. "[evidence-
+            based-review]: this claim isn't anchored to a line"). Generic
+            advice that contradicts a project skill is wrong by definition.
+
+            At the end of every review, append a single-line footer:
+              Skills referenced: [skill-name-1, skill-name-2, ...]
+            If you genuinely cited none, list "[none]" and explain why no
+            installed skill applied to this diff.
+
+            Strict-mode header (opt-in): if .claude/skills/.clud-bug.json
+            contains { "strictMode": true }, the comment header you post
+            MUST signal whether you flagged a critical issue:
+              IF you flagged any critical issue (bug, security,
+                  performance, missing test coverage):
+                  ## 🐛 Clud Bug review — critical findings
+              OTHERWISE:
+                  ## 🐛 Clud Bug review — clean
+            A post-step in this workflow greps your posted comment for
+            that header and fails the check on "critical findings." The
+            gate is deterministic on top of your judgment.
+
+            If strictMode is NOT set (or absent), keep the existing
+            "## 🐛 Clud Bug review" header — strict mode is opt-in and
+            other repos use the plain header.
+
+            Tone: address the author conversationally. A concise field-naturalist
+            voice is welcome (you are Clud Bug, examining specimens of code) but
+            never at the cost of clarity, evidence, or the critical-issues-only
+            discipline. Don't perform the bit; let the precision speak.
 
             When you finish, post your review as a single PR comment.
             The comment body MUST start with this exact line so the
@@ -69,3 +133,24 @@ jobs:
             For line-specific issues, use the github_inline_comment MCP tool
             with confirmed: true.
             If there are no critical issues, post a one-line comment saying so.
+
+      # Strict-mode gate — see workflow.yml.tmpl for full design notes.
+      - name: Strict mode — fail check on critical findings
+        if: success()
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          BASE_MANIFEST=$(git show "origin/${{ github.base_ref }}:.claude/skills/.clud-bug.json" 2>&1) || {
+            echo "::warning::Base manifest not found on ${{ github.base_ref }} — strict mode disabled for this run."
+            exit 0
+          }
+          STRICT=$(echo "$BASE_MANIFEST" | node -e "let s='';process.stdin.on('data',c=>s+=c);process.stdin.on('end',()=>{try{console.log(JSON.parse(s).strictMode===true)}catch(e){console.log('false')}})")
+          [ "$STRICT" = "true" ] || exit 0
+          LATEST=$(gh api "repos/${{ github.repository }}/issues/${PR_NUMBER}/comments?sort=created&direction=desc&per_page=100" \
+            --jq '[.[] | select(.user.login == "claude[bot]" and (.body | startswith("## 🐛 Clud Bug review")))][0].body // ""')
+          if echo "$LATEST" | head -n1 | grep -q "Clud Bug review — critical findings"; then
+            echo "::error title=Clud Bug 🐛::Critical issues found and strictMode is enabled — failing this check."
+            echo "::error::See the latest Clud Bug review comment for details. Push a fix and the gate will clear on the next run."
+            exit 1
+          fi

package/templates/workflow-ts.yml.tmpl

@@ -13,16 +13,50 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0   # strict-mode gate reads base ref's manifest
+
+      # Three-way guard — see workflow.yml.tmpl for full design notes.
+      - name: Guard — require ANTHROPIC_API_KEY
+        id: guard
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_AUTHOR: ${{ github.event.pull_request.user.login }}
+          HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+          BASE_REPO: ${{ github.repository }}
+        run: |
+          if [ -n "$ANTHROPIC_API_KEY" ]; then echo "skip=false" >> "$GITHUB_OUTPUT"; exit 0; fi
+          IS_FORK=false; [ "$HEAD_REPO" != "$BASE_REPO" ] && IS_FORK=true
+          IS_BOT=false; case "$PR_AUTHOR" in *\[bot\]) IS_BOT=true ;; esac
+          if $IS_FORK || $IS_BOT; then
+            REASON=$($IS_BOT && echo "bot author ($PR_AUTHOR)" || echo "fork ($HEAD_REPO)")
+            EXISTING=$(gh api "repos/${BASE_REPO}/issues/${PR_NUMBER}/comments?per_page=100" \
+              --jq '[.[] | select(.user.login == "claude[bot]" and (.body | startswith("## 🐛 Clud Bug skipped")))] | length')
+            if [ "${EXISTING:-0}" = "0" ]; then
+              BODY=$(printf '## 🐛 Clud Bug skipped\n\nThis PR is from a %s. GitHub deliberately does not pass repository secrets to such workflows, so Clud Bug could not authenticate against Anthropic. Review the diff manually.' "$REASON")
+              gh pr comment "$PR_NUMBER" --body "$BODY" || true
+            fi
+            echo "::warning title=Clud Bug 🐛::Skipped — $REASON cannot access repository secrets."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "::error title=Clud Bug 🐛::ANTHROPIC_API_KEY secret is not set on this repository."
+          echo "::error::Set it: Settings → Secrets and variables → Actions → New repository secret."
+          exit 1
 
       - uses: anthropics/claude-code-action@v1
+        if: steps.guard.outputs.skip != 'true'
         env:
           PR_NUMBER: ${{ github.event.pull_request.number }}
+          FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true'
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
           track_progress: true
           claude_args: |
-            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr review:*),Bash(gh api graphql:*),Bash(gh api repos/:*)"
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh api graphql:*),Bash(gh api repos/:*),Bash(cat .claude/skills/.clud-bug.json)"
           prompt: |
             {{PROJECT_DESCRIPTION}}
 
@@ -40,8 +74,38 @@ jobs:
             Skip style suggestions, minor naming issues, or anything that
             doesn't affect correctness, security, or performance.
 
-            Any project-specific skills loaded from .claude/skills/ should
-            shape your review — defer to their guidance over generic advice.
+            Skills are not background context — they are review rules with
+            authority. Before flagging any finding, scan the loaded skills in
+            .claude/skills/ for relevant guidance. If a skill applies, your
+            review MUST reference it by name in the finding (e.g. "[evidence-
+            based-review]: this claim isn't anchored to a line"). Generic
+            advice that contradicts a project skill is wrong by definition.
+
+            At the end of every review, append a single-line footer:
+              Skills referenced: [skill-name-1, skill-name-2, ...]
+            If you genuinely cited none, list "[none]" and explain why no
+            installed skill applied to this diff.
+
+            Strict-mode header (opt-in): if .claude/skills/.clud-bug.json
+            contains { "strictMode": true }, the comment header you post
+            MUST signal whether you flagged a critical issue:
+              IF you flagged any critical issue (bug, security,
+                  performance, missing test coverage):
+                  ## 🐛 Clud Bug review — critical findings
+              OTHERWISE:
+                  ## 🐛 Clud Bug review — clean
+            A post-step in this workflow greps your posted comment for
+            that header and fails the check on "critical findings." The
+            gate is deterministic on top of your judgment.
+
+            If strictMode is NOT set (or absent), keep the existing
+            "## 🐛 Clud Bug review" header — strict mode is opt-in and
+            other repos use the plain header.
+
+            Tone: address the author conversationally. A concise field-naturalist
+            voice is welcome (you are Clud Bug, examining specimens of code) but
+            never at the cost of clarity, evidence, or the critical-issues-only
+            discipline. Don't perform the bit; let the precision speak.
 
             When you finish, post your review as a single PR comment.
             The comment body MUST start with this exact line so the
@@ -70,3 +134,24 @@ jobs:
             For line-specific issues, use the github_inline_comment MCP tool
             with confirmed: true.
             If there are no critical issues, post a one-line comment saying so.
+
+      # Strict-mode gate — see workflow.yml.tmpl for full design notes.
+      - name: Strict mode — fail check on critical findings
+        if: success()
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          BASE_MANIFEST=$(git show "origin/${{ github.base_ref }}:.claude/skills/.clud-bug.json" 2>&1) || {
+            echo "::warning::Base manifest not found on ${{ github.base_ref }} — strict mode disabled for this run."
+            exit 0
+          }
+          STRICT=$(echo "$BASE_MANIFEST" | node -e "let s='';process.stdin.on('data',c=>s+=c);process.stdin.on('end',()=>{try{console.log(JSON.parse(s).strictMode===true)}catch(e){console.log('false')}})")
+          [ "$STRICT" = "true" ] || exit 0
+          LATEST=$(gh api "repos/${{ github.repository }}/issues/${PR_NUMBER}/comments?sort=created&direction=desc&per_page=100" \
+            --jq '[.[] | select(.user.login == "claude[bot]" and (.body | startswith("## 🐛 Clud Bug review")))][0].body // ""')
+          if echo "$LATEST" | head -n1 | grep -q "Clud Bug review — critical findings"; then
+            echo "::error title=Clud Bug 🐛::Critical issues found and strictMode is enabled — failing this check."
+            echo "::error::See the latest Clud Bug review comment for details. Push a fix and the gate will clear on the next run."
+            exit 1
+          fi