@deftai/directive-core 0.87.0 → 0.88.0

package/dist/hooks/dispatcher.js

@@ -1,15 +1,16 @@
 import { realpathSync } from "node:fs";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { hasArtifactSuffix } from "../layout/resolve.js";
-import { evaluateRuntimeAuthorityDirectWrite, loadRuntimeAuthorityFromProject, } from "../policy/runtime-authority.js";
+import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, } from "../policy/no-deft-directive.js";
+import { classifyMcpTool, evaluateRuntimeAuthorityDirectWrite, evaluateRuntimeAuthorityShellOp, listShellOps, loadRuntimeAuthorityFromProject, } from "../policy/runtime-authority.js";
 import { markRitualStaleAfterCompact } from "../session/ritual-sentinel.js";
 import { runSessionStartHookWrite } from "../session/session-start-hook.js";
 import { inspectSessionRitual } from "../session/verify-session-ritual.js";
 import { isExploreSpawn, isReadOnlyHookContext } from "./readonly.js";
 import { inspectActiveScope } from "./scope.js";
-import { isDirectWriteTool, isSpawnTool } from "./tools.js";
+import { isDirectWriteTool, isMcpTool, isShellTool, isSpawnTool } from "./tools.js";
 export { hookReadOnlyFromPayload, isExploreSpawn, isReadOnlyHookContext } from "./readonly.js";
-export { DIRECT_WRITE_HOOK_MATCHER, DIRECT_WRITE_TOOL_NAMES, isDirectWriteTool, isSpawnTool, READ_ONLY_HOOK_ENV, SPAWN_HOOK_MATCHER, SPAWN_TOOL_NAMES, } from "./tools.js";
+export { DIRECT_WRITE_HOOK_MATCHER, DIRECT_WRITE_TOOL_NAMES, isDirectWriteTool, isMcpTool, isShellTool, isSpawnTool, MCP_HOOK_MATCHER, MCP_PUSH_MERGE_BARE_NAMES, READ_ONLY_HOOK_ENV, SHELL_HOOK_MATCHER, SHELL_TOOL_NAMES, SPAWN_HOOK_MATCHER, SPAWN_TOOL_NAMES, } from "./tools.js";
 export const HOOK_HOSTS = ["claude", "grok", "cursor", "codex"];
 export const HOOK_EVENTS = ["session.start", "session.compact", "tool.before"];
 /** Hosts that receive compact/resume hook deposits via init/update (#2113). */
@@ -21,7 +22,8 @@ function record(value) {
         ? value
         : null;
 }
