@deftai/directive-core 0.65.0 → 0.66.0

package/dist/policy/plan-extensions.js

@@ -0,0 +1,57 @@
+/**
+ * Namespaced directive-config keys on a vBRIEF `plan` object (#1650 / #2034).
+ *
+ * "Category B" keys (`policy`, `completedNote`) are directive's OWN engine
+ * config -- not generic xbrief/consumer-extension data -- so they live under
+ * the `x-directive/` extension prefix that the conformance gate already
+ * accepts (#1620 EXTENSION_PREFIXES). Once the corpus is namespaced the
+ * conformance allow-list is removed, so any future bare `plan.policy` /
+ * `plan.completedNote` fails the gate.
+ *
+ * Read accessors accept the legacy bare key as a back-compat fallback so an
+ * un-migrated consumer PROJECT-DEFINITION keeps resolving while the operator
+ * migrates; writers always emit (and fold a legacy block into) the namespaced
+ * key.
+ */
+/** Namespaced directive policy block key. */
+export const PLAN_POLICY_KEY = "x-directive/policy";
+/** Namespaced directive scope-completion note key. */
+export const PLAN_COMPLETED_NOTE_KEY = "x-directive/completedNote";
+/** Legacy bare policy key (pre-#1650); read-side fallback / write-side migration source. */
+export const LEGACY_PLAN_POLICY_KEY = "policy";
+/** Legacy bare completedNote key (pre-#1650); read-side fallback / write-side migration source. */
+export const LEGACY_PLAN_COMPLETED_NOTE_KEY = "completedNote";
+function asPlanObject(plan) {
+    return typeof plan === "object" && plan !== null && !Array.isArray(plan)
+        ? plan
+        : null;
+}
+function readPlanExtension(plan, namespacedKey, legacyKey) {
+    const planObj = asPlanObject(plan);
+    if (planObj === null) {
+        return undefined;
+    }
+    const namespaced = planObj[namespacedKey];
+    return namespaced !== undefined ? namespaced : planObj[legacyKey];
+}
+/** Read the directive policy block from a plan (namespaced first, bare fallback). */
+export function readPlanPolicy(plan) {
+    return readPlanExtension(plan, PLAN_POLICY_KEY, LEGACY_PLAN_POLICY_KEY);
+}
+/** Read the directive completedNote from a plan (namespaced first, bare fallback). */
+export function readPlanCompletedNote(plan) {
+    return readPlanExtension(plan, PLAN_COMPLETED_NOTE_KEY, LEGACY_PLAN_COMPLETED_NOTE_KEY);
+}
+/**
+ * Rename a legacy bare `policy` key to the namespaced key in place when only
+ * the bare key is present. No-op when the namespaced key already exists or no
+ * policy key is present. Used by writers so a mutation never strands a legacy
+ * bare block alongside the namespaced one.
+ */
+export function migrateLegacyPolicyKey(plan) {
+    if (plan[PLAN_POLICY_KEY] === undefined && plan[LEGACY_PLAN_POLICY_KEY] !== undefined) {
+        plan[PLAN_POLICY_KEY] = plan[LEGACY_PLAN_POLICY_KEY];
+        delete plan[LEGACY_PLAN_POLICY_KEY];
+    }
+}
+//# sourceMappingURL=plan-extensions.js.map

package/dist/policy/resolve.d.ts

@@ -1,4 +1,4 @@
-/** Filesystem-relative location of the project-definition vBRIEF. */
+/** Filesystem-relative location of the project-definition vBRIEF (display/back-compat). */
 export declare const PROJECT_DEFINITION_REL_PATH = "vbrief/PROJECT-DEFINITION.vbrief.json";
 /** Environment variable emergency bypass for branch protection (#747). */
 export declare const ENV_BYPASS = "DEFT_ALLOW_DEFAULT_BRANCH_COMMIT";
@@ -13,7 +13,11 @@ export interface PolicyResult {
     readonly deprecationWarning: string | null;
     readonly error: string | null;
 }
