@haposoft/cafekit 0.13.4 → 0.14.1

package/README.md

@@ -131,9 +131,8 @@ CafeKit ships many skills, but the main release surface is:
 - `/hapo:docs [--init|--update|--summarize|--reconstruct]`: create project docs or reconstruct as-is system documentation from source code
 - `/hapo:test [scope|--full]`: run verification and return a structured verdict
 - `/hapo:code-review [scope|--pending]`: adversarial review focused on correctness, regressions, and security
-- `/hapo:generate-graph <diagram request>`: generate technical SVG/PNG diagrams
 
-Common companion skills bundled in this package include `inspect`, `impact-analysis`, `research`, `ai-multimodal`, `frontend-development`, `backend-development`, and `react-best-practices`.
+Common companion skills bundled in this package include `inspect`, `research`, `ai-multimodal`, `frontend-development`, `backend-development`, and `react-best-practices`.
 
 CafeKit uses rule-based skill routing guidance instead of an automatic prompt-scoring hook. See `.claude/rules/skill-workflow-routing.md`, `.claude/rules/skill-domain-routing.md`, or run:
 

package/bin/lib/i18n.js

@@ -366,11 +366,11 @@ const MESSAGES = {
   }
 };
 
-/** Normalize a language code to a supported one; unknown → 'ja'. */
+/** Normalize a language code to a supported one; unknown → 'en'. */
 function resolveLang(code) {
   if (!code) return 'en';
   const lc = String(code).toLowerCase().slice(0, 2);
-  return SUPPORTED.includes(lc) ? lc : 'ja';
+  return SUPPORTED.includes(lc) ? lc : 'en';
 }
 
 /** Build a translator. Falls back to English per-key, then the key itself. */

package/bin/lib/manifest.js

@@ -105,6 +105,21 @@ function createTracker(platformFolder, version) {
       this._pruned.add(key);
     },
 
