@haposoft/cafekit 0.13.4 → 0.14.0

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 */ }
   }

package/src/claude/hooks/spec-gate.cjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * Stop Hook — spec-gate.cjs
+ * Implements: https://docs.anthropic.com/en/docs/claude-code/hooks
+ *
+ * Blocks turn end when *newly-done* tasks lack a verification receipt.
+ * Block contract (exit 0 + stdout): {"decision":"block","reason":"..."}.
+ *
+ * Safety: stop_hook_active loop guard; runtime.spec.completion_gate=false
+ * escape hatch (missing key → ON); first-run seeds cache without blocking;
+ * crash → fail-open + hooks/.logs/hook-log.jsonl. Exit: 0 always.
+ */
+
+try {
+  const fs   = require('fs');
+  const path = require('path');
+
+  const stdin = fs.readFileSync(0, 'utf8').trim();
+  if (!stdin) process.exit(0);
+
+  const payload = JSON.parse(stdin);
+  const cwd     = payload.cwd || process.cwd();
+
+  // Never re-block a continuation caused by our own block (infinite-loop guard).
+  if (payload.stop_hook_active === true) process.exit(0);
+
+  // Missing/malformed runtime.json keeps the gate ON (fail-closed, valve 3 style).
+  let runtime = {};
+  try {
+    const rp = path.join(cwd, '.claude', 'runtime.json');
+    if (fs.existsSync(rp)) runtime = JSON.parse(fs.readFileSync(rp, 'utf8'));
+  } catch { /* gate stays on */ }
+  if (runtime.spec && runtime.spec.completion_gate === false) process.exit(0);
+
+  // Active-spec discovery — same rules as spec-state.cjs.
+  const baseDir   = process.env.PROJECT_ROOT || cwd;
+  const specsPath = path.join(baseDir, runtime.paths?.specs || 'specs');
+  if (!fs.existsSync(specsPath)) process.exit(0);
+
+  let activeSpec = null;
+  let featureName = null;
+  for (const entry of fs.readdirSync(specsPath, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const specFile = path.join(specsPath, entry.name, 'spec.json');
+    if (!fs.existsSync(specFile)) continue;
+    try {
+      const specData = JSON.parse(fs.readFileSync(specFile, 'utf8'));
+      if (specData.status === 'in_progress' || specData.status === 'in-progress') {
+        activeSpec = specData;
+        featureName = entry.name;
+        break;
+      }
+    } catch { /* skip bad JSON */ }
+  }
+  if (!activeSpec) process.exit(0);
+
+  const taskRegistry = activeSpec.task_registry || {};
+  const cacheFile = path.join(__dirname, '.logs', 'spec-gate-last.json');
+  const cacheExists = fs.existsSync(cacheFile);
+  let cache = {};
+  if (cacheExists) {
+    try { cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8')); } catch { cache = {}; }
+  }
+
+  const currentStatuses = {};
+  for (const [tp, task] of Object.entries(taskRegistry)) {
+    currentStatuses[tp] = task?.status || 'pending';
+  }
+
+  // First run: treat all current done as historical — seed cache, never block.
+  if (!cacheExists) {
+    try {
+      fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+      cache[featureName] = currentStatuses;
+      fs.writeFileSync(cacheFile, JSON.stringify(cache));
+    } catch { /* fail-open */ }
+    process.exit(0);
+  }
+
+  const featureCache = cache[featureName] || {};
+  // Newly done: status is done now AND cached status differs or is absent.
+  const newlyDone = Object.keys(taskRegistry).filter((tp) =>
+    (taskRegistry[tp]?.status || 'pending') === 'done' && featureCache[tp] !== 'done'
+  );
+  if (newlyDone.length === 0) process.exit(0);
+
+  // /m so ^ matches line starts (Evidence is never at byte 0 of the file).
+  const EVID_RE = /^#{2,3}\s+(Evidence|Task Test Plan & Verification Evidence|Verification & Evidence)\b/m;
+  const PROOF_RE = /(PASS|FAIL|exit code|passed|✓)/;
+
+  /** Body of first Evidence heading until next same-or-higher heading. */
+  function evidenceBody(text) {
+    const lines = text.split('\n');
+    let start = -1, level = 0;
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(/^(#{2,3})\s+(Evidence|Task Test Plan & Verification Evidence|Verification & Evidence)\b/);
+      if (m) { start = i + 1; level = m[1].length; break; }
+    }
+    if (start < 0) return null;
+    let end = lines.length;
+    for (let i = start; i < lines.length; i++) {
+      const hm = lines[i].match(/^(#{1,6})\s+/);
+      if (hm && hm[1].length <= level) { end = i; break; }
+    }
+    return lines.slice(start, end).join('\n');
+  }
+
+  // Receipt checks a–d → failed letter list.
+  // a: file + Status header has "done"; b: Evidence heading; c: no {{...}} + (fence|proof); d: completed_at
+  function checkReceipt(taskPath) {
+    const fails = [];
+    const abs = path.join(specsPath, featureName, taskPath);
+    if (!fs.existsSync(abs)) return ['a'];
+    let text = '';
+    try { text = fs.readFileSync(abs, 'utf8'); } catch { return ['a']; }
+
+    const statusLine = text.split('\n').find((l) => /^\s*(\*\*)?Status(\*\*)?\s*:/i.test(l));
+    if (!statusLine || !/\bdone\b/i.test(statusLine)) fails.push('a');
+
+    const body = evidenceBody(text);
+    if (body === null || !EVID_RE.test(text)) {
+      fails.push('b');
+    } else if (/\{\{[^}]+\}\}/.test(body) || !(/```/.test(body) || PROOF_RE.test(body))) {
+      fails.push('c');
+    }
+
+    const at = taskRegistry[taskPath]?.completed_at;
+    if (typeof at !== 'string' || at.trim() === '') fails.push('d');
+    return fails;
+  }
+
+  const failures = newlyDone
+    .map((tp) => ({ taskPath: tp, fails: checkReceipt(tp) }))
+    .filter((f) => f.fails.length > 0);
+
+  // Leave failing newly-done at old cache status so the gate re-fires next Stop.
+  try {
+    const nextFeature = { ...featureCache, ...currentStatuses };
+    for (const { taskPath } of failures) {
+      if (featureCache[taskPath] === undefined) delete nextFeature[taskPath];
+      else nextFeature[taskPath] = featureCache[taskPath];
+    }
+    cache[featureName] = nextFeature;
+    fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+    fs.writeFileSync(cacheFile, JSON.stringify(cache));
+  } catch { /* fail-open */ }
+
+  if (failures.length === 0) process.exit(0);
+
+  const lines = [
+    `⚠️ Completion gate: ${failures.length} newly-done task(s) lack a verification receipt.`,
+  ];
+  for (const { taskPath, fails } of failures) {
+    lines.push(`- \`${taskPath}\`: failed check(s) ${fails.join(', ')}`);
+    lines.push(
+      `  Fix: add a verification receipt to \`## Evidence\` in \`specs/${featureName}/${taskPath}\`: commands run + outcomes, then re-sync spec.json`
+    );
+  }
+  process.stdout.write(JSON.stringify({ decision: 'block', reason: lines.slice(0, 8).join('\n') }) + '\n');
+  process.exit(0);
+
+} catch (e) {
+  try {
+    const fs = require('fs'), p = require('path');
+    const d = p.join(__dirname, '.logs');
+    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+    fs.appendFileSync(p.join(d, 'hook-log.jsonl'),
+      JSON.stringify({ ts: new Date().toISOString(), hook: 'spec-gate', status: 'crash', error: e.message }) + '\n');
+  } catch (_) {}
+  process.exit(0);
+}

package/src/claude/hooks/spec-state.cjs

@@ -98,26 +98,19 @@ try {
     fs.writeFileSync(cacheFile, stateKey);
   } catch { /* fail-open: if the write fails we still print the full block */ }
 
-  // Format the output
+  // Compact state-change block (enforcement lives on Stop via spec-gate.cjs).
   const lines = [];
   lines.push('');
-  lines.push('### 🔴 URGENT SYSTEM TOLLGATE (STATE SYNC) 🔴');
-  lines.push(`- **Active Feature:** \`${featureName}\``);
-  lines.push(`- **Current Phase:** \`${phase}\``);
-  if (taskEntries.length > 0) {
-    lines.push(`- **Task Registry:** \`${taskEntries.length} total | ${(taskCounts.done || 0)} done | ${(taskCounts.in_progress || 0)} in_progress | ${(taskCounts.blocked || 0)} blocked | ${(taskCounts.pending || 0)} pending\``);
-    if (nextUnblocked) {
-      lines.push(`- **Next Unblocked Task:** \`${nextUnblocked[0]}\``);
-    }
+  lines.push(`### Spec state changed: \`${featureName}\``);
+  lines.push(`- Phase: \`${phase}\` | Tasks: ${(taskCounts.done || 0)} done / ${taskEntries.length} total` +
+    (taskEntries.length > 0
+      ? ` (${(taskCounts.in_progress || 0)} in_progress, ${(taskCounts.pending || 0)} pending, ${(taskCounts.blocked || 0)} blocked)`
+      : ''));
+  if (nextUnblocked) {
+    lines.push(`- Next unblocked: \`${nextUnblocked[0]}\``);
   }
-  lines.push('');
-  lines.push(`> BẮT BUỘC (MANDATORY): Nếu bạn vừa hoàn thành một bước, bạn KHÔNG ĐƯỢC báo cáo "Đã xong" ngay.`);
-  lines.push(`> Bạn PHẢI sử dụng công cụ Edit để cập nhật trạng thái vật lý sau khi đã có bằng chứng verify thật (build/test/runtime/artifact), không phải chỉ vì code đã viết xong.`);
-  lines.push(`> 1. Sửa file \`spec.json\` (status, phase/current_phase, timestamps, \`task_files\`, \`task_registry\`, validation state nếu có thay đổi).`);
-  lines.push(`> 2. Chỉ khi verify xong mới sửa file \`tasks/task-*.md\` (status + tick '[x]' các sub-task và completion criteria liên quan).`);
-  lines.push(`> 3. Trước khi set \`ready_for_implementation = true\`, PHẢI chạy \`node .claude/scripts/validate-spec-output.cjs specs/${featureName}\` và sửa mọi lỗi.`);
-  lines.push(`> 4. NẾU VỪA HOÀN THÀNH 1 TASK CÓ SỬA SOURCE CODE, BẮT BUỘC cập nhật ngay tài liệu trong \`docs/\` (\`system-architecture.md\` hoặc Changelog) cho đồng bộ.`);
-  lines.push(`> CẤM VI PHẠM LUẬT TOLLGATE NÀY NHẰM ĐẢM BẢO TÍNH ĐỒNG BỘ CỦA HỆ THỐNG.`);
+  lines.push(`- Sync \`spec.json\` + task file after verified work; run \`node .claude/scripts/validate-spec-output.cjs specs/${featureName}\` before \`ready_for_implementation=true\`.`);
+  lines.push(`- A completion gate verifies receipts when you end a turn with newly-done tasks.`);
   lines.push('');
 
   console.log(lines.join('\n'));

package/src/claude/hooks/task-scaffold-guard.cjs

@@ -66,6 +66,9 @@ try {
   if (!fs.existsSync(scaffold)) process.exit(0);
 
   // Valve 2: block with an actionable message carrying the exact command.
+  // NOTE: deliberately does NOT mention the runtime.json escape hatch — an
+  // OpenCode smoke test proved the model reads the advertised override and
+  // simply disables the guard itself. The hatch stays functional for humans.
   const m = norm.match(/(^|\/)specs\/([^/]+)\/tasks\//);
   const feature = m ? m[2] : '<feature>';
   console.log(
@@ -73,8 +76,7 @@ try {
     `Blocked Write: ${filePath}\n\n` +
     `Generate the stub(s), then Edit-fill the {{...}} placeholders:\n` +
     `  node .claude/scripts/spec-scaffold.cjs ${feature} --tasks "R0-01-slug,R1-01-slug,..." --tasks-only\n` +
-    `Then use Edit (not Write) on each tasks/task-*.md stub.\n` +
-    `Override: set "spec": { "scaffold_guard": false } in .claude/runtime.json`
+    `Then use Edit (not Write) on each tasks/task-*.md stub.`
   );
   process.exit(2);
 

package/src/claude/migration-manifest.json

@@ -13,17 +13,14 @@
       "chrome-devtools",
       "code-review",
       "debug",
-      "delegate",
       "develop",
       "devops",
       "docs",
       "docx",
       "frontend-design",
       "frontend-development",
-      "generate-graph",
       "git",
       "hotfix",
-      "impact-analysis",
       "inspect",
       "mobile-development",
       "pdf",
@@ -61,7 +58,6 @@
       "validate-docs.cjs",
       "validate-docs-reconstruct.cjs",
       "generate-skill-catalog.cjs",
-      "browser-tool.cjs",
       "validate-spec-output.cjs"
     ]
   },
@@ -74,7 +70,10 @@
   "obsolete": {
     "runtimeFiles": [
       "hooks/skill-router.cjs",
-      "hooks/lib/skill-router-routes.cjs"
+      "hooks/lib/skill-router-routes.cjs",
+      "scripts/browser-tool.cjs",
+      "skills/generate-graph",
+      "skills/impact-analysis"
     ],
     "settingsHookCommandSubstrings": [
       "hooks/skill-router.cjs"
@@ -94,6 +93,7 @@
       "hooks/task-scaffold-guard.cjs",
       "hooks/rules.cjs",
       "hooks/spec-state.cjs",
+      "hooks/spec-gate.cjs",
       "hooks/state.cjs",
       "hooks/lib/color.cjs",
       "hooks/lib/parser.cjs",

package/src/claude/rules/skill-domain-routing.md

@@ -21,8 +21,7 @@ Use `/hapo:react-best-practices` for performance/re-render patterns. Use `/hapo:
 User wants to...
 ├── API, service, auth, database-backed feature          -> /hapo:backend-development
 ├── deployment, Docker, Kubernetes, Cloudflare, CI/CD     -> /hapo:devops
-├── mobile apps, iOS, Android, React Native, Flutter     -> /hapo:mobile-development
-└── impact of changing existing behavior                 -> /hapo:impact-analysis
+└── mobile apps, iOS, Android, React Native, Flutter     -> /hapo:mobile-development
 ```
 
 ## Codebase Understanding
@@ -32,7 +31,7 @@ User wants to...
 ├── answer questions from source code/docs/specs/config    -> /hapo:question
 ├── find files, locate code, scan project structure       -> /hapo:inspect
 ├── diagnose an error or failing check                    -> /hapo:debug
-├── understand possible side effects                      -> /hapo:impact-analysis
+├── understand possible side effects                      -> /hapo:inspect
 └── compare external approaches or best practices         -> /hapo:research
 ```
 

package/src/claude/rules/skill-workflow-routing.md

@@ -55,30 +55,21 @@ Do not turn reconstructed docs directly into implementation. Human review must a
 ## Research And Analysis Workflow
 
 ```text
-/hapo:inspect -> /hapo:impact-analysis -> /hapo:research
+/hapo:inspect -> /hapo:research
 ```
 
 | User intent | Suggested start |
 |---|---|
 | file discovery, codebase structure, source scouting | `/hapo:inspect` |
-| affected files, blast radius, dependency impact, side effects | `/hapo:impact-analysis` |
+| affected files, blast radius, dependency impact, side effects | `/hapo:inspect` |
 | external best practices, tool comparison, technical investigation | `/hapo:research` |
 
 Use `/hapo:research` for external knowledge. Use `/hapo:inspect` for local source truth.
 
-## Delegation Workflow
-
-| User intent | Suggested skill |
-|---|---|
-| assign/offload an implementation task to an external agent CLI (codex, grok) | `/hapo:delegate` |
-
-Claude Code remains the orchestrator: it writes the task brief, dispatches, monitors, and independently verifies the returned work.
-
 ## Output Artifact Workflow
 
 | User intent | Suggested skill |
 |---|---|
-| diagrams, architecture maps, Mermaid/SVG/PNG graph output | `/hapo:generate-graph` |
 | PowerPoint or slide deck creation/editing | `/hapo:pptx` |
 | Word documents | `/hapo:docx` |
 | PDF processing | `/hapo:pdf` |

package/src/claude/rules/state-sync.md

@@ -25,3 +25,7 @@ Before returning control to the user or orchestrator, the agent **MUST**:
 **Canonical state values:** New specs MUST use `status: "in_progress"` for active work. Legacy `in-progress` may be read for compatibility, but must not be emitted in new files.
 
 **Golden Rule:** If the current phase changes, or a task completes, the agent must update the physical files. Never mark a task completed before there is execution proof, and never let `task_registry` disagree with the matching markdown task file. The context is intentionally NOT persisted in the chat to save tokens. An injected Hook (`spec-state.cjs`) constantly enforces and validates this state.
+
+### Completion gate (Stop)
+
+Marking a task `done` is now machine-gated on the **Stop** hook (`spec-gate.cjs`), not only reminded on each prompt. When a turn ends with *newly-done* tasks, the gate requires a verification receipt in each task markdown: `Status: done`, an Evidence section (or legacy `Task Test Plan & Verification Evidence` / `Verification & Evidence`) with real proof (no `{{...}}` placeholders; at least one fenced command block or PASS/FAIL line), and a non-empty `task_registry[path].completed_at`. First adoption (no cache yet) seeds history without blocking. Escape hatch for humans: `"spec": { "completion_gate": false }` in `.claude/runtime.json` (missing key keeps the gate ON).

package/src/claude/runtime.json

@@ -15,6 +15,10 @@
     "docs": "docs",
     "specs": "specs"
   },
+  "spec": {
+    "scaffold_guard": true,
+    "completion_gate": true
+  },
   "locale": {
     "thinkingLanguage": null,
     "responseLanguage": null