@deftai/directive-core 0.72.0 → 0.73.1

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/disclosure.d.ts

@@ -1,4 +1,5 @@
 import type { PolicyResult } from "./resolve.js";
+export { policyColonInvocation, policySetInvocation } from "./policy-invocation.js";
 /** One-liner disclosure phrasing for AGENTS.md / setup interview echo. */
 export declare function disclosureLine(result: PolicyResult): string;
 //# sourceMappingURL=disclosure.d.ts.map

package/dist/policy/disclosure.js

@@ -1,4 +1,5 @@
 import { ENV_BYPASS } from "./resolve.js";
+export { policyColonInvocation, policySetInvocation } from "./policy-invocation.js";
 /** One-liner disclosure phrasing for AGENTS.md / setup interview echo. */
 export function disclosureLine(result) {
     if (result.allowDirectCommits) {

package/dist/policy/index.d.ts

@@ -4,6 +4,7 @@ export * from "./capacity.js";
 export * from "./decisions.js";
 export * from "./disclosure.js";
 export * from "./plan-extensions.js";
+export * from "./policy-invocation.js";
 export * from "./resolve.js";
 export * from "./value-feedback.js";
 export * from "./wip.js";

package/dist/policy/index.js

@@ -8,6 +8,7 @@ export * from "./capacity.js";
 export * from "./decisions.js";
 export * from "./disclosure.js";
 export * from "./plan-extensions.js";
+export * from "./policy-invocation.js";
 export * from "./resolve.js";
 export * from "./value-feedback.js";
 export * from "./wip.js";

package/dist/policy/policy-invocation.d.ts

@@ -0,0 +1,5 @@
+/** User-facing colon-form policy verb for consumer `deft` disclosures (#2367). */
+export declare function policyColonInvocation(subcommand: string, trailing?: string): string;
+/** User-facing `deft policy set <cmd>` form for policy-set disclosures (#2367). */
+export declare function policySetInvocation(subcommand: string, trailing?: string): string;
+//# sourceMappingURL=policy-invocation.d.ts.map

package/dist/policy/policy-invocation.js

@@ -0,0 +1,9 @@
+/** User-facing colon-form policy verb for consumer `deft` disclosures (#2367). */
+export function policyColonInvocation(subcommand, trailing = "") {
+    return `deft policy:${subcommand}${trailing}`;
+}
+/** User-facing `deft policy set <cmd>` form for policy-set disclosures (#2367). */
+export function policySetInvocation(subcommand, trailing = "") {
+    return `deft policy set ${subcommand}${trailing}`;
+}
+//# sourceMappingURL=policy-invocation.js.map

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,9 @@ 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";
+import { policyColonInvocation } from "./policy-invocation.js";
+/** 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 +19,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] ?? "";
@@ -146,8 +155,9 @@ export function resolvePolicy(projectRoot) {
         const warn = `DEPRECATED: PROJECT-DEFINITION uses the legacy narrative key ` +
             `'${LEGACY_NARRATIVE_KEY}' (${pythonRepr(raw)}). Migrate to typed ` +
             `plan.policy.allowDirectCommitsToMaster (#746). Run ` +
-            `\`task policy:enforce-branches\` or \`task policy:allow-direct-commits ` +
-            `-- --confirm\` to set the typed flag explicitly.`;
+            `\`${policyColonInvocation("enforce-branches")}\` or ` +
+            `\`${policyColonInvocation("allow-direct-commits", " -- --confirm")}\` ` +
+            `to set the typed flag explicitly.`;
         return {
             allowDirectCommits: allow,
             source: "legacy-narrative",

package/dist/policy/value-feedback.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
+import { policyColonInvocation } from "./policy-invocation.js";
 import { appendAuditLog, loadProjectDefinition, projectDefinitionPath } from "./resolve.js";
 import { isTrustedOrgAutoEnable } from "./value-feedback-autoenable.js";
 /** Canonical registered policy field name (matches other FIELD_* dotted paths). */
@@ -21,7 +22,9 @@ export const VALUE_FEEDBACK_CAPABILITY_COST_DISCLOSURE = "\u26a0 Capability-cost
     "  \u2022 A budgeted session one-liner may appear when concrete attributed value exists.\n" +
     "  \u2022 Upstream gap-escalation prompts stay OFF unless you explicitly enable " +
     "`upstreamPrompt` (GitHub attention + token cost).\n" +
-    "  \u2022 Inspect current state: `task policy:show --field=valueFeedback`.\n" +
+    "  \u2022 Inspect current state: `" +
+    policyColonInvocation("show", " --field=valueFeedback") +
+    "`.\n" +
     "  \u2022 Reversible: set `enabled: false` under the typed policy block in PROJECT-DEFINITION.\n" +
     "  \u2022 Changes are recorded to meta/policy-changes.log for auditability.";
 function defaultResolved(source, error = null) {
@@ -202,7 +205,7 @@ export function enableValueFeedback(projectRoot, options) {
         return {
             exitCode: 1,
             stdout: `${VALUE_FEEDBACK_CAPABILITY_COST_DISCLOSURE}\n\n` +
-                "Re-run with --confirm to apply: task policy:enable-value-feedback -- --confirm\n",
+                `Re-run with --confirm to apply: ${policyColonInvocation("enable-value-feedback", " -- --confirm")}\n`,
             changed: false,
         };
     }
@@ -265,7 +268,7 @@ export function enableValueFeedback(projectRoot, options) {
             if (changedFlag) {
                 atomicWriteProjectDefinition(path, data);
             }
-            const actor = options.actor ?? "task policy:enable-value-feedback";
+            const actor = options.actor ?? policyColonInvocation("enable-value-feedback");
             const note = options.note ?? "";
             const parts = [
                 `actor=${actor}`,

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);