@deftai/directive-core 0.65.0 → 0.66.0

package/dist/vbrief-validate/schema.js

@@ -1,5 +1,5 @@
 import { pyStrRepr, pythonTypeName } from "../triage/scope/python-repr.js";
-import { PROJECT_DEF_EXPECTED_NARRATIVES, VALID_STATUSES, VALID_VBRIEF_VERSIONS, } from "./constants.js";
+import { PROJECT_DEF_EXPECTED_NARRATIVES, VALID_INFO_ROOT_KEYS, VALID_ITEM_STATUSES, VALID_PLAN_ITEM_TYPES, VALID_PLAN_STATUSES, VALID_VBRIEF_VERSIONS, } from "./constants.js";
 function validateNarratives(narratives, path, errors) {
     if (typeof narratives !== "object" || narratives === null || Array.isArray(narratives)) {
         errors.push(`${path} must be an object`);
@@ -11,6 +11,30 @@ function validateNarratives(narratives, path, errors) {
         }
     }
 }
+function validatePlanRefs(planRefs, path, errors) {
+    if (!Array.isArray(planRefs)) {
+        errors.push(`${path}.planRefs must be an array`);
+        return;
+    }
+    for (let i = 0; i < planRefs.length; i += 1) {
+        if (typeof planRefs[i] !== "string") {
+            errors.push(`${path}.planRefs[${i}] must be a string, got ${pythonTypeName(planRefs[i])}`);
+        }
+    }
+}
+function resolveInfoBlock(data) {
+    for (const key of VALID_INFO_ROOT_KEYS) {
+        if (!(key in data)) {
+            continue;
+        }
+        const info = data[key];
+        if (typeof info !== "object" || info === null || Array.isArray(info)) {
+            return null;
+        }
+        return { key: key, info: info };
+    }
+    return null;
+}
 function validatePlanItem(item, path, errors) {
     const itemId = typeof item.id === "string" ? item.id : "<no-id>";
     const itemPath = `${path}[${itemId}]`;
@@ -20,9 +44,18 @@ function validatePlanItem(item, path, errors) {
     if (!("status" in item)) {
         errors.push(`${itemPath} missing 'status'`);
     }
-    else if (!VALID_STATUSES.has(String(item.status))) {
+    else if (!VALID_ITEM_STATUSES.has(String(item.status))) {
         errors.push(`${itemPath} invalid status: ${pyStrRepr(String(item.status))}`);
     }
+    if ("type" in item && !VALID_PLAN_ITEM_TYPES.has(String(item.type))) {
+        errors.push(`${itemPath} invalid type: ${pyStrRepr(String(item.type))}`);
+    }
+    if ("summary" in item && typeof item.summary !== "string") {
+        errors.push(`${itemPath}.summary must be a string, got ${pythonTypeName(item.summary)}`);
+    }
+    if ("planRefs" in item) {
+        validatePlanRefs(item.planRefs, itemPath, errors);
+    }
     if ("narrative" in item) {
         validateNarratives(item.narrative, `${itemPath}.narrative`, errors);
     }
@@ -57,25 +90,35 @@ function validatePlanItem(item, path, errors) {
         }
     }
 }
-/** Validate vBRIEF structural requirements (v0.6). */
+/** Validate vBRIEF/xBRIEF structural requirements (v0.6 + v0.8 additive). */
 export function validateVbriefSchema(data, filepath) {
     const errors = [];
-    if (!("vBRIEFInfo" in data)) {
-        errors.push(`${filepath}: missing required top-level key 'vBRIEFInfo'`);
+    const resolved = resolveInfoBlock(data);
+    if (resolved === null) {
+        let infoShapeError = false;
+        for (const key of VALID_INFO_ROOT_KEYS) {
+            if (!(key in data)) {
+                continue;
+            }
+            const info = data[key];
+            if (info === null || Array.isArray(info) || typeof info !== "object") {
+                errors.push(`${filepath}: '${key}' must be an object`);
+                infoShapeError = true;
+                break;
+            }
+        }
+        if (!infoShapeError) {
+            errors.push(`${filepath}: missing required top-level key 'vBRIEFInfo' or 'xBRIEFInfo'`);
+        }
     }
     else {
-        const info = data.vBRIEFInfo;
-        if (typeof info !== "object" || info === null || Array.isArray(info)) {
-            errors.push(`${filepath}: 'vBRIEFInfo' must be an object`);
-        }
-        else {
-            const version = info.version;
-            if (!VALID_VBRIEF_VERSIONS.has(String(version))) {
-                errors.push(`${filepath}: 'vBRIEFInfo.version' must be '0.6' ` +
-                    `(canonical v0.6 schema, #533), got ` +
-                    `${pyStrRepr(String(version))}. Run \`task migrate:vbrief\` to ` +
-                    `upgrade pre-existing v0.5 vBRIEFs in-place.`);
-            }
+        const version = resolved.info.version;
+        if (!VALID_VBRIEF_VERSIONS.has(String(version))) {
+            errors.push(`${filepath}: '${resolved.key}.version' must be one of ` +
+                `${[...VALID_VBRIEF_VERSIONS].map((v) => `'${v}'`).join(", ")} ` +
+                `(canonical v0.6/v0.8 schema, #2107), got ` +
+                `${pyStrRepr(String(version))}. Run \`task migrate:vbrief\` to ` +
+                `upgrade pre-existing v0.5 vBRIEFs in-place.`);
         }
     }
     if (!("plan" in data)) {
@@ -96,8 +139,8 @@ export function validateVbriefSchema(data, filepath) {
             if ("title" in planObj && (typeof planObj.title !== "string" || !planObj.title)) {
                 errors.push(`${filepath}: 'plan.title' must be a non-empty string`);
             }
-            if ("status" in planObj && !VALID_STATUSES.has(String(planObj.status))) {
-                const sorted = [...VALID_STATUSES]
+            if ("status" in planObj && !VALID_PLAN_STATUSES.has(String(planObj.status))) {
+                const sorted = [...VALID_PLAN_STATUSES]
                     .sort()
                     .map((s) => `'${s}'`)
                     .join(", ");

package/dist/vbrief-validate/validate-all.js

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
+import { hasArtifactSuffix, MIGRATED_ARTIFACT_DIR } from "../layout/resolve.js";
 import { LIFECYCLE_FOLDERS } from "./constants.js";
 import { validateNoRootDecompositionDrafts } from "./decomposition.js";
 import { validateEpicStoryLinks } from "./epic-links.js";
@@ -36,7 +37,7 @@ export function discoverVbriefs(vbriefDir) {
             continue;
         }
         const names = readdirSync(folderPath)
-            .filter((name) => name.endsWith(".vbrief.json"))
+            .filter((name) => hasArtifactSuffix(name))
             .sort();
         for (const name of names) {
             files.push({
@@ -89,8 +90,15 @@ export function validateAll(vbriefDir, options = {}) {
         warnings.push(...validateOriginProvenance(display, data, vbriefDir, strictOriginTypes));
     }
     const normalizedDir = normalizeVbriefDir(vbriefDir);
-    const projectDefDisplay = `${normalizedDir}/PROJECT-DEFINITION.vbrief.json`;
-    const projectDefAbsolute = join(vbriefDir, "PROJECT-DEFINITION.vbrief.json");
+    // Layout-aware (#2109 part 1): key the project-definition suffix to the
+    // resolved lifecycle directory's identity (its basename) rather than probing
+    // the filesystem, so a stray xbrief-named file in a legacy tree cannot flip
+    // selection -- this stays consistent with resolveLifecycleLayout's output.
+    const projectDefName = basename(normalizedDir) === MIGRATED_ARTIFACT_DIR
+        ? "PROJECT-DEFINITION.xbrief.json"
+        : "PROJECT-DEFINITION.vbrief.json";
+    const projectDefDisplay = `${normalizedDir}/${projectDefName}`;
+    const projectDefAbsolute = join(vbriefDir, projectDefName);
     if (existsSync(projectDefAbsolute)) {
         const { data, error } = loadVbrief(projectDefAbsolute);
         if (error !== null) {

package/dist/verify-source/code-structure-validate.js

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { hasArtifactSuffix, projectDefinitionRelPath, resolveLifecycleRoot, resolveProjectDefinitionPath, } from "../layout/resolve.js";
 export const CODE_STRUCTURE_VERSION = "0.1";
 export const DIRECTIVE_HOME = "x-directive/architecture.codeStructure";
 export const PLAN_HOME = "plan.architecture.codeStructure";
@@ -495,7 +496,9 @@ export function validateFile(path, options = {}) {
     }
     if (projectRoot !== null && !allowStandalone) {
         const relPath = projectRelative(path, projectRoot);
-        if (relPath !== PROJECT_DEFINITION_PATH && homes.length > 0) {
+        // Layout-aware (#2109 part 2a): compare against the resolved lifecycle's
+        // PROJECT-DEFINITION rel path (vbrief/... on today's tree).
+        if (relPath !== projectDefinitionRelPath(projectRoot) && homes.length > 0) {
             errors.push(finding("CS-HOME", "canonical codeStructure metadata must live in vbrief/PROJECT-DEFINITION.vbrief.json; sibling files must be generated projections", path));
         }
     }
@@ -529,7 +532,8 @@ export function validateFile(path, options = {}) {
 }
 export function discoverCodeStructurePaths(projectRoot) {
     const paths = new Map();
-    const projectDef = join(projectRoot, "vbrief", "PROJECT-DEFINITION.vbrief.json");
+    // Layout-aware (#2109 part 2a): resolve PROJECT-DEFINITION + lifecycle root.
+    const projectDef = resolveProjectDefinitionPath(projectRoot);
     if (existsSync(projectDef)) {
         try {
             const data = loadJsonFile(projectDef);
@@ -541,7 +545,7 @@ export function discoverCodeStructurePaths(projectRoot) {
             paths.set(projectDef.replace(/\\/g, "/"), projectDef);
         }
     }
-    const vbriefRoot = join(projectRoot, "vbrief");
+    const vbriefRoot = resolveLifecycleRoot(projectRoot);
     if (existsSync(vbriefRoot)) {
         const stack = [vbriefRoot];
         while (stack.length > 0) {
@@ -562,7 +566,7 @@ export function discoverCodeStructurePaths(projectRoot) {
                     stack.push(full);
                     continue;
                 }
-                if (!name.endsWith(".vbrief.json") || full === projectDef) {
+                if (!hasArtifactSuffix(name) || full === projectDef) {
                     continue;
                 }
                 try {

package/dist/verify-source/contract-drift.d.ts

@@ -1,11 +1,13 @@
 /**
- * contract-drift.ts — deterministic gate for the public contract layer (#1799).
+ * contract-drift.ts — deterministic gate for the public contract layer (#1799, #2107).
  *
  * Ensures:
  *   1. packages/types/schemas/vbrief-core-0.6.schema.json matches the canonical
  *      content/vbrief/schemas/vbrief-core.schema.json byte-for-byte.
- *   2. @deftai/directive-types Status enum matches the schema Status enum.
- *   3. @deftai/directive-types VBRIEF_VERSION matches the schema version const.
+ *   2. packages/types/schemas/xbrief-core-0.8.schema.json matches the canonical
+ *      content/vbrief/schemas/xbrief-core-0.8.schema.json byte-for-byte.
+ *   3. @deftai/directive-types VALID_STATUSES matches v0.6 $defs.Status enum.
+ *   4. @deftai/directive-types VBRIEF_VERSION matches v0.8 $defs.xBRIEFInfo.version const.
  *
  * Exit codes: 0 clean / 1 drift / 2 config error.
  */
@@ -15,6 +17,8 @@ export declare const EXIT_DRIFT = 1;
 export declare const EXIT_CONFIG_ERROR = 2;
 export declare const CANONICAL_SCHEMA_REL = "content/vbrief/schemas/vbrief-core.schema.json";
 export declare const PUBLISHED_SCHEMA_REL = "packages/types/schemas/vbrief-core-0.6.schema.json";
+export declare const XBRIEF_CANONICAL_SCHEMA_REL = "content/vbrief/schemas/xbrief-core-0.8.schema.json";
+export declare const XBRIEF_PUBLISHED_SCHEMA_REL = "packages/types/schemas/xbrief-core-0.8.schema.json";
 export interface ContractDriftResult {
     readonly code: GateExitCode;
     readonly message: string;

package/dist/verify-source/contract-drift.js

@@ -1,11 +1,13 @@
 /**
- * contract-drift.ts — deterministic gate for the public contract layer (#1799).
+ * contract-drift.ts — deterministic gate for the public contract layer (#1799, #2107).
  *
  * Ensures:
  *   1. packages/types/schemas/vbrief-core-0.6.schema.json matches the canonical
  *      content/vbrief/schemas/vbrief-core.schema.json byte-for-byte.
- *   2. @deftai/directive-types Status enum matches the schema Status enum.
- *   3. @deftai/directive-types VBRIEF_VERSION matches the schema version const.
+ *   2. packages/types/schemas/xbrief-core-0.8.schema.json matches the canonical
+ *      content/vbrief/schemas/xbrief-core-0.8.schema.json byte-for-byte.
+ *   3. @deftai/directive-types VALID_STATUSES matches v0.6 $defs.Status enum.
+ *   4. @deftai/directive-types VBRIEF_VERSION matches v0.8 $defs.xBRIEFInfo.version const.
  *
  * Exit codes: 0 clean / 1 drift / 2 config error.
  */
@@ -17,6 +19,8 @@ export const EXIT_DRIFT = 1;
 export const EXIT_CONFIG_ERROR = 2;
 export const CANONICAL_SCHEMA_REL = "content/vbrief/schemas/vbrief-core.schema.json";
 export const PUBLISHED_SCHEMA_REL = "packages/types/schemas/vbrief-core-0.6.schema.json";
+export const XBRIEF_CANONICAL_SCHEMA_REL = "content/vbrief/schemas/xbrief-core-0.8.schema.json";
+export const XBRIEF_PUBLISHED_SCHEMA_REL = "packages/types/schemas/xbrief-core-0.8.schema.json";
 function defaultReadText(path) {
     return readFileSync(path, "utf8");
 }
@@ -48,38 +52,35 @@ function schemaStatusEnum(schema) {
     }
     return [...enumValues];
 }
-function schemaVersionConst(schema) {
+function xbriefVersionConst(schema) {
     const defs = schema.$defs;
     if (typeof defs !== "object" || defs === null || Array.isArray(defs)) {
         throw new Error("schema missing $defs");
     }
-    const info = defs.vBRIEFInfo;
+    const info = defs.xBRIEFInfo;
     if (typeof info !== "object" || info === null || Array.isArray(info)) {
-        throw new Error("schema missing $defs.vBRIEFInfo");
+        throw new Error("schema missing $defs.xBRIEFInfo");
     }
     const properties = info.properties;
     if (typeof properties !== "object" || properties === null || Array.isArray(properties)) {
-        throw new Error("schema missing $defs.vBRIEFInfo.properties");
+        throw new Error("schema missing $defs.xBRIEFInfo.properties");
     }
     const version = properties.version;
     if (typeof version !== "object" || version === null || Array.isArray(version)) {
-        throw new Error("schema missing $defs.vBRIEFInfo.properties.version");
+        throw new Error("schema missing $defs.xBRIEFInfo.properties.version");
     }
     const constValue = version.const;
     if (typeof constValue !== "string") {
-        throw new Error("schema $defs.vBRIEFInfo.properties.version.const must be a string");
+        throw new Error("schema $defs.xBRIEFInfo.properties.version.const must be a string");
     }
     return constValue;
 }
 function sortedStrings(values) {
     return [...values].sort();
 }
-/** Evaluate contract drift for the directive source tree. */
-export function evaluateContractDrift(projectRoot, options = {}) {
-    const root = resolve(projectRoot);
-    const readText = options.readText ?? defaultReadText;
-    const canonicalPath = join(root, CANONICAL_SCHEMA_REL);
-    const publishedPath = join(root, PUBLISHED_SCHEMA_REL);
+function schemaPairInSync(root, readText, canonicalRel, publishedRel) {
+    const canonicalPath = join(root, canonicalRel);
+    const publishedPath = join(root, publishedRel);
     let canonicalText;
     let publishedText;
     try {
@@ -97,14 +98,31 @@ export function evaluateContractDrift(projectRoot, options = {}) {
     if (canonicalText !== publishedText) {
         return {
             code: EXIT_DRIFT,
-            message: `contract-drift: ${PUBLISHED_SCHEMA_REL} is out of sync with ${CANONICAL_SCHEMA_REL}. ` +
+            message: `contract-drift: ${publishedRel} is out of sync with ${canonicalRel}. ` +
                 "Run: pnpm --prefix packages/types run prebuild",
             stream: "stderr",
         };
     }
-    let schema;
+    return null;
+}
+/** Evaluate contract drift for the directive source tree. */
+export function evaluateContractDrift(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    const readText = options.readText ?? defaultReadText;
+    for (const [canonicalRel, publishedRel] of [
+        [CANONICAL_SCHEMA_REL, PUBLISHED_SCHEMA_REL],
+        [XBRIEF_CANONICAL_SCHEMA_REL, XBRIEF_PUBLISHED_SCHEMA_REL],
+    ]) {
+        const syncResult = schemaPairInSync(root, readText, canonicalRel, publishedRel);
+        if (syncResult !== null) {
+            return syncResult;
+        }
+    }
+    let v06Schema;
+    let v08Schema;
     try {
-        schema = loadSchemaJson(canonicalText, CANONICAL_SCHEMA_REL);
+        v06Schema = loadSchemaJson(readText(join(root, CANONICAL_SCHEMA_REL)), CANONICAL_SCHEMA_REL);
+        v08Schema = loadSchemaJson(readText(join(root, XBRIEF_CANONICAL_SCHEMA_REL)), XBRIEF_CANONICAL_SCHEMA_REL);
     }
     catch (error) {
         const detail = error instanceof Error ? error.message : String(error);
@@ -115,7 +133,7 @@ export function evaluateContractDrift(projectRoot, options = {}) {
         };
     }
     try {
-        const schemaStatuses = sortedStrings(schemaStatusEnum(schema));
+        const schemaStatuses = sortedStrings(schemaStatusEnum(v06Schema));
         const typeStatuses = sortedStrings(VALID_STATUSES);
         if (schemaStatuses.join("|") !== typeStatuses.join("|")) {
             return {
@@ -125,12 +143,12 @@ export function evaluateContractDrift(projectRoot, options = {}) {
                 stream: "stderr",
             };
         }
-        const schemaVersion = schemaVersionConst(schema);
+        const schemaVersion = xbriefVersionConst(v08Schema);
         if (schemaVersion !== VBRIEF_VERSION) {
             return {
                 code: EXIT_DRIFT,
                 message: "contract-drift: VBRIEF_VERSION in @deftai/directive-types diverges from " +
-                    "schema vBRIEFInfo.version const.",
+                    "schema xBRIEFInfo.version const.",
                 stream: "stderr",
             };
         }
@@ -145,7 +163,7 @@ export function evaluateContractDrift(projectRoot, options = {}) {
     }
     return {
         code: EXIT_OK,
-        message: "contract-drift: canonical schema, published copy, and TS contract constants are in sync.",
+        message: "contract-drift: canonical schemas, published copies, and TS contract constants are in sync.",
         stream: "stdout",
     };
 }

package/dist/xbrief-migrate/constants.d.ts

@@ -0,0 +1,13 @@
+import { LEGACY_VBRIEF_VERSION, VBRIEF_REFERENCE_PREFIX, VBRIEF_VERSION, XBRIEF_REFERENCE_PREFIX } from "@deftai/directive-types";
+export { LEGACY_VBRIEF_VERSION, VBRIEF_REFERENCE_PREFIX, VBRIEF_VERSION, XBRIEF_REFERENCE_PREFIX };
+/** PlanItem container `type` values introduced in xBRIEF v0.8 (excludes `task`). */
+export declare const V08_CONTAINER_ITEM_TYPES: Set<string>;
+export declare const LEGACY_ARTIFACT_DIR: "vbrief";
+export declare const MIGRATED_ARTIFACT_DIR: "xbrief";
+export declare const LEGACY_ARTIFACT_SUFFIX: ".vbrief.json";
+export declare const MIGRATED_ARTIFACT_SUFFIX: ".xbrief.json";
+export declare const LEGACY_INFO_ROOT_KEY: "vBRIEFInfo";
+export declare const MIGRATED_INFO_ROOT_KEY: "xBRIEFInfo";
+/** Item-only status value added in xBRIEF v0.8. */
+export declare const V08_ITEM_STATUS_AUTO: "auto";
+//# sourceMappingURL=constants.d.ts.map

package/dist/xbrief-migrate/constants.js

@@ -0,0 +1,14 @@
+import { LEGACY_VBRIEF_VERSION, VBRIEF_REFERENCE_PREFIX, VBRIEF_VERSION, XBRIEF_REFERENCE_PREFIX, } from "@deftai/directive-types";
+import { VALID_PLAN_ITEM_TYPES } from "../vbrief-validate/constants.js";
+export { LEGACY_VBRIEF_VERSION, VBRIEF_REFERENCE_PREFIX, VBRIEF_VERSION, XBRIEF_REFERENCE_PREFIX };
+/** PlanItem container `type` values introduced in xBRIEF v0.8 (excludes `task`). */
+export const V08_CONTAINER_ITEM_TYPES = new Set([...VALID_PLAN_ITEM_TYPES].filter((t) => t !== "task"));
+export const LEGACY_ARTIFACT_DIR = "vbrief";
+export const MIGRATED_ARTIFACT_DIR = "xbrief";
+export const LEGACY_ARTIFACT_SUFFIX = ".vbrief.json";
+export const MIGRATED_ARTIFACT_SUFFIX = ".xbrief.json";
+export const LEGACY_INFO_ROOT_KEY = "vBRIEFInfo";
+export const MIGRATED_INFO_ROOT_KEY = "xBRIEFInfo";
+/** Item-only status value added in xBRIEF v0.8. */
+export const V08_ITEM_STATUS_AUTO = "auto";
+//# sourceMappingURL=constants.js.map

package/dist/xbrief-migrate/detect.d.ts

@@ -0,0 +1,11 @@
+/** Structured result of a legacy vbrief layout probe (#2108 / #2034). */
+export interface LegacyVbriefLayoutDetection {
+    legacyLayout: boolean;
+    reasons: string[];
+}
+/**
+ * Detect whether `projectRoot` still uses the legacy vbrief on-disk layout.
+ * Mirrors the structured-reasons pattern from `detectPreCutover` (#793).
+ */
+export declare function detectLegacyVbriefLayout(projectRoot: string): LegacyVbriefLayoutDetection;
+//# sourceMappingURL=detect.d.ts.map

package/dist/xbrief-migrate/detect.js

@@ -0,0 +1,81 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, LEGACY_VBRIEF_VERSION, MIGRATED_ARTIFACT_DIR, VBRIEF_REFERENCE_PREFIX, } from "./constants.js";
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function safeReadText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function walkJsonFiles(root, acc = []) {
+    if (!isDirectory(root)) {
+        return acc;
+    }
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        const full = join(root, entry.name);
+        if (entry.isDirectory()) {
+            walkJsonFiles(full, acc);
+        }
+        else if (entry.isFile() && entry.name.endsWith(".json")) {
+            acc.push(full);
+        }
+    }
+    return acc;
+}
+function scanFileContent(path, content, reasons) {
+    if (path.endsWith(LEGACY_ARTIFACT_SUFFIX)) {
+        reasons.add(`legacy artifact filename: ${path}`);
+    }
+    if (content.includes(`"${LEGACY_INFO_ROOT_KEY}"`)) {
+        reasons.add(`legacy info root key in ${path}`);
+    }
+    if (content.includes(`"version": "${LEGACY_VBRIEF_VERSION}"`)) {
+        reasons.add(`declared version ${LEGACY_VBRIEF_VERSION} in ${path}`);
+    }
+    if (content.includes(VBRIEF_REFERENCE_PREFIX)) {
+        reasons.add(`legacy reference prefix ${VBRIEF_REFERENCE_PREFIX} in ${path}`);
+    }
+}
+/**
+ * Detect whether `projectRoot` still uses the legacy vbrief on-disk layout.
+ * Mirrors the structured-reasons pattern from `detectPreCutover` (#793).
+ */
+export function detectLegacyVbriefLayout(projectRoot) {
+    const reasons = new Set();
+    const legacyRoot = join(projectRoot, LEGACY_ARTIFACT_DIR);
+    const migratedRoot = join(projectRoot, MIGRATED_ARTIFACT_DIR);
+    if (isDirectory(legacyRoot)) {
+        reasons.add(`${LEGACY_ARTIFACT_DIR}/ directory present`);
+        for (const jsonPath of walkJsonFiles(legacyRoot)) {
+            scanFileContent(jsonPath, safeReadText(jsonPath), reasons);
+        }
+    }
+    if (isDirectory(migratedRoot)) {
+        for (const jsonPath of walkJsonFiles(migratedRoot)) {
+            scanFileContent(jsonPath, safeReadText(jsonPath), reasons);
+        }
+    }
+    // Root-level legacy artifacts (unusual but covered by acceptance probes).
+    if (existsSync(projectRoot) && isDirectory(projectRoot)) {
+        for (const entry of readdirSync(projectRoot, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith(LEGACY_ARTIFACT_SUFFIX)) {
+                continue;
+            }
+            const full = join(projectRoot, entry.name);
+            scanFileContent(full, safeReadText(full), reasons);
+        }
+    }
+    const reasonList = [...reasons];
+    return { legacyLayout: reasonList.length > 0, reasons: reasonList };
+}
+//# sourceMappingURL=detect.js.map

package/dist/xbrief-migrate/drift-gate.d.ts

@@ -0,0 +1,56 @@
+/**
+ * #2109 Part 2 data-plane drift gate.
+ *
+ * After the canonical lifecycle tree is renamed `vbrief/` -> `xbrief/` and every
+ * `*.vbrief.json` artifact -> `*.xbrief.json`, this gate FAILS when a NEW
+ * legacy-layout token is reintroduced into the DATA PLANE:
+ *
+ *   1. a tracked `*.vbrief.json` artifact path (legacy suffix), or
+ *   2. a tracked file under a top-level `vbrief/` lifecycle directory, or
+ *   3. a bare `x-vbrief/` reference type inside a canonical corpus artifact
+ *      (`xbrief/ ** / *.xbrief.json`).
+ *
+ * It is a DATA-PLANE gate by construction: it only inspects artifact PATHS and
+ * the JSON content of canonical `*.xbrief.json` corpus files. The sanctioned
+ * back-compat SHIMS therefore never trip it:
+ *
+ *   - the Part 1 layout-resolver fallback (packages/core/src/layout/resolve.ts),
+ *   - the EXTENSION_PREFIXES legacy `x-vbrief/` entry
+ *     (packages/core/src/vbrief-validate/conformance.ts),
+ *   - the #2110 migrate path (packages/core/src/xbrief-migrate/),
+ *   - the #1650 legacy policy fallback,
+ *
+ * are TypeScript source files -- not `*.vbrief.json` artifacts, not under a
+ * top-level `vbrief/` dir, and not `xbrief/ ** / *.xbrief.json` corpus files --
+ * so they are outside the scanned candidate set and keep their intentional
+ * "vbrief" mentions. The DATA-PLANE fixtures that legitimately retain the legacy
+ * layout for back-compat regression coverage (test fixtures, the shipped
+ * `content/vbrief/` surface, forensic doc templates, archived history, and the
+ * framework's own `xbrief/migration/` RESULT artifacts) are explicitly
+ * allowlisted below.
+ */
+/** Bare legacy reference-namespace prefix (kept ACCEPTED by EXTENSION_PREFIXES; forbidden in NEW corpus artifacts). */
+export declare const LEGACY_REFERENCE_PREFIX: "x-vbrief/";
+/** Default allowlist: sanctioned data-plane trees that legitimately retain legacy tokens for back-compat. */
+export declare const BUILTIN_ALLOW_LIST: readonly string[];
+export type DriftScanMode = "all" | "staged";
+export interface DriftFinding {
+    readonly path: string;
+    readonly kind: "legacy-suffix" | "legacy-lifecycle-dir" | "legacy-reference-token";
+    readonly detail: string;
+}
+export interface DriftEvaluateOptions {
+    readonly mode?: DriftScanMode;
+    readonly allowListPath?: string | null;
+    readonly quiet?: boolean;
+}
+export interface DriftEvaluateResult {
+    readonly code: 0 | 1 | 2;
+    readonly findings: readonly DriftFinding[];
+    readonly message: string;
+    readonly stream: "stdout" | "stderr";
+}
+/** Scan a canonical corpus artifact's content for the bare legacy reference token. */
+export declare function scanCorpusToken(fullPath: string): boolean;
+export declare function evaluateXbriefDrift(projectRoot: string, options?: DriftEvaluateOptions): DriftEvaluateResult;
+//# sourceMappingURL=drift-gate.d.ts.map