@deftai/directive-core 0.90.0 → 0.92.0

package/dist/doctor/openclaw-skills.js

@@ -1,16 +1,22 @@
 /**
- * OpenClaw always-pin skill detect + doctor --fix wire (#3001).
+ * OpenClaw always-pin skill detect + doctor --fix wire (#3001 / #3008).
  *
  * When OpenClaw signals are present, doctor checks the main workspace skills
  * root for the four always-pin skills (#2508). Missing pins emit a warning with
- * remediation `deft doctor --fix`. Under fixMode, pins are symlinked (preferred)
- * or copied from the installed content package into the target skills dir.
+ * remediation `deft doctor --fix`. Under fixMode, pins are **copied** into the
+ * workspace skills root (not symlinked into the npm content package).
+ *
+ * OpenClaw 2026.7.x rejects workspace skills that resolve outside the configured
+ * skills root (`reason=symlink-escape`). A pin that is only a symlink into
+ * `@deftai/directive-content` therefore looks "present" on disk while the host
+ * never loads it (#3008). Prefer real directory copies; treat escaping
+ * symlinks as divergent so `--fix` can replace them.
  *
  * Multi-seat (`workspace-*`) targets only when `--openclaw-all-agents` is set.
  */
-import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, rmSync, statSync, symlinkSync, } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { join, relative, resolve, sep } from "node:path";
 import { contentRoot } from "../content-root.js";
 /** Stable doctor check id for JSON findings. */
 export const OPENCLAW_SKILL_PINS_CHECK = "openclaw-skill-pins";
@@ -159,18 +165,57 @@ function skillHasBody(skillDir, isFile, isDir) {
     // Accept dir or symlink-to-dir that contains SKILL.md
     return isFile(join(skillDir, "SKILL.md"));
 }
