forge-orkes 0.41.0 → 0.44.0

package/bin/create-forge.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const readline = require('readline');
 const { execSync } = require('child_process');
@@ -93,6 +94,56 @@ function copyDirRecursive(src, dest) {
   return count;
 }
 
+/**
+ * Make every *.sh under a hooks dir executable (ADR-017). The npm tarball usually
+ * preserves the bit, but a checkout/copy can strip it — the guard hooks must be
+ * runnable or Claude Code silently skips them. Best-effort: never throws.
+ */
+function makeHookScriptsExecutable(hooksDir) {
+  if (!fs.existsSync(hooksDir)) return;
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(p);
+      else if (entry.name.endsWith('.sh')) {
+        try { fs.chmodSync(p, 0o755); } catch { /* best-effort */ }
+      }
+    }
+  };
+  try { walk(hooksDir); } catch { /* best-effort */ }
+}
+
+/**
+ * Additively sync a framework-managed `.claude/` dir into an existing project on
+ * upgrade (ADR-017/018). Copies/updates the template's files, but NEVER deletes
+ * project-local extras — so experimental hooks (m10 `forge-claim-check`) and
+ * pack-installed path-scoped rules (laravel-*, vue-inertia, …) survive. These dirs
+ * are intentionally NOT in FRAMEWORK_OWNED_DIRS, whose auto-clean would flag those
+ * extras as "stale" and offer to remove them.
+ */
+function upgradeAdditiveDir(relDir, results) {
+  const srcDir = path.join(templateDir, relDir);
+  const destDir = path.join(targetDir, relDir);
+  if (!fs.existsSync(srcDir)) return;
+
+  for (const rel of collectFiles(srcDir, '')) {
+    const srcPath = path.join(srcDir, rel);
+    const destPath = path.join(destDir, rel);
+    const displayPath = path.join(relDir, rel);
+    if (!fs.existsSync(destPath)) {
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      fs.copyFileSync(srcPath, destPath);
+      results.added.push(displayPath);
+    } else if (Buffer.compare(fs.readFileSync(srcPath), fs.readFileSync(destPath)) !== 0) {
+      fs.copyFileSync(srcPath, destPath);
+      results.updated.push(displayPath);
+    } else {
+      results.unchanged.push(displayPath);
+    }
+  }
+  makeHookScriptsExecutable(destDir); // no-op for dirs with no *.sh
+}
+
 /**
  * npm strips files literally named `.gitignore` from a published tarball (it
  * treats them as ignore-rules, not content), so the template ships its forge
@@ -155,7 +206,7 @@ function upgradeDir(relDir, { autoClean = false } = {}) {
   const srcDir = path.join(templateDir, relDir);
   const destDir = path.join(targetDir, relDir);
 
-  const result = { updated: [], added: [], unchanged: [], removed: [], preserved: [] };
+  const result = { updated: [], added: [], unchanged: [], removed: [], preserved: [], removeCandidates: [] };
 
   if (!fs.existsSync(srcDir)) return result;
 
@@ -195,15 +246,13 @@ function upgradeDir(relDir, { autoClean = false } = {}) {
       }
       const destPath = path.join(destDir, rel);
       if (autoClean) {
-        fs.unlinkSync(destPath);
-        // Remove empty parent dirs up to relDir
-        let dir = path.dirname(destPath);
-        while (dir !== destDir && fs.existsSync(dir) && fs.readdirSync(dir).length === 0) {
-          fs.rmdirSync(dir);
-          dir = path.dirname(dir);
-        }
+        // Defer deletion — collect the candidate; upgrade() confirms before
+        // removing (R066a). Empty-parent cleanup needs destDir, carried along.
+        result.removeCandidates.push({ destPath, destDir, displayPath });
+      } else {
+        // Template-only dirs: report-only, no deletion here (existing behavior).
+        result.removed.push(displayPath);
       }
-      result.removed.push(path.join(relDir, rel));
     }
   }
 
@@ -271,7 +320,80 @@ function ensureClaudeMdImport() {
 }
 
 /**
- * Smart-merge settings.json: overwrite forge.* keys from template, preserve user hooks.
+ * Additively install the template's framework-managed hooks into an existing
+ * settings.json (ADR-017). Never removes a user's hooks; dedups by deep-equality
+ * so re-running upgrade is idempotent. New groups (the safety guardrails) get
+ * appended; groups the project already has (identical) are skipped.
+ */
+function mergeManagedHooks(destSettings, srcSettings) {
+  if (!srcSettings.hooks) return;
+  destSettings.hooks = destSettings.hooks || {};
+  for (const event of Object.keys(srcSettings.hooks)) {
+    const srcGroups = srcSettings.hooks[event] || [];
+    const destGroups = destSettings.hooks[event] || (destSettings.hooks[event] = []);
+    for (const group of srcGroups) {
+      const groupJson = JSON.stringify(group);
+      if (!destGroups.some((d) => JSON.stringify(d) === groupJson)) {
+        destGroups.push(group);
+      }
+    }
+  }
+}
+
+/**
+ * Union the template's secret/key deny globs into the project's permissions.deny
+ * (ADR-017). Additive — a user's own allow/deny entries are untouched.
+ */
+function mergeManagedDeny(destSettings, srcSettings) {
+  const srcDeny = (srcSettings.permissions && srcSettings.permissions.deny) || [];
+  if (!srcDeny.length) return;
+  destSettings.permissions = destSettings.permissions || {};
+  const destDeny = destSettings.permissions.deny || (destSettings.permissions.deny = []);
+  for (const glob of srcDeny) {
+    if (!destDeny.includes(glob)) destDeny.push(glob);
+  }
+}
+
+/**
+ * Strip the legacy *inline* active-skill guard from PreToolUse (forge#12). It was
+ * an inline `if [ ! -f .../.forge/.active-skill ]; then ... exit 2; fi` one-liner;
+ * it is replaced by the forge-active-skill-guard.sh script (which also honors a
+ * milestone's executing status). The additive hook merge can only ADD the new
+ * script group — it can't remove the superseded inline one, so an un-migrated
+ * project would run BOTH and the old inline check would still block edits when the
+ * marker is cleared. This removes only the inline form (the script call — which
+ * carries neither `if [ ! -f` nor the message — is left intact).
+ */
+function migrateActiveSkillHook(destSettings) {
+  const pre = destSettings.hooks && destSettings.hooks.PreToolUse;
+  if (!Array.isArray(pre)) return false;
+  let changed = false;
+  for (const group of pre) {
+    if (!Array.isArray(group.hooks)) continue;
+    const kept = group.hooks.filter(
+      (h) =>
+        !(
+          typeof h.command === 'string' &&
+          h.command.includes('.forge/.active-skill') &&
+          h.command.includes('No active skill') &&
+          h.command.includes('if [ ! -f')
+        )
+    );
+    if (kept.length !== group.hooks.length) {
+      group.hooks = kept;
+      changed = true;
+    }
+  }
+  // Drop any group left with no hooks by the strip.
+  destSettings.hooks.PreToolUse = pre.filter(
+    (g) => !Array.isArray(g.hooks) || g.hooks.length > 0
+  );
+  return changed;
+}
+
+/**
+ * Smart-merge settings.json: overwrite forge.* keys from template, additively
+ * install framework-managed safety hooks + secret-deny globs, preserve user hooks.
  */
 function upgradeSettings() {
   const srcPath = path.join(templateDir, SETTINGS_FILE);
@@ -289,6 +411,12 @@ function upgradeSettings() {
   destSettings.forge = { ...destSettings.forge, ...srcSettings.forge };
   // Always stamp current package version
   destSettings.forge.version = pkgVersion;
+  // Remove the superseded inline active-skill guard before the additive merge
+  // installs its script-based replacement (forge#12).
+  migrateActiveSkillHook(destSettings);
+  // Additively install framework-managed safety guardrails (ADR-017)
+  mergeManagedHooks(destSettings, srcSettings);
+  mergeManagedDeny(destSettings, srcSettings);
 
   const after = JSON.stringify(destSettings);
   if (before === after) return 'unchanged';
@@ -321,6 +449,7 @@ async function install() {
   const srcClaude = path.join(templateDir, '.claude');
   const destClaude = path.join(targetDir, '.claude');
   const claudeCount = copyDirRecursive(srcClaude, destClaude);
+  makeHookScriptsExecutable(path.join(destClaude, 'hooks'));
   console.log(`  Installed .claude/ (${claudeCount} files)`);
 
   // Copy .forge/templates/ directory
@@ -358,7 +487,9 @@ async function install() {
 
   console.log(`\n  Forge v${pkgVersion} is ready. Start with: /forge\n`);
 
-  // Presence-gated: if a Codex adapter is present, note it may need regeneration.
+  // Presence-gated: a fresh install normally has no Codex adapter, so this is a
+  // no-op — but if the target repo already carries a .agents/ / .codex/ tree
+  // (e.g. migrating in from another setup), note it may need regeneration.
   noticeCodexAdapter();
 }
 
@@ -442,14 +573,19 @@ function runPostUpgradeMigrationChecks(installedVersion) {
 
     let stdout = '';
     try {
+      // Trust model: guides were re-synced from the (trusted) npm package in
+      // step 2 above before this runs, so the on-disk content is not
+      // attacker-controlled here; the only residual risk is a runaway/buggy
+      // detection block, bounded by `timeout`.
       stdout = execSync(script, {
         cwd: targetDir,
         shell: '/bin/bash',
         encoding: 'utf-8',
         stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 10000, // 10s — a pathological guide throws (caught below) → no-op, loop continues
       });
     } catch {
-      // A non-zero exit or detection error is a no-op, not a failure — keep going.
+      // A non-zero exit, timeout, or detection error is a no-op, not a failure — keep going.
       continue;
     }
 
@@ -476,6 +612,26 @@ function runPostUpgradeMigrationChecks(installedVersion) {
   }
 }
 
+/**
+ * Sync a single standalone framework-owned file, overwriting when content
+ * differs. Records the outcome in `results` (added/updated/unchanged). Used for
+ * framework files that live outside the recursively-synced dirs (.forge/.gitignore,
+ * .forge/FORGE.md).
+ */
+function syncFrameworkFile(srcPath, destPath, displayName, results) {
+  if (!fs.existsSync(srcPath)) return;
+  const newContent = fs.readFileSync(srcPath, 'utf-8');
+  const existed = fs.existsSync(destPath);
+  const oldContent = existed ? fs.readFileSync(destPath, 'utf-8') : null;
+  if (oldContent !== newContent) {
+    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+    fs.writeFileSync(destPath, newContent);
+    results[existed ? 'updated' : 'added'].push(displayName);
+  } else {
+    results.unchanged.push(displayName);
+  }
+}
+
 async function upgrade() {
   console.log('\n  Forge Upgrade\n');
 
@@ -524,7 +680,9 @@ async function upgrade() {
     preserved: [],
   };
 
-  // 1. Process framework-owned directories (auto-clean stale files)
+  // 1. Process framework-owned directories (stale files are collected for a
+  //    confirmed removal pass below, not deleted inline — R066a).
+  const pendingRemovals = [];
   for (const dir of FRAMEWORK_OWNED_DIRS) {
     const dirResult = upgradeDir(dir, { autoClean: true });
     results.updated.push(...dirResult.updated);
@@ -532,6 +690,7 @@ async function upgrade() {
     results.unchanged.push(...dirResult.unchanged);
     results.removed.push(...dirResult.removed);
     results.preserved.push(...dirResult.preserved);
+    pendingRemovals.push(...dirResult.removeCandidates);
   }
 
   // 2. Process template-only directories
@@ -544,41 +703,66 @@ async function upgrade() {
     results.preserved.push(...dirResult.preserved);
   }
 
-  // 2b. Sync the forge .gitignore. Shipped as `gitignore` (npm strips dotfiles
-  // named .gitignore); materialize/refresh it as `.forge/.gitignore`.
-  const giSrc = path.join(templateDir, '.forge', 'gitignore');
-  const giDest = path.join(targetDir, '.forge', '.gitignore');
-  if (fs.existsSync(giSrc)) {
-    const newContent = fs.readFileSync(giSrc, 'utf-8');
-    const existed = fs.existsSync(giDest);
-    const oldContent = existed ? fs.readFileSync(giDest, 'utf-8') : null;
-    if (oldContent !== newContent) {
-      fs.mkdirSync(path.dirname(giDest), { recursive: true });
-      fs.writeFileSync(giDest, newContent);
-      results[existed ? 'updated' : 'added'].push('.forge/.gitignore');
-    } else {
-      results.unchanged.push('.forge/.gitignore');
+  // 2-hooks. Sync the safety-guardrail hooks (ADR-017) and the always-on rules
+  //    layer (ADR-018). Additive — preserves project-local/experimental hooks and
+  //    pack-installed path-scoped rules, chmod +x's any scripts. Settings wiring is
+  //    merged separately by upgradeSettings().
+  upgradeAdditiveDir('.claude/hooks', results);
+  upgradeAdditiveDir('.claude/rules', results);
+
+  // 2a. Confirm stale framework-file removals before deleting (R066a). Defaults
+  //     to yes (cleanup is the normal case); auto-confirms when non-interactive
+  //     (CI / piped stdin) or with --force/--yes, preserving prior behavior.
+  if (pendingRemovals.length > 0) {
+    const auto =
+      process.argv.includes('--force') ||
+      process.argv.includes('--yes') ||
+      !process.stdin.isTTY;
+    console.log(`  ${pendingRemovals.length} stale framework file(s) no longer in the template:`);
+    for (const c of pendingRemovals) console.log(`    ${c.displayPath}`);
+    let go = auto;
+    if (!auto) {
+      const ans = await prompt('  Remove these stale framework files? [Y/n] ');
+      go = ans === '' || ans === 'y' || ans === 'yes';
     }
-  }
-
-  // 2c. Sync the framework prose file .forge/FORGE.md (framework-owned single file,
-  // same overwrite-when-different pattern as 2b). MUST run before the CLAUDE.md pass
-  // so a migrated project's import line never points at a missing file.
-  const fmSrc = path.join(templateDir, '.forge', 'FORGE.md');
-  const fmDest = path.join(targetDir, '.forge', 'FORGE.md');
-  if (fs.existsSync(fmSrc)) {
-    const newContent = fs.readFileSync(fmSrc, 'utf-8');
-    const existed = fs.existsSync(fmDest);
-    const oldContent = existed ? fs.readFileSync(fmDest, 'utf-8') : null;
-    if (oldContent !== newContent) {
-      fs.mkdirSync(path.dirname(fmDest), { recursive: true });
-      fs.writeFileSync(fmDest, newContent);
-      results[existed ? 'updated' : 'added'].push('.forge/FORGE.md');
+    if (go) {
+      for (const c of pendingRemovals) {
+        if (fs.existsSync(c.destPath)) fs.unlinkSync(c.destPath);
+        // Remove now-empty parent dirs up to the synced root.
+        let dir = path.dirname(c.destPath);
+        while (dir !== c.destDir && fs.existsSync(dir) && fs.readdirSync(dir).length === 0) {
+          fs.rmdirSync(dir);
+          dir = path.dirname(dir);
+        }
+        results.removed.push(c.displayPath);
+      }
     } else {
-      results.unchanged.push('.forge/FORGE.md');
+      console.log('  Keeping stale files (skipped removal).');
+      for (const c of pendingRemovals) {
+        results.preserved.push(`${c.displayPath} (stale — kept by choice)`);
+      }
     }
+    console.log();
   }
 
+  // 2b. Sync the forge .gitignore. Shipped as `gitignore` (npm strips dotfiles
+  // named .gitignore); materialize/refresh it as `.forge/.gitignore`.
+  syncFrameworkFile(
+    path.join(templateDir, '.forge', 'gitignore'),
+    path.join(targetDir, '.forge', '.gitignore'),
+    '.forge/.gitignore',
+    results
+  );
+
+  // 2c. Sync the framework prose file .forge/FORGE.md. MUST run before the
+  // CLAUDE.md pass so a migrated project's import line never points at a missing file.
+  syncFrameworkFile(
+    path.join(templateDir, '.forge', 'FORGE.md'),
+    path.join(targetDir, '.forge', 'FORGE.md'),
+    '.forge/FORGE.md',
+    results
+  );
+
   // 3. Guarantee the CLAUDE.md import line; auto-migrate any legacy embedded section.
   const claudeStatus = ensureClaudeMdImport();
   if (claudeStatus === 'migrated') {
@@ -721,6 +905,24 @@ function noticeWorktreeLag() {
 
 // --- Entry point ---
 
+// cwd sanity (R066c): Forge writes .claude/, .forge/, and CLAUDE.md into the
+// current directory. Refuse the clearly-wrong locations (home dir, filesystem
+// root) unless --force, so an accidental run from the wrong place can't litter
+// framework files across $HOME or /.
+function assertSaneTargetDir() {
+  if (process.argv.includes('--force')) return;
+  const root = path.parse(targetDir).root;
+  if (targetDir === root || targetDir === os.homedir()) {
+    const where = targetDir === os.homedir() ? 'your home directory' : 'the filesystem root';
+    console.error(`  ✖ Refusing to run in ${where} (${targetDir}).`);
+    console.error('    Forge writes .claude/, .forge/, and CLAUDE.md into the current directory —');
+    console.error('    run it from a project root. To override: forge-orkes --force\n');
+    process.exit(1);
+  }
+}
+
+assertSaneTargetDir();
+
 const subcommand = process.argv[2];
 
 if (subcommand === 'upgrade') {

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "forge-orkes",
-  "version": "0.41.0",
+  "version": "0.44.0",
   "description": "Set up the Forge meta-prompting framework for Claude Code in your project",
   "bin": {
     "create-forge": "./bin/create-forge.js"
   },
+  "scripts": {
+    "release": "node scripts/release.js",
+    "release:audit": "node scripts/release.js audit"
+  },
   "files": [
     "bin/",
     "template/"

package/template/.claude/agents/doc-reviewer.md

@@ -0,0 +1,115 @@
+---
+name: doc-reviewer
+description: Confidence-gated documentation specialist. Verifies docs against source code — signatures, examples, paths, config — not vibe-checks. Spawnable from the `reviewing` skill or invoked directly when docs change materially. Read-only.
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+---
+
+You review documentation for quality. Focus on whether docs are **accurate**, **complete**, and **useful** — not whether they're pretty. A reader who follows wrong docs hits a wall; your job is to catch that before they do. The discipline that makes this agent worth running: **verify every claim against source before flagging it.**
+
+## Your Sources of Truth
+
+The source code is the source of truth — docs are checked against it, never the reverse. Know which bucket a changed doc falls in; the bar differs.
+
+1. **Agent-instruction docs** — `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/**`, `.claude/skills/**/SKILL.md`, `.claude/agents/**`. Wrong content here cascades into every agent session. **Bar is highest.**
+2. **Process/standards docs** — contributing guides, workflow/convention docs, the project's `.forge/` governance files. Affect every contributor. Bar is high.
+3. **Architecture docs / ADRs** — `.forge/decisions/**`, `docs/architecture/**`, design docs. Verify against actual code and check consistency with sibling ADRs.
+4. **Code-adjacent docs** — `README.md`, per-directory `README.md`, inline docstrings, JSDoc/TSDoc, package docs. Verify against the code they describe.
+5. **Feature specs / plans** — verify acceptance criteria are testable and match the implementation when the work has landed.
+
+If the project has no `.forge/` governance docs, just classify by what's present (READMEs, ADRs, agent docs).
+
+## Confidence Gating — Report Threshold
+
+Every finding requires:
+
+1. **Severity** — Blocker (wrong info that will make a reader take a wrong action) / Major (missing a critical step, or outdated but not dangerous) / Minor (clarity/polish)
+2. **Confidence** — 1-10. 10 = verified against source code/config. 5 = reads oddly, unverified. <6 = drop.
+3. **Concrete impact** — one sentence: "A reader following this doc will `<do X>` and hit `<Y>`." If you cannot name the wrong action the reader will take, drop the finding.
+4. **Fix** — the exact rewrite, not "clarify this" or "improve phrasing."
+
+Report only Blocker + Major findings at **Confidence ≥ 8**. Minor findings at 6-7 confidence collapse into a single "Nice-to-fix" list. Drop everything below 6. If nothing meets the bar, one sentence, stop.
+
+## How to Review
+
+1. Run `git diff --name-only` filtered to doc formats: `*.md`, `*.rst`, `*.txt`, and inline docstring/JSDoc changes (use `git diff` to see comment/docstring diffs).
+2. Classify each changed file into one of the buckets above.
+3. For each doc change, **read the source code it references**. Verify before flagging.
+4. Apply the categories below, in order.
+
+## Accuracy — Cross-Reference With Code
+
+This is the core of the job. Every factual claim gets checked against source.
+
+- **Function/command signatures**: read the actual function or CLI definition. Parameter names, types, defaults, return types must match.
+- **Code examples**: trace every import path (does it exist? use Glob), every function call (does the signature match? use Grep), every CLI flag (does it exist? check the command definition). Examples that don't run waste readers.
+- **Config options**: grep the codebase for the option name. Is it still used? Has the default changed?
+- **File/directory references**: use Glob or `ls` to verify referenced paths exist.
+- **Version numbers**: check the manifest (`package.json`, `composer.json`, `pyproject.toml`, `go.mod`, etc.). Outdated version claims are a Blocker when they drive install instructions.
+- **URLs**: internal URLs (`http://localhost:...`, repo-relative links) — verify spelling, port, and that the target exists. External URLs — trust, but flag an obviously defunct domain.
+
+If you can't verify something, say so: "Could not verify X — requires runtime testing." Do not flag it as a defect.
+
+## Completeness
+
+- **Prerequisites** named (e.g. "requires `jq`" — flag anything that relies on a binary not guaranteed installed)
+- **Steps in order** — no "configure X" before "install X"
+- **Required inputs and expected outputs** for each step
+- **Error cases**: at minimum, "if you see X, it means Y"
+- **Cross-links**: if this doc references another, the link points somewhere real
+
+## Clarity
+
+- **Pronouns with clear antecedents** ("it" referring to something three paragraphs up is a Minor)
+- **No jargon without definition** on first use in onboarding docs (skill/agent files may assume their audience)
+- **Imperative voice** for instructions ("Run …" not "You should run …")
+- **Consistent terminology** — don't switch between two words for the same concept within a single doc
+
+## Consistency Within the Project
+
+- **Conventions** — flag contradictions between a stated convention doc and what the code/commands actually do
+- **ADRs** — a new architectural doc that contradicts an existing ADR without marking the old one superseded is a Blocker
+- **Terminology drift** — if the docs call it one thing and the code calls it another, the docs are wrong; flag it
+
+## Agent-Docs Specific Checks
+
+When reviewing `CLAUDE.md`, `AGENTS.md`, `.claude/skills/**`, `.claude/agents/**`, or `.cursor/rules/**`:
+
+- **File references**: if the doc tells an agent to read `.claude/skills/foo/bar.md`, verify `foo/bar.md` exists
+- **Skill/command references**: if the doc says "run the `reviewing` skill" or "`/review`", verify the referenced skill/command exists and matches the described behaviour
+- **Agent references**: if the doc mentions an agent (e.g. `security-reviewer`), verify `.claude/agents/security-reviewer.md` exists
+- **Stale skill triggers**: a skill's `description:` field must accurately describe when it should fire — a wrong description causes skill-invocation drift
+
+## Calibrated Exclusions — Do Not Flag
+
+1. Grammar/typos that don't change meaning (unless in a headline, title, or first-line `description:`)
+2. Style preferences the project hasn't agreed on (Oxford comma, sentence vs title case) — unless there's a stated style rule this violates
+3. "This could be explained better" without a concrete proposed rewrite
+4. Archive/historical docs (`**/archive/**`, ADRs marked Superseded) unless the change itself targets them
+5. Comments that are self-evident from the code they describe being removed — that's cleanup, not a finding
+
+## Output Format
+
+```
+## Docs changed
+<list, one line per doc, e.g. ".claude/skills/reviewing/SKILL.md, README.md">
+
+## Findings (Confidence ≥ 8)
+
+### 1. [Blocker] <short title>
+- File: `README.md:28`
+- Confidence: 10/10
+- Impact: "A reader following the quick start will run `chmod +x ./.claude/hooks/*.sh` before copying the hooks in, hit `No such file or directory`, and skip the step."
+- Fix: Move the `chmod +x` line to run after step 1 (the `cp -r .claude` line), not before.
+
+## Nice-to-fix
+- `docs/WORKFLOW.md:88` — terminology drift: uses "task" and "unit" interchangeably; pick one
+
+## Summary
+<one sentence — e.g. "One Blocker in README quick start; rest is clean.">
+```
+
+If no findings at Confidence ≥ 8: "No findings at Confidence ≥ 8. Docs reviewed: <list>." Stop.