@deftai/directive-core 0.72.0 → 0.73.0

package/dist/layout/resolve.js

@@ -1,15 +1,18 @@
 import { readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, } from "../xbrief-migrate/constants.js";
-export { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, };
+import { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, } from "../xbrief-migrate/constants.js";
+export { LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, };
 /**
- * Lifecycle directory names recognized by the layout-aware resolver, in
- * preference order (migrated `xbrief` first, legacy `vbrief` second).
+ * Lifecycle directory names recognized by the layout-aware resolver and path
+ * validators. Includes both `xbrief` (canonical) and `vbrief` (legacy) so that
+ * path-validation helpers remain accurate during and after migration.
  */
 export const LIFECYCLE_DIR_NAMES = [MIGRATED_ARTIFACT_DIR, LEGACY_ARTIFACT_DIR];
 /**
- * Artifact filename suffixes recognized by the layout-aware resolver, in
- * preference order (`.xbrief.json` first, `.vbrief.json` second).
+ * Artifact filename suffixes recognized by the layout-aware resolver and path
+ * validators. Includes both `.xbrief.json` (canonical) and `.vbrief.json`
+ * (legacy) so that path-validation helpers remain accurate during and after
+ * migration.
  */
 export const ARTIFACT_SUFFIXES = [MIGRATED_ARTIFACT_SUFFIX, LEGACY_ARTIFACT_SUFFIX];
 function isDirectory(path) {
@@ -20,6 +23,25 @@ function isDirectory(path) {
         return false;
     }
 }
