@deftai/directive-core 0.92.0 → 0.94.0

package/dist/doctor/openclaw-l2-adapter.js

@@ -0,0 +1,199 @@
+/**
+ * Doctor check + --fix wire for OpenClaw L2 product-command skills (#3064 D5).
+ *
+ * Primary operator recovery path when OpenClaw is detected. Deposits thin
+ * user-invocable router + 13 product skills into workspace skills roots.
+ * Fail-closed when OC signals are absent. Policy opt-out:
+ * `plan.policy.openClawProductCommands: false`.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { generateOpenClawSkillArtifacts, isManagedOpenClawL2Skill, listOpenClawManagedSkillSlugs, } from "../slash/openclaw-adapter.js";
+import { depositOpenClawL2ProductCommands, loadOpenClawProductCommandsPolicyFromProject, } from "../slash/openclaw-deposit.js";
+import { detectOpenClaw, listInScopeSkillsDirs } from "./openclaw-skills.js";
+/** Stable doctor check id for JSON findings. */
+export const OPENCLAW_L2_ADAPTER_CHECK = "openclaw-l2-product-commands";
+const DOC_OPENCLAW_HOST = "docs/openclaw-agent-host.md";
+const DOC_SLASH_MULTI = "docs/slash-multi-host.md";
+const REMEDIATION_FIX = "deft doctor --fix";
+function defaultIsDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function assessGaps(skillsDirs) {
+    const artifacts = generateOpenClawSkillArtifacts();
+    const missing = [];
+    const stale = [];
+    let present = 0;
+    for (const skillsDir of skillsDirs) {
+        for (const art of artifacts) {
+            const path = join(skillsDir, art.slug, "SKILL.md");
+            if (!existsSync(path)) {
+                missing.push(`${skillsDir}/${art.slug}`);
+                continue;
+            }
+            let raw;
+            try {
+                raw = readFileSync(path, "utf8");
+            }
+            catch {
+                missing.push(`${skillsDir}/${art.slug}`);
+                continue;
+            }
+            if (!isManagedOpenClawL2Skill(raw)) {
+                // Consumer customization — not a gap for doctor (preserve).
+                present += 1;
+                continue;
+            }
+            if (raw === art.skillMarkdown) {
+                present += 1;
+            }
+            else {
+                stale.push(`${skillsDir}/${art.slug}`);
+            }
+        }
+    }
+    return { missing, stale, present };
+}
+/**
+ * Doctor check: OpenClaw L2 product-command skills present and current.
+ * No-ops when OpenClaw is not detected. Fix mode deposits managed skills.
+ */
+export function runOpenClawL2AdapterCheck(sink, addFinding, options) {
+    const seams = options.seams ?? {};
+    const env = seams.openclawEnv ?? process.env;
+    const homeDirFn = seams.openclawHomeDir ?? (() => homedir());
+    const isDir = seams.isDir ?? defaultIsDir;
+    const home = homeDirFn();
+    const detect = detectOpenClaw(env, { homeDir: home, isDir });
+    if (!detect.detected) {
+        sink.info(`${OPENCLAW_L2_ADAPTER_CHECK}: skip -- OpenClaw not detected`);
+        addFinding({
+            severity: "skip",
+            message: "OpenClaw not detected",
+            check: OPENCLAW_L2_ADAPTER_CHECK,
+            status: "skip",
+            reason: "openclaw-not-detected",
+        });
+        return null;
+    }
+    const policy = loadOpenClawProductCommandsPolicyFromProject(options.projectRoot);
+    if (!policy) {
+        // Opt-out: under --fix, strip managed L2 skills so the adapter does not
+        // stay active after openClawProductCommands=false (#3064 Greptile P1).
+        let depositResult = null;
+        if (options.fixMode) {
+            depositResult = depositOpenClawL2ProductCommands({
+                projectRoot: options.projectRoot,
+                env,
+                homeDir: home,
+                allAgents: options.allAgents,
+                policy: false,
+                printf: (t) => {
+                    if (!options.jsonMode)
+                        sink.info(t.trimEnd());
+                },
+                isDir,
+            });
+            const message = `${OPENCLAW_L2_ADAPTER_CHECK}: opted out (plan.policy.openClawProductCommands=false); ` +
+                (depositResult.removedPaths.length > 0
+                    ? `removed ${depositResult.removedPaths.length} managed skill path(s)`
+                    : "no managed L2 skills to remove");
+            sink.success(message);
+            addFinding({
+                severity: "skip",
+                message,
+                check: OPENCLAW_L2_ADAPTER_CHECK,
+                status: "opted-out-fixed",
+                reason: "policy-false",
+                removed: depositResult.removedPaths,
+                detect_reasons: detect.reasons,
+            });
+            return depositResult;
+        }
+        sink.info(`${OPENCLAW_L2_ADAPTER_CHECK}: skip -- plan.policy.openClawProductCommands=false`);
+        addFinding({
+            severity: "skip",
+            message: "OpenClaw L2 product commands opted out via policy; run `deft doctor --fix` to remove managed skills",
+            check: OPENCLAW_L2_ADAPTER_CHECK,
+            status: "opted-out",
+            reason: "policy-false",
+        });
+        return null;
+    }
+    const skillsDirs = listInScopeSkillsDirs(detect.stateDir, options.allAgents, {
+        isDir,
+    });
+    const gaps = assessGaps(skillsDirs);
+    const expectedCount = listOpenClawManagedSkillSlugs().length * skillsDirs.length;
+    if (gaps.missing.length === 0 && gaps.stale.length === 0) {
+        const message = `${OPENCLAW_L2_ADAPTER_CHECK}: OpenClaw L2 product-command skills present ` +
+            `(router + 13) in ${options.allAgents ? "main + workspace-* seats" : "main workspace"}`;
+        sink.success(message);
+        addFinding({
+            severity: "skip",
+            message,
+            check: OPENCLAW_L2_ADAPTER_CHECK,
+            status: "present",
+            skills_dirs: skillsDirs,
+            expected: expectedCount,
+            present: gaps.present,
+            detect_reasons: detect.reasons,
+        });
+        return null;
+    }
+    let depositResult = null;
+    if (options.fixMode) {
+        depositResult = depositOpenClawL2ProductCommands({
+            projectRoot: options.projectRoot,
+            env,
+            homeDir: home,
+            allAgents: options.allAgents,
+            policy: true,
+            printf: (t) => {
+                if (!options.jsonMode)
+                    sink.info(t.trimEnd());
+            },
+            isDir,
+        });
+        const post = assessGaps(skillsDirs);
+        if (post.missing.length === 0 && post.stale.length === 0) {
+            const message = `${OPENCLAW_L2_ADAPTER_CHECK}: deposited OpenClaw L2 product-command skills; ` +
+                "restart the OpenClaw gateway or start a new session so available_skills refreshes";
+            sink.success(message);
+            addFinding({
+                severity: "skip",
+                message,
+                check: OPENCLAW_L2_ADAPTER_CHECK,
+                status: "fixed",
+                skills_dirs: skillsDirs,
+                written: depositResult.writtenPaths,
+                detect_reasons: detect.reasons,
+            });
+            return depositResult;
+        }
+    }
+    const message = `${OPENCLAW_L2_ADAPTER_CHECK}: OpenClaw L2 product-command skills incomplete ` +
+        `(missing: ${gaps.missing.length}, stale: ${gaps.stale.length}) under ${skillsDirs.join(", ")}. ` +
+        `Remediation: ${REMEDIATION_FIX}. See ${DOC_OPENCLAW_HOST}, ${DOC_SLASH_MULTI}.`;
+    sink.warn(message);
+    addFinding({
+        severity: "warning",
+        message,
+        check: OPENCLAW_L2_ADAPTER_CHECK,
+        status: "missing",
+        missing: gaps.missing,
+        stale: gaps.stale,
+        skills_dirs: skillsDirs,
+        suggestion: REMEDIATION_FIX,
+        docs: [DOC_OPENCLAW_HOST, DOC_SLASH_MULTI],
+        detect_reasons: detect.reasons,
+    });
+    return depositResult;
+}
+//# sourceMappingURL=openclaw-l2-adapter.js.map

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).