+    /**
+     * Prune every tracked key under a directory prefix (e.g. "skills/foo/").
+     * Marks prior-manifest keys with the same prefix for deletion on write().
+     */
+    prunePrefix(relPrefix) {
+      const prefix = relPrefix.replace(/\\/g, '/');
+      for (const key of Object.keys(files)) {
+        if (key.startsWith(prefix)) delete files[key];
+      }
+      const prior = read(platformFolder);
+      for (const key of Object.keys(prior.files || {})) {
+        if (key.startsWith(prefix)) this._pruned.add(key);
+      }
+    },
+
     /** Recorded hash for a relPath written earlier this run, or null. */
     recorded(rel) {
       const key = rel.replace(/\\/g, '/');

package/bin/lib/opencode-install.js

@@ -94,13 +94,6 @@ const OPENCODE_COMMAND_TEMPLATES = [
     subtask: true,
     description: 'Inspect a codebase, artifact, or external context before planning.'
   },
-  {
-    fileName: 'generate-graph.md',
-    skillName: 'generate-graph',
-    agent: 'god-developer',
-    subtask: true,
-    description: 'Generate technical diagrams from project context.'
-  },
   // Domain skills — wrappers so users can invoke them directly via slash
   // commands. Each delegates to the matching skill under .opencode/skills/.
   {
@@ -166,13 +159,6 @@ const OPENCODE_COMMAND_TEMPLATES = [
     subtask: true,
     description: 'Run git workflows: branch, commit, tag, push, or release prep.'
   },
-  {
-    fileName: 'impact-analysis.md',
-    skillName: 'impact-analysis',
-    agent: 'inspector',
-    subtask: true,
-    description: 'Assess affected files, blast radius, and side effects of a change.'
-  },
   {
     fileName: 'mobile-development.md',
     skillName: 'mobile-development',

package/bin/phases/claude-runtime.js

@@ -78,11 +78,14 @@ function removeObsoleteClaudeRuntimeFiles(ctx, platformKey) {
     const targetPath = path.join(targetBase, relPath);
     if (!fs.existsSync(targetPath)) return;
 
+    const isDir = fs.statSync(targetPath).isDirectory();
     if (!ctx.dryRun) {
-      fs.rmSync(targetPath, { force: true });
+      fs.rmSync(targetPath, { force: true, recursive: isDir });
       // Remove the entry from the manifest so it doesn't linger as a zombie.
       if (ctx.trackers && ctx.trackers.claude) {
         ctx.trackers.claude.prune(relPath);
+        // Directories: prune every tracked file underneath as well.
+        if (isDir) ctx.trackers.claude.prunePrefix(`${relPath}/`);
       }
     }
     ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed obsolete runtime: ${relPath}`);

package/bin/phases/claude-settings.js

@@ -85,7 +85,16 @@ function mergeClaudeSettings(ctx, platformKey) {
   const managedSettings = JSON.parse(fs.readFileSync(templatePath, 'utf8'));
   let existingSettings = {};
   if (fs.existsSync(targetPath)) {
-    existingSettings = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+    // A malformed user settings.json must not abort the whole install: skip the
+    // settings merge (never overwrite the user's file blind) and tell them why.
+    try {
+      existingSettings = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+    } catch (e) {
+      ctx.ui.warn(`Settings: ${targetPath} is not valid JSON (${e.message}). ` +
+        'Skipping settings merge — fix the file and re-run the installer.');
+      ctx.results.errors++;
+      return;
+    }
   }
 
   const mergedSettings = pruneObsoleteSettingsHooks({ ...existingSettings }, ctx);
@@ -100,7 +109,10 @@ function mergeClaudeSettings(ctx, platformKey) {
     }
   }
 
-  // hooks: append managed hooks that aren't already present (dedupe by command).
+  // hooks: merge managed hooks per command (not per entry). An entry is keyed
+  // by its matcher; commands missing from the matching entry are appended, so
+  // a new command added to an existing matcher entry is not swallowed on
+  // upgrade (the old dedupe only looked at each entry's FIRST command).
   if (managedSettings.hooks) {
     mergedSettings.hooks = mergedSettings.hooks || {};
     Object.keys(managedSettings.hooks).forEach((eventName) => {
@@ -108,14 +120,33 @@ function mergeClaudeSettings(ctx, platformKey) {
       const existingHooks = mergedSettings.hooks[eventName] || [];
       const mergedHooks = [...existingHooks];
 
+      // Commands already registered anywhere under this event (any matcher):
+      // a user may have moved a hook to another entry — never re-add it.
+      const eventCommands = new Set(
+        mergedHooks.flatMap((entry) => (entry?.hooks || []).map((h) => h?.command)).filter(Boolean)
+      );
+
       managedHooks.forEach((managedHook) => {
-        const managedCommand = managedHook.hooks?.[0]?.command || '';
-        const isDuplicate = mergedHooks.some((existingHook) =>
-          existingHook.hooks?.some((h) => h.command === managedCommand));
-        if (!isDuplicate) {
-          mergedHooks.push(managedHook);
+        const managedMatcher = managedHook.matcher || '';
+        const managedCommands = (managedHook.hooks || [])
+          .filter((h) => h?.command && !eventCommands.has(h.command));
+        if (managedCommands.length === 0) return;
+
+        const target = mergedHooks.find((entry) =>
+          (entry?.matcher || '') === managedMatcher && Array.isArray(entry?.hooks));
+
+        if (!target) {
+          mergedHooks.push({ ...managedHook, hooks: managedCommands });
+          managedCommands.forEach((h) => eventCommands.add(h.command));
           ctx.ui.detail(`  ✓ ${ctx.dryRun ? '[dry-run] ' : ''}Settings: hook ${eventName} merged`);
+          return;
         }
+
+        managedCommands.forEach((hook) => {
+          target.hooks.push(hook);
+          eventCommands.add(hook.command);
+        });
+        ctx.ui.detail(`  ✓ ${ctx.dryRun ? '[dry-run] ' : ''}Settings: hook ${eventName} merged (+${managedCommands.length} command${managedCommands.length > 1 ? 's' : ''})`);
       });
 
       mergedSettings.hooks[eventName] = mergedHooks;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.13.4",
+  "version": "0.14.1",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/agents/ui-ux-designer.md

@@ -25,10 +25,10 @@ You are an award-caliber UI/UX designer. You merge aesthetic excellence with eng
 ### Phase 1: Research & Trend Scouting
 - Execute explicit searches using the bundled `ui-ux-pro-max` toolkit:
   ```bash
-  python3 packages/spec/src/claude/skills/ui-ux-pro-max/scripts/search.py "<product-type>" --domain product
-  python3 packages/spec/src/claude/skills/ui-ux-pro-max/scripts/search.py "<style-keywords>" --domain style
-  python3 packages/spec/src/claude/skills/ui-ux-pro-max/scripts/search.py "<mood>" --domain typography
-  python3 packages/spec/src/claude/skills/ui-ux-pro-max/scripts/search.py "<industry>" --domain color
+  .claude/skills/.venv/bin/python3 .claude/skills/ui-ux-pro-max/scripts/search.py "<product-type>" --domain product
+  .claude/skills/.venv/bin/python3 .claude/skills/ui-ux-pro-max/scripts/search.py "<style-keywords>" --domain style
+  .claude/skills/.venv/bin/python3 .claude/skills/ui-ux-pro-max/scripts/search.py "<mood>" --domain typography
+  .claude/skills/.venv/bin/python3 .claude/skills/ui-ux-pro-max/scripts/search.py "<industry>" --domain color
   ```
 - Study current design trends sourced from Dribbble, Awwwards, Mobbin via the python extractor outputs.
 - Review existing `docs/design-guidelines.md` if it exists.

package/src/claude/hooks/__tests__/privacy-block.test.js

@@ -0,0 +1,79 @@
+'use strict';
+
+// Behavioral tests for privacy-block.cjs. The hook is run as a real subprocess:
+// a PreToolUse payload is piped to stdin and the exit code is asserted
+// (0 = allow, 2 = block). Covers the symlink-bypass hardening.
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const HOOK = path.join(__dirname, '..', 'privacy-block.cjs');
+
+/** Run the hook with a tool payload; return { code, stderr }. */
+function runHook(payload, cwd) {
+  const res = spawnSync(process.execPath, [HOOK], {
+    input: JSON.stringify({ ...payload, cwd: cwd || payload.cwd }),
+    encoding: 'utf8',
+  });
+  return { code: res.status, stderr: res.stderr || '' };
+}
+
+function tmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'ck-privacy-'));
+}
+
+test('blocks a direct Read of .env (exit 2)', () => {
+  const dir = tmpDir();
+  try {
+    const env = path.join(dir, '.env');
+    fs.writeFileSync(env, 'SECRET=1');
+    const { code } = runHook({ tool_name: 'Read', tool_input: { file_path: env } }, dir);
+    assert.strictEqual(code, 2);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('blocks a symlink whose target is .env (regression: symlink bypass)', () => {
+  const dir = tmpDir();
+  try {
+    const env = path.join(dir, '.env');
+    fs.writeFileSync(env, 'SECRET=1');
+    const link = path.join(dir, 'notes.txt'); // harmless-looking name
+    fs.symlinkSync(env, link);
+    const { code } = runHook({ tool_name: 'Read', tool_input: { file_path: link } }, dir);
+    assert.strictEqual(code, 2, 'symlink to .env must be blocked, not allowed');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('allows a normal non-sensitive file (exit 0)', () => {
+  const dir = tmpDir();
+  try {
+    const f = path.join(dir, 'README.md');
+    fs.writeFileSync(f, '# hi');
+    const { code } = runHook({ tool_name: 'Read', tool_input: { file_path: f } }, dir);
+    assert.strictEqual(code, 0);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('allows a symlink to an exempt .env.example (exemption still wins)', () => {
+  const dir = tmpDir();
+  try {
+    const example = path.join(dir, '.env.example');
+    fs.writeFileSync(example, 'SECRET=');
+    const link = path.join(dir, 'sample.txt');
+    fs.symlinkSync(example, link);
+    const { code } = runHook({ tool_name: 'Read', tool_input: { file_path: link } }, dir);
+    assert.strictEqual(code, 0, 'symlink to an exempt file must stay allowed');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/claude/hooks/__tests__/session-writeenv.test.js

@@ -0,0 +1,68 @@
+'use strict';
+
+// Behavioral test for session.cjs writeEnv escaping. A git branch name is an
+// attacker-influenced value that flows into GIT_BRANCH in CLAUDE_ENV_FILE. If
+// the value is not escaped, sourcing that env file expands `$HOME` and executes
+// the `pwd` command substitution. We build a repo whose branch carries both
+// payloads (space-free, since git bans spaces in refs), run the hook, then
+// source the produced env file and assert GIT_BRANCH read back is the exact
+// literal branch name — nothing expanded or executed.
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const HOOK = path.join(__dirname, '..', 'session.cjs');
+
+function git(args, cwd) {
+  const res = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  if (res.status !== 0) {
+    throw new Error(`git ${args.join(' ')} failed: ${res.stderr}`);
+  }
+  return res.stdout.trim();
+}
+
+test('session.cjs escapes shell metacharacters in GIT_BRANCH (no injection when sourced)', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-session-'));
+  const envFile = path.join(dir, 'env.sh');
+  try {
+    // Branch name carries both a $HOME expansion and a `pwd` command
+    // substitution. Both are space-free so git accepts them as a valid ref.
+    const payloadBranch = 'evil$HOME-x`pwd`';
+    git(['init', '-q'], dir);
+    git(['config', 'user.email', 't@t.co'], dir);
+    git(['config', 'user.name', 't'], dir);
+    git(['commit', '-q', '--allow-empty', '-m', 'init'], dir);
+    git(['checkout', '-q', '-b', payloadBranch], dir);
+
+    // Run the hook exactly as Claude Code would (SessionStart on stdin).
+    const res = spawnSync(process.execPath, [HOOK], {
+      cwd: dir,
+      input: JSON.stringify({ source: 'startup' }),
+      encoding: 'utf8',
+      env: { ...process.env, CLAUDE_ENV_FILE: envFile },
+    });
+    assert.strictEqual(res.status, 0, 'hook must exit 0 (fail-open)');
+    assert.ok(fs.existsSync(envFile), 'env file must be written');
+
+    const envText = fs.readFileSync(envFile, 'utf8');
+    const branchLine = envText.split('\n').find((l) => l.startsWith('export GIT_BRANCH='));
+    assert.ok(branchLine, 'GIT_BRANCH must be present');
+    assert.ok(branchLine.includes('\\$') && branchLine.includes('\\`'), 'both $ and backtick must be escaped');
+
+    // The real proof: source the env file, then echo the value back. It must
+    // equal the literal branch name — no $HOME expansion, no pwd execution.
+    const sourced = spawnSync('sh', ['-c', `. "${envFile}" && printf '%s' "$GIT_BRANCH"`], { encoding: 'utf8' });
+    assert.strictEqual(sourced.status, 0, 'sourcing env file should succeed');
+    assert.strictEqual(
+      sourced.stdout,
+      payloadBranch,
+      'GIT_BRANCH must read back as the exact literal branch (no expansion/execution)',
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/claude/hooks/__tests__/spec-gate.test.js

@@ -0,0 +1,270 @@
+'use strict';
+
+// Behavioral tests for spec-gate.cjs (Stop completion gate). The hook is run as
+// a real subprocess: a Stop payload is piped to stdin; we assert exit code and
+// whether stdout carries {"decision":"block",...}. Cache lives under the hook's
+// own .logs/ dir (shared), so each test seeds/clears it deliberately.
+
+const { test, beforeEach, after } = require('node:test');
+const assert = require('node:assert');
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const HOOK = path.join(__dirname, '..', 'spec-gate.cjs');
+const CACHE = path.join(__dirname, '..', '.logs', 'spec-gate-last.json');
+const FEATURE = 'demo';
+const TASK_REL = 'tasks/task-R0-01-x.md';
+
+function runHook(payload, cwd) {
+  const projectRoot = cwd || payload.cwd;
+  // PROJECT_ROOT wins over cwd in the hook; pin it to the fixture so a host
+  // monorepo's real specs/ cannot leak into the test (e.g. active rtk-* specs).
+  const env = { ...process.env, PROJECT_ROOT: projectRoot };
+  const res = spawnSync(process.execPath, [HOOK], {
+    input: JSON.stringify({
+      hook_event_name: 'Stop',
+      session_id: 'test',
+      transcript_path: '/tmp/t',
+      stop_hook_active: false,
+      ...payload,
+      cwd: projectRoot,
+    }),
+    encoding: 'utf8',
+    env,
+  });
+  return {
+    code: res.status,
+    stdout: (res.stdout || '').trim(),
+    stderr: res.stderr || '',
+  };
+}
+
+function tmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'ck-spec-gate-'));
+}
+
+function clearCache() {
+  try { fs.unlinkSync(CACHE); } catch { /* absent */ }
+}
+
+function seedCache(featureMap) {
+  fs.mkdirSync(path.dirname(CACHE), { recursive: true });
+  fs.writeFileSync(CACHE, JSON.stringify(featureMap));
+}
+
+function readCache() {
+  return JSON.parse(fs.readFileSync(CACHE, 'utf8'));
+}
+
+/**
+ * Build a minimal active-spec fixture under dir.
+ * @param {object} opts
+ * @param {string} [opts.taskStatus='done']
+ * @param {string|null} [opts.completed_at='2026-07-01T00:00:00Z']
+ * @param {string} [opts.mdStatus='done']
+ * @param {'valid'|'missing-evidence'|'placeholder'|'none'} [opts.evidence='valid']
+ * @param {object|null} [opts.runtime] — if set, write .claude/runtime.json
+ */
+function makeFixture(opts = {}) {
+  const {
+    taskStatus = 'done',
+    completed_at = '2026-07-01T00:00:00Z',
+    mdStatus = 'done',
+    evidence = 'valid',
+    runtime = null,
+  } = opts;
+  const dir = tmpDir();
+  const featureDir = path.join(dir, 'specs', FEATURE);
+  const tasksDir = path.join(featureDir, 'tasks');
+  fs.mkdirSync(tasksDir, { recursive: true });
+
+  const entry = { status: taskStatus };
+  if (completed_at !== null) entry.completed_at = completed_at;
+
+  fs.writeFileSync(
+    path.join(featureDir, 'spec.json'),
+    JSON.stringify({
+      status: 'in_progress',
+      current_phase: 'implementation',
+      task_registry: { [TASK_REL]: entry },
+    }),
+  );
+
+  let evidenceBlock = '';
+  if (evidence === 'valid') {
+    evidenceBlock = [
+      '## Evidence',
+      '',
+      '```',
+      'npm test',
+      'PASS: 10 tests',
+      '```',
+      '',
+    ].join('\n');
+  } else if (evidence === 'placeholder') {
+    evidenceBlock = [
+      '## Evidence',
+      '',
+      'Command: `{{TYPECHECK / TEST COMMAND}}`',
+      'Expected: {{What proves success}}',
+      '',
+    ].join('\n');
+  } else if (evidence === 'missing-evidence') {
+    evidenceBlock = '## Risk Assessment\n\nNone.\n';
+  } else {
+    evidenceBlock = '';
+  }
+
+  fs.writeFileSync(
+    path.join(dir, 'specs', FEATURE, TASK_REL),
+    [
+      `# Task R0-01: example`,
+      '',
+      `**Status:** ${mdStatus}`,
+      '',
+      evidenceBlock,
+    ].join('\n'),
+  );
+
+  if (runtime) {
+    fs.mkdirSync(path.join(dir, '.claude'), { recursive: true });
+    fs.writeFileSync(
+      path.join(dir, '.claude', 'runtime.json'),
+      JSON.stringify(runtime),
+    );
+  }
+
+  return dir;
+}
+
+function parseBlock(stdout) {
+  if (!stdout) return null;
+  // Hook may print only the JSON line.
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    const line = stdout.split('\n').find((l) => l.includes('"decision"'));
+    if (!line) return null;
+    return JSON.parse(line);
+  }
+}
+
+beforeEach(() => {
+  clearCache();
+});
+
+after(() => {
+  clearCache();
+});
+
+test('1. newly-done task WITHOUT receipt → block, reason names task path', () => {
+  const dir = makeFixture({
+    evidence: 'missing-evidence',
+    completed_at: '2026-07-01T00:00:00Z',
+  });
+  try {
+    seedCache({ [FEATURE]: { [TASK_REL]: 'pending' } });
+    const { code, stdout } = runHook({}, dir);
+    assert.strictEqual(code, 0);
+    const body = parseBlock(stdout);
+    assert.ok(body, 'expected block JSON on stdout');
+    assert.strictEqual(body.decision, 'block');
+    assert.ok(
+      body.reason.includes(TASK_REL),
+      `reason must name task path; got: ${body.reason}`,
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('2. newly-done task WITH valid receipt → no block, cache updated', () => {
+  const dir = makeFixture({ evidence: 'valid' });
+  try {
+    seedCache({ [FEATURE]: { [TASK_REL]: 'pending' } });
+    const { code, stdout } = runHook({}, dir);
+    assert.strictEqual(code, 0);
+    assert.strictEqual(stdout, '', 'valid receipt must not produce block output');
+    const cache = readCache();
+    assert.strictEqual(cache[FEATURE][TASK_REL], 'done');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('3. no active spec → exit 0 silent', () => {
+  const dir = tmpDir();
+  try {
+    fs.mkdirSync(path.join(dir, 'specs'), { recursive: true });
+    // No in_progress spec.
+    seedCache({ [FEATURE]: { [TASK_REL]: 'pending' } });
+    const { code, stdout } = runHook({}, dir);
+    assert.strictEqual(code, 0);
+    assert.strictEqual(stdout, '');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('4. stop_hook_active: true → exit 0 silent even with violating task', () => {
+  const dir = makeFixture({ evidence: 'missing-evidence' });
+  try {
+    seedCache({ [FEATURE]: { [TASK_REL]: 'pending' } });
+    const { code, stdout } = runHook({ stop_hook_active: true }, dir);
+    assert.strictEqual(code, 0);
+    assert.strictEqual(stdout, '');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('5. first run (no cache) with done-without-receipt → exit 0, cache created', () => {
+  const dir = makeFixture({ evidence: 'missing-evidence' });
+  try {
+    clearCache();
+    assert.ok(!fs.existsSync(CACHE), 'cache must be absent for first-run');
+    const { code, stdout } = runHook({}, dir);
+    assert.strictEqual(code, 0);
+    assert.strictEqual(stdout, '', 'first run must never block');
+    assert.ok(fs.existsSync(CACHE), 'cache file must be created');
+    const cache = readCache();
+    assert.strictEqual(cache[FEATURE][TASK_REL], 'done');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('6. runtime.json spec.completion_gate: false → exit 0 silent', () => {
+  const dir = makeFixture({
+    evidence: 'missing-evidence',
+    runtime: { spec: { completion_gate: false } },
+  });
+  try {
+    seedCache({ [FEATURE]: { [TASK_REL]: 'pending' } });
+    const { code, stdout } = runHook({}, dir);
+    assert.strictEqual(code, 0);
+    assert.strictEqual(stdout, '');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('7. Evidence with {{...}} placeholder → blocked (check c)', () => {
+  const dir = makeFixture({ evidence: 'placeholder' });
+  try {
+    seedCache({ [FEATURE]: { [TASK_REL]: 'pending' } });
+    const { code, stdout } = runHook({}, dir);
+    assert.strictEqual(code, 0);
+    const body = parseBlock(stdout);
+    assert.ok(body, 'expected block JSON on stdout');
+    assert.strictEqual(body.decision, 'block');
+    assert.ok(
+      body.reason.includes(TASK_REL) && /\bc\b/.test(body.reason),
+      `reason must cite task path and check c; got: ${body.reason}`,
+    );
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/claude/hooks/privacy-block.cjs

@@ -60,6 +60,20 @@ try {
     return RESTRICTED_PATTERNS.some((rule) => rule.test(base) || rule.test(filePath));
   }
 
+  /**
+   * Resolve a symlink to its real target so a harmless-looking name that points
+   * at a sensitive file cannot slip through the basename check. Returns null
+   * when the path cannot be resolved (missing file, broken link) — fail-open to
+   * the original-path check in that case.
+   */
+  function resolveTarget(filePath) {
+    try {
+      return fs.realpathSync(filePath);
+    } catch {
+      return null;
+    }
+  }
+
   function extractBashPaths(command) {
     const paths = [];
     const regex = /(?:cat|less|more|head|tail|source|\.)\s+(?:"([^"]+)"|'([^']+)'|([^\s]+))/g;
@@ -146,8 +160,14 @@ try {
   if (!paths.length) process.exit(0);
 
   for (const filePath of paths) {
-    if (isSafe(filePath)) continue;
-    if (!isSensitive(filePath)) continue;
+    // Check the requested path and, when it is a symlink, its real target.
+    const target = resolveTarget(filePath);
+    const candidates = target && target !== filePath ? [filePath, target] : [filePath];
+
+    // An exemption on either name wins (e.g. a symlink to .env.example).
+    if (candidates.some(isSafe)) continue;
+    // Sensitive if the requested path OR its symlink target is sensitive.
+    if (!candidates.some(isSensitive)) continue;
 
     if (toolName === 'Bash') {
       console.error(`WARN: Privacy-sensitive file access via bash allowed for approved follow-up: ${path.basename(filePath)}`);

package/src/claude/hooks/session.cjs

@@ -31,7 +31,11 @@ try {
   function writeEnv(file, key, value) {
     if (!file) return;
     try {
-      const safe = String(value ?? '').replace(/"/g, '\\"');
+      // Escape every char that stays special inside a double-quoted shell
+      // string: backslash, dollar, backtick, and the closing quote. Escaping
+      // only `"` left `$(...)`/backticks live, so a value sourced from repo
+      // content (branch, package name) could execute when the env file is sourced.
+      const safe = String(value ?? '').replace(/([\\$`"])/g, '\\$1');
       fs.appendFileSync(file, `export ${key}="${safe}"\n`);
     } catch { /* fail-open */ }
   }