declapract-typescript-ehmpathy 0.49.12 → 0.49.14

package/dist/.test/assets/expo-fullusecase/declarations/practices/husky/check.secrets.play.declapract.integration.test.ts

@@ -0,0 +1,120 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { given, then, when } from 'test-fns';
+
+/**
+ * .what = integration test for the check.secrets husky guard (#514)
+ * .why  = proves the guard halts a commit whose staged blob holds a key shape, names the
+ *         file + line + shape (never the key), and lets clean files and look-alikes through
+ * .note = each fake key is assembled at runtime, so this source file never holds a key shape
+ *         itself — a repo that adopts the guard can still commit its own tests
+ */
+
+// the guard under test (the distributed best-practice template)
+const guardPath = path.join(__dirname, 'best-practice/.husky/check.secrets.sh');
+
+// assemble a fake key from a prefix and a tail of repeated chars
+const asFakeKey = (input: { prefix: string; tail: string; length: number }) =>
+  input.prefix + input.tail.repeat(input.length);
+
+// build a fresh temp git repo with the given files staged
+const genStagedRepo = (files: Record<string, string>): string => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'check-secrets-'));
+  execFileSync('git', ['init', '-q'], { cwd: dir });
+  for (const [name, content] of Object.entries(files)) {
+    const full = path.join(dir, name);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, content);
+    execFileSync('git', ['add', '--', name], { cwd: dir });
+  }
+  return dir;
+};
+
+// spawn the guard against a repo; return its exit code + streams
+const runGuard = (
+  dir: string,
+): { code: number | null; stdout: string; stderr: string } => {
+  const res = spawnSync('bash', [guardPath], { cwd: dir, encoding: 'utf-8' });
+  return { code: res.status, stdout: res.stdout, stderr: res.stderr };
+};
+
+describe('check.secrets guard', () => {
+  given('[case1] a staged debug file that holds a fireworks key (the #514 incident)', () => {
+    const key = asFakeKey({ prefix: 'fw_', tail: 'aB3', length: 10 });
+    const result = runGuard(
+      genStagedRepo({ '.cache/debug.env': `# debug\nFIREWORKS_API_KEY='${key}'\n` }),
+    );
+
+    when('[t0] the guard runs', () => {
+      then('it halts with exit 2', () => {
+        expect(result.code).toEqual(2);
+      });
+      then('it names the file, the line, and the shape on stderr', () => {
+        expect(result.stderr).toContain('✋ ConstraintError: a secret key shape is staged');
+        expect(result.stderr).toContain('   ├─ shape: fireworks key');
+        expect(result.stderr).toContain('   └─ .cache/debug.env:2');
+      });
+      then('it never echoes the key itself', () => {
+        expect(result.stderr).not.toContain(key);
+        expect(result.stdout).not.toContain(key);
+      });
+      then('the halt output matches snapshot', () => {
+        expect(result.stderr).toMatchSnapshot('check.secrets halt output');
+      });
+    });
+  });
+
+  given('[case2] the halt table — each key shape the guard knows', () => {
+    const haltTable = [
+      { shape: 'aws access key id', line: `id = ${asFakeKey({ prefix: 'AKIA', tail: 'Q7', length: 8 })}` },
+      { shape: 'private key block', line: `${'-----BEGIN'} RSA ${'PRIVATE KEY-----'}` },
+      { shape: 'github token', line: `token: ${asFakeKey({ prefix: 'ghp_', tail: 'aZ9', length: 13 })}` },
+      { shape: 'openai-style key', line: `key=${asFakeKey({ prefix: 'sk-', tail: 'aZ9', length: 10 })}` },
+      { shape: 'xai key', line: `XAI_API_KEY=${asFakeKey({ prefix: 'xai-', tail: 'aZ9', length: 10 })}` },
+      { shape: 'slack token', line: `hook ${asFakeKey({ prefix: 'xoxb-', tail: '12', length: 8 })}` },
+    ];
+    haltTable.forEach((row) => {
+      when(`[t0] the guard runs on a ${row.shape}`, () => {
+        const result = runGuard(genStagedRepo({ 'config.md': `${row.line}\n` }));
+
+        then('it halts with exit 2, and names the shape', () => {
+          expect(result.code).toEqual(2);
+          expect(result.stderr).toContain(`   ├─ shape: ${row.shape}`);
+        });
+      });
+    });
+  });
+
+  given('[case3] the pass table — values that resemble a key but are not one', () => {
+    const passTable = [
+      { form: 'a placeholder env line', line: 'FIREWORKS_API_KEY=__set_me__' },
+      { form: 'an env read', line: 'const key = process.env.XAI_API_KEY;' },
+      { form: 'a short prefix word', line: 'a risk-assessment and a disk-usage report' },
+      { form: 'a ci secret ref', line: 'API_KEY: ${{ secrets.API_KEY }}' },
+      { form: 'a lockfile integrity hash', line: 'integrity: sha512-Ab3Ab3Ab3Ab3Ab3Ab3Ab3Ab3Ab3Ab3Ab3==' },
+    ];
+    passTable.forEach((row) => {
+      when(`[t0] the guard runs on ${row.form}`, () => {
+        const result = runGuard(genStagedRepo({ 'notes.md': `${row.line}\n` }));
+
+        then('it allows the commit with exit 0', () => {
+          expect(result.code).toEqual(0);
+          expect(result.stderr).toEqual('');
+        });
+      });
+    });
+  });
+
+  given('[case4] no staged file holds a key', () => {
+    when('[t0] the guard runs', () => {
+      const result = runGuard(genStagedRepo({ 'readme.md': 'hello\n' }));
+
+      then('it allows the commit with exit 0', () => {
+        expect(result.code).toEqual(0);
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/husky/check.timestamps.lock.play.declapract.integration.test.ts

@@ -0,0 +1,220 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { executeApply } from 'declapract';
+import { genTempDir, given, then, useThen, when } from 'test-fns';
+
+import { asGitBlobId } from './best-practice/.husky/check.timestamps.lock.sh.declapract';
+
+/**
+ * .what = end-to-end proof of the timestamp lock: a second husky hook that halts every commit
+ *         while .husky/check.timestamps.sh differs from the practice's declared copy
+ * .why  = the timestamp hook takes zero exemptions, by design — a timestamp in a tracked file a
+ *         privacy leak. a hand edit that softens the hook (here, a
+ *         `.goals/*` exemption) must halt loud and say revert, never slip through
+ * .how  = clone a demo repo whose hook was hand-softened; apply the husky practice through the real
+ *         declapract pipeline; run the lock against the repo before and after the hook is restored
+ */
+
+// the declared timestamp hook template
+const hookTemplatePath = path.join(
+  __dirname,
+  'best-practice/.husky/check.timestamps.sh',
+);
+
+// mask the blob id so the snapshot vibechecks the shape, not the hook's current bytes
+const asMaskedBlob = (text: string): string =>
+  text.replace(/[0-9a-f]{40}/g, '[blob]');
+
+describe('check.timestamps.lock', () => {
+  given('[case1] the blob id transformer', () => {
+    when('[t0] it hashes the declared hook template', () => {
+      then('it equals the id `git hash-object` reports for the same file', () => {
+        const viaGit = execFileSync('git', ['hash-object', '--', hookTemplatePath], {
+          encoding: 'utf-8',
+        }).trim();
+        const viaFn = asGitBlobId({
+          contents: fs.readFileSync(hookTemplatePath, 'utf-8'),
+        });
+        expect(viaFn).toEqual(viaGit);
+      });
+    });
+  });
+
+  given('[case2] a repo whose timestamp hook was hand-softened with an exemption', () => {
+    const tempDir = genTempDir({
+      slug: 'declapract-husky-timestamps-lock',
+      clone:
+        './src/practices/husky/.test/assets/demo-repo-with-edited-timestamp-hook',
+      symlink: [{ at: 'declarations', to: 'src' }],
+    });
+    const hookRel = '.husky/check.timestamps.sh';
+    const lockRel = '.husky/check.timestamps.lock.sh';
+    const read = (rel: string) => fs.readFileSync(path.join(tempDir, rel), 'utf-8');
+    const applyFile = (file: string) =>
+      executeApply({
+        config: path.join(tempDir, 'declapract.use.yml'),
+        practice: 'husky',
+        file,
+      });
+    const runLock = () => {
+      const res = spawnSync('bash', [lockRel], { cwd: tempDir, encoding: 'utf-8' });
+      return { code: res.status, stderr: res.stderr };
+    };
+    // pre-commit is `#!/bin/sh` and SOURCES the lock, so the lock must also hold under posix sh
+    const runLockSourcedBySh = () => {
+      const res = spawnSync('sh', ['-c', `. ./${lockRel}`, './.husky/pre-commit'], {
+        cwd: tempDir,
+        encoding: 'utf-8',
+      });
+      return { code: res.status, stderr: res.stderr };
+    };
+
+    when('[t0] the input (before any apply)', () => {
+      then('the softened hook carries the exemption, and matches snapshot', () => {
+        const before = read(hookRel);
+        expect(before).toContain('.goals/*) continue');
+        expect(before).toMatchSnapshot('check.timestamps.sh — before');
+      });
+      then('no lock exists yet', () => {
+        expect(fs.existsSync(path.join(tempDir, lockRel))).toEqual(false);
+      });
+    });
+
+    when('[t1] the lock is applied, the softened hook left in place', () => {
+      useThen('apply the lock', async () => {
+        await applyFile(lockRel);
+        execFileSync('git', ['init', '-q'], { cwd: tempDir });
+      });
+
+      then('the lock is stamped with the declared hook blob id, and matches snapshot', () => {
+        const lock = read(lockRel);
+        expect(lock).not.toContain('__EXPECTED_BLOB__');
+        expect(lock).toContain(
+          `TIMESTAMPS_LOCK_EXPECTED='${asGitBlobId({ contents: fs.readFileSync(hookTemplatePath, 'utf-8') })}'`,
+        );
+        expect(asMaskedBlob(lock)).toMatchSnapshot('check.timestamps.lock.sh — after');
+      });
+
+      then('the lock halts with exit 2 and says revert, zero exceptions', () => {
+        const result = runLock();
+        expect(result.code).toEqual(2);
+        expect(result.stderr).toContain(
+          '✋ ConstraintError: .husky/check.timestamps.sh was changed. revert the hook, zero exceptions — remove all timestamps',
+        );
+        expect(result.stderr).toContain('a privacy leak');
+        expect(result.stderr).not.toContain('permadrift');
+        expect(asMaskedBlob(result.stderr)).toMatchSnapshot('lock halt output — on disk');
+      });
+
+      then('the lock halts with exit 2 when sourced by posix sh, as pre-commit does', () => {
+        const result = runLockSourcedBySh();
+        expect(result.code).toEqual(2);
+        expect(result.stderr).toContain('revert the hook, zero exceptions');
+      });
+    });
+
+    when('[t2] the hook edit is staged, then reverted on disk only', () => {
+      useThen('stage the softened hook, then restore the declared hook on disk', async () => {
+        execFileSync('git', ['add', '--', hookRel], { cwd: tempDir });
+        fs.copyFileSync(hookTemplatePath, path.join(tempDir, hookRel));
+      });
+
+      then('the lock still halts — the index would commit the exemption', () => {
+        const result = runLock();
+        expect(result.code).toEqual(2);
+        expect(result.stderr).toContain('in the index');
+        expect(asMaskedBlob(result.stderr)).toMatchSnapshot('lock halt output — in the index');
+      });
+    });
+
+    when('[t3] the practice restores the hook', () => {
+      useThen('apply the hook, then stage it', async () => {
+        await applyFile(hookRel);
+        execFileSync('git', ['add', '--', hookRel], { cwd: tempDir });
+      });
+
+      then('the hook equals the declared template, byte for byte', () => {
+        // no snapshot here: the template's comments hold example stamps, and a .snap is a tracked
+        // file the timestamp hook scans. the byte-equal assert IS the full after-state proof
+        const after = read(hookRel);
+        expect(after).toEqual(fs.readFileSync(hookTemplatePath, 'utf-8'));
+        expect(after).not.toContain('.goals/');
+      });
+
+      then('the lock passes with exit 0', () => {
+        expect(runLock().code).toEqual(0);
+      });
+
+      then('the lock passes with exit 0 when sourced by posix sh, as pre-commit does', () => {
+        expect(runLockSourcedBySh().code).toEqual(0);
+      });
+    });
+
+    when('[t4] the index cannot be read', () => {
+      const indexPath = path.join(tempDir, '.git/index');
+      const result = useThen('corrupt the index, run the lock, then restore the index', async () => {
+        const indexBytes = fs.readFileSync(indexPath);
+        fs.writeFileSync(indexPath, 'not an index');
+        const outcome = runLock();
+        fs.writeFileSync(indexPath, indexBytes);
+        return outcome;
+      });
+
+      then('the lock halts as a malfunction (exit 1) and names the unreadable index, never reads it as unstaged', () => {
+        // the hook may be intact, so the halt blames the index, never asks to revert the hook
+        expect(result.code).toEqual(1);
+        expect(result.stderr).toContain('💥 MalfunctionError:');
+        expect(result.stderr).toContain('unreadable (in the index)');
+        expect(result.stderr).not.toContain('was changed');
+        expect(asMaskedBlob(result.stderr)).toMatchSnapshot('lock halt output — index unreadable');
+      });
+    });
+
+    when('[t5] the practice is applied again', () => {
+      const before = useThen('read the lock', async () => ({ lock: read(lockRel) }));
+      useThen('apply both files a second time', async () => {
+        await applyFile(lockRel);
+        await applyFile(hookRel);
+      });
+
+      then('the second apply is a no-op', () => {
+        expect(read(lockRel)).toEqual(before.lock);
+        expect(read(hookRel)).toEqual(fs.readFileSync(hookTemplatePath, 'utf-8'));
+      });
+    });
+
+    when('[t6] the hook is deleted', () => {
+      useThen('delete the hook', async () => {
+        fs.rmSync(path.join(tempDir, hookRel));
+      });
+
+      then('the lock halts with exit 2', () => {
+        const result = runLock();
+        expect(result.code).toEqual(2);
+        expect(result.stderr).toContain('absent');
+        expect(asMaskedBlob(result.stderr)).toMatchSnapshot('lock halt output — hook absent');
+      });
+    });
+  });
+
+  given('[case3] the declared timestamp hook, read as text', () => {
+    const hook = fs.readFileSync(hookTemplatePath, 'utf-8');
+
+    when('[t0] its skip list is inspected', () => {
+      then('the only skip is code that computes time: *.ts and *.sh, never a new path', () => {
+        // a clamp on the no-exemption rule: any new `case` arm, path glob, or allowlist reddens this
+        const skips = hook.match(/^\s*\*[^\n]*\)\s*continue\s*;;/gm) ?? [];
+        expect(skips).toEqual(['    *.ts | *.sh) continue ;;']);
+      });
+      then('it never names permadrift, and it names the privacy reason', () => {
+        expect(hook).not.toContain('permadrift');
+        expect(hook).toContain('a privacy leak');
+      });
+      then('it declares, loud, that it takes no exemption', () => {
+        expect(hook).toContain('NEVER ADD AN EXEMPTION TO THIS HOOK');
+      });
+    });
+  });
+});

package/dist/.test/assets/expo-fullusecase/declarations/practices/husky/check.timestamps.play.declapract.integration.test.ts

@@ -31,10 +31,12 @@ const genStagedRepo = (files: Record<string, string>): string => {
   return dir;
 };
 
-// spawn the guard against a repo; return its exit code + stdout
-const runGuard = (dir: string): { code: number | null; stdout: string } => {
-  const res = spawnSync('bash', [guardPath], { cwd: dir, encoding: 'utf-8' });
-  return { code: res.status, stdout: res.stdout };
+// spawn the guard against a repo; return its exit code + streams
+const runGuard = (input: {
+  dir: string;
+}): { code: number | null; stdout: string; stderr: string } => {
+  const res = spawnSync('bash', [guardPath], { cwd: input.dir, encoding: 'utf-8' });
+  return { code: res.status, stdout: res.stdout, stderr: res.stderr };
 };
 
 describe('check.timestamps guard', () => {
@@ -43,26 +45,32 @@ describe('check.timestamps guard', () => {
       const dir = genStagedRepo({
         'snapshot.json': '{ "createdAt": "2026-06-25T14:30:00Z" }\n',
       });
-      const result = runGuard(dir);
+      const result = runGuard({ dir });
 
       then('it halts with exit 2', () => {
         expect(result.code).toEqual(2);
       });
-      then('it prints the verbatim constraint message', () => {
-        expect(result.stdout).toContain(
-          'timestamps are forbidden in snapshots. mask them to prevent permadrift',
+      then('it prints the verbatim constraint header on stderr (#681)', () => {
+        expect(result.stderr).toContain(
+          '✋ ConstraintError: timestamps are forbidden in tracked files, prose and docs included. remove them, zero exceptions',
+        );
+        expect(result.stdout).toEqual('');
+      });
+      then('it prints the why line beneath the header', () => {
+        expect(result.stderr).toContain(
+          '   ├─ why: a timestamp is a privacy leak, and churns every diff',
         );
       });
       then('it names the matched file', () => {
-        expect(result.stdout).toContain('snapshot.json');
+        expect(result.stderr).toContain('snapshot.json');
       });
       then('it renders the matched file:line:content detail line', () => {
         // locks the exact halt-output shape: tree-prefixed detail line
-        expect(result.stdout).toContain(
+        expect(result.stderr).toContain(
           '   └─ snapshot.json:1:{ "createdAt": "2026-06-25T14:30:00Z" }',
         );
       });
-      then('the verbatim halt output matches snapshot', () => {
+      then('the halt output, its instant masked, matches snapshot', () => {
         // user-faced halt message — a reword must redden a vibecheck, not slip past the
         // toContain asserts above (rule.require.snapshots). the fixture timestamp is a fixed
         // input (not a live clock), so the output is deterministic.
@@ -70,7 +78,7 @@ describe('check.timestamps guard', () => {
         // this very guard (only .ts/.sh are exempt), so a raw instant here would forbid its own
         // commit. the raw detail-line toContain above already locks the exact instant in the
         // output; the snapshot vibechecks the message shape, per the guard's own mask remedy (case8).
-        const masked = result.stdout.replace(
+        const masked = result.stderr.replace(
           /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z/g,
           '[timestamp]',
         );
@@ -82,7 +90,7 @@ describe('check.timestamps guard', () => {
   given('[case2] a non-code file with a bare time (no lead T)', () => {
     when('[t0] the guard runs', () => {
       const dir = genStagedRepo({ 'doc.md': 'released at 14:30:00 today\n' });
-      const result = runGuard(dir);
+      const result = runGuard({ dir });
 
       then('it halts with exit 2 (optional T prefix matches bare time)', () => {
         expect(result.code).toEqual(2);
@@ -93,7 +101,7 @@ describe('check.timestamps guard', () => {
   given('[case3] a .ts file with a timestamp', () => {
     when('[t0] the guard runs', () => {
       const dir = genStagedRepo({ 'time.ts': "const t = '14:30:00';\n" });
-      const result = runGuard(dir);
+      const result = runGuard({ dir });
 
       then('it allows the commit with exit 0 (.ts is exempt)', () => {
         expect(result.code).toEqual(0);
@@ -104,7 +112,7 @@ describe('check.timestamps guard', () => {
   given('[case4] a .sh file with a timestamp', () => {
     when('[t0] the guard runs', () => {
       const dir = genStagedRepo({ 'log.sh': "echo 'at 14:30:00Z'\n" });
-      const result = runGuard(dir);
+      const result = runGuard({ dir });
 
       then('it allows the commit with exit 0 (.sh is exempt)', () => {
         expect(result.code).toEqual(0);
@@ -115,7 +123,7 @@ describe('check.timestamps guard', () => {
   given('[case5] a clean non-code file with no timestamp', () => {
     when('[t0] the guard runs', () => {
       const dir = genStagedRepo({ 'notes.md': 'hello world, no times here\n' });
-      const result = runGuard(dir);
+      const result = runGuard({ dir });
 
       then('it allows the commit with exit 0', () => {
         expect(result.code).toEqual(0);
@@ -126,7 +134,7 @@ describe('check.timestamps guard', () => {
   given('[case6] a non-code file with only a date (no time)', () => {
     when('[t0] the guard runs', () => {
       const dir = genStagedRepo({ 'dated.md': 'shipped on 2026-06-25\n' });
-      const result = runGuard(dir);
+      const result = runGuard({ dir });
 
       then('it allows the commit with exit 0 (date alone does not match)', () => {
         expect(result.code).toEqual(0);
@@ -139,7 +147,7 @@ describe('check.timestamps guard', () => {
       const dir = genStagedRepo({
         'rec.yml': 'when: 2026-06-25T14:30:00+05:00\n',
       });
-      const result = runGuard(dir);
+      const result = runGuard({ dir });
 
       then('it halts with exit 2 (offset tz form matches)', () => {
         expect(result.code).toEqual(2);
@@ -152,7 +160,7 @@ describe('check.timestamps guard', () => {
       const dir = genStagedRepo({
         'render.test.ts.snap': '{ "createdAt": "[timestamp]" }\n',
       });
-      const result = runGuard(dir);
+      const result = runGuard({ dir });
 
       then('it allows the commit with exit 0 (mask remedy is committable)', () => {
         expect(result.code).toEqual(0);
@@ -160,12 +168,12 @@ describe('check.timestamps guard', () => {
     });
   });
 
-  // #566: an iso-8601 duration is a fixed span, not an instant, so it cannot permadrift —
+  // #566: an iso-8601 duration is a fixed span, not an instant, so it is a stable value —
   // the matcher must not halt on it (a false positive that trains folks to bypass the hook)
   given('[case9] a non-code file with a simple iso duration (PT12:30:00)', () => {
     when('[t0] the guard runs', () => {
       const dir = genStagedRepo({ 'fixture.json': '{ "window": "PT12:30:00" }\n' });
-      const result = runGuard(dir);
+      const result = runGuard({ dir });
 
       then('it allows the commit with exit 0 (a duration is not a timestamp)', () => {
         expect(result.code).toEqual(0);
@@ -176,7 +184,7 @@ describe('check.timestamps guard', () => {
   given('[case10] a non-code file with a day+time duration (P1DT02:15:30)', () => {
     when('[t0] the guard runs', () => {
       const dir = genStagedRepo({ 'fixture.json': '{ "elapsed": "P1DT02:15:30" }\n' });
-      const result = runGuard(dir);
+      const result = runGuard({ dir });
 
       then('it allows the commit with exit 0 (a duration is not a timestamp)', () => {
         expect(result.code).toEqual(0);
@@ -189,7 +197,7 @@ describe('check.timestamps guard', () => {
       const dir = genStagedRepo({
         'fixture.json': '{ "span": "P3Y6M4DT12:30:05" }\n',
       });
-      const result = runGuard(dir);
+      const result = runGuard({ dir });
 
       then('it allows the commit with exit 0 (a duration is not a timestamp)', () => {
         expect(result.code).toEqual(0);
@@ -203,11 +211,151 @@ describe('check.timestamps guard', () => {
         'fixture.json':
           '{ "window": "PT12:30:00", "createdAt": "2026-06-25T14:30:00Z" }\n',
       });
-      const result = runGuard(dir);
+      const result = runGuard({ dir });
 
       then('it halts with exit 2 (the real stamp wins, despite the duration)', () => {
         expect(result.code).toEqual(2);
       });
     });
   });
+
+  // #641: the pattern required seconds and colons, so a minute-only clock, a dash-separated
+  // iso stamp in a filename, and a bare `<hh>:<mm>` all slipped through
+  given('[case13] the halt table — each time-of-day form a doc can carry (#641)', () => {
+    const haltTable = [
+      { form: 'a bare minute clock', content: 'ran at 14:30 UTC\n' },
+      { form: 'a bare second clock', content: 'ran at 14:30:00\n' },
+      { form: 'a minute-only iso stamp', content: 'at 2026-09-20T14:30Z\n' },
+      { form: 'a dash-separated iso stamp', content: 'log: run.2026-09-20T14-30-00Z.log\n' },
+      { form: 'a dash-separated minute stamp', content: 'log: run.2026-09-20T14-30Z.log\n' },
+      { form: 'a clock with an offset', content: 'at T09:05+05:30\n' },
+    ];
+    haltTable.forEach((row) => {
+      when(`[t0] the guard runs on ${row.form}`, () => {
+        const result = runGuard({ dir: genStagedRepo({ 'yield.md': row.content }) });
+
+        then('it halts with exit 2', () => {
+          expect(result.code).toEqual(2);
+        });
+        then('it names the file and line on stderr', () => {
+          expect(result.stderr).toContain('   └─ yield.md:1:');
+        });
+      });
+    });
+  });
+
+  // the guard earns trust by what it lets through: a halt on a line:col ref or a port map
+  // would block every dev on every commit
+  given('[case14] the pass table — values that look like a clock but are not one (#641)', () => {
+    const passTable = [
+      { form: 'an iso duration', content: 'window: PT12:30:00\n' },
+      { form: 'a minute iso duration', content: 'window: PT12:30\n' },
+      { form: 'a date alone', content: 'shipped on 2026-09-20\n' },
+      { form: 'a file:line:col ref', content: 'see src/foo.ts:42:7\n' },
+      { form: 'a two-digit line:col ref', content: 'see src/foo.ts:12:34\n' },
+      { form: 'a port map', content: 'ports: 5432:5432\n' },
+      { form: 'a ratio', content: 'aspect 3:1\n' },
+      { form: 'a markdown table rule', content: '|:---|:---:|\n' },
+      { form: 'an out-of-range hour', content: 'score 42:17\n' },
+    ];
+    passTable.forEach((row) => {
+      when(`[t0] the guard runs on ${row.form}`, () => {
+        const result = runGuard({ dir: genStagedRepo({ 'doc.md': row.content }) });
+
+        then('it allows the commit with exit 0', () => {
+          expect(result.code).toEqual(0);
+        });
+      });
+    });
+  });
+
+  // #681: core.quotepath quoted a non-ascii path, so `git show` could not read it and the
+  // guard exited 1 as a malfunction on a legal file
+  given('[case15] a staged file at a non-ascii path (#681)', () => {
+    when('[t0] the file holds a date only', () => {
+      const result = runGuard({ dir: genStagedRepo({ 'docs/café.md': 'on 2026-09-20\n' }) });
+
+      then('it allows the commit with exit 0 — no false malfunction', () => {
+        expect(result.code).toEqual(0);
+        expect(result.stderr).toEqual('');
+      });
+    });
+
+    when('[t1] the file holds a clock time', () => {
+      const result = runGuard({ dir: genStagedRepo({ 'docs/café.md': 'at 14:30\n' }) });
+
+      then('it halts with exit 2, with the raw path and line on stderr', () => {
+        expect(result.code).toEqual(2);
+        expect(result.stderr).toContain('✋ ConstraintError:');
+        expect(result.stderr).toContain('   └─ docs/café.md:1:at 14:30');
+      });
+    });
+  });
+
+  // #681: a blob git cannot read is the system's fault, not the caller's
+  given('[case16] a staged file whose blob git cannot read (#681)', () => {
+    when('[t0] the guard runs', () => {
+      const dir = genStagedRepo({ 'notes.md': 'no time here\n' });
+      const sha = execFileSync('git', ['rev-parse', ':notes.md'], {
+        cwd: dir,
+        encoding: 'utf-8',
+      }).trim();
+      fs.rmSync(path.join(dir, '.git/objects', sha.slice(0, 2), sha.slice(2)));
+      const result = runGuard({ dir });
+
+      then('it exits 1, with a MalfunctionError header on stderr', () => {
+        expect(result.code).toEqual(1);
+        expect(result.stderr).toContain(
+          '💥 MalfunctionError: check.timestamps could not read the staged blob',
+        );
+        expect(result.stderr).toContain('   └─ notes.md');
+      });
+    });
+  });
+
+  // #684 asked to exempt the achiever's `.goals/` ask log; the answer is no (S16): the log must
+  // not hold a clock, so a pasted shell prompt clock there halts like it does anywhere else
+  given('[case17] a staged .goals/ ask log that holds a pasted shell prompt clock (#684)', () => {
+    when('[t0] the guard runs', () => {
+      const result = runGuard({
+        dir: genStagedRepo({
+          '.route/x/.goals/asks.inventory.jsonl':
+            '{"ask":"[14:32:07] ~/repo $ npm run test"}\n',
+        }),
+      });
+
+      then('it halts with exit 2, as for any other path — no path is exempt', () => {
+        expect(result.code).toEqual(2);
+        expect(result.stderr).toContain('✋ ConstraintError:');
+        expect(result.stderr).toContain('.route/x/.goals/asks.inventory.jsonl:1:');
+      });
+    });
+
+    when('[t1] the same log holds the ask with the clock masked', () => {
+      const result = runGuard({
+        dir: genStagedRepo({
+          '.route/x/.goals/asks.inventory.jsonl':
+            '{"ask":"[time] ~/repo $ npm run test"}\n',
+        }),
+      });
+
+      then('it allows the commit with exit 0 — the masked form is the remedy', () => {
+        expect(result.code).toEqual(0);
+        expect(result.stderr).toEqual('');
+      });
+    });
+  });
+
+  given('[case-scope] the hook source a reader meets (#641)', () => {
+    when('[t0] its header is read', () => {
+      const header = fs
+        .readFileSync(guardPath, 'utf-8').split('\n').slice(0, 8).join('\n');
+
+      then('the .what says prose is in scope, so no reader asks for a prose skip', () => {
+        expect(header).toContain('ANY staged file but .ts/.sh');
+        expect(header).toContain('prose included');
+        expect(header).not.toContain('snapshot'); // no single file kind reads as the target
+      });
+    });
+  });
 });