@deftai/directive-core 0.103.0 → 0.105.0

package/dist/check/cached-orchestrator.d.ts

@@ -15,7 +15,7 @@ export interface CachedCheckOptions extends CheckOrchestratorSeams {
      * Pass `null` to skip preflight entirely (legacy test paths).
      */
     readonly preflight?: ToolchainPreflightResult | null;
-    /** #3282: session id for run-summary lines (default: new UUID). */
+    /** #3282 / #3399: session id for run-summary lines (default: resolver). */
     readonly sessionId?: string;
     /** #3282: disable run-summary emission (tests). */
     readonly emitRunSummary?: boolean;

package/dist/check/cached-orchestrator.js

@@ -1,5 +1,4 @@
 import { spawnSync } from "node:child_process";
-import { randomUUID } from "node:crypto";
 import { join, resolve } from "node:path";
 import { lintShippedRegistry, resolveTaskContract, runWithCache, } from "../cache/task-cache/index.js";
 import { defaultWhich } from "../doctor/which.js";
@@ -73,7 +72,7 @@ export function dispatchCachedTaskCheck(frameworkRoot, projectRoot, options = {}
     const baseGates = gatesForCheckTarget(target);
     const gates = applyProductFirstGateMode(baseGates, modeResolution.mode, checkGateId);
     const codeVersion = readCorePackageVersion();
-    const sessionId = options.sessionId ?? randomUUID();
+    const sessionId = options.sessionId;
     const gateOutcomes = [];
     const emitSummary = (exitCode, degraded) => {
         if (options.emitRunSummary === false)
@@ -84,6 +83,7 @@ export function dispatchCachedTaskCheck(frameworkRoot, projectRoot, options = {}
                 sessionId,
                 frameworkVersion: codeVersion,
                 env: options.env,
+                component: "check",
             });
             emitter.emitCheckInvocation({
                 target,

package/dist/check/gate-lists.d.ts

@@ -10,8 +10,9 @@ export type CheckGateSpec = string | {
     readonly args?: readonly string[];
 };
 /**
- * Product-first AC gate (#3284): always first; soft-missing when no active
- * xBRIEF so framework self-check is not deadlocked without a story.
+ * Product-first AC gate (#3284): always first; `--soft-missing-xbrief` skips
+ * only when no story was active this session. A same-session complete targets
+ * xbrief/completed instead of skipping (#3357).
  */
 export declare const PRODUCT_FIRST_AC_GATE: CheckGateSpec;
 export declare function checkGateId(spec: CheckGateSpec): string;

package/dist/check/gate-lists.js

@@ -1,8 +1,9 @@
 /** Gate execution order mirrors Taskfile.yml check targets (#1713 dogfood). */
 import { PRODUCT_AC_GATE_ID } from "../product-first-done-gate/types.js";
 /**
- * Product-first AC gate (#3284): always first; soft-missing when no active
- * xBRIEF so framework self-check is not deadlocked without a story.
+ * Product-first AC gate (#3284): always first; `--soft-missing-xbrief` skips
+ * only when no story was active this session. A same-session complete targets
+ * xbrief/completed instead of skipping (#3357).
  */
 export const PRODUCT_FIRST_AC_GATE = {
     task: PRODUCT_AC_GATE_ID,
@@ -81,6 +82,8 @@ export const FRAMEWORK_CHECK_GATES = [
     "verify:test-boundary",
     "verify:scope-provenance",
     "verify:consumer-check-contract",
+    // #3362: dead-surface detector (warn-only this release; no --enforce)
+    "verify:telemetry-coverage",
     "verify:vbrief-conformance",
     "verify:destructive-gh-verbs",
     "verify:scm-boundary",

package/dist/check/index.d.ts

@@ -6,4 +6,5 @@ export { extractGateCause, formatDegradedSkipReport, formatNamedCauseFailure, ty
 export type { CheckOrchestratorOptions, CheckOrchestratorSeams } from "./orchestrator.js";
 export { dispatchTaskCheck, isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget, } from "./orchestrator.js";
 export { detectTestRunner, type RunnerDetectResult, runnerDetectionTable, type TestRunnerKind, } from "./runner-detect.js";
+export { type ResolveSessionCompletedAcInput, resolveSessionCompletedVerifyAcTarget, SESSION_COMPLETED_AC_REMEDIATION, SESSION_COMPLETED_MARKER_REL, type SessionCompletedAcTarget, type SessionCompletedMarker, sessionCompletedMarkerPath, writeSessionCompletedMarker, } from "./session-completed-ac.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/check/index.js

@@ -5,4 +5,5 @@ export { CONSUMER_CHECK_GATES, checkGateId, checkGateSpawnArgs, FRAMEWORK_CHECK_
 export { extractGateCause, formatDegradedSkipReport, formatNamedCauseFailure, remedyForGate, } from "./named-cause.js";
 export { dispatchTaskCheck, isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget, } from "./orchestrator.js";
 export { detectTestRunner, runnerDetectionTable, } from "./runner-detect.js";
+export { resolveSessionCompletedVerifyAcTarget, SESSION_COMPLETED_AC_REMEDIATION, SESSION_COMPLETED_MARKER_REL, sessionCompletedMarkerPath, writeSessionCompletedMarker, } from "./session-completed-ac.js";
 //# sourceMappingURL=index.js.map

package/dist/check/named-cause.d.ts

@@ -15,7 +15,7 @@ export interface NamedCauseMessage {
  * Extract a short cause from gate stdout/stderr without leaking env values.
  * Strips lines that look like KEY=value assignments.
  */
-export declare function extractGateCause(stdout: string, stderr: string, exitCode: number, spawnError?: string): string;
+export declare function extractGateCause(stdout: string, stderr: string, exitCode: number, spawnError?: string, gateId?: string): string;
 export declare function remedyForGate(gateId: string, cause: string): string;
 /**
  * Format named-cause failure lines for a single gate.

package/dist/check/named-cause.js

@@ -31,7 +31,7 @@ const CLI_SPAWN_ERROR_REMEDY = "Install: npm i -g @deftai/directive@latest";
  * Extract a short cause from gate stdout/stderr without leaking env values.
  * Strips lines that look like KEY=value assignments.
  */
-export function extractGateCause(stdout, stderr, exitCode, spawnError) {
+export function extractGateCause(stdout, stderr, exitCode, spawnError, gateId) {
     if (spawnError !== undefined && spawnError.length > 0) {
         // Normalize common missing-binary messages without path dumps.
         if (/ENOENT|not found|not recognized/i.test(spawnError)) {
@@ -46,15 +46,45 @@ export function extractGateCause(stdout, stderr, exitCode, spawnError) {
         .split(/\r?\n/)
         .map((l) => l.trim())
         .filter((l) => l.length > 0);
+    const useful = [];
     for (const line of combined) {
         if (looksLikeEnvLeak(line))
             continue;
         if (line.startsWith("check:"))
             continue;
-        return sanitizeCauseLine(line);
+        if (isGoTaskWrapperNoise(line))
+            continue;
+        useful.push(line);
+    }
+    const gateHint = gateId?.trim() ?? "";
+    if (gateHint.length > 0) {
+        const named = useful.find((line) => line.includes(gateHint));
+        if (named !== undefined) {
+            return sanitizeCauseLine(named);
+        }
+    }
+    if (useful.length > 0) {
+        return sanitizeCauseLine(useful[0]);
     }
     return `gate exited ${exitCode} without a diagnostic message`;
 }
+/** go-task echoes `task: [engine:_ts-build] set -eu` plus the script body (#3449). */
+function isGoTaskWrapperNoise(line) {
+    if (/^task: \[/.test(line))
+        return true;
+    if (/^set -eu$/.test(line))
+        return true;
+    if (/^: #/.test(line))
+        return true;
+    if (/^# /.test(line) || /^#\t/.test(line))
+        return true;
+    if (/^(bin|root_pkg|is_buildable_source|first_token|is_runtime_verb|global_cli)=/.test(line)) {
+        return true;
+    }
+    if (/^(if |elif |else$|fi$|then$)/.test(line))
+        return true;
+    return false;
+}
 function looksLikeEnvLeak(line) {
     // Avoid echoing DEFT_*= or generic env dumps.
     if (/^[A-Z][A-Z0-9_]*=/.test(line))
@@ -91,7 +121,7 @@ export function remedyForGate(gateId, cause) {
  * Format named-cause failure lines for a single gate.
  */
 export function formatNamedCauseFailure(input) {
-    const cause = extractGateCause(input.stdout ?? "", input.stderr ?? "", input.exitCode, input.spawnError);
+    const cause = extractGateCause(input.stdout ?? "", input.stderr ?? "", input.exitCode, input.spawnError, input.gateId);
     const remedy = remedyForGate(input.gateId, cause);
     const lines = [
         `check: gate ${input.gateId} failed (exit ${input.exitCode})`,

package/dist/check/session-completed-ac.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Check composition: verify:ac must not soft-skip after a same-session complete (#3357).
+ *
+ * "No story ever active this session" remains a legitimate skip.
+ * "A story completed this session" targets xbrief/completed (most recent).
+ * One remediation string when that target cannot be used.
+ */
+/** One remediation when check cannot target the just-completed brief (#3357). */
+export declare const SESSION_COMPLETED_AC_REMEDIATION = "Run task verify:ac -- xbrief/completed/<just-completed>.xbrief.json (a story completed this session; check must not soft-skip) (#3357)";
+/** Project-relative marker written by scope:complete for this session (#3357). */
+export declare const SESSION_COMPLETED_MARKER_REL: readonly [".deft", "last-completed.json"];
+export interface SessionCompletedMarker {
+    readonly path: string;
+    readonly sessionId: string;
+    readonly completedAt: string;
+}
+export type SessionCompletedAcTarget = {
+    readonly kind: "none";
+} | {
+    readonly kind: "target";
+    readonly path: string;
+} | {
+    readonly kind: "cannot";
+    readonly message: string;
+};
+export interface ResolveSessionCompletedAcInput {
+    readonly projectRoot: string;
+    readonly sessionId?: string | null;
+    readonly sessionStartedAt?: Date | null;
+    readonly env?: NodeJS.ProcessEnv;
+}
+export declare function sessionCompletedMarkerPath(projectRoot: string): string;
+/** Persist the just-completed brief so check can fail closed if that file is unreadable. */
+export declare function writeSessionCompletedMarker(projectRoot: string, marker: SessionCompletedMarker): void;
+/**
+ * Resolve the just-completed brief for this session, if check must target it.
+ */
+export declare function resolveSessionCompletedVerifyAcTarget(input: ResolveSessionCompletedAcInput): SessionCompletedAcTarget;
+//# sourceMappingURL=session-completed-ac.d.ts.map

package/dist/check/session-completed-ac.js

@@ -0,0 +1,198 @@
+/**
+ * Check composition: verify:ac must not soft-skip after a same-session complete (#3357).
+ *
+ * "No story ever active this session" remains a legitimate skip.
+ * "A story completed this session" targets xbrief/completed (most recent).
+ * One remediation string when that target cannot be used.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
+import { readRitualState } from "../session/ritual-sentinel.js";
+import { parseTimestamp } from "../session/time.js";
+/** One remediation when check cannot target the just-completed brief (#3357). */
+export const SESSION_COMPLETED_AC_REMEDIATION = "Run task verify:ac -- xbrief/completed/<just-completed>.xbrief.json (a story completed this session; check must not soft-skip) (#3357)";
+/** Project-relative marker written by scope:complete for this session (#3357). */
+export const SESSION_COMPLETED_MARKER_REL = [".deft", "last-completed.json"];
+function asRecord(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+export function sessionCompletedMarkerPath(projectRoot) {
+    return join(resolve(projectRoot), ...SESSION_COMPLETED_MARKER_REL);
+}
+/** Persist the just-completed brief so check can fail closed if that file is unreadable. */
+export function writeSessionCompletedMarker(projectRoot, marker) {
+    const root = resolve(projectRoot);
+    const target = sessionCompletedMarkerPath(root);
+    containedWrite({
+        root,
+        target,
+        data: `${JSON.stringify(marker, null, 2)}\n`,
+        mode: "replace",
+        mkdir: true,
+    });
+}
+function readSessionCompletedMarker(projectRoot) {
+    const path = sessionCompletedMarkerPath(projectRoot);
+    if (!existsSync(path)) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        const rec = asRecord(parsed);
+        const briefPath = typeof rec?.path === "string" ? rec.path.trim() : "";
+        const sessionId = typeof rec?.sessionId === "string" ? rec.sessionId.trim() : "";
+        const completedAt = typeof rec?.completedAt === "string" ? rec.completedAt.trim() : "";
+        if (briefPath.length === 0 || sessionId.length === 0) {
+            return "invalid";
+        }
+        return { path: briefPath, sessionId, completedAt };
+    }
+    catch {
+        return "invalid";
+    }
+}
+function resolveSession(input) {
+    const env = input.env ?? process.env;
+    const injected = input.sessionId?.trim() ?? "";
+    if (injected.length > 0) {
+        return { sessionId: injected, startedAt: input.sessionStartedAt ?? null };
+    }
+    const fromEnv = typeof env.DEFT_SESSION_ID === "string" ? env.DEFT_SESSION_ID.trim() : "";
+    const [state] = readRitualState(resolve(input.projectRoot));
+    const ritualId = state?.sessionId.trim() ?? "";
+    const sessionId = fromEnv.length > 0 ? fromEnv : ritualId;
+    // Do not pair DEFT_SESSION_ID with a different ritual-state startedAt.
+    const ritualStartedAt = ritualId.length > 0 && ritualId === sessionId ? (state?.startedAt ?? null) : null;
+    return {
+        sessionId: sessionId.length > 0 ? sessionId : null,
+        startedAt: input.sessionStartedAt ?? ritualStartedAt,
+    };
+}
+function listCompletedBriefPaths(projectRoot) {
+    const paths = [];
+    for (const dirName of ["xbrief", "vbrief"]) {
+        const completed = join(projectRoot, dirName, "completed");
+        if (!existsSync(completed))
+            continue;
+        let names = [];
+        try {
+            names = readdirSync(completed)
+                .filter((n) => n.endsWith(".xbrief.json") || n.endsWith(".vbrief.json"))
+                .sort();
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            paths.push(join(completed, name));
+        }
+    }
+    return paths;
+}
+function readCompletedCandidate(path) {
+    if (!existsSync(path)) {
+        return "unreadable";
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return "unreadable";
+    }
+    const data = asRecord(parsed);
+    const plan = asRecord(data?.plan);
+    if (plan === null) {
+        return "unreadable";
+    }
+    const meta = asRecord(plan.metadata);
+    if (meta === null) {
+        // Historical completed briefs (pre-#3357) often have no plan.metadata.
+        // That is not an unreadable this-session target (#3375).
+        return { path, completedAtMs: 0, sessionId: null };
+    }
+    const sessionRaw = typeof meta.completedSessionId === "string" ? meta.completedSessionId.trim() : "";
+    const completedAt = parseTimestamp(meta.completedAt);
+    return {
+        path,
+        completedAtMs: completedAt?.getTime() ?? 0,
+        sessionId: sessionRaw.length > 0 ? sessionRaw : null,
+    };
+}
+function isSameSession(candidate, sessionId, startedAt) {
+    if (sessionId !== null && candidate.sessionId === sessionId) {
+        return true;
+    }
+    // Timestamp fallback only for pre-#3357 briefs that never stamped a session id.
+    // A brief stamped for a different session must not replace this session's target.
+    if (candidate.sessionId === null &&
+        startedAt !== null &&
+        candidate.completedAtMs >= startedAt.getTime()) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Resolve the just-completed brief for this session, if check must target it.
+ */
+export function resolveSessionCompletedVerifyAcTarget(input) {
+    const projectRoot = resolve(input.projectRoot);
+    const { sessionId, startedAt } = resolveSession(input);
+    const marker = readSessionCompletedMarker(projectRoot);
+    if (marker === "invalid" && sessionId !== null) {
+        return { kind: "cannot", message: SESSION_COMPLETED_AC_REMEDIATION };
+    }
+    if (marker !== null &&
+        marker !== "invalid" &&
+        sessionId !== null &&
+        marker.sessionId === sessionId) {
+        const candidate = readCompletedCandidate(marker.path);
+        if (candidate === "unreadable") {
+            return { kind: "cannot", message: SESSION_COMPLETED_AC_REMEDIATION };
+        }
+        return { kind: "target", path: candidate.path };
+    }
+    const paths = listCompletedBriefPaths(projectRoot);
+    if (paths.length === 0 || (sessionId === null && startedAt === null)) {
+        return { kind: "none" };
+    }
+    const matched = [];
+    let unreadableCount = 0;
+    for (const path of paths) {
+        const candidate = readCompletedCandidate(path);
+        if (candidate === "unreadable") {
+            unreadableCount += 1;
+            continue;
+        }
+        if (isSameSession(candidate, sessionId, startedAt)) {
+            matched.push(candidate);
+        }
+    }
+    if (matched.length === 0) {
+        // Any unreadable completed brief may be this session's target.
+        if (unreadableCount > 0) {
+            return { kind: "cannot", message: SESSION_COMPLETED_AC_REMEDIATION };
+        }
+        return { kind: "none" };
+    }
+    matched.sort((a, b) => {
+        if (a.completedAtMs !== b.completedAtMs) {
+            return b.completedAtMs - a.completedAtMs;
+        }
+        return a.path < b.path ? 1 : a.path > b.path ? -1 : 0;
+    });
+    const latest = matched[0];
+    if (latest === undefined) {
+        return { kind: "none" };
+    }
+    const verified = readCompletedCandidate(latest.path);
+    if (verified === "unreadable") {
+        return { kind: "cannot", message: SESSION_COMPLETED_AC_REMEDIATION };
+    }
+    return { kind: "target", path: latest.path };
+}
+//# sourceMappingURL=session-completed-ac.js.map

package/dist/codebase/default-extractor.d.ts

@@ -3,6 +3,11 @@ export declare const DEFAULT_PROVIDER_VERSION = "0.1";
 export declare const MAX_IMPORT_SCAN_BYTES = 262144;
 export declare const MAX_FILES_PER_MODULE = 100;
 export declare const MAX_EVIDENCE_PER_EDGE = 5;
+/**
+ * Shared "not product source" core (#3487) plus `build`, which only the
+ * codebase extractor treats as non-source. Agent worktrees are not source
+ * modules (#2953, #1656).
+ */
 export declare const SKIP_DIRS: Set<string>;
 export declare const LANGUAGE_BY_SUFFIX: Readonly<Record<string, string>>;
 export declare const ENTRYPOINT_NAMES: Set<string>;

package/dist/codebase/default-extractor.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, globSync, readdirSync, readFileSync, realpathSync, statSync, } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
+import { NON_PRODUCT_DIRS } from "../fs/non-product-dirs.js";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { extractCodeStructure, loadJsonFile } from "../verify-source/code-structure-validate.js";
 import { sortedStringifyPretty } from "./json.js";
@@ -10,21 +11,12 @@ export const DEFAULT_PROVIDER_VERSION = "0.1";
 export const MAX_IMPORT_SCAN_BYTES = 262_144;
 export const MAX_FILES_PER_MODULE = 100;
 export const MAX_EVIDENCE_PER_EDGE = 5;
-export const SKIP_DIRS = new Set([
-    ".git",
-    ".mypy_cache",
-    ".pytest_cache",
-    ".ruff_cache",
-    ".venv",
-    "__pycache__",
-    "build",
-    "dist",
-    "node_modules",
-    // Swarm / agent worktrees are not source modules (#2953, #1656).
-    ".deft-scratch",
-    // Legacy swarm worktree root name (pre-.deft-scratch layout).
-    "swarm-worktrees",
-]);
+/**
+ * Shared "not product source" core (#3487) plus `build`, which only the
+ * codebase extractor treats as non-source. Agent worktrees are not source
+ * modules (#2953, #1656).
+ */
+export const SKIP_DIRS = new Set([...NON_PRODUCT_DIRS, "build"]);
 export const LANGUAGE_BY_SUFFIX = {
     ".go": "Go",
     ".js": "JavaScript",

package/dist/deposit/copy-tree.js

@@ -14,6 +14,8 @@ import { constants } from "node:fs";
 import { lstat, mkdir, mkdtemp, open, readdir, readFile, rename, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import { containedRemove, containedWrite } from "../fs/contained-write.js";
+import { isPortRecordMode, recordActiveMutation } from "../fs/mutation-ledger.js";
 const DEFAULT_FILE_MODE = 0o644;
 const DEFAULT_DIR_MODE = 0o755;
 async function assertDestinationIsNotSymlink(path, label = "copyTree") {
@@ -103,6 +105,51 @@ async function pathExists(path) {
         throw err;
     }
 }
+/** Posix-relative file and symlink paths under `root` (directories are walked). */
+async function listRelativeFilePaths(root) {
+    const out = [];
+    async function walk(dir, rel) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const childRel = rel.length > 0 ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory() && !entry.isSymbolicLink()) {
+                await walk(join(dir, entry.name), childRel);
+            }
+            else {
+                out.push(childRel.replace(/\\/g, "/"));
+            }
+        }
+    }
+    await walk(root, "");
+    return out;
+}
+async function destOnlyRelativeFiles(src, dst) {
+    const srcSet = new Set(await listRelativeFilePaths(src));
+    return (await listRelativeFilePaths(dst)).filter((rel) => !srcSet.has(rel));
+}
+/**
+ * Ledger dest-only deletes and dest writes after a successful swap (#3392).
+ * Observational: dest is already live. Failures must not reject replaceTree.
+ */
+async function ledgerReplacedTree(dst, destOnly) {
+    try {
+        for (const rel of destOnly) {
+            recordActiveMutation("deleted", join(dst, ...rel.split("/")));
+        }
+        for (const rel of await listRelativeFilePaths(dst)) {
+            recordActiveMutation("wrote", join(dst, ...rel.split("/")));
+        }
+    }
+    catch {
+        // Ledger is observational; dest is already live.
+    }
+}
 /**
  * Move `src` to `dst`, falling back to copy+remove across devices (EXDEV),
  * mirroring Go `movePayload` used by `swapInCore`.
@@ -143,15 +190,27 @@ export async function replaceTree(src, dst) {
         throw new Error(`replaceTree: source ${src} is not a directory`);
     }
     await assertDestinationIsNotSymlink(dst, "replaceTree");
+    if (isPortRecordMode()) {
+        const destOnly = (await pathExists(dst)) ? await destOnlyRelativeFiles(src, dst) : [];
+        for (const rel of destOnly) {
+            containedRemove({ root: dst, target: rel });
+        }
+        for (const rel of await listRelativeFilePaths(src)) {
+            containedWrite({ root: dst, target: rel, data: "", mode: "replace" });
+        }
+        return;
+    }
     const parent = dirname(dst);
     await mkdir(parent, { recursive: true, mode: DEFAULT_DIR_MODE });
     const staging = await mkdtemp(join(tmpdir(), "deft-core-stage-"));
     let backup = null;
     /** When true, leave `backup` on disk so an operator can recover after dual failure. */
     let preserveBackupOnExit = false;
+    let destOnly = [];
     try {
         await copyDirContents(src, staging);
         if (await pathExists(dst)) {
+            destOnly = await destOnlyRelativeFiles(src, dst);
             backup = await mkdtemp(join(tmpdir(), "deft-core-bak-"));
             // mkdtemp created an empty dir; remove it so moveTree can rename onto the path.
             await rm(backup, { recursive: true, force: true });
@@ -206,6 +265,7 @@ export async function replaceTree(src, dst) {
             await rm(backup, { recursive: true, force: true }).catch(() => undefined);
             backup = null;
         }
+        await ledgerReplacedTree(dst, destOnly);
     }
     finally {
         await rm(staging, { recursive: true, force: true }).catch(() => undefined);

package/dist/deposit/python-free.js

@@ -6,8 +6,9 @@
  * `scripts/` tree, `.py` files, and Python `run` shims.
  */
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { readdir, readFile, rm, stat } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import { join, relative } from "node:path";
+import { containedRemove } from "../fs/contained-write.js";
 const PY_SUFFIX = ".py";
 const PYC_SUFFIX = ".pyc";
 function isPythonRunShim(_path, head) {
@@ -81,19 +82,24 @@ export function isRepoRootPythonRunShim(projectDir) {
         return true;
     }
 }
+function removeContained(projectDir, target, recursive = false) {
+    return containedRemove({ root: projectDir, target, recursive }).removed;
+}
 /** Remove Python-only trees/files from the consumer deposit and repo-root run shim. */
 export async function prunePythonArtifactsFromDeposit(depositDir, projectDir, io) {
     let removed = 0;
     const scriptsDir = join(depositDir, "scripts");
     try {
         if ((await stat(scriptsDir)).isDirectory()) {
-            await rm(scriptsDir, { recursive: true, force: true });
-            removed += 1;
-            io?.printf("Removed Python scripts/ tree from the consumer deposit (#2022 Phase 3).\n");
+            if (removeContained(projectDir, scriptsDir, true)) {
+                removed += 1;
+                io?.printf("Removed Python scripts/ tree from the consumer deposit (#2022 Phase 3).\n");
+            }
         }
     }
-    catch {
-        // absent
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
     }
     async function walkRemovePy(root) {
         let entries;
@@ -107,8 +113,8 @@ export async function prunePythonArtifactsFromDeposit(depositDir, projectDir, io
             const full = join(root, entry.name);
             if (entry.isDirectory()) {
                 if (entry.name === "__pycache__") {
-                    await rm(full, { recursive: true, force: true });
-                    removed += 1;
+                    if (removeContained(projectDir, full, true))
+                        removed += 1;
                     continue;
                 }
                 await walkRemovePy(full);
@@ -117,8 +123,8 @@ export async function prunePythonArtifactsFromDeposit(depositDir, projectDir, io
             if (!entry.isFile())
                 continue;
             if (entry.name.endsWith(PY_SUFFIX) || entry.name.endsWith(PYC_SUFFIX)) {
-                await rm(full, { force: true });
-                removed += 1;
+                if (removeContained(projectDir, full))
+                    removed += 1;
             }
         }
     }
@@ -128,21 +134,23 @@ export async function prunePythonArtifactsFromDeposit(depositDir, projectDir, io
         try {
             const head = await readFile(depositRun, "utf8");
             if (isPythonRunShim(depositRun, head.slice(0, 200))) {
-                await rm(depositRun, { force: true });
-                removed += 1;
-                io?.printf("Removed Python run shim from .deft/core (#2022 Phase 3).\n");
+                if (removeContained(projectDir, depositRun)) {
+                    removed += 1;
+                    io?.printf("Removed Python run shim from .deft/core (#2022 Phase 3).\n");
+                }
             }
         }
         catch {
-            await rm(depositRun, { force: true });
-            removed += 1;
+            if (removeContained(projectDir, depositRun))
+                removed += 1;
         }
     }
     const projectRun = join(projectDir, "run");
     if (isRepoRootPythonRunShim(projectDir)) {
-        await rm(projectRun, { force: true });
-        removed += 1;
-        io?.printf("Removed repo-root Python run shim (#2022 Phase 3).\n");
+        if (removeContained(projectDir, projectRun)) {
+            removed += 1;
+            io?.printf("Removed repo-root Python run shim (#2022 Phase 3).\n");
+        }
     }
     return removed;
 }

package/dist/doctor/checks.d.ts

@@ -4,6 +4,14 @@ import type { CheckResult } from "./types.js";
 export declare const XBRIEF_ENVELOPE_MIGRATE_COMMAND: "deft migrate:xbrief";
 /** Doctor check name for envelope major mismatch (Q5 Option 2, #3243). */
 export declare const XBRIEF_ENVELOPE_MAJOR_CHECK: "xbrief-envelope-version";
+/**
+ * One SoT for advisory (exit-exempt) check fails (#3379).
+ * Union of the previous `deriveExitCode` / `cmdDoctor` name lists.
+ * A fail is advisory when `data.advisory === true` or the name is in this set.
+ */
+export declare const DOCTOR_ADVISORY_FAIL_CHECKS: ReadonlySet<string>;
+/** True when a check fail must stay a warning (not lastErrorCount / exit 1). */
+export declare function isDoctorAdvisoryFail(name: string, data?: Readonly<Record<string, unknown>> | null): boolean;
 export interface CheckSeams {
     readonly readText?: (path: string) => string | null;
     readonly isFile?: (path: string) => boolean;