@deftai/directive-core 0.65.0 → 0.66.1

package/dist/vbrief-validate/roundtrip.js

@@ -0,0 +1,168 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { isExtensionKey } from "@deftai/directive-types";
+import { validateVbriefSchema } from "./schema.js";
+/** Relative path to extension round-trip conformance fixtures (#715). */
+export const EXTENSION_CONFORMANCE_FIXTURES_DIR = "content/vbrief/conformance/extensions/valid";
+/** Thrown when `reEmitVbriefArtifact` rejects an artifact that fails schema validation. */
+export class VbriefSchemaValidationError extends Error {
+    relPath;
+    errors;
+    constructor(relPath, errors) {
+        super(`schema validation failed for ${relPath}: ${errors.join("; ")}`);
+        this.relPath = relPath;
+        this.errors = errors;
+        this.name = "VbriefSchemaValidationError";
+    }
+}
+/** Recursively collect every `x-<consumer>/` key in `value` using the contract pattern. */
+export function collectExtensionEntries(value, jsonPath = "$") {
+    if (Array.isArray(value)) {
+        const entries = [];
+        for (let index = 0; index < value.length; index += 1) {
+            entries.push(...collectExtensionEntries(value[index], `${jsonPath}[${index}]`));
+        }
+        return entries;
+    }
+    if (typeof value !== "object" || value === null) {
+        return [];
+    }
+    const obj = value;
+    const entries = [];
+    for (const [key, entryValue] of Object.entries(obj)) {
+        const childPath = `${jsonPath}.${JSON.stringify(key)}`;
+        if (isExtensionKey(key)) {
+            entries.push({ jsonPath: childPath, key, value: entryValue });
+        }
+        entries.push(...collectExtensionEntries(entryValue, childPath));
+    }
+    return entries;
+}
+function entriesByPath(entries) {
+    const map = new Map();
+    for (const entry of entries) {
+        map.set(entry.jsonPath, entry.value);
+    }
+    return map;
+}
+/** Compare extension keys/values between two parsed artifacts (JSON structural equality). */
+export function findExtensionPreservationViolations(original, roundtripped) {
+    const before = collectExtensionEntries(original);
+    const afterMap = entriesByPath(collectExtensionEntries(roundtripped));
+    const violations = [];
+    for (const entry of before) {
+        if (!afterMap.has(entry.jsonPath)) {
+            violations.push(`dropped extension key '${entry.key}' at ${entry.jsonPath}`);
+            continue;
+        }
+        const afterValue = afterMap.get(entry.jsonPath);
+        if (JSON.stringify(entry.value) !== JSON.stringify(afterValue)) {
+            violations.push(`mutated extension key '${entry.key}' at ${entry.jsonPath}`);
+        }
+    }
+    return violations;
+}
+/**
+ * Canonical reference-consumer read/write pipeline: validate, serialize, re-parse.
+ * Extension properties MUST survive this path verbatim (xBRIEF v0.8 §7).
+ */
+export function reEmitVbriefArtifact(artifact, relPath = "<roundtrip>") {
+    const schemaErrors = validateVbriefSchema(artifact, relPath);
+    if (schemaErrors.length > 0) {
+        throw new VbriefSchemaValidationError(relPath, schemaErrors);
+    }
+    const serialized = `${JSON.stringify(artifact, null, 2)}\n`;
+    return JSON.parse(serialized);
+}
+export function renderExtensionRoundtripFinding(finding) {
+    return `  ${finding.path}: ${finding.message}`;
+}
+/** Run extension round-trip preservation over packaged conformance fixtures. */
+export function evaluateExtensionRoundtrip(projectRoot) {
+    const root = resolve(projectRoot);
+    const fixturesDir = join(root, EXTENSION_CONFORMANCE_FIXTURES_DIR);
+    if (!existsSync(fixturesDir)) {
+        return {
+            exitCode: 0,
+            findings: [],
+            message: "",
+        };
+    }
+    let fixtureNames;
+    try {
+        fixtureNames = readdirSync(fixturesDir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.endsWith(".vbrief.json"))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch (err) {
+        const e = err;
+        return {
+            exitCode: 2,
+            findings: [],
+            message: `\u274c verify_vbrief_conformance: cannot read extension fixtures: ${e.message ?? err}`,
+        };
+    }
+    if (fixtureNames.length === 0) {
+        return {
+            exitCode: 2,
+            findings: [],
+            message: `\u274c verify_vbrief_conformance: no *.vbrief.json fixtures under ` +
+                `${EXTENSION_CONFORMANCE_FIXTURES_DIR}/.`,
+        };
+    }
+    const findings = [];
+    for (const name of fixtureNames) {
+        const relPath = `${EXTENSION_CONFORMANCE_FIXTURES_DIR}/${name}`;
+        const fullPath = join(fixturesDir, name);
+        let text;
+        try {
+            text = readFileSync(fullPath, "utf8");
+        }
+        catch (err) {
+            const e = err;
+            findings.push({
+                path: relPath,
+                message: `unreadable fixture: ${e.message ?? String(err)}`,
+            });
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (err) {
+            findings.push({
+                path: relPath,
+                message: `invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+            });
+            continue;
+        }
+        const schemaErrors = validateVbriefSchema(parsed, relPath);
+        for (const error of schemaErrors) {
+            findings.push({ path: relPath, message: error });
+        }
+        if (schemaErrors.length > 0) {
+            continue;
+        }
+        const roundtripped = reEmitVbriefArtifact(parsed, relPath);
+        for (const violation of findExtensionPreservationViolations(parsed, roundtripped)) {
+            findings.push({ path: relPath, message: violation });
+        }
+    }
+    if (findings.length > 0) {
+        const header = `\u274c verify_vbrief_conformance: extension round-trip preservation failed ` +
+            `(${findings.length} finding(s), #715).\n` +
+            "  Every key matching ^x-[a-z0-9-]+/ MUST survive load->re-emit verbatim at every object level.";
+        const body = findings.slice(0, 50).map(renderExtensionRoundtripFinding).join("\n");
+        const tail = findings.length > 50 ? `\n  ... and ${findings.length - 50} more` : "";
+        return { exitCode: 1, findings, message: `${header}\n${body}${tail}` };
+    }
+    return {
+        exitCode: 0,
+        findings,
+        message: `\u2713 verify_vbrief_conformance: ${fixtureNames.length} extension fixture(s) ` +
+            "round-trip clean (#715).",
+    };
+}
+//# sourceMappingURL=roundtrip.js.map

package/dist/vbrief-validate/schema.d.ts

@@ -1,5 +1,5 @@
 export type JsonObject = Record<string, unknown>;
-/** Validate vBRIEF structural requirements (v0.6). */
+/** Validate vBRIEF/xBRIEF structural requirements (v0.6 + v0.8 additive). */
 export declare function validateVbriefSchema(data: JsonObject, filepath: string): string[];
 /** Normalize a narrative key for D3 comparison. */
 export declare function normalizeNarrativeKey(key: string): string;

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