@productbrain/cli 0.1.0-beta.11282 → 0.1.0-beta.11295

package/dist/commands/handshake.js

@@ -1,1359 +0,0 @@
-/**
- * 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, realpathSync } from 'fs';
-import { join, dirname, resolve, basename, relative, sep } from 'path';
-import { homedir } from 'os';
-import { fileURLToPath } from 'url';
-import { execSync } from 'child_process';
-import { getConfigOrGuide } from '../lib/config.js';
-import { select as promptSelect, confirm as promptConfirm } from '../lib/prompts.js';
-import { HOOK_INTENT_CONFIGS, composeHooksFromIntents, getHookStatusForSurface } from '../lib/hook-intents.js';
-import { kernelCall } 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, generateCopilotInstructionFiles } from '../generators/adapters.js';
-import { readCanonicalSkills, readCanonicalRules, readPersonalLayer, readPersonalSkillsLayer, generateCursorSkill, generateCursorRule, generateCodexSkill, generateCodexSkillIndex, shouldEmitToTarget, filterByLevel, validateCodexSkills, evaluateConditions, } from '../generators/portable-knowledge.js';
-import { findNoProjectionAssets } from '../generators/noProjectionAssets.js'; // WP-660 S2 combine
-import { resolveSurfaceProfile } from '../generators/surface-profiles.js';
-import { generateEveryoneRulesMd } from '../generators/everyone-rules-md.js';
-import { removeStaleBriefingProjections, retireGeneratedProjections } from '../generators/retired-projections.js';
-import { formatWorkspaceBriefingLines } from '../lib/ruleListRender.js';
-import { formatHandshakeReport } from '../formatters/handshake.js';
-import { classifyAdapterFile, detectEol, spliceAppend, spliceReplace } from '../generators/region.js';
-import { REGION_PROJECTIONS } from '../generators/region-projections.js';
-import { readManifest, readManifestStatus, 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 { isJsonMode } from '../lib/runner.js';
-import { stripConvexInternals } from '../lib/strip.js';
-import { replaceVocabTokens } from '../lib/canonicalRefs.js';
-// WP-436 S3: vocab projector — resolves {{vocab:...}} tokens before writing to disk.
-import { getOrFetchVocabCtx } from '../lib/workspaceVocabCache.js';
-import { normalizeMaterializedFilename } from '../lib/normalizeMaterializedFilename.js';
-import { findLeftoverCursorSkills, LEFTOVER_FILES_MAX } from './handshakeCursorSkillCleanup.js';
-import { classifyDriftBucket } from './handshakeDriftClassification.js';
-import { sanitizeStartupResolutionSignals } from '../lib/startup-resolution-signals.js';
-import { assertSetupWritePath } from '../lib/writePerimeter.js';
-import { SURFACE_GOVERN_NO_SURFACES, SURFACE_REGISTRY, validateSurfacesForMode, } from '../surfaces/registry.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): every hook command MUST end with '|| true' so Claude Code always starts even if pb is unavailable.
-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'], hooks);
-    const close = HOOK_INTENT_CONFIGS['session-close'].command; // TASK-763 (DEC-2038): an older init closed on Stop, every turn
-    const stop = (hooks.Stop ?? []).map((g) => ({ ...g, hooks: g.hooks.filter((h) => h.command !== close) })).filter((g) => g.hooks.length > 0);
-    if (JSON.stringify(stop) !== JSON.stringify(hooks.Stop ?? [])) {
-        if (stop.length)
-            hooks.Stop = stop;
-        else
-            delete hooks.Stop;
-        added.push('Stop → pb session close removed (closed every turn)');
-    }
-    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.
-    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) — manifest.hooks.{cursor,copilot}, silence = no manifest/flags (DEC-536).
-    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)`);
-                    }
-                }
-            }
-        }
-    }
-}
-const LOCAL_REF_REGEX = /\b(?:WP|TEN|DEC|BET|FEAT|INS|STD|PRI|ARCH)[-\s#]*\d+\b|\bPR\s*#?\s*\d+\b/gi;
-const STARTUP_RESOLUTION_RESOLVER_VERSION = 'startup-resolution-v1';
-// Global cap on collected refs (spec "Contract: StartupResolutionSignals" — arrays are capped).
-const LOCAL_REF_GLOBAL_CAP = 25;
-// Per-source cap so a broad source (context.md) can't starve briefing.md's task-specific refs (Codex@677).
-const LOCAL_REF_PER_SOURCE_CAP = 18;
-// Time-boxed so an unauthed/slow `gh` can't stall session-start (F4).
-const PR_DIFF_TIMEOUT_MS = 4_000;
-// Bounds worst-case `gh` subprocess invocations per handshake.
-const PR_DIFF_MAX_REFS = 5;
-function runGitText(cwd, command) {
-    try {
-        const value = execSync(command, {
-            cwd,
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-        }).trim();
-        return value.length > 0 ? value : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/** Dereference a "PR #N" ref to its changed paths via `gh pr diff <N> --name-only` (F4: server
- *  resolver has no git/gh access). Guarded/time-boxed; `run` is injectable for tests. */
-export function dereferencePrRefToPaths(cwd, prNumber, run = runGitTextTimeboxed) {
-    if (!Number.isInteger(prNumber) || prNumber <= 0)
-        return [];
-    const raw = run(cwd, `gh pr diff ${prNumber} --name-only`, PR_DIFF_TIMEOUT_MS);
-    if (!raw)
-        return [];
-    return raw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
-}
-/** Time-boxed variant of runGitText for the PR-diff dereference (F4). */
-function runGitTextTimeboxed(cwd, command, timeoutMs) {
-    try {
-        const value = execSync(command, {
-            cwd,
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-            timeout: timeoutMs,
-        }).trim();
-        return value.length > 0 ? value : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-function readOptionalLocalText(cwd, path) {
-    const fullPath = join(cwd, path);
-    if (!existsSync(fullPath))
-        return undefined;
-    try {
-        return readFileSync(fullPath, 'utf8');
-    }
-    catch {
-        return undefined;
-    }
-}
-function normalizeLocalRef(ref) {
-    const trimmed = ref.trim().replace(/\s+/g, ' ');
-    const pr = trimmed.match(/^PR\s*#?\s*(\d+)$/i);
-    if (pr)
-        return `PR #${pr[1]}`;
-    const entry = trimmed.match(/^([A-Z]+)[-\s#]*(\d+)$/i);
-    if (entry)
-        return `${entry[1].toUpperCase()}-${entry[2]}`;
-    return trimmed;
-}
-/** Collect normalized local refs across several text sources, deduped. Codex@677: a per-source
- *  cap alongside the global one, so a broad source (context.md) can't starve a later,
- *  task-specific source (briefing.md); already-collected refs dedupe without spending later quota. */
-function collectLocalRefs(texts) {
-    const refs = [];
-    const seen = new Set();
-    for (const text of texts) {
-        if (!text)
-            continue;
-        let fromThisSource = 0;
-        for (const match of text.matchAll(LOCAL_REF_REGEX)) {
-            const ref = normalizeLocalRef(match[0]);
-            const key = ref.toLowerCase();
-            if (seen.has(key))
-                continue;
-            if (fromThisSource >= LOCAL_REF_PER_SOURCE_CAP)
-                break;
-            seen.add(key);
-            refs.push(ref);
-            fromThisSource++;
-            if (refs.length >= LOCAL_REF_GLOBAL_CAP)
-                return refs;
-        }
-    }
-    return refs;
-}
-function deriveHandshakeStartupTask(refs, changedPaths, callerTask) {
-    if (callerTask && callerTask.trim())
-        return callerTask.trim();
-    const parts = [];
-    if (refs.length > 0)
-        parts.push(refs.join(' '));
-    if (changedPaths.length > 0)
-        parts.push(`changed paths ${changedPaths.slice(0, 5).join(' ')}`);
-    return parts.length > 0 ? parts.join(' ') : undefined;
-}
-const DEFAULT_HANDSHAKE_SIGNAL_DEPS = {
-    runGit: runGitText,
-    prDiff: (cwd, prNumber) => dereferencePrRefToPaths(cwd, prNumber),
-};
-/** Extract the PR number from a normalized "PR #N" ref, else null. */
-function prNumberFromRef(ref) {
-    const m = ref.match(/^PR\s*#?\s*(\d+)$/i);
-    if (!m)
-        return null;
-    const n = Number(m[1]);
-    return Number.isInteger(n) && n > 0 ? n : null;
-}
-export function deriveHandshakeStartupSignals(cwd, callerSignals = {}, deps = DEFAULT_HANDSHAKE_SIGNAL_DEPS) {
-    const { runGit, prDiff } = deps;
-    const branchName = runGit(cwd, 'git branch --show-current');
-    const commitSha = runGit(cwd, 'git rev-parse --short HEAD');
-    // Changed paths, unioned + deduped: (1) dirty worktree; (2) committed branch delta vs origin/main's
-    // merge-base (Codex@665, invisible once the tree is clean); (3) PR-ref dereference (F4), appended later.
-    const dirtyChangedPaths = runGit(cwd, 'git diff --name-only HEAD')?.split(/\r?\n/).filter(Boolean) ?? [];
-    const mergeBase = runGit(cwd, 'git merge-base HEAD origin/main');
-    const branchChangedPaths = mergeBase
-        ? (runGit(cwd, `git diff --name-only ${mergeBase} HEAD`)?.split(/\r?\n/).filter(Boolean) ?? [])
-        : [];
-    const worktreeName = basename(cwd);
-    const contextText = readOptionalLocalText(cwd, '.productbrain/context.md');
-    const briefingText = readOptionalLocalText(cwd, '.productbrain/briefing.md');
-    const callerRefs = Array.isArray(callerSignals.reviewedArtifactRefs) ? callerSignals.reviewedArtifactRefs.join('\n') : undefined;
-    // Codex@677: briefing.md (task-specific) reads BEFORE context.md (broad) so its refs collect first — with the per-source cap, context.md can't starve briefing.
-    const refs = collectLocalRefs([
-        callerSignals.taskText ?? undefined,
-        callerSignals.explicitScope ?? undefined,
-        callerRefs,
-        branchName,
-        worktreeName,
-        briefingText,
-        contextText,
-    ]);
-    // F4: dereference "PR #N" refs to diff paths, folded into changedPaths — the only place this can happen (server records dereferenced:false, no git access). Time-boxed; absent/unauthed gh no-ops.
-    const prDiffPaths = [];
-    if (callerSignals.changedPaths === undefined) {
-        let derefed = 0;
-        for (const ref of refs) {
-            const prNumber = prNumberFromRef(ref);
-            if (prNumber === null)
-                continue;
-            if (derefed >= PR_DIFF_MAX_REFS)
-                break;
-            derefed++;
-            try {
-                for (const p of prDiff(cwd, prNumber))
-                    prDiffPaths.push(p);
-            }
-            catch {
-                // gh absent / unauthed / PR missing — skip gracefully, leave existing behavior.
-            }
-        }
-    }
-    // Caller-supplied changedPaths win (backward compat); otherwise union the
-    // three local sources, deduped, order-stable.
-    const unionedChangedPaths = callerSignals.changedPaths ??
-        Array.from(new Set([...dirtyChangedPaths, ...branchChangedPaths, ...prDiffPaths]));
-    const baseSignals = sanitizeStartupResolutionSignals({
-        ...callerSignals,
-        sourceSurface: callerSignals.sourceSurface ?? 'cli',
-        resolverVersion: callerSignals.resolverVersion ?? STARTUP_RESOLUTION_RESOLVER_VERSION,
-        branchName: callerSignals.branchName ?? branchName,
-        worktreeName: callerSignals.worktreeName ?? worktreeName,
-        changedPaths: unionedChangedPaths,
-        reviewedArtifactRefs: callerSignals.reviewedArtifactRefs ?? refs,
-        commitSha: callerSignals.commitSha ?? commitSha,
-    });
-    const taskText = deriveHandshakeStartupTask(baseSignals.reviewedArtifactRefs ?? [], baseSignals.changedPaths ?? [], baseSignals.taskText);
-    const sanitized = sanitizeStartupResolutionSignals({
-        ...baseSignals,
-        taskText,
-    });
-    const hasMeaningfulEvidence = Boolean(sanitized.taskText) ||
-        (sanitized.changedPaths?.length ?? 0) > 0 ||
-        (sanitized.reviewedArtifactRefs?.length ?? 0) > 0 ||
-        Boolean(sanitized.explicitScope);
-    if (hasMeaningfulEvidence)
-        return sanitized;
-    // Codex@704: even with no evidence, emit a minimal envelope carrying attribution — {} would
-    // drop the whole startup block, losing the loud domain-unresolved signal (spec "Loud Unresolved State", AC #4).
-    return sanitizeStartupResolutionSignals({
-        sourceSurface: sanitized.sourceSurface ?? 'cli',
-        resolverVersion: sanitized.resolverVersion ?? STARTUP_RESOLUTION_RESOLVER_VERSION,
-        branchName: sanitized.branchName,
-        worktreeName: sanitized.worktreeName,
-        commitSha: sanitized.commitSha,
-        changeId: sanitized.changeId,
-    });
-}
-/** Normalize volatile handshake-only timestamps before comparing generated files — keeps visible
- *  timestamps in artifacts while avoiding meaningless rewrites when 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) {
-    // An absent file at an adapter path is a projection target → materialize it.
-    if (!existsSync(filePath))
-        return true;
-    const content = readFileSync(filePath, 'utf8');
-    // No MARKER → user-owned/committed-static (CLAUDE.md, AGENTS.md, Copilot instructions) — never overwritten, not even under --force.
-    void force;
-    return content.includes(MARKER);
-}
-function normalizeSurfaceName(surface) {
-    const stripped = surface.startsWith('.') ? surface.slice(1) : surface;
-    const normalized = stripped === 'github' ? 'copilot' : stripped;
-    return normalized in SURFACE_REGISTRY ? normalized : null;
-}
-function surfacePerimeterRoots(surface) {
-    if (surface === 'codex')
-        return ['.codex', SURFACE_REGISTRY.codex.hookFilePath];
-    if (surface === 'copilot')
-        return ['.github', SURFACE_REGISTRY.copilot.hookFilePath];
-    if (surface === 'claude')
-        return ['.claude', 'CLAUDE.md'];
-    return [`.${surface}`];
-}
-// ── WP-421 S3: Three-bucket drift classification (doneWhen #17) — now its own module (STD-2/DEC-1504
-// shrink-only offset). Re-exported so existing imports `from '../commands/handshake.js'` keep working.
-export { classifyDriftBucket };
-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;
-}
-/**
- * findLeftoverProjections — WP-379 S5b
- *
- * Lists marker-bearing files under .cursor/rules/, .claude/rules/, .claude/skills/, .codex/skills/
- * (plus the nested .cursor/skills/<name>/SKILL.md layout) that look stale: orphan (no canonical
- * asset), stale case/punctuation variant, or a leftover `.dormant` copy. User-owned (no MARKER)
- * files and unselected `allowedTargets` are never reported.
- *
- * Round 12: stops once `LEFTOVER_FILES_MAX + 1` matches are found across the flat + merged
- * nested-Cursor scan combined — bounds read/enumerate I/O, not just the reported list.
- * `truncated` says more exist beyond the capped, returned `files`.
- *
- * @param cursorSkillNames Cursor-specific, SKILL-kind-only canon (falls back to `assetNames`).
- * @param exactRelativePaths Round 11: exact write-plan paths (forward-slash), exempted from both
- *   checks — covers asset-less generated files and a canonical raw name not already normalized.
- */
-export function findLeftoverProjections(cwd, assetNames, allowedTargets, cursorSkillNames, exactRelativePaths) {
-    const TARGET_DIRS_BY_EXT = [
-        { dir: join(cwd, '.cursor', 'rules'), ext: '.mdc', surface: 'cursor' },
-        { dir: join(cwd, '.claude', 'rules'), ext: '.md', surface: 'claude' },
-        { dir: join(cwd, '.claude', 'skills'), ext: '.md', surface: 'claude' },
-        { dir: join(cwd, '.codex', 'skills'), ext: '.md', surface: 'codex' },
-    ];
-    const canonicalNormalizedStems = new Set(assetNames.map((n) => normalizeMaterializedFilename(n)));
-    const exactPaths = exactRelativePaths ?? new Set();
-    const leftovers = [];
-    let truncated = false;
-    scanLoop: for (const { dir, ext, surface } of TARGET_DIRS_BY_EXT) {
-        if (!allowedTargets.has(surface))
-            continue;
-        if (!existsSync(dir))
-            continue;
-        let files;
-        try {
-            files = readdirSync(dir);
-        }
-        catch {
-            continue; // unreadable dir — skip
-        }
-        for (const filename of files) {
-            if (!filename.endsWith(ext) && !filename.endsWith(`${ext}.dormant`))
-                continue;
-            const fullPath = join(dir, filename);
-            let content;
-            try {
-                content = readFileSync(fullPath, 'utf8');
-            }
-            catch {
-                continue; // unreadable file — skip
-            }
-            if (!content.includes(MARKER))
-                continue; // user-owned — never reported
-            const isDormant = filename.endsWith('.dormant');
-            // A live file the write plan targets by this exact path is canonical by construction.
-            if (!isDormant) {
-                const relativePath = relative(cwd, fullPath).split(sep).join('/');
-                if (exactPaths.has(relativePath))
-                    continue;
-            }
-            const stem = basename(isDormant ? filename.slice(0, -'.dormant'.length) : filename, ext);
-            const normalizedStem = normalizeMaterializedFilename(stem);
-            let entry = null;
-            if (!canonicalNormalizedStems.has(normalizedStem)) {
-                entry = { path: fullPath, reason: 'orphan — no canonical asset matches this name' };
-            }
-            else if (isDormant) {
-                entry = { path: fullPath, reason: 'leftover .dormant file from an older binary version' };
-            }
-            else if (stem !== normalizedStem) {
-                entry = { path: fullPath, reason: `stale case/punctuation variant — canonical form is "${normalizedStem}${ext}"` };
-            }
-            if (!entry)
-                continue;
-            leftovers.push(entry);
-            if (leftovers.length > LEFTOVER_FILES_MAX) {
-                truncated = true;
-                leftovers.pop();
-                break scanLoop;
-            }
-        }
-    }
-    // Nested Cursor skills — extracted to its own module (STD-2/DEC-1504 shrink-only offset).
-    // Skipped once the flat scan already hit the cap; the remaining budget keeps the combined
-    // total across both scans stopping at LEFTOVER_FILES_MAX + 1.
-    if (!truncated && allowedTargets.has('cursor')) {
-        const nested = findLeftoverCursorSkills(cwd, cursorSkillNames ?? assetNames, LEFTOVER_FILES_MAX - leftovers.length);
-        leftovers.push(...nested.files);
-        truncated = nested.truncated;
-    }
-    return { files: leftovers, truncated };
-}
-/** Round 13 (Codex P1, security): strips a `user:token@` userinfo segment from an https remote
- *  so a credential never reaches JSON output. SSH remotes (`git@host:...`) are untouched — that
- *  `git@` is a fixed public username, not a secret. */
-function redactGitRemote(remote) {
-    return remote ? remote.replace(/^(https?:\/\/)[^@/]+@/i, '$1') : remote;
-}
-/** Round 13 (Codex P1, security): `pb --json handshake` serialized the report directly — leaking
- *  an HTTPS git-remote credential and raw Convex `_id`/`_creationTime` on `matchedEntries` (never
- *  went through the shared runner's `stripConvexInternals`). One public shape, both JSON paths. */
-function toPublicJsonReport(report) {
-    return stripConvexInternals({ ...report, repo: { ...report.repo, gitRemote: redactGitRemote(report.repo.gitRemote) } });
-}
-/** TASK-554 (RULE-659): getOrientView always serves the briefing's facts; a view without them is a broken contract. */
-function servedBriefing(view) {
-    if (view.briefing)
-        return view.briefing;
-    throw new CLIError('The orient view carried no briefing; getOrientView always serves one.', { code: ErrorCode.INTERNAL, category: 'internal' });
-}
-export async function runHandshake(options = {}) {
-    const config = await getConfigOrGuide(async () => { await runHandshake(options); });
-    if (!config)
-        return undefined;
-    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 a backward-compat alias).
-    const preview = !options.apply && !dryRun;
-    const applyMode = options.apply === true && !dryRun;
-    const level = options.level;
-    // `quiet` gates the final report write (`--json` alone still prints). `suppressProgress`
-    // also silences stdout log() prose in JSON mode. logErr() stays on `quiet` alone (stderr).
-    const quiet = options.quiet ?? false;
-    const suppressProgress = quiet || isJsonMode();
-    const timestamp = new Date().toISOString();
-    // Helper: emit progress line only when not suppressed. logErr is gated on `quiet` alone.
-    const log = (msg) => { if (!suppressProgress)
-        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(', ')}`);
-    }
-    const startupSignals = deriveHandshakeStartupSignals(cwd, options.startupSignals ?? {});
-    const orientArgs = { tier: 'standard' };
-    if (options.invocationPath)
-        orientArgs.invocationPath = options.invocationPath;
-    if (Object.keys(startupSignals).length > 0) {
-        orientArgs.startupSignals = startupSignals;
-        if (startupSignals.taskText)
-            orientArgs.task = startupSignals.taskText;
-    }
-    // Scopes the role rule lists this orient call returns to THIS session, not a sibling's.
-    const activeSession = readSession();
-    if (activeSession?.sessionId)
-        orientArgs.sessionId = activeSession.sessionId;
-    if (activeSession?.conversationId)
-        orientArgs.conversationId = activeSession.conversationId;
-    // 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', orientArgs).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: entries=${workspaceProfile.totalEntries}`);
-    }
-    // 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): query setup.listAssetsForUser, FS fallback.
-    const pbDir = join(cwd, '.productbrain');
-    const manifestStatus = readManifestStatus(pbDir);
-    const manifest = manifestStatus.manifest;
-    const surfaceValidation = validateSurfacesForMode(manifestStatus.mode, manifestStatus.surfaces);
-    if (applyMode && surfaceValidation.error === SURFACE_GOVERN_NO_SURFACES) {
-        throw new CLIError('materialize: govern requires at least one registered manifest surface.', {
-            code: ErrorCode.VALIDATION_FAILED,
-            category: 'validation',
-            guidance: 'Add surfaces such as `.cursor` or `.claude` to .productbrain/manifest.yaml.',
-        });
-    }
-    for (const surface of surfaceValidation.unregisteredSurfaces) {
-        logErr(`Warning: manifest surface "${surface}" is not registered; skipping it.`);
-    }
-    const manifestTargets = new Set(surfaceValidation.registeredSurfaces);
-    const cliTargets = new Set();
-    const ignoredCliSurfaces = [];
-    for (const surface of options.surfaces ?? []) {
-        const normalized = normalizeSurfaceName(surface);
-        if (normalized && manifestTargets.has(normalized)) {
-            cliTargets.add(normalized);
-        }
-        else {
-            ignoredCliSurfaces.push(surface);
-        }
-    }
-    if (ignoredCliSurfaces.length > 0) {
-        logErr(`Warning: --surfaces ignored outside manifest.surfaces: ${ignoredCliSurfaces.join(', ')}`);
-    }
-    const allowedTargets = options.surfaces && options.surfaces.length > 0
-        ? cliTargets
-        : manifestTargets;
-    const perimeterManifest = {
-        surfaces: [...manifestTargets].flatMap(surfacePerimeterRoots),
-    };
-    const authorityCanWrite = manifestStatus.mode === 'project' || manifestStatus.mode === 'govern';
-    const authorityPreviewOnly = applyMode && !authorityCanWrite;
-    const writeMode = applyMode && authorityCanWrite;
-    // TASK-554 (TEN-4036): materialize governs the coding-tool surfaces (DEC-951). PB's own files
-    // under .productbrain/ (context.md, briefing.md, generated/) refresh on every --apply wherever
-    // that folder exists; mode `off` means it does not (DEC-955), and then nothing is created.
-    const pbOwnedWriteMode = applyMode && manifestStatus.mode !== 'off';
-    // Skills and rules are read from the filesystem only (WP-776 S3f, DEC-1771).
-    const allSkills = readCanonicalSkills(pbDir);
-    const manualRules = readCanonicalRules(pbDir);
-    // The --generate flag and its chain-rules generator are gone: the everyone/team/role rule lists
-    // (DEC-1774) are the rule-delivery path (context.md, chain.mdc, everyone-rules.md).
-    let allRules = manualRules;
-    // 5b. Read personal layer (WP-310 E2) — machine-local rules/skills from .productbrain/.local/, [] if absent, all 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);
-    }
-    // 5d. Load method registry (WP-310 E4) — only when manifest is present. Unrelated to the
-    // setup-assets system (WP-329's own "methods" Chain collection, no setup.* coupling) — kept.
-    let registrySource;
-    let registryStale;
-    if (manifest) {
-        const registryResult = await loadMethodRegistry().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;
-    // Level filtering: requested level only (WP-762 C4e-2, DEC-1800 — no more stage cap).
-    const levelFilteredSkills = filterByLevel(adoptionFilteredSkills, level);
-    const levelFilteredRules = filterByLevel(adoptionFilteredRules, level);
-    // Apply when-condition filtering (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(', ')}`);
-    }
-    const noProjectionAssets = findNoProjectionAssets(canonicalSkills, canonicalRules);
-    if (canonicalSkills.length > 0 || canonicalRules.length > 0) {
-        const levelSuffix = level ? ` (level: ${level})` : '';
-        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}${stackSuffix}`);
-    }
-    // 6. Generate file contents
-    // Build workspace context for AGENTS.md enrichment (focus, entry count) — TASK-435 (C4c) deleted `stage` from it.
-    const agentsWorkspaceContext = workspaceProfile
-        ? {
-            focus: orientView?.strategicContext?.currentWorkPackage ?? undefined,
-            totalEntries: workspaceProfile.totalEntries,
-        }
-        : undefined;
-    // Collect codex-targeted skills for AGENTS.md skill directory — persist: 'local' entries included (all projections are local-only now).
-    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,
-    };
-    // TASK-554 (WP-777, DEC-1888): one workspace briefing (spine and the Everyone rule list, from
-    // the kernel builder) feeds context.md, everyone-rules.md and chain.mdc. `null` means the orient
-    // fetch failed: the two briefing files are not written (and a stale copy is removed in apply
-    // mode below), and chain.mdc says the briefing is unavailable.
-    const workspaceBriefingLines = orientView ? formatWorkspaceBriefingLines(servedBriefing(orientView), orientView.ruleLists) : null;
-    const contextContent = orientView && workspaceBriefingLines ? generateContextMd(orientView, workspaceBriefingLines, repo, timestamp) : null;
-    const everyoneRulesContent = workspaceBriefingLines ? generateEveryoneRulesMd(workspaceBriefingLines, timestamp) : 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, workspaceBriefingLines);
-    const copilotContent = generateCopilotMd(timestamp, copilotOptions);
-    // DEC-1343: one committed .github/instructions/<slug>.instructions.md per copilot rule with applyTo; repo-wide rules stay above.
-    const copilotInstructionFiles = generateCopilotInstructionFiles(canonicalRules
-        .filter((r) => shouldEmitToTarget(r, 'copilot'))
-        // `.github/instructions/` is COMMITTED — never project a machine-local (persist: 'local') rule into it.
-        .filter((r) => r.persist !== 'local')
-        .map((r) => ({ name: r.name, body: r.body, applyTo: r.applyTo, sourcePath: r.sourcePath })), timestamp);
-    const boundaryEnforcementMode = getBoundaryEnforcementMode(manifest);
-    const boundaryManifestContent = boundaryEnforcementMode === 'advisory'
-        ? null
-        : generateBoundaryManifest(pbDir);
-    // 7. Write files
-    const filesWritten = [];
-    const filesSkipped = [];
-    const previewPlan = [];
-    const writes = [
-        ...(contextContent ? [{ path: join(cwd, '.productbrain', 'context.md'), relative: '.productbrain/context.md', content: contextContent, dirs: join(cwd, '.productbrain'), isAdapter: false }] : []),
-        ...(everyoneRulesContent
-            ? [{
-                    path: join(cwd, '.productbrain', 'generated', 'everyone-rules.md'),
-                    relative: '.productbrain/generated/everyone-rules.md',
-                    content: everyoneRulesContent,
-                    dirs: join(cwd, '.productbrain', 'generated'),
-                    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', augmentTarget: true },
-        { path: join(cwd, 'CLAUDE.md'), relative: 'CLAUDE.md', content: claudeContent, isAdapter: true, target: 'claude', augmentTarget: true },
-        { 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' },
-        ...copilotInstructionFiles.map((f) => ({
-            path: join(cwd, f.relativePath),
-            relative: f.relativePath,
-            content: f.content,
-            dirs: join(cwd, '.github', 'instructions'),
-            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,
-        });
-    }
-    // 7a. WP-379 S5b: find leftover projections (apply mode) — REPORT-ONLY (coordinator ruling, PR
-    // #912 round 10), see findLeftoverProjections's own header. WP-776 S3f: gated on writeMode
-    // alone now — the DB source (dbQuerySucceeded) is gone, so activeAssetNames comes from the
-    // filesystem-sourced allSkills/allRules (which already include the personal layer, merged in
-    // above) instead of dbAssetRows.
-    let leftoverFiles = [];
-    let leftoverFilesTruncated = false;
-    // TASK-554 (RULE-659): a failed orient fetch is named in the report, and apply removes stale briefing copies.
-    if (orientView === null) {
-        for (const path of ['.productbrain/context.md', '.productbrain/generated/everyone-rules.md'])
-            filesSkipped.push({ path, reason: 'briefing unavailable — the orient fetch failed' });
-        const stale = pbOwnedWriteMode ? removeStaleBriefingProjections(cwd) : [];
-        if (stale.length > 0)
-            logErr(`Warning: the workspace briefing could not be fetched; removed the stale ${stale.join(', ')}.`);
-    }
-    if (writeMode) {
-        retireGeneratedProjections(cwd, log);
-        const activeAssetNames = [
-            ...allSkills.map((s) => s.name),
-            ...allRules.map((r) => r.name),
-        ];
-        // Nested .cursor/skills scan gets its OWN canon: canonicalSkills is SKILL-kind only and
-        // shouldEmitToTarget(_, 'cursor') respects per-skill target routing.
-        const cursorSkillNames = canonicalSkills.filter((s) => shouldEmitToTarget(s, 'cursor')).map((s) => s.name);
-        // Round 11: exempt exact write-plan paths from the leftover scan (see findLeftoverProjections's own doc).
-        const exactRelativePaths = new Set(writes.map((w) => w.relative));
-        const scanResult = findLeftoverProjections(cwd, activeAssetNames, allowedTargets, cursorSkillNames, exactRelativePaths);
-        leftoverFiles = scanResult.files;
-        leftoverFilesTruncated = scanResult.truncated;
-    }
-    // ── WP-436 S3: Vocab projector — fetch workspace vocab context once per handshake. Source-side
-    // stays tokenized; resolves {{vocab:...}} before writing. Fail-open: a failed fetch writes the raw token.
-    const handshakeVocabCtx = await getOrFetchVocabCtx(config.apiKey, async () => {
-        try {
-            const vocab = await kernelCall('chain.getVocabulary', {});
-            if (vocab?.collectionLabels || vocab?.collectionDefaults) {
-                return {
-                    ...(vocab.collectionLabels ? { collectionLabels: vocab.collectionLabels } : {}),
-                    ...(vocab.collectionDefaults ? { collectionDefaults: vocab.collectionDefaults } : {}),
-                };
-            }
-            return null;
-        }
-        catch {
-            return null; // fail-open
-        }
-    });
-    const userOwnedSkipped = [];
-    const cleanBucketPaths = [];
-    const tamperedBucket = [];
-    // TEN-2155: region augmentation context + symlink dedupe — codexActive gates the AGENTS.md skills-index pointer.
-    const regionCtx = { codexActive: allowedTargets.has('codex') };
-    const malformedRegionPaths = [];
-    // Same inode for two augment targets (e.g. CLAUDE.md symlinked to AGENTS.md): augment only first-seen.
-    const seenAugmentRealpaths = new Set();
-    const augmentTargetSkip = new Set();
-    for (const w of writes) {
-        if (!w.augmentTarget || !w.target || !allowedTargets.has(w.target) || !existsSync(w.path))
-            continue;
-        let real;
-        try {
-            real = realpathSync(w.path);
-        }
-        catch {
-            real = w.path;
-        }
-        if (seenAugmentRealpaths.has(real))
-            augmentTargetSkip.add(w.path);
-        else
-            seenAugmentRealpaths.add(real);
-    }
-    for (const w of writes) {
-        // Surface filtering: skip adapter writes for targets not in the allowed set
-        if (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;
-        }
-        // ── TEN-2155: augment user-owned CLAUDE.md / AGENTS.md with a marked PB region — runs ahead
-        // of the legacy MARKER gates; absent/legacy-pb-managed fall through to the legacy path.
-        if (w.augmentTarget) {
-            const projection = REGION_PROJECTIONS[w.target];
-            if (projection && existsSync(w.path)) {
-                if (augmentTargetSkip.has(w.path)) {
-                    filesSkipped.push({ path: w.relative, reason: 'symlinked to another augment target — augmented once' });
-                    continue;
-                }
-                const disk = readFileSync(w.path, 'utf8');
-                const cls = classifyAdapterFile(disk);
-                if (cls === 'augmentable' || cls === 'region-present') {
-                    const eol = detectEol(disk);
-                    const region = replaceVocabTokens(projection.build(regionCtx, eol), handshakeVocabCtx);
-                    // Defense-in-depth: the composed region (post vocab-token resolution) must itself be a
-                    // single well-formed region. v1 content has no vocab tokens so this is a no-op, but it
-                    // guards the documented future override/vocab seam from injecting a stray sentinel/MARKER.
-                    if (classifyAdapterFile(region) !== 'region-present') {
-                        filesSkipped.push({ path: w.relative, reason: 'internal: composed PB region malformed — skipped to protect your file' });
-                        if (preview)
-                            previewPlan.push({ path: w.relative, status: 'needs-attention' });
-                        continue;
-                    }
-                    const candidate = cls === 'augmentable' ? spliceAppend(disk, region, eol) : spliceReplace(disk, region);
-                    if (candidate === disk) {
-                        filesSkipped.push({ path: w.relative, reason: 'unchanged' });
-                        if (preview)
-                            previewPlan.push({ path: w.relative, status: 'unchanged' });
-                        continue;
-                    }
-                    if (preview || dryRun) {
-                        filesWritten.push(w.relative + (dryRun ? ' (dry run)' : ''));
-                        if (preview)
-                            previewPlan.push({ path: w.relative, status: 'would-augment' });
-                        continue;
-                    }
-                    if (authorityPreviewOnly) {
-                        // apply + materialize observe/off: honor authority — do NOT write; mirror the legacy
-                        // preview-only skip so the report does not falsely list it as written.
-                        filesSkipped.push({ path: w.relative, reason: `preview-only (materialize: ${manifestStatus.mode})` });
-                        continue;
-                    }
-                    assertSetupWritePath(w.path, perimeterManifest);
-                    writeFileSync(w.path, candidate);
-                    filesWritten.push(w.relative);
-                    continue;
-                }
-                if (cls === 'malformed') {
-                    filesSkipped.push({ path: w.relative, reason: 'malformed PB region — left untouched; fix the pb:region sentinels' });
-                    if (preview)
-                        previewPlan.push({ path: w.relative, status: 'needs-attention' });
-                    malformedRegionPaths.push(w.relative);
-                    continue;
-                }
-                // cls 'pb-managed' falls through to legacy re-projection; 'opt-out' (pb:no-augment) falls through to the user-owned skip.
-            }
-            // absent file → fall through to legacy whole-file CREATE.
-        }
-        if (w.isAdapter && !shouldWriteAdapter(w.path, force)) {
-            // User-owned: a file at an adapter path without our auto-gen MARKER is the
-            // user's own file. Leave it untouched — never overwrite, never treat as drift
-            // or log a TEN (TEN-2150). Relayed to the connect screen via userOwnedSkipped.
-            filesSkipped.push({ path: w.relative, reason: 'user-owned — left untouched (pb won\'t overwrite your file)' });
-            if (preview) {
-                previewPlan.push({ path: w.relative, status: 'user-owned' });
-            }
-            else {
-                userOwnedSkipped.push(w.relative);
-            }
-            continue;
-        }
-        if (w.isAdapter ? authorityPreviewOnly : applyMode && !pbOwnedWriteMode) {
-            filesSkipped.push({
-                path: w.relative,
-                reason: `preview-only (materialize: ${manifestStatus.mode})`,
-            });
-            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;
-        }
-        // ── WP-421 S3: defer tampered adapter writes (doneWhen #17) — classify pb-managed-clean vs
-        // pb-managed-tampered, deferred not overwritten; post-loop resolves. --force bypasses the defer.
-        if (w.isAdapter && !force) {
-            const drift = classifyDriftBucket(w.path);
-            if (drift && drift.bucket === 'pb-managed-tampered') {
-                tamperedBucket.push({
-                    path: w.path,
-                    relative: w.relative,
-                    content: w.content,
-                    expectedHash: drift.expectedHash,
-                    actualHash: drift.actualHash,
-                    dirs: w.dirs,
-                });
-                // Do NOT write — defer until prompt/refusal resolves the file.
-                continue;
-            }
-            if (drift && drift.bucket === 'pb-managed-clean') {
-                cleanBucketPaths.push(w.relative);
-            }
-        }
-        assertSetupWritePath(w.path, perimeterManifest);
-        if (w.dirs)
-            mkdirSync(w.dirs, { recursive: true });
-        // WP-436 S3: resolve {{vocab:...}} tokens before writing projected adapter files only
-        // (source-side stays tokenized). Fail-open: undefined vocabCtx falls back to canonicalKey literals.
-        const resolvedContent = w.isAdapter
-            ? replaceVocabTokens(w.content, handshakeVocabCtx)
-            : w.content;
-        if (existsSync(w.path)) {
-            const current = readFileSync(w.path, 'utf8');
-            const nextNormalized = normalizeHandshakeContentForComparison(resolvedContent);
-            const currentNormalized = normalizeHandshakeContentForComparison(current);
-            if (nextNormalized === currentNormalized) {
-                filesSkipped.push({ path: w.relative, reason: 'unchanged' });
-                continue;
-            }
-        }
-        writeFileSync(w.path, resolvedContent);
-        filesWritten.push(w.relative);
-    }
-    // Runs AFTER the write loop (malformed files were never written, nothing to record). TEN-2155:
-    // non-interactive apply refuses on a malformed region — gated on applyMode per STD-263 vi.
-    if (applyMode && malformedRegionPaths.length > 0 && (options.noPrompt || !process.stdout.isTTY)) {
-        throw new CLIError(`Malformed PB region in: ${malformedRegionPaths.join(', ')}`, {
-            code: ErrorCode.VALIDATION_FAILED,
-            category: 'validation',
-            guidance: 'Fix the `<!-- pb:region:start -->` / `<!-- pb:region:end -->` sentinels (one balanced pair), then re-run `pb handshake`.',
-        });
-    }
-    // ── WP-421 S3: tampered-bucket resolution (doneWhen #17), apply mode only — headless (--no-prompt
-    // / non-TTY) refuses, exit non-zero. WP-776 S3d/S3f: the setup-assets system this resolution used
-    // to offer as an "adopt" alternative (capture tampered edits as a personal-scoped draft via
-    // setup.ingestSetupAsset) is deleted, and with it the only OTHER option besides overwriting —
-    // per DEC-1771 (delete, never hide) there is no shim standing in for that capability. Revert
-    // (re-project canonical content) is the only resolution left; this is a real capability loss
-    // for anyone who was relying on "adopt" to preserve hand-edits, named here rather than silently
-    // dropped. The refusal receipt (`setup.recordTamperRefusal`) is deleted along with the rest of
-    // the setup-assets gateway routes — headless mode still refuses and reports, it just no longer
-    // writes an audit row for the refusal.
-    const revertedTamperedPaths = [];
-    if (writeMode && tamperedBucket.length > 0) {
-        const headless = options.noPrompt === true || !process.stdout.isTTY;
-        if (headless) {
-            // ── Headless refusal path (doneWhen #17) ────────────────────────────────
-            logErr('');
-            logErr(`pb handshake: ${tamperedBucket.length} PB-managed projection file(s) were edited downstream of the auto-gen marker.`);
-            logErr('Headless mode (--no-prompt or no TTY) cannot confirm an overwrite — refusing.');
-            logErr('');
-            const refusedTamperedFiles = tamperedBucket.map((t) => ({
-                path: t.relative,
-                expectedHash: t.expectedHash,
-                actualHash: t.actualHash,
-            }));
-            for (const refused of refusedTamperedFiles) {
-                // Per #17: stderr enumerates each tampered file as
-                // {path, expectedHash, actualHash, bucket}.
-                logErr(`  ${JSON.stringify({ ...refused, bucket: 'pb-managed-tampered' })}`);
-            }
-            logErr('');
-            logErr('Re-run interactively to resolve, or use --force to overwrite (data loss).');
-            // Surface the report counts before exit (visibility for CI logs).
-            if (!quiet) {
-                const refusalReport = {
-                    filesWritten,
-                    filesSkipped,
-                    matchedEntries,
-                    searchQueries: uniqueQueries,
-                    repo,
-                    codexWarnings: codexWarnings.length > 0 ? codexWarnings : undefined,
-                    adoptedCount: adoptedRulesCount,
-                    rejectedCount: rejectedRulesCount,
-                    personalRuleCount: personalRules.length > 0 ? personalRules.length : undefined,
-                    personalSkillCount: personalSkills.length > 0 ? personalSkills.length : undefined,
-                    registrySource,
-                    registryStale,
-                    userOwnedSkipped: userOwnedSkipped.length > 0 ? userOwnedSkipped : undefined,
-                    managedCleanCount: cleanBucketPaths.length || undefined,
-                    tamperedFiles: refusedTamperedFiles,
-                    leftoverFiles: leftoverFiles.length > 0 ? leftoverFiles : undefined,
-                    leftoverFilesTruncated: leftoverFilesTruncated || undefined, noProjectionAssets: noProjectionAssets.length > 0 ? noProjectionAssets : undefined, // same-line combine, shrink-only budget
-                };
-                process.stdout.write('\n');
-                process.stdout.write(isJsonMode() ? JSON.stringify(toPublicJsonReport(refusalReport)) + '\n' : formatHandshakeReport(refusalReport) + '\n');
-            }
-            // Exit non-zero per #17.
-            process.exit(1);
-        }
-        // ── Interactive path: confirm, then revert every tampered file ─────────────
-        log('');
-        log(`pb handshake: ${tamperedBucket.length} PB-managed projection file(s) were edited downstream of the auto-gen marker.`);
-        log('These will be REVERTED (overwritten with canonical content) — there is no adopt/draft path any more.');
-        const proceed = await promptConfirm({
-            message: `Overwrite ${tamperedBucket.length} tampered file(s) with canonical content?`,
-            initialValue: false,
-        });
-        if (proceed) {
-            for (const tamper of tamperedBucket) {
-                log('');
-                log(`Reverting: ${tamper.relative}`);
-                log(`  expected: ${tamper.expectedHash}`);
-                log(`  actual:   ${tamper.actualHash}`);
-                // Re-project canonical content over the tampered file.
-                // WP-436 S3: resolve vocab tokens before writing (all tampered files are adapters).
-                if (tamper.dirs)
-                    mkdirSync(tamper.dirs, { recursive: true });
-                assertSetupWritePath(tamper.path, perimeterManifest);
-                writeFileSync(tamper.path, replaceVocabTokens(tamper.content, handshakeVocabCtx));
-                revertedTamperedPaths.push(tamper.relative);
-            }
-        }
-        else {
-            logErr('Skipped — tampered files left as-is; re-run to resolve.');
-            process.exit(1); // doneWhen #17: never exit 0 with a tampered file unresolved (codex review round 3)
-        }
-    }
-    // DEC-1690: a dormant (gate-failed) asset is simply not projected — dbAssets already comes
-    // from the server's activeAssets list. The WP-379 S4 / WP-426 E4 on-disk marker/rename/restore
-    // machinery (and its .authoring-sync.json registries) is retired: nothing to reconcile.
-    // 8. User-owned files left untouched are NOT drift (TEN-2150) — a marker-less adapter-path
-    // file is the user's own; handshake never wrote it, so no "sync", no draft TEN, just a benign
-    // "Skipped:" surfaced via report.userOwnedSkipped.
-    // 8. Case-collision and dormant-drift TENs are gone (coordinator ruling, PR #912 round 10) —
-    // they existed only to audit automated deletions that no longer happen; `report.leftoverFiles`
-    // below is the single reporting surface now.
-    // 9. Report
-    const report = {
-        filesWritten,
-        filesSkipped,
-        matchedEntries,
-        searchQueries: uniqueQueries,
-        repo,
-        codexWarnings: codexWarnings.length > 0 ? codexWarnings : 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,
-        userOwnedSkipped: userOwnedSkipped.length > 0 ? userOwnedSkipped : undefined,
-        // WP-421 S3: three-bucket drift report (doneWhen #17). PB-managed-clean is
-        // the count of files whose marker + hash matched. Tampered files were
-        // resolved (reverted) above and are reported separately. WP-776 S3d/S3f:
-        // adoptedTamperedPaths is gone — "adopt" is no longer an option (see the
-        // tampered-bucket resolution comment above).
-        managedCleanCount: cleanBucketPaths.length > 0 ? cleanBucketPaths.length : undefined,
-        revertedTamperedPaths: revertedTamperedPaths.length > 0 ? revertedTamperedPaths : undefined,
-        // REPORT-ONLY leftover-file listing (coordinator ruling, PR #912 round 10) — the human removes these.
-        leftoverFiles: leftoverFiles.length > 0 ? leftoverFiles : undefined,
-        leftoverFilesTruncated: leftoverFilesTruncated || undefined, noProjectionAssets: noProjectionAssets.length > 0 ? noProjectionAssets : undefined, // WP-660 S2 combine
-    };
-    if (!quiet) {
-        process.stdout.write('\n');
-        process.stdout.write(isJsonMode() ? JSON.stringify(toPublicJsonReport(report)) + '\n' : formatHandshakeReport(report) + '\n');
-    }
-    // Return the report so non-UI callers (e.g. prepareConnectContext) can surface
-    // skipped/user-owned files without re-deriving the skip logic (TEN-2107).
-    return report;
-}
-// WP-426 E3/E4: exported test-only surface (not part of the public CLI API). setupAuthoringPath
-// and loadAuthoringSyncState are gone with the setup-authoring sync machinery (WP-776 S3d/S3f).
-export const __test = { MARKER };
-//# sourceMappingURL=handshake.js.map