@deftai/directive-core 0.75.0 → 0.77.0

package/dist/session/index.js

@@ -1,5 +1,6 @@
 export * from "./git.js";
 export * from "./json.js";
+export * from "./posture.js";
 export * from "./resume-conditions.js";
 export * from "./ritual-sentinel.js";
 export * from "./session-start.js";

package/dist/session/posture.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Ephemeral session posture (#2180).
+ *
+ * Conversational posture is agent-context state — not authority derived from
+ * `.deft/ritual-state.json`. Fresh or cleared contexts default to read-only;
+ * gates run fresh only at mutation boundaries.
+ *
+ * Vocabulary aligned with #2176 (`SessionPosture`: `read-only` | `mutation`).
+ */
+/** Live agent posture — never persisted as repo authority. */
+export type DirectivePosture = "read-only" | "mutation";
+/** Default for fresh or manually cleared contexts (#2180). */
+export declare const DEFAULT_POSTURE: DirectivePosture;
+/** Env override for deterministic gates / CLI (`read-only` | `mutation`). */
+export declare const ENV_SESSION_POSTURE = "DEFT_SESSION_POSTURE";
+/**
+ * Ritual-state contract (#2180 / #1348 narrowed):
+ * diagnostic evidence only — not proof of user intent or mutation posture.
+ */
+export declare const RITUAL_STATE_CONTRACT: "diagnostic-only";
+/** Action-verb directives that establish mutation intent (#810 / #2180). */
+export declare const MUTATION_INTENT_VERBS: readonly ["build", "implement", "ship", "swarm", "run agents", "start agent", "start_agent", "edit", "commit", "push", "open pr", "release", "scope:promote", "scope:activate", "scope:complete", "drive-to"];
+export type MutationIntentVerb = (typeof MUTATION_INTENT_VERBS)[number];
+export interface StructuredHandoff {
+    readonly posture: DirectivePosture;
+    readonly source: "plan" | "compaction" | "dispatch" | "allocation-context";
+    readonly mutationIntent: boolean;
+}
+export interface ResolvePostureInput {
+    readonly envPosture?: string | undefined;
+    readonly handoffText?: string | null;
+    readonly explicitPosture?: DirectivePosture | null;
+    /** Gated tier implies a mutation boundary when posture is otherwise unset. */
+    readonly tier?: "quick" | "gated";
+}
+/** Ritual-state must never be treated as posture authority (#2180). */
+export declare function ritualStateIsPostureAuthority(): boolean;
+/** Detect explicit mutation intent from free-form operator or dispatch text. */
+export declare function detectMutationIntent(text: string): boolean;
+/** Parse structured handoff markers from plan / compaction / dispatch envelopes. */
+export declare function parseStructuredHandoff(text: string | null | undefined): StructuredHandoff | null;
+/**
+ * Resolve ephemeral posture for the current agent context.
+ * Precedence: explicit > env > structured handoff > tier default > read-only.
+ * Never reads `.deft/ritual-state.json`.
+ */
+export declare function resolveSessionPosture(input?: ResolvePostureInput): DirectivePosture;
+/** Message when read-only posture skips ritual-state authority checks. */
+export declare function readOnlyPostureMessage(tier: string): string;
+//# sourceMappingURL=posture.d.ts.map

package/dist/session/posture.js

@@ -0,0 +1,152 @@
+/**
+ * Ephemeral session posture (#2180).
+ *
+ * Conversational posture is agent-context state — not authority derived from
+ * `.deft/ritual-state.json`. Fresh or cleared contexts default to read-only;
+ * gates run fresh only at mutation boundaries.
+ *
+ * Vocabulary aligned with #2176 (`SessionPosture`: `read-only` | `mutation`).
+ */
+/** Default for fresh or manually cleared contexts (#2180). */
+export const DEFAULT_POSTURE = "read-only";
+/** Env override for deterministic gates / CLI (`read-only` | `mutation`). */
+export const ENV_SESSION_POSTURE = "DEFT_SESSION_POSTURE";
+/**
+ * Ritual-state contract (#2180 / #1348 narrowed):
+ * diagnostic evidence only — not proof of user intent or mutation posture.
+ */
+export const RITUAL_STATE_CONTRACT = "diagnostic-only";
+/** Action-verb directives that establish mutation intent (#810 / #2180). */
+export const MUTATION_INTENT_VERBS = [
+    "build",
+    "implement",
+    "ship",
+    "swarm",
+    "run agents",
+    "start agent",
+    "start_agent",
+    "edit",
+    "commit",
+    "push",
+    "open pr",
+    "release",
+    "scope:promote",
+    "scope:activate",
+    "scope:complete",
+    "drive-to",
+];
+function normalisePosture(raw) {
+    const value = (raw ?? "").trim().toLowerCase();
+    if (value === "read-only" || value === "readonly") {
+        return "read-only";
+    }
+    // Accept legacy "mutating" alias from early #2180 drafts.
+    if (value === "mutation" || value === "mutating") {
+        return "mutation";
+    }
+    return null;
+}
+/** Ritual-state must never be treated as posture authority (#2180). */
+export function ritualStateIsPostureAuthority() {
+    return false;
+}
+/** Detect explicit mutation intent from free-form operator or dispatch text. */
+export function detectMutationIntent(text) {
+    const lower = text.toLowerCase();
+    for (const verb of MUTATION_INTENT_VERBS) {
+        // Require a non-hyphen / non-word char before the verb so hyphenated
+        // compounds (e.g. "rebuild") do not false-positive on short verbs.
+        const escaped = verb.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const pattern = new RegExp(`(?:^|[^\\w-])${escaped}(?:$|[^\\w-])`, "i");
+        if (pattern.test(lower)) {
+            return true;
+        }
+    }
+    if (/(?:^|[^\w-])drive-to:\s*merge-ready(?:$|[^\w-])/i.test(text)) {
+        return true;
+    }
+    if (/\b(implement|ship)\s+\/\s*(implement|ship)\b/i.test(text)) {
+        return true;
+    }
+    return false;
+}
+/** Parse structured handoff markers from plan / compaction / dispatch envelopes. */
+export function parseStructuredHandoff(text) {
+    if (!text || text.trim().length === 0) {
+        return null;
+    }
+    const dispatchKind = text.match(/dispatch_kind:\s*(swarm-cohort|solo)/i)?.[1]?.toLowerCase();
+    if (dispatchKind === "swarm-cohort" || dispatchKind === "solo") {
+        const mutationIntent = detectMutationIntent(text);
+        return {
+            posture: mutationIntent ? "mutation" : "read-only",
+            source: "allocation-context",
+            mutationIntent,
+        };
+    }
+    if (/##\s*structured handoff/i.test(text) || /handoff_kind:/i.test(text)) {
+        const postureMatch = text
+            .match(/posture:\s*(read-only|mutation|mutating)/i)?.[1]
+            ?.toLowerCase();
+        const intentTrue = /mutation_intent:\s*true\b/i.test(text);
+        const intentFalse = /mutation_intent:\s*false\b/i.test(text);
+        const source = /compaction/i.test(text) ? "compaction" : "plan";
+        // Explicit structural flags win over free-form verb heuristics (#2180 SLizard).
+        if (postureMatch === "read-only" || intentFalse) {
+            return {
+                posture: "read-only",
+                source,
+                mutationIntent: false,
+            };
+        }
+        if (postureMatch === "mutation" || postureMatch === "mutating" || intentTrue) {
+            return {
+                posture: "mutation",
+                source,
+                mutationIntent: true,
+            };
+        }
+        const mutationIntent = detectMutationIntent(text);
+        return {
+            posture: mutationIntent ? "mutation" : "read-only",
+            source,
+            mutationIntent,
+        };
+    }
+    if (detectMutationIntent(text)) {
+        return {
+            posture: "mutation",
+            source: "dispatch",
+            mutationIntent: true,
+        };
+    }
+    return null;
+}
+/**
+ * Resolve ephemeral posture for the current agent context.
+ * Precedence: explicit > env > structured handoff > tier default > read-only.
+ * Never reads `.deft/ritual-state.json`.
+ */
+export function resolveSessionPosture(input = {}) {
+    if (input.explicitPosture) {
+        return input.explicitPosture;
+    }
+    const fromEnv = normalisePosture(input.envPosture);
+    if (fromEnv) {
+        return fromEnv;
+    }
+    const handoff = parseStructuredHandoff(input.handoffText);
+    if (handoff) {
+        return handoff.posture;
+    }
+    if (input.tier === "gated") {
+        return "mutation";
+    }
+    return DEFAULT_POSTURE;
+}
+/** Message when read-only posture skips ritual-state authority checks. */
+export function readOnlyPostureMessage(tier) {
+    return (`OK read-only posture — session ritual ${tier} tier not required ` +
+        `(ritual-state is diagnostic-only; run \`deft session:start\` at mutation boundaries).`);
+}
+//# sourceMappingURL=posture.js.map

package/dist/session/ritual-sentinel.d.ts

@@ -1,5 +1,6 @@
 export declare const SCHEMA_VERSION = 1;
 export declare const RITUAL_STATE_SCHEMA_VERSION = 1;
+export { RITUAL_STATE_CONTRACT } from "./posture.js";
 export declare const SENTINEL_RELPATH: readonly [".deft", "last-session.json"];
 export declare const RITUAL_STATE_RELPATH: readonly [".deft", "ritual-state.json"];
 export declare const MIN_RESUME_AGE_MS: number;
@@ -11,6 +12,7 @@ export interface Sentinel {
     readonly lastActiveVbrief: string;
     readonly lastBranch: string;
 }
+/** Parsed `.deft/ritual-state.json` — diagnostic gate outcomes only (#2180). */
 export interface RitualState {
     readonly schemaVersion: number;
     readonly sessionId: string;

package/dist/session/ritual-sentinel.js

@@ -2,9 +2,11 @@ import { closeSync, existsSync, fdatasyncSync, mkdirSync, openSync, readdirSync,
 import { join, relative, resolve } from "node:path";
 import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, } from "../layout/resolve.js";
 import { stableJson } from "./json.js";
+import { RITUAL_STATE_CONTRACT } from "./posture.js";
 import { parseTimestamp, timestampIso } from "./time.js";
 export const SCHEMA_VERSION = 1;
 export const RITUAL_STATE_SCHEMA_VERSION = 1;
+export { RITUAL_STATE_CONTRACT } from "./posture.js";
 export const SENTINEL_RELPATH = [".deft", "last-session.json"];
 export const RITUAL_STATE_RELPATH = [".deft", "ritual-state.json"];
 export const MIN_RESUME_AGE_MS = 2 * 60 * 60 * 1000;
@@ -37,6 +39,7 @@ export function ritualStep(input) {
 export function newRitualStatePayload(input) {
     return {
         schemaVersion: RITUAL_STATE_SCHEMA_VERSION,
+        contract: RITUAL_STATE_CONTRACT,
         session_id: input.sessionId,
         git_head: input.gitHead,
         worktree_path: input.worktreePath,

package/dist/session/session-start.d.ts

@@ -1,6 +1,12 @@
 import { type ResolveUserMdResult } from "../user-config/resolve-user-md.js";
 import type { GitRunner } from "./git.js";
 import { ritualStatePath } from "./ritual-sentinel.js";
+export declare const SESSION_POSTURES: readonly ["read-only", "mutation"];
+export type SessionPosture = (typeof SESSION_POSTURES)[number];
+export declare const READ_ONLY_POSTURE: SessionPosture;
+export declare const MUTATION_POSTURE: SessionPosture;
+export declare const READ_ONLY_ALIGNMENT_MESSAGE = "Deft Directive active -- AGENTS.md loaded.";
+export declare const READ_ONLY_RESULT_MESSAGE = "read-only session posture (alignment only; no ritual-state write)";
 export declare const QUICK_STEPS: readonly ["alignment", "branch_policy", "triage_welcome"];
 export declare const GATED_STEPS: readonly ["doctor", "cache_fresh"];
 export interface DefaultBranchSync {
@@ -16,6 +22,8 @@ export interface SessionStartResult {
     readonly lines: readonly string[];
 }
 export interface SessionStartOptions {
+    /** #2176: read-only records alignment only; mutation runs the full quick tier. */
+    readonly posture?: SessionPosture;
     readonly deferrals?: Readonly<Record<string, string>>;
     readonly now?: Date;
     readonly writeHistory?: boolean;

package/dist/session/session-start.js

@@ -10,6 +10,11 @@ import { emitSessionValueReadback } from "../value/readback.js";
 import { verifyRequiredTools } from "../verify-env/verify-tools.js";
 import { defaultGitRunner, gitHead, worktreePath } from "./git.js";
 import { newRitualStatePayload, ritualStatePath, ritualStep, writeRitualState, } from "./ritual-sentinel.js";
+export const SESSION_POSTURES = ["read-only", "mutation"];
+export const READ_ONLY_POSTURE = "read-only";
+export const MUTATION_POSTURE = "mutation";
+export const READ_ONLY_ALIGNMENT_MESSAGE = "Deft Directive active -- AGENTS.md loaded.";
+export const READ_ONLY_RESULT_MESSAGE = "read-only session posture (alignment only; no ritual-state write)";
 export const QUICK_STEPS = ["alignment", "branch_policy", "triage_welcome"];
 export const GATED_STEPS = ["doctor", "cache_fresh"];
 const STEP_ALIASES = {
@@ -182,10 +187,48 @@ export function defaultBranchSync(projectRoot, runGit = defaultGitRunner) {
     }
     return { branch, upstream, ahead, behind, warning };
 }
+function runReadOnlySessionStart(projectRoot, options, instant) {
+    const lines = [];
+    const resolveUserMd = options.resolveUserMd ?? ((root) => resolveUserMdPath({ projectRoot: root }));
+    const userMd = resolveUserMd(projectRoot);
+    const safePath = userMd.path.replace(/\r?\n/g, " ");
+    const safeDiagnostic = userMd.diagnostic.replace(/\r?\n/g, " ");
+    const userMdLine = userMd.found
+        ? `USER.md resolved (${userMd.rung}): ${safePath}`
+        : safeDiagnostic;
+    lines.push(READ_ONLY_ALIGNMENT_MESSAGE);
+    lines.push(userMdLine);
+    const resultPayload = {
+        ready: true,
+        exit_code: 0,
+        posture: READ_ONLY_POSTURE,
+        state_path: null,
+        quick_steps: {
+            alignment: ritualStep({
+                ok: true,
+                ts: instant,
+                message: `${READ_ONLY_ALIGNMENT_MESSAGE} ${userMdLine}`,
+            }),
+        },
+        gated_steps: {},
+        user_md: {
+            path: userMd.path,
+            rung: userMd.rung,
+            found: userMd.found,
+            diagnostic: userMd.diagnostic,
+        },
+        message: READ_ONLY_RESULT_MESSAGE,
+    };
+    return { code: 0, payload: resultPayload, lines };
+}
 export function runSessionStart(projectRoot, options = {}) {
+    const posture = options.posture ?? MUTATION_POSTURE;
     const instant = options.now ?? new Date();
     const deferrals = options.deferrals ?? {};
     const runGit = options.runGit ?? defaultGitRunner;
+    if (posture === READ_ONLY_POSTURE) {
+        return runReadOnlySessionStart(projectRoot, options, instant);
+    }
     const { head: gitHeadValue, error: gitError } = gitHead(projectRoot, runGit);
     if (gitHeadValue === null) {
         const payload = {

package/dist/session/verify-session-ritual.d.ts

@@ -1,4 +1,5 @@
 import { type GitRunner } from "./git.js";
+import { type DirectivePosture } from "./posture.js";
 export declare const ENV_SKIP = "DEFT_SESSION_RITUAL_SKIP";
 export { ENTRYPOINT_TIMEOUT_EXIT_CODE, ENTRYPOINT_TIMEOUT_SECONDS, } from "./ritual-entrypoint.js";
 export declare const GATED_ENTRYPOINT_COMMANDS: Readonly<Record<string, readonly string[]>>;
@@ -9,6 +10,8 @@ export interface VerifyResult {
     readonly statePath: string;
     readonly bypassed: boolean;
     readonly wouldFailCode: number | null;
+    readonly posture: DirectivePosture;
+    readonly ritualStateRequired: boolean;
 }
 export type RitualRunner = (command: readonly string[], projectRoot: string) => {
     code: number;
@@ -22,6 +25,9 @@ export interface VerifySessionRitualOptions {
     readonly bypass?: boolean;
     readonly envSkip?: string | undefined;
     readonly runGit?: GitRunner;
+    readonly posture?: DirectivePosture;
+    readonly envPosture?: string | undefined;
+    readonly handoffText?: string | null;
 }
 export declare function verifySessionRitual(projectRoot: string, options?: VerifySessionRitualOptions): VerifyResult;
 export declare function emitVerifyJson(result: VerifyResult): string;

package/dist/session/verify-session-ritual.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { formatFrameworkCommand } from "../render/framework-commands.js";
 import { defaultGitRunner, gitHead, worktreePath } from "./git.js";
 import { pythonJsonDump } from "./json.js";
+import { ENV_SESSION_POSTURE, readOnlyPostureMessage, resolveSessionPosture, ritualStateIsPostureAuthority, } from "./posture.js";
 import { defaultRitualRunner } from "./ritual-entrypoint.js";
 import { readRitualState, ritualStatePath, ritualStep, writeRitualState, } from "./ritual-sentinel.js";
 import { GATED_STEPS, QUICK_STEPS } from "./session-start.js";
@@ -106,6 +107,15 @@ function evaluateLoadedState(projectRoot, state, input) {
 }
 export function verifySessionRitual(projectRoot, options = {}) {
     const tier = options.tier ?? "quick";
+    const posture = resolveSessionPosture({
+        explicitPosture: options.posture ?? null,
+        envPosture: options.envPosture ?? process.env.DEFT_SESSION_POSTURE,
+        handoffText: options.handoffText,
+        tier,
+    });
+    // Satisfy static analysis / keep ENV_SESSION_POSTURE as the public constant name.
+    void ENV_SESSION_POSTURE;
+    const ritualStateRequired = posture === "mutation" && !ritualStateIsPostureAuthority();
     if (tier !== "quick" && tier !== "gated") {
         return {
             code: 2,
@@ -114,13 +124,29 @@ export function verifySessionRitual(projectRoot, options = {}) {
             statePath: ritualStatePath(projectRoot),
             bypassed: false,
             wouldFailCode: null,
+            posture,
+            ritualStateRequired,
         };
     }
     const instant = options.now ?? new Date();
-    const envSkip = options.envSkip ?? process.env[ENV_SKIP];
+    const envSkip = options.envSkip ?? process.env.DEFT_SESSION_RITUAL_SKIP;
     const isBypassed = options.bypass ?? truthy(envSkip);
     const statePath = ritualStatePath(projectRoot);
     const missingStateFile = !existsSync(statePath);
+    // Read-only posture never treats ritual-state as authority — including when
+    // DEFT_SESSION_RITUAL_SKIP is set. Skip is only for mutation-boundary gates.
+    if (posture === "read-only") {
+        return {
+            code: 0,
+            message: readOnlyPostureMessage(tier),
+            tier,
+            statePath,
+            bypassed: false,
+            wouldFailCode: null,
+            posture,
+            ritualStateRequired: false,
+        };
+    }
     let [state, err] = readRitualState(projectRoot);
     if (state === null) {
         const code = missingStateFile ? 1 : 2;
@@ -129,9 +155,27 @@ export function verifySessionRitual(projectRoot, options = {}) {
             ? `${err}. Run \`${startCommand}\` before implementation dispatch.`
             : (err ?? "ritual state invalid");
         if (isBypassed) {
-            return { code: 0, message, tier, statePath, bypassed: true, wouldFailCode: code };
+            return {
+                code: 0,
+                message,
+                tier,
+                statePath,
+                bypassed: true,
+                wouldFailCode: code,
+                posture,
+                ritualStateRequired,
+            };
         }
-        return { code, message, tier, statePath, bypassed: false, wouldFailCode: null };
+        return {
+            code,
+            message,
+            tier,
+            statePath,
+            bypassed: false,
+            wouldFailCode: null,
+            posture,
+            ritualStateRequired,
+        };
     }
     if (tier === "gated" && !isBypassed) {
         const [precheckCode, precheckMessage] = evaluateLoadedState(projectRoot, state, {
@@ -147,6 +191,8 @@ export function verifySessionRitual(projectRoot, options = {}) {
                 statePath,
                 bypassed: false,
                 wouldFailCode: null,
+                posture,
+                ritualStateRequired,
             };
         }
         const payload = { ...state.raw };
@@ -168,6 +214,8 @@ export function verifySessionRitual(projectRoot, options = {}) {
                     statePath,
                     bypassed: false,
                     wouldFailCode: null,
+                    posture,
+                    ritualStateRequired,
                 };
             }
         }
@@ -182,6 +230,8 @@ export function verifySessionRitual(projectRoot, options = {}) {
                 statePath,
                 bypassed: false,
                 wouldFailCode: null,
+                posture,
+                ritualStateRequired,
             };
         }
     }
@@ -198,9 +248,20 @@ export function verifySessionRitual(projectRoot, options = {}) {
             statePath,
             bypassed: true,
             wouldFailCode: code === 0 ? null : code,
+            posture,
+            ritualStateRequired,
         };
     }
-    return { code, message, tier, statePath, bypassed: false, wouldFailCode: null };
+    return {
+        code,
+        message,
+        tier,
+        statePath,
+        bypassed: false,
+        wouldFailCode: null,
+        posture,
+        ritualStateRequired,
+    };
 }
 export function emitVerifyJson(result) {
     return pythonJsonDump({
@@ -211,6 +272,8 @@ export function emitVerifyJson(result) {
         state_path: result.statePath,
         bypassed: result.bypassed,
         would_fail_code: result.wouldFailCode,
+        posture: result.posture,
+        ritual_state_required: result.ritualStateRequired,
     });
 }
 export function emitBypassWarning(result) {

package/dist/triage/bootstrap/gitignore.js

@@ -394,14 +394,18 @@ function ensureEvalReadme(options) {
 }
 /** Ensure the #1144 hybrid policy is encoded in the repo (idempotent). */
 export function stepEnsureGitignoreEvalEntries(projectRoot) {
-    // Layout-aware (#2109): resolve the README under the active lifecycle `.eval`
-    // dir (xbrief/ when migrated, else vbrief/) instead of a hardcoded vbrief/ path.
-    const readmePath = resolveTriageCachePath(projectRoot, "README.md");
+    const stepName = "ensure_gitignore_eval_entries";
+    let readmePath;
+    try {
+        readmePath = resolveTriageCachePath(projectRoot, "README.md");
+    }
+    catch (err) {
+        return containmentFailure(stepName, err);
+    }
     const readmeRel = evalRelDisplay(projectRoot, readmePath);
     const entries = gitignoreTriageCacheEntries(projectRoot);
     const glob = gitattributesTriageCacheGlob(projectRoot);
     const ruleLine = `${glob}  merge=union`;
-    const stepName = "ensure_gitignore_eval_entries";
     const details = {};
     const giResult = ensureGitignoreSelectiveEntries(projectRoot, stepName, entries);
     if (!giResult.ok) {

package/dist/triage/cache-path.js

@@ -6,6 +6,7 @@
  */
 import { existsSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
+import { assertProjectionContained } from "../fs/projection-containment.js";
 import { MIGRATED_ARTIFACT_DIR, resolveEvalDir, resolveLifecycleLayout, resolveLifecycleRoot, } from "../layout/resolve.js";
 import { generateTriageCacheReadmeBody } from "./bootstrap/gitignore.js";
 /** Directory name for the triage working-set cache (not version-eval results). */
@@ -24,8 +25,8 @@ export const TRIAGE_CACHE_FILE_NAMES = [
 ];
 /** Known triage-cache directory names migrated off the legacy `.eval/` tree. */
 export const TRIAGE_CACHE_DIR_NAMES = ["decompositions"];
-/** Absolute path to the layout-aware `.triage-cache/` directory. */
-export function resolveTriageCacheDir(projectRoot) {
+/** Compute the layout-aware `.triage-cache/` directory without containment checks. */
+function triageCacheDirPath(projectRoot) {
     let layoutRoot;
     try {
         layoutRoot = resolveLifecycleRoot(projectRoot);
@@ -35,6 +36,17 @@ export function resolveTriageCacheDir(projectRoot) {
     }
     return join(layoutRoot, TRIAGE_CACHE_DIR_NAME);
 }
+/** Refuse symlink-escaping xbrief/.triage-cache before mkdir/read/write (#2446). */
+function assertWritableTriageCachePath(projectRoot, ...segments) {
+    const base = triageCacheDirPath(projectRoot);
+    const target = segments.length > 0 ? join(base, ...segments) : base;
+    assertProjectionContained(projectRoot, target);
+}
+/** Absolute path to the layout-aware `.triage-cache/` directory. */
+export function resolveTriageCacheDir(projectRoot) {
+    assertWritableTriageCachePath(projectRoot);
+    return triageCacheDirPath(projectRoot);
+}
 /** POSIX-style path relative to project root (e.g. `xbrief/.triage-cache/foo`). */
 export function triageCacheRelPath(projectRoot, ...segments) {
     let artifactDir;
@@ -118,8 +130,9 @@ export function migrateLegacyTriageCacheFromEval(projectRoot) {
 }
 /** Resolve a path under `.triage-cache/`, migrating legacy `.eval/` files first. */
 export function resolveTriageCachePath(projectRoot, ...segments) {
+    assertWritableTriageCachePath(projectRoot, ...segments);
     migrateLegacyTriageCacheFromEval(projectRoot);
-    return join(resolveTriageCacheDir(projectRoot), ...segments);
+    return join(triageCacheDirPath(projectRoot), ...segments);
 }
 /** Display helper: project-root-relative POSIX path for logs and gitignore copy. */
 export function triageCacheDisplayPath(projectRoot, absPath) {

package/dist/triage/welcome/writers.js

@@ -1,5 +1,6 @@
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { assertProjectionContained } from "../../fs/projection-containment.js";
 import { hasArtifactSuffix, resolveLifecycleFolder, resolveProjectDefinitionPath, } from "../../layout/resolve.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY } from "../../policy/plan-extensions.js";
 import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
@@ -12,6 +13,7 @@ function utcIso() {
 }
 export function appendAuditEntry(projectRoot, entry) {
     const logPath = join(resolve(projectRoot), AUDIT_LOG_REL_PATH);
+    assertProjectionContained(projectRoot, logPath);
     mkdirSync(dirname(logPath), { recursive: true });
     const line = `${utcIso()} ${entry}\n`;
     if (!existsSync(logPath)) {

package/dist/ts-check-lane/index.d.ts

@@ -1,3 +1,3 @@
 export type { LaneRunner, ResolvePnpmOptions, RunnerResult, RunTsLaneOptions } from "./run-lane.js";
-export { LANE_COMMANDS, resolvePnpm, runTsLane, SKIP_NOTICE } from "./run-lane.js";
+export { LANE_COMMANDS, resolvePnpm, runTsLane, SKIP_NOTICE, sanitizeTsLaneEnv, } from "./run-lane.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/ts-check-lane/index.js

@@ -1,2 +1,2 @@
-export { LANE_COMMANDS, resolvePnpm, runTsLane, SKIP_NOTICE } from "./run-lane.js";
+export { LANE_COMMANDS, resolvePnpm, runTsLane, SKIP_NOTICE, sanitizeTsLaneEnv, } from "./run-lane.js";
 //# sourceMappingURL=index.js.map

package/dist/ts-check-lane/run-lane.d.ts

@@ -29,6 +29,11 @@ export interface RunnerResult {
     readonly error?: Error;
 }
 export type LaneRunner = (argv: readonly string[], cwd: string) => RunnerResult;
+/**
+ * Strip release preflight bypass vars before spawning pnpm/vitest so nested unit
+ * tests observe fail-closed branch and cache gates (#2434 / #1553 recurrence).
+ */
+export declare function sanitizeTsLaneEnv(base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export interface RunTsLaneOptions {
     /** Resolved pnpm executable path, or null when not installed. */
     readonly pnpm: string | null;

package/dist/ts-check-lane/run-lane.js

@@ -19,6 +19,9 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { posix, win32 } from "node:path";
+import { BRANCH_GATE_BYPASS_ENV, RELEASE_PREFLIGHT_ENV } from "../release/constants.js";
+/** Release Step-5 vars that must not leak into vitest via inherited pnpm env (#2434). */
+const TS_LANE_POISON_ENV_KEYS = [BRANCH_GATE_BYPASS_ENV, RELEASE_PREFLIGHT_ENV];
 /**
  * Run order is deliberate: lint (cheapest, catches the biome class first),
  * then build, then the test suite.
@@ -31,6 +34,17 @@ export const LANE_COMMANDS = [
 export const SKIP_NOTICE = "[ts:check-lane] pnpm not found on PATH -- skipping the TypeScript lane " +
     "(build/lint/test). The TS engine stays validated by the dedicated CI job. " +
     "Install the Node toolchain (pnpm) to run the TS lane locally.";
+/**
+ * Strip release preflight bypass vars before spawning pnpm/vitest so nested unit
+ * tests observe fail-closed branch and cache gates (#2434 / #1553 recurrence).
+ */
+export function sanitizeTsLaneEnv(base = process.env) {
+    const env = { ...base };
+    for (const key of TS_LANE_POISON_ENV_KEYS) {
+        delete env[key];
+    }
+    return env;
+}
 /** Windows command shims (.cmd/.bat) need a shell; native executables do not. */
 export function shouldUseShellForCommand(command, platform = process.platform) {
     return platform === "win32" && /\.(?:cmd|bat)$/i.test(command);
@@ -41,6 +55,7 @@ function defaultRunner(argv, cwd) {
     const commandPath = command ?? "";
     const result = spawnSync(commandPath, rest, {
         cwd,
+        env: sanitizeTsLaneEnv(process.env),
         stdio: "inherit",
         shell: shouldUseShellForCommand(commandPath),
     });

package/dist/vbrief-build/constants.d.ts

@@ -1,8 +1,8 @@
-/** Canonical ``vBRIEFInfo.version`` emitted on scope vBRIEFs (#533). */
-export declare const EMITTED_VBRIEF_VERSION = "0.6";
+/** Canonical envelope version emitted on new scope xBRIEFs (#533, #2318). */
+export declare const EMITTED_VBRIEF_VERSION: "0.8";
 /** Migrator provenance namespace under ``plan.metadata`` (#616). */
 export declare const MIGRATOR_METADATA_KEY = "x-migrator";
-export declare const PROJECT_DEFINITION_REL_PATH = "vbrief/PROJECT-DEFINITION.vbrief.json";
+/** Layout-aware PROJECT-DEFINITION paths live in ``project-definition-io.ts`` / ``policy/resolve.ts`` (#2302). */
 export declare const DEPRECATION_SENTINEL = "<!-- deft:deprecated-redirect -->";
 export declare const INTERNAL_REFERENCE_TYPES: Set<string>;
 export declare const EXTERNAL_REFERENCE_TYPES: Set<string>;