@deftai/directive-core 0.93.0 → 0.95.0

package/dist/handoff-evidence/validate.js

@@ -0,0 +1,423 @@
+/**
+ * Deterministic handoff-evidence validator (#3120).
+ *
+ * status pass is forbidden when any remote artifact is claimed unless
+ * proof_status is bound and same-turn probe snippets cover each claim.
+ * Invented-done (false remote artifacts under pass) ranks stricter than
+ * empty-done (pass with no completion substance).
+ */
+const PROOF_STATUSES = new Set(["bound", "unbound", "n/a-no-remote-claim"]);
+const AXIS_STATES = new Set(["done", "in_progress", "not_started", "blocked", "n/a"]);
+const STATUS_VALUES = new Set(["pass", "fail", "blocked", "partial"]);
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isPresentClaim(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === "string")
+        return value.trim().length > 0;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    return true;
+}
+/** Commands that look like same-turn forge/git/gate tool invocations. */
+const TOOLISH_CMD_RE = /^(?:gh\b|git\b|task\b|deft\b|directive\b|pnpm\b|npm\b|npx\b|curl\b|python\b|node\b)/i;
+function probePresent(probe) {
+    if (!probe)
+        return false;
+    if (!isNonEmptyString(probe.command) || !isNonEmptyString(probe.snippet))
+        return false;
+    // Reject freeform narration commands ("I checked" / "x") — require tool-like invocation.
+    if (!TOOLISH_CMD_RE.test(probe.command.trim()))
+        return false;
+    // Trivial snippet that is only the claim itself is not a probe payload.
+    if (probe.snippet.trim().length < 8)
+        return false;
+    return true;
+}
+/** Escape untrusted claim text before interpolating into RegExp constructors. */
+function escapeRe(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Token-boundary match: needle must appear not as a substring of a longer
+ * alphanumeric identifier (PR 12 ⊄ 3120; score 5 ⊄ elapsed=15s).
+ */
+function hasToken(snippet, needle) {
+    if (!needle)
+        return false;
+    try {
+        return new RegExp(`(^|[^A-Za-z0-9_])${escapeRe(needle)}([^A-Za-z0-9_]|$)`, "i").test(snippet);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True when the probe's raw snippet actually mentions the claimed remote value
+ * with token-level binding (not incidental substring collisions).
+ * Never throws on malformed claims — returns false instead.
+ *
+ * Scope: textual shape binding only. Live probe execution/provenance is agent
+ * process responsibility (preamble probe-then-fill); this library does not
+ * re-run forge/git commands.
+ */
+export function probeBindsClaim(claim, evidence, probe) {
+    try {
+        if (!probePresent(probe) || !probe)
+            return false;
+        const snippet = probe.snippet;
+        switch (claim) {
+            case "pr_url": {
+                const url = String(evidence.pr_url ?? "").trim();
+                if (!url)
+                    return false;
+                // Exact claimed URL present in probe output.
+                if (snippet.toLowerCase().includes(url.toLowerCase()))
+                    return true;
+                // GitHub HTML or API form must preserve owner/repo + number identity.
+                const html = url.match(/github\.com\/([^/]+)\/([^/]+)\/pulls?\/(\d+)/i);
+                if (html) {
+                    const owner = html[1] ?? "";
+                    const repo = html[2] ?? "";
+                    const num = html[3] ?? "";
+                    const o = escapeRe(owner);
+                    const r = escapeRe(repo);
+                    const n = escapeRe(num);
+                    return (new RegExp(`${o}\\/${r}\\/pulls?\\/${n}(?:[^0-9]|$)`, "i").test(snippet) ||
+                        new RegExp(`repos\\/${o}\\/${r}\\/pulls\\/${n}(?:[^0-9]|$)`, "i").test(snippet));
+                }
+                // Non-GitHub URL: require the full URL string; no number-only fallback.
+                return false;
+            }
+            case "pr_number": {
+                const num = String(evidence.pr_number ?? "").trim();
+                if (!num || !/^\d+$/.test(num))
+                    return false;
+                const n = escapeRe(num);
+                return (new RegExp(`(?:number["'\\s:=]+|#|pulls?\\/)${n}(?:[^0-9]|$)`, "i").test(snippet) ||
+                    hasToken(snippet, num));
+            }
+            case "commit_sha":
+            case "head_sha": {
+                const sha = String(claim === "commit_sha" ? (evidence.commit_sha ?? "") : (evidence.head_sha ?? ""))
+                    .trim()
+                    .toLowerCase();
+                if (sha.length < 7 || !/^[0-9a-f]+$/i.test(sha))
+                    return false;
+                const prefix = sha.slice(0, 7);
+                return (hasToken(snippet, sha) ||
+                    new RegExp(`(^|[^0-9a-f])${prefix}(?![0-9a-f])`, "i").test(snippet));
+            }
+            case "ci_status": {
+                const ci = String(evidence.ci_status ?? "")
+                    .trim()
+                    .toLowerCase();
+                if (!ci)
+                    return false;
+                const greenFamily = [
+                    "green",
+                    "pass",
+                    "passed",
+                    "success",
+                    "successful",
+                    "ok",
+                    "clean",
+                ];
+                const redFamily = [
+                    "fail",
+                    "failed",
+                    "failure",
+                    "failing",
+                    "error",
+                    "errored",
+                    "cancelled",
+                    "canceled",
+                ];
+                if (greenFamily.includes(ci)) {
+                    const hasGreen = /"state"\s*:\s*"(success|successful|ok|clean|pass(?:ed)?)"/i.test(snippet) ||
+                        greenFamily.some((tok) => hasToken(snippet, tok));
+                    const hasRed = /"state"\s*:\s*"(failure|failed|error|cancelled|canceled)"/i.test(snippet) ||
+                        redFamily.some((tok) => hasToken(snippet, tok));
+                    // Mixed success+failure in one snippet is not a clean green bind.
+                    return hasGreen && !hasRed;
+                }
+                if (redFamily.includes(ci)) {
+                    return (/"state"\s*:\s*"(failure|failed|error|cancelled|canceled)"/i.test(snippet) ||
+                        hasToken(snippet, ci));
+                }
+                return hasToken(snippet, ci);
+            }
+            case "review_score": {
+                const score = String(evidence.review_score ?? "").trim();
+                if (!score || !/^\d+(\.\d+)?$/.test(score))
+                    return false;
+                const s = escapeRe(score);
+                // Labeled fields only — bare hasToken would bind p0=5 to review_score 5.
+                return new RegExp(`(?:confidence(?:\\s*score)?|score|rating)\\s*[:=]?\\s*${s}(?:\\s*\\/\\s*5)?(?:[^0-9]|$)`, "i").test(snippet);
+            }
+            default:
+                return false;
+        }
+    }
+    catch {
+        // Malformed claims must fail closed as unbound, never throw.
+        return false;
+    }
+}
+/** Detect which remote claim keys are present on the evidence object. */
+export function detectRemoteClaims(evidence) {
+    const claims = [];
+    if (isPresentClaim(evidence.pr_url))
+        claims.push("pr_url");
+    if (isPresentClaim(evidence.pr_number))
+        claims.push("pr_number");
+    if (isPresentClaim(evidence.commit_sha))
+        claims.push("commit_sha");
+    if (isPresentClaim(evidence.head_sha))
+        claims.push("head_sha");
+    if (isPresentClaim(evidence.ci_status)) {
+        const ci = String(evidence.ci_status).trim();
+        // Neutral tokens are not remote claims; green-family and other explicit
+        // forge outcomes (failing, cancelled, …) are claims that need probes.
+        if (!/^(unknown|pending|n\/a|none|skipped)$/i.test(ci)) {
+            claims.push("ci_status");
+        }
+    }
+    if (isPresentClaim(evidence.review_score))
+        claims.push("review_score");
+    return claims;
+}
+/** Map a remote claim key to the probe slot that must bind it. */
+function probeKeyForClaim(claim) {
+    if (claim === "pr_url" || claim === "pr_number")
+        return "pr";
+    if (claim === "commit_sha" || claim === "head_sha")
+        return "sha";
+    if (claim === "ci_status")
+        return "ci";
+    return "review";
+}
+function unboundClaimKeys(evidence, claims) {
+    const unbound = [];
+    for (const claim of claims) {
+        const slot = probeKeyForClaim(claim);
+        const probe = evidence.probes?.[slot];
+        if (!probeBindsClaim(claim, evidence, probe)) {
+            unbound.push(claim);
+        }
+    }
+    // Cross-claim consistency: PR + SHA must co-appear so unrelated forge artifacts
+    // cannot be stitched into one "bound" pass (Greptile residual on #3120).
+    try {
+        const claimSet = new Set(claims);
+        const hasPr = claimSet.has("pr_url") || claimSet.has("pr_number");
+        const shaClaim = claimSet.has("head_sha")
+            ? "head_sha"
+            : claimSet.has("commit_sha")
+                ? "commit_sha"
+                : null;
+        const rawSha = shaClaim
+            ? String(shaClaim === "head_sha" ? (evidence.head_sha ?? "") : (evidence.commit_sha ?? ""))
+                .trim()
+                .toLowerCase()
+            : "";
+        // Only hex SHAs participate in co-binding; malformed SHA fails closed as unbound.
+        const hexOk = /^[0-9a-f]{7,}$/i.test(rawSha);
+        if (shaClaim && !hexOk) {
+            if (!unbound.includes(shaClaim))
+                unbound.push(shaClaim);
+        }
+        const prefix = hexOk ? rawSha.slice(0, 7) : "";
+        if (hasPr && shaClaim && prefix) {
+            const prSnippet = evidence.probes?.pr?.snippet ?? "";
+            if (!new RegExp(`(^|[^0-9a-f])${prefix}`, "i").test(prSnippet)) {
+                if (!unbound.includes(shaClaim))
+                    unbound.push(shaClaim);
+                if (!unbound.includes("pr_number") && claimSet.has("pr_number")) {
+                    unbound.push("pr_number");
+                }
+                if (!unbound.includes("pr_url") && claimSet.has("pr_url")) {
+                    unbound.push("pr_url");
+                }
+            }
+        }
+        if (claimSet.has("ci_status") && shaClaim && prefix) {
+            const ciCmd = evidence.probes?.ci?.command ?? "";
+            const ciSnippet = evidence.probes?.ci?.snippet ?? "";
+            const joined = `${ciCmd}\n${ciSnippet}`;
+            if (!new RegExp(`(^|[^0-9a-f])${prefix}`, "i").test(joined)) {
+                if (!unbound.includes("ci_status"))
+                    unbound.push("ci_status");
+            }
+        }
+    }
+    catch {
+        // Fail closed on any unexpected error during consistency checks.
+        for (const claim of claims) {
+            if (!unbound.includes(claim))
+                unbound.push(claim);
+        }
+    }
+    return unbound;
+}
+function isPassStatus(status) {
+    return status.trim().toLowerCase() === "pass";
+}
+/** Collect shape errors for unsupported status / proof_status / axis enums. */
+function enumShapeReasons(evidence) {
+    const reasons = [];
+    const status = evidence.status.toString().trim().toLowerCase();
+    if (!STATUS_VALUES.has(status)) {
+        reasons.push(`status must be one of pass|fail|blocked|partial (got ${evidence.status})`);
+    }
+    if (evidence.proof_status !== undefined && evidence.proof_status !== null) {
+        const proof = evidence.proof_status.toString().trim().toLowerCase();
+        if (proof.length > 0 && !PROOF_STATUSES.has(proof)) {
+            reasons.push(`proof_status must be bound|unbound|n/a-no-remote-claim (got ${evidence.proof_status})`);
+        }
+    }
+    for (const [name, axis] of [
+        ["work", evidence.work],
+        ["ship", evidence.ship],
+        ["gate", evidence.gate],
+    ]) {
+        const state = axis?.state;
+        if (state === undefined || state === null)
+            continue;
+        const s = state.toString().trim().toLowerCase();
+        if (s.length > 0 && !AXIS_STATES.has(s)) {
+            reasons.push(`${name}.state must be done|in_progress|not_started|blocked|n/a (got ${state})`);
+        }
+    }
+    return reasons;
+}
+function isEmptyDone(evidence) {
+    // Pass claimed but no work/ship/gate substance and no remote claims —
+    // the empty completion shape (stricter handling still prefers invented-done
+    // when remote claims are present without binding).
+    const work = evidence.work?.state?.toString().trim().toLowerCase();
+    const ship = evidence.ship?.state?.toString().trim().toLowerCase();
+    const gate = evidence.gate?.state?.toString().trim().toLowerCase();
+    const axesEmpty = (!work || work === "n/a" || work === "not_started") &&
+        (!ship || ship === "n/a" || ship === "not_started") &&
+        (!gate || gate === "n/a" || gate === "not_started");
+    return axesEmpty;
+}
+/**
+ * Validate handoff evidence against the #3120 bound-proof contract.
+ *
+ * Ranking when invalid under status pass:
+ * 1. invented-done — remote claims present without bound proof
+ * 2. empty-done — pass with no completion substance and no remote claims
+ * 3. unbound-remote-claim — non-pass status but still has unbound remote claims
+ * 4. shape-error — malformed proof_status / inconsistent n/a
+ */
+export function validateHandoffEvidence(evidence) {
+    if (!evidence || typeof evidence !== "object") {
+        return {
+            ok: false,
+            failClass: "shape-error",
+            reasons: ["evidence must be a non-null object"],
+            hasRemoteClaims: false,
+            unboundClaims: [],
+        };
+    }
+    if (!isNonEmptyString(evidence.status)) {
+        return {
+            ok: false,
+            failClass: "shape-error",
+            reasons: ["status is required"],
+            hasRemoteClaims: false,
+            unboundClaims: [],
+        };
+    }
+    const claims = detectRemoteClaims(evidence);
+    const hasRemoteClaims = claims.length > 0;
+    const unbound = unboundClaimKeys(evidence, claims);
+    const proof = (evidence.proof_status ?? "").toString().trim().toLowerCase();
+    const reasons = [...enumShapeReasons(evidence)];
+    const pass = isPassStatus(evidence.status);
+    // proof_status consistency
+    if (hasRemoteClaims && proof === "n/a-no-remote-claim") {
+        reasons.push("proof_status is n/a-no-remote-claim but remote claims are present (" +
+            claims.join(", ") +
+            ")");
+    }
+    if (!hasRemoteClaims && proof === "bound") {
+        reasons.push("proof_status is bound but no remote claims are present");
+    }
+    // Core rule: pass + remote claims requires bound + probes
+    if (hasRemoteClaims) {
+        if (proof !== "bound") {
+            reasons.push(`remote claims present (${claims.join(", ")}) require proof_status=bound` +
+                (proof ? ` (got ${proof})` : " (missing)"));
+        }
+        if (unbound.length > 0) {
+            reasons.push(`missing same-turn probes for: ${unbound.join(", ")} ` +
+                "(probe-then-fill: copy IDs from probe JSON/text, never recollection)");
+        }
+    }
+    else if (pass && (!proof || proof === "unbound")) {
+        // No remote claims under pass: n/a-no-remote-claim is the legal proof_status.
+        // unbound without remote claims is a soft shape issue under pass.
+        if (proof === "unbound") {
+            reasons.push("proof_status=unbound with no remote claims; use n/a-no-remote-claim under pass");
+        }
+    }
+    // Rank fail class
+    let failClass = "none";
+    let ok = reasons.length === 0;
+    if (pass && hasRemoteClaims && (proof !== "bound" || unbound.length > 0)) {
+        // Invented-done: complete-looking remote artifacts under pass without binding.
+        failClass = "invented-done";
+        ok = false;
+        if (!reasons.some((r) => r.includes("invented-done"))) {
+            reasons.unshift("invented-done: status pass with remote PR/SHA/CI/review claims " +
+                "without bound same-turn probes (stricter than empty-done)");
+        }
+    }
+    else if (pass && !hasRemoteClaims && isEmptyDone(evidence)) {
+        failClass = "empty-done";
+        ok = false;
+        reasons.unshift("empty-done: status pass with no work/ship/gate substance and no remote claims");
+    }
+    else if (!pass && hasRemoteClaims && (proof !== "bound" || unbound.length > 0)) {
+        failClass = "unbound-remote-claim";
+        ok = false;
+    }
+    else if (reasons.length > 0) {
+        failClass = "shape-error";
+        ok = false;
+    }
+    // Legal partial: work done + ship not_started without PR fields → ok when not pass-with-remote
+    if (ok &&
+        evidence.status === "partial" &&
+        !hasRemoteClaims &&
+        (evidence.ship?.state === "not_started" || !evidence.ship?.state)) {
+        return {
+            ok: true,
+            failClass: "none",
+            reasons: [],
+            hasRemoteClaims: false,
+            unboundClaims: [],
+        };
+    }
+    return {
+        ok,
+        failClass,
+        reasons,
+        hasRemoteClaims,
+        unboundClaims: unbound,
+    };
+}
+/**
+ * Convenience: true when status may legally be pass for this evidence.
+ * Equivalent to validateHandoffEvidence(...).ok under a pass status intent.
+ */
+export function canClaimPass(evidence) {
+    const candidate = { ...evidence, status: "pass" };
+    return validateHandoffEvidence(candidate).ok;
+}
+//# sourceMappingURL=validate.js.map

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). */
@@ -50,6 +54,9 @@ export interface HookDispatchInput {
     readonly environ?: NodeJS.ProcessEnv;
 }
 export interface HookPolicySeams {
+    /** Active mutation-boundary verifier. Defaults to gated verification. */
+    readonly verifyRitual?: (projectRoot: string) => VerifyResult;
+    /** @deprecated Compatibility seam for existing tests and callers. */
     readonly inspectRitual?: (projectRoot: string) => VerifyResult;
     readonly inspectScope?: (projectRoot: string) => ActiveScopeInspection;
     readonly sessionStart?: (projectRoot: string) => {
@@ -102,6 +109,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

@@ -11,14 +11,14 @@ import { detectBranch } from "../session/git.js";
 import { emitSessionRitualBlockedProcessCost } from "../session/process-cost.js";
 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 { formatRitualRecoveryInstruction, verifySessionRitual, } 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,10 +489,52 @@ 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 ??
-            ((root) => inspectSessionRitual(root, { tier: "gated", posture: "mutation" })))(projectRoot);
+        // Mutation dispatch is a live gated boundary: active verification reruns
+        // non-cacheable agent-hook readiness instead of trusting persisted success.
+        // Its allow fixture is non-write and its deny fixture is read-only, so the
+        // installed-shim probe cannot recurse into this mutation path.
+        ritual = (seams.verifyRitual ??
+            seams.inspectRitual ??
+            ((root) => verifySessionRitual(root, {
+                tier: "gated",
+                posture: "mutation",
+                bypass: false,
+            })))(projectRoot);
     }
     catch (cause) {
         // #2994: best-effort local process-cost; never changes deny verdict.
@@ -520,16 +603,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 +841,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).