@productbrain/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/commands/handshake.js

@@ -2,18 +2,27 @@
  * pb handshake — generate context files for AI developer tools.
  * The fourth delivery surface: context export (GLO-63, DEC-161).
  */
-import { mkdirSync, writeFileSync, existsSync, readFileSync } from 'fs';
-import { join } from 'path';
+import { mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync, copyFileSync } from 'fs';
+import { join, dirname, resolve } from 'path';
 import { homedir } from 'os';
-import { createInterface } from 'readline';
+import { fileURLToPath } from 'url';
 import { getConfigOrGuide } from '../lib/config.js';
-import { mcpCall } from '../lib/client.js';
-import { detectRepo } from '../lib/repo-detect.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, generateClaudeMd, generateCursorMdc, generateCopilotMd } from '../generators/adapters.js';
-import { readCanonicalSkills, readCanonicalRules, generateCursorSkill, generateCursorRule, generateClaudeRule, generateClaudeSkillRouter, shouldEmitToTarget, filterByLevel, } from '../generators/portable-knowledge.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 { loadMethodRegistry } from '../lib/method-registry.js';
+import { CLIError, ErrorCode } from '../lib/errors.js';
 const LEVELS = {
     guide: {
         label: 'Guide me',
@@ -45,9 +54,6 @@ 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:*)';
-const INIT_SESSION_START_CMD = 'pb session start 2>/dev/null || true';
-const INIT_SESSION_CLOSE_CMD = 'pb session close 2>/dev/null || true';
-const INIT_PRECOMPACT_CMD = 'pb session id > /dev/null 2>&1 && echo \'{"systemMessage": "pb session active — capture decisions/tensions before compacting: pb capture \\"DEC: ...\\""}\'  || true';
 function readSettings(filePath) {
     if (!existsSync(filePath))
         return {};
@@ -59,9 +65,6 @@ function readSettings(filePath) {
         return {};
     }
 }
-function hasCommand(groups, cmd) {
-    return (groups ?? []).some((g) => g.hooks?.some((h) => h.command === cmd));
-}
 // Team write: hooks + Bash(pb:*) → .claude/settings.json (safe to commit)
 function writeTeamSettings(cwd, dryRun) {
     const claudeDir = join(cwd, '.claude');
@@ -77,26 +80,10 @@ function writeTeamSettings(cwd, dryRun) {
     }
     settings.permissions = permissions;
     const hooks = (settings.hooks ?? {});
-    if (!hasCommand(hooks.SessionStart, INIT_SESSION_START_CMD)) {
-        hooks.SessionStart = [
-            ...(hooks.SessionStart ?? []),
-            { hooks: [{ type: 'command', command: INIT_SESSION_START_CMD, statusMessage: 'Opening pb session...' }] },
-        ];
-        added.push('SessionStart → pb session start');
-    }
-    if (!hasCommand(hooks.Stop, INIT_SESSION_CLOSE_CMD)) {
-        hooks.Stop = [
-            ...(hooks.Stop ?? []),
-            { hooks: [{ type: 'command', command: INIT_SESSION_CLOSE_CMD, statusMessage: 'Closing pb session...' }] },
-        ];
-        added.push('Stop → pb session close');
-    }
-    if (!hasCommand(hooks.PreCompact, INIT_PRECOMPACT_CMD)) {
-        hooks.PreCompact = [
-            ...(hooks.PreCompact ?? []),
-            { hooks: [{ type: 'command', command: INIT_PRECOMPACT_CMD }] },
-        ];
-        added.push('PreCompact → decision capture reminder');
+    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) {
@@ -133,31 +120,26 @@ function writePersonalSettings(levelKey, dryRun) {
     return added;
 }
 async function promptLevel() {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    console.log('\nHow much should Claude explain before acting?\n');
-    LEVEL_KEYS.forEach((key, i) => {
-        const l = LEVELS[key];
-        console.log(`  ${i + 1}. ${l.label.padEnd(12)} — ${l.description}`);
-    });
-    console.log('');
-    return new Promise((resolve) => {
-        rl.question('> ', (answer) => {
-            rl.close();
-            const n = parseInt(answer.trim(), 10);
-            if (!(n >= 1 && n <= LEVEL_KEYS.length)) {
-                console.log('  (Invalid choice — defaulting to "Just work")');
-            }
-            resolve(n >= 1 && n <= LEVEL_KEYS.length ? LEVEL_KEYS[n - 1] : 'work');
-        });
+    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)) {
-        console.error(`Unknown level "${options.level}". Valid: ${LEVEL_KEYS.join(', ')}`);
-        process.exit(1);
+        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
@@ -172,7 +154,7 @@ export async function runHandshakeInit(options = {}) {
             console.log(`    + ${item}`);
     }
     // Step 2: Personal config — wizard or --level flag
-    // Cast is safe: LEVEL_KEYS.includes() validated above; invalid level already called process.exit(1).
+    // 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);
@@ -194,6 +176,88 @@ export async function runHandshakeInit(options = {}) {
     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)
@@ -222,8 +286,12 @@ export async function runHandshake(options = {}) {
     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 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)
@@ -233,8 +301,11 @@ export async function runHandshake(options = {}) {
     // 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)) {
-        process.stderr.write(`Unknown level "${level}". Valid levels: ${VALID_HANDSHAKE_LEVELS.join(', ')}\n`);
-        process.exit(1);
+        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);
@@ -242,16 +313,30 @@ export async function runHandshake(options = {}) {
     if (repo.detectedStack.length > 0) {
         log(`Stack: ${repo.detectedStack.join(', ')}`);
     }
-    // 2. Fetch orient view
+    // 2. Fetch orient view + workspace readiness in parallel (budget max +200ms added latency)
     log('Fetching workspace context...');
     let orientView = null;
+    let workspaceProfile = null;
     try {
-        orientView = await mcpCall('chain.getOrientView', {});
+        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)
@@ -269,37 +354,200 @@ export async function runHandshake(options = {}) {
     let matchedEntries = [];
     if (uniqueQueries.length > 0) {
         log(`Searching Chain for: ${uniqueQueries.join(', ')}...`);
-        const searchResults = await Promise.all(uniqueQueries.map((q) => mcpCall('chain.searchEntries', { query: q }).catch(() => [])));
+        const searchResults = await Promise.all(uniqueQueries.map((q) => kernelCall('chain.searchEntries', { query: q }).catch(() => [])));
         matchedEntries = deduplicateEntries(searchResults.flat());
     }
     // 5. Read canonical skills & rules from .productbrain/
     const pbDir = join(cwd, '.productbrain');
     const allSkills = readCanonicalSkills(pbDir);
-    const allRules = readCanonicalRules(pbDir);
-    // Apply level filtering (after read, before target filtering in write loop)
-    const canonicalSkills = filterByLevel(allSkills, level);
-    const canonicalRules = filterByLevel(allRules, level);
+    const manualRules = readCanonicalRules(pbDir);
+    // 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})` : '';
-        log(`Portable knowledge: ${canonicalSkills.length} skill(s), ${canonicalRules.length} rule(s)${levelSuffix}`);
+        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
-    const contextContent = orientView ? generateContextMd(orientView, repo, timestamp) : null;
+    // 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);
+    const copilotContent = generateCopilotMd(timestamp, copilotOptions);
     // 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, 'CLAUDE.md'), relative: 'CLAUDE.md', content: claudeContent, isAdapter: true },
-        { path: join(cwd, '.cursor', 'rules', 'chain.mdc'), relative: '.cursor/rules/chain.mdc', content: cursorContent, dirs: join(cwd, '.cursor', 'rules'), isAdapter: true },
-        { path: join(cwd, '.github', 'copilot-instructions.md'), relative: '.github/copilot-instructions.md', content: copilotContent, dirs: join(cwd, '.github'), isAdapter: true },
+        { 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' },
     ];
     // Add Cursor skill copies (filtered by target)
+    const cursorProfile = resolveSurfaceProfile('cursor');
     for (const skill of canonicalSkills) {
         if (!shouldEmitToTarget(skill, 'cursor'))
             continue;
@@ -307,11 +555,35 @@ export async function runHandshake(options = {}) {
         writes.push({
             path: join(skillDir, 'SKILL.md'),
             relative: `.cursor/skills/${skill.name}/SKILL.md`,
-            content: generateCursorSkill(skill),
+            content: generateCursorSkill(skill, cursorProfile),
             dirs: skillDir,
             isAdapter: true,
+            target: 'cursor',
         });
     }
+    // Add Codex skill copies (projected markdown + index)
+    const codexProfile = resolveSurfaceProfile('codex');
+    const codexSkills = canonicalSkills.filter((s) => shouldEmitToTarget(s, 'codex'));
+    for (const skill of codexSkills) {
+        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',
+        });
+    }
+    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'))
@@ -319,26 +591,29 @@ export async function runHandshake(options = {}) {
         writes.push({
             path: join(cwd, '.cursor', 'rules', `${rule.name}.mdc`),
             relative: `.cursor/rules/${rule.name}.mdc`,
-            content: generateCursorRule(rule),
+            content: generateCursorRule(rule, cursorProfile),
             dirs: join(cwd, '.cursor', 'rules'),
             isAdapter: true,
+            target: 'cursor',
         });
     }
     // Add Claude Code rule copies (filtered by target)
+    const claudeProfile = resolveSurfaceProfile('claude');
     for (const rule of canonicalRules) {
         if (!shouldEmitToTarget(rule, 'claude'))
             continue;
         writes.push({
             path: join(cwd, '.claude', 'rules', `${rule.name}.md`),
             relative: `.claude/rules/${rule.name}.md`,
-            content: generateClaudeRule(rule),
+            content: generateClaudeRule(rule, claudeProfile),
             dirs: join(cwd, '.claude', 'rules'),
             isAdapter: true,
+            target: 'claude',
         });
     }
     // Add Claude Code skill router (filtered by target)
     const claudeSkills = canonicalSkills.filter((s) => shouldEmitToTarget(s, 'claude'));
-    const skillRouterContent = generateClaudeSkillRouter(claudeSkills);
+    const skillRouterContent = generateClaudeSkillRouter(claudeSkills, claudeProfile);
     if (skillRouterContent) {
         writes.push({
             path: join(cwd, '.claude', 'rules', 'skill-router.md'),
@@ -346,29 +621,102 @@ export async function runHandshake(options = {}) {
             content: skillRouterContent,
             dirs: join(cwd, '.claude', 'rules'),
             isAdapter: true,
+            target: 'claude',
         });
     }
+    const forkedPaths = [];
     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 (dryRun) {
-            filesWritten.push(w.relative + ' (dry run)');
+        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' });
+                continue;
+            }
+        }
         writeFileSync(w.path, w.content);
         filesWritten.push(w.relative);
     }
-    // 8. Report
+    // 8. Drift logging — if apply mode encountered forked adapters and a session is active, log a draft TEN
+    if (forkedPaths.length > 0) {
+        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(() => { });
+        }
+    }
+    // 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');