@deftai/directive-core 0.104.0 → 0.105.0

package/dist/init-deposit/refresh.js

@@ -8,7 +8,7 @@
  * Refs #1942, #1430, #1671.
  */
 import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync, renameSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { platform as osPlatform } from "node:os";
 import { join, resolve } from "node:path";
 import { assertDepositContained } from "../deposit/contain.js";
@@ -18,6 +18,8 @@ import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
 import { readCorePackageVersion } from "../engine-version.js";
 import { readLiveGeneration, stampLiveGeneration } from "../freshness/generation.js";
+import { containedRename } from "../fs/contained-write.js";
+import { activeMutationLedger, formatMutationSummary, mutationSummaryJson, runInPortRecordMode, runWithMutationLedger, snapshotMutationSummary, } from "../fs/mutation-ledger.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_FLAG_NAME, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY, } from "../policy/no-deft-directive.js";
 import { runOrgForceOnMigration } from "../policy/org-force-on-migration.js";
@@ -189,7 +191,11 @@ function migrateLegacyInstallManifest(projectDir, canonicalManifestPath) {
         const canonicalVersion = manifestTagToVersion(parseInstallManifest(readFileSync(canonical, "utf8")));
         if (legacyVersion !== null && legacyVersion === canonicalVersion)
             return;
-        renameSync(legacy, join(projectDir, ".deft", "VERSION.premigrate"));
+        containedRename({
+            root: projectDir,
+            from: legacy,
+            to: join(projectDir, ".deft", "VERSION.premigrate"),
+        });
     }
     catch {
         // best-effort
@@ -312,8 +318,8 @@ export function printRefreshSideEffects(io, effects) {
     }
     io.printf("\nAGENTS.md refresh side effects (#1671): the refresh and framework payload swap\n");
     io.printf("left these framework files with uncommitted changes -- they belong in the\n");
-    io.printf("framework deposit commit (the installer stages them before printing the\n");
-    io.printf("`git add` list below, so there are no post-stage stragglers):\n");
+    io.printf("framework deposit commit (the installer stages this-run installer-managed\n");
+    io.printf("paths; ledger remainder stays unstaged):\n");
     for (const file of effects.files) {
         io.printf(`  ${file}\n`);
     }
@@ -335,6 +341,32 @@ export function buildVersionSkewNotice(engineVersion, contentVersion, previousDe
     }
     return null;
 }
