@deftai/directive-core 0.75.0 → 0.77.0

package/dist/plan-sequence/store.d.ts

@@ -0,0 +1,6 @@
+import { type PlanSequence } from "./types.js";
+export declare function planSequencePath(projectRoot: string): string;
+export declare function readPlanSequence(projectRoot: string): PlanSequence | null;
+export declare function writePlanSequence(projectRoot: string, sequence: PlanSequence): string;
+export declare function clearPlanSequence(projectRoot: string): boolean;
+//# sourceMappingURL=store.d.ts.map

package/dist/plan-sequence/store.js

@@ -0,0 +1,29 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { PLAN_SEQUENCE_FILENAME, parsePlanSequence } from "./types.js";
+export function planSequencePath(projectRoot) {
+    return join(projectRoot, ".deft", PLAN_SEQUENCE_FILENAME);
+}
+export function readPlanSequence(projectRoot) {
+    const path = planSequencePath(projectRoot);
+    if (!existsSync(path)) {
+        return null;
+    }
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    return parsePlanSequence(raw);
+}
+export function writePlanSequence(projectRoot, sequence) {
+    const path = planSequencePath(projectRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(sequence, null, 2)}\n`, "utf8");
+    return path;
+}
+export function clearPlanSequence(projectRoot) {
+    const path = planSequencePath(projectRoot);
+    if (!existsSync(path)) {
+        return false;
+    }
+    unlinkSync(path);
+    return true;
+}
+//# sourceMappingURL=store.js.map

package/dist/plan-sequence/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Ordered-plan continuation boundary (#2402).
+ *
+ * Continuation words ("next", "resume", "proceed") advance only within the
+ * narrowest operator-approved sequence. Exhaustion fails closed. Separate from
+ * triage queue continuationNumbers / continuationOrder.
+ */
+export declare const PLAN_SEQUENCE_FILENAME = "plan-sequence.json";
+export declare const PLAN_SEQUENCE_CONTRACT: "ordered-plan-continuation";
+export type PlanSequenceKind = "delivery" | "review" | "implementation" | "swarm" | "triage" | "cohort" | "checklist";
+export type PlanTargetKind = "pr" | "issue" | "story" | "task" | "phase" | "checklist" | "review";
+export interface PlanSequenceEntry {
+    readonly id: string;
+    readonly kind: PlanTargetKind;
+    readonly title?: string;
+    readonly issue?: number;
+    readonly status?: "pending" | "completed" | "skipped";
+}
+export interface PlanSequence {
+    readonly sequence_id: string;
+    readonly sequence_kind: PlanSequenceKind;
+    readonly entries: readonly PlanSequenceEntry[];
+    readonly current_index: number;
+    readonly batching_allowed: boolean;
+    /** Default false — exhausted sequences require fresh operator approval. */
+    readonly continuation_past_final: boolean;
+    readonly exhausted: boolean;
+    readonly authorized_by: string;
+    readonly created_at: string;
+    readonly updated_at: string;
+}
+export interface PlanSequenceVerifyInput {
+    readonly targetKind: PlanTargetKind;
+    readonly target: string;
+}
+export type PlanSequenceVerifyResult = {
+    readonly ok: true;
+    readonly entry: PlanSequenceEntry;
+    readonly index: number;
+} | {
+    readonly ok: false;
+    readonly code: "missing" | "exhausted" | "mismatch" | "kind-mismatch";
+    readonly message: string;
+};
+export type ContinuationResolution = {
+    readonly action: "advance";
+    readonly entry: PlanSequenceEntry;
+    readonly index: number;
+} | {
+    readonly action: "queue";
+    readonly reason: "no-active-sequence" | "explicit-queue-override" | "not-plan-first-phrase";
+} | {
+    readonly action: "ask";
+    readonly reason: "exhausted" | "ambiguous-sequences";
+    readonly message: string;
+};
+/** Phrases that are explicit queue/backlog selection even mid-plan. */
+export declare const EXPLICIT_QUEUE_PHRASES: readonly ["what's the queue", "whats the queue", "what is the queue", "build a cohort", "triage queue", "show the queue", "queue-driven", "from the backlog"];
+/** Bare continuation / selection phrases that bind to ordered-plan when active. */
+export declare const PLAN_FIRST_PHRASES: readonly ["what's next", "whats next", "what next", "what should i work on next", "next task", "next pr", "next issue", "next story", "move on", "proceed", "resume", "next"];
+export declare const EXHAUSTED_FAIL_CLOSED_MESSAGE = "I have completed the approved sequence. Starting another item would exceed the current authorization. Please name the next target or approve queue-driven selection.";
+export declare function isExplicitQueueAsk(text: string): boolean;
+export declare function isPlanFirstPhrase(text: string): boolean;
+/** Resolve how continuation/selection language should be handled. */
+export declare function resolveContinuation(text: string, sequence: PlanSequence | null): ContinuationResolution;
+export declare function verifyPlanTarget(sequence: PlanSequence | null, input: PlanSequenceVerifyInput): PlanSequenceVerifyResult;
+export declare function createPlanSequence(input: {
+    sequence_id: string;
+    sequence_kind: PlanSequenceKind;
+    entries: readonly PlanSequenceEntry[];
+    authorized_by: string;
+    batching_allowed?: boolean;
+    continuation_past_final?: boolean;
+    now?: string;
+}): PlanSequence;
+/** Mark current entry completed and advance index; may set exhausted. */
+export declare function advancePlanSequence(sequence: PlanSequence, now?: string): PlanSequence;
+export declare function parsePlanSequence(raw: unknown): PlanSequence;
+//# sourceMappingURL=types.d.ts.map

package/dist/plan-sequence/types.js

@@ -0,0 +1,220 @@
+/**
+ * Ordered-plan continuation boundary (#2402).
+ *
+ * Continuation words ("next", "resume", "proceed") advance only within the
+ * narrowest operator-approved sequence. Exhaustion fails closed. Separate from
+ * triage queue continuationNumbers / continuationOrder.
+ */
+export const PLAN_SEQUENCE_FILENAME = "plan-sequence.json";
+export const PLAN_SEQUENCE_CONTRACT = "ordered-plan-continuation";
+/** Phrases that are explicit queue/backlog selection even mid-plan. */
+export const EXPLICIT_QUEUE_PHRASES = [
+    "what's the queue",
+    "whats the queue",
+    "what is the queue",
+    "build a cohort",
+    "triage queue",
+    "show the queue",
+    "queue-driven",
+    "from the backlog",
+];
+/** Bare continuation / selection phrases that bind to ordered-plan when active. */
+export const PLAN_FIRST_PHRASES = [
+    "what's next",
+    "whats next",
+    "what next",
+    "what should i work on next",
+    "next task",
+    "next pr",
+    "next issue",
+    "next story",
+    "move on",
+    "proceed",
+    "resume",
+    "next",
+];
+export const EXHAUSTED_FAIL_CLOSED_MESSAGE = "I have completed the approved sequence. Starting another item would exceed the current authorization. Please name the next target or approve queue-driven selection.";
+function normalizeTarget(raw) {
+    return raw.trim().toLowerCase().replace(/^#/, "");
+}
+function entryMatches(entry, targetKind, target) {
+    if (entry.kind !== targetKind) {
+        return false;
+    }
+    const needle = normalizeTarget(target);
+    if (normalizeTarget(entry.id) === needle) {
+        return true;
+    }
+    if (entry.issue !== undefined && String(entry.issue) === needle) {
+        return true;
+    }
+    if (entry.title !== undefined && normalizeTarget(entry.title) === needle) {
+        return true;
+    }
+    return false;
+}
+export function isExplicitQueueAsk(text) {
+    const lower = text.toLowerCase();
+    return EXPLICIT_QUEUE_PHRASES.some((p) => lower.includes(p));
+}
+export function isPlanFirstPhrase(text) {
+    const lower = text.toLowerCase();
+    return PLAN_FIRST_PHRASES.some((p) => lower.includes(p));
+}
+/** Resolve how continuation/selection language should be handled. */
+export function resolveContinuation(text, sequence) {
+    // Explicit backlog/cohort asks always select from the queue, even mid-plan.
+    if (isExplicitQueueAsk(text)) {
+        return { action: "queue", reason: "explicit-queue-override" };
+    }
+    // No active sequence → queue (same as today's #1149 path).
+    if (sequence === null) {
+        return { action: "queue", reason: "no-active-sequence" };
+    }
+    // Active sequence + plan-first / continuation phrase → bind to current entry.
+    if (!isPlanFirstPhrase(text)) {
+        return { action: "queue", reason: "not-plan-first-phrase" };
+    }
+    if (sequence.exhausted || sequence.current_index >= sequence.entries.length) {
+        if (sequence.continuation_past_final) {
+            return { action: "queue", reason: "no-active-sequence" };
+        }
+        return {
+            action: "ask",
+            reason: "exhausted",
+            message: EXHAUSTED_FAIL_CLOSED_MESSAGE,
+        };
+    }
+    const index = sequence.current_index;
+    const entry = sequence.entries[index];
+    if (entry === undefined) {
+        return {
+            action: "ask",
+            reason: "exhausted",
+            message: EXHAUSTED_FAIL_CLOSED_MESSAGE,
+        };
+    }
+    return { action: "advance", entry, index };
+}
+export function verifyPlanTarget(sequence, input) {
+    if (sequence === null) {
+        return {
+            ok: false,
+            code: "missing",
+            message: "No active ordered-plan sequence. Set one with plan-sequence:set, or obtain explicit operator approval for this target.",
+        };
+    }
+    if (sequence.exhausted || sequence.current_index >= sequence.entries.length) {
+        return {
+            ok: false,
+            code: "exhausted",
+            message: EXHAUSTED_FAIL_CLOSED_MESSAGE,
+        };
+    }
+    const index = sequence.current_index;
+    const entry = sequence.entries[index];
+    if (entry === undefined) {
+        return {
+            ok: false,
+            code: "exhausted",
+            message: EXHAUSTED_FAIL_CLOSED_MESSAGE,
+        };
+    }
+    if (entry.kind !== input.targetKind) {
+        return {
+            ok: false,
+            code: "kind-mismatch",
+            message: `Current ordered-plan entry is kind=${entry.kind} id=${entry.id}; requested kind=${input.targetKind} target=${input.target}.`,
+        };
+    }
+    if (!entryMatches(entry, input.targetKind, input.target)) {
+        return {
+            ok: false,
+            code: "mismatch",
+            message: `Target ${input.targetKind}:${input.target} is not the current ordered-plan entry (${entry.kind}:${entry.id}).`,
+        };
+    }
+    return { ok: true, entry, index };
+}
+export function createPlanSequence(input) {
+    if (input.entries.length === 0) {
+        throw new Error("plan-sequence: entries must be non-empty");
+    }
+    const now = input.now ?? new Date().toISOString();
+    return {
+        sequence_id: input.sequence_id,
+        sequence_kind: input.sequence_kind,
+        entries: input.entries.map((e) => ({ ...e, status: e.status ?? "pending" })),
+        current_index: 0,
+        batching_allowed: input.batching_allowed ?? false,
+        continuation_past_final: input.continuation_past_final ?? false,
+        exhausted: false,
+        authorized_by: input.authorized_by,
+        created_at: now,
+        updated_at: now,
+    };
+}
+/** Mark current entry completed and advance index; may set exhausted. */
+export function advancePlanSequence(sequence, now = new Date().toISOString()) {
+    if (sequence.exhausted || sequence.current_index >= sequence.entries.length) {
+        return { ...sequence, exhausted: true, updated_at: now };
+    }
+    const entries = sequence.entries.map((e, i) => i === sequence.current_index ? { ...e, status: "completed" } : e);
+    const nextIndex = sequence.current_index + 1;
+    const exhausted = nextIndex >= entries.length;
+    return {
+        ...sequence,
+        entries,
+        current_index: exhausted ? sequence.current_index : nextIndex,
+        exhausted,
+        updated_at: now,
+    };
+}
+export function parsePlanSequence(raw) {
+    if (raw === null || typeof raw !== "object") {
+        throw new Error("plan-sequence: expected object");
+    }
+    const obj = raw;
+    if (typeof obj.sequence_id !== "string" || obj.sequence_id.length === 0) {
+        throw new Error("plan-sequence: sequence_id required");
+    }
+    if (typeof obj.sequence_kind !== "string") {
+        throw new Error("plan-sequence: sequence_kind required");
+    }
+    if (!Array.isArray(obj.entries) || obj.entries.length === 0) {
+        throw new Error("plan-sequence: entries must be a non-empty array");
+    }
+    const entries = obj.entries.map((item, i) => {
+        if (item === null || typeof item !== "object") {
+            throw new Error(`plan-sequence: entries[${i}] must be an object`);
+        }
+        const e = item;
+        if (typeof e.id !== "string" || typeof e.kind !== "string") {
+            throw new Error(`plan-sequence: entries[${i}] requires id and kind`);
+        }
+        return {
+            id: e.id,
+            kind: e.kind,
+            title: typeof e.title === "string" ? e.title : undefined,
+            issue: typeof e.issue === "number" ? e.issue : undefined,
+            status: e.status === "completed" || e.status === "skipped" || e.status === "pending"
+                ? e.status
+                : "pending",
+        };
+    });
+    const current_index = typeof obj.current_index === "number" ? obj.current_index : 0;
+    const exhausted = obj.exhausted === true || current_index >= entries.length;
+    return {
+        sequence_id: obj.sequence_id,
+        sequence_kind: obj.sequence_kind,
+        entries,
+        current_index,
+        batching_allowed: obj.batching_allowed === true,
+        continuation_past_final: obj.continuation_past_final === true,
+        exhausted,
+        authorized_by: typeof obj.authorized_by === "string" ? obj.authorized_by : "",
+        created_at: typeof obj.created_at === "string" ? obj.created_at : new Date().toISOString(),
+        updated_at: typeof obj.updated_at === "string" ? obj.updated_at : new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/preflight/evaluate.d.ts

@@ -2,8 +2,11 @@
 export declare const ACTIVE_FOLDER = "active";
 /** Canonical eligibility status — only `running` signals an active handoff. */
 export declare const ELIGIBLE_STATUS = "running";
-/** Actionable redirect appended to every reject path (#810). */
-export declare const ACTIVATE_HINT = "Run `task vbrief:activate {path}` before spawning an implementation agent.";
+/** Actionable redirect appended to every reject path (#810 / #2449). */
+export declare const ACTIVATE_HINT = "Run `task scope:activate -- {path}` (or legacy `task vbrief:activate -- {path}`) before spawning an implementation agent.";
+/** Lifecycle folder names eligible for implementation (#810). */
+export declare const ELIGIBLE_LIFECYCLE_DIRS: readonly ["xbrief/active", "vbrief/active"];
+export declare const PREFLIGHT_USAGE_HINT = "Expected: `task xbrief:preflight -- xbrief/active/<story>.xbrief.json` (legacy: `task vbrief:preflight -- <path>`).";
 /** Result of a vBRIEF preflight evaluation; mirrors the Python `evaluate` tuple. */
 export interface EvaluateResult {
     readonly exitCode: 0 | 1;

package/dist/preflight/evaluate.js

@@ -4,14 +4,17 @@ import { basename, dirname } from "node:path";
 export const ACTIVE_FOLDER = "active";
 /** Canonical eligibility status — only `running` signals an active handoff. */
 export const ELIGIBLE_STATUS = "running";
-/** Actionable redirect appended to every reject path (#810). */
-export const ACTIVATE_HINT = "Run `task vbrief:activate {path}` before spawning an implementation agent.";
+/** Actionable redirect appended to every reject path (#810 / #2449). */
+export const ACTIVATE_HINT = "Run `task scope:activate -- {path}` (or legacy `task vbrief:activate -- {path}`) before spawning an implementation agent.";
+/** Lifecycle folder names eligible for implementation (#810). */
+export const ELIGIBLE_LIFECYCLE_DIRS = ["xbrief/active", "vbrief/active"];
+export const PREFLIGHT_USAGE_HINT = "Expected: `task xbrief:preflight -- xbrief/active/<story>.xbrief.json` (legacy: `task vbrief:preflight -- <path>`).";
 /** Substitute `{path}` without `$`-pattern expansion in user paths (#1721). */
 export function formatActivateHint(path) {
     return ACTIVATE_HINT.replace("{path}", () => path);
 }
 function buildReject(path, reason) {
-    return `${reason}\n  ${formatActivateHint(path)}`;
+    return `${reason}\n  ${PREFLIGHT_USAGE_HINT}\n  ${formatActivateHint(path)}`;
 }
 /** Map Node `JSON.parse` errors to CPython `json.JSONDecodeError.msg` for parity (#1721). */
 function nodeJsonErrorToPythonMsg(nodeMessage) {
@@ -91,10 +94,12 @@ export function evaluate(vbriefPath) {
         };
     }
     const folder = basename(dirname(vbriefPath));
+    const parent = basename(dirname(dirname(vbriefPath)));
+    const lifecycleDir = `${parent}/${folder}`;
     if (folder !== ACTIVE_FOLDER) {
         return {
             exitCode: 1,
-            message: buildReject(path, `vBRIEF is in ${folder}/ -- only vbrief/active/ is eligible for implementation.`),
+            message: buildReject(path, `xBRIEF is in ${lifecycleDir}/ -- only xbrief/active/ (or legacy vbrief/active/) is eligible for implementation.`),
         };
     }
     const record = payload;

package/dist/preflight/index.d.ts

@@ -1,3 +1,3 @@
 export type { EvaluateResult } from "./evaluate.js";
-export { ACTIVATE_HINT, ACTIVE_FOLDER, ELIGIBLE_STATUS, emitJson, evaluate, formatActivateHint, } from "./evaluate.js";
+export { ACTIVATE_HINT, ACTIVE_FOLDER, ELIGIBLE_LIFECYCLE_DIRS, ELIGIBLE_STATUS, emitJson, evaluate, formatActivateHint, PREFLIGHT_USAGE_HINT, } from "./evaluate.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/preflight/index.js

@@ -1,2 +1,2 @@
-export { ACTIVATE_HINT, ACTIVE_FOLDER, ELIGIBLE_STATUS, emitJson, evaluate, formatActivateHint, } from "./evaluate.js";
+export { ACTIVATE_HINT, ACTIVE_FOLDER, ELIGIBLE_LIFECYCLE_DIRS, ELIGIBLE_STATUS, emitJson, evaluate, formatActivateHint, PREFLIGHT_USAGE_HINT, } from "./evaluate.js";
 //# sourceMappingURL=index.js.map

package/dist/release/pipeline-fixture.d.ts

@@ -0,0 +1,3 @@
+/** Seed a real on-disk project root for pipeline write-path tests (#2470). */
+export declare function seedReleaseProjectDir(changelog?: string): string;
+//# sourceMappingURL=pipeline-fixture.d.ts.map

package/dist/release/pipeline-fixture.js

@@ -0,0 +1,11 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/** Seed a real on-disk project root for pipeline write-path tests (#2470). */
+export function seedReleaseProjectDir(changelog = `## [Unreleased]\n\n### Added\n- x\n`) {
+    const dir = mkdtempSync(join(tmpdir(), "release-proj-"));
+    writeFileSync(join(dir, "CHANGELOG.md"), changelog, "utf8");
+    writeFileSync(join(dir, "ROADMAP.md"), "# Roadmap\n", "utf8");
+    return dir;
+}
+//# sourceMappingURL=pipeline-fixture.js.map

