claude-code-arcane 2.15.0 → 2.17.0

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+# [2.17.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.16.0...v2.17.0) (2026-10-16)
+
+
+### Bug Fixes
+
+* **update:** narrow the old Bash(gh *) allow in existing installs ([4b033be](https://github.com/SebastianLuser/claude-code-arcane/commit/4b033befa1c3f68e84855cbf9e430f21be836293))
+
+
+### Features
+
+* **cli:** add arcane doctor to check that an install works ([cd36de9](https://github.com/SebastianLuser/claude-code-arcane/commit/cd36de93baad06f6e5e47151eb2902fc6d6d1651))
+
+# [2.16.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.15.0...v2.16.0) (2026-10-16)
+
+
+### Features
+
+* **profiles:** ship playwright-pro with the web profiles ([a6d3785](https://github.com/SebastianLuser/claude-code-arcane/commit/a6d37851f1c6dd2384a96e7b3a00e797e178b10f))
+* **rules:** review a finished goal with a fresh subagent ([9aab70b](https://github.com/SebastianLuser/claude-code-arcane/commit/9aab70bf1a26af19d8bfe9ba9d7e75b7c651637b))
+
 # [2.15.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.14.0...v2.15.0) (2026-10-16)
 
 

package/README.md

@@ -149,6 +149,7 @@ Installs worktree-isolation scripts into `~/.claude/scripts/` and adds a `Sessio
 ```bash
 npx claude-code-arcane list                          # List all profiles and skills
 npx claude-code-arcane status                        # Show current installation
+npx claude-code-arcane doctor                        # Check that hooks, settings and content work
 npx claude-code-arcane update                        # Check for updates
 npx claude-code-arcane clean --force                 # Remove Arcane entirely from project
 ```
@@ -194,13 +195,13 @@ Older names still install and update: `backend-ts`, `frontend`, `mobile`, `flutt
 | `backend-go` | Backend Go — Clean Arch, DB, auth, API, CI | 26 | engineering |
 | `backend-dotnet` | Backend .NET — ASP.NET Core, Vertical Slice/Clean, EF Core, JWT | 27 | engineering |
 | `backend-nestjs` | Backend NestJS — feature modules, DI, Prisma, JWT, microservices | 27 | engineering |
-| `backend-nextjs` | Next.js full-stack — App Router, RSC, Server Actions, SEO, AI SDK | 24 | engineering |
+| `backend-nextjs` | Next.js full-stack — App Router, RSC, Server Actions, SEO, AI SDK | 25 | engineering |
 
 ### Frontend & Design
 
 | Profile | Stack | Skills | Agents |
 |---------|-------|--------|--------|
-| `frontend-react-vite` | React + Vite + TypeScript | 17 | engineering |
+| `frontend-react-vite` | React + Vite + TypeScript | 18 | engineering |
 | `design` | Figma, UX review, design system, handoff | 10 | product |
 
 ### Mobile
@@ -304,7 +305,7 @@ It ships the in-editor skills that operate and extend the MCP (`unreal-mcp`, `cr
 | ClickUp | `/clickup` | `+clickup` |
 | Figma | `/figma`, `/figma-to-code`, `/figma-tokens` | `+design` |
 | Atlassian (Confluence) | `/confluence-expert`, `/atlassian-templates` | `+agile` |
-| TestRail + BrowserStack | `/playwright-pro` (ships its own `.mcp.json`) | `+testing` |
+| TestRail + BrowserStack | `/playwright-pro` (ships its own `.mcp.json`) | `+testing`, `frontend-react-vite`, `backend-nextjs` |
 
 `/jira-tickets` is the exception: it talks to the Jira REST API v3 over `curl`, not MCP.
 

package/dist/cli.js

@@ -2940,6 +2940,13 @@ function syncUnhashedFiles(root, claudeDir, merged, dryRun) {
           dirty = true;
         }
       }
+      const allow = settings.permissions?.allow;
+      if (Array.isArray(allow) && allow.includes("Bash(gh *)")) {
+        const narrowed = merged.permissions.allow.filter((r) => r.startsWith("Bash(gh ") && !allow.includes(r));
+        settings.permissions.allow = allow.flatMap((r) => r === "Bash(gh *)" ? narrowed : [r]);
+        changed.push("settings.json (Bash(gh *) narrowed)");
+        dirty = true;
+      }
       if (dirty && !dryRun) {
         fs15.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}
 `, "utf-8");
@@ -3368,12 +3375,296 @@ function removeHookFromSettings() {
   writeSettings(settings);
 }
 
-// src/update-check.ts
+// src/commands/doctor.ts
 import fs18 from "fs";
 import path21 from "path";
+import { spawnSync as spawnSync2 } from "child_process";
 import chalk11 from "chalk";
+var DANGEROUS_ALLOWS = /* @__PURE__ */ new Set([
+  "Bash",
+  "Bash(*)",
+  "Bash(gh *)",
+  "Bash(git *)",
+  "Bash(git push*)",
+  "Bash(git reset*)",
+  "Bash(rm *)",
+  "Bash(sudo *)",
+  "Bash(bash *)",
+  "Bash(sh *)",
+  "Bash(eval *)"
+]);
+var SECRET_PATTERNS = [
+  ["Anthropic key", /sk-ant-[A-Za-z0-9_-]{20,}/],
+  ["OpenAI key", /sk-(?:proj-)?[A-Za-z0-9]{32,}/],
+  ["GitHub token", /\b(?:gh[pousr]_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{22,})/],
+  ["Slack token", /\bxox[abpr]-[A-Za-z0-9-]{10,}/],
+  ["AWS access key", /\bAKIA[0-9A-Z]{16}\b/],
+  ["Google API key", /\bAIza[0-9A-Za-z_-]{35}/],
+  ["Stripe live key", /\b[sr]k_live_[0-9A-Za-z]{20,}/],
+  ["private key", /-----BEGIN [A-Z ]*PRIVATE KEY-----/]
+];
+var SECRET_KEY = /(?:TOKEN|SECRET|PASSWORD|PASSWD|API_?KEY|ACCESS_?KEY)$/i;
+var defaultProbes = {
+  findBash,
+  checkSyntax(bash, file) {
+    const result = spawnSync2(bash, ["-n", file.replace(/\\/g, "/")], { encoding: "utf-8" });
+    if (result.error) return result.error.message;
+    return result.status === 0 ? null : (result.stderr || "syntax error").trim();
+  },
+  findPython() {
+    for (const py of ["python3", "python", "py"]) {
+      const result = spawnSync2(py, ["--version"], { encoding: "utf-8" });
+      if (!result.error && result.status === 0) return py;
+    }
+    return null;
+  }
+};
+function findBash() {
+  if (process.platform !== "win32") {
+    return spawnSync2("bash", ["--version"]).error ? null : "bash";
+  }
+  const override = process.env.CLAUDE_CODE_GIT_BASH_PATH;
+  if (override && fs18.existsSync(override)) return override;
+  const systemRoot = (process.env.SystemRoot ?? "C:\\Windows").toLowerCase();
+  for (const dir of (process.env.PATH ?? "").split(path21.delimiter)) {
+    const lower = dir.toLowerCase();
+    if (!dir || lower.startsWith(systemRoot) || lower.includes("windowsapps")) continue;
+    const candidate = path21.join(dir, "bash.exe");
+    if (fs18.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+function readJson(file) {
+  try {
+    return { value: JSON.parse(fs18.readFileSync(file, "utf-8")) };
+  } catch (error) {
+    return { error: error.message };
+  }
+}
+function commandsOf(settings) {
+  const commands = [];
+  const hooks = settings.hooks ?? {};
+  for (const groups of Object.values(hooks)) {
+    for (const group of Array.isArray(groups) ? groups : []) {
+      for (const entry of group.hooks ?? []) {
+        if (typeof entry.command === "string") commands.push(entry.command);
+      }
+    }
+  }
+  const status = settings.statusLine;
+  if (typeof status?.command === "string") commands.push(status.command);
+  return commands;
+}
+function scriptsOf(command) {
+  const scripts = [...command.matchAll(/\.claude\/((?:hooks\/)?[\w.-]+\.(?:sh|py))/g)].map((m) => m[1]);
+  const python = command.match(/run-py\.sh"?\s+([\w.-]+\.py)/);
+  if (python) scripts.push(`hooks/${python[1]}`);
+  return scripts;
+}
+function checkSettings(claudeDir, cli) {
+  const file = path21.join(claudeDir, "settings.json");
+  if (!fs18.existsSync(file)) {
+    return {
+      check: { name: "settings.json", verdict: "fail", detail: "missing", fix: `Run \`${cli} update --here --force\`.` }
+    };
+  }
+  const { value, error } = readJson(file);
+  if (error || typeof value !== "object" || value === null || Array.isArray(value)) {
+    return {
+      check: {
+        name: "settings.json",
+        verdict: "fail",
+        detail: `not valid JSON: ${error ?? "not an object"}`,
+        fix: "Fix the syntax by hand, or restore it from .claude.bak/."
+      }
+    };
+  }
+  return { check: { name: "settings.json", verdict: "ok", detail: "valid JSON" }, settings: value };
+}
+function checkHooks(claudeDir, settings, probes, cli) {
+  const commands = commandsOf(settings);
+  const scripts = [...new Set(commands.flatMap(scriptsOf))];
+  const checks = [];
+  const missing = scripts.filter((s) => !fs18.existsSync(path21.join(claudeDir, s)));
+  checks.push(
+    missing.length ? {
+      name: "hook scripts",
+      verdict: "fail",
+      detail: `settings.json runs files that are not there: ${missing.join(", ")}`,
+      fix: `If Arcane ships them, \`${cli} update --here\` restores them; otherwise remove those hooks from settings.json.`
+    } : { name: "hook scripts", verdict: "ok", detail: `${scripts.length} scripts found` }
+  );
+  const relative = commands.filter((c) => /^bash \.claude\/hooks\//.test(c));
+  if (relative.length) {
+    checks.push({
+      name: "hook paths",
+      verdict: "warn",
+      detail: `${relative.length} hooks use a relative path, which fails inside a worktree`,
+      fix: `Run \`${cli} update --here\`: it rewrites them with $CLAUDE_PROJECT_DIR.`
+    });
+  }
+  const bash = probes.findBash();
+  if (!bash) {
+    checks.push({
+      name: "bash",
+      verdict: "fail",
+      detail: "not found: no hook can run",
+      fix: process.platform === "win32" ? "Install Git for Windows, or set CLAUDE_CODE_GIT_BASH_PATH." : "Install bash."
+    });
+    return checks;
+  }
+  const broken = scripts.filter((s) => s.endsWith(".sh") && !missing.includes(s)).map((s) => [s, probes.checkSyntax(bash, path21.join(claudeDir, s))]).filter(([, error]) => error);
+  checks.push(
+    broken.length ? {
+      name: "hook syntax",
+      verdict: "fail",
+      detail: broken.map(([s, error]) => `${s}: ${error}`).join("; "),
+      fix: `Run \`${cli} update --here --force\` to restore the shipped version.`
+    } : { name: "hook syntax", verdict: "ok", detail: `bash parses every script (${bash})` }
+  );
+  return checks;
+}
+function checkPython(probes) {
+  const python = probes.findPython();
+  return python ? { name: "python", verdict: "ok", detail: `${python} starts` } : {
+    name: "python",
+    verdict: "warn",
+    detail: "no working Python: the guard and the session watch do nothing",
+    fix: "Install Python 3.9+ and make sure `python --version` works in Git Bash."
+  };
+}
+function checkContent(claudeDir, manifest, cli) {
+  const missing = [
+    ...(manifest.installed_skills ?? []).filter((s) => !fs18.existsSync(path21.join(claudeDir, "skills", s, "SKILL.md"))).map((s) => `skill ${s}`),
+    ...(manifest.installed_rules ?? []).filter((r) => !fs18.existsSync(path21.join(claudeDir, "rules", `${r}.md`))).map((r) => `rule ${r}`)
+  ];
+  if (!missing.length) {
+    return { name: "installed content", verdict: "ok", detail: "every skill and rule in the manifest is on disk" };
+  }
+  const shown = missing.slice(0, 5).join(", ") + (missing.length > 5 ? ` and ${missing.length - 5} more` : "");
+  return {
+    name: "installed content",
+    verdict: "fail",
+    detail: `missing from disk: ${shown}`,
+    fix: `Run \`${cli} update --here\` to restore them.`
+  };
+}
+function checkPermissions(claudeDir, settings, cli) {
+  const found = [];
+  for (const [file, data] of [
+    ["settings.json", settings],
+    ["settings.local.json", readJson(path21.join(claudeDir, "settings.local.json")).value]
+  ]) {
+    const permissions = data?.permissions;
+    const allow = Array.isArray(permissions?.allow) ? permissions.allow : [];
+    for (const rule of allow) {
+      if (typeof rule === "string" && DANGEROUS_ALLOWS.has(rule.trim())) found.push(`${file}: ${rule}`);
+    }
+    if (permissions?.defaultMode === "bypassPermissions") found.push(`${file}: defaultMode bypassPermissions`);
+  }
+  return found.length ? {
+    name: "permissions",
+    verdict: "warn",
+    detail: `rules that skip every confirmation: ${found.join(", ")}`,
+    fix: found.some((f) => f.endsWith("Bash(gh *)")) ? `Run \`${cli} update --here\` to narrow the old \`Bash(gh *)\`; narrow any other by hand, unless you mean it.` : "Narrow them by hand (e.g. `Bash(npm test*)` instead of `Bash(*)`), unless you mean it."
+  } : { name: "permissions", verdict: "ok", detail: "no allow rule covers a whole tool or a destructive command" };
+}
+function* strings(value, key = "") {
+  if (typeof value === "string") yield [key, value];
+  else if (Array.isArray(value)) for (const item of value) yield* strings(item, key);
+  else if (value && typeof value === "object") {
+    for (const [k, v] of Object.entries(value)) yield* strings(v, k);
+  }
+}
+function secretsIn(value) {
+  const found = /* @__PURE__ */ new Set();
+  for (const [key, text] of strings(value)) {
+    for (const [label, pattern] of SECRET_PATTERNS) if (pattern.test(text)) found.add(label);
+    if (SECRET_KEY.test(key) && text.length >= 8 && !/\$\{?[A-Za-z_]/.test(text)) found.add(`literal ${key}`);
+  }
+  return [...found];
+}
+function checkSecrets(target, claudeDir) {
+  const committed = [];
+  const local = [];
+  for (const [file, bucket] of [
+    [path21.join(claudeDir, "settings.json"), committed],
+    [path21.join(target, ".mcp.json"), committed],
+    [path21.join(claudeDir, "settings.local.json"), local]
+  ]) {
+    const { value } = readJson(file);
+    for (const label of secretsIn(value)) bucket.push(`${path21.relative(target, file).replace(/\\/g, "/")} (${label})`);
+  }
+  if (committed.length) {
+    return {
+      name: "secrets",
+      verdict: "fail",
+      detail: `credentials in files that get committed: ${committed.join(", ")}`,
+      fix: "Move them to environment variables and reference them as ${VAR}; rotate any that were pushed."
+    };
+  }
+  if (local.length) {
+    return {
+      name: "secrets",
+      verdict: "warn",
+      detail: `credentials in settings.local.json: ${local.join(", ")}`,
+      fix: "It is not committed, but an environment variable keeps it out of backups and shares."
+    };
+  }
+  return { name: "secrets", verdict: "ok", detail: "no credentials found in settings or .mcp.json" };
+}
+function diagnose(target, probes = defaultProbes) {
+  const claudeDir = path21.join(target, ".claude");
+  const cli = cliInvocation();
+  const manifest = readManifest(target);
+  if (!manifest) {
+    return [
+      {
+        name: "installation",
+        verdict: "fail",
+        detail: "no .claude/arcane-manifest.json",
+        fix: `Run \`${cli} install <profile>\`.`
+      }
+    ];
+  }
+  const checks = [
+    { name: "installation", verdict: "ok", detail: `Arcane ${manifest.arcane_version}, ${manifest.profiles.join(" + ")}` }
+  ];
+  const { check, settings } = checkSettings(claudeDir, cli);
+  checks.push(check);
+  if (settings) checks.push(...checkHooks(claudeDir, settings, probes, cli));
+  checks.push(checkPython(probes), checkContent(claudeDir, manifest, cli));
+  if (settings) checks.push(checkPermissions(claudeDir, settings, cli));
+  checks.push(checkSecrets(target, claudeDir));
+  return checks;
+}
+var ICONS = { ok: chalk11.green("\u2713"), warn: chalk11.yellow("!"), fail: chalk11.red("\u2717") };
+async function doctorCommand(opts = {}) {
+  const target = path21.resolve(opts.target ?? process.cwd());
+  const checks = diagnose(target);
+  console.log(chalk11.bold(`
+=== Arcane Doctor: ${target} ===
+`));
+  for (const check of checks) {
+    console.log(`  ${ICONS[check.verdict]} ${chalk11.bold(check.name)}: ${check.detail}`);
+    if (check.fix && check.verdict !== "ok") console.log(chalk11.dim(`      fix: ${check.fix}`));
+  }
+  const fails = checks.filter((c) => c.verdict === "fail").length;
+  const warns = checks.filter((c) => c.verdict === "warn").length;
+  console.log(
+    `
+  ${fails ? chalk11.red(`${fails} failed`) : chalk11.green("nothing failed")}${warns ? chalk11.yellow(`, ${warns} warnings`) : ""}
+`
+  );
+  if (fails) process.exitCode = 1;
+}
+
+// src/update-check.ts
+import fs19 from "fs";
+import path22 from "path";
+import chalk12 from "chalk";
 function checkFile() {
-  return path21.join(arcaneHome(), "last-check.json");
+  return path22.join(arcaneHome(), "last-check.json");
 }
 var CHECK_INTERVAL_MS = 4 * 60 * 60 * 1e3;
 var GITHUB_OWNER2 = "SebastianLuser";
@@ -3443,23 +3734,23 @@ async function checkForUpdates(opts = {}) {
 function printUpdateNotice(result) {
   if (result.cli_update_available) {
     console.log(
-      chalk11.yellow(
+      chalk12.yellow(
         `
   Arcane CLI update: ${result.cli_version} \u2192 ${result.latest_cli_version}`
       )
     );
     const how = isGloballyInstalled() ? `  Run: npm install -g ${PACKAGE_NAME3}@latest` : `  You are on an older CLI. Latest: ${PACKAGE_NAME3}@${result.latest_cli_version}`;
-    console.log(chalk11.dim(how));
+    console.log(chalk12.dim(how));
   }
   if (result.content_update_available ?? true) {
     console.log(
-      chalk11.yellow(
+      chalk12.yellow(
         `
   Arcane content update: ${result.local_version} \u2192 ${result.remote_sha}`
       )
     );
     console.log(
-      chalk11.dim(`  Run: ${cliInvocation()} update (--dry-run to preview)`)
+      chalk12.dim(`  Run: ${cliInvocation()} update (--dry-run to preview)`)
     );
   }
   console.log("");
@@ -3502,8 +3793,8 @@ async function getLatestNpmVersion() {
 function readCachedCheck() {
   try {
     const file = checkFile();
-    if (!fs18.existsSync(file)) return null;
-    return JSON.parse(fs18.readFileSync(file, "utf-8"));
+    if (!fs19.existsSync(file)) return null;
+    return JSON.parse(fs19.readFileSync(file, "utf-8"));
   } catch {
     return null;
   }
@@ -3511,11 +3802,11 @@ function readCachedCheck() {
 function writeCachedCheck(result) {
   try {
     const file = checkFile();
-    const dir = path21.dirname(file);
-    if (!fs18.existsSync(dir)) {
-      fs18.mkdirSync(dir, { recursive: true });
+    const dir = path22.dirname(file);
+    if (!fs19.existsSync(dir)) {
+      fs19.mkdirSync(dir, { recursive: true });
     }
-    fs18.writeFileSync(file, JSON.stringify(result, null, 2) + "\n");
+    fs19.writeFileSync(file, JSON.stringify(result, null, 2) + "\n");
   } catch {
   }
 }
@@ -3552,6 +3843,9 @@ program.command("list").description("List all available profiles and skills.").a
 program.command("status").description("Show current Arcane installation status.").action(async () => {
   await statusCommand();
 });
+program.command("doctor").description("Check that this project's Arcane install works: hooks, settings, content, permissions, secrets.").option("-t, --target <dir>", "Project directory", process.cwd()).action(async (opts) => {
+  await doctorCommand(opts);
+});
 program.command("update").description(
   "Update everything: the global npm package + all registered Arcane installations."
 ).option("-q, --quiet", "Quiet mode for hook usage").option("-n, --dry-run", "Show what would change without applying").option("-f, --force", "Overwrite even locally modified files").option("--here", "Update only the current repo (legacy per-repo behavior)").option("--no-self-update", "Skip updating the global npm package").option("--source <source>", "Content source: auto, github, or bundled", "auto").action(async (opts) => {

package/docs/USER-GUIDE.md

@@ -141,6 +141,23 @@ npx claude-code-arcane status
 
 Shows installed profiles, skill count, rules, agents, installation date, and worktree info.
 
+### `npx claude-code-arcane doctor` — Check that the install works
+
+```bash
+npx claude-code-arcane doctor
+npx claude-code-arcane doctor --target ../other-project
+```
+
+Read-only. Each check prints ✓, `!` (warning) or ✗ (failure) with a fix:
+
+- **Hooks:** every script `settings.json` runs exists and parses with bash; hooks still wired with a relative path, which fails inside a worktree.
+- **Settings:** `settings.json` is valid JSON.
+- **Content:** every skill and rule in the manifest is on disk.
+- **Python:** one starts, since the guard and the session watch need it.
+- **Permissions and secrets:** allow rules that skip every confirmation (`Bash(*)`, `Bash(gh *)`, `bypassPermissions`), and credentials in `settings.json`, `settings.local.json` or `.mcp.json`.
+
+It exits with code 1 when a check fails.
+
 ### `npx claude-code-arcane update` — Check for updates
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-arcane",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "description": "Skills, agents, hooks and rules for Claude Code — installable via npx claude-code-arcane",
   "type": "module",
   "bin": {

package/profiles/backend-nextjs.yaml

@@ -23,6 +23,7 @@ skills:
   # Frontend quality
   - accessibility
   - performance
+  - playwright-pro
   # Ops & quality
   - testing
   - deps-audit

package/profiles/frontend-react-vite.yaml

@@ -20,6 +20,7 @@ skills:
   - file-uploads
   - frontend-dev
   - csp-headers
+  - playwright-pro
 
 rules:
   universal:

package/profiles/frontend.yaml

@@ -22,6 +22,7 @@ skills:
   - file-uploads
   - frontend-dev
   - csp-headers
+  - playwright-pro
 
 rules:
   universal:

package/rules/frontend-code.md

@@ -55,6 +55,6 @@ paths:
   2. Screenshots at 320, 768, 1024 and 1440 px wide, in both themes if the app has a dark mode.
   3. Walk the flow you changed: clicks, forms, navigation.
   4. Keyboard: every control in the flow is reachable with Tab, usable with Enter or Space, and shows a visible focus.
-  5. Keep the screenshots and show them as evidence.
-- If Playwright is not installed, propose installing it once (`npm i -D @playwright/test`, then `npx playwright install chromium`). If the user declines, close the task with "visual result not verified".
+  5. Save the screenshots to files and show them as evidence; the goal review gets their paths.
+- If Playwright is not installed, propose setting it up once with `/playwright-pro init` (or `npm i -D @playwright/test`, then `npx playwright install chromium`). If the user declines, close the task with "visual result not verified".
 - In React Native or Flutter Playwright does not apply: say what was not verified visually.

package/rules/implementation-workflow.md

@@ -34,9 +34,9 @@ Use AskUserQuestion exactly like this:
 
 ## After selection
 
-- **Plan + Goal:** First define the verifiable session goal with validation criteria. Then EnterPlanMode and design the implementation plan linked to the goal. Plan includes explicit stop conditions (goal met, blocker, scope creep). After approval, create tasks and execute. After each significant step, check progress against the goal. When goal is met, STOP and run validation.
+- **Plan + Goal:** First define the verifiable session goal with validation criteria. Then EnterPlanMode and design the implementation plan linked to the goal. Plan includes explicit stop conditions (goal met, blocker, scope creep). After approval, create tasks and execute. After each significant step, check progress against the goal. When goal is met, STOP and run the goal review below.
 - **Action Plan:** Use EnterPlanMode, design the approach, get approval, create tasks, then implement step by step. No formal goal — implement until the plan is done.
-- **Goal-driven:** Help the user define a verifiable goal statement and 2-4 checkpoints, create tasks, implement toward each checkpoint. No formal plan.
+- **Goal-driven:** Help the user define a verifiable goal statement and 2-4 checkpoints, create tasks, implement toward each checkpoint. No formal plan. When the last checkpoint is met, run the goal review below.
 - **Directo:** Proceed immediately without ceremony.
 
 ## Progress file
@@ -63,6 +63,26 @@ Not verified: <what has not been checked yet>
 
 Directo and Action Plan tasks do not need it.
 
+## Goal review
+
+In **Plan + Goal** and **Goal-driven** mode, whoever did the work does not decide it is done. When the goal looks met, start one `general-purpose` subagent with a clean context. Its prompt carries only:
+
+- the goal and the criteria from `active.md`;
+- the diff against the base branch, untracked files included;
+- how to verify: test, build and type-check commands, and how to start the app;
+- if the task changed a web UI: the paths of the Playwright screenshots, or that the user declined Playwright;
+- the instructions below, verbatim.
+
+Never pass your reasoning or a summary of the conversation: the reviewer judges the work, not the story behind it.
+
+> You are reviewing finished work against its goal. Do not trust any reported result: run every verification yourself. Check each criterion against the code and your own runs. If the diff touches authentication, user input, database queries, file system paths, external APIs, cryptography or payments, also check that input is validated at the boundary, queries are parameterized, no secret is in code or logs, every new path checks authorization, and errors leak no internals. If the task changed a web UI, there are no Playwright screenshots and you cannot produce them, the verdict is FAIL, unless the user declined Playwright: then note "visual result not verified". Answer with `PASS` or `FAIL` on the first line, then one line per criterion with its evidence (the command and its result, or `file:line`), then what is missing.
+
+Then:
+
+1. Show the user the reviewer's verdict as it came, before your own comments.
+2. **FAIL:** fix what it found and review again with a new subagent. After a second FAIL, stop and bring both verdicts to the user.
+3. **PASS:** close `active.md` with the verdict.
+
 ## Before writing new code
 
 In every mode, search in this order and take the first option that fully works: