clud-bug 0.2.0 → 0.5.0

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

@@ -1,11 +1,26 @@
 import { mkdir, writeFile, readdir, readFile, rm, stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
 
 const API_BASE = 'https://skills.sh/api/v1';
 const MAX_SKILLS = 8;
 const MANIFEST_FILE = '.clud-bug.json';
 const MANIFEST_VERSION = 1;
 
+// Canonical home for clud-bug's baseline skills.
+// PINNED TO A COMMIT SHA, NOT `main`. This re-couples the trust boundary
+// to clud-bug releases: a compromised commit on agent-skills@main cannot
+// silently land in users' Claude review skills mid-cycle. To roll new
+// skill content, bump BASELINE_SKILLS_REF below in the same clud-bug PR
+// that ships the corresponding bundled fallback update.
+// See thrillmot/agent-skills — skills.sh `skills/<name>/SKILL.md` layout.
+const BASELINE_SKILLS_REF = '977e439ec861860351239ed89dd56edcd48cbf6b';
+const AGENT_SKILLS_BASE = process.env.CLUD_BUG_AGENT_SKILLS_BASE
+  ?? `https://raw.githubusercontent.com/thrillmot/agent-skills/${BASELINE_SKILLS_REF}/skills`;
+const SKILL_FETCH_TIMEOUT_MS = 5000;
+const SKILL_CACHE_TTL_MS = 24 * 60 * 60 * 1000;   // 24h
+
 export class SkillsClient {
   constructor({ fetch = globalThis.fetch, base, userAgent = 'clud-bug' } = {}) {
     this.fetch = fetch;
@@ -78,7 +93,34 @@ export function rankAndCap(curated, searched, baseline, cap = MAX_SKILLS) {
   return out;
 }
 
-export async function loadBaseline(baselineDir) {
+// Loads the baseline skills, preferring the pinned thrillmot/agent-skills
+// commit and falling back to the bundled npm-package copy on any fetch failure.
+// Returns the same shape as before, plus a `_source` of either 'agent-skills'
+// or 'bundled' so the CLI can report which path was used.
+//
+// Options:
+//   - fetch     — injectable for tests (defaults to globalThis.fetch)
+//   - cacheDir  — where to cache fetched SKILL.md files (defaults to
+//                 ~/.cache/clud-bug/skills/, skipped if null)
+export async function loadBaseline(baselineDir, opts = {}) {
+  const fetchImpl = opts.fetch ?? globalThis.fetch;
+  const cacheDir = opts.cacheDir === null ? null
+    : (opts.cacheDir ?? join(homedir(), '.cache', 'clud-bug', 'skills'));
+
+  // First, enumerate the bundled baseline skills (source of truth for which
+  // names exist). Then fetch each in parallel — sequential awaits would
+  // stack timeouts (3 baselines × 5s = 15s before fallback when offline).
+  const bundled = await readBundled(baselineDir);
+  const remotes = await Promise.all(
+    bundled.map((s) => tryFetchSkill(s.name, fetchImpl, cacheDir)),
+  );
+  return bundled.map((skill, i) => remotes[i]
+    ? { ...skill, content: remotes[i], _source: 'agent-skills' }
+    : { ...skill, _source: 'bundled' });
+}
+
+// Reads the bundled baseline from the npm-package directory.
+async function readBundled(baselineDir) {
   const skills = [];
   let entries;
   try {
@@ -92,7 +134,7 @@ export async function loadBaseline(baselineDir) {
     skills.push({
       source: 'clud-bug-baseline',
       name: entry.name.replace(/\.md$/, ''),
-      description: '(bundled baseline)',
+      description: '(baseline)',
       installs: 0,
       kind: 'baseline',
       content,
@@ -101,6 +143,65 @@ export async function loadBaseline(baselineDir) {
   return skills;
 }
 
+// Try to read from cache, then fall back to network. Returns the SKILL.md
+// content string on success, null on any failure (caller falls back to bundled).
+async function tryFetchSkill(name, fetchImpl, cacheDir) {
+  // Cache lookup first.
+  if (cacheDir) {
+    const cached = await readFromCache(cacheDir, name);
+    if (cached !== null) return cached;
+  }
+
+  // Network fetch with timeout covering BOTH the connection AND the body
+  // read (clearTimeout in finally guarantees the timer doesn't keep the
+  // event loop alive for up to 5s past a failed CLI run).
+  const url = `${AGENT_SKILLS_BASE}/${encodeURIComponent(name)}/SKILL.md`;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), SKILL_FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetchImpl(url, { signal: ctrl.signal });
+    if (!res.ok) return null;
+    const content = await res.text();
+    if (!content || !content.trim()) return null;
+    if (cacheDir) await writeToCache(cacheDir, name, content);
+    return content;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function readFromCache(cacheDir, name) {
+  const path = cachePath(cacheDir, name);
+  try {
+    const st = await stat(path);
+    if (Date.now() - st.mtimeMs > SKILL_CACHE_TTL_MS) return null;
+    return await readFile(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+async function writeToCache(cacheDir, name, content) {
+  try {
+    await mkdir(cacheDir, { recursive: true });
+    await writeFile(cachePath(cacheDir, name), content);
+  } catch {
+    // Cache write failures are non-fatal — we already have the content.
+  }
+}
+
+function cachePath(cacheDir, name) {
+  // Include AGENT_SKILLS_BASE in the hash so different upstream URLs (e.g.
+  // a fork via CLUD_BUG_AGENT_SKILLS_BASE, or a different pinned SHA after
+  // a clud-bug release) get different cache entries. Otherwise switching
+  // bases would silently return the previously-cached content from a
+  // different upstream — cross-base cache poisoning.
+  const hash = createHash('sha256').update(`${AGENT_SKILLS_BASE}\n${name}`).digest('hex').slice(0, 16);
+  return join(cacheDir, `${hash}.md`);
+}
+
 export async function writeSkills(targetDir, skills, client) {
   await mkdir(targetDir, { recursive: true });
   const written = [];
@@ -133,6 +234,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 +245,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 +263,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,99 @@
+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,
+  loadBaselineOpts,    // forwarded to loadBaseline (e.g. for tests: { fetch, cacheDir: null })
+} = {}) {
+  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, loadBaselineOpts);
+  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.5.0",
   "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."