@deftai/directive-core 0.93.0 → 0.94.0

package/dist/check/consumer-gate-integrity.js

@@ -0,0 +1,265 @@
+/**
+ * Consumer check-graph integrity (#3070).
+ *
+ * CONSUMER_CHECK_GATES lists Taskfile tasks that must resolve in a vendored
+ * deposit. When optional Taskfile includes silently omit `tasks/verify.yml`
+ * (etc.), go-task fails with opaque exit 200/201 ("Task does not exist").
+ *
+ * This module:
+ *  1. Maps each gate to its include namespace / root Taskfile surface
+ *  2. Proves shipped files define those tasks (static + runtime)
+ *  3. Emits a deposit-repair recovery message instead of opaque go-task errors
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { CONSUMER_CHECK_GATES, checkGateId } from "./gate-lists.js";
+/** Include namespaces required by the consumer check graph (Taskfile includes). */
+export const CHECK_GRAPH_REQUIRED_NAMESPACES = ["verify", "toolchain", "vbrief"];
+export const CONSUMER_GATE_INTEGRITY_RECOVERY = "Incomplete Deft deposit: check-graph Taskfile include(s) missing or incomplete. " +
+    "Run `deft update` (or `npm i -g @deftai/directive@latest` then `deft update`) " +
+    "to restore `.deft/core/tasks/` (including `tasks/verify.yml` for `verify:orphan-active`). " +
+    "See UPGRADING.md.";
+/** Namespace for a namespaced task (`verify:orphan-active` → `verify`); null for root tasks. */
+export function gateNamespace(gateId) {
+    const colon = gateId.indexOf(":");
+    if (colon <= 0) {
+        return null;
+    }
+    return gateId.slice(0, colon);
+}
+/** Local task name inside an include (`verify:orphan-active` → `orphan-active`). */
+export function gateLocalName(gateId) {
+    const colon = gateId.indexOf(":");
+    if (colon <= 0) {
+        return gateId;
+    }
+    return gateId.slice(colon + 1);
+}
+/** Relative path of the include Taskfile for a namespace. */
+export function includeTaskfileRel(namespace) {
+    return `tasks/${namespace}.yml`;
+}
+/**
+ * Namespaces that CONSUMER_CHECK_GATES require via `ns:task` form.
+ * Root-only gates (doctor, verify-strategy-output) do not add a namespace.
+ */
+export function requiredNamespacesForGates(gates = CONSUMER_CHECK_GATES) {
+    const seen = new Set();
+    for (const spec of gates) {
+        const ns = gateNamespace(checkGateId(spec));
+        if (ns !== null) {
+            seen.add(ns);
+        }
+    }
+    return [...seen].sort();
+}
+/** True when `localName` is a top-level task key under a Taskfile `tasks:` section. */
+export function taskDefinedInTaskfileYaml(text, localName) {
+    // go-task task keys are indented two spaces under `tasks:`.
+    // Match `  orphan-active:` / `  check-consumer:` etc., not nested keys.
+    const escaped = localName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const re = new RegExp(`^ {2}${escaped}\\s*:`, "m");
+    return re.test(text.replace(/\r\n/g, "\n").replace(/\r/g, "\n"));
+}
+/**
+ * Parse root Taskfile `includes:` entries: map namespace → { taskfile, optional }.
+ * Minimal line parser (avoids a YAML dependency); sufficient for go-task include shape.
+ */
+export function parseTaskfileIncludes(text) {
+    const lines = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+    const result = new Map();
+    let inIncludes = false;
+    let includesIndent = 0;
+    let currentNs = null;
+    let currentTaskfile = null;
+    let currentOptional = true; // go-task default when omitted is false, but our deposit historically used true
+    const flush = () => {
+        if (currentNs !== null && currentTaskfile !== null) {
+            result.set(currentNs, { taskfile: currentTaskfile, optional: currentOptional });
+        }
+        currentNs = null;
+        currentTaskfile = null;
+        currentOptional = false;
+    };
+    for (const raw of lines) {
+        const stripped = raw.trim();
+        if (!stripped || stripped.startsWith("#")) {
+            continue;
+        }
+        const indent = raw.length - raw.trimStart().length;
+        if (!inIncludes) {
+            if (/^includes\s*:/.test(stripped) && indent === 0) {
+                inIncludes = true;
+                includesIndent = indent;
+            }
+            continue;
+        }
+        if (indent <= includesIndent && !stripped.startsWith("#")) {
+            flush();
+            inIncludes = false;
+            // fall through if a new top-level key; re-check next iteration naturally
+            if (/^includes\s*:/.test(stripped)) {
+                inIncludes = true;
+                includesIndent = indent;
+            }
+            continue;
+        }
+        // Namespace key at includes+2 (typically 2 spaces): `  verify:`
+        if (indent === includesIndent + 2 && /^[A-Za-z_][\w-]*\s*:/.test(stripped)) {
+            flush();
+            currentNs = stripped.replace(/:\s*(?:#.*)?$/, "").trim();
+            currentTaskfile = null;
+            currentOptional = false;
+            continue;
+        }
+        if (currentNs === null) {
+            continue;
+        }
+        // Properties at includes+4: taskfile / optional
+        if (indent >= includesIndent + 4) {
+            const taskfileMatch = stripped.match(/^taskfile\s*:\s*["']?([^"'#]+?)["']?\s*(?:#.*)?$/i);
+            if (taskfileMatch?.[1]) {
+                currentTaskfile = taskfileMatch[1].trim();
+                continue;
+            }
+            const optionalMatch = stripped.match(/^optional\s*:\s*(true|false)\s*(?:#.*)?$/i);
+            if (optionalMatch?.[1]) {
+                currentOptional = optionalMatch[1].toLowerCase() === "true";
+            }
+        }
+    }
+    flush();
+    return result;
+}
+/**
+ * Assert every consumer check gate resolves against `frameworkRoot` Taskfile + includes.
+ * When the root Taskfile is absent, returns ok with no findings (caller/spawn handles that).
+ */
+export function evaluateConsumerGateIntegrity(frameworkRoot, seams = {}) {
+    const root = resolve(frameworkRoot);
+    const exists = seams.exists ?? ((p) => existsSync(p));
+    const readText = seams.readText ??
+        ((p) => {
+            try {
+                if (!existsSync(p)) {
+                    return null;
+                }
+                return readFileSync(p, "utf8");
+            }
+            catch {
+                return null;
+            }
+        });
+    const gates = seams.gates ?? CONSUMER_CHECK_GATES;
+    const findings = [];
+    const rootTaskfile = join(root, "Taskfile.yml");
+    if (!exists(rootTaskfile)) {
+        // Incomplete / non-deposit path: do not invent a Taskfile; let spawn fail as before.
+        return { ok: true, findings: [], recovery: CONSUMER_GATE_INTEGRITY_RECOVERY };
+    }
+    const rootText = readText(rootTaskfile);
+    if (rootText === null) {
+        findings.push({
+            gateId: "*",
+            kind: "missing-root-taskfile",
+            detail: `Taskfile.yml unreadable at ${rootTaskfile}`,
+            expectedPath: rootTaskfile,
+        });
+        return { ok: false, findings, recovery: CONSUMER_GATE_INTEGRITY_RECOVERY };
+    }
+    const includes = parseTaskfileIncludes(rootText);
+    const yamlCache = new Map();
+    const readCached = (abs) => {
+        if (yamlCache.has(abs)) {
+            return yamlCache.get(abs) ?? null;
+        }
+        const t = readText(abs);
+        yamlCache.set(abs, t);
+        return t;
+    };
+    yamlCache.set(rootTaskfile, rootText);
+    for (const spec of gates) {
+        const gateId = checkGateId(spec);
+        const ns = gateNamespace(gateId);
+        const local = gateLocalName(gateId);
+        if (ns === null) {
+            // Root Taskfile task (doctor, verify-strategy-output, …)
+            if (!taskDefinedInTaskfileYaml(rootText, local)) {
+                findings.push({
+                    gateId,
+                    kind: "missing-task-definition",
+                    detail: `Root task "${local}" not defined in Taskfile.yml (required by consumer check gate "${gateId}")`,
+                    expectedPath: rootTaskfile,
+                });
+            }
+            continue;
+        }
+        const rel = includeTaskfileRel(ns);
+        const includeMeta = includes.get(ns);
+        const relFromInclude = includeMeta?.taskfile ? includeMeta.taskfile.replace(/^\.\//, "") : rel;
+        const includeAbs = join(root, relFromInclude);
+        if (!exists(includeAbs)) {
+            findings.push({
+                gateId,
+                kind: "missing-include-file",
+                detail: `Missing Taskfile include file for namespace "${ns}" (gate "${gateId}"): ` +
+                    `${relFromInclude}. Optional silent omit of this include causes go-task ` +
+                    `"Task \\"${gateId}\\" does not exist" (exit 200/201).`,
+                expectedPath: includeAbs,
+            });
+            continue;
+        }
+        const includeText = readCached(includeAbs);
+        if (includeText === null) {
+            findings.push({
+                gateId,
+                kind: "missing-include-file",
+                detail: `Unreadable Taskfile include for namespace "${ns}": ${relFromInclude}`,
+                expectedPath: includeAbs,
+            });
+            continue;
+        }
+        if (!taskDefinedInTaskfileYaml(includeText, local)) {
+            findings.push({
+                gateId,
+                kind: "missing-task-definition",
+                detail: `Task "${local}" not defined in ${relFromInclude} (required by consumer check gate "${gateId}")`,
+                expectedPath: includeAbs,
+            });
+        }
+    }
+    return {
+        ok: findings.length === 0,
+        findings,
+        recovery: CONSUMER_GATE_INTEGRITY_RECOVERY,
+    };
+}
+/** Format integrity failure for stderr (check orchestrator / doctor). */
+export function formatConsumerGateIntegrityFailure(result) {
+    const lines = [
+        "check: consumer gate integrity failed (#3070)",
+        ...result.findings.map((f) => `  - ${f.gateId}: ${f.detail}`),
+        `  recovery: ${result.recovery}`,
+    ];
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * Namespaces that must not be `optional: true` on the root Taskfile when the
+ * check graph depends on them — silent omit is the #3070 failure mode.
+ */
+export function checkGraphOptionalIncludeViolations(rootTaskfileText, namespaces = requiredNamespacesForGates()) {
+    const includes = parseTaskfileIncludes(rootTaskfileText);
+    const bad = [];
+    for (const ns of namespaces) {
+        const meta = includes.get(ns);
+        if (meta === undefined) {
+            bad.push(`${ns} (include entry missing)`);
+            continue;
+        }
+        if (meta.optional) {
+            bad.push(`${ns} (optional: true — check-graph includes must fail loud when file is missing)`);
+        }
+    }
+    return bad;
+}
+//# sourceMappingURL=consumer-gate-integrity.js.map

package/dist/check/index.d.ts

@@ -1,4 +1,5 @@
 export { dispatchCachedTaskCheck } from "./cached-orchestrator.js";
+export { CHECK_GRAPH_REQUIRED_NAMESPACES, CONSUMER_GATE_INTEGRITY_RECOVERY, type ConsumerGateIntegrityFinding, type ConsumerGateIntegrityResult, type ConsumerGateIntegritySeams, checkGraphOptionalIncludeViolations, evaluateConsumerGateIntegrity, formatConsumerGateIntegrityFailure, gateLocalName, gateNamespace, includeTaskfileRel, parseTaskfileIncludes, requiredNamespacesForGates, taskDefinedInTaskfileYaml, } from "./consumer-gate-integrity.js";
 export { type CheckGateSpec, CONSUMER_CHECK_GATES, checkGateId, checkGateSpawnArgs, FRAMEWORK_CHECK_GATES, gatesForCheckTarget, } from "./gate-lists.js";
 export type { CheckOrchestratorOptions, CheckOrchestratorSeams } from "./orchestrator.js";
 export { dispatchTaskCheck, isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget, } from "./orchestrator.js";

package/dist/check/index.js

@@ -1,4 +1,5 @@
 export { dispatchCachedTaskCheck } from "./cached-orchestrator.js";
+export { CHECK_GRAPH_REQUIRED_NAMESPACES, CONSUMER_GATE_INTEGRITY_RECOVERY, checkGraphOptionalIncludeViolations, evaluateConsumerGateIntegrity, formatConsumerGateIntegrityFailure, gateLocalName, gateNamespace, includeTaskfileRel, parseTaskfileIncludes, requiredNamespacesForGates, taskDefinedInTaskfileYaml, } from "./consumer-gate-integrity.js";
 export { CONSUMER_CHECK_GATES, checkGateId, checkGateSpawnArgs, FRAMEWORK_CHECK_GATES, gatesForCheckTarget, } from "./gate-lists.js";
 export { dispatchTaskCheck, isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget, } from "./orchestrator.js";
 export { detectTestRunner, runnerDetectionTable, } from "./runner-detect.js";

package/dist/check/orchestrator.js

@@ -14,6 +14,7 @@
 import { spawnSync } from "node:child_process";
 import { join, resolve } from "node:path";
 import { dispatchCachedTaskCheck } from "./cached-orchestrator.js";
+import { evaluateConsumerGateIntegrity, formatConsumerGateIntegrityFailure, } from "./consumer-gate-integrity.js";
 import { resolveCheckTarget } from "./context.js";
 export { isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget } from "./context.js";
 /**
@@ -35,6 +36,15 @@ export function dispatchTaskCheck(frameworkRoot, projectRoot, seams = {}) {
     const taskBin = seams.taskBin ?? "task";
     const target = resolveCheckTarget(resolvedFramework, resolvedProject);
     const cwd = target === "check:framework-source" ? resolvedFramework : resolvedProject;
+    // #3070: pre-flight consumer check-graph integrity (same path as cached
+    // orchestrator) so uncached aggregate shelling also fails with recovery text.
+    if (target === "check:consumer") {
+        const integrity = evaluateConsumerGateIntegrity(resolvedFramework);
+        if (!integrity.ok) {
+            process.stderr.write(formatConsumerGateIntegrityFailure(integrity));
+            return 2;
+        }
+    }
     const spawn = seams.spawnFn ?? defaultSpawn;
     const result = spawn(taskBin, [target, "--taskfile", taskfilePath], {
         cwd,

package/dist/content-contracts/skills/greptile-detector.d.ts

@@ -34,6 +34,13 @@ export declare const BODY_AC4_INLINE_SHA_CLEAN: string;
 export declare const BODY_AC4_THIRD_CONFIDENCE_FORM: string;
 export declare const BODY_AC4_EMPTY = "";
 export declare const BODY_AC4_TRUNCATED: string;
+/**
+ * Fail-closed CLEAN gate shared by pr:watch, swarm poller, and content-contracts.
+ *
+ * `minConfidence` defaults to the consumer bar (4 == legacy confidence > 3).
+ * Directive dogfood and project policy resolve a higher floor via
+ * `resolveMinGreptileConfidence` (#3095).
+ */
 export declare function evaluateCleanGate(params: {
     lastReviewedSha: string | null;
     headSha: string;
@@ -42,6 +49,8 @@ export declare function evaluateCleanGate(params: {
     ciFailures: number;
     errored: boolean;
     terminalCheckRun?: boolean;
+    /** Minimum confidence score (1–5) that CLEANs; score must be >= min. Default 4. */
+    minConfidence?: number;
 }): [boolean, string | null];
 type PollExitClass = "CLEAN" | "NEW_P0P1" | "ERRORED" | "STALL" | "RUNNING";
 export declare function simulatePollLoop(params: {

package/dist/content-contracts/skills/greptile-detector.js

@@ -277,15 +277,22 @@ export const BODY_AC4_THIRD_CONFIDENCE_FORM = "Greptile review of head 1234567\n
     `Last reviewed commit: [fix: foo](https://github.com/deftai/directive/commit/${HEAD_SHA})\n`;
 export const BODY_AC4_EMPTY = "";
 export const BODY_AC4_TRUNCATED = "Greptile review of head 1234567\n" + "\n" + "## Confidence Score:";
+/**
+ * Fail-closed CLEAN gate shared by pr:watch, swarm poller, and content-contracts.
+ *
+ * `minConfidence` defaults to the consumer bar (4 == legacy confidence > 3).
+ * Directive dogfood and project policy resolve a higher floor via
+ * `resolveMinGreptileConfidence` (#3095).
+ */
 export function evaluateCleanGate(params) {
-    const { lastReviewedSha, headSha, hasBlocking, confidence, ciFailures, errored, terminalCheckRun = true, } = params;
+    const { lastReviewedSha, headSha, hasBlocking, confidence, ciFailures, errored, terminalCheckRun = true, minConfidence = 4, } = params;
     if (lastReviewedSha === null || lastReviewedSha !== headSha) {
         return [false, "sha_match"];
     }
     if (hasBlocking) {
         return [false, "has_blocking"];
     }
-    if (confidence === null || confidence <= 3) {
+    if (confidence === null || confidence < minConfidence) {
         return [false, "confidence"];
     }
     if (ciFailures > 0) {

package/dist/doctor/main.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { VBRIEF_VERSION } from "@deftai/directive-types";
 import { evaluate as evaluateAgentsMdAdvisory } from "../agents-md-advisory/evaluate.js";
+import { evaluateConsumerGateIntegrity, formatConsumerGateIntegrityFailure, } from "../check/consumer-gate-integrity.js";
 import { contentRoot } from "../content-root.js";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { DEFT_DIRECTIVE_DISABLE_FLAG_NAME, DEFT_DIRECTIVE_DISABLE_STATUS, DEFT_DIRECTIVE_DISABLE_TRACKED_WARNING, detectDeftDirectiveDisable, formatDeftDirectiveDisableMessage, isDeftDirectiveDisableActive, } from "../policy/deft-directive-disable.js";
@@ -389,6 +390,11 @@ export function cmdDoctor(args, seams = {}) {
     if (!jsonMode) {
         sink.blank();
     }
+    sink.info("Checking consumer check-graph integrity (verify:orphan-active and peers)...");
+    runConsumerCheckGraphIntegrity(projectRoot, frameworkRoot, sink, addFinding, seams);
+    if (!jsonMode) {
+        sink.blank();
+    }
     sink.info("Checking OpenClaw always-pin skills...");
     runOpenClawSkillPinsCheck(sink, addFinding, {
         frameworkRoot,
@@ -763,6 +769,57 @@ function runAgentsMdAdvisoryCheck(projectRoot, sink, addFinding, seams) {
         addFinding({ severity: "warning", message, check: checkName });
     }
 }
+/**
+ * Consumer check-graph integrity (#3070): every CONSUMER_CHECK_GATES entry
+ * (including `verify:orphan-active`) must resolve against the deposited
+ * Taskfile includes. Missing `tasks/verify.yml` previously failed only at
+ * go-task shell time with opaque exit 200/201.
+ */
+function runConsumerCheckGraphIntegrity(projectRoot, frameworkRoot, sink, addFinding, seams) {
+    const checkName = "consumer-check-graph-integrity";
+    if (runningInsideDeftRepo(projectRoot, seams)) {
+        // Still prove the source checkout ships a resolvable consumer gate set.
+        const integrity = evaluateConsumerGateIntegrity(frameworkRoot);
+        if (integrity.ok) {
+            sink.success(`${checkName}: source checkout resolves CONSUMER_CHECK_GATES (incl. verify:orphan-active)`);
+            return;
+        }
+        const message = formatConsumerGateIntegrityFailure(integrity).trim();
+        sink.error(message);
+        addFinding({
+            severity: "error",
+            message,
+            check: checkName,
+            suggestion: "deft update",
+            status: "fail",
+        });
+        return;
+    }
+    try {
+        const depositRoot = frameworkRoot;
+        const integrity = evaluateConsumerGateIntegrity(depositRoot);
+        if (integrity.ok) {
+            sink.success(`${checkName}: deposit resolves CONSUMER_CHECK_GATES (incl. verify:orphan-active)`);
+            return;
+        }
+        // Incomplete deposit is an error for consumers — check:consumer would hard-fail.
+        const message = formatConsumerGateIntegrityFailure(integrity).trim();
+        sink.error(message);
+        addFinding({
+            severity: "error",
+            message,
+            check: checkName,
+            suggestion: integrity.recovery,
+            status: "fail",
+            findings: integrity.findings,
+        });
+    }
+    catch (exc) {
+        const message = `${checkName}: probe failed -- ${exc instanceof Error ? exc.name : "Error"}: ${exc}`;
+        sink.warn(message);
+        addFinding({ severity: "warning", message, check: checkName });
+    }
+}
 function runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFinding, seams) {
     if (runningInsideDeftRepo(projectRoot, seams)) {
         sink.info("Skipping Taskfile include check -- running inside the deft framework repo (the repo's own Taskfile.yml is the surface).");

package/dist/finish-loop/pr-finish-loop.js

@@ -77,6 +77,7 @@ export function runPrFinishLoop(options) {
             maxWaitMinutes: options.maxWaitMinutes,
             pollSeconds: options.pollSeconds,
             oneShot: options.oneShot === true,
+            projectRoot,
         });
     }
     catch (err) {

package/dist/hooks/dispatcher.d.ts

@@ -5,7 +5,7 @@ import { type RuntimeAuthorityPolicy } from "../policy/runtime-authority.js";
 import { type VerifyResult } from "../session/verify-session-ritual.js";
 import { type HookPayloadContext } from "./classify/index.js";
 import { type ActiveScopeInspection } from "./scope.js";
-export { hookReadOnlyFromPayload, isExploreSpawn, isReadOnlyHookContext } from "./readonly.js";
+export { ASSIST_SESSION_POSTURE_ENV, hookReadOnlyFromPayload, isAssistPosture, isEphemeralSpawn, isExploreSpawn, isReadOnlyHookContext, } from "./readonly.js";
 export { DIRECT_WRITE_HOOK_MATCHER, DIRECT_WRITE_TOOL_NAMES, isDirectWriteTool, isMcpTool, isShellTool, isSpawnTool, MCP_HOOK_MATCHER, MCP_PUSH_MERGE_BARE_NAMES, READ_ONLY_HOOK_ENV, SHELL_HOOK_MATCHER, SHELL_TOOL_NAMES, SPAWN_HOOK_MATCHER, SPAWN_TOOL_NAMES, } from "./tools.js";
 export declare const HOOK_HOSTS: readonly ["claude", "grok", "cursor", "codex"];
 export type HookHost = (typeof HOOK_HOSTS)[number];
@@ -21,7 +21,11 @@ export type HookDecisionCode = "session-start" | "session-start-disabled" | "ses
 /** 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"
+ | "stdin-empty" | "ritual-not-ready" | "scope-not-ready" | "write-propose-ready"
+/** Allowlisted assist/scratch write without active xBRIEF (#1802). */
+ | "write-assist-scratch-ready" | "write-ready" | "read-only-deny" | "spawn-explore-ready"
+/** Non-lifecycle assist/docs spawn allowed without active xBRIEF (#3080). */
+ | "spawn-ephemeral-ready" | "spawn-ready" | "spawn-not-ready" | "runtime-policy-deny-path" | "runtime-policy-deny-scope"
 /** Shell/MCP classifiable push/merge allowed under runtimeAuthority (#2711). */
  | "shell-op-ready"
 /** Shell/MCP tool seen but command/tool not classifiable as push/merge — fail open (#2711). */
@@ -102,6 +106,24 @@ export declare function isOutsideProjectRootWrite(projectRoot: string, targetPat
  * planning, not implementation dispatch — exempt from the active-scope gate (#2625).
  */
 export declare function isProposedLifecycleWrite(projectRoot: string, targetPath: string | null): boolean;
+/**
+ * Canonical + gitignored assist scratch roots for low-ceremony disposable notes (#1802).
+ * Path fence only — not free-text "for Obsidian" NLP. Tracked trees (src/, packages/, …)
+ * are never listed here.
+ */
+export declare const ASSIST_SCRATCH_ROOT_PREFIXES: readonly [".deft-scratch/", "temp/"];
+/**
+ * True when the write target is under an allowlisted disposable scratch root (#1802).
+ * Fail closed on null/empty/unparseable targets and on path escape (`..`).
+ * Does not authorize tracked product paths even under assist posture.
+ */
+export declare function isAllowlistedAssistScratchPath(projectRoot: string, targetPath: string | null): boolean;
+/**
+ * Assist/ephemeral classification for scratch-write carve-out (#1802).
+ * Requires allowlisted path AND (assist posture markers OR ephemeral spawn markers).
+ * Path alone without posture markers fails closed to the mutation gate stack.
+ */
+export declare function isAssistScratchWrite(projectRoot: string, targetPath: string | null, payload: unknown, environ?: NodeJS.ProcessEnv): boolean;
 /** Normalize hook project-root resolution on Windows (doubled drive + MSYS `/c/...`). */
 export declare function normalizeHookProjectRoot(path: string): string;
 export declare function projectRootFromHookPayload(payload: unknown, fallback: string): string;

package/dist/hooks/dispatcher.js

@@ -13,12 +13,12 @@ import { markRitualStaleAfterCompact } from "../session/ritual-sentinel.js";
 import { runSessionStartHookWrite } from "../session/session-start-hook.js";
 import { formatRitualRecoveryInstruction, inspectSessionRitual, } from "../session/verify-session-ritual.js";
 import { hookMcpArgsText, hookShellCommand, hookToolName, hookWriteTargetPath, missingToolNameMessage, record, } from "./classify/index.js";
-import { isExploreSpawn, isReadOnlyHookContext } from "./readonly.js";
+import { isAssistPosture, isEphemeralSpawn, isExploreSpawn, isReadOnlyHookContext, } from "./readonly.js";
 import { inspectActiveScope } from "./scope.js";
 import { isDirectWriteTool, isMcpTool, isShellTool, isSpawnTool } from "./tools.js";
 // Pure parse/classify helpers are defined in ./classify/ and re-exported from
 // ./index.ts (#2950). Dispatcher is orchestration: classify → policy → decision.
-export { hookReadOnlyFromPayload, isExploreSpawn, isReadOnlyHookContext } from "./readonly.js";
+export { ASSIST_SESSION_POSTURE_ENV, hookReadOnlyFromPayload, isAssistPosture, isEphemeralSpawn, isExploreSpawn, isReadOnlyHookContext, } from "./readonly.js";
 export { DIRECT_WRITE_HOOK_MATCHER, DIRECT_WRITE_TOOL_NAMES, isDirectWriteTool, isMcpTool, isShellTool, isSpawnTool, MCP_HOOK_MATCHER, MCP_PUSH_MERGE_BARE_NAMES, READ_ONLY_HOOK_ENV, SHELL_HOOK_MATCHER, SHELL_TOOL_NAMES, SPAWN_HOOK_MATCHER, SPAWN_TOOL_NAMES, } from "./tools.js";
 export const HOOK_HOSTS = ["claude", "grok", "cursor", "codex"];
 export const HOOK_EVENTS = ["session.start", "session.compact", "tool.before"];
@@ -99,6 +99,47 @@ export function isProposedLifecycleWrite(projectRoot, targetPath) {
         return false;
     return posix.startsWith("xbrief/proposed/") || posix.startsWith("vbrief/proposed/");
 }
+/**
+ * Canonical + gitignored assist scratch roots for low-ceremony disposable notes (#1802).
+ * Path fence only — not free-text "for Obsidian" NLP. Tracked trees (src/, packages/, …)
+ * are never listed here.
+ */
+export const ASSIST_SCRATCH_ROOT_PREFIXES = [".deft-scratch/", "temp/"];
+/**
+ * True when the write target is under an allowlisted disposable scratch root (#1802).
+ * Fail closed on null/empty/unparseable targets and on path escape (`..`).
+ * Does not authorize tracked product paths even under assist posture.
+ */
+export function isAllowlistedAssistScratchPath(projectRoot, targetPath) {
+    if (targetPath === null || targetPath.trim().length === 0)
+        return false;
+    const posix = toProjectRelativePosix(projectRoot, targetPath);
+    // resolve()+relative() collapses mid-path `..`; only outside-root `..` remains.
+    if (posix === ".." || posix.startsWith("../") || isAbsolute(posix))
+        return false;
+    if (isLexicalOutsideProjectRoot(posix))
+        return false;
+    for (const prefix of ASSIST_SCRATCH_ROOT_PREFIXES) {
+        if (posix === prefix.slice(0, -1) || posix.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+/**
+ * Assist/ephemeral classification for scratch-write carve-out (#1802).
+ * Requires allowlisted path AND (assist posture markers OR ephemeral spawn markers).
+ * Path alone without posture markers fails closed to the mutation gate stack.
+ */
+export function isAssistScratchWrite(projectRoot, targetPath, payload, environ = process.env) {
+    if (!isAllowlistedAssistScratchPath(projectRoot, targetPath))
+        return false;
+    // Structural classification only — compose with #3080 ephemeral markers.
+    if (isAssistPosture(payload, environ))
+        return true;
+    if (isEphemeralSpawn(payload))
+        return true;
+    return false;
+}
 function isWindowsDriveOnlyRoot(value) {
     return /^[A-Za-z]:[/\\]?$/.test(value.trim());
 }
@@ -448,6 +489,39 @@ function decideShellOrMcpRuntimeAuthority(input, toolName, seams) {
 }
 function inspectMutationGates(input, toolName, seams, options) {
     const projectRoot = resolve(input.projectRoot);
+    const environ = input.environ ?? process.env;
+    // Assist/scratch low-ceremony writes (#1802): allowlisted gitignored roots under
+    // assist/ephemeral classification skip ritual + active-scope (no fake scope:activate).
+    // Tracked product paths never match the path fence. Read-only still denied upstream.
+    if (!isSpawnTool(toolName)) {
+        const scratchTarget = hookWriteTargetPath(input.payload);
+        if (isAssistScratchWrite(projectRoot, scratchTarget, input.payload, environ)) {
+            const relPath = scratchTarget !== null ? toProjectRelativePosix(projectRoot, scratchTarget) : null;
+            const authzDeny = authzForMutation(input, toolName, seams, {
+                isDirectWrite: true,
+                relPath,
+                scopePath: null,
+            });
+            if (authzDeny !== null)
+                return authzDeny;
+            const runtimeDeny = runtimeAuthorityForDirectWrite(input, toolName, seams, null);
+            if (runtimeDeny !== null)
+                return runtimeDeny;
+            return {
+                verdict: "allow",
+                code: "write-assist-scratch-ready",
+                event: input.event,
+                host: input.host,
+                toolName,
+                projectRoot,
+                message: `Directive write gate allowed ${toolName} under allowlisted assist scratch ` +
+                    "root (disposable notes; active scope and story-start not required). " +
+                    "Tracked product paths still require mutation gates — do not smuggle source " +
+                    "under .deft-scratch/ or temp/.",
+                scopePath: null,
+            };
+        }
+    }
     let ritual;
     try {
         ritual = (seams.inspectRitual ??
@@ -520,16 +594,38 @@ function inspectMutationGates(input, toolName, seams, options) {
         // 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 &&
+            let proposedPathHint;
+            if (isSpawnTool(toolName)) {
+                // Multi-path recovery for implement-class spawns (#3080 AC4).
+                proposedPathHint =
+                    " Recovery: (1) Product implementation — run `deft scope:activate -- <path>` " +
+                        "for the approved xBRIEF, then re-run the pre-start_agent gate stack. " +
+                        "(2) Read-only research — spawn with `subagent_type`/`worker_role` explore. " +
+                        "(3) Ephemeral docs/analysis — spawn with `worker_role: ephemeral` " +
+                        "(aliases: docs, assist; see commands.md), or continue in the parent without " +
+                        "a lifecycle story. Do not invent a fake scope only to satisfy this gate.";
+            }
+            else if (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.");
+                (relTarget.startsWith("xbrief/proposed/") || relTarget.startsWith("vbrief/proposed/"))) {
+                proposedPathHint =
+                    " 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).";
+            }
+            else {
+                proposedPathHint =
+                    " Recovery: run `deft scope:activate -- <path>` for the approved xBRIEF, " +
+                        (options.proposedLifecycleExempt
+                            ? "or Write a new proposal to xbrief/proposed/*.xbrief.json (planning exemption), " +
+                                "or for disposable research notes write under `.deft-scratch/` (or `temp/`) " +
+                                "with assist/ephemeral posture (`DEFT_SESSION_POSTURE=assist` or " +
+                                "`worker_role: assist` / ephemeral — see commands.md #1802 / #3080). " +
+                                "Do not invent a fake scope only to capture Obsidian/scratch notes."
+                            : "then re-run the pre-start_agent gate stack. " +
+                                "For disposable research notes only: write under `.deft-scratch/` with " +
+                                "assist posture (commands.md #1802) — do not fake `scope:activate` for notes.");
+            }
             const denyCode = isSpawnTool(toolName) ? "spawn-not-ready" : "scope-not-ready";
             return deny(input, denyCode, toolName, `Directive denied ${toolName}: ${scope.message}${proposedPathHint}`);
         }
@@ -736,6 +832,21 @@ export function decideHook(input, seams = {}) {
                 scopePath: null,
             };
         }
+        // Ephemeral/docs/assist: write-capable non-lifecycle spawn; no active xBRIEF (#3080).
+        // Does not authorize push/merge/deploy — those remain on shell/MCP matchers.
+        if (isEphemeralSpawn(input.payload)) {
+            return {
+                verdict: "allow",
+                code: "spawn-ephemeral-ready",
+                event: input.event,
+                host: input.host,
+                toolName,
+                projectRoot,
+                message: `Directive allowed ephemeral ${toolName} spawn without active-xBRIEF ` +
+                    "implementation gates (non-lifecycle assist/docs posture).",
+                scopePath: null,
+            };
+        }
         return inspectMutationGates(input, toolName, seams, { proposedLifecycleExempt: false });
     }
     // Shell/Bash and classifiable MCP: enforce scopes.push / scopes.merge (#2711).