package/dist/release/pipeline.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { assertProjectionContained } from "../fs/projection-containment.js";
 import { prependUpgradeBanner, promoteChangelog, sectionForVersion } from "./changelog.js";
 import { EXIT_CONFIG_ERROR, EXIT_OK, EXIT_VIOLATION, RELEASE_ARTIFACTS, TOTAL_STEPS, VERIFY_DRAFT_INTERVAL_SECONDS, VERIFY_DRAFT_MAX_ATTEMPTS, } from "./constants.js";
 import { checkTagAvailable, createGithubRelease, readTextFile, verifyReleaseDraft } from "./gh.js";
@@ -16,6 +17,7 @@ export function runPipeline(config, seams = {}) {
     const version = config.version;
     const today = (seams.todayIso ?? todayIso)();
     const changelogPath = join(projectRoot, "CHANGELOG.md");
+    const roadmapPath = join(projectRoot, "ROADMAP.md");
     const readFile = seams.readFile ?? ((p) => readFileSync(p, "utf8"));
     const writeFile = seams.writeFile ?? ((p, c) => writeFileSync(p, c, "utf8"));
     const fileExists = seams.fileExists ?? ((p) => existsSync(p));
@@ -149,6 +151,7 @@ export function runPipeline(config, seams = {}) {
         emit(6, label, `DRYRUN (would rewrite CHANGELOG.md: ## [Unreleased] -> ## [${version}] - ${today}; new compare link added;${summaryNote})`);
     }
     else {
+        assertProjectionContained(projectRoot, changelogPath);
         writeFile(changelogPath, promotedChangelog);
         emit(6, label, `OK (## [${version}] - ${today};${summaryNote})`);
     }
@@ -158,6 +161,7 @@ export function runPipeline(config, seams = {}) {
         emit(7, label, "DRYRUN (would run task roadmap:render)");
     }
     else {
+        assertProjectionContained(projectRoot, roadmapPath);
         const [ok, reason] = refreshRoadmapFn(projectRoot);
         if (ok) {
             emit(7, label, `OK (${reason})`);

package/dist/release/version.d.ts

@@ -8,4 +8,6 @@ export declare function isPrereleaseTag(version: string): boolean;
 /** Normalize a semver-shaped release tag to a PEP 440 version string (#771). */
 export declare function toPep440(version: string): string;
 export declare function isPublishable(version: string): boolean;
+/** Compare two publishable Deft release versions using stable/prerelease ordering. */
+export declare function comparePublishableVersions(left: string, right: string): -1 | 0 | 1;
 //# sourceMappingURL=version.d.ts.map

package/dist/release/version.js

@@ -5,6 +5,12 @@ const PRE_KIND_MAP = {
     rc: "rc",
 };
 const NON_PUBLISHABLE_KINDS = new Set(["test"]);
+const PRERELEASE_RANK = {
+    alpha: 0,
+    beta: 1,
+    rc: 2,
+    "": 3,
+};
 export class NonPublishableVersionError extends Error {
     constructor(message) {
         super(message);
@@ -71,4 +77,40 @@ export function isPublishable(version) {
         return false;
     }
 }
+function publishableVersionSortKey(version) {
+    const candidate = version.trim();
+    const match = PEP440_TAG_RE.exec(candidate);
+    if (match?.groups === undefined) {
+        throw new Error(`Cannot compare '${candidate}': expected ` + "[v]X.Y.Z or [v]X.Y.Z-(rc|alpha|beta).N");
+    }
+    const kind = match.groups.kind ?? "";
+    if (NON_PUBLISHABLE_KINDS.has(kind)) {
+        throw new NonPublishableVersionError(`Version '${candidate}' carries non-publishable pre-release tag '${kind}'.${match.groups.num}.`);
+    }
+    const rank = PRERELEASE_RANK[kind];
+    if (rank === undefined) {
+        throw new Error(`Cannot compare '${candidate}': unsupported pre-release kind '${kind}'.`);
+    }
+    return [
+        Number(match.groups.major),
+        Number(match.groups.minor),
+        Number(match.groups.patch),
+        rank,
+        Number(match.groups.num ?? 0),
+    ];
+}
+/** Compare two publishable Deft release versions using stable/prerelease ordering. */
+export function comparePublishableVersions(left, right) {
+    const leftKey = publishableVersionSortKey(left);
+    const rightKey = publishableVersionSortKey(right);
+    for (let index = 0; index < leftKey.length; index += 1) {
+        const leftPart = leftKey[index] ?? 0;
+        const rightPart = rightKey[index] ?? 0;
+        if (leftPart < rightPart)
+            return -1;
+        if (leftPart > rightPart)
+            return 1;
+    }
+    return 0;
+}
 //# sourceMappingURL=version.js.map

package/dist/release-e2e/npm-ops.js

@@ -1,6 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { defaultWhich, spawnText } from "../release/spawn.js";
+import { defaultWhich } from "../release/spawn.js";
+import { resolveCommandOnPath, spawnCommandText } from "../verify-env/command-spawn.js";
 import { MODULE_NOT_FOUND_MARKERS, NPM_BUILD_TIMEOUT_SECONDS, NPM_E2E_REHEARSAL_TAG, NPM_INSTALL_RUN_TIMEOUT_SECONDS, NPM_INSTALL_TIMEOUT_SECONDS, NPM_PACK_TIMEOUT_SECONDS, NPM_PUBLISH_DRYRUN_TIMEOUT_SECONDS, NPM_PUBLISH_PACKAGES, } from "./constants.js";
 /**
  * npm publish dry-run rehearsal (#1910) -- the TS port of the
@@ -18,19 +19,32 @@ function resolveWhich(seams) {
  * available.
  */
 export function resolvePnpm(seams = {}) {
-    const which = resolveWhich(seams);
-    const pnpm = which("pnpm");
+    // Injected which seam wins for unit tests; production uses PATHEXT-aware PATH scan
+    // so `where pnpm` extensionless shims do not ENOENT under spawnSync (#2548 / #2467).
+    if (seams.which ?? seams.whichGh) {
+        const which = resolveWhich(seams);
+        const pnpm = which("pnpm");
+        if (pnpm) {
+            return [pnpm];
+        }
+        const corepack = which("corepack");
+        if (corepack) {
+            return [corepack, "pnpm"];
+        }
+        return null;
+    }
+    const pnpm = resolveCommandOnPath("pnpm");
     if (pnpm) {
         return [pnpm];
     }
-    const corepack = which("corepack");
+    const corepack = resolveCommandOnPath("corepack");
     if (corepack) {
         return [corepack, "pnpm"];
     }
     return null;
 }
 function runNpmStep(cmd, cwd, env, label, timeoutSeconds, seams) {
-    const spawn = seams.spawnText ?? spawnText;
+    const spawn = seams.spawnText ?? spawnCommandText;
     const head = cmd[0] ?? "";
     const result = spawn(head, cmd.slice(1), {
         cwd,
@@ -217,7 +231,7 @@ export function rehearseNpmInstallAndRun(cloneDir, version, seams = {}, options
     [ok, reason] = runNpmStep(installArgs, consumerDir, env, "npm install packed tarballs", NPM_INSTALL_RUN_TIMEOUT_SECONDS, seams);
     if (!ok)
         return [false, reason];
-    const spawn = seams.spawnText ?? spawnText;
+    const spawn = seams.spawnText ?? spawnCommandText;
     const cliBin = join(consumerDir, "node_modules", "@deftai", "directive", "dist", "bin.js");
     // Liveness probe (#2010): `--version` loads the cli + core engine via
     // engineInfo(), exercising the cross-package import path that #1993 broke,

package/dist/scope/transition.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, renameSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { InstrumentedVbriefCrud, persistCrudMetrics } from "../eval/crud-telemetry.js";
+import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { hasArtifactSuffix } from "../layout/resolve.js";
 import { append, canonicalLogPath, newDecisionId } from "./audit-log.js";
 import { stampCompletionMetadata } from "./capacity-stamp.js";
@@ -76,11 +77,25 @@ export function runTransition(action, filePath, now = new Date()) {
             message: `No-op: ${basename} is already in ${currentFolder}/ (status: ${currentStatus})`,
         };
     }
+    const vbriefRoot = dirname(dirname(resolvedPath));
+    const projectRoot = dirname(vbriefRoot);
+    if (targetFolder !== null) {
+        const destDir = join(vbriefRoot, targetFolder);
+        try {
+            // #2447: refuse lifecycle moves when the destination folder escapes the checkout.
+            // Run before mutating the source file so a refusal leaves lifecycle state intact.
+            assertProjectionContained(projectRoot, destDir);
+        }
+        catch (err) {
+            if (err instanceof ProjectionContainmentError) {
+                return { ok: false, message: err.message };
+            }
+            throw err;
+        }
+    }
     const nowIso = utcNowIso(now);
     planObj.status = targetStatus;
     planObj.updated = nowIso;
-    const vbriefRoot = dirname(dirname(resolvedPath));
-    const projectRoot = dirname(vbriefRoot);
     if (act === "complete") {
         stampCompletionMetadata(planObj, projectRoot, nowIso);
     }

package/dist/scope/vbrief-ref.d.ts

@@ -1,4 +1,10 @@
+import { ProjectionContainmentError } from "../fs/projection-containment.js";
 import { type ResolveLifecycleArtifactRefOptions } from "../layout/lifecycle-ref.js";
+export { ProjectionContainmentError as LifecycleRefContainmentError };
+/** Reject absolute or `..`-escaping lifecycle refs before path resolution (#2470). */
+export declare function rejectEscapingLifecycleRel(rel: string): void;
+/** Assert a resolved lifecycle artifact path stays under the lifecycle root (#2470). */
+export declare function assertLifecycleArtifactContained(lifecycleRoot: string, resolvedPath: string): void;
 /** Resolve a vBRIEF reference URI to an absolute path, or null. */
 export declare function resolveVbriefRef(uri: unknown, vbriefDir: string, options?: ResolveLifecycleArtifactRefOptions): string | null;
 /** Collect planRef values from the plan root and top-level items. */

package/dist/scope/vbrief-ref.js

@@ -1,7 +1,23 @@
-import { resolve, sep } from "node:path";
+import { isAbsolute, resolve, sep } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
+import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { resolveLifecycleArtifactRef, } from "../layout/lifecycle-ref.js";
 import { hasArtifactSuffix, stripArtifactSuffix } from "../layout/resolve.js";
+export { ProjectionContainmentError as LifecycleRefContainmentError };
+/** Reject absolute or `..`-escaping lifecycle refs before path resolution (#2470). */
+export function rejectEscapingLifecycleRel(rel) {
+    if (isAbsolute(rel)) {
+        throw new ProjectionContainmentError(`lifecycle ref refused: absolute path ${rel} is not allowed under the lifecycle root`, { projectDir: "", targetPath: rel, offendingPath: rel });
+    }
+    const segments = rel.split(/[/\\]+/).filter((segment) => segment.length > 0);
+    if (segments.includes("..")) {
+        throw new ProjectionContainmentError(`lifecycle ref refused: path ${rel} contains parent traversal (..)`, { projectDir: "", targetPath: rel, offendingPath: rel });
+    }
+}
+/** Assert a resolved lifecycle artifact path stays under the lifecycle root (#2470). */
+export function assertLifecycleArtifactContained(lifecycleRoot, resolvedPath) {
+    assertProjectionContained(lifecycleRoot, resolvedPath);
+}
 /** Resolve a vBRIEF reference URI to an absolute path, or null. */
 export function resolveVbriefRef(uri, vbriefDir, options = {}) {
     if (typeof uri !== "string" || uri.length === 0) {
@@ -17,7 +33,10 @@ export function resolveVbriefRef(uri, vbriefDir, options = {}) {
     else {
         rel = uri;
     }
-    return resolveLifecycleArtifactRef(rel, vbriefDir, options);
+    rejectEscapingLifecycleRel(rel);
+    const resolved = resolveLifecycleArtifactRef(rel, vbriefDir, options);
+    assertLifecycleArtifactContained(vbriefDir, resolved);
+    return resolved;
 }
 /** Collect planRef values from the plan root and top-level items. */
 export function collectPlanRefs(plan) {

package/dist/session/index.d.ts

@@ -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";