-/** Resolve absolute path to PROJECT-DEFINITION.vbrief.json. */
+/**
+ * Resolve absolute path to PROJECT-DEFINITION. Layout-aware (#2109 part 2a):
+ * resolves PROJECT-DEFINITION.xbrief.json when the xbrief layout is present,
+ * else PROJECT-DEFINITION.vbrief.json (unchanged on today's tree).
+ */
 export declare function projectDefinitionPath(projectRoot: string): string;
 /** Best-effort coerce a legacy narrative value to a boolean. */
 export declare function coerceLegacyNarrative(value: unknown): {

package/dist/policy/resolve.js

@@ -1,6 +1,8 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve as pathResolve } from "node:path";
-/** Filesystem-relative location of the project-definition vBRIEF. */
+import { resolveProjectDefinitionPath } from "../layout/resolve.js";
+import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
+/** Filesystem-relative location of the project-definition vBRIEF (display/back-compat). */
 export const PROJECT_DEFINITION_REL_PATH = "vbrief/PROJECT-DEFINITION.vbrief.json";
 /** Environment variable emergency bypass for branch protection (#747). */
 export const ENV_BYPASS = "DEFT_ALLOW_DEFAULT_BRANCH_COMMIT";
@@ -9,9 +11,13 @@ export const LEGACY_NARRATIVE_KEY = "Allow direct commits to master";
 /** Audit log relative path (#746). */
 export const AUDIT_LOG_REL_PATH = "meta/policy-changes.log";
 const TRUTHY = new Set(["1", "true", "yes", "on"]);
-/** Resolve absolute path to PROJECT-DEFINITION.vbrief.json. */
+/**
+ * Resolve absolute path to PROJECT-DEFINITION. Layout-aware (#2109 part 2a):
+ * resolves PROJECT-DEFINITION.xbrief.json when the xbrief layout is present,
+ * else PROJECT-DEFINITION.vbrief.json (unchanged on today's tree).
+ */
 export function projectDefinitionPath(projectRoot) {
-    return join(pathResolve(projectRoot), PROJECT_DEFINITION_REL_PATH);
+    return resolveProjectDefinitionPath(pathResolve(projectRoot));
 }
 function envBypassActive() {
     const raw = process.env[ENV_BYPASS] ?? "";
@@ -109,7 +115,7 @@ export function resolvePolicy(projectRoot) {
         };
     }
     const planObj = plan;
-    const policyBlock = planObj.policy;
+    const policyBlock = readPlanPolicy(planObj);
     if (typeof policyBlock === "object" &&
         policyBlock !== null &&
         !Array.isArray(policyBlock) &&
@@ -188,15 +194,19 @@ export function setPolicy(projectRoot, options) {
         }
     }
     const plan = data.plan;
