@haposoft/cafekit 0.16.0 → 0.16.1

package/bin/phases/omp-runtime.js

@@ -0,0 +1,140 @@
+'use strict';
+
+/**
+ * Phase: Oh My Pi runtime.
+ *
+ * omp discovers `.claude/skills` and `.agents/skills` on its own, so CafeKit copies no
+ * skill payload here. What omp does not have is CafeKit's enforcement chain, so this
+ * phase provisions what carries it:
+ *
+ *   .omp/hooks/           the gate scripts: the Claude set, with omp's overlay on top
+ *   .omp/extensions/      the bridge omp auto-loads, which dispatches those scripts
+ *   .omp/runtime.json     the hooks' configuration, beside the schema that describes it
+ *   .omp/rules/           the rules the hooks inject
+ *
+ * The hooks are portable: they derive their runtime directory from their own location,
+ * so the Claude bytes run unchanged under `.omp/`. Only the files that genuinely differ
+ * for omp live in `src/omp/hooks/` and are written over the Claude set afterwards, so a
+ * change to a shared hook reaches omp without anyone remembering to re-fork it.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { PLATFORMS } = require('../lib/context');
+const { writeManagedFile, copyManagedTree } = require('../lib/managed-writer');
+const { report, treeAction } = require('./report');
+const { copyRulesDirectory } = require('./claude-runtime');
+
+const SRC = path.join(__dirname, '../../src');
+const CLAUDE_SRC = path.join(SRC, 'claude');
+const OMP_SRC = path.join(SRC, 'omp');
+
+/** Files under `src/omp/hooks/` that replace their Claude counterpart, relative to the hooks dir. */
+function overlayFiles(dir = path.join(OMP_SRC, 'hooks'), prefix = '') {
+  if (!fs.existsSync(dir)) return [];
+  const found = [];
+  for (const name of fs.readdirSync(dir)) {
+    const rel = prefix ? `${prefix}/${name}` : name;
+    if (fs.statSync(path.join(dir, name)).isDirectory()) found.push(...overlayFiles(path.join(dir, name), rel));
+    else found.push(rel);
+  }
+  return found.sort();
+}
+
+/**
+ * The Claude hook set is the list the migration manifest ships to `.claude/`, not a
+ * directory walk: the source tree also holds `__tests__/`, which must never install.
+ */
+function claudeHookFiles(ctx) {
+  const files = ctx.manifest?.runtime?.files || [];
+  return files.filter((rel) => rel.startsWith('hooks/')).map((rel) => rel.slice('hooks/'.length));
+}
+
+function writeSourceFile(ctx, platformKey, src, dest, label) {
+  const platform = PLATFORMS[platformKey];
+  const { action } = writeManagedFile({
+    src,
+    dest,
+    platformFolder: platform.folder,
+    ctx,
+    tracker: ctx.trackers[platformKey]
+  });
+  report(ctx, action, label);
+}
+
+function installHooks(ctx, platformKey) {
+  const platform = PLATFORMS[platformKey];
+  const overlay = new Set(overlayFiles());
+  // Claude set first, skipping anything the overlay is about to replace so a file is
+  // written once and the manifest records the bytes that actually land.
+  for (const rel of claudeHookFiles(ctx)) {
+    if (overlay.has(rel)) continue;
+    writeSourceFile(
+      ctx,
+      platformKey,
+      path.join(CLAUDE_SRC, 'hooks', rel),
+      path.join(platform.folder, 'hooks', rel),
+      `omp hooks: ${rel}`
+    );
+  }
+  for (const rel of overlay) {
+    writeSourceFile(
+      ctx,
+      platformKey,
+      path.join(OMP_SRC, 'hooks', rel),
+      path.join(platform.folder, 'hooks', rel),
+      `omp hooks (overlay): ${rel}`
+    );
+  }
+}
+
+function installRuntimeFiles(ctx, platformKey) {
+  const platform = PLATFORMS[platformKey];
+  writeSourceFile(
+    ctx,
+    platformKey,
+    path.join(OMP_SRC, 'runtime.json'),
+    path.join(platform.folder, 'runtime.json'),
+    'omp runtime: runtime.json'
+  );
+  // One canonical runtime schema lives in the Claude source tree; every installed
+  // runtime references it as ./runtime.schema.json beside its runtime.json.
+  writeSourceFile(
+    ctx,
+    platformKey,
+    path.join(CLAUDE_SRC, 'runtime.schema.json'),
+    path.join(platform.folder, 'runtime.schema.json'),
+    'omp runtime schema'
+  );
+}
+
+function installBridge(ctx, platformKey) {
+  const platform = PLATFORMS[platformKey];
+  const bridgeSource = path.join(OMP_SRC, 'extensions');
+  const bridgeDest = path.join(platform.folder, 'extensions');
+  if (fs.existsSync(bridgeSource)) {
+    const bridge = copyManagedTree({
+      src: bridgeSource,
+      dest: bridgeDest,
+      platformFolder: platform.folder,
+      ctx,
+      tracker: ctx.trackers[platformKey]
+    });
+    report(ctx, treeAction(bridge), 'omp bridge extension');
+  } else if (!ctx.dryRun) {
+    // A half-provisioned install is visibly empty rather than silently absent.
+    fs.mkdirSync(bridgeDest, { recursive: true });
+    ctx.ui.detail('  ✓ omp extensions directory created (bridge not present)');
+  }
+}
+
+function installOmpRuntime(ctx, platformKey) {
+  if (platformKey !== 'omp') return;
+  installHooks(ctx, platformKey);
+  installRuntimeFiles(ctx, platformKey);
+  installBridge(ctx, platformKey);
+  copyRulesDirectory(ctx, platformKey);
+  return ctx;
+}
+
+module.exports = { installOmpRuntime, overlayFiles, claudeHookFiles };

