@deftai/directive-core 0.85.0 → 0.87.0

package/dist/check/gate-lists.js

@@ -22,6 +22,7 @@ export const FRAMEWORK_CHECK_GATES = [
     "verify:skill-external-fetch-gate",
     "verify:contract-drift",
     "verify:cursor-tier1",
+    "verify:openclaw-tier1",
     "verify:go-freeze",
     "verify:bridge-drift",
     "verify:branch",

package/dist/doctor/constants.d.ts

@@ -14,9 +14,9 @@ export declare const PUBLIC_NPM_REGISTRY = "https://registry.npmjs.org/";
 export declare const NPM_REGISTRY_MIRROR_DOC_URL = "https://github.com/deftai/directive/blob/master/content/UPGRADING.md#corporate-or-mirrored-npm-registry";
 export declare const NETWORK_DISCLOSURE_LINE: string;
 export declare const PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE: string;
-export declare const EXPECTED_FRAMEWORK_DIRS: readonly ["tasks", "scripts", "vbrief"];
+export declare const EXPECTED_FRAMEWORK_DIRS: readonly ["tasks", "scripts", "xbrief"];
 /** npm consumer deposit after #2022 Phase 3 -- Python scripts/ tree is intentionally absent. */
-export declare const CONSUMER_FRAMEWORK_DIRS: readonly ["tasks", "vbrief"];
+export declare const CONSUMER_FRAMEWORK_DIRS: readonly ["tasks", "xbrief"];
 export declare const DEFT_REPO_POSITIVE_MARKERS: readonly ["content/templates/agents-entry.md", "content/skills/deft-directive-build/SKILL.md"];
 export declare const EXPECTED_CONTENT_DIRS: readonly ["languages", "strategies", "skills", "templates"];
 /** Post-freeze canonical upgrade path (#1997 / #2003 / #1912). */

package/dist/doctor/constants.js

@@ -46,9 +46,9 @@ export const PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE = "skip -- offline tier (def
     "(discloses tool + registry before contacting either).";
 // Engine / lifecycle dirs that stay at the framework root (NOT relocated by
 // #1875). Shippable-content dirs moved under content/ -- see EXPECTED_CONTENT_DIRS.
-export const EXPECTED_FRAMEWORK_DIRS = ["tasks", "scripts", "vbrief"];
+export const EXPECTED_FRAMEWORK_DIRS = ["tasks", "scripts", "xbrief"];
 /** npm consumer deposit after #2022 Phase 3 -- Python scripts/ tree is intentionally absent. */
-export const CONSUMER_FRAMEWORK_DIRS = ["tasks", "vbrief"];
+export const CONSUMER_FRAMEWORK_DIRS = ["tasks", "xbrief"];
 // Post-#1875 content/ move: these framework-internal markers now live under
 // content/ in the SOURCE repo. They identify a deft source checkout (a consumer
 // would never reproduce them); the C1 flatten means a consumer deposit has no

package/dist/doctor/main.d.ts

@@ -2,14 +2,16 @@ import { type ResolutionFacts } from "../resolution/index.js";
 import { createPlainSink } from "./output.js";
 import type { DoctorSeams, Finding, ResolutionSummary } from "./types.js";
 export declare function cmdDoctor(args: readonly string[], seams?: DoctorSeams): number;
-export declare function runAgentHooksHealthCheck(projectRoot: string, consumerContext: boolean, sink: ReturnType<typeof createPlainSink>, addFinding: (finding: Finding) => void, seams: DoctorSeams): void;
+export declare function runAgentHooksHealthCheck(projectRoot: string, consumerContext: boolean, sink: ReturnType<typeof createPlainSink>, addFinding: (finding: Finding) => void, seams: DoctorSeams): boolean;
+export declare function runAgentHooksLiveProbeCheck(projectRoot: string, sink: ReturnType<typeof createPlainSink>, addFinding: (finding: Finding) => void, seams: DoctorSeams): void;
 /**
  * Never emit a bare `task ...` remediation in a project without Taskfile wiring
- * (#2267). The `directive` surface always works; `task deft:X` is optional and
- * only present when the consumer wired the include. `plan()` already emits the
- * `directive` / `npx` / `npm` surface, so this guard is a defensive invariant:
- * any `task`-prefixed command is rewritten to the `directive` surface unless the
- * project actually has the include.
+ * (#2267 / #2893). The `directive`/`deft` surface always works; `task deft:X` is
+ * the go-task namespaced form only when the consumer wired the include (bare
+ * `task pr:watch` is not the consumer form under include key `deft:`). `plan()`
+ * already emits the `directive` / `npx` / `npm` surface, so this guard is a
+ * defensive invariant: any `task`-prefixed command is rewritten to the
+ * `directive` surface unless the project actually has the include.
  */
 /**
  * Detect Taskfile wiring through the injected seam (#2267). Mirrors

package/dist/doctor/main.js

@@ -7,6 +7,7 @@ import { loadProjectDefinition } from "../policy/resolve.js";
 import { checkLocalEngineIntegrity, classify, detectPackageManager, evaluateSkew, reconcileVersions, plan as resolvePlan, } from "../resolution/index.js";
 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 { runChecks } 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";
@@ -16,10 +17,10 @@ import { pythonJsonDump } from "./json.js";
 import { parseInstallRootFromAgentsMd } from "./manifest.js";
 import { runNpmRegistryMirrorCheck } from "./npm-registry.js";
 import { createPlainSink } from "./output.js";
-import { readTextSafe, resolveDefaultFrameworkRoot, resolvePath, resolveVersion, runningInsideDeftRepo, } from "./paths.js";
+import { readTextSafe, resolveFrameworkRootForProject, resolvePath, resolveVersion, runningInsideDeftRepo, } from "./paths.js";
 import { runPayloadStalenessCheck } from "./payload-staleness.js";
 import { runLocalSignpostChecks } from "./signpost-checks.js";
-import { classifyTaskfileInclude, formatMissingIncludeSnippet, includesBlockHasDeftTaskfile, resolveConsumerTaskfile, } from "./taskfile.js";
+import { classifyTaskfileInclude, formatGatesSurfaceDualRemediation, formatMissingIncludeSnippet, GATES_SURFACE_DEFT_REMEDIATION, includesBlockHasDeftTaskfile, resolveConsumerTaskfile, } from "./taskfile.js";
 import { defaultWhich } from "./which.js";
 const DEFAULT_RESOLUTION_PLATFORMS = ["linux", "darwin", "win32"];
 /**
@@ -57,7 +58,7 @@ export function cmdDoctor(args, seams = {}) {
     const quietMode = flags.quiet;
     const fullMode = flags.full;
     const projectRoot = resolvePath(flags.projectRoot ?? process.cwd());
-    const frameworkRoot = seams.frameworkRoot ?? resolveDefaultFrameworkRoot();
+    const frameworkRoot = seams.frameworkRoot ?? resolveFrameworkRootForProject(projectRoot);
     const consumerContext = resolve(projectRoot) !== resolve(frameworkRoot);
     const whichFn = seams.whichFn ?? defaultWhich;
     const nowFn = seams.now ?? (() => new Date());
@@ -165,7 +166,17 @@ export function cmdDoctor(args, seams = {}) {
         sink.blank();
     }
     sink.info("Checking agent-host hook registration...");
-    runAgentHooksHealthCheck(projectRoot, consumerContext, sink, addFinding, seams);
+    const findingCountBeforeHooks = findings.length;
+    const hooksHealthy = runAgentHooksHealthCheck(projectRoot, consumerContext, sink, addFinding, seams);
+    if (fullMode && hooksHealthy) {
+        const lastFinding = findings[findings.length - 1];
+        if (findings.length > findingCountBeforeHooks &&
+            lastFinding?.check === "agent-hooks-registration" &&
+            lastFinding?.status === "registered") {
+            findings.pop();
+        }
+        runAgentHooksLiveProbeCheck(projectRoot, sink, addFinding, seams);
+    }
     if (consumerContext) {
         if (!jsonMode) {
             sink.blank();
@@ -280,7 +291,7 @@ export function cmdDoctor(args, seams = {}) {
     if (!jsonMode) {
         sink.blank();
     }
-    sink.info("Checking optional root Taskfile.yml include...");
+    sink.info("Checking gates-surface readiness (Taskfile include for deep-think agent gates)...");
     runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFinding, seams);
     let resolution = null;
     if (!runningInsideDeftRepo(projectRoot, seams)) {
@@ -353,40 +364,81 @@ export function runAgentHooksHealthCheck(projectRoot, consumerContext, sink, add
         const reason = "maintainer source checkout; project hook deposit is consumer-only";
         sink.info(`${checkName}: skip -- ${reason}`);
         addFinding({ severity: "skip", message: reason, check: checkName, status: "skip" });
-        return;
+        return false;
     }
     try {
         const result = (seams.evaluateAgentHooks ?? evaluateAgentHooks)(projectRoot);
-        if (result.code === 0) {
-            const message = `${checkName}: registered and structurally valid; ` +
-                "Codex runtime trust is user-controlled and must be reviewed with `/hooks`";
-            sink.success(message);
+        if (result.code !== 0) {
+            const message = `${checkName}: ${result.message.replace(/\s+/g, " ").trim()}`;
+            sink.warn(message);
             addFinding({
-                severity: "skip",
+                severity: "warning",
                 message,
                 check: checkName,
-                status: "registered",
+                status: result.code === 2 ? "unavailable" : "incomplete",
                 registrations: result.registrations,
-                trust_status: "not-verifiable",
-                trust_review: "Open `/hooks` in Codex and review the project hook commands.",
+                suggestion: "deft update",
             });
-            return;
+            return false;
         }
-        const message = `${checkName}: ${result.message.replace(/\s+/g, " ").trim()}`;
-        sink.warn(message);
+        const message = `${checkName}: registered and structurally valid; ` +
+            "Codex runtime trust is user-controlled and must be reviewed with `/hooks`";
+        sink.success(message);
         addFinding({
-            severity: "warning",
+            severity: "skip",
             message,
             check: checkName,
-            status: result.code === 2 ? "unavailable" : "incomplete",
+            status: "registered",
             registrations: result.registrations,
-            suggestion: "deft update",
+            trust_status: "not-verifiable",
+            trust_review: "Open `/hooks` in Codex and review the project hook commands.",
         });
+        return true;
     }
     catch (cause) {
         const message = `${checkName}: probe failed -- ${String(cause)}`;
         sink.warn(message);
         addFinding({ severity: "warning", message, check: checkName, suggestion: "deft update" });
+        return false;
+    }
+}
+export function runAgentHooksLiveProbeCheck(projectRoot, sink, addFinding, seams) {
+    const checkName = "agent-hooks-registration";
+    const liveCheckName = "agent-hooks-live-probe";
+    try {
+        const result = (seams.evaluateAgentHooks ?? evaluateAgentHooks)(projectRoot);
+        const liveResult = (seams.probeAgentHooksLive ?? probeAgentHooksLive)(projectRoot);
+        if (liveResult.code !== 0) {
+            const message = `${liveCheckName}: ${liveResult.message.replace(/\s+/g, " ").trim()}`;
+            sink.warn(message);
+            addFinding({
+                severity: "warning",
+                message,
+                check: liveCheckName,
+                status: liveResult.code === 2 ? "unavailable" : "non-functional",
+                cases: liveResult.cases,
+                suggestion: "npm i -g @deftai/directive@latest && deft update",
+            });
+            return;
+        }
+        const message = `${checkName}: registered, structurally valid, and live probe passed; ` +
+            "Codex runtime trust is user-controlled and must be reviewed with `/hooks`";
+        sink.success(message);
+        addFinding({
+            severity: "skip",
+            message,
+            check: liveCheckName,
+            status: "registered-and-functional",
+            registrations: result.registrations,
+            trust_status: "not-verifiable",
+            trust_review: "Open `/hooks` in Codex and review the project hook commands.",
+            live_probe: "passed",
+        });
+    }
+    catch (cause) {
+        const message = `${liveCheckName}: probe failed -- ${String(cause)}`;
+        sink.warn(message);
+        addFinding({ severity: "warning", message, check: liveCheckName, suggestion: "deft update" });
     }
 }
 function runInstallIntegrityChecks(projectRoot, sink, addFinding, seams) {
@@ -588,15 +640,21 @@ function runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFindin
     }
     const includeStatus = classifyTaskfileInclude(projectRoot);
     if (includeStatus === "ok") {
-        sink.success("Root Taskfile.yml includes the deft framework");
+        sink.success("Gates-surface ready: root Taskfile.yml includes the deft framework (`task deft:<verb>`)");
         return;
     }
     if (includeStatus === "missing-file") {
         let includeMissing = true;
         const target = join(projectRoot, "Taskfile.yml");
-        const message = "Root Taskfile.yml missing. This is OK for package-manager installs that use the `deft X` surface directly. To also enable the optional `task deft:X` surface, paste this into " +
-            `${target}:`;
-        sink.info(message);
+        // #2893: elevate to warning — deep-think agent gates need a working invoke path.
+        // Dual remediations: (1) deft CLI primary (2) Taskfile include for task deft: verbs.
+        const message = "Gates-surface readiness: root Taskfile.yml missing. Deep-think agent gates " +
+            "(`pr:watch`, `review-monitor:*`) need a working invoke path — not optional convenience. " +
+            "1. " +
+            GATES_SURFACE_DEFT_REMEDIATION +
+            ` 2. Create ${target} with the canonical include so go-task exposes \`task deft:<verb>\` ` +
+            "(include key `deft:` → namespaced tasks; bare `task pr:watch` is not the consumer form):";
+        sink.warn(message);
         if (!jsonMode) {
             sink.blank();
             sink.raw(TASKFILE_INCLUDE_SNIPPET);
@@ -616,22 +674,27 @@ function runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFindin
                 }
             }
             else {
-                sink.info("Skipped Taskfile.yml creation -- paste the snippet above when you are ready.");
+                sink.info("Skipped Taskfile.yml creation -- use `deft <verb>` now, or paste the include snippet when ready.");
             }
         }
         if (includeMissing) {
             addFinding({
                 severity: "warning",
-                message: "Root Taskfile.yml missing; optional Taskfile include unavailable",
+                message: "Gates-surface: root Taskfile.yml missing — deep-think gates need `deft` CLI or `task deft:` include",
                 check: "taskfile-include",
                 file: target,
-                suggestion: TASKFILE_INCLUDE_SNIPPET,
+                suggestion: formatGatesSurfaceDualRemediation("missing-file"),
             });
         }
         return;
     }
     if (includeStatus === "missing-include") {
-        const message = "Root Taskfile.yml exists but does not include the deft framework. The `deft X` surface still works; add this to the Taskfile `includes:` block only if you want the optional `task deft:X` surface (doctor NEVER mutates an existing user-owned Taskfile):";
+        const message = "Gates-surface readiness: root Taskfile.yml exists but does not include the deft framework. " +
+            "Deep-think agent gates (`pr:watch`, `review-monitor:*`) need a working invoke path. " +
+            "1. " +
+            GATES_SURFACE_DEFT_REMEDIATION +
+            " 2. Add this to the Taskfile `includes:` block so go-task exposes `task deft:<verb>` " +
+            "(doctor NEVER mutates an existing user-owned Taskfile; bare `task pr:watch` is not the consumer form when the include key is `deft:`):";
         sink.warn(message);
         if (!jsonMode) {
             sink.blank();
@@ -640,21 +703,23 @@ function runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFindin
         const tf = resolveConsumerTaskfile(projectRoot);
         addFinding({
             severity: "warning",
-            message: "Root Taskfile.yml does not include the deft framework",
+            message: "Gates-surface: root Taskfile.yml does not include the deft framework — deep-think gates need `deft` CLI or `task deft:` include",
             check: "taskfile-include",
             file: tf,
-            suggestion: formatMissingIncludeSnippet(),
+            suggestion: formatGatesSurfaceDualRemediation("missing-include"),
         });
         return;
     }
     const taskfilePath = resolveConsumerTaskfile(projectRoot) ?? join(projectRoot, "Taskfile.yml");
-    const message = `Root Taskfile.yml at ${taskfilePath} exists but could not be read -- check file permissions.`;
+    const message = `Gates-surface readiness: root Taskfile.yml at ${taskfilePath} exists but could not be read — ` +
+        "check file permissions. Deep-think gates still work via `deft <verb>` until the include is readable.";
     sink.warn(message);
     addFinding({
         severity: "warning",
         message,
         check: "taskfile-include",
         file: taskfilePath,
+        suggestion: GATES_SURFACE_DEFT_REMEDIATION,
     });
 }
 /**
@@ -734,11 +799,12 @@ function runPlanExtensionShadowCheck(projectRoot, sink, addFinding, seams) {
 }
 /**
  * Never emit a bare `task ...` remediation in a project without Taskfile wiring
- * (#2267). The `directive` surface always works; `task deft:X` is optional and
- * only present when the consumer wired the include. `plan()` already emits the
- * `directive` / `npx` / `npm` surface, so this guard is a defensive invariant:
- * any `task`-prefixed command is rewritten to the `directive` surface unless the
- * project actually has the include.
+ * (#2267 / #2893). The `directive`/`deft` surface always works; `task deft:X` is
+ * the go-task namespaced form only when the consumer wired the include (bare
+ * `task pr:watch` is not the consumer form under include key `deft:`). `plan()`
+ * already emits the `directive` / `npx` / `npm` surface, so this guard is a
+ * defensive invariant: any `task`-prefixed command is rewritten to the
+ * `directive` surface unless the project actually has the include.
  */
 /**
  * Detect Taskfile wiring through the injected seam (#2267). Mirrors

package/dist/doctor/taskfile.d.ts

@@ -3,4 +3,12 @@ export declare function resolveConsumerTaskfile(projectRoot: string): string | n
 export type TaskfileIncludeStatus = "ok" | "missing-file" | "missing-include" | "unreadable";
 export declare function classifyTaskfileInclude(projectRoot: string): TaskfileIncludeStatus;
 export declare function formatMissingIncludeSnippet(): string;
+/** Primary remediation for deep-think gates when Taskfile include is absent (#2893). */
+export declare const GATES_SURFACE_DEFT_REMEDIATION: string;
+/**
+ * Dual remediations for gates-surface readiness (#2893):
+ * 1. `deft <verb>` CLI (works without Taskfile)
+ * 2. Taskfile include so go-task exposes `task deft:<verb>` (not bare `task pr:watch`)
+ */
+export declare function formatGatesSurfaceDualRemediation(kind: "missing-file" | "missing-include"): string;
 //# sourceMappingURL=taskfile.d.ts.map

package/dist/doctor/taskfile.js

@@ -62,4 +62,23 @@ export function classifyTaskfileInclude(projectRoot) {
 export function formatMissingIncludeSnippet() {
     return "  deft:\n    taskfile: ./.deft/core/Taskfile.yml\n    optional: true\n";
 }
+/** Primary remediation for deep-think gates when Taskfile include is absent (#2893). */
+export const GATES_SURFACE_DEFT_REMEDIATION = "Prefer `deft pr:watch` / `deft review-monitor:register` / `deft verify:review-monitor` " +
+    "(primary npm/CLI surface; no Taskfile required).";
+/**
+ * Dual remediations for gates-surface readiness (#2893):
+ * 1. `deft <verb>` CLI (works without Taskfile)
+ * 2. Taskfile include so go-task exposes `task deft:<verb>` (not bare `task pr:watch`)
+ */
+export function formatGatesSurfaceDualRemediation(kind) {
+    const includePart = kind === "missing-file"
+        ? "Create root Taskfile.yml with the canonical deft include so go-task exposes `task deft:<verb>` " +
+            "(not bare `task pr:watch`):\n" +
+            "version: '3'\n\nincludes:\n" +
+            formatMissingIncludeSnippet()
+        : "Add the deft include to the existing Taskfile `includes:` block so go-task exposes " +
+            "`task deft:<verb>` (doctor NEVER mutates an existing user-owned Taskfile):\n" +
+            formatMissingIncludeSnippet();
+    return `${GATES_SURFACE_DEFT_REMEDIATION}\n2. ${includePart}`;
+}
 //# sourceMappingURL=taskfile.js.map

package/dist/doctor/types.d.ts

@@ -4,6 +4,7 @@ import type { EngineProbeResult } from "../resolution/classify.js";
 import type { ResolutionMode } from "../resolution/index.js";
 import type { ResolveUserMdResult } from "../user-config/resolve-user-md.js";
 import type { AgentHookHealthResult } from "../verify-env/agent-hooks.js";
+import type { AgentHookLiveProbeResult } from "../verify-env/agent-hooks-live-probe.js";
 export declare const EXIT_CLEAN = 0;
 export declare const EXIT_DRIFT = 1;
 export declare const EXIT_CONFIG_ERROR = 2;
@@ -147,5 +148,7 @@ export interface DoctorSeams {
     readonly detectPlanExtensionShadows?: (projectRoot: string) => readonly ShadowedPlanExtension[];
     /** Read-only agent-host hook registration probe (#2438). */
     readonly evaluateAgentHooks?: (projectRoot: string) => AgentHookHealthResult;
+    /** Live hook spawn probe for doctor --full (#2852). */
+    readonly probeAgentHooksLive?: (projectRoot: string) => AgentHookLiveProbeResult;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/hooks/dispatcher.d.ts

@@ -13,7 +13,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-degraded" | "session-compact-rearm" | "session-compact-rearm-degraded" | "session-compact-noop" | "not-direct-write" | "invalid-input" | "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";
+export type HookDecisionCode = "session-start" | "session-start-degraded" | "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";
 export interface HookDecision {
     readonly verdict: HookVerdict;
     readonly code: HookDecisionCode;
@@ -62,6 +64,19 @@ export declare function hookToolName(payload: unknown, host?: HookHost): string
 export declare function hookWriteTargetPath(payload: unknown): string | null;
 /** POSIX-ish project-relative path for lifecycle matching. */
 export declare function toProjectRelativePosix(projectRoot: string, targetPath: string): string;
+/**
+ * Lexical "outside project root" predicate used by #2885.
+ * - `".."` / `"../…"` are outside (not bare `startsWith("..")` — that matches `..secret`).
+ * - Absolute relatives and win32 cross-drive paths (`D:/…`) are outside.
+ * - Drive-letter form is win32-only so POSIX children like `D:/tmp/x` stay in-repo.
+ */
+export declare function isLexicalOutsideProjectRoot(relPosix: string): boolean;
+/**
+ * True when a write target is outside `projectRoot` for the active-scope skip (#2885).
+ * Lexically outside paths still fail the skip when a symlink/junction re-enters the project.
+ * When the project root cannot be realpath'd (unit fixtures), lexical classification wins.
+ */
+export declare function isOutsideProjectRootWrite(projectRoot: string, targetPath: string): boolean;
 /**
  * Proposing a scope under xbrief/proposed/ (or legacy vbrief/proposed/) is
  * planning, not implementation dispatch — exempt from the active-scope gate (#2625).
@@ -81,6 +96,11 @@ export declare function decideHook(input: HookDispatchInput, seams?: HookPolicyS
  * hook failure and blocks the tool — so Cursor allows must emit explicit
  * `{"permission":"allow"}`. Other hosts keep empty allow so the host permission
  * flow is unchanged.
+ *
+ * Cursor stdout always includes `code` (stable machine-readable decision code)
+ * so agents can distinguish policy denials from host-integration failures
+ * without parsing English (#2864). Exit status still does not encode the
+ * verdict — see hook-dispatch `run()` exit-code contract.
  */
 export declare function renderHostDecision(host: HookHost, decision: HookDecision): string;
 //# sourceMappingURL=dispatcher.d.ts.map

package/dist/hooks/dispatcher.js

@@ -1,4 +1,5 @@
-import { relative, resolve, sep } from "node:path";
+import { realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { hasArtifactSuffix } from "../layout/resolve.js";
 import { evaluateRuntimeAuthorityDirectWrite, loadRuntimeAuthorityFromProject, } from "../policy/runtime-authority.js";
 import { markRitualStaleAfterCompact } from "../session/ritual-sentinel.js";
@@ -145,6 +146,57 @@ export function toProjectRelativePosix(projectRoot, targetPath) {
     const rel = relative(resolve(projectRoot), abs);
     return rel.split(sep).join("/").replace(/\\/g, "/");
 }
+function posixRelative(fromAbs, toAbs) {
+    return relative(fromAbs, toAbs).split(sep).join("/").replace(/\\/g, "/");
+}
+/**
+ * Lexical "outside project root" predicate used by #2885.
+ * - `".."` / `"../…"` are outside (not bare `startsWith("..")` — that matches `..secret`).
+ * - Absolute relatives and win32 cross-drive paths (`D:/…`) are outside.
+ * - Drive-letter form is win32-only so POSIX children like `D:/tmp/x` stay in-repo.
+ */
+export function isLexicalOutsideProjectRoot(relPosix) {
+    if (relPosix === ".." || relPosix.startsWith("../") || isAbsolute(relPosix)) {
+        return true;
+    }
+    // path.relative returns absolute drive paths across volumes on Windows only.
+    return process.platform === "win32" && /^[A-Za-z]:\//.test(relPosix);
+}
+/**
+ * True when a write target is outside `projectRoot` for the active-scope skip (#2885).
+ * Lexically outside paths still fail the skip when a symlink/junction re-enters the project.
+ * When the project root cannot be realpath'd (unit fixtures), lexical classification wins.
+ */
+export function isOutsideProjectRootWrite(projectRoot, targetPath) {
+    const projectAbs = resolve(projectRoot);
+    const targetAbs = resolve(projectRoot, targetPath.replace(/\\/g, "/"));
+    const rel = posixRelative(projectAbs, targetAbs);
+    if (!isLexicalOutsideProjectRoot(rel))
+        return false;
+    try {
+        const projectReal = realpathSync(projectAbs);
+        let probe = targetAbs;
+        for (;;) {
+            try {
+                const probeReal = realpathSync(probe);
+                const reenter = posixRelative(projectReal, probeReal);
+                // Empty reenter ⇒ probeReal === projectReal (inside). Lexical-outside reenter ⇒ truly out.
+                if (reenter === "" || !isLexicalOutsideProjectRoot(reenter))
+                    return false;
+                return true;
+            }
+            catch {
+                const parent = dirname(probe);
+                if (parent === probe)
+                    return true;
+                probe = parent;
+            }
+        }
+    }
+    catch {
+        return true;
+    }
+}
 /**
  * Proposing a scope under xbrief/proposed/ (or legacy vbrief/proposed/) is
  * planning, not implementation dispatch — exempt from the active-scope gate (#2625).
@@ -298,18 +350,25 @@ function inspectMutationGates(input, toolName, seams, options) {
     if (!scope.ready) {
         const writeTarget = hookWriteTargetPath(input.payload);
         const relTarget = writeTarget !== null ? toProjectRelativePosix(projectRoot, writeTarget) : null;
-        const proposedPathHint = options.proposedLifecycleExempt &&
-            relTarget !== null &&
-            (relTarget.startsWith("xbrief/proposed/") || relTarget.startsWith("vbrief/proposed/"))
-            ? " For a new proposal under xbrief/proposed/, include a lifecycle artifact " +
-                "filename (*.xbrief.json) in the Write/Edit payload so the gate can exempt " +
-                "planning writes (#2625)."
-            : " Recovery: run `deft scope:activate -- <path>` for the approved xBRIEF, " +
-                (options.proposedLifecycleExempt
-                    ? "or Write a new proposal to xbrief/proposed/*.xbrief.json (planning exemption)."
-                    : "then re-run the pre-start_agent gate stack.");
-        const denyCode = isSpawnTool(toolName) ? "spawn-not-ready" : "scope-not-ready";
-        return deny(input, denyCode, toolName, `Directive denied ${toolName}: ${scope.message}${proposedPathHint}`);
+        // Active-scope governs in-repo lifecycle work only. Outside-root Write/Edit
+        // (agent memory, $TMPDIR, user config) skips the deny; null/unparseable
+        // targets stay fail-closed. Spawn has no write target → still requires scope (#2885).
+        // Lexical ../ + realpath re-entry guard (not bare startsWith(".."); not symlink aliases).
+        const outsideRoot = writeTarget !== null && isOutsideProjectRootWrite(projectRoot, writeTarget);
+        if (!outsideRoot || isSpawnTool(toolName)) {
+            const proposedPathHint = options.proposedLifecycleExempt &&
+                relTarget !== null &&
+                (relTarget.startsWith("xbrief/proposed/") || relTarget.startsWith("vbrief/proposed/"))
+                ? " For a new proposal under xbrief/proposed/, include a lifecycle artifact " +
+                    "filename (*.xbrief.json) in the Write/Edit payload so the gate can exempt " +
+                    "planning writes (#2625)."
+                : " Recovery: run `deft scope:activate -- <path>` for the approved xBRIEF, " +
+                    (options.proposedLifecycleExempt
+                        ? "or Write a new proposal to xbrief/proposed/*.xbrief.json (planning exemption)."
+                        : "then re-run the pre-start_agent gate stack.");
+            const denyCode = isSpawnTool(toolName) ? "spawn-not-ready" : "scope-not-ready";
+            return deny(input, denyCode, toolName, `Directive denied ${toolName}: ${scope.message}${proposedPathHint}`);
+        }
     }
     const allowCode = isSpawnTool(toolName) ? "spawn-ready" : "write-ready";
     if (!isSpawnTool(toolName)) {
@@ -414,7 +473,12 @@ export function decideHook(input, seams = {}) {
     }
     const toolName = hookToolName(input.payload, input.host);
     if (toolName === null) {
-        return deny(input, "invalid-input", null, missingToolNameMessage({
+        // stdin-empty is a host-integration failure; keep it distinct from invalid-input
+        // so agents can retry without treating it as a policy refusal (#2864).
+        const missingCode = input.payloadContext?.stdinEmpty
+            ? "stdin-empty"
+            : "invalid-input";
+        return deny(input, missingCode, null, missingToolNameMessage({
             host: input.host,
             payload: input.payload,
             context: input.payloadContext,
@@ -467,11 +531,16 @@ export function decideHook(input, seams = {}) {
  * hook failure and blocks the tool — so Cursor allows must emit explicit
  * `{"permission":"allow"}`. Other hosts keep empty allow so the host permission
  * flow is unchanged.
+ *
+ * Cursor stdout always includes `code` (stable machine-readable decision code)
+ * so agents can distinguish policy denials from host-integration failures
+ * without parsing English (#2864). Exit status still does not encode the
+ * verdict — see hook-dispatch `run()` exit-code contract.
  */
 export function renderHostDecision(host, decision) {
     if (decision.verdict === "allow") {
         if (host === "cursor") {
-            return JSON.stringify({ permission: "allow" });
+            return JSON.stringify({ permission: "allow", code: decision.code });
         }
         return "";
     }
@@ -492,6 +561,7 @@ export function renderHostDecision(host, decision) {
                 permission: "deny",
                 user_message: decision.message,
                 agent_message: decision.message,
+                code: decision.code,
             });
     }
 }

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

@@ -238,14 +238,22 @@ export function writeAgentHookDeposit(projectRoot, io = { printf: () => undefine
                 changedPaths.push(item.path);
         }
     }
-    const adapterAbsolute = join(projectRoot, ".cursor/hooks/deft-cursor-hook-adapter.mjs");
-    assertDepositContained(projectRoot, adapterAbsolute);
-    if (existsSync(adapterAbsolute)) {
-        rmSync(adapterAbsolute, { force: true });
-        if (!changedPaths.includes(AGENT_HOOK_PATHS[2])) {
-            changedPaths.push(AGENT_HOOK_PATHS[2]);
+    const legacyAdapterPaths = [
+        ".cursor/hooks/deft-cursor-hook-adapter.mjs",
+        ".cursor/hooks/deft-cursor-hook-adapter.test.mjs",
+    ];
+    let removedLegacyAdapter = false;
+    for (const relative of legacyAdapterPaths) {
+        const absolute = join(projectRoot, relative);
+        assertDepositContained(projectRoot, absolute);
+        if (existsSync(absolute)) {
+            rmSync(absolute, { force: true });
+            removedLegacyAdapter = true;
         }
     }
+    if (removedLegacyAdapter && !changedPaths.includes(AGENT_HOOK_PATHS[2])) {
+        changedPaths.push(AGENT_HOOK_PATHS[2]);
+    }
     if (changedPaths.length > 0) {
         io.printf(`Installed Directive agent hooks: ${changedPaths.join(", ")}\n`);
     }

package/dist/init-deposit/gitignore.js

@@ -11,6 +11,7 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.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/";
@@ -195,9 +196,13 @@ function reconcileGitignoreFile(projectDir, targetLines, includeDeftCoreRational
         }
     }
     try {
+        assertWriteTargetSafe(projectDir, path);
         writeFileSync(path, body, { encoding: "utf8", mode: 0o644 });
     }
     catch (cause) {
+        if (cause instanceof ProjectionContainmentError) {
+            throw cause;
+        }
         throw new Error(`could not write .gitignore: ${String(cause)}`);
     }
     const finalPresent = collectPresentGitignoreLines(body);