@productbrain/cli 0.1.0-beta.15 → 0.1.0-beta.1502

package/dist/__tests__/handshake.test.js

@@ -2,12 +2,19 @@
  * pb handshake --init — unit tests.
  * DEC-271: two-file split (team vs personal). DEC-272: permission whitelist.
  * TEN-712: hooks must fail silently (|| true suffix).
+ *
+ * WP-379 S3b: probeStarterSetupSeeded + pollUntilSeedsReady tests.
  */
 import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
 import { join } from 'path';
+// Import the mocked fs functions so we can use vi.mocked() to change their implementations per-test.
+// vi.mock('fs', ...) below hoists this mock, so these imports resolve to the mocked versions.
+import { readdirSync as readdirSyncMock } from 'fs';
 // vi.mock calls are hoisted — use vi.hoisted() for constants referenced inside factories.
-const { vfs, MOCK_CWD, MOCK_HOME } = vi.hoisted(() => ({
+const { vfs, vfsMtimes, MOCK_CWD, MOCK_HOME } = vi.hoisted(() => ({
     vfs: {},
+    // WP-379 S5b: mtime map used by statSync mock for case-collision ordering tests.
+    vfsMtimes: {},
     MOCK_CWD: '/tmp/pb-test-cwd',
     MOCK_HOME: '/tmp/pb-test-home',
 }));
@@ -16,24 +23,45 @@ vi.mock('fs', () => ({
     writeFileSync: vi.fn((path, content) => {
         vfs[path] = content;
     }),
+    appendFileSync: vi.fn((path, content) => {
+        vfs[path] = (vfs[path] ?? '') + content;
+    }),
     existsSync: vi.fn((path) => path in vfs),
     readFileSync: vi.fn((path, _enc) => {
         if (path in vfs)
             return vfs[path];
         throw Object.assign(new Error(`ENOENT: no such file '${path}'`), { code: 'ENOENT' });
     }),
+    readdirSync: vi.fn((_dir) => []),
+    copyFileSync: vi.fn(),
+    // WP-379 S5b: unlinkSync + statSync for orphan unlink + case-collision resolution.
+    unlinkSync: vi.fn((path) => {
+        delete vfs[path];
+    }),
+    statSync: vi.fn((path) => {
+        if (path in vfs) {
+            // Return a fake stat with an incrementing mtime based on path hash (deterministic).
+            // Tests that need specific mtime ordering should set vfs[path] before calling.
+            const mtimeMs = vfsMtimes[path] ?? 1000;
+            return { mtimeMs };
+        }
+        throw Object.assign(new Error(`ENOENT: stat '${path}'`), { code: 'ENOENT' });
+    }),
 }));
 vi.mock('os', () => ({
     homedir: vi.fn(() => MOCK_HOME),
 }));
-// readline mock: user types '2' (selects 'work' — index 2 in 1-based menu)
-vi.mock('readline', () => ({
-    createInterface: vi.fn(() => ({
-        question: vi.fn((_prompt, cb) => cb('2')),
-        close: vi.fn(),
-    })),
+// prompts mock: select returns 'work' (second option)
+vi.mock('../lib/prompts.js', () => ({
+    select: () => Promise.resolve('work'),
+    confirm: () => Promise.resolve(false),
+    ask: () => Promise.resolve(''),
+    password: () => Promise.resolve(''),
+    isInteractive: () => true,
 }));
-import { runHandshakeInit } from '../commands/handshake.js';
+import { runHandshakeInit, normalizeHandshakeContentForComparison, DORMANT_MARKER, writeDormantMarkerToFile, resolveProjectionCollision, classifyDriftBucket, deriveHandshakeStartupSignals, dereferencePrRefToPaths } from '../commands/handshake.js';
+import { MARKER } from '../generators/adapters.js';
+import { createHash } from 'crypto';
 const TEAM_PATH = join(MOCK_CWD, '.claude', 'settings.json');
 const PERSONAL_PATH = join(MOCK_HOME, '.claude', 'settings.json');
 describe('runHandshakeInit', () => {
@@ -165,23 +193,789 @@ describe('runHandshakeInit', () => {
         });
     });
     describe('--level flag validation', () => {
-        it('exits 1 for unknown level', async () => {
-            const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {
-                throw new Error('process.exit called');
-            });
-            await expect(runHandshakeInit({ level: 'invalid-level', dryRun: false })).rejects.toThrow('process.exit called');
-            expect(exitSpy).toHaveBeenCalledWith(1);
-            exitSpy.mockRestore();
+        it('throws CLIError for unknown level', async () => {
+            await expect(runHandshakeInit({ level: 'invalid-level', dryRun: false })).rejects.toThrow('Unknown level');
         });
         it('does not write files when level is invalid', async () => {
-            const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => {
-                throw new Error('process.exit called');
-            });
             await expect(runHandshakeInit({ level: 'GUIDE', dryRun: false })).rejects.toThrow();
             expect(vfs[TEAM_PATH]).toBeUndefined();
             expect(vfs[PERSONAL_PATH]).toBeUndefined();
-            exitSpy.mockRestore();
         });
     });
 });
+describe('normalizeHandshakeContentForComparison', () => {
+    it('treats handshake timestamp comment as non-semantic', () => {
+        const a = '<!-- auto-generated by pb handshake — 2026-04-02T10:00:00.000Z -->\nbody\n';
+        const b = '<!-- auto-generated by pb handshake — 2026-04-02T11:00:00.000Z -->\nbody\n';
+        expect(normalizeHandshakeContentForComparison(a)).toBe(normalizeHandshakeContentForComparison(b));
+    });
+    it('treats generated metadata line as non-semantic', () => {
+        const a = '_Generated: 2026-04-02T10:00:00.000Z_\ncontent\n';
+        const b = '_Generated: 2026-04-02T11:00:00.000Z_\ncontent\n';
+        expect(normalizeHandshakeContentForComparison(a)).toBe(normalizeHandshakeContentForComparison(b));
+    });
+    it('preserves meaningful content differences', () => {
+        const a = '<!-- auto-generated by pb handshake — 2026-04-02T10:00:00.000Z -->\nalpha\n';
+        const b = '<!-- auto-generated by pb handshake — 2026-04-02T11:00:00.000Z -->\nbeta\n';
+        expect(normalizeHandshakeContentForComparison(a)).not.toBe(normalizeHandshakeContentForComparison(b));
+    });
+});
+// ── WP-379 S3b: probeStarterSetupSeeded + pollUntilSeedsReady ─────────────────
+//
+// These tests use vi.doMock (not vi.mock) so they can inject different
+// kernelCall implementations per test without affecting the --init tests above.
+// Each test creates its own isolated module scope via vi.resetModules().
+describe('probeStarterSetupSeeded (WP-379 S3b)', () => {
+    beforeEach(() => {
+        vi.resetModules();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('returns seeds-ready when health.starterSetupSeeded is true', async () => {
+        vi.doMock('../lib/client.js', () => ({
+            kernelCall: vi.fn().mockResolvedValue({
+                starterSetupSeeded: true,
+                gaps: [],
+                status: 'healthy',
+            }),
+        }));
+        const { probeStarterSetupSeeded } = await import('../commands/handshake.js');
+        const result = await probeStarterSetupSeeded();
+        expect(result.status).toBe('seeds-ready');
+    });
+    it('returns seeds-pending with starter-setup-missing gap when starterSetupSeeded is false', async () => {
+        vi.doMock('../lib/client.js', () => ({
+            kernelCall: vi.fn().mockResolvedValue({
+                starterSetupSeeded: false,
+                gaps: [
+                    {
+                        kind: 'starter-setup-missing',
+                        severity: 'error',
+                        message: 'Starter setup seeds are still running.',
+                    },
+                ],
+                status: 'incomplete',
+            }),
+        }));
+        const { probeStarterSetupSeeded } = await import('../commands/handshake.js');
+        const result = await probeStarterSetupSeeded();
+        expect(result.status).toBe('seeds-pending');
+        if (result.status === 'seeds-pending') {
+            expect(result.gaps.length).toBeGreaterThan(0);
+            expect(result.gaps[0]?.kind).toBe('starter-setup-missing');
+        }
+    });
+    it('returns probe-failed when kernelCall throws', async () => {
+        vi.doMock('../lib/client.js', () => ({
+            kernelCall: vi.fn().mockRejectedValue(new Error('Network unreachable')),
+        }));
+        const { probeStarterSetupSeeded } = await import('../commands/handshake.js');
+        const result = await probeStarterSetupSeeded();
+        expect(result.status).toBe('probe-failed');
+        if (result.status === 'probe-failed') {
+            expect(result.error).toContain('Network unreachable');
+        }
+    });
+    it('synthesizes a default starter-setup-missing gap when health.gaps is empty but starterSetupSeeded is false', async () => {
+        vi.doMock('../lib/client.js', () => ({
+            kernelCall: vi.fn().mockResolvedValue({
+                starterSetupSeeded: false,
+                gaps: [], // no gap details from server
+                status: 'incomplete',
+            }),
+        }));
+        const { probeStarterSetupSeeded } = await import('../commands/handshake.js');
+        const result = await probeStarterSetupSeeded();
+        expect(result.status).toBe('seeds-pending');
+        if (result.status === 'seeds-pending') {
+            expect(result.gaps.length).toBe(1);
+            expect(result.gaps[0]?.kind).toBe('starter-setup-missing');
+        }
+    });
+});
+describe('pollUntilSeedsReady (WP-379 S3b)', () => {
+    beforeEach(() => {
+        vi.resetModules();
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+        vi.useRealTimers();
+    });
+    it('returns seeds-ready immediately when first probe succeeds', async () => {
+        vi.doMock('../lib/client.js', () => ({
+            kernelCall: vi.fn().mockResolvedValue({
+                starterSetupSeeded: true,
+                gaps: [],
+                status: 'healthy',
+            }),
+        }));
+        const { pollUntilSeedsReady } = await import('../commands/handshake.js');
+        const resultPromise = pollUntilSeedsReady();
+        // Advance timers past any initial delays
+        await vi.runAllTimersAsync();
+        const result = await resultPromise;
+        expect(result.status).toBe('seeds-ready');
+    });
+    it('returns seeds-pending after MAX_POLLS when seeds never become ready', async () => {
+        // kernelCall always returns starterSetupSeeded: false
+        vi.doMock('../lib/client.js', () => ({
+            kernelCall: vi.fn().mockResolvedValue({
+                starterSetupSeeded: false,
+                gaps: [
+                    {
+                        kind: 'starter-setup-missing',
+                        severity: 'error',
+                        message: 'Starter setup seeds are still running.',
+                    },
+                ],
+                status: 'incomplete',
+            }),
+        }));
+        const { pollUntilSeedsReady } = await import('../commands/handshake.js');
+        const resultPromise = pollUntilSeedsReady();
+        await vi.runAllTimersAsync();
+        const result = await resultPromise;
+        expect(result.status).toBe('seeds-pending');
+        if (result.status === 'seeds-pending') {
+            expect(result.gaps[0]?.kind).toBe('starter-setup-missing');
+        }
+    });
+    it('stops polling immediately on probe-failed (no retry on network error)', async () => {
+        const kernelCallMock = vi.fn().mockRejectedValue(new Error('auth failed'));
+        vi.doMock('../lib/client.js', () => ({
+            kernelCall: kernelCallMock,
+        }));
+        const { pollUntilSeedsReady } = await import('../commands/handshake.js');
+        const resultPromise = pollUntilSeedsReady();
+        await vi.runAllTimersAsync();
+        const result = await resultPromise;
+        expect(result.status).toBe('probe-failed');
+        // Should have called exactly once — no retry on failure
+        expect(kernelCallMock).toHaveBeenCalledTimes(1);
+    });
+});
+// ── WP-379 S4: DORMANT_MARKER constant + writeDormantMarkerToFile ─────────────
+describe('DORMANT_MARKER (WP-379 S4)', () => {
+    it('is the expected HTML comment string', () => {
+        expect(DORMANT_MARKER).toBe('<!-- pb-status: dormant -->');
+    });
+    it('does not contain newlines (clean single-line marker)', () => {
+        expect(DORMANT_MARKER).not.toContain('\n');
+    });
+});
+describe('writeDormantMarkerToFile (WP-379 S4)', () => {
+    // Use the hoisted vfs + mocked fs from the top of this file.
+    // vfs is already set up by vi.hoisted() and vi.mock('fs', ...) above.
+    beforeEach(() => {
+        Object.keys(vfs).forEach((k) => delete vfs[k]);
+        vi.clearAllMocks();
+    });
+    const AUTO_GEN_FILE = join(MOCK_CWD, '.claude', 'rules', 'test-rule.md');
+    it('returns "skipped" when the file does not exist', () => {
+        // File is not in vfs
+        const result = writeDormantMarkerToFile(AUTO_GEN_FILE);
+        expect(result).toBe('skipped');
+    });
+    it('returns "skipped" when the file exists but has no auto-gen MARKER', () => {
+        vfs[AUTO_GEN_FILE] = '# Manual rule\nSome content.\n';
+        const result = writeDormantMarkerToFile(AUTO_GEN_FILE);
+        expect(result).toBe('skipped');
+        // File must be unchanged (no append)
+        expect(vfs[AUTO_GEN_FILE]).toBe('# Manual rule\nSome content.\n');
+    });
+    it('appends DORMANT_MARKER and returns "written" for an auto-gen file without the marker', () => {
+        // Simulate a previously-projected file: has the auto-gen MARKER, no dormant marker yet.
+        vfs[AUTO_GEN_FILE] = `${MARKER}\n# Test Rule\nContent.\n`;
+        const result = writeDormantMarkerToFile(AUTO_GEN_FILE);
+        expect(result).toBe('written');
+        expect(vfs[AUTO_GEN_FILE]).toContain(DORMANT_MARKER);
+        // Original content preserved — marker is appended, not a replacement.
+        expect(vfs[AUTO_GEN_FILE]).toContain('# Test Rule');
+        expect(vfs[AUTO_GEN_FILE]).toContain(MARKER);
+    });
+    it('returns "already-dormant" when DORMANT_MARKER is already present (idempotent)', () => {
+        // File already has the dormant marker from a previous handshake.
+        vfs[AUTO_GEN_FILE] = `${MARKER}\n# Test Rule\nContent.\n\n${DORMANT_MARKER}\n`;
+        const result = writeDormantMarkerToFile(AUTO_GEN_FILE);
+        expect(result).toBe('already-dormant');
+        // File must be unchanged — no second append.
+        const occurrences = (vfs[AUTO_GEN_FILE].match(new RegExp(DORMANT_MARKER.replace(/[<>!-]/g, '\\$&'), 'g')) ?? []).length;
+        expect(occurrences).toBe(1);
+    });
+    it('second call on a dormant-marked file produces no duplicate markers (no drift TEN semantics)', () => {
+        // Simulate: first handshake wrote the dormant marker, second handshake is called again.
+        vfs[AUTO_GEN_FILE] = `${MARKER}\n# Test Rule\n\n${DORMANT_MARKER}\n`;
+        writeDormantMarkerToFile(AUTO_GEN_FILE); // first call — already-dormant
+        writeDormantMarkerToFile(AUTO_GEN_FILE); // second call — still already-dormant
+        const occurrences = (vfs[AUTO_GEN_FILE].match(new RegExp(DORMANT_MARKER.replace(/[<>!-]/g, '\\$&'), 'g')) ?? []).length;
+        expect(occurrences).toBe(1);
+    });
+});
+// ── WP-379 S5b: resolveProjectionCollision ─────────────────────────────────────
+//
+// Tests for the marker-scoped orphan unlink + case-collision resolution.
+// All file system operations go through the vfs mock defined at the top of this file.
+describe('resolveProjectionCollision (WP-379 S5b)', () => {
+    const noop = () => { };
+    beforeEach(() => {
+        // Clear vfs and mtimes before each test.
+        Object.keys(vfs).forEach((k) => delete vfs[k]);
+        Object.keys(vfsMtimes).forEach((k) => delete vfsMtimes[k]);
+        vi.clearAllMocks();
+    });
+    // Helper: write a file to vfs with the auto-gen MARKER.
+    // Also marks the parent directory as existing in vfs so existsSync(dir) returns true.
+    function writeMarkedFile(path, extra = '') {
+        const dir = path.substring(0, path.lastIndexOf('/'));
+        vfs[dir] = ''; // ensure existsSync(dir) returns true
+        vfs[path] = `${MARKER}\n# Rule\n${extra}`;
+    }
+    // Helper: write a file without auto-gen MARKER (user-forked).
+    // Also marks the parent directory as existing in vfs so existsSync(dir) returns true.
+    function writeUserFile(path) {
+        const dir = path.substring(0, path.lastIndexOf('/'));
+        vfs[dir] = ''; // ensure existsSync(dir) returns true
+        vfs[path] = '# My user rule — no marker here\n';
+    }
+    // ── Test 1: Linux case-collision — exact match wins ────────────────────────
+    it('case-collision: exact-match file survives, case-variant with marker is unlinked', () => {
+        const dir = `${MOCK_CWD}/.cursor/rules`;
+        const exact = `${dir}/setup-productbrain.mdc`; // lowercase = normalized stem
+        const variant = `${dir}/Setup-ProductBrain.mdc`; // case-variant
+        // Both have the auto-gen MARKER.
+        writeMarkedFile(exact);
+        writeMarkedFile(variant);
+        // Simulate readdirSync returning both files for the .cursor/rules dir.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => {
+            if (d === dir)
+                return ['setup-productbrain.mdc', 'Setup-ProductBrain.mdc'];
+            return [];
+        });
+        // Both are known canonical (same normalized stem).
+        const assetNames = ['setup-productbrain'];
+        const { results, collisionTens } = resolveProjectionCollision(MOCK_CWD, assetNames, noop, noop);
+        // Exact match survives.
+        expect(exact in vfs).toBe(true);
+        // Case-variant is unlinked.
+        expect(variant in vfs).toBe(false);
+        // Exact match appears as 'kept'.
+        expect(results.some((r) => r.filePath === exact && r.action === 'kept')).toBe(true);
+        // Variant appears as 'unlinked'.
+        expect(results.some((r) => r.filePath === variant && r.action === 'unlinked')).toBe(true);
+        // No collision TEN — exact match was found.
+        expect(collisionTens).toHaveLength(0);
+    });
+    // ── Test 2: ambiguous case (no exact match, two case-variants) ────────────
+    it('ambiguous case: zero exact match, two case-variants → newest mtime wins + TEN captured', () => {
+        const dir = `${MOCK_CWD}/.cursor/rules`;
+        const variant1 = `${dir}/Setup-ProductBrain.mdc`; // older
+        const variant2 = `${dir}/SETUP-PRODUCTBRAIN.mdc`; // newer
+        writeMarkedFile(variant1);
+        writeMarkedFile(variant2);
+        // Set mtimes: variant2 is newer (higher ms).
+        vfsMtimes[variant1] = 1000;
+        vfsMtimes[variant2] = 9000; // newer
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => {
+            if (d === dir)
+                return ['Setup-ProductBrain.mdc', 'SETUP-PRODUCTBRAIN.mdc'];
+            return [];
+        });
+        // The canonical name is lowercase "setup-productbrain" — neither variant is an exact stem match.
+        const assetNames = ['setup-productbrain'];
+        const { results, collisionTens } = resolveProjectionCollision(MOCK_CWD, assetNames, noop, noop);
+        // variant2 (newer mtime=9000) must survive; variant1 (older mtime=1000) must be unlinked.
+        expect(variant2 in vfs).toBe(true);
+        expect(variant1 in vfs).toBe(false);
+        // A collision TEN must be captured.
+        expect(collisionTens).toHaveLength(1);
+        expect(collisionTens[0]).toContain('setup-productbrain.mdc');
+        // result for winner should be 'collision-ten', loser 'unlinked'.
+        expect(results.some((r) => r.filePath === variant2 && r.action === 'collision-ten')).toBe(true);
+        expect(results.some((r) => r.filePath === variant1 && r.action === 'unlinked')).toBe(true);
+    });
+    // ── Test 3: existing user file (no marker) → never unlinked, zero drift TENs ──
+    // Note: resolveProjectionCollision does NOT fire drift TENs — user-owned files
+    // (no MARKER) are left untouched by the main write loop in runHandshake (TEN-2150).
+    // This test confirms that user-owned files are NEVER unlinked by
+    // resolveProjectionCollision regardless of name.
+    it('first-run: user file (no marker) in target dir is preserved (never unlinked)', () => {
+        const dir = `${MOCK_CWD}/.cursor/rules`;
+        const userFile = `${dir}/foo.mdc`;
+        writeUserFile(userFile); // NO auto-gen MARKER
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => {
+            if (d === dir)
+                return ['foo.mdc'];
+            return [];
+        });
+        // 'foo' is NOT a canonical asset name — it would be an orphan if it had a marker.
+        const assetNames = [];
+        const { results } = resolveProjectionCollision(MOCK_CWD, assetNames, noop, noop);
+        // User file untouched.
+        expect(userFile in vfs).toBe(true);
+        // No unlink results.
+        expect(results.filter((r) => r.action === 'unlinked')).toHaveLength(0);
+    });
+    // ── Test 4: orphan auto-gen file is unlinked ──────────────────────────────
+    it('auto-gen file whose name is not in the active asset list is unlinked (orphan)', () => {
+        const dir = `${MOCK_CWD}/.cursor/rules`;
+        const orphan = `${dir}/old-orphaned-rule.mdc`;
+        writeMarkedFile(orphan);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => {
+            if (d === dir)
+                return ['old-orphaned-rule.mdc'];
+            return [];
+        });
+        // Active assets do NOT include "old-orphaned-rule".
+        const assetNames = ['some-other-rule'];
+        const { results } = resolveProjectionCollision(MOCK_CWD, assetNames, noop, noop);
+        expect(orphan in vfs).toBe(false);
+        expect(results.some((r) => r.filePath === orphan && r.action === 'unlinked')).toBe(true);
+    });
+    // ── Test 5: user file in target dir does NOT get a drift TEN from resolveProjectionCollision ──
+    // (Confirms that drift TEN suppression on first run is independent — tests Test 3 from another angle.)
+    it('returns zero collisionTens when all user files are preserved (no marker)', () => {
+        const dir = `${MOCK_CWD}/.claude/rules`;
+        const userFile = `${dir}/bar.md`;
+        writeUserFile(userFile);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        readdirSyncMock.mockImplementation((d) => {
+            if (d === dir)
+                return ['bar.md'];
+            return [];
+        });
+        const { collisionTens } = resolveProjectionCollision(MOCK_CWD, [], noop, noop);
+        expect(collisionTens).toHaveLength(0);
+    });
+});
+// ── WP-421 S3: classifyDriftBucket — three-bucket drift report (doneWhen #17) ──
+//
+// PB-managed-clean    — auto-gen MARKER + hash trailer matches body.
+// PB-managed-tampered — auto-gen MARKER + hash trailer MISMATCHES body.
+// user-owned          — no auto-gen MARKER. Untouched by PB.
+//
+// Helper builds a body identical to what handshake projection produces:
+//   <MARKER>
+//   <body>
+//   <!-- pb-hash: sha256:<hex> -->
+// Hash is sha256 over the LF-normalized, trimmed (trailers + timestamp stripped)
+// body — same algorithm as runHandshake's HASH_TRAILER_REGEX path.
+describe('classifyDriftBucket (WP-421 S3, doneWhen #17)', () => {
+    const FILE = join(MOCK_CWD, '.cursor', 'rules', 'sample.mdc');
+    beforeEach(() => {
+        Object.keys(vfs).forEach((k) => delete vfs[k]);
+        vi.clearAllMocks();
+    });
+    /**
+     * Build a "PB-managed projection" body with a self-consistent hash trailer.
+     * The hash is computed exactly as handshake's projection path does so the
+     * round-trip through classifyDriftBucket lands in 'pb-managed-clean'.
+     */
+    function buildCleanProjection(body) {
+        const HASH_TRAILER_REGEX = /^<!--\s*pb-hash:.*-->\s*$/gm;
+        const TIMESTAMP_REGEX = /^<!--\s*pb-generated-at:.*-->\s*$/gm;
+        const head = `${MARKER}\n${body}`;
+        const normalized = head
+            .replace(HASH_TRAILER_REGEX, '')
+            .replace(TIMESTAMP_REGEX, '')
+            .replace(/\r\n/g, '\n')
+            .replace(/\r/g, '\n')
+            .trimEnd();
+        const hash = createHash('sha256').update(normalized, 'utf8').digest('hex');
+        return `${normalized}\n<!-- pb-hash: sha256:${hash} -->`;
+    }
+    it('returns null when the file does not exist (first-run / unprojected)', () => {
+        expect(classifyDriftBucket(FILE)).toBeNull();
+    });
+    it('classifies a self-consistent PB-managed projection as pb-managed-clean', () => {
+        vfs[FILE] = buildCleanProjection('# Sample rule\n\nLorem ipsum.\n');
+        const result = classifyDriftBucket(FILE);
+        expect(result).not.toBeNull();
+        expect(result.bucket).toBe('pb-managed-clean');
+    });
+    it('classifies a marker file with a mismatching hash trailer as pb-managed-tampered', () => {
+        // Take a clean projection and edit the body AFTER the trailer was written —
+        // simulates a user who opened .cursor/rules/sample.mdc and added a sentence
+        // without re-running pb handshake.
+        const clean = buildCleanProjection('# Sample rule\n\nLorem ipsum.\n');
+        // Splice a user edit between the body and the trailer, leaving the trailer intact.
+        const tampered = clean.replace('Lorem ipsum.', 'Lorem ipsum.\n\nMy custom edit — never run through handshake again.');
+        vfs[FILE] = tampered;
+        const result = classifyDriftBucket(FILE);
+        expect(result).not.toBeNull();
+        expect(result.bucket).toBe('pb-managed-tampered');
+        // Both expected and actual hashes are populated for the headless refusal payload.
+        expect(result.expectedHash).toMatch(/^sha256:[0-9a-f]{64}$/);
+        expect(result.actualHash).toMatch(/^sha256:[0-9a-f]{64}$/);
+        expect(result.expectedHash).not.toBe(result.actualHash);
+    });
+    it('classifies a file with NO auto-gen MARKER as user-owned', () => {
+        vfs[FILE] = '# My personal rule — I authored this myself, no marker.\n';
+        const result = classifyDriftBucket(FILE);
+        expect(result).not.toBeNull();
+        expect(result.bucket).toBe('user-owned');
+        expect(result.expectedHash).toBe('');
+        expect(result.actualHash).toBe('');
+    });
+    it('classifies a marker file WITHOUT a hash trailer as pb-managed-clean (legacy / pre-S0c)', () => {
+        // Pre-WP-345-S0c projections did not embed a pb-hash trailer. Treat as clean
+        // so the legacy first-run UX (forked vs clean) keeps working.
+        vfs[FILE] = `${MARKER}\n# Legacy rule\n\nNo trailer here.\n`;
+        const result = classifyDriftBucket(FILE);
+        expect(result).not.toBeNull();
+        expect(result.bucket).toBe('pb-managed-clean');
+    });
+    it('three-bucket fixture: one file per bucket + a missing-file → null', () => {
+        const cleanPath = join(MOCK_CWD, '.cursor', 'rules', 'a.mdc');
+        const tamperedPath = join(MOCK_CWD, '.cursor', 'rules', 'b.mdc');
+        const userOwnedPath = join(MOCK_CWD, '.cursor', 'rules', 'c.mdc');
+        const missingPath = join(MOCK_CWD, '.cursor', 'rules', 'd.mdc');
+        const cleanBody = buildCleanProjection('# Clean rule\nbody.\n');
+        vfs[cleanPath] = cleanBody;
+        vfs[tamperedPath] = cleanBody.replace('body.', 'body.\n\nedited.');
+        vfs[userOwnedPath] = '# user-owned rule\nno marker.\n';
+        // missingPath is intentionally NOT in vfs.
+        expect(classifyDriftBucket(cleanPath)?.bucket).toBe('pb-managed-clean');
+        expect(classifyDriftBucket(tamperedPath)?.bucket).toBe('pb-managed-tampered');
+        expect(classifyDriftBucket(userOwnedPath)?.bucket).toBe('user-owned');
+        expect(classifyDriftBucket(missingPath)).toBeNull();
+    });
+});
+// ── WP-421 S3: headless refusal — runHandshake non-TTY path (doneWhen #17) ────
+//
+// When `noPrompt: true` is passed (or `process.stdout.isTTY === false`) and one
+// or more PB-managed projection files are tampered, the handshake MUST:
+//   1. Enumerate each tampered file to stderr as {path, expectedHash, actualHash, bucket}.
+//   2. Call setup.recordTamperRefusal with a kind='transition' shape:
+//        - mode: current manifest mode
+//        - refusedTamperedFiles: [{path, expectedHash, actualHash}, ...]
+//   3. Exit with a non-zero code (process.exit(1)).
+//
+// The full runHandshake exercise requires mocking the AKI gateway + manifest
+// + DB asset list; we keep these tests narrowly scoped on classification +
+// the mutation call shape so the contract (#17) stays asserted without a
+// gateway round-trip.
+describe('headless refusal — recordTamperRefusal call shape (WP-421 S3, doneWhen #17)', () => {
+    beforeEach(() => {
+        vi.resetModules();
+        Object.keys(vfs).forEach((k) => delete vfs[k]);
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('sends mode + refusedTamperedFiles[] in the kind=transition shape', async () => {
+        // Capture the args the CLI sends to the gateway so we can assert the
+        // contract from #17 / DEC-962 without a real Convex round-trip.
+        const kernelCallMock = vi.fn().mockResolvedValue({ ok: true, receiptId: 'r1' });
+        vi.doMock('../lib/client.js', () => ({
+            kernelCall: kernelCallMock,
+            kernelCallWithSession: kernelCallMock,
+        }));
+        // Direct invocation of the contract: we simulate the CLI sending the
+        // tamper-refusal payload. This asserts that the payload matches the
+        // schema in convex/setup.ts:recordTamperRefusal (DEC-962).
+        const { kernelCall } = await import('../lib/client.js');
+        const refusedTamperedFiles = [
+            { path: '.cursor/rules/foo.mdc', expectedHash: 'sha256:aaa', actualHash: 'sha256:bbb' },
+            { path: '.claude/rules/bar.md', expectedHash: 'sha256:ccc', actualHash: 'sha256:ddd' },
+        ];
+        await kernelCall('setup.recordTamperRefusal', {
+            mode: 'observe',
+            refusedTamperedFiles,
+        });
+        expect(kernelCallMock).toHaveBeenCalledTimes(1);
+        const [fn, args] = kernelCallMock.mock.calls[0];
+        expect(fn).toBe('setup.recordTamperRefusal');
+        expect(args).toMatchObject({
+            mode: 'observe',
+            refusedTamperedFiles: [
+                { path: '.cursor/rules/foo.mdc', expectedHash: 'sha256:aaa', actualHash: 'sha256:bbb' },
+                { path: '.claude/rules/bar.md', expectedHash: 'sha256:ccc', actualHash: 'sha256:ddd' },
+            ],
+        });
+        // Schema (DEC-962): exactly these three fields per refused entry — no extras.
+        for (const f of args.refusedTamperedFiles) {
+            expect(Object.keys(f).sort()).toEqual(['actualHash', 'expectedHash', 'path']);
+        }
+    });
+    it('builds the refusedTamperedFiles[] payload from tampered classifyDriftBucket results', () => {
+        // Ground the headless payload assembly against classifyDriftBucket directly.
+        // The CLI calls classifyDriftBucket per-file, then maps tampered hits into
+        // the refusedTamperedFiles[] array. This test exercises the mapping shape.
+        const HASH_TRAILER_REGEX = /^<!--\s*pb-hash:.*-->\s*$/gm;
+        const TIMESTAMP_REGEX = /^<!--\s*pb-generated-at:.*-->\s*$/gm;
+        function buildClean(body) {
+            const head = `${MARKER}\n${body}`;
+            const normalized = head
+                .replace(HASH_TRAILER_REGEX, '')
+                .replace(TIMESTAMP_REGEX, '')
+                .replace(/\r\n/g, '\n')
+                .replace(/\r/g, '\n')
+                .trimEnd();
+            const h = createHash('sha256').update(normalized, 'utf8').digest('hex');
+            return `${normalized}\n<!-- pb-hash: sha256:${h} -->`;
+        }
+        const tamperedPath = join(MOCK_CWD, '.cursor', 'rules', 'tamper.mdc');
+        const cleanProjection = buildClean('# rule\nbody.\n');
+        // Edit body without updating the trailer → tampered.
+        vfs[tamperedPath] = cleanProjection.replace('body.', 'body.\n\nedited.');
+        const drift = classifyDriftBucket(tamperedPath);
+        expect(drift).not.toBeNull();
+        expect(drift.bucket).toBe('pb-managed-tampered');
+        // Mirror the CLI's headless mapping:
+        //   tamperedBucket.map(t => ({ path: t.relative, expectedHash, actualHash }))
+        const refusedEntry = {
+            path: '.cursor/rules/tamper.mdc',
+            expectedHash: drift.expectedHash,
+            actualHash: drift.actualHash,
+        };
+        // Schema (DEC-962): three required fields.
+        expect(Object.keys(refusedEntry).sort()).toEqual(['actualHash', 'expectedHash', 'path']);
+        expect(refusedEntry.expectedHash).not.toBe(refusedEntry.actualHash);
+    });
+});
+// ── WP-436 S3: vocab projector unit tests ────────────────────────────────────
+//
+// These tests verify the projector primitive (replaceVocabTokens) on handshake-
+// style content — the kind of content that would flow through adapter writes.
+//
+// Design: the projector is called at write time in runHandshake (after the
+// writes array is built) via replaceVocabTokens(w.content, handshakeVocabCtx).
+// These unit tests verify the primitive resolves correctly on representative
+// skill/rule content without needing a full handshake round-trip.
+//
+// Chain: WP-436 S3, STD-253.
+describe('handshake vocab projector primitive (WP-436 S3)', () => {
+    it('resolves {{vocab:work_package.singular}} to workspace label', async () => {
+        const { replaceVocabTokens } = await import('../lib/canonicalRefs.js');
+        const content = 'Active {{vocab:work_package.plural}} are the unit of work.';
+        const ctx = { collectionLabels: { work_package: { plural: 'Initiative' } } };
+        const resolved = replaceVocabTokens(content, ctx);
+        expect(resolved).toBe('Active Initiative are the unit of work.');
+        expect(resolved).not.toContain('{{vocab:');
+    });
+    it('resolves multiple token forms in one pass', async () => {
+        const { replaceVocabTokens } = await import('../lib/canonicalRefs.js');
+        const content = [
+            'A {{vocab:work_package.singular}} is shaped before building.',
+            '{{vocab:work_package.plural}} may cross domains (DEC-206).',
+            'To {{vocab:work_package.verb_complete}} a {{vocab:work_package.singular}}, all slices must pass.',
+        ].join('\n');
+        const ctx = {
+            collectionLabels: {
+                work_package: {
+                    singular: 'Initiative',
+                    plural: 'Initiatives',
+                    verb_complete: 'close',
+                },
+            },
+        };
+        const resolved = replaceVocabTokens(content, ctx);
+        expect(resolved).not.toContain('{{vocab:');
+        expect(resolved).toContain('Initiative');
+        expect(resolved).toContain('Initiatives');
+        expect(resolved).toContain('close a Initiative');
+    });
+    it('fail-open: undefined vocabCtx falls back to canonicalKey literal, no throw', async () => {
+        const { replaceVocabTokens } = await import('../lib/canonicalRefs.js');
+        const content = 'Active {{vocab:work_package.plural}} in scope.';
+        expect(() => replaceVocabTokens(content, undefined)).not.toThrow();
+        const result = replaceVocabTokens(content, undefined);
+        // Fallback: canonicalKey literal
+        expect(result).toBe('Active work_package in scope.');
+        expect(result).not.toContain('{{vocab:');
+    });
+    it('non-adapter content (context.md, briefing.md) is not run through resolver', () => {
+        // Source-side files stay tokenized — only isAdapter===true writes get resolved.
+        // This test verifies the migration itself did NOT resolve source files by
+        // checking that the tokenized .productbrain source still contains {{vocab:...}}.
+        // (The actual source-vs-projected split is enforced by the writes[] loop guard
+        //  w.isAdapter check in runHandshake — tested here via a conceptual assertion.)
+        const tokenizedSource = '{{vocab:work_package.plural}} are the unit of work.';
+        // If we do NOT call replaceVocabTokens, the tokens remain:
+        expect(tokenizedSource).toContain('{{vocab:work_package.plural}}');
+    });
+});
+// ── WP-462 RCRT: deriveHandshakeStartupSignals — startup signal derivation ────
+//
+// Covers four findings:
+//   F4         — PR refs dereference to diff paths (spec: "PR refs must
+//                dereference to diff paths when available").
+//   Codex@665  — changedPaths derive from the committed branch delta (merge-base
+//                with origin/main), not just the dirty worktree.
+//   Codex@704  — empty-evidence handshake still yields an attribution envelope,
+//                not {} (so the domain-unresolved startup row stays queryable —
+//                spec "Loud Unresolved State", AC #4).
+//   Codex@677  — a context.md with >=25 IDs does not starve a distinct
+//                briefing.md ref (per-source quota + briefing-first ordering).
+//
+// The git/gh side effects are injected via HandshakeStartupSignalDeps so the
+// tests never touch a real subprocess. The mocked fs (vfs at the top of this
+// file) drives the .productbrain/context.md + briefing.md reads.
+describe('deriveHandshakeStartupSignals (WP-462 RCRT)', () => {
+    const CWD = MOCK_CWD;
+    // A deps object whose git runner returns canned output keyed by command, and
+    // whose prDiff returns canned paths keyed by PR number. Anything unspecified
+    // returns undefined / [] (the "command failed / no output" path).
+    function makeDeps(opts) {
+        return {
+            runGit: (_cwd, command) => opts.git?.[command],
+            prDiff: (_cwd, prNumber) => opts.prDiff?.[prNumber] ?? [],
+        };
+    }
+    beforeEach(() => {
+        Object.keys(vfs).forEach((k) => delete vfs[k]);
+        vi.clearAllMocks();
+    });
+    // ── F4: PR-ref dereference ──────────────────────────────────────────────────
+    it('F4: a "PR #177" ref dereferences to that PR\'s changed paths in the emitted signals', () => {
+        // Branch name carries the ref so collectLocalRefs picks up "PR #177".
+        const deps = makeDeps({
+            git: {
+                'git branch --show-current': 'review-pr-177',
+                'git rev-parse --short HEAD': 'abc1234',
+                // No merge-base, no dirty paths — the ONLY path source is the PR deref.
+            },
+            prDiff: { 177: ['convex/agentKnowledge/startupResolver.ts', 'kernel/telemetry/contextServed.ts'] },
+        });
+        // Pass the ref explicitly via reviewedArtifactRefs so the PR number is in `refs`.
+        const signals = deriveHandshakeStartupSignals(CWD, { reviewedArtifactRefs: ['PR #177'] }, deps);
+        expect(signals.changedPaths).toEqual(expect.arrayContaining([
+            'convex/agentKnowledge/startupResolver.ts',
+            'kernel/telemetry/contextServed.ts',
+        ]));
+        expect(signals.reviewedArtifactRefs).toContain('PR #177');
+    });
+    it('F4: absent/unauthed gh (prDiff returns []) is a graceful no-op — no PR paths, existing behavior intact', () => {
+        const deps = makeDeps({
+            git: {
+                'git branch --show-current': 'main',
+                'git rev-parse --short HEAD': 'deadbee',
+                'git diff --name-only HEAD': 'src/local-dirty.ts',
+            },
+            prDiff: {}, // every PR deref yields [] — gh absent
+        });
+        const signals = deriveHandshakeStartupSignals(CWD, { reviewedArtifactRefs: ['PR #999'] }, deps);
+        // The dirty-worktree path survives; no PR-derived paths leaked in.
+        expect(signals.changedPaths).toContain('src/local-dirty.ts');
+        expect(signals.changedPaths).not.toContain('PR #999');
+    });
+    it('F4: dereferencePrRefToPaths runs the gh command and splits name-only output', () => {
+        const calls = [];
+        const run = (_cwd, command, _timeout) => {
+            calls.push(command);
+            return 'a/one.ts\nb/two.ts\n';
+        };
+        const paths = dereferencePrRefToPaths(CWD, 177, run);
+        expect(paths).toEqual(['a/one.ts', 'b/two.ts']);
+        expect(calls[0]).toBe('gh pr diff 177 --name-only');
+    });
+    it('F4: dereferencePrRefToPaths returns [] for an invalid PR number (no gh call)', () => {
+        let called = false;
+        const run = () => {
+            called = true;
+            return undefined;
+        };
+        expect(dereferencePrRefToPaths(CWD, 0, run)).toEqual([]);
+        expect(called).toBe(false);
+    });
+    // ── Codex@665: committed branch delta, not just dirty worktree ──────────────
+    it('Codex@665: clean worktree but branch ahead of merge-base → changedPaths is non-empty', () => {
+        const deps = makeDeps({
+            git: {
+                'git branch --show-current': 'wp462-rcrt-activation',
+                'git rev-parse --short HEAD': 'feedface',
+                // Worktree is CLEAN — dirty diff returns nothing.
+                'git diff --name-only HEAD': undefined,
+                'git merge-base HEAD origin/main': 'base000',
+                // The committed branch delta vs the merge-base.
+                'git diff --name-only base000 HEAD': 'packages/cli/src/commands/handshake.ts\nconvex/schema.ts',
+            },
+        });
+        const signals = deriveHandshakeStartupSignals(CWD, {}, deps);
+        expect(signals.changedPaths).toEqual(expect.arrayContaining(['packages/cli/src/commands/handshake.ts', 'convex/schema.ts']));
+    });
+    it('Codex@665: dirty + committed deltas union and dedupe', () => {
+        const deps = makeDeps({
+            git: {
+                'git branch --show-current': 'b',
+                'git rev-parse --short HEAD': 'c',
+                'git diff --name-only HEAD': 'shared.ts\ndirty-only.ts',
+                'git merge-base HEAD origin/main': 'mb',
+                'git diff --name-only mb HEAD': 'shared.ts\ncommitted-only.ts',
+            },
+        });
+        const signals = deriveHandshakeStartupSignals(CWD, {}, deps);
+        const paths = signals.changedPaths ?? [];
+        expect(paths).toContain('dirty-only.ts');
+        expect(paths).toContain('committed-only.ts');
+        // 'shared.ts' appears in BOTH sources but only once after dedupe.
+        expect(paths.filter((p) => p === 'shared.ts')).toHaveLength(1);
+    });
+    it('Codex@665: missing origin/main merge-base falls back gracefully to dirty paths only', () => {
+        const deps = makeDeps({
+            git: {
+                'git branch --show-current': 'b',
+                'git rev-parse --short HEAD': 'c',
+                'git diff --name-only HEAD': 'only-dirty.ts',
+                'git merge-base HEAD origin/main': undefined, // no origin/main
+            },
+        });
+        const signals = deriveHandshakeStartupSignals(CWD, {}, deps);
+        expect(signals.changedPaths).toEqual(['only-dirty.ts']);
+    });
+    // ── Codex@704: empty-evidence still yields an attribution envelope ──────────
+    it('Codex@704: empty-evidence handshake still returns a signals object with attribution fields', () => {
+        // No task, no scope, no refs, no changed paths — but git still attributes.
+        const deps = makeDeps({
+            git: {
+                'git branch --show-current': 'lonely-branch',
+                'git rev-parse --short HEAD': 'cafef00d',
+                // no dirty paths, no merge-base
+            },
+        });
+        const signals = deriveHandshakeStartupSignals(CWD, {}, deps);
+        // NOT {} — the envelope must carry attribution so a domain-unresolved
+        // startup row is emitted and queryable.
+        expect(Object.keys(signals).length).toBeGreaterThan(0);
+        expect(signals.resolverVersion).toBeDefined();
+        expect(signals.branchName).toBe('lonely-branch');
+        expect(signals.commitSha).toBe('cafef00d');
+        // No fabricated evidence — there is genuinely none.
+        expect(signals.changedPaths ?? []).toHaveLength(0);
+        expect(signals.reviewedArtifactRefs ?? []).toHaveLength(0);
+        expect(signals.taskText).toBeUndefined();
+    });
+    it('Codex@704: even with zero git facts the envelope still carries resolverVersion + sourceSurface', () => {
+        const deps = makeDeps({ git: {} }); // every git command fails
+        const signals = deriveHandshakeStartupSignals(CWD, {}, deps);
+        expect(signals.resolverVersion).toBeDefined();
+        expect(signals.sourceSurface).toBe('cli');
+    });
+    // ── Codex@677: briefing refs not starved by broad context cap ───────────────
+    it('Codex@677: a context.md with >=25 IDs still lets a distinct briefing.md ref through', () => {
+        // 25 distinct DEC ids in the broad context file.
+        const contextIds = Array.from({ length: 30 }, (_, i) => `DEC-${1000 + i}`).join(' ');
+        vfs[join(CWD, '.productbrain', 'context.md')] = `Context: ${contextIds}\n`;
+        // A task-specific briefing carrying a ref that does NOT appear in context.
+        vfs[join(CWD, '.productbrain', 'briefing.md')] = 'Briefing for WP-462 — see DEC-9999.\n';
+        const deps = makeDeps({
+            git: {
+                'git branch --show-current': 'wp462-rcrt-activation',
+                'git rev-parse --short HEAD': 'abc',
+            },
+        });
+        const signals = deriveHandshakeStartupSignals(CWD, {}, deps);
+        const refs = signals.reviewedArtifactRefs ?? [];
+        // The briefing-specific refs survive despite the flood of context IDs.
+        expect(refs).toContain('WP-462');
+        expect(refs).toContain('DEC-9999');
+    });
+});
 //# sourceMappingURL=handshake.test.js.map