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

package/dist/commands/handshake.js

@@ -0,0 +1,929 @@
+/**
+ * pb handshake — generate context files for AI developer tools.
+ * The fourth delivery surface: context export (GLO-63, DEC-161).
+ */
+import { mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync, copyFileSync } from 'fs';
+import { join, dirname, resolve } 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';
+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;
+}
+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 = [];
+    const dbProjectionHashes = new Map();
+    try {
+        const dbAssets = await kernelCall('setup.listAssetsForUser', {}).catch(() => null);
+        if (dbAssets && 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)`);
+        }
+    }
+    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',
+        });
+    }
+    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),
+                });
+            }
+        });
+    }
+    // 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(() => { });
+        }
+    }
+    // 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