@haposoft/cafekit 0.16.6 → 0.18.0

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

@@ -295,9 +295,6 @@ function installClaudeGate(root, policyMode = 'valid') {
     path.join(__dirname, '..', 'lib', 'hook-state-dir.cjs'),
     path.join(hooks, 'lib', 'hook-state-dir.cjs'),
   );
-  for (const name of [
-    'completion-authority-check.cjs', 'completion-authority-state.cjs', 'semantic-review-authority.cjs',
-  ]) fs.copyFileSync(path.join(__dirname, '..', name), path.join(hooks, name));
   for (const name of ['spec-resolver.cjs', 'spec-receipt.cjs', 'validate-spec-output.cjs', 'spec-ground.cjs', 'spec-semantic-model.cjs', 'spec-final-state.cjs']) {
     fs.copyFileSync(path.join(__dirname, '..', '..', 'scripts', name), path.join(scripts, name));
   }
@@ -1842,6 +1839,64 @@ test('47. completed-set branch accepts committed receipts and blocks an edited o
   }
 });
 
+test('51. Receipt fields written as list items are accepted', () => {
+  // Every neighbouring section writes its fields as list items — the Verification Plan's
+  // own `- Command:` sits a few lines above — so continuing that house style inside the
+  // Receipt is the natural mistake. It used to fail verification_state, command,
+  // exit_result and command_identity at once, with a message telling the user to rewrite
+  // a Receipt whose content was already correct.
+  const bulleted = boundReceipt().map((line) => (
+    /^(Verification|Command|Exit|Base|Head):/.test(line) ? `- ${line}` : line
+  ));
+  assert.ok(bulleted.some((line) => line.startsWith('- Verification:')), 'the fixture must be bulleted');
+  const dir = makeWorkflowFixture(bulleted);
+  try {
+    clearCache();
+    assert.strictEqual(runHook({}, dir).stdout, '', 'a bulleted Receipt must be read, not rejected');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('52. the block names what to change, not just which check failed', () => {
+  // The same sentence used to answer every receipt failure, including the ones where
+  // the Receipt was present and one field simply could not be read.
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Command: node --test', 'Exit: 0',
+    `Base: ${VALID_BASE}`, `Head: ${VALID_HEAD}`, '```text', '$ node --test', 'pass: 1', '```',
+  ]);
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block');
+    assert.match(body.reason, /add a `Verification: PASS` line/, 'the fix must name the missing field');
+    assert.doesNotMatch(body.reason, /write a runtime-bound `## Receipt` with command output/,
+      'the generic instruction must not stand in for a specific one');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('53. a hand-typed provenance pair is told to re-derive, not to add lines', () => {
+  // Reported from a project whose receipt carried git short SHAs. Telling someone to
+  // add `Base:` and `Head:` lines they had already written sends them looking in the
+  // wrong place; the pair is there, it just is not the one the runtime derives.
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', '- Verification: PASS', '- Command: node --test', '- Exit: 0',
+    '- Base: d72bb57', '- Head: 5da1eca', '```text', '$ node --test', 'pass: 1', '```',
+  ]);
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block');
+    assert.match(body.reason, /present but are not the pair this runtime derives/);
+    assert.match(body.reason, /short SHAs/);
+    assert.doesNotMatch(body.reason, /add runtime-derived/, 'the lines exist; do not ask for them again');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test('49. an unversioned specs root does not keep every receipt bound', () => {
   // Committing specs/ is the user's choice, not the tool's requirement. Without a
   // committed copy of the task file there is no baseline, so the selector used to keep
@@ -1917,3 +1972,57 @@ test('48. the gate\'s own runtime state does not defeat structure mode', () => {
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
+
+test('52. a plan with several commands binds the Receipt to the last one', () => {
+  // A proof that takes several steps declares several commands. The Receipt must name the
+  // last: naming an earlier, cheaper step would let the task close without its real proof.
+  const planned = 'node -v\n- Command: node --test';
+  const earlier = boundReceipt().map((line) => line
+    .replace('Command: node --test', 'Command: node -v').replace('$ node --test', '$ node -v'));
+  const absent = boundReceipt().map((line) => line
+    .replace('Command: node --test', 'Command: npm test').replace('$ node --test', '$ npm test'));
+  const cases = [
+    [boundReceipt(), null, 'the last declared command closes the task'],
+    [earlier, /command_identity/, 'an earlier declared command must not close the task'],
+    [absent, /command_identity/, 'a command the plan never declared must not close the task'],
+  ];
+  for (const [receipt, expected, message] of cases) {
+    const dir = makeWorkflowFixture(receipt, planned);
+    try {
+      clearCache();
+      const out = runHook({}, dir).stdout;
+      if (expected === null) {
+        assert.strictEqual(out, '', message);
+      } else {
+        const body = parseBlock(out);
+        assert.ok(body && body.decision === 'block', message);
+        assert.match(body.reason, expected, message);
+      }
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  }
+});
+
+test('53. an indented or sub-heading Command never becomes the canonical one', () => {
+  // A cheap command nested under a Counterexample, or placed under a ### step after the main
+  // block, must not become the command a Receipt can close on.
+  const cheap = boundReceipt().map((line) => line
+    .replace('Command: node --test', 'Command: true').replace('$ node --test', '$ true'));
+  for (const planned of [
+    'node --test\n- Counterexample: none\n  - Command: true',
+    'node --test\n\n### Cleanup\n\n- Command: true',
+  ]) {
+    for (const [receipt, expected] of [[cheap, /command_identity/], [boundReceipt(), null]]) {
+      const dir = makeWorkflowFixture(receipt, planned);
+      try {
+        clearCache();
+        const out = runHook({}, dir).stdout;
+        if (expected === null) assert.strictEqual(out, '', `the main command must still close: ${planned}`);
+        else assert.match(parseBlock(out).reason, expected, `a nested command must not close: ${planned}`);
+      } finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+      }
+    }
+  }
+});

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

@@ -0,0 +1,134 @@
+'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/);
+  });
+});

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');