@haposoft/cafekit 0.16.7 → 0.18.1

package/src/claude/hooks/__tests__/spec-state-touched.test.js

@@ -0,0 +1,160 @@
+'use strict';
+
+// spec-state injects the active packet's tollgate on every prompt. With several sessions in
+// one checkout, a Claude session kept seeing a packet another session was working on. On
+// Claude the hook now speaks only about packets this session touched; omp, grok and
+// payloads without a Claude session id keep the old behaviour. Each case names the failure
+// it prevents.
+
+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 CLAUDE_ROOT = path.join(__dirname, '..', '..');
+
+function taskContent(status) {
+  return ['# Task 01 — work', '', `Status: ${status}`, '', '## Dependencies', '', '- none', '',
+    '## Verification Plan', '', '- Command: node --test', ''].join('\n');
+}
+
+function writePacket(root, name) {
+  const dir = path.join(root, 'specs', name);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'plan.md'), `# ${name}\nSpecs-Contract: process-first-ready-v1\n`);
+  fs.writeFileSync(path.join(dir, 'task-01-work.md'), taskContent('pending'));
+  return dir;
+}
+
+/** A project with the installed hook tree under `<root>/<runtimeDir>/hooks` and the given packets. */
+function fixture(packets, runtimeDir = '.claude') {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-spec-touched-'));
+  const hooks = path.join(root, runtimeDir, 'hooks');
+  const scripts = path.join(root, runtimeDir, 'scripts');
+  fs.mkdirSync(path.join(hooks, 'lib'), { recursive: true });
+  fs.mkdirSync(scripts, { recursive: true });
+  fs.copyFileSync(path.join(CLAUDE_ROOT, 'hooks', 'spec-state.cjs'), path.join(hooks, 'spec-state.cjs'));
+  for (const lib of ['runtime-dir.cjs', 'hook-payload.cjs', 'hook-state-dir.cjs']) {
+    fs.copyFileSync(path.join(CLAUDE_ROOT, 'hooks', 'lib', lib), path.join(hooks, 'lib', lib));
+  }
+  for (const file of ['provenance.cjs', 'spec-receipt.cjs', 'spec-resolver.cjs', 'workflow-policy.cjs']) {
+    fs.copyFileSync(path.join(CLAUDE_ROOT, 'scripts', file), path.join(scripts, file));
+  }
+  for (const name of packets) writePacket(root, name);
+  for (const args of [['init', '-q'], ['config', 'user.email', 'cafekit@example.invalid'],
+    ['config', 'user.name', 'CafeKit Test'], ['commit', '--allow-empty', '-qm', 'fixture']]) {
+    const git = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+    assert.strictEqual(git.status, 0, git.stderr);
+  }
+  const run = (payload) => {
+    const result = spawnSync(process.execPath, [path.join(hooks, 'spec-state.cjs')], {
+      cwd: root, env: { ...process.env, PROJECT_ROOT: root },
+      input: JSON.stringify({ cwd: root, ...payload }), encoding: 'utf8',
+    });
+    assert.strictEqual(result.status, 0, result.stderr);
+    return result.stdout.trim();
+  };
+  const prompt = (session, text) => run({ hook_event_name: 'UserPromptSubmit', session_id: session, prompt: text });
+  const cacheFile = path.join(hooks, '.logs', 'tollgate-last.txt');
+  return { root, hooks, run, prompt, cacheFile, cleanup: () => fs.rmSync(root, { recursive: true, force: true }) };
+}
+
+function within(fx, fn) {
+  try { return fn(fx); } finally { fx.cleanup(); }
+}
+
+test('an untouched packet prints nothing on Claude', () => {
+  within(fixture(['auth-flow']), (fx) => {
+    assert.strictEqual(fx.prompt('s1', 'Continue'), '');
+    assert.strictEqual(fs.existsSync(fx.cacheFile), false, 'a filtered session must not claim the cache slot');
+  });
+});
+
+test('naming the packet in the prompt touches it and keeps the full block', () => {
+  within(fixture(['auth-flow']), (fx) => {
+    assert.strictEqual(fx.prompt('s1', 'Continue'), '');
+    assert.match(fx.prompt('s1', 'continue auth-flow'), /Spec state changed/);
+    assert.match(fx.prompt('s1', 'Continue'), /Tollgate active/);
+  });
+});
+
+test('editing a file inside the packet touches it silently', () => {
+  within(fixture(['auth-flow']), (fx) => {
+    // macOS tmp dirs live under /private/var behind the /var symlink; send the other spelling.
+    const real = fs.realpathSync(fx.root);
+    const alias = real.startsWith('/private/var/') ? real.slice('/private'.length) : (() => {
+      const link = path.join(os.tmpdir(), `ck-alias-${process.pid}-${Date.now()}`);
+      fs.symlinkSync(real, link);
+      return link;
+    })();
+    const edited = path.join(alias, 'specs', 'auth-flow', 'plan.md');
+    assert.notStrictEqual(edited, fs.realpathSync(edited), 'the path sent must not be canonical');
+    const out = fx.run({ hook_event_name: 'PostToolUse', session_id: 's2', tool_name: 'Edit', tool_input: { file_path: edited } });
+    assert.strictEqual(out, '');
+    assert.strictEqual(fs.existsSync(fx.cacheFile), false, 'a touch record must not run the tollgate');
+    assert.match(fx.prompt('s2', 'Continue'), /Spec state changed/);
+    if (!real.startsWith('/private/var/')) fs.rmSync(alias, { force: true });
+  });
+});
+
+test('a plain one-word slug needs specs/ prefix', () => {
+  within(fixture(['docs']), (fx) => {
+    assert.strictEqual(fx.prompt('s1', 'fix the docs'), '');
+    assert.match(fx.prompt('s1', 'look at specs/docs'), /Spec state changed/);
+  });
+});
+
+test("another session's touch does not leak", () => {
+  within(fixture(['auth-flow']), (fx) => {
+    assert.match(fx.prompt('s3', 'specs/auth-flow'), /Spec state changed/);
+    assert.strictEqual(fx.prompt('s4', 'Continue'), '');
+  });
+});
+
+test('omp, grok and session-less payloads keep the old behaviour', () => {
+  within(fixture(['auth-flow'], '.omp'), (fx) => {
+    assert.match(fx.prompt('s5', 'Continue'), /Spec state changed/, 'omp is unchanged');
+  });
+  within(fixture(['auth-flow']), (fx) => {
+    assert.match(fx.run({ hook_event_name: 'UserPromptSubmit', sessionId: 's6', prompt: 'Continue' }), /Spec/, 'grok sends sessionId');
+  });
+  within(fixture(['auth-flow']), (fx) => {
+    assert.match(fx.run({ hook_event_name: 'UserPromptSubmit', prompt: 'Continue' }), /Spec/, 'no session id');
+  });
+});
+
+test('a prompt touch is remembered even when two packets are active', () => {
+  within(fixture(['auth-flow', 'billing-2']), (fx) => {
+    assert.match(fx.prompt('s7', 'work on specs/auth-flow'), /Multiple active specs/);
+    fs.rmSync(path.join(fx.root, 'specs', 'billing-2'), { recursive: true, force: true });
+    assert.match(fx.prompt('s7', 'Continue'), /auth-flow/);
+  });
+});
+
+function writeLegacyPacket(root, name) {
+  const dir = path.join(root, 'specs', name);
+  fs.mkdirSync(path.join(dir, 'tasks'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'spec.json'), JSON.stringify({ feature_name: name, status: 'in_progress' }));
+}
+
+const LEGACY_NOTICE = /`specs\/old` is a legacy Specs packet without plan\.md; CafeKit no longer reads it/;
+
+test('a leftover legacy packet is noticed once per session, before the touch filter', () => {
+  within(fixture(['auth-flow']), (fx) => {
+    writeLegacyPacket(fx.root, 'old');
+    const first = fx.prompt('s1', 'Continue');
+    assert.match(first, LEGACY_NOTICE);
+    assert.strictEqual(first.match(new RegExp(LEGACY_NOTICE.source, 'g')).length, 1);
+    assert.strictEqual(fx.prompt('s1', 'Continue'), '', 'the same session is not told twice');
+    assert.match(fx.prompt('s2', 'Continue'), LEGACY_NOTICE, 'a new session is told once');
+  });
+});
+
+test('a legacy packet is noticed even when it is the only packet', () => {
+  within(fixture([]), (fx) => {
+    writeLegacyPacket(fx.root, 'old');
+    assert.match(fx.prompt('s1', 'Continue'), LEGACY_NOTICE);
+  });
+});

