@deftai/directive-core 0.74.0 → 0.76.0

package/dist/init-deposit/scaffold.js

@@ -10,12 +10,19 @@ import { mkdir, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { platform } from "node:os";
 import { dirname, join, relative } from "node:path";
 import { copyTree } from "../deposit/copy-tree.js";
+import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { agentsRefreshPlan } from "../platform/agents-md.js";
 import { MIGRATED_ARTIFACT_DIR } from "../xbrief-migrate/constants.js";
 import { CANONICAL_INSTALL_ROOT } from "./constants.js";
 import { installerManagedGuardEre } from "./hygiene.js";
 export { CANONICAL_INSTALL_ROOT };
 export const CORE_GLOB = ".deft/core/**";
+/** Refuse init/update projection writes that escape via repo-controlled symlinks (#2446). */
+function projectionTarget(projectDir, ...relSegments) {
+    const target = join(projectDir, ...relSegments);
+    assertProjectionContained(projectDir, target);
+    return target;
+}
 const CODEQL_CONFIG_REL = ".github/codeql/codeql-config.yml";
 const CORE_GUARD_WORKFLOW_REL = ".github/workflows/deft-core-guard.yml";
 const FRAMEWORK_SELF_TEST_REL = ".deft/core/tests";
@@ -232,7 +239,7 @@ export const PIN_DEPENDENCY_NAME = "@deftai/directive";
  */
 export function ensurePackageJsonPin(projectDir, version, io) {
     const pinVersion = version.trim().replace(/^v/i, "");
-    const path = join(projectDir, "package.json");
+    const path = projectionTarget(projectDir, "package.json");
     const existed = existsSync(path);
     let pkg = {};
     if (existed) {
@@ -284,7 +291,7 @@ export function writeAgentsMd(projectDir, deftDir, io) {
     if (typeof newContent !== "string") {
         throw new Error("AGENTS.md render produced no content");
     }
-    const path = join(projectDir, "AGENTS.md");
+    const path = projectionTarget(projectDir, "AGENTS.md");
     writeFileSync(path, newContent, "utf8");
     if (state === "absent") {
         io.printf("AGENTS.md created.\n");
@@ -294,9 +301,9 @@ export function writeAgentsMd(projectDir, deftDir, io) {
     }
     return true;
 }
-async function ensureVbriefLifecycleDirs(consumerVbrief) {
+async function ensureVbriefLifecycleDirs(projectDir) {
     for (const sub of VBRIEF_LIFECYCLE_DIRS) {
-        const dir = join(consumerVbrief, sub);
+        const dir = projectionTarget(projectDir, MIGRATED_ARTIFACT_DIR, sub);
         await mkdir(dir, { recursive: true, mode: 0o755 });
         const gitkeep = join(dir, ".gitkeep");
         try {
@@ -323,9 +330,9 @@ function vbriefLifecycleDirsPresent(consumerVbrief) {
     });
 }
 export async function writeConsumerVbrief(projectDir, deftDir, io) {
-    const consumerVbrief = join(projectDir, MIGRATED_ARTIFACT_DIR);
-    const schemasDst = join(consumerVbrief, "schemas");
-    const vbriefMdDst = join(consumerVbrief, "vbrief.md");
+    const consumerVbrief = projectionTarget(projectDir, MIGRATED_ARTIFACT_DIR);
+    const schemasDst = projectionTarget(projectDir, MIGRATED_ARTIFACT_DIR, "schemas");
+    const vbriefMdDst = projectionTarget(projectDir, MIGRATED_ARTIFACT_DIR, "vbrief.md");
     const schemasPresent = existsSync(schemasDst) && statSync(schemasDst).isDirectory();
     const vbriefMdPresent = existsSync(vbriefMdDst) && statSync(vbriefMdDst).isFile();
     const lifecyclePresent = vbriefLifecycleDirsPresent(consumerVbrief);
@@ -352,20 +359,21 @@ export async function writeConsumerVbrief(projectDir, deftDir, io) {
             writeFileSync(vbriefMdDst, VBRIEF_README_BODY, "utf8");
         }
     }
-    await ensureVbriefLifecycleDirs(consumerVbrief);
+    await ensureVbriefLifecycleDirs(projectDir);
     io.printf("vbrief/ deposited at project root (schemas + vbrief.md + lifecycle dirs).\n");
     return true;
 }
 export function writeAgentsSkills(projectDir, io) {
+    projectionTarget(projectDir, ".agents");
     const allExist = AGENTS_SKILLS.every((skill) => existsSync(join(projectDir, ".agents", "skills", skill.dir, "SKILL.md")));
     if (allExist) {
         io.printf(".agents/skills/ already present — skipping.\n");
         return false;
     }
     for (const skill of AGENTS_SKILLS) {
-        const dir = join(projectDir, ".agents", "skills", skill.dir);
+        const dir = projectionTarget(projectDir, ".agents", "skills", skill.dir);
         mkdirSync(dir, { recursive: true });
-        const path = join(dir, "SKILL.md");
+        const path = projectionTarget(projectDir, ".agents", "skills", skill.dir, "SKILL.md");
         if (existsSync(path))
             continue;
         writeFileSync(path, skill.content, "utf8");
@@ -412,7 +420,7 @@ function insertDeftIncludeAfterIncludesLine(content) {
     return { content, ok: false };
 }
 export function ensureTaskfile(projectDir, io) {
-    const path = join(projectDir, "Taskfile.yml");
+    const path = projectionTarget(projectDir, "Taskfile.yml");
     let existing = "";
     if (existsSync(path)) {
         existing = readFileSync(path, "utf8");
@@ -457,28 +465,32 @@ export function ensureTaskfile(projectDir, io) {
     return true;
 }
 const HOOK_FILENAMES = ["pre-commit", "pre-push"];
+const HOOK_SUPPORT_FILENAMES = ["_deft-run.sh"];
 const HOOK_FILE_MODE = 0o755;
+const HOOK_SUPPORT_FILE_MODE = 0o644;
 export function writeConsumerGitHooks(projectDir, deftDir, io, seams = {}) {
     const srcDir = join(deftDir, ".githooks");
     if (!existsSync(srcDir) || !statSync(srcDir).isDirectory()) {
         io.printf(`git hooks source ${srcDir} absent — skipping hook wiring.\n`);
         return false;
     }
-    const dstDir = join(projectDir, ".githooks");
+    const dstDir = projectionTarget(projectDir, ".githooks");
     mkdirSync(dstDir, { recursive: true });
     let filesDeposited = false;
-    for (const name of HOOK_FILENAMES) {
+    for (const name of [...HOOK_FILENAMES, ...HOOK_SUPPORT_FILENAMES]) {
         const src = join(srcDir, name);
         if (!existsSync(src))
             continue;
         const data = readFileSync(src);
-        const dst = join(dstDir, name);
+        const dst = projectionTarget(projectDir, ".githooks", name);
         const existing = existsSync(dst) ? readFileSync(dst) : null;
+        const isHookScript = HOOK_FILENAMES.includes(name);
         if (!existing?.equals(data)) {
-            writeFileSync(dst, data, { mode: HOOK_FILE_MODE });
+            const mode = isHookScript ? HOOK_FILE_MODE : HOOK_SUPPORT_FILE_MODE;
+            writeFileSync(dst, data, { mode });
             filesDeposited = true;
         }
-        if (platform() !== "win32") {
+        if (platform() !== "win32" && isHookScript) {
             try {
                 const mode = statSync(dst).mode & 0o777;
                 if ((mode & 0o111) === 0) {
@@ -652,7 +664,7 @@ function coreGuardWorkflowContent() {
         '          echo "OK: no mixed framework + app changes."\n');
 }
 export function ensureGitattributes(projectDir, io) {
-    const path = join(projectDir, ".gitattributes");
+    const path = projectionTarget(projectDir, ".gitattributes");
     const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
     const present = new Set(existing.split("\n").map((line) => line.trim()));
     const additions = CORE_GITATTRIBUTES_LINES.filter((line) => !present.has(line));
@@ -687,7 +699,7 @@ function appendGreptilePattern(patterns, glob) {
     return `${patterns}\n${glob}`;
 }
 export function ensureGreptileIgnore(projectDir, io) {
-    const path = join(projectDir, "greptile.json");
+    const path = projectionTarget(projectDir, "greptile.json");
     const fileExisted = existsSync(path);
     let raw = fileExisted ? readFileSync(path, "utf8") : "";
     if (!raw.trim())
@@ -762,7 +774,7 @@ function insertCodeqlPathsIgnore(content, glob) {
     return { content, ok: false };
 }
 export function ensureCodeqlPathsIgnore(projectDir, io) {
-    const path = join(projectDir, CODEQL_CONFIG_REL);
+    const path = projectionTarget(projectDir, CODEQL_CONFIG_REL);
     if (!existsSync(path)) {
         mkdirSync(dirname(path), { recursive: true });
         writeFileSync(path, codeqlConfigDefault(), "utf8");
@@ -783,7 +795,7 @@ export function ensureCodeqlPathsIgnore(projectDir, io) {
     return true;
 }
 export function ensureCoreGuardWorkflow(projectDir, io) {
-    const path = join(projectDir, CORE_GUARD_WORKFLOW_REL);
+    const path = projectionTarget(projectDir, CORE_GUARD_WORKFLOW_REL);
     const desired = coreGuardWorkflowContent();
     if (existsSync(path)) {
         const existing = readFileSync(path, "utf8");
@@ -862,6 +874,9 @@ export async function depositNeutralization(projectDir, io, options = {}) {
             await step();
         }
         catch (cause) {
+            if (cause instanceof ProjectionContainmentError) {
+                throw cause;
+            }
             io.printf(`Warning: neutralization step failed: ${String(cause)}\n`);
         }
     }

package/dist/intake/issue-emit.js

@@ -1,6 +1,6 @@
 import { globSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, relative, resolve } from "node:path";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
 import { call } from "../scm/call.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
@@ -217,7 +217,7 @@ export function expandPatterns(patterns, root = null) {
     const seen = new Set();
     const out = [];
     for (const pattern of patterns) {
-        const candidate = root !== null && !pattern.startsWith("/") ? join(root, pattern) : pattern;
+        const candidate = root !== null && !isAbsolute(pattern) ? join(root, pattern) : pattern;
         let matches = globSync(candidate).sort();
         if (matches.length === 0) {
             try {

package/dist/intake/issue-ingest.js

@@ -8,7 +8,7 @@ import { resolveProjectRoot } from "../scope/project-context.js";
 import { resolveProjectRepo } from "../slice/project-context.js";
 import { slugify, TODAY } from "../vbrief-build/build.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
-import { LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, LEGACY_VBRIEF_VERSION, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, VBRIEF_VERSION, } from "../xbrief-migrate/constants.js";
+import { LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, VBRIEF_VERSION, } from "../xbrief-migrate/constants.js";
 import { findAcHeading, parseCheckboxItems, parseListItems, sliceAcSection, stripCodeBlocks, stripFencedCodeBlocks, } from "./markdown-scanners.js";
 import { detectRepo, extractReferencesFromVbrief, fetchOpenIssues, GITHUB_ISSUE_REF_TYPES, LIFECYCLE_FOLDERS, parseIssueNumber, } from "./reconcile-issues.js";
 export const INGEST_STATUSES = ["proposed", "pending", "active"];
@@ -78,7 +78,7 @@ function resolveIngestEmissionLayout(vbriefDir) {
         return {
             artifactSuffix: LEGACY_ARTIFACT_SUFFIX,
             infoRootKey: LEGACY_INFO_ROOT_KEY,
-            infoVersion: LEGACY_VBRIEF_VERSION,
+            infoVersion: EMITTED_VBRIEF_VERSION,
         };
     }
     return {
@@ -300,11 +300,25 @@ export function issueCommentThread(issue) {
 export function issueCommentsAlreadyFetched(issue) {
     return Object.hasOwn(issue, ISSUE_COMMENT_THREAD_KEY);
 }
+/**
+ * Run quarantine `scan()` on untrusted ingest text (#2447). Fail closed on a
+ * credential hard-fail; return the fenced/quarantined transform for soft signals.
+ */
+function scanUntrustedIngestText(issueNumber, text) {
+    const scanResult = scan(text);
+    const hardFails = scanResult.flags.filter((f) => f.severity === "hard-fail");
+    if (hardFails.length > 0) {
+        throw new ScannerHardFailError(issueNumber, scanResult.flags);
+    }
+    return scanResult.transformed_content;
+}
 export function buildIssueVbrief(issue, status, repoUrl, options = {}) {
     const number = Number(issue.number);
-    const title = (typeof issue.title === "string" && issue.title.length > 0
+    const titleRaw = (typeof issue.title === "string" && issue.title.length > 0
         ? issue.title
         : `Issue #${number}`) || `Issue #${number}`;
+    // #2447: quarantine-scan issue title before it lands in agent-authoritative fields.
+    const title = scanUntrustedIngestText(number, titleRaw);
     const url = (typeof issue.url === "string" && issue.url.length > 0 ? issue.url : "") ||
         (repoUrl.length > 0 ? `${repoUrl}/issues/${number}` : "");
     const bodyRaw = issue.body;
@@ -345,7 +359,12 @@ export function buildIssueVbrief(issue, status, repoUrl, options = {}) {
     if (labelNames.length > 0) {
         narratives.Labels = labelNames.join(", ");
     }
-    const planItems = bodyStr.length > 0 ? extractPlanItems(bodyStr) : [];
+    const planItemsRaw = bodyStr.length > 0 ? extractPlanItems(bodyStr) : [];
+    // #2447: scan each derived plan-item title (empty-body issues still scan title above).
+    const planItems = planItemsRaw.map((item) => ({
+        ...item,
+        title: scanUntrustedIngestText(number, String(item.title ?? "")),
+    }));
     const plan = {
         title,
         status: planStatus,

package/dist/packaging/openpackage-tiers.d.ts

@@ -0,0 +1,12 @@
+export type OpenPackageTierName = "daily-core" | "standard" | "advanced";
+export interface OpenPackageTierManifest {
+    readonly defaultInstallTier: OpenPackageTierName;
+    readonly tiers: Record<OpenPackageTierName, {
+        skills: string[];
+    }>;
+}
+/** Default OpenPackage install tier from deft-tiers.json (#2494). */
+export declare function getOpenPackageDefaultInstallTier(repoRoot: string): OpenPackageTierName;
+/** Skill names for an OpenPackage tier selection (`all` = every mapped skill). */
+export declare function resolveOpenPackageTierSkills(repoRoot: string, tier: OpenPackageTierName | "all"): string[];
+//# sourceMappingURL=openpackage-tiers.d.ts.map

package/dist/packaging/openpackage-tiers.js

@@ -0,0 +1,42 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+const TIER_NAMES = ["daily-core", "standard", "advanced"];
+function isOpenPackageTierName(value) {
+    return TIER_NAMES.includes(value);
+}
+function loadOpenPackageTierManifest(repoRoot) {
+    const path = join(repoRoot, "packaging", "openpackage", "deft-tiers.json");
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (parsed === null || typeof parsed !== "object" || !parsed.tiers) {
+        throw new Error("deft-tiers.json must be an object with a tiers field");
+    }
+    for (const tier of TIER_NAMES) {
+        const block = parsed.tiers[tier];
+        if (!block || !Array.isArray(block.skills)) {
+            throw new Error(`deft-tiers.json missing tiers.${tier}.skills`);
+        }
+    }
+    const defaultInstallTier = parsed.defaultInstallTier ?? "daily-core";
+    if (!isOpenPackageTierName(defaultInstallTier)) {
+        throw new Error(`deft-tiers.json defaultInstallTier must be one of ${TIER_NAMES.join(", ")}; got ${defaultInstallTier}`);
+    }
+    return {
+        defaultInstallTier,
+        tiers: parsed.tiers,
+    };
+}
+function resolveTierSkills(manifest, tier) {
+    if (tier === "all") {
+        return [...new Set(TIER_NAMES.flatMap((name) => manifest.tiers[name].skills))];
+    }
+    return [...manifest.tiers[tier].skills];
+}
+/** Default OpenPackage install tier from deft-tiers.json (#2494). */
+export function getOpenPackageDefaultInstallTier(repoRoot) {
+    return loadOpenPackageTierManifest(repoRoot).defaultInstallTier;
+}
+/** Skill names for an OpenPackage tier selection (`all` = every mapped skill). */
+export function resolveOpenPackageTierSkills(repoRoot, tier) {
+    return resolveTierSkills(loadOpenPackageTierManifest(repoRoot), tier);
+}
+//# sourceMappingURL=openpackage-tiers.js.map

package/dist/policy/agents-md-budget.d.ts

@@ -9,9 +9,32 @@
  * it is an explicit, reviewed diff to this typed field -- that diff IS the
  * "was this growth deliberate?" checkpoint.
  */
+export type HarnessProfile = "cursor" | "none";
+export type SkillFrontmatterTier = "daily-core" | "all" | "none";
 export interface AgentsMdBudget {
     readonly managedMaxLines: number;
     readonly unmanagedMaxLines: number;
+    /**
+     * Fail-closed UTF-8 byte ratchet for the managed section (#2452).
+     * Seeded at the current measured size so the gate ships green; growth past
+     * this ceiling fails. The <=8192 B north-star is reported separately.
+     */
+    readonly absoluteMaxBytes?: number;
+    /**
+     * Harness profile for DD-3 skill-frontmatter measurement (#2463).
+     * When unset, the gate auto-detects `cursor` when `content/skills/` exists.
+     */
+    readonly harnessProfile?: HarnessProfile;
+    /**
+     * Skill tier for DD-3 frontmatter caps (`daily-core` vs `all` vs `none`).
+     * Defaults to `all` for reporting when unset.
+     */
+    readonly skillFrontmatterTier?: SkillFrontmatterTier;
+    /**
+     * Optional fail-closed ratchet for DD-3 skill-frontmatter bytes (#2463).
+     * Advisory when unset; growth past this ceiling fails when set.
+     */
+    readonly skillFrontmatterMaxBytes?: number;
 }
 export type AgentsMdBudgetSource = "typed" | "unset" | "default-on-error";
 export interface AgentsMdBudgetResult {

package/dist/policy/agents-md-budget.js

@@ -39,6 +39,19 @@ function readRegion(block, key) {
     }
     return { value: raw, error: null };
 }
+function readOptionalRegion(block, key) {
+    if (!(key in block)) {
+        return { value: undefined, error: null };
+    }
+    const raw = block[key];
+    if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
+        return {
+            value: undefined,
+            error: `plan.policy.agentsMdBudget.${key} must be a non-negative integer; got ${pythonTypeName(raw)} (${pythonRepr(raw)})`,
+        };
+    }
+    return { value: raw, error: null };
+}
 /** Resolve plan.policy.agentsMdBudget from PROJECT-DEFINITION (#645). */
 export function resolveAgentsMdBudget(projectRoot) {
     const [data, err] = loadProjectDefinition(projectRoot);
@@ -77,13 +90,71 @@ export function resolveAgentsMdBudget(projectRoot) {
     if (unmanaged.error !== null) {
         return { budget: null, source: "default-on-error", error: unmanaged.error };
     }
+    const absolute = readOptionalRegion(block, "absoluteMaxBytes");
+    if (absolute.error !== null) {
+        return { budget: null, source: "default-on-error", error: absolute.error };
+    }
+    const skillFrontmatterMax = readOptionalRegion(block, "skillFrontmatterMaxBytes");
+    if (skillFrontmatterMax.error !== null) {
+        return { budget: null, source: "default-on-error", error: skillFrontmatterMax.error };
+    }
+    const harnessProfile = readOptionalHarnessProfile(block, "harnessProfile");
+    if (harnessProfile.error !== null) {
+        return { budget: null, source: "default-on-error", error: harnessProfile.error };
+    }
+    const skillFrontmatterTier = readOptionalSkillTier(block, "skillFrontmatterTier");
+    if (skillFrontmatterTier.error !== null) {
+        return { budget: null, source: "default-on-error", error: skillFrontmatterTier.error };
+    }
+    const budget = {
+        managedMaxLines: managed.value,
+        unmanagedMaxLines: unmanaged.value,
+    };
+    const withOptional = {
+        ...budget,
+        ...(absolute.value !== undefined ? { absoluteMaxBytes: absolute.value } : {}),
+        ...(skillFrontmatterMax.value !== undefined
+            ? { skillFrontmatterMaxBytes: skillFrontmatterMax.value }
+            : {}),
+        ...(harnessProfile.value !== undefined ? { harnessProfile: harnessProfile.value } : {}),
+        ...(skillFrontmatterTier.value !== undefined
+            ? { skillFrontmatterTier: skillFrontmatterTier.value }
+            : {}),
+    };
     return {
-        budget: {
-            managedMaxLines: managed.value,
-            unmanagedMaxLines: unmanaged.value,
-        },
+        budget: withOptional,
         source: "typed",
         error: null,
     };
 }
+const HARNESS_PROFILES = new Set(["cursor", "none"]);
+const SKILL_FRONTMATTER_TIERS = new Set(["daily-core", "all", "none"]);
+function readOptionalHarnessProfile(block, key) {
+    if (!(key in block)) {
+        return { value: undefined, error: null };
+    }
+    const raw = block[key];
+    if (typeof raw !== "string" || !HARNESS_PROFILES.has(raw)) {
+        return {
+            value: undefined,
+            error: `plan.policy.agentsMdBudget.${key} must be one of ${[...HARNESS_PROFILES].join(", ")}; ` +
+                `got ${pythonTypeName(raw)} (${pythonRepr(raw)})`,
+        };
+    }
+    return { value: raw, error: null };
+}
+function readOptionalSkillTier(block, key) {
+    if (!(key in block)) {
+        return { value: undefined, error: null };
+    }
+    const raw = block[key];
+    if (typeof raw !== "string" || !SKILL_FRONTMATTER_TIERS.has(raw)) {
+        return {
+            value: undefined,
+            error: `plan.policy.agentsMdBudget.${key} must be one of ${[...SKILL_FRONTMATTER_TIERS].join(", ")}; ` +
+                `got ${pythonTypeName(raw)} (${pythonRepr(raw)})`,
+        };
+    }
+    return { value: raw, error: null };
+}
 //# sourceMappingURL=agents-md-budget.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/spawn.js

@@ -1,12 +1,14 @@
 import { spawnSync } from "node:child_process";
 import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 export function defaultWhich(name) {
-    const result = spawnSync("which", [name], { encoding: "utf8" });
+    const locator = process.platform === "win32" ? "where" : "which";
+    const result = spawnSync(locator, [name], { encoding: "utf8" });
     if (result.status !== 0) {
         return null;
     }
-    const path = (result.stdout ?? "").trim();
-    return path || null;
+    // `where` on Windows may return multiple lines; take the first non-empty match.
+    const first = (result.stdout ?? "").split(/\r?\n/).find((line) => line.trim().length > 0);
+    return first ? first.trim() : null;
 }
 export function spawnText(cmd, args, options = {}) {
     const result = spawnSync(cmd, [...args], {

package/dist/scope/decompose.js

@@ -7,7 +7,7 @@
  * that draft, writes the child story vBRIEFs, and updates the parent scope references.
  */
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
 import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, resolveLifecycleRoot, } from "../layout/resolve.js";
 import { referenceWithDefaultTrust, slugify } from "../vbrief-build/build.js";
@@ -415,7 +415,7 @@ function vbriefDir(projectRoot) {
 function relToVbrief(vbriefDirPath, path) {
     const resolvedPath = resolve(path);
     const resolvedVbrief = resolve(vbriefDirPath);
-    if (resolvedPath.startsWith(`${resolvedVbrief}/`) || resolvedPath === resolvedVbrief) {
+    if (resolvedPath.startsWith(resolvedVbrief + sep) || resolvedPath === resolvedVbrief) {
         return resolvedPath.slice(resolvedVbrief.length + 1).replace(/\\/g, "/");
     }
     throw new DecompositionError(`${path}: path must be inside ${vbriefDirPath}`);
@@ -823,7 +823,8 @@ export function applyDecomposition(opts) {
     if (!LIFECYCLE_FOLDERS.has(outputFolderName)) {
         throw new DecompositionError("output_dir must be a vbrief lifecycle folder");
     }
-    if (!outputDir.startsWith(`${resolve(vbriefDirPath)}/`) && outputDir !== resolve(vbriefDirPath)) {
+    const resolvedVbriefDir = resolve(vbriefDirPath);
+    if (!outputDir.startsWith(resolvedVbriefDir + sep) && outputDir !== resolvedVbriefDir) {
         throw new DecompositionError("output_dir must be inside vbrief/");
     }
     if (outputFolderName === "active") {

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. */