-    if (typeof plan.policy !== "object" || plan.policy === null || Array.isArray(plan.policy)) {
-        if (plan.policy === undefined) {
-            plan.policy = {};
+    migrateLegacyPolicyKey(plan);
+    const existingPolicy = plan[PLAN_POLICY_KEY];
+    if (typeof existingPolicy !== "object" ||
+        existingPolicy === null ||
+        Array.isArray(existingPolicy)) {
+        if (existingPolicy === undefined) {
+            plan[PLAN_POLICY_KEY] = {};
         }
         else {
             throw new Error("plan.policy is not an object");
         }
     }
-    const policyBlock = plan.policy;
+    const policyBlock = plan[PLAN_POLICY_KEY];
     const previous = policyBlock.allowDirectCommitsToMaster;
     policyBlock.allowDirectCommitsToMaster = Boolean(allowDirectCommits);
     let legacyDropped = false;

package/dist/policy/wip.js

@@ -1,5 +1,7 @@
 import { existsSync, readdirSync } from "node:fs";
-import { join, resolve as pathResolve } from "node:path";
+import { join } from "node:path";
+import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
+import { readPlanPolicy } from "./plan-extensions.js";
 import { loadProjectDefinition } from "./resolve.js";
 /** Framework default WIP cap (#1124 / umbrella #1119). */
 export const DEFAULT_WIP_CAP = 10;
@@ -43,7 +45,7 @@ export function resolveWipCap(projectRoot) {
             error: "PROJECT-DEFINITION 'plan' is not an object",
         };
     }
-    const policyBlock = plan.policy;
+    const policyBlock = readPlanPolicy(plan);
     if (typeof policyBlock !== "object" ||
         policyBlock === null ||
         Array.isArray(policyBlock) ||
@@ -63,7 +65,7 @@ export function resolveWipCap(projectRoot) {
 /** Count *.vbrief.json files in vbrief/pending/ + vbrief/active/ (#1124). */
 export function countVbriefWip(projectRoot) {
     let total = 0;
-    const vbriefRoot = join(pathResolve(projectRoot), "vbrief");
+    const vbriefRoot = resolveLifecycleRoot(projectRoot);
     for (const sub of WIP_LIFECYCLE_DIRS) {
         const folder = join(vbriefRoot, sub);
         if (!existsSync(folder)) {
@@ -71,7 +73,7 @@ export function countVbriefWip(projectRoot) {
         }
         const entries = readdirSync(folder, { withFileTypes: true });
         for (const entry of entries) {
-            if (entry.isFile() && entry.name.endsWith(".vbrief.json")) {
+            if (entry.isFile() && hasArtifactSuffix(entry.name)) {
                 total += 1;
             }
         }

package/dist/preflight-cache/evaluate.js

@@ -14,6 +14,8 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 import { probeCacheDrift } from "../cache/fetch.js";
+import { resolveEvalPath, resolveProjectDefinitionPath } from "../layout/resolve.js";
+import { readPlanPolicy } from "../policy/plan-extensions.js";
 import { latestDecisionForIssue as auditLatestDecisionForIssue } from "../triage/actions/candidates-log.js";
 // ---------------------------------------------------------------------------
 // Public constants (mirror preflight_cache.py)
@@ -176,7 +178,7 @@ function metaEntryIsTerminalClosed(metaPath) {
     return false;
 }
 function loadScopeRules(projectRoot) {
-    const defPath = join(projectRoot, "vbrief", "PROJECT-DEFINITION.vbrief.json");
+    const defPath = resolveProjectDefinitionPath(projectRoot);
     if (!existsSync(defPath))
         return null;
     try {
@@ -186,7 +188,7 @@ function loadScopeRules(projectRoot) {
         const plan = data.plan;
         if (plan === null || typeof plan !== "object" || Array.isArray(plan))
             return null;
-        const policy = plan.policy;
+        const policy = readPlanPolicy(plan);
         if (policy === null || typeof policy !== "object" || Array.isArray(policy))
             return null;
         const scope = policy.triageScope;
@@ -325,7 +327,8 @@ export function evaluate(projectRoot, options = {}) {
         (envMaxAgeParsed !== null && !Number.isNaN(envMaxAgeParsed) ? envMaxAgeParsed : null) ??
         DEFAULT_MAX_AGE_HOURS;
     const cacheRoot = join(projectRoot, CACHE_DIR_NAME);
-    const candidatesPath = join(projectRoot, CANDIDATES_RELPATH);
+    // Layout-aware (#2109 part 2a): resolve under xbrief/.eval when migrated.
+    const candidatesPath = resolveEvalPath(projectRoot, "candidates.jsonl");
     // Step 1: Resolve repo slug
     const resolvedRepo = resolveRepo(projectRoot, cacheRoot, source, options.repo ?? null);
     // Step 2: Check cache dir exists
@@ -357,7 +360,7 @@ export function evaluate(projectRoot, options = {}) {
         return {
             code: 2,
             message: [
-                `❌ deft cache-fresh: ${CANDIDATES_RELPATH} not found at ${projectRoot}.`,
+                `❌ deft cache-fresh: ${candidatesPath} not found.`,
                 REMEDIATION_NO_CANDIDATES,
             ].join("\n"),
         };
@@ -511,7 +514,7 @@ function evaluateForIssue(repo, issueNumber, candidatesPath, cacheRoot, source,
         return {
             code: 1,
             message: [
-                `❌ deft cache-fresh: issue #${issueNumber} has no triage decision in ${CANDIDATES_RELPATH}.`,
+                `❌ deft cache-fresh: issue #${issueNumber} has no triage decision in ${candidatesPath}.`,
                 `  Recovery: \`deft triage:accept -- --repo ${repo} --issue ${issueNumber}\` before dispatching an implementation agent.`,
             ].join("\n"),
         };

package/dist/release/native-steps.js

@@ -6,11 +6,12 @@ import { spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { fetchIssueStates, isTerminalLifecyclePath, reconcile, scanVbriefDir, } from "../intake/reconcile-issues.js";
+import { resolveLifecycleFolder, resolveLifecycleRoot } from "../layout/resolve.js";
 import { renderRoadmap } from "../render/roadmap-render.js";
 const BUILD_DIST_RUNNER = join(dirname(fileURLToPath(import.meta.url)), "build-dist-runner.js");
 export function refreshRoadmapNative(projectRoot) {
-    const pending = join(projectRoot, "vbrief", "pending");
-    const completed = join(projectRoot, "vbrief", "completed");
+    const pending = resolveLifecycleFolder(projectRoot, "pending");
+    const completed = resolveLifecycleFolder(projectRoot, "completed");
     const roadmap = join(projectRoot, "ROADMAP.md");
     const [ok, msg] = renderRoadmap(pending, roadmap, completed);
     if (!ok) {
@@ -19,7 +20,7 @@ export function refreshRoadmapNative(projectRoot) {
     return [true, "ROADMAP.md re-rendered"];
 }
 export function checkVbriefLifecycleSyncNative(projectRoot, repo) {
-    const vbriefDir = join(projectRoot, "vbrief");
+    const vbriefDir = resolveLifecycleRoot(projectRoot);
     try {
         const issueToVbriefs = scanVbriefDir(vbriefDir);
         const issueStateMap = fetchIssueStates(repo, new Set(issueToVbriefs.keys()), {

package/dist/render/framework-commands.js

@@ -3,6 +3,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { cmdDoctor } from "../doctor/main.js";
+import { resolveLifecycleRoot } from "../layout/resolve.js";
 function spec(name, entrypoint, opts = {}) {
     return { name, entrypoint, ...opts };
 }
@@ -232,7 +233,7 @@ function argvForSpec(commandSpec, argv, projectRoot, frameworkRoot) {
     if (commandSpec.frameworkRootArg)
         resolved.push(commandSpec.frameworkRootArg, frameworkRoot);
     if (commandSpec.vbriefDirArg)
-        resolved.push(commandSpec.vbriefDirArg, join(projectRoot, "vbrief"));
+        resolved.push(commandSpec.vbriefDirArg, resolveLifecycleRoot(projectRoot));
     if (commandSpec.rootArg)
         resolved.push(commandSpec.rootArg, frameworkRoot);
     resolved.push(...normalizeTaskSeparator(argv));

package/dist/render/prd-render.js

@@ -52,8 +52,8 @@ export function renderPrd(specPath, outputPath, options = {}) {
         }
     }
     lines.push("---\n" +
-        "*This document is auto-generated from `vbrief/specification.vbrief.json` " +
-        "via `task prd:render`. Do not edit directly.*\n");
+        "*This document is auto-generated from the specification artifact " +
+        "(e.g. `xbrief/specification.xbrief.json`) via `task prd:render`. Do not edit directly.*\n");
     writeFileSync(outputPath, lines.join("\n"), "utf8");
     process.stdout.write(`PRD.md written to ${outputPath}\n`);
 }

package/dist/render/project-render.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
+import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
 import { deriveRegistryItemStatus, registryMetadataReferencesFromScope, } from "../vbrief-validate/registry-status.js";
 import { PROJECT_LIFECYCLE_FOLDERS, SKELETON_NARRATIVES } from "./constants.js";
@@ -13,7 +14,7 @@ export function scanLifecycleFolders(vbriefDir) {
         let files;
         try {
             files = readdirSync(folder)
-                .filter((n) => n.endsWith(".vbrief.json"))
+                .filter((n) => hasArtifactSuffix(n))
                 .sort();
         }
         catch {
@@ -260,11 +261,28 @@ export function acknowledgeProjectDefinitionStaleness(vbriefDir, options = {}) {
 export function main(argv) {
     const acknowledge = argv[0] === "--acknowledge-staleness";
     const rest = acknowledge ? argv.slice(1) : argv;
-    if (rest.length > 1) {
-        process.stderr.write("Usage: project_render.py [--acknowledge-staleness] [vbrief_dir]\n");
+    let projectRoot;
+    const positional = [];
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (arg === "--project-root") {
+            projectRoot = rest[i + 1];
+            i += 1;
+        }
+        else if (arg.startsWith("--project-root=")) {
+            projectRoot = arg.slice("--project-root=".length);
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    if (positional.length > 1) {
+        process.stderr.write("Usage: project-render [--acknowledge-staleness] [--project-root <dir>] [vbrief_dir]\n");
         return 2;
     }
-    const vbriefDir = rest[0] ?? "vbrief";
+    const vbriefDir = projectRoot !== undefined
+        ? resolveLifecycleRoot(resolve(projectRoot))
+        : (positional[0] ?? "vbrief");
     const [ok, message] = acknowledge
         ? acknowledgeProjectDefinitionStaleness(vbriefDir)
         : renderProjectDefinition(vbriefDir);

package/dist/render/roadmap-render.js

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { MIGRATOR_METADATA_KEY, ROADMAP_BANNER } from "./constants.js";
 import { phaseSortKey } from "./text-utils.js";
 function scopeMetadataRank(plan) {
@@ -32,7 +33,7 @@ function loadVbriefs(folder) {
     let files;
     try {
         files = readdirSync(folder)
-            .filter((n) => n.endsWith(".vbrief.json"))
+            .filter((n) => hasArtifactSuffix(n))
             .sort();
     }
     catch {
@@ -363,10 +364,10 @@ export function renderRoadmap(pendingDir, outPath, completedDir) {
 export function checkDrift(pendingDir, roadmapPath, completedDir) {
     const expected = renderRoadmapToBuffer(pendingDir, completedDir);
     if (!existsSync(roadmapPath)) {
-        const hasPending = existsSync(pendingDir) && readdirSync(pendingDir).some((n) => n.endsWith(".vbrief.json"));
+        const hasPending = existsSync(pendingDir) && readdirSync(pendingDir).some((n) => hasArtifactSuffix(n));
         const inferredCompleted = resolveCompletedDir(pendingDir, completedDir);
         const hasCompleted = existsSync(inferredCompleted) &&
-            readdirSync(inferredCompleted).some((n) => n.endsWith(".vbrief.json"));
+            readdirSync(inferredCompleted).some((n) => hasArtifactSuffix(n));
         if (!hasPending && !hasCompleted) {
             return [true, "✓ No ROADMAP.md needed (no pending or completed vBRIEFs)"];
         }
@@ -379,10 +380,37 @@ export function checkDrift(pendingDir, roadmapPath, completedDir) {
 }
 /** CLI entry (mirrors ``scripts/roadmap_render.main``). */
 export function main(argv) {
-    const positional = argv.filter((a) => !a.startsWith("--"));
-    const pendingDir = positional[0] ?? join(process.cwd(), "vbrief", "pending");
-    const outPath = positional[1] ?? join(process.cwd(), "ROADMAP.md");
-    if (argv.includes("--check")) {
+    let projectRoot;
+    let check = false;
+    const positional = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--project-root") {
+            projectRoot = argv[i + 1];
+            i += 1;
+        }
+        else if (arg.startsWith("--project-root=")) {
+            projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--check") {
+            check = true;
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    let pendingDir;
+    let outPath;
+    if (projectRoot !== undefined) {
+        const lifecycleRoot = resolveLifecycleRoot(resolve(projectRoot));
+        pendingDir = join(lifecycleRoot, "pending");
+        outPath = positional[0] ?? join(resolve(projectRoot), "ROADMAP.md");
+    }
+    else {
+        pendingDir = positional[0] ?? join(process.cwd(), "vbrief", "pending");
+        outPath = positional[1] ?? join(process.cwd(), "ROADMAP.md");
+    }
+    if (check) {
         const [ok, msg] = checkDrift(pendingDir, outPath);
         process.stdout.write(`${msg}\n`);
         return ok ? 0 : 1;

package/dist/render/scope-outlook.js

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { hasArtifactSuffix, stripArtifactSuffix } from "../layout/resolve.js";
 import { PROPOSED_DISCLAIMER_LINES, PROPOSED_STATUS_FILTER } from "../spec-authority/constants.js";
 import { SCOPE_SUMMARY_NARRATIVES } from "./constants.js";
 function readEdgeEndpoints(edge) {
@@ -14,7 +15,7 @@ function loadScopeVbriefs(folder) {
     let entries;
     try {
         entries = readdirSync(folder)
-            .filter((n) => n.endsWith(".vbrief.json"))
+            .filter((n) => hasArtifactSuffix(n))
             .sort();
     }
     catch {
@@ -24,7 +25,7 @@ function loadScopeVbriefs(folder) {
     for (const name of entries) {
         try {
             const data = JSON.parse(readFileSync(join(folder, name), "utf8"));
-            const stem = name.endsWith(".vbrief.json") ? name.slice(0, -".vbrief.json".length) : name;
+            const stem = stripArtifactSuffix(name);
             out.push([stem, data]);
         }
         catch {

package/dist/scope/audit-log.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync, writeSync, } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { AUDIT_LOG_REL_PATH } from "./constants.js";
+import { resolveEvalPath } from "../layout/resolve.js";
 import { utcNowIso } from "./vbrief-json.js";
 export class ScopeAuditLogError extends Error {
     constructor(message) {
@@ -94,7 +94,8 @@ export function newDecisionId() {
     return randomUUID();
 }
 export function canonicalLogPath(projectRoot) {
-    return join(resolve(projectRoot), AUDIT_LOG_REL_PATH);
+    // Layout-aware (#2109 part 2a): xbrief/.eval when migrated, else vbrief/.eval.
+    return resolveEvalPath(resolve(projectRoot), "scope-lifecycle.jsonl");
 }
 function withAppendLock(logPath, fn) {
     const lockPath = `${logPath}.lock`;

package/dist/scope/capacity-stamp.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { readPlanPolicy } from "../policy/plan-extensions.js";
 import { PROJECT_DEFINITION_REL_PATH } from "../policy/resolve.js";
 function resolveDefaultCapacityBucket(projectRoot) {
     try {
@@ -10,7 +11,7 @@ function resolveDefaultCapacityBucket(projectRoot) {
         if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
             return "";
         }
-        const policy = plan.policy;
+        const policy = readPlanPolicy(plan);
         if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
             return "";
         }

package/dist/scope/decompose.js

@@ -8,6 +8,8 @@
  */
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { referenceTypeMatches } from "@deftai/directive-types";
+import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { referenceWithDefaultTrust, slugify } from "../vbrief-build/build.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
 import { formatVbriefJson } from "./vbrief-json.js";
@@ -398,7 +400,7 @@ export function storyQualityIssues(opts) {
 // Path helpers
 // ---------------------------------------------------------------------------
 function vbriefDir(projectRoot) {
-    return join(resolve(projectRoot), "vbrief");
+    return resolveLifecycleRoot(projectRoot);
 }
 function relToVbrief(vbriefDirPath, path) {
     const resolvedPath = resolve(path);
@@ -507,7 +509,7 @@ function storyHasTraces(story, items, sw) {
     if (Array.isArray(refs)) {
         for (const ref of refs) {
             if (typeof ref === "object" && ref !== null && !Array.isArray(ref)) {
-                if (ref.type === "x-vbrief/spec-section")
+                if (referenceTypeMatches(String(ref.type ?? ""), "spec-section"))
                     return true;
             }
         }
@@ -752,7 +754,7 @@ function storyNarratives(story) {
 }
 function childFilename(story, stId, title, date) {
     const fn = story.filename;
-    if (typeof fn === "string" && fn.endsWith(".vbrief.json"))
+    if (typeof fn === "string" && hasArtifactSuffix(fn))
         return fn;
     const sl = slugify(title) || slugify(stId) || "story";
     return `${date}-${sl}.vbrief.json`;
@@ -891,7 +893,7 @@ export function applyDecomposition(opts) {
     for (const { target, title } of childPaths) {
         references.push(referenceWithDefaultTrust({
             uri: relToVbrief(vbriefDirPath, target),
-            type: "x-vbrief/plan",
+            type: "x-xbrief/plan",
             title,
         }));
     }

package/dist/scope/decomposed-refs.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
+import { referenceTypeMatches } from "@deftai/directive-types";
 import { formatVbriefJson } from "./vbrief-json.js";
 import { collectChildUris, collectPlanRefs, resolveVbriefRef } from "./vbrief-ref.js";
 function rewriteOnePlanRef(value, oldParentResolved, newParentRel, vbriefDir) {
@@ -36,7 +37,7 @@ function rewriteParentChildReference(parentPath, oldChildResolved, newChildRel,
             continue;
         }
         const r = ref;
-        if (r.type !== "x-vbrief/plan") {
+        if (!referenceTypeMatches(String(r.type ?? ""), "plan")) {
             continue;
         }
         const resolved = resolveVbriefRef(r.uri, vbriefDir);

package/dist/scope/demote.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
+import { hasArtifactSuffix, resolveLifecycleFolder } from "../layout/resolve.js";
 import { stripTrailingPathSeparators } from "../text/redos-safe.js";
 import { append, canonicalLogPath, latestForPath, newDecisionId } from "./audit-log.js";
 import { resolveProjectRoot } from "./project-context.js";
@@ -35,10 +36,10 @@ export function demoteOne(filePath, projectRoot, reason, options = {}) {
         return { ok: false, message: `File not found: ${resolved}`, auditEntry: null };
     }
     const basename = resolved.split(/[/\\]/).pop() ?? "";
-    if (!basename.endsWith(".vbrief.json")) {
+    if (!hasArtifactSuffix(basename)) {
         return {
             ok: false,
-            message: `Not a vBRIEF file (expected .vbrief.json): ${basename}`,
+            message: `Not a vBRIEF file (expected .vbrief.json or .xbrief.json): ${basename}`,
             auditEntry: null,
         };
     }
@@ -114,7 +115,7 @@ export function batchDemote(projectRoot, olderThanDays, options = {}) {
         throw new Error(`--older-than-days must be >= 0, got ${olderThanDays}`);
     }
     const now = options.now ?? new Date();
-    const pendingDir = join(resolve(projectRoot), "vbrief", SOURCE_FOLDER);
+    const pendingDir = resolveLifecycleFolder(projectRoot, SOURCE_FOLDER);
     if (!existsSync(pendingDir)) {
         return [0, [], []];
     }
@@ -124,7 +125,7 @@ export function batchDemote(projectRoot, olderThanDays, options = {}) {
     const skipped = [];
     let demoted = 0;
     const files = readdirSync(pendingDir)
-        .filter((name) => name.endsWith(".vbrief.json"))
+        .filter((name) => hasArtifactSuffix(name))
         .sort();
     for (const name of files) {
         const candidate = join(pendingDir, name);

package/dist/scope/project-context.js

@@ -1,6 +1,7 @@
 import { existsSync, statSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-const PROJECT_ROOT_SENTINELS = ["vbrief", ".git"];
+// Layout-aware (#2109 part 1): an xbrief-only tree is also a valid project root.
+const PROJECT_ROOT_SENTINELS = ["xbrief", "vbrief", ".git"];
 function isProjectRoot(candidate) {
     return PROJECT_ROOT_SENTINELS.some((sentinel) => existsSync(join(candidate, sentinel)));
 }

package/dist/scope/project-definition-sync.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { referenceTypeMatches } from "@deftai/directive-types";
 import { PROJECT_DEFINITION_REL_PATH } from "../policy/resolve.js";
 import { formatVbriefJson } from "./vbrief-json.js";
 import { relativeToVbrief, resolveVbriefRef, scopeIdsForFilename } from "./vbrief-ref.js";
@@ -8,7 +9,7 @@ function rewriteProjectDefinitionPlanReference(ref, oldResolved, newRel, vbriefR
         return false;
     }
     const r = ref;
-    if (r.type !== "x-vbrief/plan") {
+    if (!referenceTypeMatches(String(r.type ?? ""), "plan")) {
         return false;
     }
     const resolved = resolveVbriefRef(r.uri, vbriefRoot);
@@ -41,7 +42,7 @@ function projectItemReferencesScope(item, oldResolved, newResolved, vbriefRoot)
                     continue;
                 }
                 const r = ref;
-                if (r.type !== "x-vbrief/plan") {
+                if (!referenceTypeMatches(String(r.type ?? ""), "plan")) {
                     continue;
                 }
                 const resolved = resolveVbriefRef(r.uri, vbriefRoot);
@@ -58,7 +59,7 @@ function projectItemReferencesScope(item, oldResolved, newResolved, vbriefRoot)
                 continue;
             }
             const r = ref;
-            if (r.type !== "x-vbrief/plan") {
+            if (!referenceTypeMatches(String(r.type ?? ""), "plan")) {
                 continue;
             }
             const resolved = resolveVbriefRef(r.uri, vbriefRoot);

package/dist/scope/transition.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { hasArtifactSuffix } from "../layout/resolve.js";
 import { append, canonicalLogPath, newDecisionId } from "./audit-log.js";
 import { stampCompletionMetadata } from "./capacity-stamp.js";
 import { LIFECYCLE_FOLDERS, MOVE_LABELS, STATUS_PRECONDITIONS, STAY_LABELS, TRANSITIONS, } from "./constants.js";
@@ -17,8 +18,11 @@ export function runTransition(action, filePath, now = new Date()) {
         return { ok: false, message: `File not found: ${resolvedPath}` };
     }
     const basename = resolvedPath.split(/[/\\]/).pop() ?? "";
-    if (!basename.endsWith(".vbrief.json")) {
-        return { ok: false, message: `Not a vBRIEF file (expected .vbrief.json): ${basename}` };
+    if (!hasArtifactSuffix(basename)) {
+        return {
+            ok: false,
+            message: `Not a vBRIEF file (expected .vbrief.json or .xbrief.json): ${basename}`,
+        };
     }
     const currentFolder = detectLifecycleFolder(resolvedPath);
     if (currentFolder === null) {

package/dist/scope/undo.js

@@ -1,10 +1,11 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { basename, join, relative, resolve } from "node:path";
+import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { append, canonicalLogPath, newDecisionId, readAll } from "./audit-log.js";
 import { REVERSIBLE_ACTIONS, TERMINAL_ACTIONS } from "./constants.js";
 import { formatVbriefJson, utcNowIso } from "./vbrief-json.js";
 function vbriefRoot(projectRoot) {
-    return join(resolve(projectRoot), "vbrief");
+    return resolveLifecycleRoot(projectRoot);
 }
 function absForEntryPath(projectRoot, vbriefPath) {
     return resolve(projectRoot, vbriefPath);