+/**
+ * Returns the layout root for non-layout-sensitive helpers (#2112).
+ *
+ * - If a valid `xbrief/` layout exists, returns its root.
+ * - If only `vbrief/` exists (legacy-only), throws so the caller surfaces the migrate hint.
+ * - If neither exists (empty/new project), falls back to `<projectRoot>/xbrief/` canonical path.
+ */
+export function resolveLayoutRootOrCanonical(projectRoot) {
+    try {
+        return resolveLifecycleRoot(projectRoot);
+    }
+    catch (err) {
+        if (isDirectory(join(projectRoot, LEGACY_ARTIFACT_DIR)) &&
+            !isDirectory(join(projectRoot, MIGRATED_ARTIFACT_DIR))) {
+            throw err; // Legacy-only project: operator must run deft migrate:xbrief.
+        }
+        return join(projectRoot, MIGRATED_ARTIFACT_DIR); // New/empty project; use canonical path.
+    }
+}
 /** True when `name` ends with any recognized artifact suffix (.xbrief.json or .vbrief.json). */
 export function hasArtifactSuffix(name) {
     return ARTIFACT_SUFFIXES.some((suffix) => name.endsWith(suffix));
@@ -37,8 +59,10 @@ export function stripArtifactSuffix(name) {
     return name;
 }
 /**
- * True when a POSIX-style path is a lifecycle artifact under either layout
- * root (`xbrief/` or `vbrief/`) carrying either artifact suffix.
+ * True when a POSIX-style path is a lifecycle artifact path carrying a
+ * recognized lifecycle directory prefix (`xbrief/` or `vbrief/`) and a
+ * recognized artifact suffix. The `vbrief/` prefix and `.vbrief.json` suffix
+ * remain recognized for path-validation purposes during and after migration.
  */
 export function isLifecycleArtifactPath(posix) {
     const underLifecycleDir = LIFECYCLE_DIR_NAMES.some((dir) => posix.startsWith(`${dir}/`));
@@ -64,12 +88,16 @@ function containsMigratedArtifact(root) {
     return false;
 }
 /**
- * Resolve the active lifecycle layout for `projectRoot` (#2109 part 1).
+ * Resolve the active lifecycle layout for `projectRoot` (#2109 part 1 / #2112).
+ *
+ * Requires the migrated `xbrief/` layout: the `xbrief/` directory must exist
+ * AND contain at least one `.xbrief.json` artifact. If no such layout is found,
+ * throws with a clear error directing the operator to run `deft migrate:xbrief`.
  *
- * Prefers the migrated `xbrief/` layout only when BOTH the `xbrief/` directory
- * exists AND it contains at least one `.xbrief.json` artifact; otherwise falls
- * back to the legacy `vbrief/` layout. With only `vbrief/` present (today's
- * repo) the result is the legacy layout, so existing behavior is unchanged.
+ * The legacy `vbrief/` read-path fallback was removed in #2112 (0.73.0 MINOR).
+ * Projects that have not migrated must run `deft migrate:xbrief` first.
+ *
+ * @throws {Error} When no `xbrief/` layout with `.xbrief.json` artifacts exists.
  */
 export function resolveLifecycleLayout(projectRoot) {
     const migratedRoot = join(projectRoot, MIGRATED_ARTIFACT_DIR);
@@ -82,28 +110,26 @@ export function resolveLifecycleLayout(projectRoot) {
             migrated: true,
         };
     }
-    return {
-        artifactDir: LEGACY_ARTIFACT_DIR,
-        artifactSuffix: LEGACY_ARTIFACT_SUFFIX,
-        infoRootKey: LEGACY_INFO_ROOT_KEY,
-        root: join(projectRoot, LEGACY_ARTIFACT_DIR),
-        migrated: false,
-    };
+    throw new Error(`No xbrief/ layout found at ${projectRoot}. ` +
+        "Run `deft migrate:xbrief` to convert your project from the legacy vbrief/ layout.");
 }
 /** Convenience accessor for the absolute resolved lifecycle root directory. */
 export function resolveLifecycleRoot(projectRoot) {
     return resolveLifecycleLayout(projectRoot).root;
 }
 /**
- * Absolute path to a lifecycle folder under the resolved layout root
- * (e.g. `<root>/<xbrief|vbrief>/active`). Layout-aware (#2109 part 2a).
+ * Absolute path to a lifecycle folder under the resolved `xbrief/` layout root
+ * (e.g. `<root>/xbrief/active`). Layout-aware (#2109 part 2a / #2112).
  */
 export function resolveLifecycleFolder(projectRoot, folder) {
-    return join(resolveLifecycleRoot(projectRoot), folder);
+    // Throws on a pure vbrief/-only tree (#2112). Falls back to xbrief/ when neither layout exists.
+    return join(resolveLayoutRootOrCanonical(projectRoot), folder);
 }
 /** Absolute path to the layout-aware `.eval/` directory for version-eval results (#1703). */
 export function resolveEvalDir(projectRoot) {
-    return join(resolveLifecycleRoot(projectRoot), ".eval");
+    // Throws on a pure vbrief/-only tree (#2112). Falls back to xbrief/ when neither layout exists.
+    const layoutRoot = resolveLayoutRootOrCanonical(projectRoot);
+    return join(layoutRoot, ".eval");
 }
 /** Absolute path under `.eval/` for version-eval artefacts (not triage working-set). */
 export function resolveEvalPath(projectRoot, ...segments) {
@@ -111,7 +137,9 @@ export function resolveEvalPath(projectRoot, ...segments) {
 }
 /** Absolute path to the resolved lifecycle `.audit` directory (#2109 part 2a). */
 export function resolveAuditDir(projectRoot) {
-    return join(resolveLifecycleRoot(projectRoot), ".audit");
+    // Throws on a pure vbrief/-only tree (#2112). Falls back to xbrief/ when neither layout exists.
+    const layoutRoot = resolveLayoutRootOrCanonical(projectRoot);
+    return join(layoutRoot, ".audit");
 }
 /** Absolute path to a file or subpath under the resolved `.audit` directory. */
 export function resolveAuditPath(projectRoot, ...segments) {
@@ -122,27 +150,56 @@ export function resolveAuditPath(projectRoot, ...segments) {
  * (`PROJECT-DEFINITION.xbrief.json` when migrated, else `.vbrief.json`).
  */
 export function projectDefinitionFilename(projectRoot) {
-    return `PROJECT-DEFINITION${resolveLifecycleLayout(projectRoot).artifactSuffix}`;
+    // Throws on a pure vbrief/-only tree (#2112). Falls back to xbrief/ when neither layout exists.
+    try {
+        return `PROJECT-DEFINITION${resolveLifecycleLayout(projectRoot).artifactSuffix}`;
+    }
+    catch (err) {
+        if (isDirectory(join(projectRoot, LEGACY_ARTIFACT_DIR)) &&
+            !isDirectory(join(projectRoot, MIGRATED_ARTIFACT_DIR))) {
+            throw err;
+        }
+        return `PROJECT-DEFINITION${MIGRATED_ARTIFACT_SUFFIX}`;
+    }
 }
 /** Absolute path to the resolved PROJECT-DEFINITION artifact (#2109 part 2a). */
 export function resolveProjectDefinitionPath(projectRoot) {
-    const layout = resolveLifecycleLayout(projectRoot);
-    return join(layout.root, `PROJECT-DEFINITION${layout.artifactSuffix}`);
+    // Throws on a pure vbrief/-only tree (#2112). Falls back to xbrief/ when neither layout exists.
+    try {
+        const layout = resolveLifecycleLayout(projectRoot);
+        return join(layout.root, `PROJECT-DEFINITION${layout.artifactSuffix}`);
+    }
+    catch (err) {
+        if (isDirectory(join(projectRoot, LEGACY_ARTIFACT_DIR)) &&
+            !isDirectory(join(projectRoot, MIGRATED_ARTIFACT_DIR))) {
+            throw err; // Legacy-only project: operator must run deft migrate:xbrief.
+        }
+        return join(projectRoot, MIGRATED_ARTIFACT_DIR, `PROJECT-DEFINITION${MIGRATED_ARTIFACT_SUFFIX}`);
+    }
 }
 /**
  * POSIX-style display path to the resolved PROJECT-DEFINITION artifact relative
- * to the project root (e.g. `vbrief/PROJECT-DEFINITION.vbrief.json`).
+ * to the project root (e.g. `xbrief/PROJECT-DEFINITION.xbrief.json`).
  */
 export function projectDefinitionRelPath(projectRoot) {
-    const layout = resolveLifecycleLayout(projectRoot);
-    return `${layout.artifactDir}/PROJECT-DEFINITION${layout.artifactSuffix}`;
+    // Throws on a pure vbrief/-only tree (#2112). Falls back to xbrief/ when neither layout exists.
+    try {
+        const layout = resolveLifecycleLayout(projectRoot);
+        return `${layout.artifactDir}/PROJECT-DEFINITION${layout.artifactSuffix}`;
+    }
+    catch (err) {
+        if (isDirectory(join(projectRoot, LEGACY_ARTIFACT_DIR)) &&
+            !isDirectory(join(projectRoot, MIGRATED_ARTIFACT_DIR))) {
+            throw err;
+        }
+        return `${MIGRATED_ARTIFACT_DIR}/PROJECT-DEFINITION${MIGRATED_ARTIFACT_SUFFIX}`;
+    }
 }
 /**
- * Absolute path to the resolved specification artifact (#2132).
+ * Absolute path to the resolved specification artifact (#2132 / #2112).
  *
- * Prefers `xbrief/specification.xbrief.json` on a migrated tree; falls back to
- * `vbrief/specification.vbrief.json` on an unmigrated tree. Consistent with the
- * layout resolver used by the #2109 Part-2a call-site sweep.
+ * Returns `xbrief/specification.xbrief.json`; throws when no migrated xbrief/
+ * layout is present (see `resolveLifecycleLayout`).
  */
 export function resolveSpecArtifactPath(projectRoot) {
     const layout = resolveLifecycleLayout(projectRoot);
@@ -150,7 +207,7 @@ export function resolveSpecArtifactPath(projectRoot) {
 }
 /**
  * POSIX-style display path to the resolved specification artifact relative to
- * the project root (e.g. `xbrief/specification.xbrief.json`).
+ * the project root (`xbrief/specification.xbrief.json`).
  */
 export function specArtifactRelPath(projectRoot) {
     const layout = resolveLifecycleLayout(projectRoot);

package/dist/lifecycle/lifecycle-hygiene.d.ts

@@ -11,7 +11,7 @@ export declare const TERMINAL_STATUSES: Set<string>;
 /** Child reference type that marks an epic as decomposed. */
 export declare const CHILD_REF_TYPE = "x-xbrief/plan";
 /** Durable tech-debt acceptance ledger relative path segments. */
-export declare const TECH_DEBT_LEDGER_RELPATH: readonly ["vbrief", ".audit", "epic-tech-debt-accepted.jsonl"];
+export declare const TECH_DEBT_LEDGER_RELPATH: readonly ["xbrief", ".audit", "epic-tech-debt-accepted.jsonl"];
 /** Session-start nudge tiers (rate-of-harm ranking). */
 export declare const TIER_STRANDED = 1;
 export declare const TIER_STALE_EPIC = 2;

package/dist/lifecycle/lifecycle-hygiene.js

@@ -26,7 +26,7 @@ export const TERMINAL_STATUSES = new Set(["completed", "cancelled", "failed"]);
 export const CHILD_REF_TYPE = "x-xbrief/plan";
 /** Durable tech-debt acceptance ledger relative path segments. */
 export const TECH_DEBT_LEDGER_RELPATH = [
-    "vbrief",
+    "xbrief",
     ".audit",
     "epic-tech-debt-accepted.jsonl",
 ];

package/dist/migrate-preflight/index.js

@@ -14,7 +14,7 @@ function resolveContentRoot(frameworkRoot) {
     return frameworkRoot;
 }
 export function checkLayout(deftRoot, projectRoot) {
-    const schemasDir = join(resolveContentRoot(deftRoot), "vbrief", "schemas");
+    const schemasDir = join(resolveContentRoot(deftRoot), "xbrief", "schemas");
     if (!existsSync(schemasDir) || !statSync(schemasDir).isDirectory()) {
         return {
             name: "layout",
@@ -22,18 +22,18 @@ export function checkLayout(deftRoot, projectRoot) {
             message: `Framework schemas dir missing at ${schemasDir}. Refresh the deft checkout (see deft/QUICK-START.md).`,
         };
     }
-    const projectVbrief = join(projectRoot, "vbrief");
-    if (!existsSync(projectVbrief)) {
+    const projectXbrief = join(projectRoot, "xbrief");
+    if (!existsSync(projectXbrief)) {
         return {
             name: "layout",
             status: "WARN",
-            message: `Project vbrief/ not present at ${projectVbrief} -- expected for greenfield projects.`,
+            message: `Project xbrief/ not present at ${projectXbrief} -- expected for greenfield projects.`,
         };
     }
     return {
         name: "layout",
         status: "PASS",
-        message: `Framework schemas present; project vbrief/ at ${projectVbrief}.`,
+        message: `Framework schemas present; project xbrief/ at ${projectXbrief}.`,
     };
 }
 export function checkGitClean(projectRoot) {
@@ -91,7 +91,7 @@ export function checkDocumentModel(projectRoot) {
                 return {
                     name: "document-model",
                     status: "FAIL",
-                    message: `Generated SPECIFICATION.md detected (source: vbrief/specification.vbrief.json); repair missing lifecycle folder(s) instead of migrating: ${missing.join(", ")}.`,
+                    message: `Generated SPECIFICATION.md detected (source: xbrief/specification.xbrief.json); repair missing lifecycle folder(s) instead of migrating: ${missing.join(", ")}.`,
                 };
             }
         }
@@ -99,18 +99,18 @@ export function checkDocumentModel(projectRoot) {
             return {
                 name: "document-model",
                 status: "PASS",
-                message: "Current generated SPECIFICATION.md detected (source: vbrief/specification.vbrief.json); pre-v0.20 migration is not needed.",
+                message: "Current generated SPECIFICATION.md detected (source: xbrief/specification.xbrief.json); pre-v0.20 migration is not needed.",
             };
         }
     }
-    const vbriefRoot = join(projectRoot, "vbrief");
-    if (existsSync(vbriefRoot)) {
+    const xbriefRoot = join(projectRoot, "xbrief");
+    if (existsSync(xbriefRoot)) {
         const missing = missingLifecycleFolders(projectRoot);
         if (missing.length > 0) {
             return {
                 name: "document-model",
                 status: "FAIL",
-                message: `Partial vBRIEF layout detected; missing lifecycle folder(s): ${missing.join(", ")}. Create the folders or follow ${frozenPreCutoverMigrationGuidance()}`,
+                message: `Partial xBRIEF layout detected; missing lifecycle folder(s): ${missing.join(", ")}. Create the folders or follow ${frozenPreCutoverMigrationGuidance()}`,
             };
         }
     }

package/dist/policy/resolve.d.ts

@@ -1,5 +1,5 @@
-/** Filesystem-relative location of the project-definition vBRIEF (display/back-compat). */
-export declare const PROJECT_DEFINITION_REL_PATH = "vbrief/PROJECT-DEFINITION.vbrief.json";
+/** Filesystem-relative location of the project-definition xBRIEF (display/back-compat). */
+export declare const PROJECT_DEFINITION_REL_PATH = "xbrief/PROJECT-DEFINITION.xbrief.json";
 /** Environment variable emergency bypass for branch protection (#747). */
 export declare const ENV_BYPASS = "DEFT_ALLOW_DEFAULT_BRANCH_COMMIT";
 /** Legacy narrative key replaced by the typed flag (#746). */

package/dist/policy/resolve.js

@@ -3,8 +3,8 @@ import { join, resolve as pathResolve } from "node:path";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.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";
+/** Filesystem-relative location of the project-definition xBRIEF (display/back-compat). */
+export const PROJECT_DEFINITION_REL_PATH = "xbrief/PROJECT-DEFINITION.xbrief.json";
 /** Environment variable emergency bypass for branch protection (#747). */
 export const ENV_BYPASS = "DEFT_ALLOW_DEFAULT_BRANCH_COMMIT";
 /** Legacy narrative key replaced by the typed flag (#746). */
@@ -18,7 +18,15 @@ const TRUTHY = new Set(["1", "true", "yes", "on"]);
  * else PROJECT-DEFINITION.vbrief.json (unchanged on today's tree).
  */
 export function projectDefinitionPath(projectRoot) {
-    return resolveProjectDefinitionPath(pathResolve(projectRoot));
+    const root = pathResolve(projectRoot);
+    try {
+        return resolveProjectDefinitionPath(root);
+    }
+    catch {
+        // No xbrief/ layout; return canonical xbrief path so callers get a predictable
+        // "not found" result rather than a thrown error.
+        return join(root, PROJECT_DEFINITION_REL_PATH);
+    }
 }
 function envBypassActive() {
     const raw = process.env[ENV_BYPASS] ?? "";

package/dist/policy/wip.d.ts

@@ -10,6 +10,6 @@ export interface WipCapResult {
 }
 /** Resolve plan.policy.wipCap from PROJECT-DEFINITION (#1124). */
 export declare function resolveWipCap(projectRoot: string): WipCapResult;
-/** Count *.vbrief.json files in vbrief/pending/ + vbrief/active/ (#1124). */
+/** Count *.xbrief.json files in xbrief/pending/ + xbrief/active/ (#1124). */
 export declare function countVbriefWip(projectRoot: string): number;
 //# sourceMappingURL=wip.d.ts.map

package/dist/policy/wip.js

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
+import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, resolveLifecycleRoot, } from "../layout/resolve.js";
 import { readPlanPolicy } from "./plan-extensions.js";
 import { loadProjectDefinition } from "./resolve.js";
 /** Framework default WIP cap (#2319; raised from 10 per #1124 / umbrella #1119). */
@@ -62,10 +62,22 @@ export function resolveWipCap(projectRoot) {
     }
     return { cap: raw, source: "typed", error: null };
 }
-/** Count *.vbrief.json files in vbrief/pending/ + vbrief/active/ (#1124). */
+/** Count *.xbrief.json files in xbrief/pending/ + xbrief/active/ (#1124). */
 export function countVbriefWip(projectRoot) {
     let total = 0;
-    const vbriefRoot = resolveLifecycleRoot(projectRoot);
+    let vbriefRoot;
+    try {
+        vbriefRoot = resolveLifecycleRoot(projectRoot);
+    }
+    catch (err) {
+        // If xbrief/ dir exists (even without artifacts), there is no WIP to count.
+        // If only vbrief/ exists, this is a legacy project that must be migrated -- re-throw.
+        if (!existsSync(join(projectRoot, MIGRATED_ARTIFACT_DIR)) &&
+            existsSync(join(projectRoot, LEGACY_ARTIFACT_DIR))) {
+            throw err; // Legacy-only project: operator must run deft migrate:xbrief.
+        }
+        return 0; // No layout found at all; no WIP files to count.
+    }
     for (const sub of WIP_LIFECYCLE_DIRS) {
         const folder = join(vbriefRoot, sub);
         if (!existsSync(folder)) {

package/dist/preflight-cache/evaluate.js

@@ -23,7 +23,7 @@ import { resolveCandidatesLogPath } from "../triage/cache-path.js";
 // ---------------------------------------------------------------------------
 export const CACHE_DIR_NAME = ".deft-cache";
 export const DEFAULT_SOURCE = "github-issue";
-export const CANDIDATES_RELPATH = join("vbrief", ".triage-cache", "candidates.jsonl");
+export const CANDIDATES_RELPATH = join("xbrief", ".triage-cache", "candidates.jsonl");
 export const DEFAULT_MAX_AGE_HOURS = 24;
 export const ENV_MAX_AGE_HOURS = "DEFT_CACHE_MAX_AGE_HOURS";
 export const ENV_TRIAGE_REPO = "DEFT_TRIAGE_REPO";

package/dist/release/native-steps.js

@@ -3,10 +3,11 @@
  * Replaces python-steps.ts (scripts/ roadmap_render, reconcile_issues, build_dist).
  */
 import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
 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 { LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, 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) {
@@ -20,7 +21,18 @@ export function refreshRoadmapNative(projectRoot) {
     return [true, "ROADMAP.md re-rendered"];
 }
 export function checkVbriefLifecycleSyncNative(projectRoot, repo) {
-    const vbriefDir = resolveLifecycleRoot(projectRoot);
+    let vbriefDir;
+    try {
+        vbriefDir = resolveLifecycleRoot(projectRoot);
+    }
+    catch (_err) {
+        // Re-throw if this is a legacy-only vbrief/ project; fall back to canonical path otherwise.
+        if (existsSync(join(projectRoot, LEGACY_ARTIFACT_DIR)) &&
+            !existsSync(join(projectRoot, MIGRATED_ARTIFACT_DIR))) {
+            return [false, 0, "no xbrief/ layout found; skipping lifecycle sync check"];
+        }
+        vbriefDir = join(projectRoot, MIGRATED_ARTIFACT_DIR);
+    }
     try {
         const issueToVbriefs = scanVbriefDir(vbriefDir);
         const issueStateMap = fetchIssueStates(repo, new Set(issueToVbriefs.keys()), {

package/dist/render/export-spec.js

@@ -26,7 +26,7 @@ export function exportSpec(options = {}) {
     const includeProposed = audience === "internal";
     const authority = resolveSpecAuthority(projectRoot);
     if (!authority) {
-        return [false, "✗ Missing vbrief/PROJECT-DEFINITION.vbrief.json — cannot export spec."];
+        return [false, "✗ Missing xbrief/PROJECT-DEFINITION.xbrief.json — cannot export spec."];
     }
     if (authority.kind === "full-spec" && authority.specPath) {
         const [ok, msg] = validateSpec(authority.specPath);
@@ -36,7 +36,7 @@ export function exportSpec(options = {}) {
     else if (!greenfieldOverviewNonEmpty(authority)) {
         return [
             false,
-            "⚠ PROJECT-DEFINITION.vbrief.json Overview narrative is empty (D3). Populate Overview before export.",
+            "⚠ PROJECT-DEFINITION.xbrief.json Overview narrative is empty (D3). Populate Overview before export.",
         ];
     }
     const narratives = resolveExportNarratives(authority);

package/dist/render/project-render.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
-import { hasArtifactSuffix, resolveLifecycleRoot, stripArtifactSuffix } from "../layout/resolve.js";
+import { hasArtifactSuffix, resolveLayoutRootOrCanonical, stripArtifactSuffix, } from "../layout/resolve.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
 import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
 import { deriveRegistryItemStatus, registryMetadataReferencesFromScope, } from "../vbrief-validate/registry-status.js";
@@ -317,30 +317,61 @@ export function acknowledgeProjectDefinitionStaleness(vbriefDir, options = {}) {
         ];
     });
 }
+const USAGE = "Usage: project-render [--help] [--acknowledge-staleness] [--project-root <dir>]\n";
 /** CLI entry (mirrors ``scripts/project_render.main``). */
 export function main(argv) {
-    const acknowledge = argv[0] === "--acknowledge-staleness";
-    const rest = acknowledge ? argv.slice(1) : argv;
+    // Handle --help / -h before any other parsing so the flag is never treated
+    // as a positional output path and no stray ./--help/ directory is created
+    // (#2236).
+    if (argv.includes("--help") || argv.includes("-h")) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    // Parse all flags in a single positional-independent pass so that
+    // --acknowledge-staleness is recognised at any position (not only argv[0]).
+    let acknowledge = false;
     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];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--acknowledge-staleness") {
+            acknowledge = true;
+        }
+        else 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.startsWith("-")) {
+            // Reject unknown flags rather than consuming them as positional output
+            // paths (would otherwise create stray directories like ./--help/).
+            process.stderr.write(`Unknown flag: ${arg}\n${USAGE}`);
+            return 2;
+        }
         else {
             positional.push(arg);
         }
     }
     if (positional.length > 1) {
-        process.stderr.write("Usage: project-render [--acknowledge-staleness] [--project-root <dir>] [vbrief_dir]\n");
+        process.stderr.write(USAGE);
         return 2;
     }
-    const vbriefDir = positional[0] ?? resolveLifecycleRoot(resolve(projectRoot !== undefined ? projectRoot : "."));
+    let vbriefDir;
+    if (positional[0] !== undefined) {
+        vbriefDir = positional[0];
+    }
+    else {
+        const effectiveRoot = resolve(projectRoot !== undefined ? projectRoot : ".");
+        try {
+            vbriefDir = resolveLayoutRootOrCanonical(effectiveRoot);
+        }
+        catch {
+            process.stderr.write(`No xbrief/ layout found at ${effectiveRoot}. Run \`deft migrate:xbrief\` to convert your project from the legacy vbrief/ layout.\n`);
+            return 2;
+        }
+    }
     const [ok, message] = acknowledge
         ? acknowledgeProjectDefinitionStaleness(vbriefDir)
         : renderProjectDefinition(vbriefDir);

package/dist/scope/decompose.js

@@ -9,7 +9,7 @@
 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 { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, 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";
@@ -400,7 +400,17 @@ export function storyQualityIssues(opts) {
 // Path helpers
 // ---------------------------------------------------------------------------
 function vbriefDir(projectRoot) {
-    return resolveLifecycleRoot(projectRoot);
+    try {
+        return resolveLifecycleRoot(projectRoot);
+    }
+    catch (err) {
+        // Re-throw if only vbrief/ exists (legacy-only); fall back to canonical xbrief/ path otherwise.
+        if (existsSync(join(projectRoot, LEGACY_ARTIFACT_DIR)) &&
+            !existsSync(join(projectRoot, MIGRATED_ARTIFACT_DIR))) {
+            throw err;
+        }
+        return join(projectRoot, MIGRATED_ARTIFACT_DIR);
+    }
 }
 function relToVbrief(vbriefDirPath, path) {
     const resolvedPath = resolve(path);

package/dist/session/resume-conditions.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { hasArtifactSuffix } from "../layout/resolve.js";
+import { hasArtifactSuffix, MIGRATED_ARTIFACT_DIR } from "../layout/resolve.js";
 export const RESUME_ELIGIBLE_DECISION = "resume-eligible";
 export const EVALUATOR_ACTOR = "agent:resume-evaluator";
 export const CACHE_DIR_NAME = ".deft-cache";
@@ -258,7 +258,7 @@ export function evaluate(expr, ctx) {
     throw new ResumeGrammarError(`unknown composition op ${JSON.stringify(expr.op)}`);
 }
 function countPending(projectRoot) {
-    const folder = join(resolve(projectRoot), "vbrief", PENDING_LIFECYCLE_DIR);
+    const folder = join(resolve(projectRoot), MIGRATED_ARTIFACT_DIR, PENDING_LIFECYCLE_DIR);
     try {
         if (!statSync(folder).isDirectory())
             return 0;

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

@@ -3,7 +3,7 @@ export declare const RITUAL_STATE_SCHEMA_VERSION = 1;
 export declare const SENTINEL_RELPATH: readonly [".deft", "last-session.json"];
 export declare const RITUAL_STATE_RELPATH: readonly [".deft", "ritual-state.json"];
 export declare const MIN_RESUME_AGE_MS: number;
-export declare const ACTIVE_VBRIEF_PREFIX = "vbrief/active/";
+export declare const ACTIVE_VBRIEF_PREFIX: string;
 export interface Sentinel {
     readonly schemaVersion: number;
     readonly deftVersion: string;

package/dist/session/ritual-sentinel.js

@@ -1,6 +1,6 @@
 import { closeSync, existsSync, fdatasyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, writeSync, } from "node:fs";
 import { join, relative, resolve } from "node:path";
-import { hasArtifactSuffix } from "../layout/resolve.js";
+import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, } from "../layout/resolve.js";
 import { stableJson } from "./json.js";
 import { parseTimestamp, timestampIso } from "./time.js";
 export const SCHEMA_VERSION = 1;
@@ -8,7 +8,7 @@ export const RITUAL_STATE_SCHEMA_VERSION = 1;
 export const SENTINEL_RELPATH = [".deft", "last-session.json"];
 export const RITUAL_STATE_RELPATH = [".deft", "ritual-state.json"];
 export const MIN_RESUME_AGE_MS = 2 * 60 * 60 * 1000;
-export const ACTIVE_VBRIEF_PREFIX = "vbrief/active/";
+export const ACTIVE_VBRIEF_PREFIX = `${MIGRATED_ARTIFACT_DIR}/active/`;
 export function ritualStatePath(projectRoot) {
     return join(resolve(projectRoot), ...RITUAL_STATE_RELPATH);
 }
@@ -249,7 +249,9 @@ export function writeSentinel(projectRoot, input) {
         schemaVersion: SCHEMA_VERSION,
         deftVersion: input.deftVersion,
         timestamp: timestampIso(instant),
-        lastActiveVbrief: input.lastActiveVbrief.replace(/\\/g, "/"),
+        lastActiveVbrief: input.lastActiveVbrief
+            .replace(/\\/g, "/")
+            .replace(`${LEGACY_ARTIFACT_DIR}/active/`, `${MIGRATED_ARTIFACT_DIR}/active/`),
         lastBranch: input.lastBranch,
     };
     atomicWriteJson(sentinelFile, payload, ".last-session.");
@@ -290,7 +292,7 @@ export function computeResumeSignal(sentinel, now, projectRoot) {
         `${elapsedLabel} ago. Resume? Run \`task vbrief:show ${lastActive}\`.`);
 }
 export function detectLatestActiveVbrief(projectRoot) {
-    const activeDir = join(resolve(projectRoot), "vbrief", "active");
+    const activeDir = join(resolve(projectRoot), MIGRATED_ARTIFACT_DIR, "active");
     try {
         if (!existsSync(activeDir)) {
             return null;

package/dist/slice/constants.d.ts

@@ -14,5 +14,5 @@ export declare const CHILD_ALLOWED_FIELDS: Set<"n" | "url" | "wave" | "role">;
 export declare const UUID_RE: RegExp;
 export declare const ISO8601_RE: RegExp;
 export declare const WAVE_FLAG_RE: RegExp;
-export declare const PROJECT_ROOT_SENTINELS: readonly ["vbrief", ".git"];
+export declare const PROJECT_ROOT_SENTINELS: readonly ["xbrief", "vbrief", ".git"];
 //# sourceMappingURL=constants.d.ts.map

package/dist/slice/constants.js

@@ -26,5 +26,5 @@ export const CHILD_ALLOWED_FIELDS = new Set(CHILD_REQUIRED_FIELDS);
 export const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
 export const ISO8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
 export const WAVE_FLAG_RE = /^--wave-(\d+)(?:=(.*))?$/;
-export const PROJECT_ROOT_SENTINELS = ["vbrief", ".git"];
+export const PROJECT_ROOT_SENTINELS = ["xbrief", "vbrief", ".git"];
 //# sourceMappingURL=constants.js.map

package/dist/slice/project-context.js

@@ -77,7 +77,7 @@ export function resolveRootAndRepo(cliProjectRoot, cliRepo, requireRepo) {
 export function formatMissingRootError() {
     return ("error: cannot determine project root. Pass --project-root PATH, " +
         "set $DEFT_PROJECT_ROOT, or run from inside a directory tree that " +
-        "contains vbrief/ or .git/ (#535).");
+        "contains xbrief/ or .git/ (#535).");
 }
 export function formatMissingRepoError() {
     return ("error: cannot determine repo slug. Pass --repo OWNER/NAME, " +