+/**
+ * True when both dirs have SKILL.md with identical bytes (pin still current
+ * after package upgrade). False / unreadable → treat as stale (#3008 P1).
+ */
+function skillBodyMatchesPackage(sourceDir, targetDir, isFile) {
+    const src = join(sourceDir, "SKILL.md");
+    const dst = join(targetDir, "SKILL.md");
+    if (!isFile(src) || !isFile(dst))
+        return false;
+    try {
+        return readFileSync(src, "utf8") === readFileSync(dst, "utf8");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True when `path` is a symlink whose resolved real path is outside `skillsDir`
+ * (OpenClaw `symlink-escape` / #3008).
+ */
+export function isEscapingSkillSymlink(skillsDir, path, seams = {}) {
+    const lstatKind = seams.lstatKind ?? defaultLstatKind;
+    if (lstatKind(path) !== "symlink")
+        return false;
+    try {
+        const skillsReal = realpathSync(skillsDir);
+        const pathReal = realpathSync(path);
+        const rel = relative(skillsReal, pathReal);
+        // Outside root, or walks up with ".."
+        return rel === "" || rel.startsWith(`..${sep}`) || rel.startsWith("..") || rel === "..";
+    }
+    catch {
+        // Broken symlink / unreadable realpath — treat as escape / unusable.
+        return true;
+    }
+}
 /**
  * Assess which always-pins are present / missing / divergent in a skills root.
  *
- * - present: directory (or symlink) with SKILL.md
+ * - present: real directory (or non-escaping symlink) with SKILL.md matching
+ *   the content package when `contentBase` is supplied
  * - missing: path does not exist
- * - divergent: path exists but is not a usable pin (file, empty dir, broken link)
+ * - divergent: path exists but is not a usable OpenClaw pin (file, empty dir,
+ *   broken link, **escaping symlink**, or **stale SKILL.md** vs package — #3008)
  */
-export function assessOpenClawPins(skillsDir, seams = {}) {
+export function assessOpenClawPins(skillsDir, seams = {}, options = {}) {
     const isDir = seams.isDir ?? defaultIsDir;
     const isFile = seams.isFile ?? defaultIsFile;
     const pathExists = seams.pathExists ?? defaultPathExists;
     const lstatKind = seams.lstatKind ?? defaultLstatKind;
+    const contentBase = options.contentBase;
     const present = [];
     const missing = [];
     const divergent = [];
@@ -181,7 +226,21 @@ export function assessOpenClawPins(skillsDir, seams = {}) {
             missing.push(skillId);
             continue;
         }
+        // Escaping symlink: SKILL.md may resolve, but OpenClaw skips load (#3008).
+        if (kind === "symlink" && isEscapingSkillSymlink(skillsDir, target, { lstatKind })) {
+            divergent.push(skillId);
+            continue;
+        }
         if (skillHasBody(target, isFile, isDir)) {
+            if (contentBase) {
+                const sourceDir = resolvePinSourceDir(contentBase, skillId);
+                if (!skillBodyMatchesPackage(sourceDir, target, isFile)) {
+                    // Stale copy after package upgrade — surface as divergent so doctor
+                    // does not report "present" and skip repair (#3008 Greptile P1).
+                    divergent.push(skillId);
+                    continue;
+                }
+            }
             present.push(skillId);
             continue;
         }
@@ -218,8 +277,19 @@ function defaultCopyDir(src, dst) {
     cpSync(src, dst, { recursive: true });
 }
 /**
- * Install one pin into a skills root. Prefer symlink; copy on failure.
- * Never deletes user skills. Divergent targets require force or TTY confirm.
+ * Install one pin into a skills root.
+ *
+ * Default: **copy** into the workspace skills root (#3008). OpenClaw rejects
+ * skills that resolve outside the workspace skills root via symlink-escape, so
+ * symlinking into the npm content package leaves pins unloaded while doctor
+ * reports "present". Opt into legacy symlink-first with `preferSymlink: true`
+ * (still falls back to copy). Never deletes unrelated user skills. Divergent
+ * targets (including escaping symlinks) require force or TTY confirm.
+ *
+ * Stale copies (SKILL.md differs from package) are not "already-present" —
+ * doctor --fix refreshes them so upgrades land without manual delete (#3008 P1).
+ * Forced replace stages into a sibling temp dir first so a failed copy does not
+ * leave the pin permanently deleted (#3008 P1).
  */
 export function installOpenClawPin(skillId, sourceDir, skillsDir, options = {}, seams = {}) {
     const isFile = seams.isFile ?? defaultIsFile;
@@ -234,8 +304,11 @@ export function installOpenClawPin(skillId, sourceDir, skillsDir, options = {},
         });
     const copyDir = seams.copyDir ?? defaultCopyDir;
     const removePath = seams.removePath ?? ((p) => rmSync(p, { recursive: true, force: true }));
+    const renamePath = seams.renamePath ?? ((from, to) => renameSync(from, to));
     const target = join(skillsDir, skillId);
     const force = options.force === true || options.allowOverwrite === true;
+    const preferSymlink = options.preferSymlink === true;
+    const refreshStale = options.refreshStale === true;
     if (!isDir(sourceDir) || !isFile(join(sourceDir, "SKILL.md"))) {
         return {
             skillId,
@@ -248,43 +321,199 @@ export function installOpenClawPin(skillId, sourceDir, skillsDir, options = {},
     mkdirp(skillsDir);
     const kind = lstatKind(target);
     if (kind !== "missing") {
-        if (skillHasBody(target, isFile, isDir)) {
-            return {
-                skillId,
-                method: "already-present",
-                target,
-                source: sourceDir,
-            };
+        const escaping = kind === "symlink" && isEscapingSkillSymlink(skillsDir, target, { lstatKind });
+        if (!escaping && skillHasBody(target, isFile, isDir)) {
+            const matches = skillBodyMatchesPackage(sourceDir, target, isFile);
+            if (matches) {
+                return {
+                    skillId,
+                    method: "already-present",
+                    target,
+                    source: sourceDir,
+                };
+            }
+            // Stale copy after package upgrade — refresh under --fix / force.
+            if (!force && !refreshStale) {
+                return {
+                    skillId,
+                    method: "skipped",
+                    target,
+                    source: sourceDir,
+                    detail: "stale pin (SKILL.md differs from content package); re-run with --force or doctor --fix to refresh",
+                };
+            }
+            // fall through to safe replace
         }
-        if (!force) {
+        else if (!force) {
             return {
                 skillId,
                 method: "skipped",
                 target,
                 source: sourceDir,
-                detail: "divergent target exists; re-run with --force or confirm on TTY to replace",
+                detail: escaping
+                    ? "escaping symlink (OpenClaw symlink-escape); re-run with --force to replace with a real copy (#3008)"
+                    : "divergent target exists; re-run with --force or confirm on TTY to replace",
             };
         }
-        removePath(target);
     }
+    if (preferSymlink && kind === "missing") {
+        try {
+            symlinkDir(sourceDir, target);
+            return { skillId, method: "symlink", target, source: sourceDir };
+        }
+        catch {
+            // fall through to copy
+        }
+    }
+    // Exclusive lock dir serializes concurrent doctor --fix on the same pin
+    // (non-recursive mkdir fails with EEXIST — atomic on win32 + posix). No
+    // writeFileSync (contained-writes #2951). Crash recovery: reclaim locks older
+    // than 10 minutes (pin install is seconds; long steal window is intentional).
+    const lockDir = `${target}.deft-lock`;
+    const STALE_LOCK_MS = 10 * 60 * 1000;
+    const tryAcquireLock = () => {
+        try {
+            mkdirSync(lockDir);
+            return true;
+        }
+        catch {
+            try {
+                const ageMs = Date.now() - statSync(lockDir).mtimeMs;
+                if (ageMs >= STALE_LOCK_MS) {
+                    rmSync(lockDir, { recursive: true, force: true });
+                    mkdirSync(lockDir);
+                    return true;
+                }
+            }
+            catch {
+                try {
+                    mkdirSync(lockDir);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }
+            return false;
+        }
+    };
+    if (!tryAcquireLock()) {
+        return {
+            skillId,
+            method: "skipped",
+            target,
+            source: sourceDir,
+            detail: "another doctor process is installing this pin; re-run after it finishes",
+        };
+    }
+    const releaseLock = () => {
+        try {
+            removePath(lockDir);
+        }
+        catch {
+            // ignore
+        }
+    };
+    // Stage copy first so a failed install never deletes the prior target without
+    // a replacement ready (#3008 Greptile P1: failed copies lose replaced targets).
+    // Unique suffix avoids leftover collision if a prior crash left staging files.
+    const swapId = `${process.pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    const staging = `${target}.deft-installing-${swapId}`;
     try {
-        symlinkDir(sourceDir, target);
-        return { skillId, method: "symlink", target, source: sourceDir };
+        removePath(staging);
     }
     catch {
+        // ignore missing staging
+    }
+    try {
+        copyDir(sourceDir, staging);
+    }
+    catch (err) {
         try {
-            copyDir(sourceDir, target);
-            return { skillId, method: "copy", target, source: sourceDir };
+            removePath(staging);
         }
-        catch (err) {
-            return {
-                skillId,
-                method: "skipped",
-                target,
-                source: sourceDir,
-                detail: `install failed: ${err instanceof Error ? err.message : String(err)}`,
-            };
+        catch {
+            // ignore cleanup
         }
+        releaseLock();
+        return {
+            skillId,
+            method: "skipped",
+            target,
+            source: sourceDir,
+            detail: `install failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // Re-check under the lock: another process may have already refreshed to a
+    // matching real copy. Escaping symlinks still match SKILL.md bytes through
+    // the link — never short-circuit those; they must become real copies.
+    const kindUnderLock = lstatKind(target);
+    const escapingUnderLock = kindUnderLock === "symlink" && isEscapingSkillSymlink(skillsDir, target, { lstatKind });
+    if (kindUnderLock !== "missing" &&
+        !escapingUnderLock &&
+        skillHasBody(target, isFile, isDir) &&
+        skillBodyMatchesPackage(sourceDir, target, isFile)) {
+        try {
+            removePath(staging);
+        }
+        catch {
+            // ignore
+        }
+        releaseLock();
+        return {
+            skillId,
+            method: "already-present",
+            target,
+            source: sourceDir,
+        };
+    }
+    const backup = kindUnderLock !== "missing" ? `${target}.deft-backup-${swapId}` : null;
+    try {
+        if (backup !== null) {
+            try {
+                removePath(backup);
+            }
+            catch {
+                // ignore
+            }
+            renamePath(target, backup);
+        }
+        renamePath(staging, target);
+        if (backup !== null) {
+            try {
+                removePath(backup);
+            }
+            catch {
+                // leftover backup is harmless
+            }
+        }
+        releaseLock();
+        return { skillId, method: "copy", target, source: sourceDir };
+    }
+    catch (err) {
+        // Restore backup if we moved it away and the swap failed.
+        try {
+            removePath(staging);
+        }
+        catch {
+            // ignore
+        }
+        if (backup !== null && lstatKind(target) === "missing" && lstatKind(backup) !== "missing") {
+            try {
+                renamePath(backup, target);
+            }
+            catch {
+                // best-effort restore
+            }
+        }
+        releaseLock();
+        return {
+            skillId,
+            method: "skipped",
+            target,
+            source: sourceDir,
+            detail: `install failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
     }
 }
 /**
@@ -318,7 +547,7 @@ export function runOpenClawSkillPinsCheck(sink, addFinding, options) {
     const divergentByDir = [];
     let allPresent = true;
     for (const skillsDir of skillsDirs) {
-        const assessment = assessOpenClawPins(skillsDir, { isDir, isFile, lstatKind: seams.lstatKind });
+        const assessment = assessOpenClawPins(skillsDir, { isDir, isFile, lstatKind: seams.lstatKind }, { contentBase });
         if (assessment.missing.length > 0) {
             allPresent = false;
             missingByDir.push({ skillsDir, missing: [...assessment.missing] });
@@ -363,21 +592,35 @@ export function runOpenClawSkillPinsCheck(sink, addFinding, options) {
                     isDir,
                     isFile,
                     lstatKind: seams.lstatKind,
-                });
+                }, { contentBase });
                 const toInstall = new Set([
                     ...assessment.missing,
                     ...(options.force ? assessment.divergent : []),
                 ]);
-                if (!options.force && assessment.divergent.length > 0 && isTty() && !options.jsonMode) {
+                // Stale pins (SKILL.md ≠ package) are classified divergent; under --fix
+                // refresh them without TTY confirm (safe overwrite of our own pins).
+                if (!options.force) {
                     for (const skillId of assessment.divergent) {
-                        if (readYn(`Replace divergent OpenClaw skill dir ${join(skillsDir, skillId)} with pin from content package?`, false)) {
+                        const sourceDir = resolvePinSourceDir(contentBase, skillId);
+                        const target = join(skillsDir, skillId);
+                        if (skillHasBody(target, isFile, isDir) &&
+                            !skillBodyMatchesPackage(sourceDir, target, isFile)) {
                             toInstall.add(skillId);
+                            continue;
+                        }
+                        if (isTty() && !options.jsonMode) {
+                            if (readYn(`Replace divergent OpenClaw skill dir ${join(skillsDir, skillId)} with pin from content package?`, false)) {
+                                toInstall.add(skillId);
+                            }
                         }
                     }
                 }
                 for (const skillId of toInstall) {
                     const sourceDir = resolvePinSourceDir(contentBase, skillId);
-                    const result = installOpenClawPin(skillId, sourceDir, skillsDir, { force: options.force || assessment.divergent.includes(skillId) }, seams);
+                    const result = installOpenClawPin(skillId, sourceDir, skillsDir, {
+                        force: options.force || assessment.divergent.includes(skillId),
+                        refreshStale: true,
+                    }, seams);
                     installResults.push(result);
                     if (result.method === "symlink" || result.method === "copy") {
                         sink.success(`OpenClaw pin ${skillId}: ${result.method} → ${result.target}${result.method === "symlink" ? ` (from ${result.source})` : ""}`);
@@ -395,7 +638,7 @@ export function runOpenClawSkillPinsCheck(sink, addFinding, options) {
         let stillMissing = false;
         const postMissing = [];
         for (const skillsDir of skillsDirs) {
-            const post = assessOpenClawPins(skillsDir, { isDir, isFile, lstatKind: seams.lstatKind });
+            const post = assessOpenClawPins(skillsDir, { isDir, isFile, lstatKind: seams.lstatKind }, { contentBase });
             if (post.missing.length > 0 || post.divergent.length > 0) {
                 stillMissing = true;
                 postMissing.push(...post.missing.map((id) => `${skillsDir}/${id}`), ...post.divergent.map((id) => `${skillsDir}/${id} (divergent)`));

package/dist/eval/health.d.ts

@@ -40,7 +40,16 @@ export interface EvaluateHealthResult {
 }
 /** Absolute path to the versioned health history ledger (#2545). */
 export declare function healthHistoryPath(projectRoot: string): string | null;
-/** Detect the canonical wipCap unsatisfiable-nudge contradiction (#1694). */
+/**
+ * Residual regression detector for the #1694 wipCap unsatisfiable-nudge.
+ *
+ * Pre-fix: classify treated absent `plan.policy.wipCap` as incomplete while
+ * omit-by-design (#1186 D1) made materializing the default a self-check trap.
+ * The fix records decision-provenance out-of-band (`x-directive/onboarding`),
+ * so greenfield "missing wipCap decision" is satisfiable without materializing
+ * the value field. This detector now only fires if a decision marker is set
+ * but classify still lists wipCap as missing (classifier regression).
+ */
 export declare function detectWipCapUnsatisfiableNudge(projectRoot: string): ContradictionEvidence | null;
 /** Run all registered contradictory-gate detectors. */
 export declare function detectContradictoryGates(projectRoot: string): ContradictionEvidence[];

package/dist/eval/health.js

@@ -6,7 +6,6 @@ import { readCorePackageVersion } from "../engine-version.js";
 import { containedWrite } from "../fs/contained-write.js";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { healthMetricsHistoryPath } from "../metrics/resolve-metrics-home.js";
-import { readPlanPolicy } from "../policy/plan-extensions.js";
 import { classifyOnboarding, detectPriorState } from "../triage/welcome/prior-state.js";
 import { validateLinks } from "../validate-content/index.js";
 import { evaluateConformance } from "../vbrief-validate/conformance.js";
@@ -106,26 +105,27 @@ function probeContentManifest(projectRoot) {
 export function healthHistoryPath(projectRoot) {
     return healthMetricsHistoryPath(projectRoot);
 }
-/** Detect the canonical wipCap unsatisfiable-nudge contradiction (#1694). */
+/**
+ * Residual regression detector for the #1694 wipCap unsatisfiable-nudge.
+ *
+ * Pre-fix: classify treated absent `plan.policy.wipCap` as incomplete while
+ * omit-by-design (#1186 D1) made materializing the default a self-check trap.
+ * The fix records decision-provenance out-of-band (`x-directive/onboarding`),
+ * so greenfield "missing wipCap decision" is satisfiable without materializing
+ * the value field. This detector now only fires if a decision marker is set
+ * but classify still lists wipCap as missing (classifier regression).
+ */
 export function detectWipCapUnsatisfiableNudge(projectRoot) {
     const loaded = loadPlan(projectRoot);
     if (loaded === null) {
         return null;
     }
-    const { plan, filepath } = loaded;
-    const policy = readPlanPolicy(plan);
-    const wipCapPresent = typeof policy === "object" &&
-        policy !== null &&
-        !Array.isArray(policy) &&
-        "wipCap" in policy;
-    if (wipCapPresent) {
-        return null;
-    }
     const state = detectPriorState(projectRoot);
     const [, missing] = classifyOnboarding(state);
-    if (!missing.includes("wipCap")) {
+    if (!(state.wipCapDecided && missing.includes("wipCap"))) {
         return null;
     }
+    const { plan, filepath } = loaded;
     const validatorErrors = validateWipCapOnPlan(plan, filepath);
     if (validatorErrors.length > 0) {
         return null;
@@ -133,11 +133,11 @@ export function detectWipCapUnsatisfiableNudge(projectRoot) {
     return {
         id: "wipCap-unsatisfiable-nudge",
         kind: "unsatisfiable-nudge",
-        summary: "Onboarding completeness treats absent plan.policy.wipCap as incomplete, but omit-by-design accepts absence as valid (#1694 / #1186 D1).",
+        summary: "wipCap decision marker is set but classifyOnboarding still lists wipCap as missing (#1694 regression).",
         signals: [
-            "classifyOnboarding: wipCap listed in missing onboarding signals",
-            "validateWipCapOnPlan: omitted wipCap is valid",
-            "triage:welcome --onboard nudge cannot clear without violating omit-by-design contract",
+            "x-directive/onboarding.wipCapDecided: true",
+            "classifyOnboarding: wipCap still in missing onboarding signals",
+            "decision-provenance and completeness classifier are out of sync",
         ],
     };
 }

package/dist/hooks/dispatcher.d.ts

@@ -1,4 +1,5 @@
 import { type AuthzState, type HumanOriginGrant } from "../authz/index.js";
+import { detectDeftDirectiveDisable } from "../policy/deft-directive-disable.js";
 import { detectNoDeftDirective } from "../policy/no-deft-directive.js";
 import { type RuntimeAuthorityPolicy } from "../policy/runtime-authority.js";
 import { type VerifyResult } from "../session/verify-session-ritual.js";
@@ -16,7 +17,9 @@ export type CompactHookHost = (typeof COMPACT_HOOK_HOSTS)[number];
 /** Hosts without a native compact hook surface — deposit skips cleanly (#2113). */
 export declare const COMPACT_HOOK_SKIP_HOSTS: readonly ["codex"];
 export type HookVerdict = "allow" | "deny";
-export type HookDecisionCode = "session-start" | "session-start-disabled" | "session-start-degraded" | "session-compact-rearm" | "session-compact-rearm-degraded" | "session-compact-noop" | "not-direct-write" | "invalid-input"
+export type HookDecisionCode = "session-start" | "session-start-disabled" | "session-start-degraded"
+/** Enforcement skipped: root `.deft-directive-disable` test kill-switch (#3039). */
+ | "directive-disabled" | "session-compact-rearm" | "session-compact-rearm-degraded" | "session-compact-noop" | "not-direct-write" | "invalid-input"
 /** Host closed stdin with zero bytes — integration failure, not a policy gate (#2864). */
  | "stdin-empty" | "ritual-not-ready" | "scope-not-ready" | "write-propose-ready" | "write-ready" | "read-only-deny" | "spawn-explore-ready" | "spawn-ready" | "spawn-not-ready" | "runtime-policy-deny-path" | "runtime-policy-deny-scope"
 /** Shell/MCP classifiable push/merge allowed under runtimeAuthority (#2711). */
@@ -56,6 +59,8 @@ export interface HookPolicySeams {
     };
     /** Test seam for #2926 root opt-out on SessionStart. */
     readonly detectNoDeftDirective?: typeof detectNoDeftDirective;
+    /** Test seam for #3039 root test kill-switch (precedence over #2926 for enforcement). */
+    readonly detectDeftDirectiveDisable?: typeof detectDeftDirectiveDisable;
     readonly markCompactStale?: (projectRoot: string) => {
         changed: boolean;
         statePath: string;

package/dist/hooks/dispatcher.js

@@ -2,6 +2,7 @@ import { realpathSync } from "node:fs";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { appendAuthzAudit, classifyHookAuthzOps, evaluateAuthzMutation, evidenceSatisfiesImplementationApproval, listActiveHumanGrants, loadAuthzStateResult, markGrantUsed, shouldConsumeSingleUseGrant, utcIso, } from "../authz/index.js";
 import { hasArtifactSuffix } from "../layout/resolve.js";
+import { detectDeftDirectiveDisable, formatDeftDirectiveDisableMessage, isDeftDirectiveDisableActive, } from "../policy/deft-directive-disable.js";
 import { evaluateIntentCeilingFromEnv } from "../policy/intent-ceiling.js";
 import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, } from "../policy/no-deft-directive.js";
 import { classifyMcpTool, DEFAULT_RUNTIME_AUTHORITY_POLICY, evaluateRuntimeAuthorityDirectWrite, evaluateRuntimeAuthorityShellOp, listShellOps, loadRuntimeAuthorityFromProject, } from "../policy/runtime-authority.js";
@@ -570,6 +571,35 @@ function inspectMutationGates(input, toolName, seams, options) {
 /** Decide a normalized event using only the P0 direct-write policy. */
 export function decideHook(input, seams = {}) {
     const projectRoot = resolve(input.projectRoot);
+    // #3039: local (untracked) `.deft-directive-disable` wins for enforcement
+    // short-circuit (SessionStart / compact / PreToolUse). Deposit may remain.
+    // Tracked/committed flags do NOT bypass gates (repo-controlled content must
+    // not disable enforcement for clones) — doctor warns instead.
+    {
+        const detectKill = seams.detectDeftDirectiveDisable ?? detectDeftDirectiveDisable;
+        const kill = detectKill(projectRoot);
+        const killActive = seams.detectDeftDirectiveDisable !== undefined
+            ? kill.active
+            : isDeftDirectiveDisableActive(projectRoot);
+        if (killActive) {
+            const detectOptOut = seams.detectNoDeftDirective ?? detectNoDeftDirective;
+            const optOut = detectOptOut(projectRoot);
+            const message = formatDeftDirectiveDisableMessage({
+                permanentOptOutAlsoPresent: optOut.present,
+                trackedByGit: false,
+            });
+            return {
+                verdict: "allow",
+                code: input.event === "session.start" ? "session-start-disabled" : "directive-disabled",
+                event: input.event,
+                host: input.host,
+                toolName: null,
+                projectRoot,
+                message,
+                scopePath: null,
+            };
+        }
+    }
     if (input.event === "session.compact") {
         try {
             const result = (seams.markCompactStale ?? markRitualStaleAfterCompact)(projectRoot);

package/dist/init-deposit/gitignore.js

@@ -13,6 +13,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { containedWrite } from "../fs/contained-write.js";
 import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
+import { DEFT_DIRECTIVE_DISABLE_GITIGNORE_LINE } from "../policy/deft-directive-disable.js";
 import { FORBIDDEN_BLANKET_EVAL_LINES, stripGitignoreInlineComment, } from "../triage/bootstrap/gitignore.js";
 /** Directory ignore entry for the hybrid deposit (greenfield only). */
 export const GITIGNORE_DEFT_CORE_LINE = ".deft/core/";
@@ -29,6 +30,8 @@ export const CANONICAL_GITIGNORE_BASELINE = [
     ".deft/ritual-state.json",
     ".deft/last-session.json",
     ".deft/routing.local.json",
+    // Temporary test/local kill-switch — must stay untracked (#3039).
+    DEFT_DIRECTIVE_DISABLE_GITIGNORE_LINE,
     "vbrief/.triage-cache/candidates.jsonl",
     "vbrief/.triage-cache/summary-history.jsonl",
     "vbrief/.triage-cache/scope-lifecycle.jsonl",

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

@@ -2,7 +2,13 @@
  * Scoped staging + installer-managed allowlist for TS-native init/update (#1453).
  *
  * Mirrors cmd/deft-install/hygiene.go + deposit.go installerManagedMatchers.
- * Refs #1576, #1453, #1430.
+ *
+ * CRITICAL (#1430 / #3030): the allowlist MUST honor the SPEC consumer-path
+ * denylist (`CONSUMER_GUARD_MUST_FIRE`). Consumer-authored PROJECT-DEFINITION
+ * and scope briefs are never installer-managed; if they reappear in
+ * `installerManagedMatchers()`, unit tests and deposit-time assert fail closed.
+ *
+ * Refs #1576, #1453, #1430, #3029, #3030.
  */
 import { type InitDepositIo } from "./constants.js";
 export declare const CODEQL_CONFIG_REL = ".github/codeql/codeql-config.yml";
@@ -11,11 +17,47 @@ export interface InstallerManagedMatcher {
     readonly exact?: string;
     readonly prefix?: string;
 }
+/**
+ * Consumer paths that MUST trip no-mixed-core-and-app when mixed with
+ * `.deft/core/**` (#1430 SPEC). These probe paths must never match
+ * `installerManagedMatchers()` / the deposited guard ERE.
+ *
+ * Legitimate installer scaffolding (xbrief/.deft-version, lifecycle .gitkeep,
+ * schemas/, migration/, xbrief.md) is NOT in this denylist — see #2277.
+ * Init may still *create* PROJECT-DEFINITION (#3013); create ≠ allowlist.
+ *
+ * Refs #3030, #3029, #1430.
+ */
+export declare const CONSUMER_GUARD_MUST_FIRE: readonly string[];
 /** Single source of truth for installer-managed paths (#1440 / #1576). */
 export declare function installerManagedMatchers(): InstallerManagedMatcher[];
+/**
+ * Fail closed when the installer-managed allowlist would exempt consumer
+ * PROJECT-DEFINITION or scope briefs (#3030 / #1430). Pure over `matchers` so
+ * tests can inject a bad matcher without mutating production state.
+ *
+ * Checks both:
+ * 1. Explicit probe paths in {@link CONSUMER_GUARD_MUST_FIRE}
+ * 2. Structural patterns (any exact consumer scope brief / PD; forbidden prefixes)
+ *    so an unlisted `xbrief/active/another-scope.xbrief.json` matcher still fails.
+ */
+export declare function assertInstallerAllowlistHonors1430(matchers?: readonly InstallerManagedMatcher[]): void;
 /** POSIX ERE alternation embedded in the deposited deft-core-guard workflow. */
 export declare function installerManagedGuardEre(): string;
 export declare function isInstallerManagedPath(path: string): boolean;
+export interface MixedCoreAndAppClassification {
+    readonly core: string[];
+    readonly installerManaged: string[];
+    readonly app: string[];
+    /** True when both core and app are non-empty — the deposited guard fails. */
+    readonly wouldFail: boolean;
+}
+/**
+ * TS twin of Go `classifyChangedPaths` / deposited shell guard (#1430).
+ * Core = `.deft/core/**`; installer-managed = allowlist; app = everything else.
+ * Guard fails iff both core and app are non-empty.
+ */
+export declare function classifyMixedCoreAndApp(changedPaths: readonly string[], matchers?: readonly InstallerManagedMatcher[]): MixedCoreAndAppClassification;
 export interface FrameworkStagePathsOptions {
     /**
      * Include the vendored `.deft/core` payload in the stage set. Defaults to