@deftai/directive-core 0.64.0 → 0.66.0

package/dist/vbrief-validate/conformance.js

@@ -2,7 +2,9 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { GitCommandError, GitNotFoundError, gitStagedFiles, gitTrackedFiles, } from "../encoding/git.js";
 import { fnmatchCase } from "../encoding/text.js";
-export const DOC_CORE = new Set(["vBRIEFInfo", "plan"]);
+import { isLifecycleArtifactPath, LIFECYCLE_DIR_NAMES } from "../layout/resolve.js";
+import { evaluateExtensionRoundtrip } from "./roundtrip.js";
+export const DOC_CORE = new Set(["vBRIEFInfo", "xBRIEFInfo", "plan"]);
 export const PLAN_CORE = new Set([
     "id",
     "uid",
@@ -30,11 +32,14 @@ export const PLAN_CORE = new Set([
 export const ITEM_CORE = new Set([
     "id",
     "uid",
+    "type",
+    "summary",
     "title",
     "status",
     "narrative",
     "subItems",
     "planRef",
+    "planRefs",
     "tags",
     "metadata",
     "created",
@@ -58,12 +63,11 @@ export const ITEM_CORE = new Set([
     "lockedBy",
     "items",
 ]);
-export const EXTENSION_PREFIXES = ["x-directive/", "x-vbrief/"];
-export const ALLOW_LIST = new Set(["plan.policy", "plan.completedNote"]);
+export const EXTENSION_PREFIXES = ["x-directive/", "x-vbrief/", "x-xbrief/"];
 export function renderFinding(finding) {
     return `  ${finding.path} [${finding.level}] bare key '${finding.key}' at ${finding.location}`;
 }
-function isConformant(level, key, core) {
+function isConformant(key, core) {
     if (core.has(key)) {
         return true;
     }
@@ -72,7 +76,8 @@ function isConformant(level, key, core) {
             return true;
         }
     }
-    return ALLOW_LIST.has(`${level}.${key}`);
+    // No allow-list exceptions: every non-core key MUST be namespaced (#1650).
+    return false;
 }
 function planPlanRefFinding(relPath, value) {
     if (typeof value === "string" && value.trim().startsWith("#")) {
@@ -88,7 +93,7 @@ function planPlanRefFinding(relPath, value) {
 function scanItem(relPath, item, location) {
     const findings = [];
     for (const key of Object.keys(item)) {
-        if (!isConformant("item", key, ITEM_CORE)) {
+        if (!isConformant(key, ITEM_CORE)) {
             findings.push({ path: relPath, level: "item", key, location });
         }
     }
@@ -113,7 +118,7 @@ export function scanVbrief(relPath, data) {
     }
     const doc = data;
     for (const key of Object.keys(doc)) {
-        if (!isConformant("document", key, DOC_CORE)) {
+        if (!isConformant(key, DOC_CORE)) {
             findings.push({ path: relPath, level: "document", key, location: "<root>" });
         }
     }
@@ -130,7 +135,7 @@ export function scanVbrief(relPath, data) {
             }
             continue;
         }
-        if (!isConformant("plan", key, PLAN_CORE)) {
+        if (!isConformant(key, PLAN_CORE)) {
             findings.push({ path: relPath, level: "plan", key, location: "plan" });
         }
     }
@@ -164,7 +169,8 @@ function isAllowListed(relPath, patterns) {
     return patterns.some((pat) => fnmatchCase(relPath, pat));
 }
 function isVbriefPath(posix) {
-    return posix.startsWith("vbrief/") && posix.endsWith(".vbrief.json");
+    // Layout-aware (#2109 part 1): accept either lifecycle root + either suffix.
+    return isLifecycleArtifactPath(posix);
 }
 /** Pure driver returning exit code, findings, and human message. */
 export function evaluateConformance(projectRoot, options = {}) {
@@ -178,7 +184,7 @@ export function evaluateConformance(projectRoot, options = {}) {
                 "(expected 'all' or 'staged').",
         };
     }
-    if (!existsSync(join(root, "vbrief"))) {
+    if (!LIFECYCLE_DIR_NAMES.some((dir) => existsSync(join(root, dir)))) {
         return {
             exitCode: 2,
             findings: [],
@@ -251,8 +257,8 @@ export function evaluateConformance(projectRoot, options = {}) {
         const uniquePaths = new Set(findings.map((f) => f.path));
         const header = `\u274c verify_vbrief_conformance: detected ${findings.length} bare ` +
             `key(s) across ${uniquePaths.size} file(s) (#1620).\n` +
-            "  Every vBRIEF key MUST be 0.6 spec-core, x-directive/-namespaced, " +
-            "or x-vbrief/-namespaced -- never bare.\n" +
+            "  Every vBRIEF key MUST be spec-core, x-directive/-namespaced, " +
+            "x-vbrief/-namespaced, or x-xbrief/-namespaced -- never bare.\n" +
             "  Fix: migrate misused/misspelled core fields to their core home " +
             "(see scripts/vbrief_migrate_conformance.py), or namespace a genuine\n" +
             "  extension under x-directive/. Allow-list a documented file " +
@@ -263,11 +269,20 @@ export function evaluateConformance(projectRoot, options = {}) {
         }
         return { exitCode: 1, findings, message: `${header}\n${body}` };
     }
+    const extensionRoundtrip = evaluateExtensionRoundtrip(root);
+    if (extensionRoundtrip.exitCode !== 0) {
+        return {
+            exitCode: extensionRoundtrip.exitCode,
+            findings,
+            message: extensionRoundtrip.message,
+        };
+    }
+    const bareKeysMessage = `\u2713 verify_vbrief_conformance: ${candidates.length} vBRIEF file(s) ` +
+        "clean -- no bare keys (#1620).";
     return {
         exitCode: 0,
         findings,
-        message: `\u2713 verify_vbrief_conformance: ${candidates.length} vBRIEF file(s) ` +
-            "clean -- no bare keys (#1620).",
+        message: [extensionRoundtrip.message, bareKeysMessage].filter(Boolean).join("\n"),
     };
 }
 //# sourceMappingURL=conformance.js.map

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

@@ -1,12 +1,29 @@
-/** v0.6 Status enum from the canonical schema. */
+/** v0.6/v0.8 plan-level Status enum (excludes item-only `auto`). */
+export declare const VALID_PLAN_STATUSES: Set<string>;
+/** PlanItem status enum — plan statuses plus container rollup `auto` (#2107 / xBRIEF v0.8). */
+export declare const VALID_ITEM_STATUSES: Set<string>;
+/** @deprecated Use VALID_PLAN_STATUSES or VALID_ITEM_STATUSES; kept for module re-exports. */
 export declare const VALID_STATUSES: Set<string>;
 export declare const VALID_VBRIEF_VERSIONS: Set<string>;
+/** Accepted top-level document info blocks (additive v0.6 + v0.8). */
+export declare const VALID_INFO_ROOT_KEYS: Set<string>;
+/** v0.8 PlanItem.type enum values (optional field). */
+export declare const VALID_PLAN_ITEM_TYPES: Set<string>;
 /** D13: status-to-folder mapping (#533 adds ``failed`` in completed/). */
 export declare const FOLDER_ALLOWED_STATUSES: Readonly<Record<string, ReadonlySet<string>>>;
 export declare const LIFECYCLE_FOLDERS: string[];
 /** D3: expected narrative keys for PROJECT-DEFINITION (normalized). */
 export declare const PROJECT_DEF_EXPECTED_NARRATIVES: Set<string>;
 export declare const STRICT_ORIGIN_ALLOWLIST: Set<string>;
+/**
+ * Scope plan-link reference types under both the legacy `x-vbrief/` and the
+ * migrated `x-xbrief/` namespaces (#2109). Cross-file link validation (D4) and
+ * registry-status filtering must recognize both so a migrated corpus and a
+ * legacy corpus validate identically.
+ */
+export declare const PLAN_REFERENCE_TYPES: Set<string>;
+/** True when `value` is a scope plan-link reference type under either namespace. */
+export declare function isPlanReferenceType(value: unknown): boolean;
 export declare const LEGACY_ORIGIN_TYPES: Set<string>;
 export declare const DEPRECATED_FILES: readonly ["SPECIFICATION.md", "PROJECT.md"];
 export declare const USAGE = "Usage: vbrief_validate.py [--vbrief-dir <path>] [--strict-origin-types] [--warnings-as-errors]";

package/dist/vbrief-validate/constants.js

@@ -1,5 +1,5 @@
-/** v0.6 Status enum from the canonical schema. */
-export const VALID_STATUSES = new Set([
+/** v0.6/v0.8 plan-level Status enum (excludes item-only `auto`). */
+export const VALID_PLAN_STATUSES = new Set([
     "draft",
     "proposed",
     "approved",
@@ -10,7 +10,15 @@ export const VALID_STATUSES = new Set([
     "failed",
     "cancelled",
 ]);
-export const VALID_VBRIEF_VERSIONS = new Set(["0.6"]);
+/** PlanItem status enum — plan statuses plus container rollup `auto` (#2107 / xBRIEF v0.8). */
+export const VALID_ITEM_STATUSES = new Set([...VALID_PLAN_STATUSES, "auto"]);
+/** @deprecated Use VALID_PLAN_STATUSES or VALID_ITEM_STATUSES; kept for module re-exports. */
+export const VALID_STATUSES = VALID_PLAN_STATUSES;
+export const VALID_VBRIEF_VERSIONS = new Set(["0.6", "0.8"]);
+/** Accepted top-level document info blocks (additive v0.6 + v0.8). */
+export const VALID_INFO_ROOT_KEYS = new Set(["vBRIEFInfo", "xBRIEFInfo"]);
+/** v0.8 PlanItem.type enum values (optional field). */
+export const VALID_PLAN_ITEM_TYPES = new Set(["task", "group", "milestone", "epic"]);
 /** D13: status-to-folder mapping (#533 adds ``failed`` in completed/). */
 export const FOLDER_ALLOWED_STATUSES = {
     proposed: new Set(["draft", "proposed"]),
@@ -29,7 +37,28 @@ export const STRICT_ORIGIN_ALLOWLIST = new Set([
     "x-vbrief/jira-ticket",
     "x-vbrief/user-request",
     "x-vbrief/spec-section",
+    "x-xbrief/plan",
+    "x-xbrief/github-issue",
+    "x-xbrief/github-pr",
+    "x-xbrief/jira-ticket",
+    "x-xbrief/user-request",
+    "x-xbrief/spec-section",
+    "x-xbrief/commit",
+    "x-xbrief/external",
+    "x-xbrief/research",
+    "x-xbrief/adr",
 ]);
+/**
+ * Scope plan-link reference types under both the legacy `x-vbrief/` and the
+ * migrated `x-xbrief/` namespaces (#2109). Cross-file link validation (D4) and
+ * registry-status filtering must recognize both so a migrated corpus and a
+ * legacy corpus validate identically.
+ */
+export const PLAN_REFERENCE_TYPES = new Set(["x-vbrief/plan", "x-xbrief/plan"]);
+/** True when `value` is a scope plan-link reference type under either namespace. */
+export function isPlanReferenceType(value) {
+    return typeof value === "string" && PLAN_REFERENCE_TYPES.has(value);
+}
 export const LEGACY_ORIGIN_TYPES = new Set(["github-issue", "jira-ticket", "user-request"]);
 export const DEPRECATED_FILES = ["SPECIFICATION.md", "PROJECT.md"];
 export const USAGE = "Usage: vbrief_validate.py [--vbrief-dir <path>] [--strict-origin-types] [--warnings-as-errors]";

package/dist/vbrief-validate/epic-links.js

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs";
 import { basename, resolve } from "node:path";
+import { isPlanReferenceType } from "./constants.js";
 import { resolveRefPath } from "./paths.js";
 function collectPlanRefs(plan) {
     const refs = [];
@@ -77,7 +78,7 @@ export function validateEpicStoryLinks(allVbriefs, vbriefDir, resolvedToOriginal
                 if (typeof uri !== "string" || !uri || typeof refType !== "string" || !refType) {
                     continue;
                 }
-                if (refType !== "x-vbrief/plan") {
+                if (!isPlanReferenceType(refType)) {
                     continue;
                 }
                 const childPath = resolveRefPath(uri, vbriefDir);
@@ -124,7 +125,7 @@ export function validateEpicStoryLinks(allVbriefs, vbriefDir, resolvedToOriginal
                                     if (typeof pref === "object" &&
                                         pref !== null &&
                                         !Array.isArray(pref) &&
-                                        pref.type === "x-vbrief/plan") {
+                                        isPlanReferenceType(pref.type)) {
                                         const u = pref.uri;
                                         if (typeof u === "string") {
                                             childUris.add(u);

package/dist/vbrief-validate/filename.js

@@ -1,9 +1,11 @@
+import { ARTIFACT_SUFFIXES, hasArtifactSuffix, stripArtifactSuffix } from "../layout/resolve.js";
 /** D7: filename convention without polynomial regex (#1782 s3). */
 export function matchesFilenameConvention(name) {
-    if (!name.endsWith(".vbrief.json")) {
+    // Layout-aware (#2109 part 1): accept either .vbrief.json or .xbrief.json.
+    if (!ARTIFACT_SUFFIXES.some((suffix) => name.endsWith(suffix))) {
         return false;
     }
-    const stem = name.slice(0, -".vbrief.json".length);
+    const stem = stripArtifactSuffix(name);
     if (stem.length < 12) {
         return false;
     }
@@ -48,7 +50,7 @@ export function matchesFilenameConvention(name) {
 /** Check filename matches YYYY-MM-DD-descriptive-slug.vbrief.json (D7). */
 export function validateFilename(filepath) {
     const name = filepath.split("/").pop() ?? filepath;
-    if (name === "PROJECT-DEFINITION.vbrief.json") {
+    if (hasArtifactSuffix(name) && stripArtifactSuffix(name) === "PROJECT-DEFINITION") {
         return [];
     }
     if (!matchesFilenameConvention(name)) {

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

@@ -1,5 +1,5 @@
 export type { ConformanceEvaluateResult, ConformanceFinding, ConformanceMode, } from "./conformance.js";
-export { ALLOW_LIST, DOC_CORE, evaluateConformance, ITEM_CORE, PLAN_CORE, renderFinding, scanVbrief, } from "./conformance.js";
+export { DOC_CORE, evaluateConformance, ITEM_CORE, PLAN_CORE, renderFinding, scanVbrief, } from "./conformance.js";
 export { LIFECYCLE_FOLDERS, USAGE, VALID_STATUSES } from "./constants.js";
 export { matchesFilenameConvention, validateFilename } from "./filename.js";
 export { validateFolderStatus } from "./folder-status.js";
@@ -8,6 +8,8 @@ export { cmdVbriefValidate, runConformance, runValidate } from "./main.js";
 export { validateOriginProvenance } from "./origin.js";
 export { validateSessionRitualStalenessHoursOnPlan, validateTriageRankingLabelsOnPlan, validateWipCapOnPlan, } from "./plan-hooks.js";
 export { validateProjectDefinition } from "./project-definition.js";
+export type { ExtensionEntry, ExtensionRoundtripEvaluateResult, ExtensionRoundtripFinding, } from "./roundtrip.js";
+export { collectExtensionEntries, EXTENSION_CONFORMANCE_FIXTURES_DIR, evaluateExtensionRoundtrip, findExtensionPreservationViolations, reEmitVbriefArtifact, renderExtensionRoundtripFinding, VbriefSchemaValidationError, } from "./roundtrip.js";
 export { normalizeNarrativeKey, validateVbriefSchema } from "./schema.js";
 export type { ValidateAllResult } from "./validate-all.js";
 export { discoverVbriefs, validateAll, validateAllMigration, } from "./validate-all.js";

package/dist/vbrief-validate/index.js

@@ -1,4 +1,4 @@
-export { ALLOW_LIST, DOC_CORE, evaluateConformance, ITEM_CORE, PLAN_CORE, renderFinding, scanVbrief, } from "./conformance.js";
+export { DOC_CORE, evaluateConformance, ITEM_CORE, PLAN_CORE, renderFinding, scanVbrief, } from "./conformance.js";
 export { LIFECYCLE_FOLDERS, USAGE, VALID_STATUSES } from "./constants.js";
 export { matchesFilenameConvention, validateFilename } from "./filename.js";
 export { validateFolderStatus } from "./folder-status.js";
@@ -6,6 +6,7 @@ export { cmdVbriefValidate, runConformance, runValidate } from "./main.js";
 export { validateOriginProvenance } from "./origin.js";
 export { validateSessionRitualStalenessHoursOnPlan, validateTriageRankingLabelsOnPlan, validateWipCapOnPlan, } from "./plan-hooks.js";
 export { validateProjectDefinition } from "./project-definition.js";
+export { collectExtensionEntries, EXTENSION_CONFORMANCE_FIXTURES_DIR, evaluateExtensionRoundtrip, findExtensionPreservationViolations, reEmitVbriefArtifact, renderExtensionRoundtripFinding, VbriefSchemaValidationError, } from "./roundtrip.js";
 export { normalizeNarrativeKey, validateVbriefSchema } from "./schema.js";
 export { discoverVbriefs, validateAll, validateAllMigration, } from "./validate-all.js";
 //# sourceMappingURL=index.js.map

package/dist/vbrief-validate/main.js

@@ -1,11 +1,16 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
+import { resolveLifecycleLayout } from "../layout/resolve.js";
 import { evaluateConformance } from "./conformance.js";
 import { USAGE } from "./constants.js";
 import { validateAll } from "./validate-all.js";
 /** CLI entry for vbrief_validate.py parity. */
 export function runValidate(argv) {
-    let vbriefDir = "vbrief";
+    // Layout-aware (#2109 part 1/2a): when --vbrief-dir is omitted, resolve the
+    // lifecycle layout root for --project-root (xbrief when migrated, else vbrief
+    // -- unchanged on today's repo). The prior false-green hardcoded the dir.
+    let vbriefDir = null;
+    let projectRoot = null;
     let strictOriginTypes = false;
     let warningsAsErrors = false;
     let i = 0;
@@ -15,6 +20,10 @@ export function runValidate(argv) {
             vbriefDir = argv[i + 1] ?? vbriefDir;
             i += 2;
         }
+        else if (arg === "--project-root" && i + 1 < argv.length) {
+            projectRoot = argv[i + 1] ?? projectRoot;
+            i += 2;
+        }
         else if (arg === "--strict-origin-types") {
             strictOriginTypes = true;
             i += 1;
@@ -33,11 +42,12 @@ export function runValidate(argv) {
             return 2;
         }
     }
-    if (!existsSync(vbriefDir)) {
-        process.stdout.write(`OK: No vbrief directory at ${vbriefDir} -- skipping validation\n`);
+    const resolvedDir = vbriefDir ?? resolveLifecycleLayout(projectRoot ?? process.cwd()).root;
+    if (!existsSync(resolvedDir)) {
+        process.stdout.write(`OK: No vbrief directory at ${resolvedDir} -- skipping validation\n`);
         return 0;
     }
-    const { errors, warnings, scopeCount } = validateAll(vbriefDir, { strictOriginTypes });
+    const { errors, warnings, scopeCount } = validateAll(resolvedDir, { strictOriginTypes });
     for (const w of warnings) {
         process.stdout.write(`WARN: ${w}\n`);
     }
@@ -51,8 +61,9 @@ export function runValidate(argv) {
         if (scopeCount > 0) {
             parts.push(`${scopeCount} scope vBRIEF(s)`);
         }
-        const projectDef = resolve(vbriefDir, "PROJECT-DEFINITION.vbrief.json");
-        if (existsSync(projectDef)) {
+        const projectDef = resolve(resolvedDir, "PROJECT-DEFINITION.vbrief.json");
+        const projectDefXbrief = resolve(resolvedDir, "PROJECT-DEFINITION.xbrief.json");
+        if (existsSync(projectDef) || existsSync(projectDefXbrief)) {
             parts.push("PROJECT-DEFINITION");
         }
         const summary = parts.length > 0 ? parts.join(", ") : "no vBRIEF files";

package/dist/vbrief-validate/origin.js

@@ -12,7 +12,7 @@ function legacyOriginMatch(refType) {
     return false;
 }
 function schemaTrustingOrigin(refType) {
-    return refType.startsWith("x-vbrief/");
+    return refType.startsWith("x-vbrief/") || refType.startsWith("x-xbrief/");
 }
 /** Warn if a scope vBRIEF in pending/ or active/ has no origin reference (D11). */
 export function validateOriginProvenance(filepath, data, vbriefDir, strictOriginTypes = false) {

package/dist/vbrief-validate/paths.js

@@ -1,4 +1,5 @@
 import { basename, relative, resolve, sep } from "node:path";
+import { hasArtifactSuffix, stripArtifactSuffix } from "../layout/resolve.js";
 /** Return true when ``child`` resolves under ``parent``. */
 export function isRelativeTo(child, parent) {
     const resolvedParent = resolve(parent);
@@ -45,7 +46,7 @@ function splitMax(value, sep, maxsplit) {
 export function scopeIdsForRefUri(uri) {
     const rel = uri.startsWith("file://") ? uri.slice("file://".length) : uri;
     const name = basename(rel);
-    const fullId = name.endsWith(".vbrief.json") ? name.slice(0, -".vbrief.json".length) : name;
+    const fullId = hasArtifactSuffix(name) ? stripArtifactSuffix(name) : name;
     const ids = new Set([fullId]);
     const parts = splitMax(fullId, "-", 3);
     if (parts.length === 4 &&

package/dist/vbrief-validate/plan-hooks.js

@@ -1,3 +1,4 @@
+import { readPlanPolicy } from "../policy/plan-extensions.js";
 import { validateTriageAutoClassifyOnPlan, validateTriageHoldMarkersOnPlan, } from "../triage/classify/index.js";
 import { validateRankingLabels } from "../triage/queue/ranking-labels.js";
 import { pyStrRepr, pythonTypeName } from "../triage/scope/python-repr.js";
@@ -30,7 +31,7 @@ export function validateWipCapOnPlan(plan, filepath) {
     if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
         return [];
     }
-    const policy = plan.policy;
+    const policy = readPlanPolicy(plan);
     if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
         return [];
     }
@@ -72,7 +73,7 @@ export function validateSessionRitualStalenessHoursOnPlan(plan, filepath) {
     if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
         return [];
     }
-    const policy = plan.policy;
+    const policy = readPlanPolicy(plan);
     if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
         return [];
     }
@@ -90,7 +91,7 @@ export function validateTriageRankingLabelsOnPlan(plan, filepath) {
     if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
         return [];
     }
-    const policy = plan.policy;
+    const policy = readPlanPolicy(plan);
     const raw = typeof policy === "object" && policy !== null && !Array.isArray(policy)
         ? policy.triageRankingLabels
         : undefined;

package/dist/vbrief-validate/registry-status.d.ts

@@ -1,4 +1,5 @@
 import type { JsonObject } from "./schema.js";
+/** @deprecated Use {@link isPlanReferenceType}; kept for back-compat re-exports. */
 export declare const REGISTRY_SCOPE_LINK_TYPE = "x-vbrief/plan";
 /** Derive the registry item status from a scope vBRIEF (render side). */
 export declare function deriveRegistryItemStatus(planStatus: unknown, lifecycleFolder: string): string;

package/dist/vbrief-validate/registry-status.js

@@ -1,3 +1,5 @@
+import { isPlanReferenceType } from "./constants.js";
+/** @deprecated Use {@link isPlanReferenceType}; kept for back-compat re-exports. */
 export const REGISTRY_SCOPE_LINK_TYPE = "x-vbrief/plan";
 /** Derive the registry item status from a scope vBRIEF (render side). */
 export function deriveRegistryItemStatus(planStatus, lifecycleFolder) {
@@ -10,7 +12,7 @@ function isScopeLinkRef(ref) {
     return (typeof ref === "object" &&
         ref !== null &&
         !Array.isArray(ref) &&
-        ref.type === REGISTRY_SCOPE_LINK_TYPE);
+        isPlanReferenceType(ref.type));
 }
 /**
  * References copied onto a registry item from a scope vBRIEF.

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

@@ -0,0 +1,36 @@
+import type { JsonObject } from "./schema.js";
+/** Relative path to extension round-trip conformance fixtures (#715). */
+export declare const EXTENSION_CONFORMANCE_FIXTURES_DIR = "content/vbrief/conformance/extensions/valid";
+export interface ExtensionEntry {
+    readonly jsonPath: string;
+    readonly key: string;
+    readonly value: unknown;
+}
+export interface ExtensionRoundtripFinding {
+    readonly path: string;
+    readonly message: string;
+}
+/** Thrown when `reEmitVbriefArtifact` rejects an artifact that fails schema validation. */
+export declare class VbriefSchemaValidationError extends Error {
+    readonly relPath: string;
+    readonly errors: readonly string[];
+    constructor(relPath: string, errors: readonly string[]);
+}
+/** Recursively collect every `x-<consumer>/` key in `value` using the contract pattern. */
+export declare function collectExtensionEntries(value: unknown, jsonPath?: string): ExtensionEntry[];
+/** Compare extension keys/values between two parsed artifacts (JSON structural equality). */
+export declare function findExtensionPreservationViolations(original: unknown, roundtripped: unknown): string[];
+/**
+ * Canonical reference-consumer read/write pipeline: validate, serialize, re-parse.
+ * Extension properties MUST survive this path verbatim (xBRIEF v0.8 §7).
+ */
+export declare function reEmitVbriefArtifact(artifact: JsonObject, relPath?: string): JsonObject;
+export declare function renderExtensionRoundtripFinding(finding: ExtensionRoundtripFinding): string;
+export interface ExtensionRoundtripEvaluateResult {
+    readonly exitCode: number;
+    readonly findings: readonly ExtensionRoundtripFinding[];
+    readonly message: string;
+}
+/** Run extension round-trip preservation over packaged conformance fixtures. */
+export declare function evaluateExtensionRoundtrip(projectRoot: string): ExtensionRoundtripEvaluateResult;
+//# sourceMappingURL=roundtrip.d.ts.map

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;