@deftai/directive-core 0.104.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/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/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;

package/dist/doctor/checks.js

@@ -21,6 +21,28 @@ import { readTextSafe } from "./paths.js";
 export const XBRIEF_ENVELOPE_MIGRATE_COMMAND = "deft migrate:xbrief";
 /** Doctor check name for envelope major mismatch (Q5 Option 2, #3243). */
 export 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 const DOCTOR_ADVISORY_FAIL_CHECKS = new Set([
+    "legacy-layout",
+    "canonical-vendored-npm-signpost",
+    "manifest-version-reportable",
+    "gitignore-coverage",
+    "stale-xbrief-schema-deposit",
+    "typescript-7-side-by-side",
+    "completed-open-items",
+    "coverage-check-resume-policy",
+]);
+/** True when a check fail must stay a warning (not lastErrorCount / exit 1). */
+export function isDoctorAdvisoryFail(name, data) {
+    return data?.advisory === true || DOCTOR_ADVISORY_FAIL_CHECKS.has(name);
+}
+function stampAdvisory(data) {
+    return { ...data, advisory: true };
+}
 /** True when an fs error means the path is cleanly absent (not unreadable). */
 function isEnoentError(err) {
     return (typeof err === "object" &&
@@ -650,13 +672,13 @@ export function checkLegacyLayout(projectRoot, seams = {}) {
             name: "legacy-layout",
             status: "fail",
             detail: dualLayoutSignpostLine(dualLayout),
-            data: {
+            data: stampAdvisory({
                 legacy_layout: true,
                 legacy_layout_kind: dualLayout.kind,
                 evidence: [...dualLayout.evidence],
                 upgrading_doc_url: UPGRADING_DOC_URL,
                 go_bridge_releases_url: GO_BRIDGE_RELEASES_URL,
-            },
+            }),
         };
     }
     const detection = detectLegacyLayout(projectRoot, legacySeams);
@@ -672,13 +694,13 @@ export function checkLegacyLayout(projectRoot, seams = {}) {
         name: "legacy-layout",
         status: "fail",
         detail: legacyLayoutSignpostLine(detection),
-        data: {
+        data: stampAdvisory({
             legacy_layout: true,
             legacy_layout_kind: detection.kind,
             evidence: [...detection.evidence],
             upgrading_doc_url: UPGRADING_DOC_URL,
             go_bridge_releases_url: GO_BRIDGE_RELEASES_URL,
-        },
+        }),
     };
 }
 /**
@@ -723,14 +745,14 @@ export function checkCanonicalVendoredNpmSignpost(projectRoot, seams = {}) {
         name: "canonical-vendored-npm-signpost",
         status: "fail",
         detail,
-        data: {
+        data: stampAdvisory({
             canonical_vendored: true,
             npm_managed: false,
             manifest_path: manifestPath,
             sentinel_key: NPM_MANAGED_SENTINEL_KEY,
             sentinel_value: NPM_MANAGED_SENTINEL_VALUE,
             upgrading_doc_url: UPGRADING_DOC_URL,
-        },
+        }),
     };
 }
 /**
@@ -786,14 +808,14 @@ export function checkManifestVersionReportable(projectRoot, installRoot, seams =
                 "so the framework version is unreportable. This happens on legacy `deft-install` deposits " +
                 `made without a release pin (#2294). Run \`${CANONICAL_UPGRADE_COMMAND}\` then \`directive update\` ` +
                 `to obtain a pinned npm-managed manifest. See ${UPGRADING_DOC_URL}.`,
-            data: {
+            data: stampAdvisory({
                 manifest_path: manifestPath,
                 version: null,
                 source: reportable.source,
                 sha: reportable.sha,
                 upgrade_command: CANONICAL_UPGRADE_COMMAND,
                 upgrading_doc_url: UPGRADING_DOC_URL,
-            },
+            }),
         };
     }
     return {
@@ -875,11 +897,11 @@ export function checkStaleXbriefSchemaDeposit(projectRoot, seams = {}) {
         status: "fail",
         detail: `Stale deposited schema at ${STALE_VBRIEF_CORE_SCHEMA_REL} still carries the legacy ${LEGACY_INFO_ROOT_KEY} root key on an already-migrated xbrief/ layout. ` +
             "Run `directive update` to refresh deposited schema files — not `deft migrate:xbrief` (no vbrief/ tree remains to convert).",
-        data: {
+        data: stampAdvisory({
             schema_path: schemaPath,
             convergence_state: convergence.state,
             suggested_fix: "directive update",
-        },
+        }),
     };
 }
 const TS7_SIDE_BY_SIDE_CHECK = "typescript-7-side-by-side";
@@ -1011,11 +1033,11 @@ export function checkTypescript7SideBySide(projectRoot, seams = {}) {
         detail: "typescript resolves to 7.x without the @typescript/typescript6 alias while typescript-eslint and eslint are present. " +
             "Until TS 7.1, use the side-by-side alias pattern in languages/typescript.md § TypeScript 7 side-by-side (pre-7.1) " +
             "(Cartograph #111: keep typescript on npm:@typescript/typescript6 and install TS 7 under @typescript/native).",
-        data: {
+        data: stampAdvisory({
             package_json_path: packageJsonPath,
             typescript: typescriptValue,
             suggested_fix: "languages/typescript.md#typescript-7-side-by-side-pre-71",
-        },
+        }),
     };
 }
 /**
@@ -1062,11 +1084,11 @@ export function checkGitignoreCoverage(projectRoot, seams = {}) {
             `missing (${missing.slice(0, 3).join(", ")}${missing.length > 3 ? ", …" : ""}). ` +
             "Run `directive update` to add the missing entries (idempotent, safe on re-run). " +
             `Full missing list: ${JSON.stringify(missing)}.`,
-        data: {
+        data: stampAdvisory({
             gitignore_path: gitignorePath,
             missing,
             suggested_fix: "directive update",
-        },
+        }),
     };
 }
 /**
@@ -1181,20 +1203,10 @@ export function checkCoverageCheckResumePolicy(projectRoot) {
     };
 }
 export function deriveExitCode(checks, errors) {
-    const exitExempt = new Set([
-        "canonical-vendored-npm-signpost",
-        "manifest-version-reportable",
-        "gitignore-coverage",
-        "stale-xbrief-schema-deposit",
-        "typescript-7-side-by-side",
-        "coverage-check-resume-policy",
-        // Historical pre-#2862 completed/ corpora; hard fail is scope:complete (#3242).
-        "completed-open-items",
-    ]);
     if (errors.length > 0 || checks.some((c) => c.status === "error")) {
         return 2;
     }
-    if (checks.some((c) => c.status === "fail" && !exitExempt.has(c.name))) {
+    if (checks.some((c) => c.status === "fail" && !isDoctorAdvisoryFail(c.name, c.data))) {
         return 1;
     }
     return 0;

package/dist/doctor/doctor-state.d.ts

@@ -11,6 +11,10 @@ export declare function writeState(projectRoot: string, payload: {
 export declare function decideThrottle(state: DoctorState | null, now?: Date): ThrottleDecision;
 export declare function formatUtcIso(when: Date): string;
 export declare function formatIsoZ(when: Date | null): string;
+/** Dirty doctor / ritual copy: --full re-probes only; do not prescribe a write (#3379). */
+export declare const DOCTOR_HARD_ERROR_NOTE = "these are hard errors (advisory warnings do not block writes)";
+export declare const DOCTOR_DIRTY_REPROBE_HINT = "run `deft doctor --full` to re-probe only";
+export declare function dirtyDoctorHint(): string;
 export declare function renderDoctorStatusLine(decision: ThrottleDecision, now?: Date): string;
 export {};
 //# sourceMappingURL=doctor-state.d.ts.map