-function firstString(...values) {
+/** First non-empty trimmed string from candidates (array form — clear arity for static tools). */
+function firstString(values) {
     for (const value of values) {
         if (typeof value === "string" && value.trim().length > 0)
             return value.trim();
@@ -138,7 +140,14 @@ export function hookWriteTargetPath(payload) {
     if (input === null)
         return null;
     const toolInput = toolInputRecord(input);
-    return firstString(toolInput?.file_path, toolInput?.filePath, toolInput?.path, input.file_path, input.filePath, input.path);
+    return firstString([
+        toolInput?.file_path,
+        toolInput?.filePath,
+        toolInput?.path,
+        input.file_path,
+        input.filePath,
+        input.path,
+    ]);
 }
 /** POSIX-ish project-relative path for lifecycle matching. */
 export function toProjectRelativePosix(projectRoot, targetPath) {
@@ -305,6 +314,113 @@ function runtimeAuthorityForDirectWrite(input, toolName, seams, scopePath) {
         return null;
     return deny(input, verdict.code ?? "runtime-policy-deny-path", toolName, verdict.reason ?? "Directive denied this direct write under runtime authority policy.", scopePath);
 }
+/**
+ * Best-effort shell command string from host PreToolUse payloads (#2711).
+ * Hosts disagree on nesting (`tool_input.command` vs top-level `command`).
+ */
+export function hookShellCommand(payload) {
+    const input = record(payload);
+    if (input === null)
+        return null;
+    const toolInput = toolInputRecord(input);
+    return firstString([
+        toolInput !== null ? toolInput.command : null,
+        toolInput !== null ? toolInput.cmd : null,
+        toolInput !== null ? toolInput.shell_command : null,
+        input.command,
+        input.cmd,
+    ]);
+}
+/** Serialize tool args for MCP classification when nested objects are present (#2711). */
+function hookMcpArgsText(payload) {
+    const input = record(payload);
+    if (input === null)
+        return null;
+    const toolInput = toolInputRecord(input);
+    if (toolInput === null)
+        return null;
+    try {
+        return JSON.stringify(toolInput);
+    }
+    catch {
+        return null;
+    }
+}
+function loadRuntimeAuthorityPolicySafe(input, seams) {
+    const projectRoot = resolve(input.projectRoot);
+    try {
+        return (seams.loadRuntimeAuthority ?? loadRuntimeAuthorityFromProject)(projectRoot);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Evaluate scopes.push / scopes.merge for Shell/Bash or classifiable MCP tools (#2711).
+ * Returns a full HookDecision (allow or deny). Unclassifiable ops fail open.
+ */
+function decideShellOrMcpRuntimeAuthority(input, toolName, seams) {
+    const projectRoot = resolve(input.projectRoot);
+    const policy = loadRuntimeAuthorityPolicySafe(input, seams);
+    if (policy === null) {
+        return {
+            verdict: "allow",
+            code: "shell-op-unclassifiable",
+            event: input.event,
+            host: input.host,
+            toolName,
+            projectRoot,
+            message: `Directive allowed ${toolName}: runtimeAuthority policy load failed (fail open).`,
+            scopePath: null,
+        };
+    }
+    // Shell: evaluate every classifiable op in compound/multi-line commands (#2711 Greptile).
+    // MCP / bare push-merge names: single tool name maps to at most one op
+    // (includes bare `merge_pull_request` etc. that isMcpTool does not flag).
+    const ops = [];
+    if (isShellTool(toolName)) {
+        const command = hookShellCommand(input.payload);
+        if (command !== null)
+            ops.push(...listShellOps(command));
+    }
+    else {
+        const mcpOp = classifyMcpTool(toolName, hookMcpArgsText(input.payload));
+        if (mcpOp !== null)
+            ops.push(mcpOp);
+    }
+    if (ops.length === 0) {
+        return {
+            verdict: "allow",
+            code: "shell-op-unclassifiable",
+            event: input.event,
+            host: input.host,
+            toolName,
+            projectRoot,
+            message: `${toolName} is classifiable as Shell/MCP but the command/tool was not recognized as ` +
+                "push or merge — fail open (host gap; see runtime-authority.md).",
+            scopePath: null,
+        };
+    }
+    // Deny if any classifiable op is out of scope (compound commands must not short-circuit).
+    for (const op of ops) {
+        const verdict = evaluateRuntimeAuthorityShellOp({ policy, op });
+        if (!verdict.allowed) {
+            return deny(input, verdict.code ?? "runtime-policy-deny-scope", toolName, verdict.reason ??
+                "Directive denied this shell/MCP operation under runtime authority policy.");
+        }
+    }
+    const opsLabel = ops.join("+");
+    return {
+        verdict: "allow",
+        code: "shell-op-ready",
+        event: input.event,
+        host: input.host,
+        toolName,
+        projectRoot,
+        message: `Directive runtimeAuthority allowed classifiable ${opsLabel} via ${toolName}.`,
+        scopePath: null,
+    };
+}
 function inspectMutationGates(input, toolName, seams, options) {
     const projectRoot = resolve(input.projectRoot);
     let ritual;
@@ -431,6 +547,24 @@ export function decideHook(input, seams = {}) {
         }
     }
     if (input.event === "session.start") {
+        // #2926: root `.no-deft-directive` wins — skip host SessionStart bookkeeping.
+        const detectOptOut = seams.detectNoDeftDirective ?? detectNoDeftDirective;
+        const optOut = detectOptOut(projectRoot);
+        if (optOut.present) {
+            const message = optOut.inconsistent
+                ? `${NO_DEFT_DIRECTIVE_DISABLED_MESSAGE}. ${NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE}`
+                : NO_DEFT_DIRECTIVE_DISABLED_MESSAGE;
+            return {
+                verdict: "allow",
+                code: "session-start-disabled",
+                event: input.event,
+                host: input.host,
+                toolName: null,
+                projectRoot,
+                message,
+                scopePath: null,
+            };
+        }
         try {
             const result = (seams.sessionStart ?? runSessionStartHookWrite)(projectRoot);
             if (result.code !== 0) {
@@ -510,6 +644,15 @@ export function decideHook(input, seams = {}) {
         }
         return inspectMutationGates(input, toolName, seams, { proposedLifecycleExempt: false });
     }
+    // Shell/Bash and classifiable MCP: enforce scopes.push / scopes.merge (#2711).
+    // Route bare push/merge MCP names (merge_pull_request, git_push, …) even when
+    // isMcpTool is false — classifyMcpTool is the gate (dispatcher-side, no tools↔policy cycle).
+    // Does not require active-scope ritual — only runtimeAuthority when enabled.
+    if (isShellTool(toolName) ||
+        isMcpTool(toolName) ||
+        classifyMcpTool(toolName, hookMcpArgsText(input.payload)) !== null) {
+        return decideShellOrMcpRuntimeAuthority(input, toolName, seams);
+    }
     if (!isDirectWriteTool(toolName)) {
         return {
             verdict: "allow",
@@ -518,7 +661,7 @@ export function decideHook(input, seams = {}) {
             host: input.host,
             toolName,
             projectRoot,
-            message: `${toolName} is outside the P0 direct-write/spawn enforcement slice.`,
+            message: `${toolName} is outside the P0 direct-write/spawn/shell enforcement slice.`,
             scopePath: null,
         };
     }

package/dist/hooks/tools.d.ts

@@ -2,10 +2,41 @@
 export declare const DIRECT_WRITE_TOOL_NAMES: readonly ["Edit", "Write", "WriteFile", "CreateFile", "MultiEdit", "NotebookEdit", "StrReplace", "SearchReplace", "Delete", "DeleteFile", "ApplyPatch", "apply_patch"];
 /** PreToolUse spawn / sub-agent dispatch tools (#1185 / #2437). */
 export declare const SPAWN_TOOL_NAMES: readonly ["Task", "SubagentStart", "spawn_subagent", "start_agent", "CreateAgent"];
+/**
+ * Host spellings for Shell/Bash execution tools (#2711).
+ * Used for runtimeAuthority scopes.push / scopes.merge classification.
+ */
+export declare const SHELL_TOOL_NAMES: readonly ["Shell", "Bash", "BashTool", "shell", "bash"];
 /** Env override forcing hook-level read-only write denial (#1185). */
 export declare const READ_ONLY_HOOK_ENV = "DEFT_HOOK_READ_ONLY";
 export declare function isDirectWriteTool(toolName: string): boolean;
 export declare function isSpawnTool(toolName: string): boolean;
+/** True for host Shell/Bash-class tools that carry a command string (#2711). */
+export declare function isShellTool(toolName: string): boolean;
+/**
+ * Best-effort MCP tool detection for runtimeAuthority push/merge scopes (#2711).
+ * Host spellings vary (`mcp__*`, `server__tool`, bare MCP-looking names).
+ * Unclassifiable MCP tools fail open at the operation classifier.
+ *
+ * Bare push/merge names (e.g. `merge_pull_request`) are NOT detected here —
+ * they are classified by `classifyMcpTool` and routed from `decideHook` so
+ * tools.ts stays free of policy imports (#2711 Greptile conf holdout).
+ */
+export declare function isMcpTool(toolName: string): boolean;
+/**
+ * Bare tool names that hosts may emit without mcp__/server__ prefixes and that
+ * `classifyMcpTool` treats as push or merge (#2711).
+ * Keep in sync with classifyMcpTool name patterns (narrow list for PreToolUse matchers).
+ */
+export declare const MCP_PUSH_MERGE_BARE_NAMES: readonly ["merge_pull_request", "merge-pull-request", "pull_request_merge", "pull-request-merge", "merge_pr", "pr_merge", "pr-merge", "git_push", "git-push", "push_branch", "push-branch"];
 export declare const DIRECT_WRITE_HOOK_MATCHER: string;
 export declare const SPAWN_HOOK_MATCHER: string;
+export declare const SHELL_HOOK_MATCHER: string;
+/**
+ * PreToolUse matcher for MCP-class push/merge tools (#2711).
+ * Regex-friendly for Claude/nested hosts. Prefer broad install match +
+ * fail-open classify in the dispatcher over missing a classifiable push/merge
+ * tool name (e.g. `server__push_to_remote` via push+remote).
+ */
+export declare const MCP_HOOK_MATCHER: string;
 //# sourceMappingURL=tools.d.ts.map

package/dist/hooks/tools.js

@@ -21,6 +21,11 @@ export const SPAWN_TOOL_NAMES = [
     "start_agent",
     "CreateAgent",
 ];
+/**
+ * Host spellings for Shell/Bash execution tools (#2711).
+ * Used for runtimeAuthority scopes.push / scopes.merge classification.
+ */
+export const SHELL_TOOL_NAMES = ["Shell", "Bash", "BashTool", "shell", "bash"];
 /** Env override forcing hook-level read-only write denial (#1185). */
 export const READ_ONLY_HOOK_ENV = "DEFT_HOOK_READ_ONLY";
 function normalizedToolName(toolName) {
@@ -28,12 +33,81 @@ function normalizedToolName(toolName) {
 }
 const DIRECT_WRITE_TOOLS = new Set(DIRECT_WRITE_TOOL_NAMES.map(normalizedToolName));
 const SPAWN_TOOLS = new Set(SPAWN_TOOL_NAMES.map(normalizedToolName));
+const SHELL_TOOLS = new Set(SHELL_TOOL_NAMES.map(normalizedToolName));
 export function isDirectWriteTool(toolName) {
     return DIRECT_WRITE_TOOLS.has(normalizedToolName(toolName));
 }
 export function isSpawnTool(toolName) {
     return SPAWN_TOOLS.has(normalizedToolName(toolName));
 }
+/** True for host Shell/Bash-class tools that carry a command string (#2711). */
+export function isShellTool(toolName) {
+    return SHELL_TOOLS.has(normalizedToolName(toolName));
+}
+/**
+ * Best-effort MCP tool detection for runtimeAuthority push/merge scopes (#2711).
+ * Host spellings vary (`mcp__*`, `server__tool`, bare MCP-looking names).
+ * Unclassifiable MCP tools fail open at the operation classifier.
+ *
+ * Bare push/merge names (e.g. `merge_pull_request`) are NOT detected here —
+ * they are classified by `classifyMcpTool` and routed from `decideHook` so
+ * tools.ts stays free of policy imports (#2711 Greptile conf holdout).
+ */
+export function isMcpTool(toolName) {
+    const raw = toolName.trim();
+    if (raw.length === 0)
+        return false;
+    const lower = raw.toLowerCase();
+    if (lower.startsWith("mcp__") || lower.startsWith("mcp_"))
+        return true;
+    if (lower.includes("__") && !isDirectWriteTool(toolName) && !isShellTool(toolName)) {
+        // server__tool style used by some MCP bridges
+        return true;
+    }
+    return false;
+}
+/**
+ * Bare tool names that hosts may emit without mcp__/server__ prefixes and that
+ * `classifyMcpTool` treats as push or merge (#2711).
+ * Keep in sync with classifyMcpTool name patterns (narrow list for PreToolUse matchers).
+ */
+export const MCP_PUSH_MERGE_BARE_NAMES = [
+    "merge_pull_request",
+    "merge-pull-request",
+    "pull_request_merge",
+    "pull-request-merge",
+    "merge_pr",
+    "pr_merge",
+    "pr-merge",
+    "git_push",
+    "git-push",
+    "push_branch",
+    "push-branch",
+];
 export const DIRECT_WRITE_HOOK_MATCHER = DIRECT_WRITE_TOOL_NAMES.join("|");
 export const SPAWN_HOOK_MATCHER = SPAWN_TOOL_NAMES.join("|");
+export const SHELL_HOOK_MATCHER = SHELL_TOOL_NAMES.join("|");
+/**
+ * PreToolUse matcher for MCP-class push/merge tools (#2711).
+ * Regex-friendly for Claude/nested hosts. Prefer broad install match +
+ * fail-open classify in the dispatcher over missing a classifiable push/merge
+ * tool name (e.g. `server__push_to_remote` via push+remote).
+ */
+export const MCP_HOOK_MATCHER = [
+    // Prefixed / server-bridge styles (isMcpTool); dispatcher fail-opens non-ops.
+    "mcp__.*",
+    "mcp_.*",
+    ".*__.*",
+    // Bare names classifyMcpTool recognizes without prefixes.
+    ...MCP_PUSH_MERGE_BARE_NAMES,
+    // Name fragments for hosts that strip server prefixes differently.
+    ".*merge[_-]?pull[_-]?request.*",
+    ".*pull[_-]?request[_-]?merge.*",
+    ".*(?:^|[_-])merge_pr(?:$|[_-]).*",
+    ".*pr[_-]?merge.*",
+    ".*git[_-]?push.*",
+    ".*push[_-]?branch.*",
+    ".*push.*(?:git|branch|remote|ref).*",
+    ".*(?:git|branch|remote|ref).*push.*",
+].join("|");
 //# sourceMappingURL=tools.js.map

package/dist/init-deposit/agent-hooks.d.ts

@@ -1,7 +1,7 @@
 import type { HookHost } from "../hooks/dispatcher.js";
 import { type HostHooksPolicy } from "../policy/host-hooks.js";
 import type { InitDepositIo } from "./constants.js";
-export { DIRECT_WRITE_HOOK_MATCHER, SPAWN_HOOK_MATCHER } from "../hooks/tools.js";
+export { DIRECT_WRITE_HOOK_MATCHER, MCP_HOOK_MATCHER, SHELL_HOOK_MATCHER, SPAWN_HOOK_MATCHER, } from "../hooks/tools.js";
 export declare const DEFT_HOOK_COMMAND_MARKER = "deft-hook";
 export declare const LEGACY_DEFT_HOOK_COMMAND_MARKER = "deft hook:dispatch";
 export declare const AGENT_HOOK_PATHS: readonly [".claude/settings.json", ".grok/hooks/deft.json", ".cursor/hooks.json", ".codex/hooks.json"];

package/dist/init-deposit/agent-hooks.js

@@ -1,9 +1,9 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { assertDepositContained } from "../deposit/contain.js";
-import { DIRECT_WRITE_HOOK_MATCHER, SPAWN_HOOK_MATCHER } from "../hooks/tools.js";
+import { DIRECT_WRITE_HOOK_MATCHER, MCP_HOOK_MATCHER, SHELL_HOOK_MATCHER, SPAWN_HOOK_MATCHER, } from "../hooks/tools.js";
 import { isHostHookDepositEnabled, loadHostHooksPolicyFromProject, } from "../policy/host-hooks.js";
-export { DIRECT_WRITE_HOOK_MATCHER, SPAWN_HOOK_MATCHER } from "../hooks/tools.js";
+export { DIRECT_WRITE_HOOK_MATCHER, MCP_HOOK_MATCHER, SHELL_HOOK_MATCHER, SPAWN_HOOK_MATCHER, } from "../hooks/tools.js";
 export const DEFT_HOOK_COMMAND_MARKER = "deft-hook";
 export const LEGACY_DEFT_HOOK_COMMAND_MARKER = "deft hook:dispatch";
 export const AGENT_HOOK_PATHS = [
@@ -103,6 +103,10 @@ function mergeNestedConfig(config, path, host, options = {}) {
         ...preTool,
         nestedGroup(host, "tool.before", DIRECT_WRITE_HOOK_MATCHER),
         nestedGroup(host, "tool.before", SPAWN_HOOK_MATCHER),
+        // Shell/Bash for runtimeAuthority scopes.push / scopes.merge (#2711)
+        nestedGroup(host, "tool.before", SHELL_HOOK_MATCHER),
+        // MCP push/merge (mcp__*, bare merge_pull_request / git_push, …) (#2711)
+        nestedGroup(host, "tool.before", MCP_HOOK_MATCHER),
     ];
     if (options.compact) {
         const preCompact = eventArray(hooks, "PreCompact", path).filter((entry) => !isManagedNestedGroup(entry));
@@ -164,6 +168,18 @@ function mergeCursorConfig(config, path) {
             failClosed: true,
             timeout: 5,
         },
+        {
+            command: command("cursor", "tool.before"),
+            matcher: SHELL_HOOK_MATCHER,
+            failClosed: true,
+            timeout: 5,
+        },
+        {
+            command: command("cursor", "tool.before"),
+            matcher: MCP_HOOK_MATCHER,
+            failClosed: true,
+            timeout: 5,
+        },
     ];
     hooks.preCompact = [...preCompact, { command: command("cursor", "session.compact"), timeout: 5 }];
     return { ...config, version: 1, hooks };
@@ -285,6 +301,14 @@ function hasNestedRegistration(config, host, options = {}) {
         preTool.some((entry) => {
             const group = object(entry);
             return group?.matcher === SPAWN_HOOK_MATCHER && nestedCommands(entry).includes(toolCommand);
+        }) &&
+        preTool.some((entry) => {
+            const group = object(entry);
+            return group?.matcher === SHELL_HOOK_MATCHER && nestedCommands(entry).includes(toolCommand);
+        }) &&
+        preTool.some((entry) => {
+            const group = object(entry);
+            return group?.matcher === MCP_HOOK_MATCHER && nestedCommands(entry).includes(toolCommand);
         });
     if (!base)
         return false;
@@ -315,6 +339,18 @@ function hasCursorRegistration(config) {
                 hook.matcher === SPAWN_HOOK_MATCHER &&
                 hook.failClosed === true);
         }) &&
+        preTool.some((entry) => {
+            const hook = object(entry);
+            return (hook?.command === command("cursor", "tool.before") &&
+                hook.matcher === SHELL_HOOK_MATCHER &&
+                hook.failClosed === true);
+        }) &&
+        preTool.some((entry) => {
+            const hook = object(entry);
+            return (hook?.command === command("cursor", "tool.before") &&
+                hook.matcher === MCP_HOOK_MATCHER &&
+                hook.failClosed === true);
+        }) &&
         preCompact.some((entry) => object(entry)?.command === command("cursor", "session.compact")));
 }
 /** Read-only registration probe shared by verify and doctor. */

package/dist/init-deposit/hygiene.d.ts

@@ -77,8 +77,24 @@ export interface PrunePackageAbsentDepositPathsResult {
  * Remove deposit files not shipped by `@deftai/directive-content`, preserving
  * generated deposit metadata such as `VERSION` (#2804). Subsumes the legacy
  * hard-coded `packages/` prune (#2347).
+ *
+ * Individual removal failures are reported but do not throw — callers that must
+ * refuse a VERSION stamp until the deposit matches the content package should
+ * use {@link reconcileDepositToContentPackage} (#2913).
  */
 export declare function prunePackageAbsentDepositPaths(deftDir: string, contentRoot: string, io: InitDepositIo): Promise<PrunePackageAbsentDepositPathsResult>;
+/**
+ * Fail-closed deposit reconcile against the installed content package (#2913).
+ *
+ * Runs {@link prunePackageAbsentDepositPaths}, then re-scans. If any
+ * package-absent path remains, throws so callers refuse the VERSION stamp
+ * (dst-only stale/malicious agent content must not survive a refresh).
+ *
+ * After a successful {@link replaceTree} full-swap this is typically a no-op
+ * verification; it also covers additive copy seams and the already-current
+ * refresh path that skips payload copy.
+ */
+export declare function reconcileDepositToContentPackage(deftDir: string, contentRoot: string, io: InitDepositIo): Promise<PrunePackageAbsentDepositPathsResult>;
 export interface PruneStrayDepositPathsResult {
     readonly pruned: string[];
 }

package/dist/init-deposit/hygiene.js

@@ -257,6 +257,10 @@ async function pruneEmptyParentsForFile(deftDir, contentDirs, relFile) {
  * Remove deposit files not shipped by `@deftai/directive-content`, preserving
  * generated deposit metadata such as `VERSION` (#2804). Subsumes the legacy
  * hard-coded `packages/` prune (#2347).
+ *
+ * Individual removal failures are reported but do not throw — callers that must
+ * refuse a VERSION stamp until the deposit matches the content package should
+ * use {@link reconcileDepositToContentPackage} (#2913).
  */
 export async function prunePackageAbsentDepositPaths(deftDir, contentRoot, io) {
     const absent = await findPackageAbsentDepositPaths(deftDir, contentRoot);
@@ -278,6 +282,28 @@ export async function prunePackageAbsentDepositPaths(deftDir, contentRoot, io) {
     }
     return { pruned, prunedDirs };
 }
+/**
+ * Fail-closed deposit reconcile against the installed content package (#2913).
+ *
+ * Runs {@link prunePackageAbsentDepositPaths}, then re-scans. If any
+ * package-absent path remains, throws so callers refuse the VERSION stamp
+ * (dst-only stale/malicious agent content must not survive a refresh).
+ *
+ * After a successful {@link replaceTree} full-swap this is typically a no-op
+ * verification; it also covers additive copy seams and the already-current
+ * refresh path that skips payload copy.
+ */
+export async function reconcileDepositToContentPackage(deftDir, contentRoot, io) {
+    const result = await prunePackageAbsentDepositPaths(deftDir, contentRoot, io);
+    const remaining = await findPackageAbsentDepositPaths(deftDir, contentRoot);
+    if (remaining.length > 0) {
+        const sample = remaining.slice(0, 5).join(", ");
+        const more = remaining.length > 5 ? ` (+${remaining.length - 5} more)` : "";
+        throw new Error(`deposit reconcile failed: ${remaining.length} package-absent path(s) remain under .deft/core ` +
+            `(e.g. ${sample}${more}). Refusing VERSION stamp until dst-only content is removed (#2913).`);
+    }
+    return result;
+}
 /**
  * Remove framework-source subdirectories from `.deft/core/` that are not
  * present in the deposited content package (#2347). Silently skips any path

package/dist/init-deposit/init-dispatch.js

@@ -21,6 +21,7 @@
  * dispatcher never re-implements deposit, refresh, or migrate behavior.
  */
 import { resolve } from "node:path";
+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 { classify, plan } from "../resolution/index.js";
 import { runInitDepositCli } from "./init-deposit.js";
 import { runMigrateCli } from "./migrate.js";
@@ -119,6 +120,33 @@ export async function runInitDispatchCli(options) {
                 options.writeOut(text);
         },
     };
+    // #2926: root opt-out — do not scaffold/install/refresh when flag is present.
+    const optOut = detectNoDeftDirective(projectDir);
+    if (optOut.present) {
+        io.printf(`\n[directive init] ${NO_DEFT_DIRECTIVE_DISABLED_MESSAGE}\n`);
+        if (optOut.inconsistent) {
+            io.printf(`[directive init] ${NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE}\n`);
+        }
+        if (options.jsonOut) {
+            options.writeOut(`${JSON.stringify({
+                success: false,
+                action: "init",
+                disabled: true,
+                disabled_via: NO_DEFT_DIRECTIVE_FLAG_NAME,
+                inconsistent: optOut.inconsistent,
+                ...(optOut.inconsistent
+                    ? { inconsistent_policy: NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY }
+                    : {}),
+                deposit_present: optOut.depositPresent,
+                project_dir: projectDir,
+                message: optOut.inconsistent
+                    ? NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE
+                    : NO_DEFT_DIRECTIVE_DISABLED_MESSAGE,
+            }, null, 2)}\n`);
+        }
+        // Clean opt-out is a successful short-circuit; inconsistent state fails closed.
+        return optOut.inconsistent ? 1 : 0;
+    }
     const classification = classifyInitDispatch(projectDir, seams.classifySeams ?? {});
     const { decision, plan: resolutionPlan } = classification;
     printInitDispatchSummary(io, decision, resolutionPlan);

package/dist/init-deposit/prettierignore.js

@@ -9,7 +9,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { assertProjectionContained } from "../fs/projection-containment.js";
+import { assertDestinationNotSymlink } from "../fs/projection-containment.js";
 import { stripGitignoreInlineComment } from "../triage/bootstrap/gitignore.js";
 /** Directory ignore entry for the hybrid deposit. */
 export const PRETTIERIGNORE_DEFT_CORE_LINE = ".deft/core/";
@@ -18,7 +18,7 @@ const DEFT_CORE_COVERING_LINES = new Set([".deft/core/", ".deft/core", ".deft/co
 const DEFT_FRAMEWORK_PRETTIERIGNORE_HEADER = "# Deft framework: the vendored payload is outside the consumer Prettier gate (#2534).\n";
 function projectionTarget(projectDir) {
     const target = join(projectDir, ".prettierignore");
-    assertProjectionContained(projectDir, target);
+    assertDestinationNotSymlink(projectDir, target);
     return target;
 }
 function prettierIgnoreCoversLine(present, line) {

package/dist/init-deposit/refresh.js

@@ -12,19 +12,20 @@ import { existsSync, readFileSync, renameSync, statSync } from "node:fs";
 import { platform as osPlatform } from "node:os";
 import { join, resolve } from "node:path";
 import { assertDepositContained } from "../deposit/contain.js";
-import { copyTree } from "../deposit/copy-tree.js";
+import { replaceTree } from "../deposit/copy-tree.js";
 import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
 import { readCorePackageVersion } from "../engine-version.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";
 import { checkLocalEngineIntegrity, classify, ENGINE_PACKAGE, plan, renderGlobalInstall, resolveEngine, } from "../resolution/index.js";
 import { gitPorcelain } from "../story-ready/git.js";
 import { removeStaleMigratedFrameworkNarrative } from "../xbrief-migrate/migrate-project.js";
 import { writeAgentHookDeposit } from "./agent-hooks.js";
 import { ensureInitGitignoreLines, isDepositTrackedInGit } from "./gitignore.js";
-import { depositStagePaths, isInstallerManagedPath, printCommitGuidance, prunePackageAbsentDepositPaths, } from "./hygiene.js";
+import { depositStagePaths, isInstallerManagedPath, printCommitGuidance, reconcileDepositToContentPackage, } from "./hygiene.js";
 import { parseInitArgv } from "./init-deposit.js";
 import { buildLegacyRefusalJson, buildLegacyRefusalMessage, detectLegacyLayout, LEGACY_LAYOUT_REFUSED_EXIT_CODE, LegacyLayoutRefusedError, } from "./legacy-detect.js";
 import { printMigrateNudgeIfNeeded } from "./migrate.js";
@@ -392,7 +393,9 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     // the resolved project tree. Writes nothing on refusal.
     assertDepositContained(projectDir, deftDir);
     const resolveContent = seams.resolveContentRoot ?? resolveInstalledContentRoot;
-    const copyContent = seams.copyContent ?? copyTree;
+    // #2913: default is full-tree replace (Go swapInCore parity), not additive copyTree.
+    // Injected seams.copyContent still wins (tests / specialized callers).
+    const copyContent = seams.copyContent ?? replaceTree;
     const readEngine = seams.readEngineVersion ?? readCorePackageVersion;
     const readPackageVersion = seams.readPackageVersion ?? readCorePackageVersion;
     const contentRoot = await resolveContent();
@@ -406,15 +409,19 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     const strategy = alreadyCurrent ? "no-op" : "file-swap";
     if (alreadyCurrent) {
         io.printf("[deft update] Framework payload already current; skipping payload copy.\n");
+        // #2913: still fail-closed reconcile so dst-only leftovers cannot linger when
+        // VERSION already matches (e.g. pre-#2804 additive deposits). Does not re-stamp.
+        await reconcileDepositToContentPackage(deftDir, contentRoot, io);
         migrateLegacyInstallManifest(projectDir, join(deftDir, "VERSION"));
     }
     else {
+        // Full-tree replace (or injected seam). Additive copy is no longer the default.
         await copyContent(contentRoot, deftDir);
         await prunePythonArtifactsFromDeposit(deftDir, projectDir, io);
-        // #2804 / #2347: prune deposit paths absent from the content package. The
-        // additive file-swap never removes them, causing stale bridge-era files to
-        // survive across upgrades until manually cleaned.
-        await prunePackageAbsentDepositPaths(deftDir, contentRoot, io);
+        // #2913 / #2804 / #2347: fail-closed delete-not-in-source BEFORE VERSION stamp.
+        // replaceTree already drops dst-only paths; reconcile verifies and covers
+        // additive seams. Throws => no VERSION rewrite (refuse stamp until clean).
+        await reconcileDepositToContentPackage(deftDir, contentRoot, io);
         const nowIso = seams.nowIso ?? (() => new Date().toISOString().replace(/\.\d{3}Z$/, "Z"));
         const manifestFields = {
             ref: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,
@@ -586,6 +593,30 @@ export async function runRefreshDepositCli(options) {
     // Legacy layouts keep their existing refusal path (thrown by runRefreshDeposit
     // and handled below), so classification is skipped for them.
     const projectDir = resolve(options.projectDir);
+    // #2926: root opt-out wins over update/refresh and ambient force-on.
+    const optOut = detectNoDeftDirective(projectDir);
+    if (optOut.present) {
+        const message = optOut.inconsistent
+            ? NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE
+            : NO_DEFT_DIRECTIVE_DISABLED_MESSAGE;
+        io.printf(`${message}\n`);
+        if (options.jsonOut) {
+            options.writeOut(`${JSON.stringify({
+                success: false,
+                action: "update",
+                disabled: true,
+                disabled_via: NO_DEFT_DIRECTIVE_FLAG_NAME,
+                inconsistent: optOut.inconsistent,
+                ...(optOut.inconsistent
+                    ? { inconsistent_policy: NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY }
+                    : {}),
+                deposit_present: optOut.depositPresent,
+                project_dir: projectDir,
+                message,
+            }, null, 2)}\n`);
+        }
+        return UPDATE_REFUSED_EXIT_CODE;
+    }
     const detectLegacy = options.seams?.detectLegacy ?? detectLegacyLayout;
     let classification = null;
     if (!detectLegacy(projectDir).legacy) {