package/src/claude/hooks/__tests__/state.test.js

@@ -316,3 +316,71 @@ test('Stop snapshot includes untracked files before the first commit', () => {
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
+
+// The SessionStart block used to print even when it held only headings, placeholders and
+// timestamp-only agent results, which told a resumed Claude session nothing.
+const PLACEHOLDER_STATE = [
+  '# Session State',
+  '<!-- Generated: GENERATED -->',
+  '<!-- Branch: unknown -->',
+  '',
+  '## What Worked (Verified)',
+  '- (No completed tasks recorded)',
+  '',
+  "## What's Left",
+  '- (All tasks completed)',
+  '',
+  '## Key Files Modified',
+  '- (No file changes detected)',
+  '',
+  '## Agent Result: code-auditor (01:44:00)',
+  '- Completed at 01:44:00',
+  '',
+  '## Agent Result: code-auditor (01:44:21)',
+  '- Completed at 01:44:21',
+  '',
+  '## Agent Result: code-auditor (01:44:50)',
+  '- Completed at 01:44:50',
+  '',
+].join('\n');
+
+function sessionStartWith(content, runtimeFolder = '.claude') {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-state-start-'));
+  try {
+    let hook = STATE_HOOK;
+    if (runtimeFolder !== '.claude') {
+      const hooks = path.join(dir, runtimeFolder, 'hooks');
+      fs.mkdirSync(path.join(hooks, 'lib'), { recursive: true });
+      fs.copyFileSync(STATE_HOOK, path.join(hooks, 'state.cjs'));
+      for (const lib of ['parser.cjs', 'runtime-dir.cjs', 'hook-payload.cjs', 'hook-state-dir.cjs']) {
+        fs.copyFileSync(path.join(path.dirname(STATE_HOOK), 'lib', lib), path.join(hooks, 'lib', lib));
+      }
+      hook = path.join(hooks, 'state.cjs');
+    }
+    const stateFolder = path.join(dir, runtimeFolder, 'session-state');
+    fs.mkdirSync(stateFolder, { recursive: true });
+    fs.writeFileSync(path.join(stateFolder, 'latest.md'), content.replace('GENERATED', new Date().toISOString()));
+    const result = spawnSync(process.execPath, [hook], {
+      cwd: dir,
+      input: JSON.stringify({ hook_event_name: 'SessionStart', session_id: 'start-1', cwd: dir }),
+      encoding: 'utf8',
+    });
+    assert.strictEqual(result.status, 0, result.stderr);
+    return result.stdout.trim();
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test('SessionStart prints nothing when prior context is only placeholders', () => {
+  assert.strictEqual(sessionStartWith(PLACEHOLDER_STATE), '');
+});
+
+test('SessionStart prints prior context that has a completed todo', () => {
+  const withTodo = PLACEHOLDER_STATE.replace('- (No completed tasks recorded)', '- Ship the statusline');
+  assert.match(sessionStartWith(withTodo), /Prior Execution Context[\s\S]*Ship the statusline/);
+});
+
+test('SessionStart under .omp keeps printing placeholder-only context', () => {
+  assert.match(sessionStartWith(PLACEHOLDER_STATE, '.omp'), /Prior Execution Context/);
+});

package/src/claude/hooks/__tests__/statusline.test.js

@@ -10,6 +10,9 @@ const path = require('node:path');
 const STATUS_PATH = path.resolve(__dirname, '..', '..', 'status.cjs');
 const GOLDEN_PATH = path.join(__dirname, 'fixtures', 'statusline-default.golden');
 const NBSP = / /g;
+const ANSI = /\x1b\[[0-9;]*m/g;
+/** Visible text: colour codes removed, non-breaking spaces read as spaces, reset countdown masked. */
+const visible = (text) => text.replace(ANSI, '').replace(NBSP, ' ').replace(/\d+h\d+m/g, '<reset>');
 
 const cleanupDirs = [];
 process.on('exit', () => {
@@ -79,6 +82,16 @@ function runStatus({ runtime = { statusline: 'full', statuslineColors: true }, p
   }
 }
 
+/** Claude Code's own quota payload: used percentages and epoch-second resets 2h29m and 2d5h ahead. */
+function rateLimits({ fiveHour = 20, weekly = 45 } = {}) {
+  const nowSec = Math.floor(Date.now() / 1000);
+  return {
+    five_hour: { used_percentage: fiveHour, resets_at: nowSec + 2 * 3600 + 29 * 60 + 30 },
+    seven_day: { used_percentage: weekly, resets_at: nowSec + 2 * 86400 + 5 * 3600 },
+  };
+}
+
+/** The file the retired usage hook used to write; the statusline must ignore it. */
 function freshUsageCache(now = Date.now()) {
   return {
     status: 'available',
@@ -138,21 +151,19 @@ test('statusline empty or invalid layout falls back to the default renderers', (
   }
 });
 
-test('statusline shows five-hour and weekly windows with countdowns when the cache is fresh', () => {
-  const run = runStatus({ tmpFiles: { 'ck-usage-limits-cache.json': freshUsageCache() } });
+test('statusline shows five-hour and weekly windows with countdowns from the payload', () => {
+  const run = runStatus({ payload: basePayload({ rate_limits: rateLimits() }) });
   assert.equal(run.status, 0, run.stderr);
-  const plain = run.stdout.replace(NBSP, ' ');
-  assert.match(plain, /⌛ \d+h \d+m left \(20% used\)/, plain);
-  assert.match(plain, /wk 45% \(\d+d \d+h\)/, plain);
+  const plain = visible(run.stdout);
+  assert.match(plain, /⧗ 20% <reset>/, plain);
+  assert.match(plain, /◷ 45%/, plain);
 });
 
-test('statusline hides the quota area when the cache is stale', () => {
-  const stale = freshUsageCache(Date.now() - 10 * 60 * 1000);
-  stale.timestamp = Date.now() - 10 * 60 * 1000;
-  const run = runStatus({ tmpFiles: { 'ck-usage-limits-cache.json': stale } });
+test('statusline shows no quota when the payload has no rate_limits, even with a fresh usage cache', () => {
+  const run = runStatus({ tmpFiles: { 'ck-usage-limits-cache.json': freshUsageCache() } });
   assert.equal(run.status, 0, run.stderr);
-  assert.doesNotMatch(run.stdout, /⌛/);
-  assert.doesNotMatch(run.stdout, /wk /);
+  assert.doesNotMatch(run.stdout, /⧗/);
+  assert.doesNotMatch(run.stdout, /◷/);
 });
 
 test('statusline cost renders only when the layout enables it, billing is api, and data exists', () => {
@@ -194,3 +205,121 @@ test('statusline honors NO_COLOR with no ANSI escapes in output', () => {
   assert.equal(run.status, 0, run.stderr);
   assert.doesNotMatch(run.stdout, /\[/);
 });
+
+test('statusline default is one labelled line and narrow terminals drop the least useful parts first', () => {
+  const payload = basePayload({ rate_limits: rateLimits(), cost: { total_lines_added: 120, total_lines_removed: 30 } });
+  const plainLines = (run) => visible(run.stdout).trimEnd().split('\n');
+  const runtime = { statusline: 'full', statuslineColors: false };
+
+  const wide = runStatus({ runtime, payload });
+  assert.equal(wide.status, 0, wide.stderr);
+  assert.deepEqual(plainLines(wide), ['◆ TestModel  ◑ 53%  ⧗ 20% <reset>  ◷ 45%  ± +120/-30']);
+
+  const narrow = runStatus({ runtime, payload, envExtra: { COLUMNS: '34' } });
+  assert.deepEqual(plainLines(narrow), ['◆ TestModel  ◑ 53%  ⧗ 20% <reset>']);
+  const tiny = runStatus({ runtime, payload, envExtra: { COLUMNS: '10' } });
+  assert.deepEqual(plainLines(tiny), ['◆ TestModel  ◑ 53%']);
+});
+
+test('statusline compact is the default line alone and minimal keeps model and context', () => {
+  const payload = basePayload({ rate_limits: rateLimits() });
+  const plain = (run) => visible(run.stdout).trimEnd();
+  const compact = runStatus({ runtime: { statusline: 'compact', statuslineColors: false }, payload });
+  assert.equal(plain(compact), '◆ TestModel  ◑ 53%  ⧗ 20% <reset>  ◷ 45%');
+  const minimal = runStatus({ runtime: { statusline: 'minimal', statuslineColors: false }, payload });
+  assert.equal(plain(minimal), '◆ TestModel  ◑ 53%');
+});
+
+test('statusline colours percentages by threshold and prints no escape when statuslineColors is false', () => {
+  const hot = basePayload({ rate_limits: rateLimits({ fiveHour: 90 }) });
+  const coloured = runStatus({ payload: hot });
+  assert.match(coloured.stdout, /\x1b\[31m90%/, 'a five-hour quota at 90% is red');
+  assert.match(coloured.stdout, /\x1b\[32m◑[ \u00A0]53%/, 'context at 53% is green');
+  const plain = runStatus({ runtime: { statusline: 'full', statuslineColors: false }, payload: hot });
+  assert.doesNotMatch(plain.stdout, /\x1b\[/);
+});
+
+test('statusline shows the live effort level next to the model, and nothing when the payload has none', () => {
+  const runtime = { statusline: 'minimal', statuslineColors: false };
+  const withEffort = runStatus({ runtime, payload: basePayload({ effort: { level: 'xhigh' } }) });
+  assert.equal(visible(withEffort.stdout).trimEnd(), '◆ TestModel (xhigh)  ◑ 53%');
+  const narrow = runStatus({ runtime: { statusline: 'full', statuslineColors: false }, payload: basePayload({ effort: { level: 'high' } }), envExtra: { COLUMNS: '10' } });
+  assert.equal(visible(narrow.stdout).trimEnd(), '◆ TestModel (high)  ◑ 53%', 'effort travels with the model and never drops');
+  const without = runStatus({ runtime });
+  assert.equal(visible(without.stdout).trimEnd(), '◆ TestModel  ◑ 53%');
+});
+
+test('statusline reads quota from the payload rate_limits', () => {
+  const nowSec = Math.floor(Date.now() / 1000);
+  const payload = basePayload({ rate_limits: {
+    five_hour: { used_percentage: 36, resets_at: nowSec + 2 * 3600 + 12 * 60 + 30 },
+    seven_day: { used_percentage: 43, resets_at: nowSec + 2 * 86400 },
+  } });
+  const run = runStatus({ runtime: { statusline: 'compact', statuslineColors: false }, payload,
+    tmpFiles: { 'ck-usage-limits-cache.json': freshUsageCache() } });
+  assert.equal(visible(run.stdout).trimEnd(), '◆ TestModel  ◑ 53%  ⧗ 36% <reset>  ◷ 43%', 'the payload is the only source (the cache says 20%/45%)');
+});
+
+test('statusline layout quota section renders from the payload', () => {
+  const run = runStatus({
+    runtime: { statusline: 'full', statuslineColors: false, statuslineLayout: { lines: [['quota']] } },
+    payload: basePayload({ rate_limits: rateLimits({ fiveHour: 36, weekly: 43 }) }),
+  });
+  assert.equal(run.status, 0, run.stderr);
+  // Not visible(): its mask matches only \d+h\d+m, and the layout prints "2h 29m" plus a
+  // weekly countdown that can roll over between seconds.
+  const line = run.stdout.replace(ANSI, '').replace(NBSP, ' ').trimEnd();
+  assert.match(line, /⌛ \d+h \d+m left \(36% used\)  wk 43% \(\d+d \d+h\)/, line);
+});
+
+/** A throwaway git repo on branch `feat`, so git, PR and worktree marks have a branch to ride on. */
+function gitRepo() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sl-git-'));
+  cleanupDirs.push(dir);
+  for (const args of [['init', '-q', '-b', 'feat'], ['-c', 'user.email=t@t', '-c', 'user.name=t', 'commit', '-q', '--allow-empty', '-m', 'init']]) {
+    const r = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8' });
+    assert.equal(r.status, 0, r.stderr);
+  }
+  return dir;
+}
+
+const stripAnsi = (text) => text.replace(ANSI, '').replace(NBSP, ' ').trimEnd();
+
+test('statusline shows fast mode, thinking, PR state, worktree, session time and cache hit only when present', () => {
+  const runtime = { statusline: 'compact', statuslineColors: false };
+  const repo = gitRepo();
+  const rich = basePayload({
+    fast_mode: true,
+    thinking: { enabled: true },
+    pr: { number: 80, review_state: 'approved' },
+    workspace: { current_dir: repo, git_worktree: 'feat-x' },
+    cost: { total_duration_ms: 28147114 },
+    prompt_cache: { requests: 77, hit_ratio: 0.986 },
+  });
+  assert.equal(stripAnsi(runStatus({ runtime, payload: rich }).stdout), '◆ TestModel ϟ✱  ◑ 53%  ⎇ feat #80✓ ⊟  ⏱ 7h49m  ↻ 99%');
+
+  const off = basePayload({
+    fast_mode: false, thinking: { enabled: false }, workspace: { current_dir: repo },
+    cost: { total_duration_ms: 30000 }, prompt_cache: { requests: 0, hit_ratio: 0 },
+  });
+  assert.equal(stripAnsi(runStatus({ runtime, payload: off }).stdout), '◆ TestModel  ◑ 53%  ⎇ feat');
+});
+
+test('statusline marks each PR review state and a GitLab merge request', () => {
+  const runtime = { statusline: 'minimal', statuslineColors: true };
+  const repo = gitRepo();
+  const line = (pr) => runStatus({ runtime: { statusline: 'compact', statuslineColors: true }, payload: basePayload({ pr, workspace: { current_dir: repo } }) }).stdout;
+  assert.match(line({ number: 7, review_state: 'approved' }), /#7\x1b\[32m✓/);
+  assert.match(line({ number: 7, review_state: 'changes_requested' }), /#7\x1b\[31m✗/);
+  assert.match(line({ number: 7, review_state: 'draft' }), /\x1b\[2m#7\x1b\[0m/);
+  assert.match(stripAnsi(line({ number: 7, review_state: 'pending' })), /⎇ feat #7$/);
+  assert.match(stripAnsi(line({ number: 12, kind: 'mr' })), /⎇ feat !12$/);
+  assert.doesNotMatch(runStatus({ runtime, payload: basePayload({ pr: { number: 7 }, workspace: { current_dir: repo } }) }).stdout, /#7/, 'minimal keeps only the branch name');
+});
+
+test('statusline drops session time and cache before changes on a narrow terminal', () => {
+  const payload = basePayload({ cost: { total_duration_ms: 28147114, total_lines_added: 5, total_lines_removed: 1 }, prompt_cache: { requests: 3, hit_ratio: 0.4 } });
+  const runtime = { statusline: 'full', statuslineColors: false };
+  assert.equal(stripAnsi(runStatus({ runtime, payload, envExtra: { COLUMNS: '34' } }).stdout), '◆ TestModel  ◑ 53%  ± +5/-1');
+  assert.equal(stripAnsi(runStatus({ runtime, payload, envExtra: { COLUMNS: '44' } }).stdout), '◆ TestModel  ◑ 53%  ± +5/-1  ⏱ 7h49m');
+});

package/src/claude/hooks/agent.cjs

@@ -59,6 +59,7 @@ try {
   const baseDir    = agentCwd;
   const plansPath  = path.join(baseDir, runtime.paths?.plans || 'plans');
   const docsPath   = path.join(baseDir, runtime.paths?.docs  || 'docs');
+  const specsPath  = path.join(baseDir, runtime.paths?.specs || 'specs');
 
   // Build context block
   const lines = [];
@@ -76,7 +77,7 @@ try {
   const venv = resolveVenv(agentCwd);
 
   lines.push('## Rules');
-  lines.push(`- Plans → ${plansPath}/ | Docs → ${docsPath}/`);
+  lines.push(`- Specs → ${specsPath}/ | Plans → ${plansPath}/ | Docs → ${docsPath}/`);
   if (venv) {
     lines.push(`- Python in ${skillsDir()}/: use \`${venv}\``);
     lines.push('- Never use global pip install');

package/src/claude/hooks/lib/hook-payload.cjs

@@ -54,8 +54,8 @@ const EVENT_NAMES = Object.freeze({
  * Grok's registry and matcher aliases come first, then omp's lowercase registry. Where
  * both hosts use a spelling (`write`, `grep`) they agree on the destination. `write` is
  * grok's file-creating tool and maps to `Write`, while `search_replace` edits an existing
- * file and maps to `Edit`; conflating them would make the scaffold guard reject ordinary
- * edits. `delete_file` maps to `Write` so a delete is gated like any other file write.
+ * file and maps to `Edit`, which keeps grok's file creation distinct from an edit.
+ * `delete_file` maps to `Write` so a delete is gated like any other file write.
  */
 const TOOL_ALIASES = Object.freeze({
   // grok — every spelling that reaches a Bash matcher

package/src/claude/hooks/rules.cjs

@@ -70,6 +70,7 @@ try {
   const baseDir   = cwd;
   const plansPath = path.join(baseDir, runtime.paths?.plans || 'plans');
   const docsPath  = path.join(baseDir, runtime.paths?.docs  || 'docs');
+  const specsPath = path.join(baseDir, runtime.paths?.specs || 'specs');
   const maxLoc    = runtime.docs?.maxLoc || 800;
 
   const lines = [];
@@ -84,7 +85,7 @@ try {
 
   lines.push(
     '## Rules',
-    `- Markdown files: Plans → "${plansPath}/" | Docs → "${docsPath}/"`,
+    `- Markdown files: Specs → "${specsPath}/" | Plans → "${plansPath}/" | Docs → "${docsPath}/"`,
     '- **DO NOT** create markdown files outside of those directories unless explicitly asked.',
     `- docs.maxLoc: ${maxLoc} lines max per doc file`
   );

package/src/claude/hooks/session.cjs

@@ -202,7 +202,6 @@ try {
   const envFile = process.env.CLAUDE_ENV_FILE;
   const cwd     = projectRoot();
   const runtime = readRuntime(cwd);
-  try { require('./completion-authority-state.cjs').clearState(cwd, payload.session_id); } catch { /* old installs remain fail-open */ }
 
   // Check CafeKit update in parallel with project detection (async, fail-open).
   const updateCheckPromise = checkCafeKitUpdate(cwd);

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

@@ -90,17 +90,16 @@ try {
   let POLICY;
   let RESOLVER;
   let RECEIPT;
-  let FINAL_STATE;
   try {
     POLICY = require(policyPath);
+    // One gate run checks every done receipt against the same checkout; capture it once.
+    require(path.join(__dirname, '..', 'scripts', 'provenance.cjs')).enableSnapshotMemo();
     RESOLVER = require(path.join(__dirname, '..', 'scripts', 'spec-resolver.cjs'));
     RECEIPT = require(path.join(__dirname, '..', 'scripts', 'spec-receipt.cjs'));
-    FINAL_STATE = require('./completion-authority-check.cjs');
     if (typeof POLICY.validateCanonicalReceipt !== 'function'
-      || typeof POLICY.completionDecisionForSpec !== 'function'
-      || typeof RECEIPT.checkTaskReceipt !== 'function'
+      || typeof RECEIPT.checkWorkflowTaskReceipt !== 'function'
       || typeof RECEIPT.checkWorkflowReceiptSet !== 'function'
-      || typeof FINAL_STATE.evaluateCloseout !== 'function') {
+      || typeof RESOLVER.resolveWorkflowCandidate !== 'function') {
       throw new Error('shared workflow policy lacks completion authority functions');
     }
   } catch (error) {
@@ -127,9 +126,7 @@ try {
     || (typeof RESOLVER.readActiveFeatureTarget === 'function'
       ? RESOLVER.readActiveFeatureTarget({ projectRoot: baseDir, runtime })
       : null);
-  let resolved = typeof RESOLVER.resolveWorkflowCandidate === 'function'
-    ? RESOLVER.resolveWorkflowCandidate({ projectRoot: baseDir, runtime, target, includeCompleted: true })
-    : FINAL_STATE.resolveCandidate({ resolver: RESOLVER, projectRoot: baseDir, runtime, payload });
+  let resolved = RESOLVER.resolveWorkflowCandidate({ projectRoot: baseDir, runtime, target, includeCompleted: true });
   if (typeof RESOLVER.refineWorkflowGateResolution === 'function') {
     resolved = RESOLVER.refineWorkflowGateResolution(resolved);
   }
@@ -150,7 +147,7 @@ try {
     const lines = [`⚠️ Completion gate: ${checked.failures.length} done task(s) lack a verification receipt.`];
     for (const failure of checked.failures) {
       lines.push(`- \`${failure.featureName}/${failure.taskPath}\`: failed check(s) ${failure.failures.join(', ')}`);
-      const hint = typeof RECEIPT.receiptFixHint === 'function' ? RECEIPT.receiptFixHint(failure.failures) : null;
+      const hint = typeof RECEIPT.receiptFixHint === 'function' ? RECEIPT.receiptFixHint(failure.failures, failure.body) : null;
       lines.push(`  Fix in \`specs/${failure.featureName}/${failure.taskPath}\`: ${hint || 'write a runtime-bound `## Receipt` with the planned command'}.`);
     }
     emitBlock(lines.slice(0, 8).join('\n'));
@@ -166,7 +163,7 @@ try {
   if (resolved.error === 'invalid_specs') {
     process.stdout.write(JSON.stringify({
       decision: 'block',
-      reason: `Completion gate: invalid spec JSON detected (${resolved.candidates.join(', ')}): ${resolved.reason}. Fix or remove malformed spec.json before completing tasks.`
+      reason: `Completion gate: invalid workflow packet detected (${resolved.candidates.join(', ')}): ${resolved.reason}. Fix the packet's plan.md or task files before completing tasks.`,
     }) + '\n');
     process.exit(0);
   }
@@ -179,31 +176,12 @@ try {
   }
   if (resolved.error) process.exit(0);
 
-  const activeSpec = resolved.spec || {};
-  const processWorkflow = resolved.layoutKind === 'process-v3';
   const featureName = resolved.featureName;
   const specsPath = resolved.specsDir;
-  const lifecyclePhase = activeSpec.current_phase || activeSpec.phase;
-  const explicitCloseout = ['done', 'completed', 'complete'].includes(activeSpec.status)
-    || ['closeout', 'completion', 'completed', 'complete'].includes(lifecyclePhase);
-  if (!processWorkflow && activeSpec.schema_version === '2.1') {
-    const finalState = FINAL_STATE.evaluateCloseout({
-      resolver: RESOLVER,
-      policy: POLICY,
-      projectRoot: baseDir,
-      runtime,
-      payload: { ...payload, session_id: sessionIdentity(payload) },
-    });
-    if (!finalState.ok) {
-      emitBlock(`Completion gate: ${finalState.reason}`);
-      process.exit(0);
-    }
-    if (finalState.active) process.exit(0);
-  }
   const runtimeContext = POLICY.deriveRuntimeContext({
     projectRoot: baseDir,
     specsRoot: specsPath,
-    specFile: resolved.stateFile || resolved.specFile || path.join(specsPath, featureName, 'spec.json'),
+    specFile: resolved.stateFile,
     featureName,
     runtimeSession: sessionIdentity(payload),
   });
@@ -213,7 +191,7 @@ try {
     emitBlock('Completion gate: runtime.spec.completion_gate is a worker-writable flag, not an authorization; no completion-gate bypass is supported. Remove the flag and satisfy the gate.');
     process.exit(0);
   }
-  const taskRegistry = resolved.taskRegistry || activeSpec.task_registry || {};
+  const taskRegistry = resolved.taskRegistry || {};
   const cacheFile = path.join(require('./lib/hook-state-dir.cjs').hookStateDir(), 'spec-gate-last.json');
   const cacheExists = fs.existsSync(cacheFile);
   let cache = {};
@@ -226,17 +204,6 @@ try {
     currentStatuses[tp] = task?.status || 'pending';
   }
 
-  const staleFlashTasks = processWorkflow ? [] : Object.entries(taskRegistry)
-    .filter(([, task]) => POLICY.isStaleFlashDone(task))
-    .map(([taskPath]) => taskPath);
-  if (staleFlashTasks.length > 0) {
-    process.stdout.write(JSON.stringify({
-      decision: 'block',
-      reason: `Completion gate: ${staleFlashTasks.length} task(s) marked done with FLASH_UNVERIFIED (${staleFlashTasks.join(', ')}). Run /cf:test for exact proof, then use explicit sync-finalize.`
-    }) + '\n');
-    process.exit(0);
-  }
-
   // Cache hardening: every Stop re-reads and re-checks the receipt of every
   // task currently marked done, so a cached PASS cannot hide later mutations
   // (deletion, placeholder, changed Verification/Command/Exit, missing
@@ -251,29 +218,11 @@ try {
   );
   const featureDir = path.join(specsPath, featureName);
   const failures = allDoneTasks
-    .map((taskPath) => ({
-      taskPath,
-      fails: processWorkflow
-        ? RECEIPT.checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, POLICY).failures
-        : RECEIPT.checkTaskReceipt(featureDir, taskPath, taskRegistry[taskPath], runtimeContext, POLICY).failures,
-    }))
-    .filter((f) => f.fails.length > 0);
-
-  const featureCloseoutRequired = !processWorkflow && explicitCloseout && allDoneTasks.length > 0;
-  const featureReceipt = featureCloseoutRequired
-    ? RECEIPT.checkFeatureReceipt(featureDir, runtimeContext, POLICY)
-    : null;
-  if (featureReceipt && featureReceipt.failures.length) {
-    failures.push({ taskPath: 'feature-receipt.md', fails: featureReceipt.failures });
-  }
-  const completion = featureCloseoutRequired && featureReceipt?.failures.length === 0
-    && Object.prototype.hasOwnProperty.call(activeSpec, 'workflow_policy')
-    ? POLICY.completionDecisionForSpec(activeSpec, {
-      runtimeContext,
-      executionReceipt: featureReceipt.body,
-      taskContext: {},
+    .map((taskPath) => {
+      const proof = RECEIPT.checkWorkflowTaskReceipt(featureDir, taskPath, runtimeContext, POLICY);
+      return { taskPath, fails: proof.failures, body: proof.body };
     })
-    : null;
+    .filter((f) => f.fails.length > 0);
 
   // Always persist status transitions, including done → pending. Keep
   // failing done tasks at their previous cached status so a stale valid
@@ -290,27 +239,12 @@ try {
     fs.writeFileSync(cacheFile, JSON.stringify(cache));
   } catch { /* fail-open */ }
 
-  const completionBlocked = completion && completion.completion !== 'complete' && completion.completion !== 'not_applicable';
-  if (failures.length === 0 && !completionBlocked) process.exit(0);
+  if (failures.length === 0) process.exit(0);
 
-  const lines = [
-    failures.length > 0
-      ? `⚠️ Completion gate: ${failures.length} done task(s) lack a verification receipt.`
-      : '⚠️ Completion gate: workflow completion proof is incomplete.',
-  ];
-  for (const { taskPath, fails } of failures) {
+  const lines = [`⚠️ Completion gate: ${failures.length} done task(s) lack a verification receipt.`];
+  for (const { taskPath, fails, body } of failures) {
     lines.push(`- \`${taskPath}\`: failed check(s) ${fails.join(', ')}`);
-    lines.push(taskPath === 'feature-receipt.md'
-      ? `  Fix: run final integration proof, then write \`specs/${featureName}/feature-receipt.md\`.`
-      : processWorkflow
-        ? `  Fix in \`specs/${featureName}/${path.posix.basename(taskPath)}\`: ${(typeof RECEIPT.receiptFixHint === 'function' && RECEIPT.receiptFixHint(fails)) || 'write a runtime-bound `## Receipt` with command output'}.`
-        : `  Fix: write canonical proof to \`specs/${featureName}/receipts/${path.posix.basename(taskPath)}\`; legacy \`## Evidence\` remains read-compatible.`);
-  }
-  if (completionBlocked) {
-    lines.push(`- Completion decision unfinished: ${completion.blocker || 'required workflow proof is missing.'}`);
-    if (Array.isArray(completion.missingProof) && completion.missingProof.length > 0) {
-      lines.push(`  Missing proof: ${completion.missingProof.join(', ')}`);
-    }
+    lines.push(`  Fix in \`specs/${featureName}/${path.posix.basename(taskPath)}\`: ${(typeof RECEIPT.receiptFixHint === 'function' && RECEIPT.receiptFixHint(fails, body)) || 'write a runtime-bound `## Receipt` with command output'}.`);
   }
   process.stdout.write(JSON.stringify({ decision: 'block', reason: lines.slice(0, 8).join('\n') }) + '\n');
   process.exit(0);