package/dist/doctor/doctor-state.js

@@ -126,6 +126,12 @@ export function formatIsoZ(when) {
     }
     return formatUtcIso(when);
 }
+/** Dirty doctor / ritual copy: --full re-probes only; do not prescribe a write (#3379). */
+export const DOCTOR_HARD_ERROR_NOTE = "these are hard errors (advisory warnings do not block writes)";
+export const DOCTOR_DIRTY_REPROBE_HINT = "run `deft doctor --full` to re-probe only";
+export function dirtyDoctorHint() {
+    return `${DOCTOR_HARD_ERROR_NOTE}; ${DOCTOR_DIRTY_REPROBE_HINT}`;
+}
 export function renderDoctorStatusLine(decision, now = new Date()) {
     const ageH = Math.max(Math.floor(decision.ageHours), 0);
     if (decision.dirty) {
@@ -133,7 +139,7 @@ export function renderDoctorStatusLine(decision, now = new Date()) {
         const warns = Math.max(decision.lastFindingCount - decision.lastErrorCount, 0);
         const errPhrase = `${errs} error${errs !== 1 ? "s" : ""}`;
         const warnPhrase = `${warns} warning${warns !== 1 ? "s" : ""}`;
-        return `[doctor] ran ${ageH}h ago, ${errPhrase} / ${warnPhrase} -- UNRESOLVED; run \`deft doctor --full\` to re-probe or address findings.`;
+        return `[doctor] ran ${ageH}h ago, ${errPhrase} / ${warnPhrase} -- UNRESOLVED; ${DOCTOR_HARD_ERROR_NOTE}. ${DOCTOR_DIRTY_REPROBE_HINT}.`;
     }
     const remainingMs = (decision.nextEligibleAt?.getTime() ?? now.getTime()) - now.getTime();
     const remainingH = Math.max(Math.floor(remainingMs / 3_600_000), 0);

package/dist/doctor/main.js

@@ -12,9 +12,9 @@ import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
 import { evaluateAgentHooks } from "../verify-env/agent-hooks.js";
 import { probeAgentHooksLive } from "../verify-env/agent-hooks-live-probe.js";
 import { agentsRefreshPlan, hasV3ManagedMarker } from "./agents-md.js";
-import { checkXbriefEnvelopeMajorVersion, runChecks, XBRIEF_ENVELOPE_MAJOR_CHECK, XBRIEF_ENVELOPE_MIGRATE_COMMAND, } from "./checks.js";
+import { checkXbriefEnvelopeMajorVersion, DOCTOR_ADVISORY_FAIL_CHECKS, runChecks, XBRIEF_ENVELOPE_MAJOR_CHECK, XBRIEF_ENVELOPE_MIGRATE_COMMAND, } from "./checks.js";
 import { CONSUMER_FRAMEWORK_DIRS, EXPECTED_CONTENT_DIRS, EXPECTED_FRAMEWORK_DIRS, NETWORK_DISCLOSURE_LINE, PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE, TASKFILE_INCLUDE_SNIPPET, UV_INSTALL_URL, } from "./constants.js";
-import { decideThrottle, formatIsoZ, readState, renderDoctorStatusLine, writeState, } from "./doctor-state.js";
+import { decideThrottle, dirtyDoctorHint, formatIsoZ, readState, renderDoctorStatusLine, writeState, } from "./doctor-state.js";
 import { formatAllowedFlagsHint, formatUnknownFlagsError, parseDoctorFlags } from "./flags.js";
 import { formatDoctorHelp } from "./help.js";
 import { pythonJsonDump } from "./json.js";
@@ -166,9 +166,7 @@ export function cmdDoctor(args, seams = {}) {
             runLocalSignpostChecks(projectRoot, throttleSink, (finding) => {
                 throttleFindings.push(finding);
             }, seams);
-            const hint = decision.dirty
-                ? "run `deft doctor --full` to re-probe or address findings"
-                : "--full forces";
+            const hint = decision.dirty ? dirtyDoctorHint() : "--full forces";
             if (jsonMode) {
                 const payload = {
                     status: "throttle-skipped",
@@ -700,22 +698,14 @@ function runInstallIntegrityChecks(projectRoot, sink, addFinding, seams) {
                     return null;
                 }
             });
-        const result = runChecks(projectRoot, { isDir, isFile, readText });
-        // Exit-exempt check fails stay warnings so lastErrorCount stays 0
-        // (gated ritual / PreToolUse). Keep completed-lifecycle-consistency hard.
-        const warningOnFail = new Set([
-            "legacy-layout",
-            "canonical-vendored-npm-signpost",
-            "manifest-version-reportable",
-            "gitignore-coverage",
-            "stale-xbrief-schema-deposit",
-            "typescript-7-side-by-side",
-            "completed-open-items",
-        ]);
+        const result = (seams.runChecks ?? runChecks)(projectRoot, { isDir, isFile, readText });
+        // Advisory fails stay warnings so lastErrorCount stays 0
+        // (gated ritual / PreToolUse). Hard stays hard: completed-lifecycle-consistency.
         for (const entry of result.checks ?? []) {
             const name = String(entry.name ?? "install-integrity");
             const status = String(entry.status ?? "");
             const detail = String(entry.detail ?? "");
+            const data = entry.data ?? {};
             // Authoritative envelope-major emission is runXbriefEnvelopeVersionCheck
             // (runs for framework repo + consumers). Skip install-integrity duplicate.
             if (name === XBRIEF_ENVELOPE_MAJOR_CHECK) {
@@ -729,7 +719,7 @@ function runInstallIntegrityChecks(projectRoot, sink, addFinding, seams) {
                 sink.info(`${name}: skip -- ${detail}`);
                 continue;
             }
-            if (warningOnFail.has(name) && status === "fail") {
+            if (status === "fail" && (data.advisory === true || DOCTOR_ADVISORY_FAIL_CHECKS.has(name))) {
                 sink.warn(`${name}: ${detail}`);
                 addFinding({
                     severity: "warning",
@@ -737,7 +727,7 @@ function runInstallIntegrityChecks(projectRoot, sink, addFinding, seams) {
                     check: `install-integrity:${name}`,
                     install_check: name,
                     status,
-                    data: entry.data ?? {},
+                    data,
                 });
                 continue;
             }

package/dist/doctor/types.d.ts

@@ -166,6 +166,15 @@ export interface DoctorSeams {
      * its `plan` object; returns [] when no project definition is present.
      */
     readonly detectPlanExtensionShadows?: (projectRoot: string) => readonly ShadowedPlanExtension[];
+    /**
+     * Override install-integrity `runChecks` for tests (#3379). Default is
+     * `runChecks` from `./checks.js`.
+     */
+    readonly runChecks?: (projectRoot: string, seams?: {
+        readonly readText?: (path: string) => string | null;
+        readonly isFile?: (path: string) => boolean;
+        readonly isDir?: (path: string) => boolean;
+    }) => Record<string, unknown>;
     /** Read-only agent-host hook registration probe (#2438). */
     readonly evaluateAgentHooks?: (projectRoot: string) => AgentHookHealthResult;
     /** Live hook spawn probe for doctor --full (#2852). */