@productbrain/cli 0.1.0-beta.75 → 0.1.0-beta.7503

package/dist/commands/handshake.js

@@ -1,24 +1,43 @@
 /**
  * pb handshake — generate context files for AI developer tools.
- * The fourth delivery surface: context export (GLO-63, DEC-161).
+ * Context export wiring (read-only filesystem bridge; GLO-63, DEC-161) — not a product surface.
  */
-import { mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync, copyFileSync } from 'fs';
-import { join, dirname, resolve } from 'path';
+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 } from '../lib/prompts.js';
+import { select as promptSelect, confirm as promptConfirm } from '../lib/prompts.js';
+import { composeHooksFromIntents, getHookStatusForSurface } from '../lib/hook-intents.js';
 import { kernelCall } from '../lib/client.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, generateCursorSkill, generateCursorRule, generateCodexSkill, generateCodexSkillIndex, generateClaudeRule, generateClaudeSkillRouter, shouldEmitToTarget, filterByLevel, validateCodexSkills, evaluateConditions, STAGE_TO_MAX_LEVEL, LEVEL_ORDER, } from '../generators/portable-knowledge.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, STAGE_TO_MAX_LEVEL, LEVEL_ORDER, } from '../generators/portable-knowledge.js';
 import { generateChainRules } from '../generators/chain-rules.js';
+import { findNoProjectionAssets } from '../generators/noProjectionAssets.js'; // WP-660 S2 combine
 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 { 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',
@@ -47,12 +66,8 @@ const LEVELS = {
 };
 // 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.
+// 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:*)';
-const INIT_SESSION_START_CMD = 'pb session start 2>/dev/null || true';
-const INIT_SESSION_CLOSE_CMD = 'pb session close 2>/dev/null || true';
-const INIT_PRECOMPACT_CMD = 'pb session id > /dev/null 2>&1 && echo \'{"systemMessage": "pb session active — capture decisions/tensions before compacting: pb capture \\"DEC: ...\\""}\'  || true';
 function readSettings(filePath) {
     if (!existsSync(filePath))
         return {};
@@ -64,9 +79,6 @@ function readSettings(filePath) {
         return {};
     }
 }
-function hasCommand(groups, cmd) {
-    return (groups ?? []).some((g) => g.hooks?.some((h) => h.command === cmd));
-}
 // Team write: hooks + Bash(pb:*) → .claude/settings.json (safe to commit)
 function writeTeamSettings(cwd, dryRun) {
     const claudeDir = join(cwd, '.claude');
@@ -82,26 +94,10 @@ function writeTeamSettings(cwd, dryRun) {
     }
     settings.permissions = permissions;
     const hooks = (settings.hooks ?? {});
-    if (!hasCommand(hooks.SessionStart, INIT_SESSION_START_CMD)) {
-        hooks.SessionStart = [
-            ...(hooks.SessionStart ?? []),
-            { hooks: [{ type: 'command', command: INIT_SESSION_START_CMD, statusMessage: 'Opening pb session...' }] },
-        ];
-        added.push('SessionStart → pb session start');
-    }
-    if (!hasCommand(hooks.Stop, INIT_SESSION_CLOSE_CMD)) {
-        hooks.Stop = [
-            ...(hooks.Stop ?? []),
-            { hooks: [{ type: 'command', command: INIT_SESSION_CLOSE_CMD, statusMessage: 'Closing pb session...' }] },
-        ];
-        added.push('Stop → pb session close');
-    }
-    if (!hasCommand(hooks.PreCompact, INIT_PRECOMPACT_CMD)) {
-        hooks.PreCompact = [
-            ...(hooks.PreCompact ?? []),
-            { hooks: [{ type: 'command', command: INIT_PRECOMPACT_CMD }] },
-        ];
-        added.push('PreCompact → decision capture reminder');
+    const hookAdditions = composeHooksFromIntents(['session-start', 'session-close', 'pre-compact'], hooks);
+    for (const addition of hookAdditions) {
+        hooks[addition.event] = [...(hooks[addition.event] ?? []), addition.entry];
+        added.push(addition.label);
     }
     settings.hooks = hooks;
     if (!dryRun) {
@@ -171,8 +167,7 @@ export async function runHandshakeInit(options = {}) {
         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.
+    // 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);
@@ -194,6 +189,27 @@ export async function runHandshakeInit(options = {}) {
     if (!dryRun)
         console.log('Reload /hooks in Claude Code (or restart) to activate.');
     console.log('Run `pb handshake --init --level <guide|work|silent|full-trust>` to change level.');
+    // Step 2b: Report multi-surface hook opt-in status (WP-310 E3b) — 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;
@@ -242,24 +258,239 @@ export async function runHandshakeInit(options = {}) {
         }
     }
 }
-/**
- * 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.
- */
+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) {
-    if (force)
-        return true;
+    // 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-776 S3f: modeRank deleted — its only caller compared authority-mode transitions for the
+// now-deleted setup.recordTransition receipt.
+// ── 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 = [];
@@ -272,19 +503,128 @@ function deduplicateEntries(entries) {
     }
     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) } });
