@deftai/directive-core 0.103.0 → 0.105.0

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,11 +698,14 @@ function runInstallIntegrityChecks(projectRoot, sink, addFinding, seams) {
                     return null;
                 }
             });
-        const result = runChecks(projectRoot, { isDir, isFile, readText });
+        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) {
@@ -718,13 +719,7 @@ function runInstallIntegrityChecks(projectRoot, sink, addFinding, seams) {
                 sink.info(`${name}: skip -- ${detail}`);
                 continue;
             }
-            if ((name === "legacy-layout" ||
-                name === "canonical-vendored-npm-signpost" ||
-                name === "manifest-version-reportable" ||
-                name === "gitignore-coverage" ||
-                name === "stale-xbrief-schema-deposit" ||
-                name === "typescript-7-side-by-side") &&
-                status === "fail") {
+            if (status === "fail" && (data.advisory === true || DOCTOR_ADVISORY_FAIL_CHECKS.has(name))) {
                 sink.warn(`${name}: ${detail}`);
                 addFinding({
                     severity: "warning",
@@ -732,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). */

package/dist/fs/contained-write.d.ts

@@ -15,7 +15,20 @@
  * onto this API over bespoke per-sink checks when equivalent. See
  * `docs/reference/contained-write.md`.
  *
- * Refs #2951.
+ * Delete coverage (#3392 / #3456): real dest deletes MUST go through
+ * {@link containedRemove} so a bound ledger (and ADR-004 record mode) records
+ * them. Raw `rmSync` on a dest path is a chokepoint bypass.
+ *
+ * Plan-mode zero-mutation (#3456 / ADR-004): `deft update --dry-run` binds
+ * this port in record mode (`runInPortRecordMode`). Dest write / remove /
+ * chmod / dest-mutating exec record and skip dest IO. Temp-file cleanups
+ * either use this chokepoint or live outside the project root.
+ *
+ * `tryCleanupLegacyDeftTree` is not on the update/dry-run path (classify
+ * refuses `migration-required` first). Its default removeDir still routes
+ * through containedRemove so the site is not a silent exception.
+ *
+ * Refs #2951 / #3392 / #3456.
  */
 /** Stable machine-readable error codes for contained-write refusals. */
 export declare const ContainedWriteErrorCode: {
@@ -78,6 +91,38 @@ export interface ContainedWriteInput {
      * {@link assertWriteTargetSafe}.
      */
     readonly followSymlinks?: boolean;
+    /**
+     * Ledger side-effect (#3392). Default records `wrote` when a ledger is bound.
+     * `false` skips. `kind`/`path` override the recorded entry (atomic tmp+rename).
+     */
+    readonly mutation?: false | {
+        readonly kind?: "wrote" | "stripped";
+        readonly path?: string;
+    };
+}
+export interface ContainedRemoveInput {
+    /** Absolute containment root (project root, deposit root, or sandbox). */
+    readonly root: string;
+    /**
+     * Remove target. Relative paths are resolved under `root`. Absolute paths
+     * must stay under `root` after normalization.
+     */
+    readonly target: string;
+    /**
+     * Ledger side-effect (#3392). Default records `deleted` when a ledger is bound.
+     * `false` skips. `path` overrides the recorded path.
+     */
+    readonly mutation?: false | {
+        readonly path?: string;
+    };
+    /** When true, remove directories recursively. Default `false`. */
+    readonly recursive?: boolean;
+}
+export interface ContainedRemoveResult {
+    /** Absolute path considered for removal. */
+    readonly path: string;
+    /** True when a file existed and was removed. */
+    readonly removed: boolean;
 }
 export interface ContainedWriteResult {
     /** Absolute path written. */
@@ -86,6 +131,37 @@ export interface ContainedWriteResult {
     readonly bytesWritten: number;
     readonly mode: ContainedWriteMode;
 }
+export interface ContainedChmodInput {
+    readonly root: string;
+    readonly target: string;
+    readonly mode: number;
+    readonly mutation?: false | {
+        readonly path?: string;
+    };
+}
+export interface ContainedRenameInput {
+    readonly root: string;
+    readonly from: string;
+    readonly to: string;
+    /**
+     * Default records `wrote` on `to`. `false` skips (caller already ledgered).
+     */
+    readonly mutation?: false | {
+        readonly kind?: "wrote" | "stripped";
+        readonly path?: string;
+    };
+}
+export interface ContainedDestExecInput {
+    readonly root: string;
+    /** Dest path this exec mutates (e.g. `.git/config`). */
+    readonly destTarget: string;
+    readonly file: string;
+    readonly args: readonly string[];
+}
+export interface ContainedDestExecResult {
+    readonly ok: boolean;
+    readonly stdout: string;
+}
 /**
  * Resolve `target` under `root`. Relative targets join root; absolute targets
  * must already be nested under root (path-segment containment).
@@ -98,4 +174,42 @@ export declare function resolveContainedTarget(root: string, target: string): st
  * @throws {ContainedWriteError} on containment refusal or mode violation
  */
 export declare function containedWrite(input: ContainedWriteInput): ContainedWriteResult;
+/**
+ * Contained remove: resolve under root, refuse parent-path symlink / out-of-root,
+ * then delete. An in-root leaf symlink is unlinked (not followed, not refused).
+ * Missing targets are a no-op (not ledgered).
+ *
+ * @throws {ContainedWriteError} on containment refusal
+ */
+export declare function containedRemove(input: ContainedRemoveInput): ContainedRemoveResult;
+/**
+ * Contained mkdir: nest under root. Record mode skips dest IO (dirs are not
+ * dest-file membership). Live path creates recursively.
+ */
+export declare function containedMkdir(input: {
+    readonly root: string;
+    readonly target: string;
+}): {
+    path: string;
+};
+/**
+ * Contained chmod: resolve under root, refuse parent-path symlink / out-of-root,
+ * then set mode. Record mode records `chmod` and skips dest IO.
+ */
+export declare function containedChmod(input: ContainedChmodInput): {
+    path: string;
+};
+/**
+ * Contained rename: both paths must nest under root. Record mode records
+ * `wrote` on `to` (unless `mutation: false`) and skips dest IO.
+ */
+export declare function containedRename(input: ContainedRenameInput): {
+    from: string;
+    to: string;
+};
+/**
+ * Dest-mutating exec (git config, git add, …). Record mode records `exec` on
+ * `destTarget` and skips the child process. Allowlisted as the port impl.
+ */
+export declare function containedDestExec(input: ContainedDestExecInput): ContainedDestExecResult;
 //# sourceMappingURL=contained-write.d.ts.map