@haposoft/cafekit 0.18.0 → 0.18.2

package/bin/phases/codex-hooks.js

@@ -17,21 +17,81 @@ const { PLATFORMS } = require('../lib/context');
 
 const CODEX_SRC = path.join(__dirname, '../../src/codex');
 const HOOK_COMMAND_TEMPLATE = /^node "\.codex\/hooks\/([a-z0-9-]+\.cjs)"$/;
-// Exact shapes earlier installers wrote, kept only to recognize and upgrade them. Before
-// 0.16.2 the path came from Git; 0.16.2 fixed the path but still resolved `node` through
-// PATH. Matching the whole command keeps a hook the user wrote from ever being rewritten.
-const LEGACY_POSIX_COMMANDS = [
-  /^node "\$\(git rev-parse --show-toplevel\)\/\.codex\/hooks\/([a-z0-9-]+\.cjs)"$/,
-  /^node '(?:[^']|'\\'')*[/\\]hooks[/\\]([a-z0-9-]+\.cjs)'$/,
-];
-
-function legacyPosixScript(command) {
-  if (typeof command !== 'string') return null;
-  for (const pattern of LEGACY_POSIX_COMMANDS) {
-    const match = command.match(pattern);
-    if (match) return match[1];
+const LEGACY_GIT_COMMAND = /^node "\$\(git rev-parse --show-toplevel\)\/\.codex\/hooks\/([a-z0-9-]+\.cjs)"$/;
+const SHELL_QUOTED = "'(?:[^']|'\\\\'')*'";
+const POSIX_COMMAND = new RegExp(`^(?:PATH="\\$PATH"(?::${SHELL_QUOTED})+ )?node (${SHELL_QUOTED})$`);
+const WINDOWS_LAUNCHER = 'node -e "process.argv[1]=Buffer.from(process.argv[1],\'base64url\').toString(\'utf8\');require(\'module\').runMain()" ';
+
+// Former template values from the hooks.json history. Custom expressions never
+// establish ownership, even when every handler belongs to CafeKit.
+const FORMER_MATCHERS = {
+  PreToolUse: new Set([
+    'Bash|apply_patch|Edit|Write|Read|Glob|Grep|mcp__.*',
+    'Bash|exec_command|apply_patch|Edit|Write|Read|Glob|Grep|mcp__.*|shell',
+  ]),
+  PostToolUse: new Set([
+    'Agent|spawn_agent|update_plan|task|Task|TodoWrite',
+    'apply_patch|Edit|Write|MultiEdit',
+  ]),
+};
+
+function refreshManagedMatchers(config, template, ctx) {
+  let updated = 0;
+  const hooks = { ...(config.hooks || {}) };
+  for (const [event, former] of Object.entries(FORMER_MATCHERS)) {
+    if (!Array.isArray(hooks[event])) continue;
+    hooks[event] = hooks[event].map(group => {
+      const handlers = Array.isArray(group?.hooks) ? group.hooks : [];
+      const scripts = handlers.map(managedHandlerScript);
+      if (!scripts.some(Boolean)) return group;
+      const candidates = handlers.length && scripts.every(Boolean)
+        ? (template.hooks[event] || []).filter(target => {
+          const wanted = target.hooks.map(managedHandlerScript);
+          return scripts.every(script => wanted.includes(script));
+        }) : [];
+      const target = candidates.length === 1 ? candidates[0] : null;
+      if (target && (group.matcher || '') === (target.matcher || '')) return group;
+      if (target && former.has(group.matcher)) {
+        updated += 1;
+        ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Codex hooks: ${event} matcher updated`);
+        return { ...group, matcher: target.matcher };
+      }
+      ctx.ui.warn(`Codex hooks: ${event} matcher preserved; custom, mixed, or ambiguous group. Review it manually.`);
+      return group;
+    });
   }
-  return null;
+  return { config: { ...config, hooks }, updated };
+}
+
+// A basename alone cannot prove ownership: users may also run tools/hooks/session.cjs.
+// Only known source scripts at the native runtime path and an exact emitted launcher
+// shape may be rebound or count as already registered.
+const MANAGED_SCRIPTS = new Set(fs.readdirSync(path.join(CODEX_SRC, 'hooks')).filter((name) => /^[a-z0-9-]+\.cjs$/.test(name)));
+
+function nativeScript(target) {
+  if (!path.posix.isAbsolute(target) && !path.win32.isAbsolute(target)) return null;
+  const match = target.match(/[/\\]\.codex[/\\]hooks[/\\]([a-z0-9-]+\.cjs)$/);
+  return match && MANAGED_SCRIPTS.has(match[1]) ? match[1] : null;
+}
+
+function managedCommandScript(command) {
+  if (typeof command !== 'string') return null;
+  const template = command.match(HOOK_COMMAND_TEMPLATE) || command.match(LEGACY_GIT_COMMAND);
+  if (template) return MANAGED_SCRIPTS.has(template[1]) ? template[1] : null;
+  const posix = command.match(POSIX_COMMAND);
+  if (posix) return nativeScript(posix[1].slice(1, -1).replace(/'\\''/g, "'"));
+  if (!command.startsWith(WINDOWS_LAUNCHER)) return null;
+  const encoded = command.slice(WINDOWS_LAUNCHER.length);
+  if (!/^[A-Za-z0-9_-]+$/.test(encoded)) return null;
+  const target = Buffer.from(encoded, 'base64url').toString('utf8');
+  return Buffer.from(target, 'utf8').toString('base64url') === encoded ? nativeScript(target) : null;
+}
+
+function managedHandlerScript(handler) {
+  if (handler?.type !== 'command') return null;
+  const fields = ['command', 'commandWindows'].filter((field) => handler[field] !== undefined);
+  const scripts = fields.map((field) => managedCommandScript(handler[field]));
+  return scripts.length > 0 && scripts.every((script) => script && script === scripts[0]) ? scripts[0] : null;
 }
 
 /** The hook script a command runs, which is stable across installs and platforms. */
@@ -57,8 +117,8 @@ function hookPathFor(script, projectRoot) {
  * nothing outside a repository and the *outer* root for a project nested inside one. Both
  * cases produced a path that does not exist, so Codex started every hook, every hook died,
  * and the gates were silently absent. The path is known at install time, so it is written
- * directly. The literal `/hooks/<script>.cjs` segment must survive, because hookScript()
- * reads it as the identity that lets a reinstall recognize CafeKit's own entries.
+ * directly. The literal `.codex/hooks/<script>.cjs` path and emitted launcher shape
+ * let managedHandlerScript() recognize CafeKit's own entries on a reinstall.
  */
 /**
  * Directories to fall back on when PATH carries no `node`.
@@ -88,7 +148,7 @@ function posixHookCommand(script, projectRoot) {
  */
 function windowsHookCommand(script, projectRoot) {
   const encoded = Buffer.from(hookPathFor(script, projectRoot), 'utf8').toString('base64url');
-  return 'node -e "process.argv[1]=Buffer.from(process.argv[1],\'base64url\').toString(\'utf8\');require(\'module\').runMain()" ' + encoded;
+  return WINDOWS_LAUNCHER + encoded;
 }
 
 /** Rewrite a managed template handler into absolute launchers for both platforms. */
@@ -104,10 +164,9 @@ function materializeHookCommands(handler, projectRoot) {
 }
 
 /**
- * Repair launchers an older installer wrote. A reinstall treats an already-registered
- * script as the user's placement and leaves it alone, so without this pass every existing
- * project would keep its broken git-derived command forever. Only the exact byte pattern
- * CafeKit itself emitted is rewritten; anything else stays untouched.
+ * Rebind recognized CafeKit launchers after an upgrade or a project move. Registration
+ * preserves the user's event/matcher placement; only emitted command shapes change,
+ * and a custom field for another platform remains untouched.
  */
 function repairLegacyCodexLaunchers(config, projectRoot) {
   if (!config.hooks) return { config, repaired: 0 };
@@ -120,13 +179,13 @@ function repairLegacyCodexLaunchers(config, projectRoot) {
       return {
         ...group,
         hooks: group.hooks.map((handler) => {
-          const legacy = legacyPosixScript(handler?.command);
-          const template = typeof handler?.commandWindows === 'string'
-            && handler.commandWindows.match(HOOK_COMMAND_TEMPLATE);
-          if (!legacy && !template) return handler;
+          if (handler?.type !== 'command') return handler;
           const next = { ...handler };
-          if (legacy) next.command = posixHookCommand(legacy, projectRoot);
-          if (template) next.commandWindows = windowsHookCommand(template[1], projectRoot);
+          for (const [field, build] of [['command', posixHookCommand], ['commandWindows', windowsHookCommand]]) {
+            const script = managedCommandScript(handler[field]);
+            if (script) next[field] = build(script, projectRoot);
+          }
+          if (next.command === handler.command && next.commandWindows === handler.commandWindows) return handler;
           repaired += 1;
           return next;
         }),
@@ -139,7 +198,7 @@ function repairLegacyCodexLaunchers(config, projectRoot) {
 /** Drop CafeKit hooks the manifest has retired, leaving foreign entries untouched. */
 function pruneObsoleteCodexHooks(config, ctx) {
   const obsolete = ctx.manifest?.obsolete?.settingsHookCommandSubstrings || [];
-  if (!config.hooks || obsolete.length === 0) return { config, removed: 0 };
+  if (!config.hooks) return { config, removed: 0 };
 
   let removed = 0;
   const pruned = {};
@@ -150,7 +209,8 @@ function pruneObsoleteCodexHooks(config, ctx) {
       if (!Array.isArray(group?.hooks)) { keptGroups.push(group); continue; }
       const keptHooks = group.hooks.filter((handler) => {
         const command = handler?.command || '';
-        const isObsolete = obsolete.some((substring) => command.includes(substring));
+        const isObsolete = obsolete.some((substring) => command.includes(substring))
+          || (eventName === 'SessionStart' && managedHandlerScript(handler) === 'docs-sync.cjs');
         if (isObsolete) removed += 1;
         return !isObsolete;
       });
@@ -196,12 +256,15 @@ function mergeCodexHooks(ctx, platformKey, projectRoot = process.cwd()) {
     ctx.results.updated++;
   }
 
-  const { config: base, repaired } = repairLegacyCodexLaunchers(pruned, projectRoot);
+  const { config: rebound, repaired } = repairLegacyCodexLaunchers(pruned, projectRoot);
   if (repaired > 0) {
-    ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Codex hooks: rebound ${repaired} launcher(s) written by an older installer`);
+    ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Codex hooks: rebound ${repaired} launcher(s) to the current project`);
     ctx.results.updated++;
   }
 
+  const { config: base, updated: matcherUpdates } = refreshManagedMatchers(rebound, managed, ctx);
+  ctx.results.updated += matcherUpdates;
+
   const merged = { ...base };
   if (typeof managed.description === 'string' && typeof merged.description !== 'string') {
     merged.description = managed.description;
@@ -215,7 +278,7 @@ function mergeCodexHooks(ctx, platformKey, projectRoot = process.cwd()) {
     // it. Matching on the script rather than the whole command survives the path
     // differences between installs and platforms.
     const registered = new Set(
-      groups.flatMap((group) => (group?.hooks || []).map((handler) => hookScript(handler?.command))).filter(Boolean),
+      groups.flatMap((group) => (Array.isArray(group?.hooks) ? group.hooks : []).map(managedHandlerScript)).filter(Boolean),
     );
 
     for (const managedGroup of managedGroups) {
@@ -242,7 +305,7 @@ function mergeCodexHooks(ctx, platformKey, projectRoot = process.cwd()) {
     merged.hooks[eventName] = groups;
   }
 
-  if (added === 0 && removed === 0) {
+  if (added === 0 && removed === 0 && matcherUpdates === 0) {
     ctx.ui.detail(`  → ${ctx.dryRun ? '[dry-run] ' : ''}Codex hooks: already registered`);
     ctx.results.unchanged++;
   }

package/bin/phases/codex-runtime.js

@@ -5,7 +5,8 @@ const path = require('path');
 const { PLATFORMS } = require('../lib/context');
 const { writeManagedFile, copyManagedTree } = require('../lib/managed-writer');
 const { report, treeAction } = require('./report');
-const { copyRulesDirectory, copyOutputStylesDirectory } = require('./claude-runtime');
+const { isGeneratedArtifact } = require('../lib/copy-utils');
+const { copyRulesDirectory, copyOutputStylesDirectory, removeObsoleteRuntimeFiles } = require('./claude-runtime');
 const {
   managedRange,
   upsertManagedCodexBlock
@@ -23,27 +24,9 @@ const CODEX_OWN_RUNTIME = [
   ['runtime.json', 'runtime.json']
 ];
 
-/**
- * Delete hooks the manifest marks obsolete. Codex tracker keys are project-relative
- * (`.codex/hooks/…`), so the record is pruned through keyFor, and always: a record whose
- * file is already gone must still leave the manifest.
- */
+/** Use the shared ownership and symlink checks for Codex runtime cleanup. */
 function removeObsoleteCodexHooks(ctx, platformKey) {
-  const platform = PLATFORMS[platformKey];
-  const tracker = ctx.trackers && ctx.trackers[platformKey];
-  const obsoleteHooks = (ctx.manifest?.obsolete?.runtimeFiles || []).filter((rel) => rel.startsWith('hooks/'));
-  for (const rel of obsoleteHooks) {
-    const target = path.join(platform.folder, rel);
-    const exists = fs.existsSync(target);
-    if (!ctx.dryRun) {
-      if (exists) fs.rmSync(target, { force: true, recursive: fs.statSync(target).isDirectory() });
-      if (tracker) tracker.prune(tracker.keyFor(target));
-    }
-    if (exists) {
-      ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed obsolete Codex runtime: ${rel}`);
-      ctx.results.updated++;
-    }
-  }
+  removeObsoleteRuntimeFiles(ctx, platformKey);
 }
 
 function writeSourceFile(ctx, platformKey, src, dest, label) {
@@ -79,13 +62,32 @@ function installRuntimeFiles(ctx, platformKey) {
 
   mergeCodexHooks(ctx, platformKey);
 
-  const agg = copyManagedTree({
-    src: path.join(CODEX_SRC, 'hooks'),
-    dest: path.join(platform.folder, 'hooks'),
-    platformFolder: platform.folder,
-    ctx,
-    tracker: ctx.trackers[platformKey]
+  const hooksSource = path.join(CODEX_SRC, 'hooks');
+  const libsSource = path.join(hooksSource, 'lib');
+  const shimPattern = /^(?:['"]use strict['"];?\s*)?module\.exports\s*=\s*require\(['"]\.\.\/\.\.\/\.\.\/claude\/hooks\/lib\/([^'"/]+)['"]\);?\s*$/;
+  const sharedLibraries = fs.readdirSync(libsSource).filter(name => {
+    const file = path.join(libsSource, name);
+    if (!fs.lstatSync(file).isFile()) return false;
+    const match = fs.readFileSync(file, 'utf8').match(shimPattern);
+    return match && match[1] === name;
   });
+  const agg = { created: 0, updated: 0, unchanged: 0, preserved: 0, missing: 0 };
+  const copyHookEntry = relative => {
+    if (isGeneratedArtifact(path.basename(relative))) return;
+    const child = copyManagedTree({
+      src: path.join(hooksSource, relative),
+      dest: path.join(platform.folder, 'hooks', relative),
+      sourceRoot: hooksSource,
+      platformFolder: platform.folder, ctx, tracker: ctx.trackers[platformKey]
+    });
+    for (const key of Object.keys(agg)) agg[key] += child[key];
+  };
+  for (const name of fs.readdirSync(hooksSource)) {
+    if (name !== 'lib') copyHookEntry(name);
+    else for (const lib of fs.readdirSync(libsSource)) {
+      if (!sharedLibraries.includes(lib)) copyHookEntry(path.join('lib', lib));
+    }
+  }
   report(ctx, treeAction(agg), 'Codex native hooks');
   removeObsoleteCodexHooks(ctx, platformKey);
   // Keep one canonical command analyzer in the Claude source tree, then
@@ -99,27 +101,21 @@ function installRuntimeFiles(ctx, platformKey) {
     path.join(platform.folder, 'runtime.schema.json'),
     'Codex runtime schema'
   );
-  writeSourceFile(
-    ctx,
-    platformKey,
-    path.join(SRC, 'claude', 'hooks', 'lib', 'privacy-command-analysis.cjs'),
-    path.join(platform.folder, 'hooks', 'lib', 'privacy-command-analysis.cjs'),
-    'Codex privacy command analyzer'
-  );
-  writeSourceFile(
-    ctx,
-    platformKey,
-    path.join(SRC, 'claude', 'hooks', 'lib', 'secret-keywords.cjs'),
-    path.join(platform.folder, 'hooks', 'lib', 'secret-keywords.cjs'),
-    'Codex secret keyword matcher'
-  );
-  writeSourceFile(
-    ctx,
-    platformKey,
-    path.join(SRC, 'claude', 'hooks', 'lib', 'runtime-path-safety.cjs'),
-    path.join(platform.folder, 'hooks', 'lib', 'runtime-path-safety.cjs'),
-    'Codex runtime path safety'
-  );
+  const helperLabels = {
+    'privacy-command-analysis.cjs': 'Codex privacy command analyzer',
+    'privacy-paths.cjs': 'Codex privacy path analyzer',
+    'secret-keywords.cjs': 'Codex secret keyword matcher',
+    'runtime-path-safety.cjs': 'Codex runtime path safety',
+    'inspect-paths.cjs': 'Codex inspection path analyzer',
+    'spec-touch.cjs': 'Codex spec touch helpers',
+    'update-check.cjs': 'Codex update check'
+  };
+  for (const name of sharedLibraries) {
+    writeSourceFile(ctx, platformKey,
+      path.join(SRC, 'claude', 'hooks', 'lib', name),
+      path.join(platform.folder, 'hooks', 'lib', name),
+      helperLabels[name] || `Codex hook helper: ${name}`);
+  }
 }
 
 function installNativeRuleOverrides(ctx, platformKey) {
@@ -167,7 +163,7 @@ function installManagedAgentsMd(ctx) {
 function installCodexRuntime(ctx, platformKey) {
   if (platformKey !== 'codex') return ctx;
   installRuntimeFiles(ctx, platformKey);
-  copyRulesDirectory(ctx, platformKey);
+  copyRulesDirectory(ctx, platformKey, new Set(fs.readdirSync(path.join(CODEX_SRC, 'rules'))));
   copyOutputStylesDirectory(ctx, platformKey);
   installNativeRuleOverrides(ctx, platformKey);
   installManagedAgentsMd(ctx);

package/bin/phases/copy-payload.js

@@ -94,37 +94,20 @@ function copyPlatformFiles(ctx, platformKey) {
       report(ctx, treeAction(agg), 'Skill: specs');
     }
 
-    // Keep spec templates in sync (Claude command runtime reads these).
+    // The specs skill tree above carries its templates; remove the ones retired
+    // with the spec.json planning flow from earlier installs.
     if (platformKey === 'claude' || platformKey === 'codex') {
-      const legacyInitTemplate = path.join(platform.skillsDir, 'specs', 'templates', 'init.json');
-      if (platformKey === 'claude' && fs.existsSync(legacyInitTemplate)) {
-        if (!ctx.dryRun) fs.rmSync(legacyInitTemplate, { force: true });
-        ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed legacy template: ${legacyInitTemplate}`);
+      const retiredTemplates = ['init.json', 'spec-state.json', 'requirements-init.md', 'requirements.md', 'design.md', 'task.md'];
+      for (const fileName of retiredTemplates) {
+        const retired = path.join(platform.skillsDir, 'specs', 'templates', fileName);
+        if (!fs.existsSync(retired)) continue;
+        if (!ctx.dryRun) {
+          fs.rmSync(retired, { force: true });
+          if (tracker) tracker.prune(tracker.keyFor(retired));
+        }
+        ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed legacy template: ${retired}`);
         ctx.results.updated++;
       }
-
-      const specTemplates = [
-        'spec-state.json',
-        'requirements-init.md',
-        'requirements.md',
-        'design.md',
-        'research.md',
-        'task.md'
-      ];
-
-      specTemplates.forEach((fileName) => {
-        const src = path.join(specSkillSource, 'templates', fileName);
-        const dest = path.join(platform.skillsDir, 'specs', 'templates', fileName);
-        const { action } = writeManagedFile({
-          src,
-          dest,
-          platformFolder,
-          ctx,
-          tracker,
-          transform: bodyTransform
-        });
-        report(ctx, action, `template: ${fileName}`);
-      });
     }
 
     // Core skills plus the optional document bundle selected for this runtime.

package/bin/phases/omp-runtime.js

@@ -129,16 +129,19 @@ function installBridge(ctx, platformKey) {
 }
 
 /**
- * Delete hooks the manifest marks obsolete. Mirrors removeObsoleteClaudeRuntimeFiles, but the
+ * Delete hooks, scripts and skill files the manifest marks obsolete. Mirrors removeObsoleteClaudeRuntimeFiles, but the
  * omp tracker records keys relative to the project root (`.omp/hooks/…`), so the record is
  * pruned through keyFor rather than by the bare `hooks/…` path.
  */
 function removeObsoleteOmpHooks(ctx, platformKey) {
   const platform = PLATFORMS[platformKey];
   const tracker = ctx.trackers && ctx.trackers[platformKey];
-  const obsoleteHooks = (ctx.manifest?.obsolete?.runtimeFiles || []).filter((rel) => rel.startsWith('hooks/'));
+  const obsoleteHooks = (ctx.manifest?.obsolete?.runtimeFiles || []).filter((rel) => rel.startsWith('hooks/') || rel.startsWith('scripts/') || rel.startsWith('skills/'));
   for (const rel of obsoleteHooks) {
-    const target = path.join(platform.folder, rel);
+    // Skill files live in the shared skills directory, not under the runtime folder.
+    const target = rel.startsWith('skills/')
+      ? path.join(platform.skillsDir, rel.slice('skills/'.length))
+      : path.join(platform.folder, rel);
     if (!fs.existsSync(target)) continue;
     if (!ctx.dryRun) {
       fs.rmSync(target, { force: true, recursive: fs.statSync(target).isDirectory() });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "description": "Native spec-driven workflows for Claude Code and Codex CLI. Bundles CafeKit skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",
@@ -12,8 +12,7 @@
     "test": "node scripts/run-skill-self-tests.mjs",
     "test:package": "node --test bin/__tests__/package-inventory.test.js",
     "test:secrets": "node --test bin/__tests__/secret-scanner.test.js",
-    "test:policy": "node --test bin/__tests__/develop-contract.test.js",
-    "release:freeze": "node scripts/benchmark-workflow.mjs freeze"
+    "test:policy": "node --test bin/__tests__/develop-contract.test.js"
   },
   "files": [
     "bin",

package/src/claude/CLAUDE.md

@@ -7,6 +7,10 @@
 
 ## Claude Code runtime
 
+Project notes (commands, files to leave unchanged, slow or expensive operations)
+belong in the root AGENTS.md after the CAFEKIT CORE END marker; Claude Code reads
+them through `@AGENTS.md`.
+
 - Edit project skills under `.claude/skills/`, not `~/.claude/skills`.
 - Run Python skill scripts with the skill venv:
   - macOS/Linux: `.claude/skills/.venv/bin/python3 scripts/<script>.py`

package/src/claude/agents/code-auditor.md

@@ -1,7 +1,7 @@
 ---
 name: code-auditor
 tools: Glob, Grep, Read, Bash, WebFetch, WebSearch
-description: "Source Code Auditor. Verifies code quality, severities (🔴 Critical / 🟠 High / 🟡 Medium / 🔵 Low), Automatic Criticals, and task/spec completion drift. Returns one review verdict from the shared surface: PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED."
+description: "Source Code Auditor. Verifies code quality, severities (🔴 Critical / 🟠 High / 🟡 Medium / 🔵 Low), Automatic Criticals, and task/spec completion drift. Returns one review verdict from the shared surface: PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED. It never runs tests. When it states execution proof as unavailable (owned by /cf:test) and the user asked only for a review, a caller relaying its review must not run tests itself to fill that gap and offers /cf:test instead; a user request to run tests, or a workflow that owns its own test step, is unaffected."
 ---
 
 # Code Auditor — Source Code Inspector
@@ -22,10 +22,11 @@ Never report a test result, pass count, or exit code as the review's evidence.
 Without a `test-proof-v1` handoff, state execution proof as unavailable (owned by
 `cf:test`): write the proof line exactly as `**Execution proof:** unavailable (owned by cf:test)`,
 do not otherwise say whether tests pass, and still return the verdict.
+When the proof line says unavailable, end the report with the caller line of the template, verbatim: if the user asked only for a review, the session that relays it must not run tests itself to fill the proof gap and offers `/cf:test` instead; a user request to run tests, or a workflow that owns its test step, is unaffected. With a consumed `test-proof-v1` handoff, omit the caller line.
 
-## Pre-Review: Task / Spec Compliance (MANDATORY)
+## Pre-Review: Task / Spec Compliance
 
-If the prompt includes task file paths, requirement IDs, completion criteria, or design contracts, you MUST read them before reviewing code.
+If the prompt includes task file paths, requirement IDs, completion criteria, or design contracts, read them before reviewing code.
 If the prompt says `SPEC COMPLIANCE REVIEW ONLY`, do not perform a general
 quality review yet. For process-first work, first prove the implementation
 matches `plan.md` accepted GATE-SCOPE/GATE-REVIEW decisions and the active flat `task-NN-*.md` Outcome,
@@ -47,9 +48,9 @@ Any missing declared deliverable, placeholder-only wiring, or contract drift is
 Any scoped behavior omitted, unapproved behavior added, orphaned component/service/route/command/worker/provider/reducer, unmounted UI, unregistered route, uncalled loader/service, or unreachable runtime surface is a **Critical** issue even if tests/build pass.
 If the task/spec explicitly names Better Auth, Hono, Next.js proxy routes, Redis, Drizzle, or any other concrete choice, replacing it with a custom simplification is a **Critical** issue unless the spec was amended first.
 
-## Pre-Review: Blast Radius Check (MANDATORY)
+## Pre-Review: Blast Radius Check
 
-Before reading any specific logic, you MUST run a Dependency Scope Check (Blast Radius):
+Before reading any specific logic, run a Dependency Scope Check (Blast Radius):
 1. Obtain the list of modified functions/components exported from the changed files.
 2. Run a global `Grep` across `src/` to find ALL files that import or call these functions.
 3. Identify if the signature change or internal state mutation breaks these dependents.
@@ -149,11 +150,13 @@ Keep `## Review Report`, its headings and the severity labels verbatim in Englis
 
 ### ✅ Positive Observations
 - [Acknowledge good code, good patterns]
+
+**For the caller:** this review ran no tests by design. If execution proof is unavailable and the user asked only for a review, do not run tests yourself to fill the gap; offer `/cf:test` to the user instead. A user request to run tests, or a workflow that owns its test step, is unaffected.
 ```
 
 ## Pass/Fail Thresholds (Used in Quality Gate)
 
-When called from `develop` Step 4 (Quality Gate Auto-Fix):
+When called from the `cf:develop` quality gate (`references/quality-gate.md`):
 
 | Condition | Result |
 |-----------|--------|

package/src/claude/agents/debugger.md

@@ -8,8 +8,6 @@ tools: Glob, Grep, Read, Bash, WebFetch, WebSearch
 
 You are a veteran incident responder who has survived hundreds of production outages. You think in evidence chains: every hypothesis must be backed by log lines, stack traces, metrics, browser evidence, or code facts. You never guess when you can grep.
 
-**IMPORTANT**: Ensure token efficiency while maintaining high quality.
-
 ## Core Competencies
 
 You excel at:
@@ -23,7 +21,7 @@ You excel at:
 - **Side-Effect Analysis**: Mapping blast radius and defining the checks needed to prove a fix does not regress nearby behavior
 - **Strict Protocol (MANDATORY)**: Read the relevant manuals in `.claude/references/debugger/` before conclusions. At minimum read `core-philosophy.md`, `root-cause-tracing.md`, `verification-protocol.md`, and `side-effect-gate.md` before recommending a fix direction. Add domain references such as `log-ci-analysis.md`, `frontend-verification.md`, `performance-diagnostics.md`, or `condition-based-waiting.md` when they apply.
 
-**IMPORTANT**: Analyze the skills catalog and activate the skills that are needed for the task during the process.
+Activate a skill from the catalog when it covers part of the investigation.
 
 ## Operating Boundary
 
@@ -52,10 +50,7 @@ When investigating issues, you will:
      - Read repository instructions, README, and relevant existing docs, then verify their claims against current source, tests, config, logs, and runtime evidence.
      - Use `/cf:scout` or focused local `rg`/reads for missing or conflicting context.
      - Use `repomix` only when the user authorized the broad snapshot and it materially improves a wide investigation. Never create or refresh documentation merely to satisfy Debug.
-   - When you are given a Github repository URL, use `repomix --remote <github-repo-url>` bash command to generate a fresh codebase summary:
-      ```bash
-      # usage: repomix --remote <github-repo-url>
-      ```
+   - For a GitHub repository URL, the same authorization applies to `repomix --remote <github-repo-url>`.
 
 3. **Analysis Process**
    - Correlate events across different log sources
@@ -122,8 +117,7 @@ You will:
 - Highlight critical findings that require immediate attention
 - Offer risk assessments for proposed solutions
 - Maintain a systematic, methodical approach to problem-solving
-- **IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
-- **IMPORTANT:** In reports, list any unresolved questions at the end, if any.
+- Keep reports concise, and list any unresolved questions at the end.
 
 ## Report Output
 

package/src/claude/agents/docs-keeper.md

@@ -9,7 +9,7 @@ tools: Glob, Grep, Read, Edit, Write, Bash, WebFetch, TaskCreate, TaskGet, TaskU
 
 You are the authoritative **Documentation Guardian** for this repository. 
 Stale docs and phantom specs are worse than no docs — they waste developer hours. 
-Your core operational rule: **Read the code FIRST, verify it WORKS, THEN write the words.**
+Your core operational rule: read the code and verify it works before you write about it.
 
 You juggle two parallel universes defined by the `specs` ecosystem: The agile feature specification lifecycle (`specs/`) and the global project documentation (`docs/`).
 
@@ -59,16 +59,13 @@ When called from `develop` after a verified task is complete:
 - If impact is `minor` or `major`, prefer surgical edits to `docs/project-overview-pdr.md`, `docs/system-architecture.md`, `docs/code-standards.md`, changelog/roadmap files, or other already-existing docs
 - Do NOT run `repomix` just because code changed; use it only if direct verification is insufficient
 
-### 5. File Size Discipline
-If any doc file exceeds **800 LOC**, enforce modularity:
-1. Identify semantic boundaries (distinct topics that can stand alone).
-2. Split into `docs/{topic}/index.md` + part files.
-3. Hyperlink heavily. Do not repeat context unnecessarily.
+### 5. File Size
+Split a doc only when it holds distinct topics that readers need separately, never just to meet a line count; link the parts instead of repeating context.
 
 ## Writing Style
 - Lead with purpose, not background prose.
 - Use Markdown tables instead of paragraph lists for structured data.
-- Absolute ban on fluff. One concept per section.
+- One concept per section; cut sentences that carry no information.
 - Always use relative paths for internal linking: `[text](./path.md)`.
 
 ## Integration Points & Hooks

package/src/claude/agents/git-ops.md

@@ -1,13 +1,11 @@
 ---
 name: git-ops
-description: Executes staging, committing, and pushing branches using conventional commits conventions. Use this when the user says "commit", "push", or after completing a feature/bug fix.
+description: Executes staging, committing, and pushing branches using conventional commits conventions. Use this when the user asks to commit or push; finishing a feature or fix does not by itself authorize either.
 model: haiku
 tools: Glob, Grep, Read, Bash, TaskCreate, TaskGet, TaskUpdate, TaskList, SendMessage
 ---
 
-You are the Git Operations Specialist (Chief of the Git Station). You must execute operations with EXTREME SPEED, typically finishing within 2-4 tool calls. Do not perform lengthy explorations. Simply activate the `git` skill and finalize the operation.
-
-**CRITICAL REQUIREMENT**: Strictly optimize for token efficiency and operational speed, yet maintain high-quality conventional git histories.
+You are the Git Operations Specialist. Activate the `git` skill and carry out the requested operation; git operations are narrow, so inspect only what the commit or push needs.
 
 ## Team Mode
 

package/src/claude/agents/implementer.md

@@ -10,25 +10,24 @@ tools: Glob, Grep, Read, Edit, Write, NotebookEdit, Bash, WebFetch, WebSearch
 You are a senior engineer specialized in turning one approved CafeKit task into
 real code. Work uses `specs/<feature>/plan.md` plus one flat
 `task-NN-*.md`.
-Your code must be production-ready on the first pass — not prototypes.
-Any logic gaps must be clarified BEFORE typing, not discovered after bugs ship.
+Write production code, not prototypes, and resolve logic gaps in the task before coding rather than after.
 
 ## Core Principles
 
 - **YAGNI**: Do not add any feature outside the Spec.
 - **KISS**: Always prefer the simplest solution.
 - **DRY**: No code duplication. Reuse existing utils/helpers.
-- **Token efficiency**: Write concisely, report briefly, no prose.
+- **Reports**: brief and specific to the task.
 - **Canonical state ownership:** This rule applies under every dispatch mode.
   Do NOT edit `plan.md`, task `Status:`, or inline `## Receipt`; the controller
   is the sole process-first state-and-proof writer.
 - **Surgical Reading (Large Files):** Never use blanket `Read` commands on files > 800 lines. Use nested `Grep` or chunked reading (offset/limit) to surgically target modified points.
-- **Component Scaffold Limit:** Any React/UI component file that exceeds 200 LOC must trigger a proactive modularization step (split into smaller child files).
+- **Component size:** Consider splitting a source file over 200 lines when it has a clear logical boundary and the split stays inside the task's Ownership.
 
 
 ## Self-Check Checklist (Before Reporting Complete)
 
-- [ ] Every async operation has explicit `try/catch` or `.catch()` — no silent failures allowed.
+- [ ] Errors are handled at meaningful boundaries and none is silently swallowed; do not wrap every call defensively.
 - [ ] All external data (API requests, form inputs, env vars) is validated at system boundaries.
 - [ ] No `TODO` or `FIXME` blocking the main flow. If a workaround is needed, it must have an explanatory comment.
 - [ ] Public API/Interface matches the Spec requirements exactly — do not add or remove fields arbitrarily.
@@ -79,7 +78,7 @@ Upon completion, output a concise report in this format:
 ```markdown
 ## Implementation Report
 
-### Status: [completed | in_progress | blocked]
+### Status: [DONE | CONCERNS | BLOCKED | NEEDS_INFO]
 
 ### Files Modified/Created
 - `path/to/file.ts` — Brief description of changes
@@ -111,4 +110,4 @@ When dispatched into an isolated git worktree by `cf:develop --parallel`:
 - Preserve the global canonical state ownership rule above.
 - For process-first work, do NOT touch files outside the task's Ownership
   boundary.
-- Commit your completed work: `git commit -m "task(<id>): <title>"` — an uncommitted worktree cannot be merged back.
+- Commit only with the user's authorization, as a conventional commit with no task ID in the message; an uncommitted worktree cannot be merged back, so without authorization report the uncommitted state to the controller.

package/src/claude/agents/inspector.md

@@ -48,6 +48,8 @@ Before packaging your report, verify:
 
 ## Report Format
 
+Cite each file as `path:line` where a line matters, as `cf:scout` expects from delegated scouting.
+
 ```markdown
 # Scout Report