+}
 export async function runHandshake(options = {}) {
-    const config = await getConfigOrGuide(() => runHandshake(options));
+    const config = await getConfigOrGuide(async () => { await runHandshake(options); });
     if (!config)
-        return;
+        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 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)
+    // 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'); };
@@ -303,6 +643,15 @@ export async function runHandshake(options = {}) {
     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;
+    }
     // 2. Fetch orient view + workspace readiness in parallel (budget max +200ms added latency)
     log('Fetching workspace context...');
     let orientView = null;
@@ -310,7 +659,7 @@ export async function runHandshake(options = {}) {
     try {
         const workspaceReadinessPromise = kernelCall('chain.workspaceReadiness', {}).catch(() => null);
         const [orientResult, readinessRaw] = await Promise.all([
-            kernelCall('chain.getOrientView', {}).catch((err) => {
+            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;
@@ -325,7 +674,7 @@ export async function runHandshake(options = {}) {
         logErr('Continuing with limited context (Chain search + portable knowledge only).');
     }
     if (workspaceProfile) {
-        log(`Workspace profile: stage=${workspaceProfile.stage}, entries=${workspaceProfile.totalEntries}, governance=${workspaceProfile.governanceMode}`);
+        log(`Workspace profile: entries=${workspaceProfile.totalEntries}`);
     }
     // 3. Build search queries from repo context
     const searchQueries = [];
@@ -347,8 +696,51 @@ export async function runHandshake(options = {}) {
         const searchResults = await Promise.all(uniqueQueries.map((q) => kernelCall('chain.searchEntries', { query: q }).catch(() => [])));
         matchedEntries = deduplicateEntries(searchResults.flat());
     }
-    // 5. Read canonical skills & rules from .productbrain/
+    // 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;
+    // WP-776 S3f: the DB-first setup-asset sourcing pipeline (setup.listAssetsForUser +
+    // setup.fetchAssetBody + setup.resolveSemanticRefs + setup.ingestSetupAssetWithBody, plus the
+    // personal-asset dormancy sync and per-asset projection-hash/drift-detection bookkeeping around
+    // it) is deleted along with the rest of the setup-assets system — DEC-1771 (delete, never hide).
+    // The filesystem read path below (readCanonicalSkills/readCanonicalRules) was always the
+    // fallback when the DB source was unavailable; it is now the only source.
     const allSkills = readCanonicalSkills(pbDir);
     const manualRules = readCanonicalRules(pbDir);
     // 5a. Optionally fetch and merge Chain-derived rules (--generate flag)
@@ -382,12 +774,49 @@ export async function runHandshake(options = {}) {
             log(diffText);
         }
     }
-    // Apply level filtering with stage-gating (after read, 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.
+    // 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 with stage-gating: stage caps the effective level (blank→beginner, seed→intermediate, grounded+→expert).
     const profileStage = workspaceProfile?.stage;
-    const levelFilteredSkills = filterByLevel(allSkills, level, profileStage);
-    const levelFilteredRules = filterByLevel(allRules, level, profileStage);
+    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];
@@ -395,7 +824,7 @@ export async function runHandshake(options = {}) {
             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}`);
+                log(`Level capped from ${level || 'expert'} to ${stageCap}`);
             }
         }
     }
@@ -420,25 +849,23 @@ export async function runHandshake(options = {}) {
     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 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}`);
+        log(`Portable knowledge: ${canonicalSkills.length}/${totalSkills} skills, ${canonicalRules.length}/${totalRules} rules${levelSuffix}${stackSuffix}`);
     }
     // 6. Generate file contents
-    // Build workspace context for AGENTS.md enrichment (stage, focus, governance, entry count)
+    // Build workspace context for AGENTS.md enrichment (focus, entry count) — TASK-435 (C4c) deleted `stage` from it.
     const agentsWorkspaceContext = workspaceProfile
         ? {
-            stage: workspaceProfile.stage,
-            focus: orientView?.strategicContext?.currentBet ?? undefined,
-            governanceMode: workspaceProfile.governanceMode,
+            focus: orientView?.strategicContext?.currentWorkPackage ?? undefined,
             totalEntries: workspaceProfile.totalEntries,
         }
         : undefined;
-    // Collect codex-targeted skills for AGENTS.md skill directory
+    // 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) => ({
@@ -477,26 +904,52 @@ export async function runHandshake(options = {}) {
     const claudeContent = generateClaudeMd(timestamp);
     const cursorContent = generateCursorMdc(timestamp);
     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 = [];
-    // 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 previewPlan = [];
+    // WP-776 S3f: the personal-setup-asset authoring sync block (setup.markPersonalSetupAssetDormantFromSync
+    // + setup.updateLastProjectedHash) is deleted along with the DB-asset sourcing pipeline above —
+    // there is no DB-sourced personal asset any more to reconcile against .productbrain authoring files.
     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, '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'),
@@ -505,12 +958,14 @@ export async function runHandshake(options = {}) {
             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`,
@@ -518,6 +973,7 @@ export async function runHandshake(options = {}) {
             dirs: join(cwd, '.codex', 'skills'),
             isAdapter: true,
             target: 'codex',
+            dbAssetEntryId,
         });
     }
     writes.push({
@@ -534,6 +990,7 @@ export async function runHandshake(options = {}) {
     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`,
@@ -541,64 +998,336 @@ export async function runHandshake(options = {}) {
             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;
-        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',
-        });
+    // 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;
+    if (writeMode) {
+        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;
     }
-    // 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',
-        });
+    // ── 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 (allowedTargets && w.target && !allowedTargets.has(w.target)) {
+        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)) {
-            filesSkipped.push({ path: w.relative, reason: 'exists without auto-generated marker (use --force to overwrite)' });
+            // 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 (dryRun) {
-            filesWritten.push(w.relative + ' (dry run)');
+        if (authorityPreviewOnly) {
+            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(w.content);
+            const nextNormalized = normalizeHandshakeContentForComparison(resolvedContent);
             const currentNormalized = normalizeHandshakeContentForComparison(current);
             if (nextNormalized === currentNormalized) {
                 filesSkipped.push({ path: w.relative, reason: 'unchanged' });
                 continue;
             }
         }
-        writeFileSync(w.path, w.content);
+        writeFileSync(w.path, resolvedContent);
         filesWritten.push(w.relative);
     }
-    // 8. Report
+    // WP-776 S3f: the projected-hash flush back to the DB (setup.updateLastProjectedHash) is
+    // deleted along with the rest of the setup-assets gateway routes — there is no DB-sourced
+    // asset any more whose lastProjectedHash needs updating (dbAssetEntryId is always undefined
+    // now that allSkills/allRules are filesystem-sourced).
+    // Runs AFTER the hash flush (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,
+                    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,
+                    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.
+    // WP-776 S3f: the setup-transition receipt (setup.getCurrentSetupState / setup.recordTransition)
+    // and the setup materialization receipt (setup.materializeSetup) are deleted along with the
+    // rest of the setup-assets gateway routes — both were fail-open advisory writes recording
+    // authority-mode transitions and materialized-asset counts for a system that no longer exists.
+    // 9. Report
     const report = {
         filesWritten,
         filesSkipped,
@@ -608,10 +1337,35 @@ export async function runHandshake(options = {}) {
         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,
+        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(formatHandshakeReport(report) + '\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