+function displayVersion(version) {
+    return version === null || version.trim() === "" ? "unknown" : normalizeVersion(version);
+}
+/** True when recorded deposit version and content package version disagree (#3437). */
+export function depositRefreshPending(previousDepositVersion, contentVersion) {
+    if (previousDepositVersion === null || previousDepositVersion.trim() === "")
+        return true;
+    return normalizeVersion(previousDepositVersion) !== normalizeVersion(contentVersion);
+}
+/** First-line dry-run headline when deposit manifest and content disagree (#3437). */
+export function buildDepositVersionSkewHeadline(previousDepositVersion, contentVersion) {
+    if (!depositRefreshPending(previousDepositVersion, contentVersion))
+        return null;
+    return (`[deft update] Version skew: deposit manifest ${displayVersion(previousDepositVersion)}` +
+        ` -> content ${displayVersion(contentVersion)}`);
+}
+async function readDryRunVersions(projectDir, seams = {}) {
+    const deftDir = join(resolve(projectDir), CANONICAL_INSTALL_ROOT);
+    const resolveContent = seams.resolveContentRoot ?? resolveInstalledContentRoot;
+    const readPackageVersion = seams.readPackageVersion ?? readCorePackageVersion;
+    const contentRoot = await resolveContent();
+    return {
+        previousVersion: readRecordedDepositVersion(deftDir),
+        contentVersion: readContentPackageVersion(contentRoot, readPackageVersion),
+    };
+}
 export function buildUpdateSummaryJson(input) {
     const { result, options, updateState, readiness } = input;
     return {
@@ -363,6 +395,8 @@ export function buildUpdateSummaryJson(input) {
         dirty_tree: false,
         dirty_files: [],
         staged_paths: result.stagedPaths,
+        mutations: mutationSummaryJson(result.mutations),
+        prettier_sensitive_rewrites: prettierSensitiveRewrites(result.mutations),
         backup_path: "",
         previous_version: result.previousDepositVersion ?? "",
         content_version: result.contentVersion,
@@ -370,6 +404,19 @@ export function buildUpdateSummaryJson(input) {
         agents_md_updated: result.agentsMdUpdated,
     };
 }
+/** Consumer-owned prefixes whose rewrite can fail a repo Prettier/fmt gate (#3395). */
+export const PRETTIER_SENSITIVE_CONSUMER_PREFIXES = ["xbrief/schemas/"];
+export const PRETTIER_SENSITIVE_FMT_HINT = "run `task fmt` or your repo formatter before the upgrade PR";
+/** Ledger `wrote` paths under prettier-sensitive consumer-owned prefixes. */
+export function prettierSensitiveRewrites(summary) {
+    return summary.wrote.filter((path) => PRETTIER_SENSITIVE_CONSUMER_PREFIXES.some((prefix) => path === prefix.slice(0, -1) || path.startsWith(prefix)));
+}
+export function formatPrettierSensitiveAnnounce(paths) {
+    if (paths.length === 0)
+        return "";
+    return (`Rewritten consumer-owned paths (${PRETTIER_SENSITIVE_FMT_HINT}):\n` +
+        paths.map((path) => `  ${path}\n`).join(""));
+}
 export function printUpdateComplete(result, io, updateState) {
     io.printf(result.alreadyCurrent
         ? "\nOK Deft framework payload already current.\n\n"
@@ -384,11 +431,22 @@ export function printUpdateComplete(result, io, updateState) {
     if (result.versionSkewNotice) {
         io.printf(`\n${result.versionSkewNotice}\n`);
     }
+    const mutationText = formatMutationSummary(result.mutations);
+    if (mutationText.length > 0) {
+        io.printf(`\n${mutationText}`);
+    }
+    const prettierText = formatPrettierSensitiveAnnounce(prettierSensitiveRewrites(result.mutations));
+    if (prettierText.length > 0) {
+        io.printf(`\n${prettierText}`);
+    }
     printMigrateNudgeIfNeeded(result.projectDir, io);
     io.printf("\n");
 }
 export async function runRefreshDeposit(args, io, seams = {}) {
     const projectDir = resolve(args.projectDir);
+    if (activeMutationLedger() === undefined) {
+        return runWithMutationLedger(projectDir, () => runRefreshDeposit(args, io, seams));
+    }
     const deftDir = join(projectDir, CANONICAL_INSTALL_ROOT);
     // #1912: refuse a legacy on-disk layout BEFORE any refresh. The npm CLI never
     // migrates -- the frozen Go bridge does (stage 1), then the npm path (stage 2).
@@ -545,6 +603,7 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         const stagedResult = depositStagePaths(projectDir, {
             includeTaskfile: taskfileWired,
             includeCore: !alreadyCurrent,
+            printf: (text) => io.printf(text),
         });
         stagedPaths = stagedResult.stagedPaths;
         if (!alreadyCurrent) {
@@ -552,7 +611,7 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         }
         else if (stagedResult.stagedPaths.length > 0) {
             io.printf("\nUpdated installer-managed projections for the current framework deposit:\n");
-            io.printf(`  git add ${stagedResult.stagedPaths.join(" ")}\n`);
+            io.printf(`  git add -- ${stagedResult.stagedPaths.join(" ")}\n`);
         }
     }
     printRefreshSideEffects(io, { ...effects, payloadSwapped: !alreadyCurrent });
@@ -572,6 +631,7 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         legacyLayout: false,
         taskfileWired,
         stagedPaths,
+        mutations: snapshotMutationSummary(),
     };
 }
 function buildRefusalJson(state, projectDir, message, command) {
@@ -602,10 +662,24 @@ function emitMigrationRequired(options, io, projectDir, classification) {
     }
     return UPDATE_REFUSED_EXIT_CODE;
 }
-/** Emit the classified plan for `--dry-run`/`--plan` without executing the refresh. */
-function emitDryRunPlan(options, io, projectDir, classification) {
+/**
+ * Dest effects the port cannot yet capture (ADR-004 condition 3).
+ * Shrink as sites fold; never drop the printed label.
+ */
+export const UPDATE_DRY_RUN_EXCLUSIONS = ["openclaw-home-skills"];
+export const UPDATE_DRY_RUN_EXCLUSIONS_LABEL = "Excluded from dest plan (not yet captured by the port): OpenClaw $HOME skills.";
+/** Emit the classified plan plus recorded port dest mutations (ADR-004). */
+async function emitDryRunPlan(options, io, projectDir, classification) {
+    const { previousVersion, contentVersion } = await readDryRunVersions(projectDir, options.seams ?? {});
+    const refreshPending = depositRefreshPending(previousVersion, contentVersion);
+    const skewHeadline = buildDepositVersionSkewHeadline(previousVersion, contentVersion);
     const { state, plan: resolutionPlan } = classification;
-    io.printf(`\n[deft update] dry-run -- classified plan (no changes written):\n`);
+    const silentIo = { printf: () => undefined };
+    const result = await runInPortRecordMode(() => runRefreshDeposit(options, silentIo, options.seams ?? {}));
+    if (skewHeadline) {
+        io.printf(`${skewHeadline}\n`);
+    }
+    io.printf(`\n[deft update] dry-run -- dest plan (recorded port calls, no changes written):\n`);
     io.printf(`  State        : ${state}\n`);
     io.printf(`  Mode         : ${resolutionPlan.mode}\n`);
     io.printf(`  Root cause   : ${resolutionPlan.nextAction.rootCause}\n`);
@@ -613,6 +687,14 @@ function emitDryRunPlan(options, io, projectDir, classification) {
     for (const warning of resolutionPlan.warnings) {
         io.printf(`  Warning      : ${warning}\n`);
     }
+    const mutationText = formatMutationSummary(result.mutations);
+    if (mutationText.length > 0) {
+        io.printf(`\n${mutationText}`);
+    }
+    else {
+        io.printf(`\nNo dest mutations recorded.\n`);
+    }
+    io.printf(`\n${UPDATE_DRY_RUN_EXCLUSIONS_LABEL}\n`);
     if (options.jsonOut) {
         options.writeOut(`${JSON.stringify({
             success: true,
@@ -621,8 +703,13 @@ function emitDryRunPlan(options, io, projectDir, classification) {
             update_state: state,
             mode: resolutionPlan.mode,
             project_dir: projectDir,
+            previous_version: previousVersion ?? "",
+            content_version: contentVersion,
+            deposit_refresh_pending: refreshPending,
             next_action: resolutionPlan.nextAction,
             warnings: resolutionPlan.warnings,
+            mutations: mutationSummaryJson(result.mutations),
+            exclusions: [...UPDATE_DRY_RUN_EXCLUSIONS],
         }, null, 2)}\n`);
     }
     return 0;
@@ -678,7 +765,17 @@ export async function runRefreshDepositCli(options) {
             return emitMigrationRequired(options, io, projectDir, classification);
         }
         if (options.dryRun) {
-            return emitDryRunPlan(options, io, projectDir, classification);
+            try {
+                return await emitDryRunPlan(options, io, projectDir, classification);
+            }
+            catch (cause) {
+                const message = cause instanceof Error ? cause.message : String(cause);
+                options.writeErr(`directive update: ${message}\n`);
+                if (options.jsonOut) {
+                    options.writeOut(`${JSON.stringify({ success: false, error: message, error_code: "refresh_deposit_failed" }, null, 2)}\n`);
+                }
+                return 1;
+            }
         }
         // #2266 a3: self-heal a mismatched / unreachable engine via the keystone
         // global-first ladder before the refresh proceeds.

package/dist/init-deposit/scaffold.js

@@ -5,15 +5,17 @@
  * Refs #1942, #1430, #1463, #1179.
  */
 import { execFileSync } from "node:child_process";
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
-import { mkdir, readdir, rm, stat } from "node:fs/promises";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
 import { platform } from "node:os";
 import { join, relative, resolve } from "node:path";
-import { containedWrite } from "../fs/contained-write.js";
+import { containedChmod, containedDestExec, containedMkdir, containedRemove, containedWrite, } from "../fs/contained-write.js";
 import { assertDestinationNotSymlink, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { agentsRefreshPlan } from "../platform/agents-md.js";
+import { renderCoreGuardBranchSyncIfBlock } from "../policy/branch-sync.js";
 import { MIGRATED_ARTIFACT_DIR } from "../xbrief-migrate/constants.js";
 import { CANONICAL_INSTALL_ROOT } from "./constants.js";
+import { CORE_GUARD_PIN_CONTENT_PYTHON } from "./core-guard-pin-content.js";
 import { assertInstallerAllowlistHonors1430, installerManagedGuardErePatterns } from "./hygiene.js";
 import { writeAgentsSkillsFromInventory } from "./skill-discovery-deposit.js";
 import { syncConsumerXbriefSchemas } from "./xbrief-projections.js";
@@ -204,7 +206,7 @@ export function writeAgentsMd(projectDir, deftDir, io) {
 async function ensureVbriefLifecycleDirs(projectDir) {
     for (const sub of VBRIEF_LIFECYCLE_DIRS) {
         const dir = projectionTarget(projectDir, MIGRATED_ARTIFACT_DIR, sub);
-        await mkdir(dir, { recursive: true, mode: 0o755 });
+        containedMkdir({ root: projectDir, target: dir });
         const gitkeep = join(dir, ".gitkeep");
         try {
             await stat(gitkeep);
@@ -243,11 +245,11 @@ export async function writeConsumerVbrief(projectDir, deftDir, io) {
             : "vbrief/ already present at project root — skipping.\n");
         return schemasChanged;
     }
-    mkdirSync(consumerVbrief, { recursive: true });
+    containedMkdir({ root: projectDir, target: consumerVbrief });
     if (!vbriefMdPresent) {
         const fwVbriefMd = join(deftDir, "vbrief", "vbrief.md");
         if (existsSync(fwVbriefMd)) {
-            copyFileSync(fwVbriefMd, vbriefMdDst);
+            containedProjectWrite(projectDir, vbriefMdDst, readFileSync(fwVbriefMd));
         }
         else {
             containedProjectWrite(projectDir, vbriefMdDst, VBRIEF_README_BODY);
@@ -373,7 +375,7 @@ export function writeConsumerGitHooks(projectDir, deftDir, io, seams = {}) {
             try {
                 const mode = statSync(dst).mode & 0o777;
                 if ((mode & 0o111) === 0) {
-                    chmodSync(dst, HOOK_FILE_MODE);
+                    containedChmod({ root: projectDir, target: dst, mode: HOOK_FILE_MODE });
                     filesDeposited = true;
                 }
             }
@@ -394,15 +396,12 @@ export function writeConsumerGitHooks(projectDir, deftDir, io, seams = {}) {
             }
         });
     const setHooksPath = seams.setHooksPath ??
-        ((dir, value) => {
-            try {
-                execFileSync("git", ["-C", dir, "config", "core.hooksPath", value], { encoding: "utf8" });
-                return true;
-            }
-            catch {
-                return false;
-            }
-        });
+        ((dir, value) => containedDestExec({
+            root: dir,
+            destTarget: join(".git", "config"),
+            file: "git",
+            args: ["-C", dir, "config", "core.hooksPath", value],
+        }).ok);
     const target = ".githooks";
     const current = getHooksPath(projectDir) ?? "";
     let configWired = false;
@@ -550,274 +549,20 @@ export function assertCoreGuardWorkflowLoadable(content) {
 }
 /**
  * Embedded python3 content check for package.json / lockfiles when co-travelling
- * with .deft/core/** (#3193). Mirrors TS `isUpgradePinPathContentAllowed`.
+ * with .deft/core/** (#3193 / #3427). Mirrors TS `isUpgradePinPathContentAllowed`.
  * Uses a single-quoted heredoc so GHA does not interpolate shell variables
- * inside the Python source (BASE/HEAD are argv).
+ * inside the Python source (BASE/HEAD are argv). Body is
+ * {@link CORE_GUARD_PIN_CONTENT_PYTHON} (twin of the Go embed).
  *
  * Every emitted line is indented to {@link CORE_GUARD_RUN_INDENT} so the YAML
  * `run: |` block stays intact (#3345). After GHA strips the common indent, the
  * shell heredoc body reaches python3 with correct relative indentation.
  */
 function coreGuardPinContentPython() {
-    // Keep this compact: deposited into every consumer workflow on init/update.
-    const pyBody = [
-        "import json, re, subprocess, sys",
-        "base_sha, head_sha = sys.argv[1], sys.argv[2]",
-        "def git_show(sha, path):",
-        "    try:",
-        "        return subprocess.check_output(['git','show',f'{sha}:{path}'], text=True, stderr=subprocess.DEVNULL)",
-        "    except subprocess.CalledProcessError:",
-        "        return ''",
-        "def changed_names():",
-        "    out = subprocess.check_output(['git','diff','--name-only',base_sha,head_sha], text=True)",
-        "    return [p for p in out.splitlines() if p]",
-        "def is_dir_key(n):",
-        "    return n.startswith('@deftai/directive')",
-        "DEP_FIELDS = ('dependencies','devDependencies','optionalDependencies','peerDependencies')",
-        "def deep_eq(a,b):",
-        "    if a is b: return True",
-        "    if type(a) is not type(b): return False",
-        "    if isinstance(a, dict):",
-        "        if set(a) != set(b): return False",
-        "        return all(deep_eq(a[k], b[k]) for k in a)",
-        "    if isinstance(a, list):",
-        "        return len(a)==len(b) and all(deep_eq(x,y) for x,y in zip(a,b))",
-        "    return a == b",
-        "def strip_pins(obj):",
-        "    if not isinstance(obj, dict): return obj",
-        "    out = {}",
-        "    for k,v in obj.items():",
-        "        if k in DEP_FIELDS and isinstance(v, dict):",
-        "            out[k] = {dk:dv for dk,dv in v.items() if not is_dir_key(dk)}",
-        "        else:",
-        "            out[k] = v",
-        "    return out",
-        "def pkg_pin_only(base, head):",
-        "    try:",
-        "        b, h = json.loads(base or '{}'), json.loads(head or '{}')",
-        "    except json.JSONDecodeError:",
-        "        return False",
-        "    return deep_eq(strip_pins(b), strip_pins(h))",
-        "def collect_deps(pkg):",
-        "    out = {}",
-        "    if not isinstance(pkg, dict): return out",
-        "    for f in DEP_FIELDS:",
-        "        block = pkg.get(f)",
-        "        if isinstance(block, dict):",
-        "            for k,v in block.items():",
-        "                if isinstance(v, str): out[k]=v",
-        "                elif isinstance(v, dict) and isinstance(v.get('version'), str): out[k]=v['version']",
-        "                elif v is not None: out[k]=str(v)",
-        "    return out",
-        "def only_dir_diff(bd, hd):",
-        "    keys = set(bd)|set(hd)",
-        "    for k in keys:",
-        "        if is_dir_key(k): continue",
-        "        if bd.get(k) != hd.get(k): return False",
-        "    return True",
-        "def npm_root_deps(lock):",
-        "    pkgs = lock.get('packages') if isinstance(lock, dict) else None",
-        "    if isinstance(pkgs, dict) and isinstance(pkgs.get(''), dict):",
-        "        return collect_deps(pkgs[''])",
-        "    deps = lock.get('dependencies') if isinstance(lock, dict) else None",
-        "    out = {}",
-        "    if isinstance(deps, dict):",
-        "        for k,v in deps.items():",
-        "            if isinstance(v, dict): out[k]=str(v.get('version', v))",
-        "            elif isinstance(v, str): out[k]=v",
-        "    return out",
-        "def npm_lock_ok(base, head):",
-        "    try:",
-        "        b, h = json.loads(base or '{}'), json.loads(head or '{}')",
-        "    except json.JSONDecodeError:",
-        "        return False",
-        "    br, hr = npm_root_deps(b), npm_root_deps(h)",
-        "    if not only_dir_diff(br, hr): return False",
-        "    bp, hp = b.get('packages') or {}, h.get('packages') or {}",
-        "    if not isinstance(bp, dict): bp = {}",
-        "    if not isinstance(hp, dict): hp = {}",
-        "    all_keys = set(bp)|set(hp)",
-        "    for key in all_keys:",
-        "        if key == '': continue",
-        "        if 'node_modules/@deftai/directive' in key or '/@deftai/directive/' in key: continue",
-        "        if not deep_eq(bp.get(key), hp.get(key)): return False",
-        "    if not bp and not hp:",
-        "        def strip_dir(v):",
-        "            if not isinstance(v, dict): return v",
-        "            out = {}",
-        "            for k, val in v.items():",
-        "                if is_dir_key(k): continue",
-        "                if isinstance(val, dict):",
-        "                    nxt = dict(val)",
-        "                    if 'dependencies' in val: nxt['dependencies'] = strip_dir(val['dependencies'])",
-        "                    out[k] = nxt",
-        "                else: out[k] = val",
-        "            return out",
-        "        if not deep_eq(strip_dir(b.get('dependencies')), strip_dir(h.get('dependencies'))): return False",
-        "    return True",
-        "def pnpm_root_deps(raw):",
-        "    out = {}",
-        "    in_imp = in_root = in_dep = False",
-        "    cur = None",
-        "    def unq(s):",
-        "        s=s.strip()",
-        '        if len(s)>=2 and s[0]==s[-1] and s[0] in "\'\\"": return s[1:-1]',
-        "        return s",
-        "    for line in raw.splitlines():",
-        "        if re.match(r'^importers:\\s*$', line):",
-        "            in_imp, in_root, in_dep, cur = True, False, False, None",
-        "            continue",
-        "        if not in_imp: continue",
-        "        if re.match(r'^[^\\s#]', line) and not line.startswith('importers'):",
-        "            break",
-        '        if re.match(r"^ {2}(?:\\.|\'\\.\'|\\"\\.\\"):\\s*$", line):',
-        "            in_root, in_dep, cur = True, False, None",
-        "            continue",
-        "        if in_root and re.match(r'^ {2}\\S', line) and not re.match(r'^ {2}\\.', line):",
-        "            in_root, in_dep, cur = False, False, None",
-        "            continue",
-        "        if not in_root: continue",
-        "        if re.match(r'^ {4}(?:dependencies|devDependencies|optionalDependencies|peerDependencies):\\s*$', line):",
-        "            in_dep, cur = True, None",
-        "            continue",
-        "        if in_dep and re.match(r'^ {4}\\S', line):",
-        "            in_dep, cur = False, None",
-        "            continue",
-        "        if not in_dep: continue",
-        "        m = re.match(r'^ {6}(.+?):\\s*$', line)",
-        "        if m:",
-        "            cur = unq(m.group(1)); continue",
-        "        if cur:",
-        "            vm = re.match(r'^ {8}version:\\s*(.+?)\\s*$', line)",
-        "            if vm:",
-        "                out[cur] = unq(vm.group(1)); cur = None",
-        "    return out",
-        "def pnpm_packages_by_name(raw):",
-        "    blocks, out = {}, {}",
-        "    in_pkg, cur, buf = False, None, []",
-        "    def flush():",
-        "        nonlocal cur, buf",
-        "        if cur is None: return",
-        "        blocks.setdefault(cur, []).append('\\n'.join(buf))",
-        "        cur, buf = None, []",
-        "    def unq(s):",
-        "        s=s.strip()",
-        '        if len(s)>=2 and s[0]==s[-1] and s[0] in "\'\\"": return s[1:-1]',
-        "        return s",
-        "    for line in raw.splitlines():",
-        "        if re.match(r'^packages:\\s*$', line):",
-        "            flush(); in_pkg = True; continue",
-        "        if not in_pkg: continue",
-        "        if re.match(r'^[^\\s#]', line) and not line.startswith('packages'):",
-        "            flush(); break",
-        "        m = re.match(r'^ {2}(.+?):\\s*$', line)",
-        "        if m:",
-        "            flush()",
-        "            key = unq(m.group(1))",
-        "            at = key.find('@', 1) if key.startswith('@') else key.find('@')",
-        "            cur = key[:at] if at > 0 else key",
-        "            buf = [line]; continue",
-        "        if cur is not None: buf.append(line)",
-        "    flush()",
-        "    for name, blist in blocks.items():",
-        "        out[name] = '\\n---\\n'.join(sorted(blist))",
-        "    return out",
-        "def pnpm_section_by_name(raw, section):",
-        "    blocks, out = {}, {}",
-        "    in_sec, cur, buf = False, None, []",
-        "    sec_re = re.compile(r'^' + re.escape(section) + r':\\s*$')",
-        "    def flush():",
-        "        nonlocal cur, buf",
-        "        if cur is None: return",
-        "        blocks.setdefault(cur, []).append('\\n'.join(buf))",
-        "        cur, buf = None, []",
-        "    def unq(s):",
-        "        s=s.strip()",
-        '        if len(s)>=2 and s[0]==s[-1] and s[0] in "\'\\"": return s[1:-1]',
-        "        return s",
-        "    for line in raw.splitlines():",
-        "        if sec_re.match(line):",
-        "            flush(); in_sec = True; continue",
-        "        if not in_sec: continue",
-        "        if re.match(r'^[^\\s#]', line) and not line.startswith(section):",
-        "            flush(); break",
-        "        m = re.match(r'^ {2}(.+?):\\s*$', line)",
-        "        if m:",
-        "            flush()",
-        "            key = unq(m.group(1))",
-        "            at = key.find('@', 1) if key.startswith('@') else key.find('@')",
-        "            cur = key[:at] if at > 0 else key",
-        "            buf = [line]; continue",
-        "        if cur is not None: buf.append(line)",
-        "    flush()",
-        "    for name, blist in blocks.items():",
-        "        out[name] = '\\n---\\n'.join(sorted(blist))",
-        "    return out",
-        "def pnpm_ok(base, head):",
-        "    br, hr = pnpm_root_deps(base), pnpm_root_deps(head)",
-        "    if not only_dir_diff(br, hr): return False",
-        "    for section in ('packages', 'snapshots'):",
-        "        bp, hp = pnpm_section_by_name(base, section), pnpm_section_by_name(head, section)",
-        "        for name in set(bp)|set(hp):",
-        "            if is_dir_key(name): continue",
-        "            if bp.get(name) != hp.get(name): return False",
-        "    return True",
-        "def yarn_blocks(raw):",
-        "    blocks = {}",
-        "    names, buf = [], []",
-        "    def flush():",
-        "        nonlocal names, buf",
-        "        if not names: return",
-        "        body = '\\n'.join(buf)",
-        "        for n in names: blocks[n] = body",
-        "        names, buf = [], []",
-        "    for line in raw.splitlines():",
-        "        if line == '' or line.startswith('#'):",
-        "            if names and line == '': flush()",
-        "            continue",
-        "        if not re.match(r'^\\s', line) and line.endswith(':'):",
-        "            flush()",
-        "            header = line[:-1]",
-        "            names = []",
-        "            for part in header.split(','):",
-        "                p = part.strip()",
-        '                if len(p)>=2 and p[0]==p[-1] and p[0] in "\'\\"": p = p[1:-1]',
-        "                at = p.find('@', 1) if p.startswith('@') else p.find('@')",
-        "                names.append(p[:at] if at > 0 else p)",
-        "            buf = [line]",
-        "            continue",
-        "        if names: buf.append(line)",
-        "    flush()",
-        "    return blocks",
-        "def yarn_ok(base, head):",
-        "    bb, hb = yarn_blocks(base), yarn_blocks(head)",
-        "    for name in set(bb)|set(hb):",
-        "        if is_dir_key(name): continue",
-        "        if bb.get(name) != hb.get(name): return False",
-        "    return True",
-        "paths = changed_names()",
-        "core = [p for p in paths if p == '.deft/core' or p.startswith('.deft/core/')]",
-        "if not core:",
-        "    sys.exit(0)",
-        "checks = {",
-        "    'package.json': pkg_pin_only,",
-        "    'package-lock.json': npm_lock_ok,",
-        "    'pnpm-lock.yaml': pnpm_ok,",
-        "    'yarn.lock': yarn_ok,",
-        "}",
-        "bad = []",
-        "for path, fn in checks.items():",
-        "    if path not in paths: continue",
-        "    if not fn(git_show(base_sha, path), git_show(head_sha, path)):",
-        "        bad.append(path)",
-        "if bad:",
-        "    print('::error title=deft-core guard (#3193)::package/lock co-travel with .deft/core/** must be @deftai/directive* pin-only + lock follow-through. Rejected: ' + ', '.join(bad))",
-        "    print('--- content-rejected pin/lock paths ---')",
-        "    print('\\n'.join(bad))",
-        "    sys.exit(1)",
-        "print('OK: package/lock content is Directive pin unit (#3193).')",
-    ];
+    // Shared SoT with cmd/deft-install/core_guard_pin_content.embed (#3427).
+    // Consumer deposit stays a python3 heredoc; this repo has no .py file.
     const run = CORE_GUARD_RUN_INDENT;
+    const pyBody = CORE_GUARD_PIN_CONTENT_PYTHON.replace(/\n$/, "").split("\n");
     return [
         `${run}python3 - "$BASE_SHA" "$HEAD_SHA" <<'PY'`,
         ...pyBody.map((line) => `${run}${line}`),
@@ -848,8 +593,9 @@ function coreGuardWorkflowContent() {
     assertInstallerAllowlistHonors1430();
     const baseSha = githubActionsExpr("github.event.pull_request.base.sha");
     const headSha = githubActionsExpr("github.event.pull_request.head.sha");
+    const baseRef = githubActionsExpr("github.event.pull_request.base.ref");
     return ("name: deft-core-guard\n\n" +
-        "# Deft framework guard (#1430 / #3127 / #3193 / #3345): a single PR should not mix changes to the\n" +
+        "# Deft framework guard (#1430 / #3127 / #3193 / #3345 / #3388): a single PR should not mix changes to the\n" +
         "# vendored framework payload (.deft/core/**) with true application/product files.\n" +
         "# One upgrade PR MAY include deposit + installer-managed paths + package.json pin/lock\n" +
         "# + .deft/GENERATION.json when package.json is @deftai/directive* dependency-key pin-only\n" +
@@ -871,6 +617,7 @@ function coreGuardWorkflowContent() {
         "        env:\n" +
         `          BASE_SHA: ${baseSha}\n` +
         `          HEAD_SHA: ${headSha}\n` +
+        `          BASE_REF: ${baseRef}\n` +
         "        run: |\n" +
         "          set -eu\n" +
         '          changed=$(git diff --name-only "$BASE_SHA" "$HEAD_SHA")\n' +
@@ -879,6 +626,8 @@ function coreGuardWorkflowContent() {
         "          core=$(printf '%s\\n' \"$changed\" | grep -E '^\\.deft/core/' || true)\n" +
         `${coreGuardAllowlistShell()}\n` +
         '          if [ -n "$core" ] && [ -n "$app" ]; then\n' +
+        "            # Evidence-based branch-sync exemption (#3388). Not name-only.\n" +
+        `${renderCoreGuardBranchSyncIfBlock(CORE_GUARD_RUN_INDENT)}\n` +
         '            echo "::error title=deft-core guard (#1430)::This PR changes the vendored framework payload (.deft/core/**) AND non-framework files. Split the framework update into its own PR."\n' +
         '            echo "--- framework (.deft/core/**) changes ---"; printf \'%s\\n\' "$core"\n' +
         '            echo "--- non-framework changes ---"; printf \'%s\\n\' "$app"\n' +
@@ -1053,7 +802,7 @@ export async function pruneFrameworkSelfTests(projectDir, io) {
     catch {
         return false;
     }
-    await rm(path, { recursive: true, force: true });
+    containedRemove({ root: projectDir, target: path, recursive: true });
     io.printf(`Removed vendored framework self-tests (${FRAMEWORK_SELF_TEST_REL}) from the consumer deposit (#1474).\n`);
     return true;
 }
@@ -1074,7 +823,7 @@ export async function pruneVendoredTsTests(projectDir, io) {
                 await walk(full);
             }
             else if (entry.isFile() && VENDORED_TS_TEST_RE.test(entry.name)) {
-                await rm(full, { force: true });
+                containedRemove({ root: projectDir, target: full });
                 removed += 1;
             }
         }