@productbrain/cli 0.1.0-beta.1 → 0.1.0-beta.102

package/dist/commands/handshake.js

@@ -0,0 +1,1349 @@
+/**
+ * pb handshake — generate context files for AI developer tools.
+ * Context export wiring (read-only filesystem bridge; GLO-63, DEC-161) — not a product surface.
+ */
+import { mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync, copyFileSync, appendFileSync, unlinkSync, statSync } from 'fs';
+import { join, dirname, resolve, basename } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { createHash } from 'crypto';
+import { getConfigOrGuide } from '../lib/config.js';
+import { select as promptSelect } from '../lib/prompts.js';
+import { composeHooksFromIntents, getHookStatusForSurface } from '../lib/hook-intents.js';
+import { kernelCall, kernelCallWithSession } from '../lib/client.js';
+import { readSession } from '../lib/session.js';
+import { detectRepo, extractWorkspaceProfile } from '../lib/repo-detect.js';
+import { generateContextMd } from '../generators/context-md.js';
+import { generateBriefingMd } from '../generators/briefing-md.js';
+import { MARKER, generateAgentsMd, generateClaudeMd, generateCursorMdc, generateCopilotMd } from '../generators/adapters.js';
+import { readCanonicalSkills, readCanonicalRules, readPersonalLayer, readPersonalSkillsLayer, generateCursorSkill, generateCursorRule, generateCodexSkill, generateCodexSkillIndex, generateClaudeRule, generateClaudeSkillRouter, shouldEmitToTarget, filterByLevel, validateCodexSkills, evaluateConditions, STAGE_TO_MAX_LEVEL, LEVEL_ORDER, } from '../generators/portable-knowledge.js';
+import { generateChainRules } from '../generators/chain-rules.js';
+import { saveHandshakeState, loadPreviousState, diffHandshakeState, formatDiff, buildCurrentState, } from '../generators/handshake-diff.js';
+import { resolveSurfaceProfile } from '../generators/surface-profiles.js';
+import { formatHandshakeReport } from '../formatters/handshake.js';
+import { readManifest, filterByAdoptionState } from '../generators/manifest.js';
+import { generateBoundaryManifest, getBoundaryEnforcementMode } from '../generators/boundary-manifest.js';
+import { loadMethodRegistry } from '../lib/method-registry.js';
+import { CLIError, ErrorCode } from '../lib/errors.js';
+import { trackEvent } from '../lib/telemetry.js';
+import { normalizeMaterializedFilename } from '../lib/normalizeMaterializedFilename.js';
+const MAX_HANDSHAKE_WAIT_MS = 10_000; // 10 seconds
+const POLL_INTERVAL_MS = 500; // 500 ms per poll
+const MAX_POLLS = MAX_HANDSHAKE_WAIT_MS / POLL_INTERVAL_MS; // 20
+// ── WP-379 S4: Dormant marker ─────────────────────────────────────────────────
+/**
+ * DORMANT_MARKER — appended to previously-projected asset files when the asset's
+ * gate deactivates (e.g. workspace readiness exceeds the max threshold).
+ *
+ * Contract:
+ *   - The file is NOT deleted. It persists on disk so that history is preserved
+ *     and the agent surface remains inspectable.
+ *   - The marker is appended at the end of the file, idempotent — if it already
+ *     exists, no second append occurs.
+ *   - The marker does NOT trigger a drift TEN. Dormant files are intentionally
+ *     deactivated, not accidentally forked.
+ *   - The marker is never included in active file writes — only dormant writes.
+ *
+ * Used by: writeDormantMarker() (write) and hasDormantMarker() (idempotency check).
+ * Exported for use in tests.
+ *
+ * Chain: WP-379 S4.
+ */
+export const DORMANT_MARKER = '<!-- pb-status: dormant -->';
+/**
+ * hasDormantMarker — check whether a file on disk already has the dormant marker.
+ * Used for idempotency: if the marker is already present, skip the append.
+ */
+function hasDormantMarker(content) {
+    return content.includes(DORMANT_MARKER);
+}
+/**
+ * writeDormantMarker — append the dormant marker to a previously-projected file.
+ *
+ * Idempotent: if DORMANT_MARKER is already present, no-op.
+ * Only operates on files that have the auto-gen MARKER — we never touch
+ * manually-authored files.
+ *
+ * @param filePath  Absolute path to the file.
+ * @returns         'written' | 'already-dormant' | 'skipped' (no auto-gen marker)
+ */
+export function writeDormantMarkerToFile(filePath) {
+    if (!existsSync(filePath))
+        return 'skipped';
+    const content = readFileSync(filePath, 'utf8');
+    // Only mark files that were originally projected by pb handshake.
+    // Files without the auto-gen MARKER are manually authored — leave them alone.
+    if (!content.includes(MARKER))
+        return 'skipped';
+    if (hasDormantMarker(content))
+        return 'already-dormant';
+    // Append the marker on its own line. No trailing newline assumption —
+    // appendFileSync adds to whatever is already there.
+    appendFileSync(filePath, `\n${DORMANT_MARKER}\n`);
+    return 'written';
+}
+/**
+ * deriveDormantFilePaths — compute the set of on-disk file paths that would have
+ * been projected for a given dormant asset (by name and assetKind).
+ *
+ * Assets are projected to one or more surfaces (cursor/claude/codex) depending
+ * on shouldEmitToTarget. Since we don't re-run shouldEmitToTarget here, we
+ * speculatively probe all known surface paths and let writeDormantMarkerToFile
+ * decide whether each exists and has the auto-gen MARKER.
+ *
+ * @param asset  The dormant asset from the server.
+ * @param cwd    Current working directory (project root).
+ * @returns      Array of absolute file paths to probe.
+ */
+function deriveDormantFilePaths(asset, cwd) {
+    // Defense-in-depth: even though `name` originates from platform-seeded DB
+    // entries (not user input), validate it against a strict charset before
+    // interpolating into a filesystem path. Reject anything that could traverse
+    // out of the expected directories. WP-379 S4 review finding.
+    if (!/^[A-Za-z0-9._-]+$/.test(asset.name)) {
+        return [];
+    }
+    const paths = [];
+    const { name, assetKind } = asset;
+    if (assetKind === 'skill') {
+        // Cursor skill
+        paths.push(join(cwd, '.cursor', 'skills', name, 'SKILL.md'));
+        // Codex skill
+        paths.push(join(cwd, '.codex', 'skills', `${name}.md`));
+    }
+    else if (assetKind === 'rule' || assetKind === 'hook') {
+        // Cursor rule
+        paths.push(join(cwd, '.cursor', 'rules', `${name}.mdc`));
+        // Claude rule
+        paths.push(join(cwd, '.claude', 'rules', `${name}.md`));
+    }
+    return paths;
+}
+/**
+ * Single-shot health probe — calls `workspace.health` and inspects
+ * `starterSetupSeeded`. Does NOT poll internally; polling is the caller's
+ * responsibility (connect-screens.tsx).
+ *
+ * Returns:
+ *  - `seeds-ready`   — health query succeeded AND starterSetupSeeded is true
+ *  - `seeds-pending` — health query succeeded but starterSetupSeeded is false
+ *  - `probe-failed`  — health query threw (network, auth, etc.)
+ */
+export async function probeStarterSetupSeeded() {
+    try {
+        const health = await kernelCall('workspace.health', {});
+        if (health.starterSetupSeeded) {
+            return { status: 'seeds-ready' };
+        }
+        const starterGaps = (health.gaps ?? []).filter((g) => g.kind === 'starter-setup-missing' || g.kind === 'platform-domains-missing');
+        return {
+            status: 'seeds-pending',
+            gaps: starterGaps.length > 0 ? starterGaps : [
+                {
+                    kind: 'starter-setup-missing',
+                    severity: 'warn',
+                    message: 'Starter setup seeds are still running.',
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            status: 'probe-failed',
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Poll `probeStarterSetupSeeded` up to MAX_POLLS times (10s at 500ms intervals).
+ * Returns the final probe result — caller decides how to render the outcome.
+ *
+ * Exported so connect-screens.tsx can use it without re-implementing the loop.
+ */
+export async function pollUntilSeedsReady() {
+    for (let poll = 0; poll < MAX_POLLS; poll++) {
+        const result = await probeStarterSetupSeeded();
+        if (result.status === 'seeds-ready')
+            return result;
+        if (result.status === 'probe-failed')
+            return result; // don't retry on auth/network errors
+        // seeds-pending — wait before next poll
+        if (poll < MAX_POLLS - 1) {
+            await new Promise((res) => setTimeout(res, POLL_INTERVAL_MS));
+        }
+    }
+    // Final probe after exhausting waits — return whatever state we have
+    return probeStarterSetupSeeded();
+}
+const LEVELS = {
+    guide: {
+        label: 'Guide me',
+        description: "Explain what you're doing, ask before anything unfamiliar",
+        defaultMode: 'auto',
+        allow: ['Bash(pb:*)', 'Bash(git:*)'],
+    },
+    work: {
+        label: 'Just work',
+        description: 'Ask only when something could be risky or irreversible',
+        defaultMode: 'auto',
+        allow: ['Bash(pb:*)', 'Bash(git:*)', 'Bash(npm run:*)'],
+    },
+    silent: {
+        label: 'Silent',
+        description: "I'll review the diff; don't ask unless it's destructive",
+        defaultMode: 'acceptEdits',
+        allow: ['Bash(pb:*)', 'Bash(git:*)', 'Bash(npm run:*)', 'Bash(npx:*)'],
+    },
+    'full-trust': {
+        label: 'Full trust',
+        description: 'Never ask (your machine, your call)',
+        defaultMode: 'bypassPermissions',
+        allow: [],
+    },
+};
+// Explicit ordering — determines menu numbering in promptLevel(). Do not reorder.
+const LEVEL_KEYS = ['guide', 'work', 'silent', 'full-trust'];
+// Hook failure contract (TEN-712): all hook commands MUST end with '2>/dev/null || true'
+// so Claude Code always starts even if pb is unavailable. Never remove this suffix.
+const INIT_PERMISSION = 'Bash(pb:*)';
+function readSettings(filePath) {
+    if (!existsSync(filePath))
+        return {};
+    try {
+        return JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        console.error(`Warning: ${filePath} has invalid JSON — starting fresh.`);
+        return {};
+    }
+}
+// Team write: hooks + Bash(pb:*) → .claude/settings.json (safe to commit)
+function writeTeamSettings(cwd, dryRun) {
+    const claudeDir = join(cwd, '.claude');
+    const settingsPath = join(claudeDir, 'settings.json');
+    const settings = readSettings(settingsPath);
+    const added = [];
+    const permissions = (settings.permissions ?? {});
+    const allow = permissions.allow ?? [];
+    if (!allow.includes(INIT_PERMISSION)) {
+        allow.push(INIT_PERMISSION);
+        permissions.allow = allow;
+        added.push('Bash(pb:*) permission');
+    }
+    settings.permissions = permissions;
+    const hooks = (settings.hooks ?? {});
+    const hookAdditions = composeHooksFromIntents(['session-start', 'session-close', 'pre-compact'], hooks);
+    for (const addition of hookAdditions) {
+        hooks[addition.event] = [...(hooks[addition.event] ?? []), addition.entry];
+        added.push(addition.label);
+    }
+    settings.hooks = hooks;
+    if (!dryRun) {
+        mkdirSync(claudeDir, { recursive: true });
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    }
+    return added;
+}
+// Personal write: trust level → ~/.claude/settings.json (never committed)
+function writePersonalSettings(levelKey, dryRun) {
+    const level = LEVELS[levelKey];
+    const globalDir = join(homedir(), '.claude');
+    const globalPath = join(globalDir, 'settings.json');
+    const settings = readSettings(globalPath);
+    const added = [];
+    const permissions = (settings.permissions ?? {});
+    if (permissions.defaultMode !== level.defaultMode) {
+        permissions.defaultMode = level.defaultMode;
+        added.push(`defaultMode → ${level.defaultMode}`);
+    }
+    const allow = permissions.allow ?? [];
+    for (const entry of level.allow) {
+        if (!allow.includes(entry)) {
+            allow.push(entry);
+            added.push(`allow: ${entry}`);
+        }
+    }
+    permissions.allow = allow;
+    settings.permissions = permissions;
+    if (!dryRun) {
+        mkdirSync(globalDir, { recursive: true });
+        writeFileSync(globalPath, JSON.stringify(settings, null, 2) + '\n');
+    }
+    return added;
+}
+async function promptLevel() {
+    const result = await promptSelect({
+        message: 'How much should Claude explain before acting?',
+        options: LEVEL_KEYS.map((key) => ({
+            value: key,
+            label: LEVELS[key].label,
+            hint: LEVELS[key].description,
+        })),
+    });
+    return result;
+}
+export async function runHandshakeInit(options = {}) {
+    const cwd = process.cwd();
+    const dryRun = options.dryRun ?? false;
+    const suffix = dryRun ? ' (dry run)' : '';
+    if (options.level && !LEVEL_KEYS.includes(options.level)) {
+        throw new CLIError(`Unknown level "${options.level}".`, {
+            code: ErrorCode.VALIDATION_FAILED,
+            category: 'validation',
+            guidance: `Valid levels: ${LEVEL_KEYS.join(', ')}`,
+        });
+    }
+    console.log('Setting up Claude Code integration...\n');
+    // Step 1: Team config — always, no prompt
+    const teamAdded = writeTeamSettings(cwd, dryRun);
+    const teamPath = join(cwd, '.claude', 'settings.json');
+    if (teamAdded.length === 0) {
+        console.log(`✓ ${teamPath} — already up to date${suffix}`);
+    }
+    else {
+        console.log(`✓ ${teamPath}${suffix}`);
+        for (const item of teamAdded)
+            console.log(`    + ${item}`);
+    }
+    // Step 2: Personal config — wizard or --level flag
+    // Cast is safe: LEVEL_KEYS.includes() validated above; invalid level already threw CLIError.
+    const levelKey = options.level ? options.level : await promptLevel();
+    const level = LEVELS[levelKey];
+    const personalAdded = writePersonalSettings(levelKey, dryRun);
+    const personalPath = join(homedir(), '.claude', 'settings.json');
+    if (personalAdded.length === 0) {
+        console.log(`✓ ${personalPath} — already at "${level.label}"${suffix}`);
+    }
+    else {
+        console.log(`✓ ${personalPath} — set to "${level.label}"${suffix}`);
+        for (const item of personalAdded)
+            console.log(`    + ${item}`);
+    }
+    console.log('');
+    console.log('Team config   → commit .claude/settings.json to share hooks with your team');
+    console.log('Personal config → ~/.claude/settings.json is private to this machine, never commit');
+    console.log('');
+    console.log('Hook failure: if pb is unavailable, hooks fail silently — Claude Code always starts.');
+    console.log('');
+    if (!dryRun)
+        console.log('Reload /hooks in Claude Code (or restart) to activate.');
+    console.log('Run `pb handshake --init --level <guide|work|silent|full-trust>` to change level.');
+    // Step 2b: Report multi-surface hook opt-in status (WP-310 E3b)
+    // Reads manifest.hooks.{cursor,copilot} and prints an informational note for
+    // each opted-in surface. Silence = no manifest or no hooks flags set.
+    // DEC-536: Claude-native default is already wired above; this block only fires
+    // when the user has explicitly opted in via manifest.
+    const pbDirForManifest = join(cwd, '.productbrain');
+    const initManifest = readManifest(pbDirForManifest);
+    const multiSurfaceOptIns = [];
+    if (initManifest?.hooks?.cursor)
+        multiSurfaceOptIns.push('cursor');
+    if (initManifest?.hooks?.copilot)
+        multiSurfaceOptIns.push('copilot');
+    if (multiSurfaceOptIns.length > 0) {
+        console.log('');
+        for (const surface of multiSurfaceOptIns) {
+            const status = getHookStatusForSurface(surface);
+            if (status.writable) {
+                // Future-proofing path: surface has hook events, would write files.
+                console.log(`ℹ ${surface} hooks: opted in — hooks will be written`);
+            }
+            else {
+                console.log(`ℹ ${surface} hooks: opted in — no auto-hooks (${surface} has no session events; run \`pb session start\` manually)`);
+            }
+        }
+    }
+    // Step 3: Scaffold starter templates if .productbrain/rules/ is empty
+    const rulesDir = join(cwd, '.productbrain', 'rules');
+    const hasExistingRules = existsSync(rulesDir) && readdirSync(rulesDir).filter((f) => f.endsWith('.md')).length > 0;
+    if (!hasExistingRules) {
+        // Detect stack from repo to pick template set
+        const repo = detectRepo(cwd);
+        const stack = repo.detectedStack.map((s) => s.toLowerCase());
+        let templateSet;
+        if (stack.some((s) => ['typescript', 'sveltekit', 'nextjs', 'react'].includes(s))) {
+            templateSet = 'node-ts';
+        }
+        else if (stack.includes('python')) {
+            templateSet = 'python';
+        }
+        else {
+            templateSet = 'general';
+        }
+        // Resolve templates directory relative to this file
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = dirname(__filename);
+        // From dist/commands/handshake.js → ../../templates/
+        const templatesRoot = resolve(__dirname, '..', '..', 'templates');
+        const templateDir = join(templatesRoot, templateSet);
+        if (existsSync(templateDir)) {
+            const templateFiles = readdirSync(templateDir).filter((f) => f.endsWith('.md'));
+            if (templateFiles.length > 0) {
+                console.log('');
+                console.log(`Scaffolding starter rules from ${templateSet} template...`);
+                if (!dryRun) {
+                    mkdirSync(rulesDir, { recursive: true });
+                    for (const file of templateFiles) {
+                        const src = join(templateDir, file);
+                        const dest = join(rulesDir, file);
+                        copyFileSync(src, dest);
+                        console.log(`  + .productbrain/rules/${file}`);
+                    }
+                    console.log('');
+                    console.log('Run `pb handshake` to sync the scaffolded rules to your AI tools.');
+                }
+                else {
+                    for (const file of templateFiles) {
+                        console.log(`  + .productbrain/rules/${file} (dry run)`);
+                    }
+                }
+            }
+        }
+    }
+}
+/**
+ * Normalize volatile handshake-only timestamps before comparing generated files.
+ * This keeps the visible timestamps in generated artifacts while avoiding
+ * meaningless rewrites when semantic content is unchanged.
+ */
+export function normalizeHandshakeContentForComparison(content) {
+    return content
+        .replace(/<!-- auto-generated by pb handshake — [0-9]{4}-[0-9]{2}-[0-9]{2}T[^>]+ -->/g, '<!-- auto-generated by pb handshake — <TIMESTAMP> -->')
+        .replace(/^_Generated: [0-9]{4}-[0-9]{2}-[0-9]{2}T.*_$/gm, '_Generated: <TIMESTAMP>_');
+}
+function shouldWriteAdapter(filePath, force) {
+    if (force)
+        return true;
+    if (!existsSync(filePath))
+        return true;
+    const content = readFileSync(filePath, 'utf8');
+    return content.includes(MARKER);
+}
+function deduplicateEntries(entries) {
+    const seen = new Set();
+    const result = [];
+    for (const e of entries) {
+        const key = e.entryId ?? e.name;
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(e);
+        }
+    }
+    return result;
+}
+/**
+ * resolveProjectionCollision — WP-379 S5b
+ *
+ * Marker-scoped orphan unlink: enumerates target dirs (.cursor/rules/,
+ * .claude/rules/, .claude/skills/, .codex/skills/); for each file that has
+ * the auto-gen MARKER whose lowercase-normalized filename does NOT match any
+ * current active-asset materializedFilename, the file is unlinked.
+ *
+ * User-forked files (no MARKER) are never touched, regardless of name.
+ *
+ * Linux case-collision disambiguation:
+ *   1. Exact match (lowercase name == any canonical name): survives.
+ *   2. Case-variant with MARKER (marker file, no exact canonical match): unlinked.
+ *   3. Ambiguous (zero exact, multiple case-variants with MARKER):
+ *      newest mtime wins; all others are unlinked; a collision TEN is
+ *      appended to the session capture queue (not fired inline).
+ *
+ * Returns a list of unlink results so the caller can log/report them.
+ *
+ * @param cwd         Project root (absolute path).
+ * @param assetNames  The current set of canonical asset names from the server
+ *                    (e.g. ["Setup-ProductBrain", "chain-rules"]).
+ * @param log         Progress log function.
+ * @param logErr      Error log function.
+ */
+export function resolveProjectionCollision(cwd, assetNames, log, logErr) {
+    // Target directories by extension suffix.
+    const TARGET_DIRS_BY_EXT = [
+        { dir: join(cwd, '.cursor', 'rules'), ext: '.mdc' },
+        { dir: join(cwd, '.claude', 'rules'), ext: '.md' },
+        { dir: join(cwd, '.claude', 'skills'), ext: '.md' },
+        { dir: join(cwd, '.codex', 'skills'), ext: '.md' },
+    ];
+    // Build a set of normalized canonical names (without extension) for fast lookup.
+    // We normalize all asset names to detect case-variant collisions.
+    // For each asset name we derive the normalized basename (the part before the ext).
+    // canonicalNormalizedNames: Set<normalized-stem> (lowercase + slug).
+    const canonicalNormalizedStems = new Set(assetNames.map((n) => normalizeMaterializedFilename(n)));
+    const results = [];
+    const collisionTens = [];
+    for (const { dir, ext } of TARGET_DIRS_BY_EXT) {
+        if (!existsSync(dir))
+            continue;
+        let files;
+        try {
+            files = readdirSync(dir);
+        }
+        catch {
+            continue; // unreadable dir — skip
+        }
+        // Group files by their normalized stem.
+        // normalizedStem → [ { filename, fullPath } ]
+        const groups = new Map();
+        for (const filename of files) {
+            if (!filename.endsWith(ext))
+                continue;
+            const fullPath = join(dir, filename);
+            // Only operate on files that have the auto-gen MARKER.
+            let content;
+            try {
+                content = readFileSync(fullPath, 'utf8');
+            }
+            catch {
+                continue; // unreadable file — skip
+            }
+            if (!content.includes(MARKER))
+                continue; // user-forked — never touch
+            const stem = basename(filename, ext);
+            const normalizedStem = normalizeMaterializedFilename(stem);
+            const group = groups.get(normalizedStem) ?? [];
+            group.push({ filename, fullPath });
+            groups.set(normalizedStem, group);
+        }
+        // Evaluate each normalized stem group.
+        for (const [normalizedStem, members] of groups) {
+            const isKnownCanonical = canonicalNormalizedStems.has(normalizedStem);
+            if (!isKnownCanonical) {
+                // All members of this group are orphans (no canonical asset with this stem).
+                // Unlink them all — they're stale projections of an asset no longer in the server.
+                for (const { filename, fullPath } of members) {
+                    try {
+                        unlinkSync(fullPath);
+                        log(`Orphan unlinked: ${fullPath}`);
+                        results.push({ action: 'unlinked', filePath: fullPath, reason: 'orphan-no-canonical-match' });
+                    }
+                    catch (err) {
+                        logErr(`Warning: could not unlink orphan ${fullPath} — ${err instanceof Error ? err.message : String(err)}`);
+                        results.push({ action: 'kept', filePath: fullPath, reason: 'unlink-failed' });
+                    }
+                }
+                continue;
+            }
+            // The stem IS known canonical. Check for case-collision.
+            if (members.length === 1) {
+                // Single file — no collision.
+                results.push({ action: 'kept', filePath: members[0].fullPath, reason: 'canonical-exact' });
+                continue;
+            }
+            // Multiple files with the same normalized stem → case-collision.
+            // Rule: exact match (filename stem === normalized stem, i.e. already lowercase) wins.
+            const exactMatches = members.filter(({ filename }) => {
+                const stem = basename(filename, ext);
+                return stem === normalizedStem; // lowercase-equal means already normalized
+            });
+            if (exactMatches.length === 1) {
+                // Rule 1: exactly one exact match → keep it, unlink all case-variants.
+                const keeper = exactMatches[0];
+                results.push({ action: 'kept', filePath: keeper.fullPath, reason: 'case-exact-match-wins' });
+                for (const member of members) {
+                    if (member.fullPath === keeper.fullPath)
+                        continue;
+                    try {
+                        unlinkSync(member.fullPath);
+                        log(`Case-variant unlinked: ${member.fullPath} (kept: ${keeper.filename})`);
+                        results.push({ action: 'unlinked', filePath: member.fullPath, reason: 'case-variant-unlinked' });
+                    }
+                    catch (err) {
+                        logErr(`Warning: could not unlink case-variant ${member.fullPath} — ${err instanceof Error ? err.message : String(err)}`);
+                        results.push({ action: 'kept', filePath: member.fullPath, reason: 'unlink-failed' });
+                    }
+                }
+                continue;
+            }
+            // Rule 3: ambiguous — zero exact matches (or multiple exact matches, which
+            // can't happen on a case-sensitive FS). Newest mtime wins.
+            // Sort by mtime descending: highest mtime = newest = winner.
+            const withStats = members.map(({ filename, fullPath }) => {
+                try {
+                    const { mtimeMs } = statSync(fullPath);
+                    return { filename, fullPath, mtimeMs };
+                }
+                catch {
+                    return { filename, fullPath, mtimeMs: 0 };
+                }
+            });
+            withStats.sort((a, b) => b.mtimeMs - a.mtimeMs);
+            const winner = withStats[0];
+            log(`Case-collision ambiguous for ${normalizedStem}${ext}: newest mtime wins (${winner.filename})`);
+            results.push({ action: 'collision-ten', filePath: winner.fullPath, reason: 'ambiguous-newest-mtime-wins' });
+            const tenMsg = `Handshake case-collision: ambiguous filename for stem "${normalizedStem}${ext}" ` +
+                `(${members.map((m) => m.filename).join(', ')}). ` +
+                `Kept newest: ${winner.filename}. Consider renaming to ${normalizedStem}${ext}.`;
+            collisionTens.push(tenMsg);
+            for (const member of withStats.slice(1)) {
+                try {
+                    unlinkSync(member.fullPath);
+                    log(`Case-variant (ambiguous) unlinked: ${member.fullPath}`);
+                    results.push({ action: 'unlinked', filePath: member.fullPath, reason: 'ambiguous-case-variant-unlinked' });
+                }
+                catch (err) {
+                    logErr(`Warning: could not unlink ambiguous case-variant ${member.fullPath} — ${err instanceof Error ? err.message : String(err)}`);
+                    results.push({ action: 'kept', filePath: member.fullPath, reason: 'unlink-failed' });
+                }
+            }
+        }
+    }
+    return { results, collisionTens };
+}
+export async function runHandshake(options = {}) {
+    const config = await getConfigOrGuide(() => runHandshake(options));
+    if (!config)
+        return;
+    const cwd = process.cwd();
+    const force = options.force ?? false;
+    const dryRun = options.dryRun ?? false;
+    // Preview mode: default when neither --apply nor --dry-run is passed.
+    // --dry-run is kept as a backward-compat alias for preview (same behavior).
+    const preview = !options.apply && !dryRun;
+    const applyMode = options.apply === true && !dryRun;
+    const level = options.level;
+    const quiet = options.quiet ?? false;
+    const generate = options.generate ?? false;
+    const timestamp = new Date().toISOString();
+    // Helper: emit progress line only when not quiet (used when handshake is a sub-step)
+    const log = (msg) => { if (!quiet)
+        process.stdout.write(msg + '\n'); };
+    const logErr = (msg) => { if (!quiet)
+        process.stderr.write(msg + '\n'); };
+    // Validate --level if provided (for handshake content filtering, not --init trust level)
+    const VALID_HANDSHAKE_LEVELS = ['beginner', 'intermediate', 'expert'];
+    if (level && !VALID_HANDSHAKE_LEVELS.includes(level)) {
+        throw new CLIError(`Unknown level "${level}".`, {
+            code: ErrorCode.VALIDATION_FAILED,
+            category: 'validation',
+            guidance: `Valid levels: ${VALID_HANDSHAKE_LEVELS.join(', ')}`,
+        });
+    }
+    // 1. Detect repo
+    const repo = detectRepo(cwd);
+    log(`Detecting repo: ${repo.name ?? 'unknown'}${repo.repoSlug ? ` (${repo.repoSlug})` : ''}`);
+    if (repo.detectedStack.length > 0) {
+        log(`Stack: ${repo.detectedStack.join(', ')}`);
+    }
+    // 2. Fetch orient view + workspace readiness in parallel (budget max +200ms added latency)
+    log('Fetching workspace context...');
+    let orientView = null;
+    let workspaceProfile = null;
+    try {
+        const workspaceReadinessPromise = kernelCall('chain.workspaceReadiness', {}).catch(() => null);
+        const [orientResult, readinessRaw] = await Promise.all([
+            kernelCall('chain.getOrientView', {}).catch((err) => {
+                logErr(`Warning: could not fetch workspace context — ${err instanceof Error ? err.message : err}`);
+                logErr('Continuing with limited context (Chain search + portable knowledge only).');
+                return null;
+            }),
+            workspaceReadinessPromise,
+        ]);
+        orientView = orientResult;
+        workspaceProfile = extractWorkspaceProfile(readinessRaw);
+    }
+    catch (err) {
+        logErr(`Warning: could not fetch workspace context — ${err instanceof Error ? err.message : err}`);
+        logErr('Continuing with limited context (Chain search + portable knowledge only).');
+    }
+    if (workspaceProfile) {
+        log(`Workspace profile: stage=${workspaceProfile.stage}, entries=${workspaceProfile.totalEntries}, governance=${workspaceProfile.governanceMode}`);
+    }
+    // 3. Build search queries from repo context
+    const searchQueries = [];
+    if (repo.name && repo.name.length >= 2)
+        searchQueries.push(repo.name);
+    // Add repo slug parts (e.g. "Product-OS" -> "Product-OS")
+    if (repo.repoSlug) {
+        const repoPart = repo.repoSlug.split('/').pop();
+        if (repoPart && repoPart.length >= 2 && repoPart !== repo.name) {
+            searchQueries.push(repoPart);
+        }
+    }
+    // Limit to 5 unique queries
+    const uniqueQueries = [...new Set(searchQueries.filter((q) => q.length >= 2))].slice(0, 5);
+    // 4. Search the Chain
+    let matchedEntries = [];
+    if (uniqueQueries.length > 0) {
+        log(`Searching Chain for: ${uniqueQueries.join(', ')}...`);
+        const searchResults = await Promise.all(uniqueQueries.map((q) => kernelCall('chain.searchEntries', { query: q }).catch(() => [])));
+        matchedEntries = deduplicateEntries(searchResults.flat());
+    }
+    // 5. Read canonical skills & rules — DB-first (WP-345 S0c, TEN-1459), FS fallback.
+    // Primary: query setup.listAssetsForUser from DB (workspace SSOT).
+    // Fallback: read from .productbrain/ filesystem (legacy — used when DB is empty or unavailable).
+    const pbDir = join(cwd, '.productbrain');
+    let dbSkills = [];
+    let dbRules = [];
+    let usedDbSource = false;
+    let dbAssetRows = [];
+    // WP-379 S4: dormant assets (gate-failed) — their on-disk files get the dormant marker.
+    let dormantDbAssetRows = [];
+    // WP-379 S5b: whether any setup_receipt exists for this workspace (first-run UX gate).
+    // undefined when server is pre-S5b (treat as unknown → suppress drift TENs conservatively).
+    let hasAnyReceipt = undefined;
+    const dbProjectionHashes = new Map();
+    try {
+        // WP-379 S4: listAssetsForUser now returns { activeAssets, dormantAssets }.
+        // Wire format changed from DbAsset[] to { activeAssets: DbAsset[], dormantAssets: DbAsset[] }.
+        // Fall back to empty arrays if the server returns the old flat-array shape (graceful degradation).
+        const rawResponse = await kernelCall('setup.listAssetsForUser', {}).catch(() => null);
+        let dbAssets = [];
+        if (rawResponse !== null) {
+            if (Array.isArray(rawResponse)) {
+                // Pre-S4 server — treat entire response as active assets with no dormant list.
+                dbAssets = rawResponse;
+                dormantDbAssetRows = [];
+                hasAnyReceipt = undefined; // unknown on legacy servers
+            }
+            else {
+                dbAssets = rawResponse.activeAssets ?? [];
+                dormantDbAssetRows = rawResponse.dormantAssets ?? [];
+                // WP-379 S5b: extract hasAnyReceipt when provided by the server.
+                // undefined means pre-S5b server — we treat as unknown (no receipts assumed).
+                hasAnyReceipt = rawResponse.hasAnyReceipt;
+            }
+        }
+        if (dbAssets.length > 0) {
+            dbAssetRows = dbAssets;
+            // Map DB assets to CanonicalSkill/CanonicalRule shapes
+            for (const asset of dbAssets) {
+                if (asset.disabledByOwner)
+                    continue;
+                if (asset.assetKind === 'skill') {
+                    dbSkills.push({
+                        name: asset.name,
+                        description: asset.description,
+                        triggers: asset.triggers ?? [],
+                        body: asset.body,
+                        sourcePath: `db:${asset.entryId}`,
+                    });
+                }
+                else if (asset.assetKind === 'rule' || asset.assetKind === 'hook') {
+                    dbRules.push({
+                        name: asset.name,
+                        description: asset.description,
+                        autoApply: false,
+                        body: asset.body,
+                        sourcePath: `db:${asset.entryId}`,
+                    });
+                }
+            }
+            usedDbSource = true;
+            log(`Setup assets: ${dbSkills.length} skills, ${dbRules.length} rules/hooks from DB (WP-345 DB-first path)`);
+            if (dormantDbAssetRows.length > 0) {
+                log(`Setup assets: ${dormantDbAssetRows.length} dormant (gate-filtered) asset(s) will be marked on disk`);
+            }
+        }
+    }
+    catch {
+        // DB source unavailable — silently fall through to FS path
+    }
+    const allSkills = usedDbSource ? dbSkills : readCanonicalSkills(pbDir);
+    const manualRules = usedDbSource ? dbRules : readCanonicalRules(pbDir);
+    if (!usedDbSource) {
+        log('Setup assets: reading from filesystem (DB source unavailable or empty)');
+    }
+    // 5a-pre. E4: Resolve semantic refs in DB assets (WP-345, DEC-A, DEC-C, DEC-K)
+    // For each asset with semanticRefs[], resolve them via the Convex resolver and
+    // replace {{ref:key}} placeholders in the body. Runs in apply mode only (not preview).
+    // NG11: PostHog events fire from CLI side only (never inside Convex mutations).
+    if (usedDbSource && applyMode) {
+        const projectableDbAssets = dbAssetRows.filter((a) => !a.disabledByOwner && (a.assetKind === 'skill' || a.assetKind === 'rule' || a.assetKind === 'hook'));
+        const assetsWithRefs = projectableDbAssets.filter((a) => a.semanticRefs && a.semanticRefs.length > 0);
+        if (assetsWithRefs.length > 0) {
+            log(`Resolving semantic refs for ${assetsWithRefs.length} asset(s)...`);
+            // Collect unique ref keys across all assets
+            const allRefKeys = [...new Set(assetsWithRefs.flatMap((a) => a.semanticRefs))];
+            // Resolve all refs in a single batch call. Shape: SetupRefResolution[]
+            // (DEC-767 / WP-354 Build-Order #6 — kind + status discriminator).
+            let resolvedRefs = [];
+            try {
+                resolvedRefs = await kernelCall('setup.resolveSemanticRefs', { semanticRefs: allRefKeys });
+            }
+            catch (err) {
+                trackEvent('setup.refs.resolve_failed', { error: err instanceof Error ? err.message : String(err) });
+                logErr(`Warning: could not resolve semantic refs — ${err instanceof Error ? err.message : String(err)}`);
+            }
+            // Build resolved map: canonicalKey → display name. Only required refs
+            // count as unresolved warnings; seed/unknown refs are not gates.
+            const resolvedMap = new Map();
+            let unresolvedCount = 0;
+            for (const result of resolvedRefs) {
+                if (result.status === 'resolved' && result.localEntryId) {
+                    resolvedMap.set(result.ref, result.localEntryId);
+                    trackEvent('skill.ref.resolved', { ref: result.ref, kind: result.kind });
+                }
+                else if (result.status === 'unsupported-future') {
+                    // seed: refs are explicitly future scope per WP-354 Build-Order #6 — not a warning.
+                    trackEvent('skill.ref.future', { ref: result.ref, kind: result.kind });
+                }
+                else if (result.required) {
+                    unresolvedCount++;
+                    trackEvent('skill.ref.unresolved', { ref: result.ref, kind: result.kind, status: result.status });
+                }
+            }
+            if (unresolvedCount > 0) {
+                logErr(`Warning: ${unresolvedCount} required semantic ref(s) could not be resolved.`);
+            }
+            // Projection must preserve ref tokens as portable machine-readable refs.
+            // resolvedMap is only used for validation/telemetry here; generated setup
+            // artifacts keep {{ref:domain:...}} / {{ref:entry:...}} intact.
+        }
+        // Compute projection hash for each projected DB asset (DEC-K).
+        // The stored hash is sha256 of the normalized resolved asset body; DB persistence
+        // is deferred until the write loop confirms a matching file was emitted.
+        // Strip existing hash trailer and timestamp lines, normalize to LF, then hash.
+        const HASH_TRAILER_REGEX = /^<!--\s*pb-hash:.*-->\s*$/gm;
+        const TIMESTAMP_REGEX = /^<!--\s*pb-generated-at:.*-->\s*$/gm;
+        for (const rawAsset of projectableDbAssets) {
+            const resolvedAsset = [...dbSkills, ...dbRules].find((a) => a.sourcePath === `db:${rawAsset.entryId}`);
+            if (!resolvedAsset)
+                continue;
+            try {
+                // Build the projected body (what will be written to disk)
+                const projectedBody = resolvedAsset.body;
+                // Normalize: strip existing hash/timestamp trailers, convert to LF
+                const normalized = projectedBody
+                    .replace(HASH_TRAILER_REGEX, '')
+                    .replace(TIMESTAMP_REGEX, '')
+                    .replace(/\r\n/g, '\n')
+                    .replace(/\r/g, '\n')
+                    .trimEnd();
+                // Compute sha256 hash
+                const hash = createHash('sha256').update(normalized, 'utf8').digest('hex');
+                const hashTrailer = `<!-- pb-hash: sha256:${hash} -->`;
+                // Append hash trailer to the projected body
+                resolvedAsset.body = `${normalized}\n${hashTrailer}`;
+                dbProjectionHashes.set(rawAsset.entryId, {
+                    hash: `sha256:${hash}`,
+                    assetKind: rawAsset.assetKind,
+                });
+                // Drift detection: compare against last known hash
+                if (rawAsset.lastProjectedHash && rawAsset.lastProjectedHash !== `sha256:${hash}`) {
+                    trackEvent('skill.drift.detected', {
+                        entryId: rawAsset.entryId,
+                        assetKind: rawAsset.assetKind,
+                    });
+                    log(`Drift detected for asset ${rawAsset.entryId} — projecting updated version.`);
+                }
+                trackEvent('skill.projection.succeeded', {
+                    entryId: rawAsset.entryId,
+                    assetKind: rawAsset.assetKind,
+                });
+            }
+            catch (err) {
+                trackEvent('skill.projection.failed', {
+                    entryId: rawAsset.entryId,
+                    assetKind: rawAsset.assetKind,
+                });
+                logErr(`Warning: projection failed for ${rawAsset.entryId} — ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    // 5a. Optionally fetch and merge Chain-derived rules (--generate flag)
+    let chainRulesStats = null;
+    let chainGaps = [];
+    let allRules = manualRules;
+    if (generate) {
+        log('Generating Chain-derived rules...');
+        const chainResult = await generateChainRules(kernelCall, manualRules);
+        if (chainResult.sentinel) {
+            // MCP unavailable — inject sentinel rule and warn
+            allRules = [...manualRules, chainResult.sentinel];
+            logErr('Warning: Chain MCP unavailable — generated rules are disabled. Sentinel rule injected.');
+        }
+        else {
+            // Merge generated rules after manual rules (manual takes precedence on dedup)
+            allRules = [...manualRules, ...chainResult.rules];
+            chainRulesStats = chainResult.stats;
+            chainGaps = chainResult.gaps;
+            const { generatedRules, suppressedByManual, suppressedByZeroEntries } = chainResult.stats;
+            log(`Chain-derived rules: ${generatedRules} generated, ${suppressedByManual} suppressed by manual, ${suppressedByZeroEntries} gaps`);
+            if (chainGaps.length > 0) {
+                log(`Gaps (no matching governance entries): ${chainGaps.join(', ')}`);
+            }
+            // Diff: compare current state against previous run
+            const previousState = loadPreviousState(pbDir);
+            const currentState = buildCurrentState(chainResult.rules, chainResult.classified);
+            saveHandshakeState(pbDir, chainResult.rules, chainResult.classified);
+            const diff = diffHandshakeState(currentState, previousState);
+            const diffText = formatDiff(diff);
+            log(diffText);
+        }
+    }
+    // 5b. Read personal layer (WP-310 E2) — machine-local rules/skills from .productbrain/.local/
+    // Returns [] when the directory is absent. All returned entries have persist: 'local'.
+    const personalRules = readPersonalLayer(pbDir);
+    if (personalRules.length > 0) {
+        // Name collision detection — warn when a personal rule overrides a team rule
+        const teamRuleNames = new Set(allRules.map((r) => r.name));
+        for (const pr of personalRules) {
+            if (teamRuleNames.has(pr.name)) {
+                logErr(`Personal rule "${pr.name}" overrides team rule (local takes precedence).`);
+            }
+        }
+        // Merge: team rules first, personal rules appended (personal takes precedence via name collision above)
+        allRules = [...allRules, ...personalRules];
+    }
+    const personalSkills = readPersonalSkillsLayer(pbDir);
+    if (personalSkills.length > 0) {
+        const teamSkillNames = new Set(allSkills.map((s) => s.name));
+        for (const ps of personalSkills) {
+            if (teamSkillNames.has(ps.name)) {
+                logErr(`Personal skill "${ps.name}" overrides team skill (local takes precedence).`);
+            }
+        }
+        allSkills.push(...personalSkills);
+    }
+    // 5c. Apply manifest-based adoption filter (WP-310 E1)
+    // readManifest returns null when manifest.yaml is absent → filterByAdoptionState is a no-op.
+    const manifest = readManifest(pbDir);
+    // 5d. Load method registry (WP-310 E4) — only when manifest is present.
+    let registrySource;
+    let registryStale;
+    if (manifest) {
+        const registryResult = await loadMethodRegistry(manifest.method_source, kernelCall).catch(() => null);
+        if (registryResult) {
+            registrySource = registryResult.source;
+            registryStale = registryResult.stale;
+        }
+    }
+    const adoptionFilteredSkills = filterByAdoptionState(allSkills, manifest);
+    const adoptionFilteredRules = filterByAdoptionState(allRules, manifest);
+    // Compute adoption counts for report (only meaningful when manifest is present)
+    const adoptedRulesCount = manifest ? adoptionFilteredRules.length : undefined;
+    const rejectedRulesCount = manifest ? allRules.length - adoptionFilteredRules.length : undefined;
+    // Apply level filtering with stage-gating (after adoption filter, before target filtering in write loop)
+    // Stage caps the effective level: blank→beginner, seed→intermediate, grounded+→expert.
+    // If stage caps below the requested level, log it so the user knows why items were dropped.
+    const profileStage = workspaceProfile?.stage;
+    const levelFilteredSkills = filterByLevel(adoptionFilteredSkills, level, profileStage);
+    const levelFilteredRules = filterByLevel(adoptionFilteredRules, level, profileStage);
+    // Log when stage gating changes the effective level
+    if (profileStage) {
+        const stageCap = STAGE_TO_MAX_LEVEL[profileStage];
+        if (stageCap) {
+            const requestedIdx = level ? LEVEL_ORDER.indexOf(level) : LEVEL_ORDER.length - 1;
+            const capIdx = LEVEL_ORDER.indexOf(stageCap);
+            if (capIdx < requestedIdx) {
+                log(`Stage "${profileStage}" caps level from ${level || 'expert'} to ${stageCap}`);
+            }
+        }
+    }
+    // Apply when-condition filtering (stage-aware, workspace profile + repo context)
+    const canonicalSkills = levelFilteredSkills.filter((skill) => {
+        const result = evaluateConditions(skill.conditions ?? {}, workspaceProfile, repo);
+        if (dryRun && !result.included) {
+            log(`  EXCLUDED skill ${skill.name}: ${result.reasons.join(', ')}`);
+        }
+        return result.included;
+    });
+    const canonicalRules = levelFilteredRules.filter((rule) => {
+        const result = evaluateConditions(rule.conditions ?? {}, workspaceProfile, repo);
+        if (dryRun && !result.included) {
+            log(`  EXCLUDED rule ${rule.name}: ${result.reasons.join(', ')}`);
+        }
+        return result.included;
+    });
+    if (dryRun && canonicalSkills.length > 0) {
+        log(`  INCLUDED skills: ${canonicalSkills.map((s) => s.name).join(', ')}`);
+    }
+    if (dryRun && canonicalRules.length > 0) {
+        log(`  INCLUDED rules: ${canonicalRules.map((r) => r.name).join(', ')}`);
+    }
+    if (canonicalSkills.length > 0 || canonicalRules.length > 0) {
+        const levelSuffix = level ? ` (level: ${level})` : '';
+        const stageSuffix = profileStage ? `, stage: ${profileStage}` : '';
+        const stackSuffix = repo.detectedStack.length > 0 ? `, stack: [${repo.detectedStack.join(', ')}]` : '';
+        const totalSkills = allSkills.length;
+        const totalRules = allRules.length;
+        log(`Portable knowledge: ${canonicalSkills.length}/${totalSkills} skills, ${canonicalRules.length}/${totalRules} rules${levelSuffix}${stageSuffix}${stackSuffix}`);
+    }
+    // 6. Generate file contents
+    // Build workspace context for AGENTS.md enrichment (stage, focus, governance, entry count)
+    const agentsWorkspaceContext = workspaceProfile
+        ? {
+            stage: workspaceProfile.stage,
+            focus: orientView?.strategicContext?.currentBet ?? undefined,
+            governanceMode: workspaceProfile.governanceMode,
+            totalEntries: workspaceProfile.totalEntries,
+        }
+        : undefined;
+    // Collect codex-targeted skills for AGENTS.md skill directory
+    // Exclude persist: 'local' rules — committed adapter files must never include local-only rules.
+    const agentsCodexSkills = canonicalSkills
+        .filter((s) => shouldEmitToTarget(s, 'codex'))
+        .map((s) => ({
+        name: s.name,
+        description: s.description,
+        triggers: s.triggers,
+    }));
+    // Collect copilot-targeted skills for copilot-instructions.md skill summaries
+    const copilotSkills = canonicalSkills
+        .filter((s) => shouldEmitToTarget(s, 'copilot'))
+        .map((s) => ({
+        name: s.name,
+        description: s.description,
+        triggers: s.triggers,
+    }));
+    // Collect copilot-targeted rules for copilot-instructions.md rule summaries
+    const copilotRules = canonicalRules
+        .filter((r) => shouldEmitToTarget(r, 'copilot'))
+        .map((r) => ({
+        name: r.name,
+        description: r.description,
+    }));
+    const copilotProfile = resolveSurfaceProfile('copilot');
+    const copilotOptions = {
+        profile: copilotProfile,
+        workspaceContext: agentsWorkspaceContext,
+        skills: copilotSkills.length > 0 ? copilotSkills : undefined,
+        rules: copilotRules.length > 0 ? copilotRules : undefined,
+    };
+    const contextContent = orientView ? generateContextMd(orientView, repo, timestamp, workspaceProfile?.stage) : null;
+    const briefingContent = generateBriefingMd(matchedEntries, repo, uniqueQueries, timestamp);
+    const agentsContent = generateAgentsMd(timestamp, {
+        workspaceContext: agentsWorkspaceContext,
+        skills: agentsCodexSkills.length > 0 ? agentsCodexSkills : undefined,
+    });
+    const claudeContent = generateClaudeMd(timestamp);
+    const cursorContent = generateCursorMdc(timestamp);
+    const copilotContent = generateCopilotMd(timestamp, copilotOptions);
+    const boundaryEnforcementMode = getBoundaryEnforcementMode(manifest);
+    const boundaryManifestContent = boundaryEnforcementMode === 'advisory'
+        ? null
+        : generateBoundaryManifest(pbDir);
+    // 7. Write files
+    const filesWritten = [];
+    const filesSkipped = [];
+    const previewPlan = [];
+    // Surface filtering: skip adapter writes for targets not in the allowed set
+    const allowedTargets = options.surfaces && options.surfaces.length > 0
+        ? new Set(options.surfaces)
+        : null; // null = write all
+    const writes = [
+        ...(contextContent ? [{ path: join(cwd, '.productbrain', 'context.md'), relative: '.productbrain/context.md', content: contextContent, dirs: join(cwd, '.productbrain'), isAdapter: false }] : []),
+        { path: join(cwd, '.productbrain', 'briefing.md'), relative: '.productbrain/briefing.md', content: briefingContent, isAdapter: false },
+        { path: join(cwd, 'AGENTS.md'), relative: 'AGENTS.md', content: agentsContent, isAdapter: true, target: 'codex' },
+        { path: join(cwd, 'CLAUDE.md'), relative: 'CLAUDE.md', content: claudeContent, isAdapter: true, target: 'claude' },
+        { path: join(cwd, '.cursor', 'rules', 'chain.mdc'), relative: '.cursor/rules/chain.mdc', content: cursorContent, dirs: join(cwd, '.cursor', 'rules'), isAdapter: true, target: 'cursor' },
+        { path: join(cwd, '.github', 'copilot-instructions.md'), relative: '.github/copilot-instructions.md', content: copilotContent, dirs: join(cwd, '.github'), isAdapter: true, target: 'copilot' },
+        ...(boundaryManifestContent ? [{
+                path: join(cwd, '.productbrain', 'generated', 'boundaries.json'),
+                relative: '.productbrain/generated/boundaries.json',
+                content: boundaryManifestContent,
+                dirs: join(cwd, '.productbrain', 'generated'),
+                isAdapter: false,
+            }] : []),
+    ];
+    // Add Cursor skill copies (filtered by target)
+    const cursorProfile = resolveSurfaceProfile('cursor');
+    for (const skill of canonicalSkills) {
+        if (!shouldEmitToTarget(skill, 'cursor'))
+            continue;
+        const dbAssetEntryId = skill.sourcePath.startsWith('db:') ? skill.sourcePath.slice(3) : undefined;
+        const skillDir = join(cwd, '.cursor', 'skills', skill.name);
+        writes.push({
+            path: join(skillDir, 'SKILL.md'),
+            relative: `.cursor/skills/${skill.name}/SKILL.md`,
+            content: generateCursorSkill(skill, cursorProfile),
+            dirs: skillDir,
+            isAdapter: true,
+            target: 'cursor',
+            dbAssetEntryId,
+        });
+    }
+    // Add Codex skill copies (projected markdown + index)
+    const codexProfile = resolveSurfaceProfile('codex');
+    const codexSkills = canonicalSkills.filter((s) => shouldEmitToTarget(s, 'codex'));
+    for (const skill of codexSkills) {
+        const dbAssetEntryId = skill.sourcePath.startsWith('db:') ? skill.sourcePath.slice(3) : undefined;
+        writes.push({
+            path: join(cwd, '.codex', 'skills', `${skill.name}.md`),
+            relative: `.codex/skills/${skill.name}.md`,
+            content: generateCodexSkill(skill, codexProfile),
+            dirs: join(cwd, '.codex', 'skills'),
+            isAdapter: true,
+            target: 'codex',
+            dbAssetEntryId,
+        });
+    }
+    writes.push({
+        path: join(cwd, '.codex', 'skills', 'README.md'),
+        relative: '.codex/skills/README.md',
+        content: generateCodexSkillIndex(codexSkills),
+        dirs: join(cwd, '.codex', 'skills'),
+        isAdapter: true,
+        target: 'codex',
+    });
+    // Validate Codex-projected skills for dead references
+    const codexWarnings = validateCodexSkills(codexSkills);
+    // Add Cursor rule copies (filtered by target)
+    for (const rule of canonicalRules) {
+        if (!shouldEmitToTarget(rule, 'cursor'))
+            continue;
+        const dbAssetEntryId = rule.sourcePath.startsWith('db:') ? rule.sourcePath.slice(3) : undefined;
+        writes.push({
+            path: join(cwd, '.cursor', 'rules', `${rule.name}.mdc`),
+            relative: `.cursor/rules/${rule.name}.mdc`,
+            content: generateCursorRule(rule, cursorProfile),
+            dirs: join(cwd, '.cursor', 'rules'),
+            isAdapter: true,
+            target: 'cursor',
+            dbAssetEntryId,
+        });
+    }
+    // Add Claude Code rule copies (filtered by target)
+    const claudeProfile = resolveSurfaceProfile('claude');
+    for (const rule of canonicalRules) {
+        if (!shouldEmitToTarget(rule, 'claude'))
+            continue;
+        const dbAssetEntryId = rule.sourcePath.startsWith('db:') ? rule.sourcePath.slice(3) : undefined;
+        writes.push({
+            path: join(cwd, '.claude', 'rules', `${rule.name}.md`),
+            relative: `.claude/rules/${rule.name}.md`,
+            content: generateClaudeRule(rule, claudeProfile),
+            dirs: join(cwd, '.claude', 'rules'),
+            isAdapter: true,
+            target: 'claude',
+            dbAssetEntryId,
+        });
+    }
+    // Add Claude Code skill router (filtered by target)
+    const claudeSkills = canonicalSkills.filter((s) => shouldEmitToTarget(s, 'claude'));
+    const skillRouterContent = generateClaudeSkillRouter(claudeSkills, claudeProfile);
+    if (skillRouterContent) {
+        writes.push({
+            path: join(cwd, '.claude', 'rules', 'skill-router.md'),
+            relative: '.claude/rules/skill-router.md',
+            content: skillRouterContent,
+            dirs: join(cwd, '.claude', 'rules'),
+            isAdapter: true,
+            target: 'claude',
+        });
+    }
+    // 7a. WP-379 S5b: Resolve projection collisions before writing.
+    // In apply mode, enumerate target dirs and unlink any auto-generated files
+    // whose normalized name no longer matches any active asset from the server.
+    // This prevents case-variant orphans from accumulating across handshakes.
+    // Runs only when we have a DB asset list (usedDbSource) — without a DB source,
+    // we can't determine which files are canonical vs. orphan.
+    const collisionTensToFire = [];
+    if (applyMode && usedDbSource) {
+        const activeAssetNames = dbAssetRows
+            .filter((a) => !a.disabledByOwner)
+            .map((a) => a.name);
+        const { collisionTens } = resolveProjectionCollision(cwd, activeAssetNames, log, logErr);
+        collisionTensToFire.push(...collisionTens);
+    }
+    const forkedPaths = [];
+    const projectedHashUpdates = new Map();
+    const recordProjectedHash = (entryId) => {
+        if (!applyMode || !entryId)
+            return;
+        const projection = dbProjectionHashes.get(entryId);
+        if (projection)
+            projectedHashUpdates.set(entryId, projection.hash);
+    };
+    for (const w of writes) {
+        // Surface filtering: skip adapter writes for targets not in the allowed set
+        if (allowedTargets && w.target && !allowedTargets.has(w.target)) {
+            filesSkipped.push({ path: w.relative, reason: `filtered (surface: ${w.target})` });
+            if (preview)
+                previewPlan.push({ path: w.relative, status: 'filtered' });
+            continue;
+        }
+        if (w.isAdapter && !shouldWriteAdapter(w.path, force)) {
+            filesSkipped.push({ path: w.relative, reason: 'exists without auto-generated marker (use --force to overwrite)' });
+            if (preview) {
+                previewPlan.push({ path: w.relative, status: 'forked' });
+            }
+            else {
+                forkedPaths.push(w.relative);
+            }
+            continue;
+        }
+        if (preview || dryRun) {
+            // In preview/dry-run mode: check content to distinguish new/update/unchanged
+            if (existsSync(w.path)) {
+                const current = readFileSync(w.path, 'utf8');
+                const nextNormalized = normalizeHandshakeContentForComparison(w.content);
+                const currentNormalized = normalizeHandshakeContentForComparison(current);
+                if (nextNormalized === currentNormalized) {
+                    filesSkipped.push({ path: w.relative, reason: 'unchanged' });
+                    if (preview)
+                        previewPlan.push({ path: w.relative, status: 'unchanged' });
+                }
+                else {
+                    filesWritten.push(w.relative + (dryRun ? ' (dry run)' : ''));
+                    if (preview)
+                        previewPlan.push({ path: w.relative, status: 'would-update' });
+                }
+            }
+            else {
+                filesWritten.push(w.relative + (dryRun ? ' (dry run)' : ''));
+                if (preview)
+                    previewPlan.push({ path: w.relative, status: 'would-write' });
+            }
+            continue;
+        }
+        if (w.dirs)
+            mkdirSync(w.dirs, { recursive: true });
+        if (existsSync(w.path)) {
+            const current = readFileSync(w.path, 'utf8');
+            const nextNormalized = normalizeHandshakeContentForComparison(w.content);
+            const currentNormalized = normalizeHandshakeContentForComparison(current);
+            if (nextNormalized === currentNormalized) {
+                filesSkipped.push({ path: w.relative, reason: 'unchanged' });
+                recordProjectedHash(w.dbAssetEntryId);
+                continue;
+            }
+        }
+        writeFileSync(w.path, w.content);
+        filesWritten.push(w.relative);
+        recordProjectedHash(w.dbAssetEntryId);
+    }
+    if (projectedHashUpdates.size > 0) {
+        const updates = [...projectedHashUpdates];
+        const results = await Promise.allSettled(updates.map(([entryId, hash]) => kernelCall('setup.updateLastProjectedHash', { entryId, hash })));
+        results.forEach((result, index) => {
+            if (result.status === 'rejected') {
+                const [entryId] = updates[index];
+                trackEvent('skill.projection.failed', {
+                    entryId,
+                    reason: result.reason instanceof Error ? result.reason.message : String(result.reason),
+                });
+            }
+        });
+    }
+    // 8a. Dormant marker writes (WP-379 S4) — apply mode only.
+    // For each dormant asset (gate-filtered by the server), locate any previously-projected
+    // on-disk files and append the DORMANT_MARKER trailer. Files are NOT deleted.
+    //
+    // Drift TEN exclusion: dormant-marked files have the auto-gen MARKER, so
+    // shouldWriteAdapter() returns true for them. However, because the asset is dormant,
+    // it is NOT in the `writes` array — it was never queued for a fresh write. Therefore,
+    // dormant files will never appear in forkedPaths (forkedPaths only catches files that
+    // ARE in the writes array but fail shouldWriteAdapter). The dormant marker write is a
+    // separate, independent pass that runs BEFORE the drift TEN check — intentionally
+    // after the main write loop to avoid interfering with active asset writes.
+    //
+    // Fail-open: if a dormant marker write fails, log and continue. Never crash the handshake.
+    const dormantMarkedPaths = [];
+    if (applyMode && dormantDbAssetRows.length > 0) {
+        for (const dormantAsset of dormantDbAssetRows) {
+            const candidatePaths = deriveDormantFilePaths(dormantAsset, cwd);
+            for (const filePath of candidatePaths) {
+                try {
+                    const markerResult = writeDormantMarkerToFile(filePath);
+                    if (markerResult === 'written') {
+                        dormantMarkedPaths.push(filePath);
+                        log(`Dormant marker written: ${filePath}`);
+                    }
+                    // 'already-dormant' and 'skipped' are silent no-ops — idempotent.
+                }
+                catch (err) {
+                    // Fail-open: dormant marker write is advisory. Log, never throw.
+                    logErr(`Warning: could not write dormant marker to ${filePath} — ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+    }
+    // 8. Drift logging — if apply mode encountered forked adapters and a session is active, log a draft TEN.
+    // Dormant-marked files are NOT forked — they were intentionally deactivated and have the auto-gen MARKER.
+    // They will never appear in forkedPaths because they are excluded from the `writes` array entirely.
+    //
+    // WP-379 S5b — First-run UX rule:
+    // When `hasAnyReceipt` is false OR undefined (unknown / pre-S5b server), drift TENs are suppressed.
+    // Rationale: on the first handshake, users may have pre-existing non-marked files from manual
+    // setup; we must not flood them with TENs before they've even had one successful materialization.
+    // A TEN fires only after setup_receipt.count >= 1 for this workspace.
+    //
+    // Conservative unknown-treatment: if the server does not provide hasAnyReceipt (old server),
+    // we treat it as "no receipt exists" and suppress the TEN. The day-1 experience is more important
+    // than catching every early drift case; the TEN will fire on the next run once the server is updated.
+    const isFirstRun = hasAnyReceipt !== true; // true when no receipts or unknown
+    if (forkedPaths.length > 0) {
+        if (isFirstRun) {
+            log(`Info: ${forkedPaths.length} adapter(s) skipped (user files without auto-gen marker). ` +
+                'Drift TEN suppressed — first run (no setup receipt yet). Files: ' +
+                forkedPaths.join(', '));
+        }
+        else {
+            const session = readSession();
+            if (session) {
+                const names = forkedPaths.join(', ');
+                kernelCallWithSession('chain.createEntry', {
+                    collectionSlug: 'tensions',
+                    name: `TEN: handshake drift — ${forkedPaths.length} adapter(s) forked, sync blocked`,
+                    status: 'draft',
+                    data: {
+                        description: `pb handshake --apply encountered forked adapters that blocked sync. Files: ${names}. Use --force to overwrite or resolve drift manually.`,
+                    },
+                    sessionId: session.sessionId,
+                    createdBy: `agent:${session.sessionId}`,
+                }).catch(() => { });
+            }
+        }
+    }
+    // 8. Case-collision TENs (WP-379 S5b) — fire after the first-run gate.
+    // These are distinct from drift TENs: they record ambiguous filename collisions
+    // where the "newest mtime wins" heuristic was applied. They fire regardless of
+    // first-run status (collision is a data quality issue, not a drift issue).
+    if (collisionTensToFire.length > 0) {
+        const session = readSession();
+        if (session) {
+            for (const tenDescription of collisionTensToFire) {
+                kernelCallWithSession('chain.createEntry', {
+                    collectionSlug: 'tensions',
+                    name: `TEN: handshake case-collision — ambiguous filename resolved by mtime`,
+                    status: 'draft',
+                    data: { description: tenDescription },
+                    sessionId: session.sessionId,
+                    createdBy: `agent:${session.sessionId}`,
+                }).catch(() => { });
+            }
+        }
+    }
+    // 8b. Setup receipt — record which assets were materialized (apply mode only)
+    // Fail-open: receipt write is advisory, never blocks the handshake.
+    if (applyMode) {
+        const session = readSession();
+        const caller = session ? kernelCallWithSession : kernelCall;
+        try {
+            const receiptResult = await caller('setup.materializeSetup', {});
+            if (receiptResult?.assetCount > 0) {
+                log(`Setup receipt: ${receiptResult.assetCount} asset(s) recorded.`);
+            }
+        }
+        catch (err) {
+            trackEvent('setup.receipt.write_failed', { error: err instanceof Error ? err.message : String(err) });
+            logErr(`Warning: could not write setup receipt — ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // 9. Report
+    const report = {
+        filesWritten,
+        filesSkipped,
+        matchedEntries,
+        searchQueries: uniqueQueries,
+        repo,
+        codexWarnings: codexWarnings.length > 0 ? codexWarnings : undefined,
+        chainRulesStats: chainRulesStats ?? undefined,
+        chainGaps: chainGaps.length > 0 ? chainGaps : undefined,
+        adoptedCount: adoptedRulesCount,
+        rejectedCount: rejectedRulesCount,
+        personalRuleCount: personalRules.length > 0 ? personalRules.length : undefined,
+        personalSkillCount: personalSkills.length > 0 ? personalSkills.length : undefined,
+        registrySource,
+        registryStale,
+        preview: preview ? true : undefined,
+        previewPlan: preview && previewPlan.length > 0 ? previewPlan : undefined,
+        driftConflicts: forkedPaths.length > 0 ? forkedPaths : undefined,
+    };
+    if (!quiet) {
+        process.stdout.write('\n');
+        process.stdout.write(formatHandshakeReport(report) + '\n');
+    }
+}
+//# sourceMappingURL=handshake.js.map