package/dist/hooks/readonly.d.ts

@@ -1,7 +1,21 @@
+/** Session posture env for assist/research low-ceremony writes (#1802). */
+export declare const ASSIST_SESSION_POSTURE_ENV = "DEFT_SESSION_POSTURE";
 /** Best-effort read-only explore signal from host payload (#1185). */
 export declare function hookReadOnlyFromPayload(payload: unknown): boolean;
 /** Read-only hook context: env override or host payload marker (#1185). */
 export declare function isReadOnlyHookContext(payload: unknown, environ?: NodeJS.ProcessEnv): boolean;
 /** Explore sub-agent spawns are exempt from the implementation gate stack (#1185). */
 export declare function isExploreSpawn(payload: unknown): boolean;
+/**
+ * Assist / research / ephemeral session posture for low-ceremony scratch writes (#1802).
+ * Structural markers only (env, payload posture fields, worker_role/subagent_type).
+ * Absent marker → false (fail closed). Compose with allowlisted scratch path fence.
+ */
+export declare function isAssistPosture(payload: unknown, environ?: NodeJS.ProcessEnv): boolean;
+/**
+ * Ephemeral / assist / docs spawns skip active-xBRIEF implementation gates (#3080).
+ * True only with an explicit allowlisted marker. Absent marker → false (fail closed).
+ * When an ephemeral marker conflicts with implement envelope signals, implement wins.
+ */
+export declare function isEphemeralSpawn(payload: unknown): boolean;
 //# sourceMappingURL=readonly.d.ts.map