package/bin/phases/root-config.js

@@ -110,6 +110,9 @@ function ensureGitignore(ctx) {
     // Local runtime payload — reinstall with npx; keep out of git
     '.claude/',
     '.codex/',
+    // omp auto-executes every file in .omp/extensions/, so a committed copy
+    // would run arbitrary code on clone. Keep it out of git like the rest.
+    '.omp/',
     '.agents/'
   ];
   const prefix = ctx.dryRun ? '[dry-run] ' : '';

package/bin/phases/select-platform.js

@@ -11,7 +11,8 @@ const path = require('path');
 const {
   PLATFORMS,
   detectPlatforms,
-  getPlatformKeys
+  getPlatformKeys,
+  resolvePlatformAliases
 } = require('../lib/context');
 const { SUPPORTED, LANGUAGE_LABELS, OTHER_LABEL } = require('../lib/i18n');
 
@@ -36,7 +37,25 @@ function getInstalledLocale(platformKeys = getPlatformKeys()) {
 }
 
 /** First step: pick the installer/UI language (interactive only). */
+/**
+ * Resolve host aliases on the requested platform list, once, before anything reads it.
+ *
+ * selectLanguage() filters this list through PLATFORMS to decide which installed runtime
+ * to take a saved locale from, so an unresolved alias would empty that list and fall back
+ * to scanning every platform folder — `--platform grok` in a project that also has
+ * `.codex/` would then silently take Codex's language.
+ */
+function applyPlatformAliases(ctx) {
+  const requested = ctx.options.platforms || [];
+  if (requested.length === 0) return ctx;
+  const { platforms, aliased } = resolvePlatformAliases(requested);
+  ctx.options.platforms = platforms;
+  ctx.aliasedHost = aliased;
+  return ctx;
+}
+
 async function selectLanguage(ctx) {
+  applyPlatformAliases(ctx);
   // Restore the saved locale BEFORE the interactivity check: a non-interactive
   // upgrade (--yes) must not forget the configured language. Skipping this left
   // ctx at the 'en' default, and patchRuntimeLocale then clobbered the user's
@@ -161,6 +180,7 @@ async function resolvePlatforms(ctx) {
     ctx.ui.info(ctx.t('installingFor', {
       names: platformNames(requested)
     }));
+    if (ctx.aliasedHost) ctx.ui.info(ctx.t('grokCompatNotice'));
     reportInstallMode(ctx);
     return ctx;
   }
@@ -244,6 +264,7 @@ function getInstalledPlatform() {
 
 module.exports = {
   selectLanguage,
+  applyPlatformAliases,
   promptPlatformSelection,
   resolvePlatforms,
   getInstalledPlatform,

package/bin/phases/summary.js

@@ -59,10 +59,6 @@ function printSummary(ctx) {
     }[key];
     if (messageKey) lines.push(t(messageKey));
   }
-  // rtk token-saver result (set by phases/setup-rtk.js when setup completed).
-  if (ctx.rtkSetupRan) {
-    lines.push(t('rtkSummary'));
-  }
   const keySkills = skillsNeedingKeys(platforms);
   if (keySkills.length > 0) {
     lines.push(t('nsKeys', { skills: keySkills.join(', ') }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "Native spec-driven workflows for Claude Code and Codex CLI. Bundles CafeKit skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/hooks/__tests__/semantic-review-authority.test.js

@@ -30,6 +30,8 @@ function installSemanticRuntime(target, runtime) {
   for (const name of ['semantic-review-authority.cjs', 'completion-authority-state.cjs']) {
     fs.copyFileSync(path.join(PACKAGE_ROOT, `src/${runtime}/hooks`, name), path.join(hooks, name));
   }
+  fs.copyFileSync(path.join(PACKAGE_ROOT, 'src/claude/hooks/lib/runtime-dir.cjs'), path.join(hooks, 'lib/runtime-dir.cjs'));
+  fs.copyFileSync(path.join(PACKAGE_ROOT, 'src/claude/hooks/lib/hook-payload.cjs'), path.join(hooks, 'lib/hook-payload.cjs'));
   fs.copyFileSync(
     path.join(PACKAGE_ROOT, 'src/claude/hooks/lib/runtime-path-safety.cjs'),
     path.join(hooks, 'lib/runtime-path-safety.cjs'),

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

@@ -289,6 +289,8 @@ function installClaudeGate(root, policyMode = 'valid') {
   fs.mkdirSync(scripts, { recursive: true });
   fs.copyFileSync(HOOK, path.join(hooks, 'spec-gate.cjs'));
   fs.mkdirSync(path.join(hooks, 'lib'), { recursive: true });
+  fs.copyFileSync(path.join(__dirname, '..', 'lib', 'runtime-dir.cjs'), path.join(hooks, 'lib', 'runtime-dir.cjs'));
+  fs.copyFileSync(path.join(__dirname, '..', 'lib', 'hook-payload.cjs'), path.join(hooks, 'lib', 'hook-payload.cjs'));
   fs.copyFileSync(
     path.join(__dirname, '..', 'lib', 'hook-state-dir.cjs'),
     path.join(hooks, 'lib', 'hook-state-dir.cjs'),
@@ -1486,3 +1488,339 @@ test('36. process-v3 Stop accepts two completed packets with valid Receipts', ()
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
+
+// ── Receipt freshness: bound while written or altered, structure-only once committed on a clean tree ──
+
+const STALE_BASE = 'f'.repeat(40);
+const STALE_HEAD = 'e'.repeat(40);
+
+function commitAll(dir, message) {
+  for (const args of [['add', '-A'], ['commit', '-qm', message, '--allow-empty']]) {
+    const result = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8' });
+    assert.strictEqual(result.status, 0, result.stderr);
+  }
+}
+
+function boundReceipt(base = VALID_BASE, head = VALID_HEAD) {
+  return [
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${base}`, `Head: ${head}`, '```text', '$ node --test', 'pass: 1', '```',
+  ];
+}
+
+function runHookFrom(dir, cwd) {
+  const res = spawnSync(process.execPath, [HOOK], {
+    cwd,
+    input: JSON.stringify({ hook_event_name: 'Stop', session_id: 'test', transcript_path: '/tmp/t', stop_hook_active: false, cwd: dir }),
+    encoding: 'utf8',
+    env: { ...process.env, PROJECT_ROOT: dir },
+  });
+  return { code: res.status, stdout: (res.stdout || '').trim(), stderr: res.stderr || '' };
+}
+
+test('37. committed receipt on a clean tree survives later commits', () => {
+  const dir = makeWorkflowFixture(boundReceipt());
+  try {
+    commitAll(dir, 'receipt');
+    fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'src', 'unrelated.txt'), 'later change\n');
+    commitAll(dir, 'unrelated source change');
+    clearCache();
+    const result = runHook({}, dir);
+    assert.strictEqual(result.code, 0, result.stderr);
+    assert.strictEqual(result.stdout, '', 'a committed, unchanged receipt on a clean tree must stay accepted after unrelated commits');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('38. untracked task file requires binding', () => {
+  const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
+  try {
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block', 'an untracked task file must keep full binding');
+    assert.match(body.reason, /\bprovenance\b/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('38b. the same stale receipt is accepted once committed on a clean tree', () => {
+  // Documents the accepted trade-off: once committed and clean, Base and Head
+  // must be concrete but are no longer compared against the runtime.
+  const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
+  try {
+    commitAll(dir, 'receipt');
+    clearCache();
+    const result = runHook({}, dir);
+    assert.strictEqual(result.stdout, '', result.stderr);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('39. staged but uncommitted task file requires binding', () => {
+  const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
+  try {
+    const add = spawnSync('git', ['-C', dir, 'add', '-A'], { encoding: 'utf8' });
+    assert.strictEqual(add.status, 0, add.stderr);
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block', 'git add alone must not grant structure-only');
+    assert.match(body.reason, /\bprovenance\b/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('40. modified receipt requires binding', () => {
+  const dir = makeWorkflowFixture(boundReceipt());
+  try {
+    commitAll(dir, 'receipt');
+    const taskFile = path.join(dir, 'specs', FEATURE, 'task-01-demo.md');
+    const context = workflowRuntimeContext(dir);
+    const before = fs.readFileSync(taskFile, 'utf8');
+    const after = before.replace(`Head: ${context.head}`, `Head: ${STALE_HEAD}`);
+    assert.notStrictEqual(after, before, 'fixture must contain the bound Head');
+    fs.writeFileSync(taskFile, after);
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block', 'a receipt edited after commit must be rebound');
+    assert.match(body.reason, /\bprovenance\b/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('41. unborn HEAD fails closed before any receipt check', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ck-spec-gate-'));
+  try {
+    for (const args of [['init', '-q'], ['config', 'user.email', 'cafekit@example.invalid'], ['config', 'user.name', 'CafeKit Test']]) {
+      const result = spawnSync('git', ['-C', dir, ...args], { encoding: 'utf8' });
+      assert.strictEqual(result.status, 0, result.stderr);
+    }
+    const featureDir = path.join(dir, 'specs', FEATURE);
+    fs.mkdirSync(featureDir, { recursive: true });
+    fs.writeFileSync(path.join(featureDir, 'plan.md'), '# Demo plan\n');
+    fs.writeFileSync(path.join(featureDir, 'task-01-demo.md'), [
+      '# Task 01: demo', '', 'Status: done', '', '## Dependencies', '', '- none', '',
+      '## Verification Plan', '', '- Command: node --test', '', ...boundReceipt(STALE_BASE, STALE_HEAD), '',
+    ].join('\n'));
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block', 'an unborn HEAD must block');
+    // The block arrives from provenance derivation, which cannot resolve a base
+    // commit here, so the receipt check is never reached. Asserting the reason
+    // keeps this case honest: it guards fail-closed behavior on an unborn HEAD,
+    // not the binding-mode selector. The selector's own HEAD-unreadable branch
+    // is guarded by cases 38 and 39.
+    assert.match(body.reason, /controlled failure/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('42. dirty tree outside specs requires binding, regardless of working directory', () => {
+  const dir = makeWorkflowFixture(boundReceipt());
+  try {
+    commitAll(dir, 'receipt');
+    fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'src', 'dirty.txt'), 'uncommitted\n');
+    clearCache();
+    const fromRoot = parseBlock(runHook({}, dir).stdout);
+    assert.ok(fromRoot && fromRoot.decision === 'block', 'an uncommitted change outside specs must rebind');
+    assert.match(fromRoot.reason, /\bprovenance\b/);
+    clearCache();
+    const fromSpecs = parseBlock(runHookFrom(dir, path.join(dir, 'specs', FEATURE)).stdout);
+    assert.ok(fromSpecs && fromSpecs.decision === 'block', 'the status check must pin the project root, not the working directory');
+    assert.match(fromSpecs.reason, /\bprovenance\b/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('42b. a change hidden by skip-worktree or assume-unchanged requires binding', () => {
+  // `git status` honors both index flags, so a tracked file outside the specs
+  // root can differ from HEAD while the tree reports clean. Structure mode must
+  // not be granted from a report that git itself is suppressing.
+  for (const flag of ['--skip-worktree', '--assume-unchanged']) {
+    const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
+    try {
+      fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+      fs.writeFileSync(path.join(dir, 'src', 'hidden.txt'), 'committed\n');
+      commitAll(dir, 'receipt and source');
+      const marked = spawnSync('git', ['-C', dir, 'update-index', flag, 'src/hidden.txt'], { encoding: 'utf8' });
+      assert.strictEqual(marked.status, 0, marked.stderr);
+      fs.writeFileSync(path.join(dir, 'src', 'hidden.txt'), 'tampered\n');
+      const status = spawnSync('git', ['-C', dir, 'status', '--porcelain'], { encoding: 'utf8' });
+      assert.strictEqual(status.stdout.trim(), '', `${flag} must make the tree look clean for this case to mean anything`);
+      clearCache();
+      const body = parseBlock(runHook({}, dir).stdout);
+      assert.ok(body && body.decision === 'block', `${flag} must not grant structure-only`);
+      assert.match(body.reason, /\bprovenance\b/);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  }
+});
+
+test('43. structure checks still block in committed mode', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 1',
+    `Base: ${STALE_BASE}`, `Head: ${STALE_HEAD}`, '```text', '$ node --test', 'fail: 1', '```',
+  ]);
+  try {
+    commitAll(dir, 'receipt');
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block');
+    assert.match(body.reason, /exit_result/);
+    assert.doesNotMatch(body.reason, /\bprovenance\b/, 'committed mode must not report a provenance failure for a stale but concrete pair');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('43b. committed mode still requires concrete Base and Head fields', () => {
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${STALE_BASE}`, '```text', '$ node --test', 'pass: 1', '```',
+  ]);
+  try {
+    commitAll(dir, 'receipt without Head');
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block', 'a missing Head field must still block');
+    assert.match(body.reason, /\bprovenance\b/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('44. edited artifact bytes still block in committed mode', () => {
+  const artifactPath = 'output/bundle.js';
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${STALE_BASE}`, `Head: ${STALE_HEAD}`,
+    `Artifact: ${artifactPath} (sha256:${FIXTURE_ARTIFACT_DIGEST})`,
+    '```text', '$ node --test', 'pass: 1', '```',
+  ]);
+  try {
+    fs.mkdirSync(path.join(dir, 'output'), { recursive: true });
+    fs.writeFileSync(path.join(dir, artifactPath), FIXTURE_ARTIFACT);
+    commitAll(dir, 'receipt and artifact');
+    clearCache();
+    const accepted = runHook({}, dir);
+    assert.strictEqual(accepted.stdout, '', accepted.stderr);
+    fs.writeFileSync(path.join(dir, artifactPath), 'tampered\n');
+    commitAll(dir, 'tamper artifact');
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block', 'artifact bytes must still be verified in committed mode');
+    assert.match(body.reason, /artifact_hash/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('45. the cache grants no authority across a state change', () => {
+  // A cached PASS must not survive a later mutation. The first run accepts and
+  // writes the cache; the second run sees tampered artifact bytes committed on a
+  // still-clean tree and must block without the cache being cleared first.
+  const artifactPath = 'output/cached.js';
+  const dir = makeWorkflowFixture([
+    '## Receipt', '', 'Verification: PASS', 'Command: node --test', 'Exit: 0',
+    `Base: ${STALE_BASE}`, `Head: ${STALE_HEAD}`,
+    `Artifact: ${artifactPath} (sha256:${FIXTURE_ARTIFACT_DIGEST})`,
+    '```text', '$ node --test', 'pass: 1', '```',
+  ]);
+  try {
+    fs.mkdirSync(path.join(dir, 'output'), { recursive: true });
+    fs.writeFileSync(path.join(dir, artifactPath), FIXTURE_ARTIFACT);
+    commitAll(dir, 'receipt and artifact');
+    clearCache();
+    const accepted = runHook({}, dir);
+    assert.strictEqual(accepted.stdout, '', 'first run must accept and populate the cache');
+    fs.writeFileSync(path.join(dir, artifactPath), 'tampered after the cached pass\n');
+    commitAll(dir, 'tamper artifact, tree stays clean');
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block', 'a cached pass must not hide a later mutation');
+    assert.match(body.reason, /artifact_hash/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('46. a dirty file inside the specs root does not force binding', () => {
+  // The status and index queries exclude the specs root on purpose: a receipt is
+  // written into that root, so counting it would make every receipt invalidate
+  // itself. Dropping the exclusion from either query must fail this case.
+  const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
+  try {
+    commitAll(dir, 'receipt');
+    fs.writeFileSync(path.join(dir, 'specs', FEATURE, 'plan.md'), '# Demo plan\n\nEdited after the receipt was committed.\n');
+    fs.writeFileSync(path.join(dir, 'specs', FEATURE, 'notes-untracked.md'), 'scratch\n');
+    const dirty = spawnSync('git', ['-C', dir, 'status', '--porcelain', '--untracked-files=all'], { encoding: 'utf8' });
+    assert.match(dirty.stdout, /specs\//, 'the specs root must actually be dirty for this case to mean anything');
+    clearCache();
+    const result = runHook({}, dir);
+    assert.strictEqual(result.stdout, '', 'work inside the specs root must not reopen a committed receipt');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('47. completed-set branch accepts committed receipts and blocks a tampered one', () => {
+  // Two finished packets resolve to the completed-set branch, which is the path
+  // that revalidated every done receipt on every Stop. Prove the new mode works
+  // there, then prove it still blocks.
+  const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
+  try {
+    const secondDir = path.join(dir, 'specs', 'second');
+    fs.mkdirSync(secondDir, { recursive: true });
+    fs.writeFileSync(path.join(secondDir, 'plan.md'), '# Second plan\n');
+    fs.writeFileSync(path.join(secondDir, 'task-01-second.md'), [
+      '# Task 01: second', '', 'Status: done', '', '## Dependencies', '', '- none', '',
+      '## Verification Plan', '', '- Command: node --test', '', ...boundReceipt(STALE_BASE, STALE_HEAD), '',
+    ].join('\n'));
+    commitAll(dir, 'two completed packets');
+    clearCache();
+    const accepted = runHook({}, dir);
+    assert.strictEqual(accepted.stdout, '', 'the completed-set branch must accept committed receipts on a clean tree');
+    fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+    fs.writeFileSync(path.join(dir, 'src', 'dirty.txt'), 'uncommitted\n');
+    clearCache();
+    const body = parseBlock(runHook({}, dir).stdout);
+    assert.ok(body && body.decision === 'block', 'the completed-set branch must rebind on a dirty tree');
+    assert.match(body.reason, /\bprovenance\b/);
+    assert.match(body.reason, /second|demo/);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('48. the gate\'s own runtime state does not defeat structure mode', () => {
+  // The gate writes its cache under .claude/hooks/.logs on every Stop. If that
+  // write counted as a dirty tree, a project tracking its runtime directory could
+  // never reach structure mode and the gate would defeat itself. The status query
+  // excludes the same runtime-state roots the provenance manifest already ignores.
+  const dir = makeWorkflowFixture(boundReceipt(STALE_BASE, STALE_HEAD));
+  try {
+    const stateDir = path.join(dir, '.claude', 'hooks', '.logs');
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(path.join(stateDir, 'spec-gate-last.json'), '{}\n');
+    fs.writeFileSync(path.join(dir, '.claude', 'runtime.json'), '{}\n');
+    commitAll(dir, 'receipt plus tracked runtime state');
+    // Mutate the tracked runtime state exactly as a Stop would.
+    fs.writeFileSync(path.join(stateDir, 'spec-gate-last.json'), '{"demo":{"task-01-demo.md":"done"}}\n');
+    fs.writeFileSync(path.join(dir, '.claude', 'runtime.json'), '{"spec":{}}\n');
+    const dirty = spawnSync('git', ['-C', dir, 'status', '--porcelain'], { encoding: 'utf8' });
+    assert.match(dirty.stdout, /\.claude\//, 'the runtime state must actually be dirty for this case to mean anything');
+    clearCache();
+    const result = runHook({}, dir);
+    assert.strictEqual(result.stdout, '', 'generated runtime state must not be read as a dirty worktree');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

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

@@ -44,6 +44,8 @@ function inInstalledProcessSpecStateFixture(run) {
     fs.mkdirSync(scripts, { recursive: true });
     fs.copyFileSync(path.join(CLAUDE_ROOT, 'hooks', 'spec-state.cjs'), path.join(hooks, 'spec-state.cjs'));
     fs.mkdirSync(path.join(hooks, 'lib'), { recursive: true });
+    fs.copyFileSync(path.join(CLAUDE_ROOT, 'hooks', 'lib', 'runtime-dir.cjs'), path.join(hooks, 'lib', 'runtime-dir.cjs'));
+    fs.copyFileSync(path.join(CLAUDE_ROOT, 'hooks', 'lib', 'hook-payload.cjs'), path.join(hooks, 'lib', 'hook-payload.cjs'));
     fs.copyFileSync(
       path.join(CLAUDE_ROOT, 'hooks', 'lib', 'hook-state-dir.cjs'),
       path.join(hooks, 'lib', 'hook-state-dir.cjs'),

package/src/claude/hooks/agent.cjs

@@ -15,19 +15,23 @@ try {
   const fs   = require('fs');
   const path = require('path');
 
-  /** Read .claude/runtime.json */
+  /** Read <runtime>/runtime.json */
+  const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
   function readRuntime(cwd) {
     try {
-      const p = path.join(cwd, '.claude', 'runtime.json');
+      const p = runtimePath(cwd, 'runtime.json');
       return fs.existsSync(p) ? JSON.parse(fs.readFileSync(p, 'utf8')) : null;
     } catch { return null; }
   }
 
+  // Skills live beside the runtime only on Claude; Codex and omp read `.agents/skills`.
+  function skillsDir() { return runtimeDirName() === '.claude' ? '.claude/skills' : '.agents/skills'; }
+
   /** Resolve Python venv executable path if it exists */
   function resolveVenv(cwd) {
     const candidates = [
-      path.join(cwd, '.claude', 'skills', '.venv', 'bin', 'python3'),
-      path.join(cwd, '.claude', 'skills', '.venv', 'Scripts', 'python.exe'),
+      path.join(cwd, skillsDir(), '.venv', 'bin', 'python3'),
+      path.join(cwd, skillsDir(), '.venv', 'Scripts', 'python.exe'),
     ];
     return candidates.find(p => fs.existsSync(p)) || null;
   }
@@ -37,7 +41,8 @@ try {
   const stdin = fs.readFileSync(0, 'utf8').trim();
   if (!stdin) process.exit(0);
 
-  const payload    = JSON.parse(stdin);
+  const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
+  const payload    = normalizeHookPayload(JSON.parse(stdin));
   // Use payload.cwd for monorepo support — subagent may run in a different dir
   const payloadCwd = typeof payload.cwd === 'string' ? payload.cwd.trim() : '';
   const agentCwd   = payloadCwd || process.env.PROJECT_ROOT || process.cwd();
@@ -67,13 +72,13 @@ try {
     lines.push('');
   }
 
-  // Python venv (optional — if .claude/skills/.venv exists)
+  // Python venv (optional — if <skills>/.venv exists)
   const venv = resolveVenv(agentCwd);
 
   lines.push('## Rules');
   lines.push(`- Plans → ${plansPath}/ | Docs → ${docsPath}/`);
   if (venv) {
-    lines.push(`- Python in .claude/skills/: use \`${venv}\``);
+    lines.push(`- Python in ${skillsDir()}/: use \`${venv}\``);
     lines.push('- Never use global pip install');
   }