package/dist/hooks/readonly.js

@@ -1,5 +1,19 @@
 import { READ_ONLY_HOOK_ENV } from "./tools.js";
 const TRUTHY = new Set(["1", "true", "yes", "on"]);
+/** Session posture env for assist/research low-ceremony writes (#1802). */
+export const ASSIST_SESSION_POSTURE_ENV = "DEFT_SESSION_POSTURE";
+/** Explicit non-lifecycle assist markers (#3080 / #1802). Primary: ephemeral; aliases: docs, assist. */
+const EPHEMERAL_ROLE_MARKERS = new Set(["ephemeral", "docs", "assist"]);
+/** Assist/research session posture tokens (structural; not free-text NLP) (#1802). */
+const ASSIST_POSTURE_MARKERS = new Set([
+    "assist",
+    "ephemeral",
+    "docs",
+    "research",
+    "research-notes",
+    "research_notes",
+    "scratch",
+]);
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -28,6 +42,9 @@ function isReadOnlyCapability(value) {
     const normalized = value.toLowerCase().replace(/[_\s-]/g, "");
     return normalized === "readonly";
 }
+function normalizePostureToken(value) {
+    return value.toLowerCase().replace(/[_\s]/g, "-");
+}
 /** Best-effort read-only explore signal from host payload (#1185). */
 export function hookReadOnlyFromPayload(payload) {
     const input = record(payload);
@@ -80,4 +97,113 @@ export function isExploreSpawn(payload) {
         fieldString(input, "workerRole");
     return workerRole?.toLowerCase() === "explore";
 }
+/**
+ * Assist / research / ephemeral session posture for low-ceremony scratch writes (#1802).
+ * Structural markers only (env, payload posture fields, worker_role/subagent_type).
+ * Absent marker → false (fail closed). Compose with allowlisted scratch path fence.
+ */
+export function isAssistPosture(payload, environ = process.env) {
+    const envPosture = (environ[ASSIST_SESSION_POSTURE_ENV] ?? "").trim();
+    if (envPosture.length > 0 && ASSIST_POSTURE_MARKERS.has(normalizePostureToken(envPosture))) {
+        return true;
+    }
+    // Explicit assist env override (truthy), separate from posture token names.
+    if (envTruthy(environ, "DEFT_HOOK_ASSIST"))
+        return true;
+    const input = record(payload);
+    if (input === null)
+        return false;
+    const toolInput = toolInputRecord(input) ?? input;
+    const posture = fieldString(toolInput, "posture") ??
+        fieldString(toolInput, "session_posture") ??
+        fieldString(toolInput, "sessionPosture") ??
+        fieldString(input, "posture") ??
+        fieldString(input, "session_posture") ??
+        fieldString(input, "sessionPosture");
+    if (posture !== null && ASSIST_POSTURE_MARKERS.has(normalizePostureToken(posture))) {
+        return true;
+    }
+    // Shared taxonomy with #3080 ephemeral spawn markers.
+    if (isEphemeralSpawn(payload))
+        return true;
+    return false;
+}
+/**
+ * Structural implement signals that win over an ephemeral marker (fail closed, #3080).
+ * Detected from envelope fields only — never free-text prompt heuristics.
+ */
+function hasImplementConflictSignal(toolInput, input) {
+    const driveTo = fieldString(toolInput, "drive_to") ??
+        fieldString(toolInput, "driveTo") ??
+        fieldString(toolInput, "drive-to") ??
+        fieldString(input, "drive_to") ??
+        fieldString(input, "driveTo") ??
+        fieldString(input, "drive-to");
+    if (driveTo !== null) {
+        const normalized = driveTo.toLowerCase().replace(/[_\s]/g, "-");
+        if (normalized === "merge-ready" ||
+            normalized === "merge" ||
+            normalized.startsWith("merge-") ||
+            normalized.includes("implement")) {
+            return true;
+        }
+    }
+    // Non-ephemeral worker roles that imply product implementation / swarm leaf.
+    // Skip when this field is itself the ephemeral marker (conflict is via other fields).
+    const workerRole = fieldString(toolInput, "worker_role") ??
+        fieldString(toolInput, "workerRole") ??
+        fieldString(input, "worker_role") ??
+        fieldString(input, "workerRole");
+    if (workerRole !== null && !EPHEMERAL_ROLE_MARKERS.has(workerRole.toLowerCase())) {
+        const role = workerRole.toLowerCase().replace(/[_\s]/g, "-");
+        if (role === "leaf-implementation" ||
+            role === "implementation" ||
+            role === "implement" ||
+            role.includes("implement")) {
+            return true;
+        }
+    }
+    const dispatchKind = fieldString(toolInput, "dispatch_kind") ??
+        fieldString(toolInput, "dispatchKind") ??
+        fieldString(input, "dispatch_kind") ??
+        fieldString(input, "dispatchKind");
+    if (dispatchKind !== null) {
+        const kind = dispatchKind.toLowerCase().replace(/[_\s]/g, "-");
+        if (kind === "swarm-cohort" || kind === "swarm-leaf" || kind.includes("implement")) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Ephemeral / assist / docs spawns skip active-xBRIEF implementation gates (#3080).
+ * True only with an explicit allowlisted marker. Absent marker → false (fail closed).
+ * When an ephemeral marker conflicts with implement envelope signals, implement wins.
+ */
+export function isEphemeralSpawn(payload) {
+    const input = record(payload);
+    if (input === null)
+        return false;
+    const toolInput = toolInputRecord(input) ?? input;
+    const subagentType = fieldString(toolInput, "subagent_type") ??
+        fieldString(toolInput, "subagentType") ??
+        fieldString(input, "subagent_type") ??
+        fieldString(input, "subagentType");
+    const workerRole = fieldString(toolInput, "worker_role") ??
+        fieldString(toolInput, "workerRole") ??
+        fieldString(input, "worker_role") ??
+        fieldString(input, "workerRole");
+    const marker = (workerRole !== null && EPHEMERAL_ROLE_MARKERS.has(workerRole.toLowerCase())
+        ? workerRole.toLowerCase()
+        : null) ??
+        (subagentType !== null && EPHEMERAL_ROLE_MARKERS.has(subagentType.toLowerCase())
+            ? subagentType.toLowerCase()
+            : null);
+    if (marker === null)
+        return false;
+    // Implement signals win over ephemeral markers (fail closed).
+    if (hasImplementConflictSignal(toolInput, input))
+        return false;
+    return true;
+}
 //# sourceMappingURL=readonly.js.map

package/dist/index.d.ts

@@ -50,6 +50,7 @@ export * as resolution from "./resolution/index.js";
 export * as scm from "./scm/index.js";
 export * as scope from "./scope/index.js";
 export * as session from "./session/index.js";
+export * as slash from "./slash/index.js";
 export * as slice from "./slice/index.js";
 export * as storyReady from "./story-ready/index.js";
 export * as swarm from "./swarm/index.js";
@@ -65,6 +66,7 @@ export * as vbriefValidation from "./vbrief-validation/index.js";
 export * as verifyEnv from "./verify-env/index.js";
 export * as verifySource from "./verify-source/index.js";
 export * as wipCap from "./wip-cap/index.js";
+export * as xbrief from "./xbrief/index.js";
 export * as xbriefMigrate from "./xbrief-migrate/index.js";
 export declare const CORE_PACKAGE: "@deftai/directive-core";
 /** Returns identifying metadata for the core engine package. */

package/dist/index.js

@@ -51,6 +51,7 @@ export * as resolution from "./resolution/index.js";
 export * as scm from "./scm/index.js";
 export * as scope from "./scope/index.js";
 export * as session from "./session/index.js";
+export * as slash from "./slash/index.js";
 export * as slice from "./slice/index.js";
 export * as storyReady from "./story-ready/index.js";
 export * as swarm from "./swarm/index.js";
@@ -66,6 +67,7 @@ export * as vbriefValidation from "./vbrief-validation/index.js";
 export * as verifyEnv from "./verify-env/index.js";
 export * as verifySource from "./verify-source/index.js";
 export * as wipCap from "./wip-cap/index.js";
+export * as xbrief from "./xbrief/index.js";
 export * as xbriefMigrate from "./xbrief-migrate/index.js";
 export const CORE_PACKAGE = "@deftai/directive-core";
 /** Returns identifying metadata for the core engine package. */