@deftai/directive-core 0.65.0 → 0.66.1

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

package/dist/xbrief-migrate/drift-gate.js

@@ -0,0 +1,205 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { GitCommandError, GitNotFoundError, gitStagedFiles, gitTrackedFiles, } from "../encoding/git.js";
+import { fnmatchCase } from "../encoding/text.js";
+import { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, } from "./constants.js";
+/**
+ * #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 const LEGACY_REFERENCE_PREFIX = "x-vbrief/";
+/** Default allowlist: sanctioned data-plane trees that legitimately retain legacy tokens for back-compat. */
+export const BUILTIN_ALLOW_LIST = [
+    // Shipped vBRIEF surface (#1875 C3) + conformance round-trip fixtures (#715).
+    "content/vbrief/**",
+    // Test fixtures exercising the legacy read path + pre-cutover migration (#2108 / #2110)
+    // and this gate's own regression fixtures.
+    "tests/**",
+    // Forensic-research doc templates ship a `.vbrief.json` example.
+    "docs/**",
+    // Archived forensic / onboarding records.
+    "history/**",
+    // The framework's own migration RESULT artifacts may reference the legacy layout by design.
+    `${MIGRATED_ARTIFACT_DIR}/migration/**`,
+];
+function loadAllowList(path) {
+    if (path === null) {
+        return [];
+    }
+    if (!existsSync(path)) {
+        return {
+            error: `verify_xbrief_drift: --allow-list file not found: [Errno 2] No such file or directory: '${path}'\n` +
+                "  Recovery: pass an existing path or omit the flag.",
+        };
+    }
+    try {
+        const raw = readFileSync(path, { encoding: "utf8" });
+        const out = [];
+        for (const line of raw.split("\n")) {
+            const stripped = line.trim();
+            if (!stripped || stripped.startsWith("#")) {
+                continue;
+            }
+            out.push(stripped);
+        }
+        return out;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            error: `verify_xbrief_drift: --allow-list unreadable: ${msg}\n` +
+                "  Recovery: check file permissions.",
+        };
+    }
+}
+function isAllowListed(relPath, patterns) {
+    return patterns.some((pat) => fnmatchCase(relPath, pat));
+}
+function listFiles(projectRoot, mode) {
+    try {
+        const files = mode === "staged" ? gitStagedFiles(projectRoot) : gitTrackedFiles(projectRoot);
+        return files.map((p) => p.replace(/\\/g, "/"));
+    }
+    catch (err) {
+        if (err instanceof GitNotFoundError) {
+            return {
+                error: "verify_xbrief_drift: 'git' executable not found on PATH.\n" +
+                    "  Recovery: install git or run inside a git working tree.",
+            };
+        }
+        if (err instanceof GitCommandError) {
+            return {
+                error: `verify_xbrief_drift: git failed: ${err.message}\n` +
+                    "  Recovery: run inside a git working tree.",
+            };
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        return { error: `verify_xbrief_drift: ${msg}` };
+    }
+}
+/** Scan a canonical corpus artifact's content for the bare legacy reference token. */
+export function scanCorpusToken(fullPath) {
+    let source;
+    try {
+        source = readFileSync(fullPath, { encoding: "utf8" });
+    }
+    catch {
+        return false;
+    }
+    // Reference types appear as JSON string values, e.g. `"type": "x-vbrief/..."`.
+    // The bare prefix as a quoted-string boundary is the structural token we forbid.
+    return source.includes(`"${LEGACY_REFERENCE_PREFIX}`) || source.includes(LEGACY_REFERENCE_PREFIX);
+}
+export function evaluateXbriefDrift(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    let isDir = false;
+    try {
+        isDir = statSync(root).isDirectory();
+    }
+    catch {
+        isDir = false;
+    }
+    if (!isDir) {
+        return {
+            code: 2,
+            findings: [],
+            message: `verify_xbrief_drift: --project-root is not a directory: ${root}\n` +
+                "  Recovery: pass an existing directory path.",
+            stream: "stderr",
+        };
+    }
+    const allowLoaded = loadAllowList(options.allowListPath ?? null);
+    if (!Array.isArray(allowLoaded)) {
+        return { code: 2, findings: [], message: allowLoaded.error, stream: "stderr" };
+    }
+    const allowGlobs = [...BUILTIN_ALLOW_LIST, ...allowLoaded];
+    const mode = options.mode ?? "all";
+    const listed = listFiles(root, mode);
+    if (!Array.isArray(listed)) {
+        return { code: 2, findings: [], message: listed.error, stream: "stderr" };
+    }
+    const legacyDirPrefix = `${LEGACY_ARTIFACT_DIR}/`;
+    const corpusPrefix = `${MIGRATED_ARTIFACT_DIR}/`;
+    const findings = [];
+    for (const rel of listed) {
+        if (isAllowListed(rel, allowGlobs)) {
+            continue;
+        }
+        if (rel === LEGACY_ARTIFACT_DIR || rel.startsWith(legacyDirPrefix)) {
+            findings.push({
+                path: rel,
+                kind: "legacy-lifecycle-dir",
+                detail: `tracked under the legacy top-level \`${legacyDirPrefix}\` lifecycle directory (canonical: \`${corpusPrefix}\`)`,
+            });
+            continue;
+        }
+        if (rel.endsWith(LEGACY_ARTIFACT_SUFFIX)) {
+            findings.push({
+                path: rel,
+                kind: "legacy-suffix",
+                detail: `legacy artifact suffix \`${LEGACY_ARTIFACT_SUFFIX}\` (canonical: \`${MIGRATED_ARTIFACT_SUFFIX}\`)`,
+            });
+            continue;
+        }
+        if (rel.startsWith(corpusPrefix) && rel.endsWith(MIGRATED_ARTIFACT_SUFFIX)) {
+            if (scanCorpusToken(join(root, rel))) {
+                findings.push({
+                    path: rel,
+                    kind: "legacy-reference-token",
+                    detail: `bare legacy reference token \`${LEGACY_REFERENCE_PREFIX}\` in a canonical corpus artifact (canonical: \`x-${MIGRATED_ARTIFACT_DIR}/\`)`,
+                });
+            }
+        }
+    }
+    if (findings.length > 0) {
+        const header = `verify_xbrief_drift: detected ${findings.length} legacy-layout token(s) reintroduced into the data plane (#2109).\n` +
+            "  Root cause: the canonical lifecycle layout is `xbrief/ ** / *.xbrief.json` with `x-xbrief/` reference types.\n" +
+            "  Fix: rename the artifact to `.xbrief.json`, move it under `xbrief/`, and use the `x-xbrief/` reference prefix.\n" +
+            "  Sanctioned back-compat fixtures are allowlisted; add a documented exception via `--allow-list <path>`\n" +
+            "  (file with newline-separated glob patterns).";
+        const body = findings
+            .slice(0, 50)
+            .map((f) => `  ${f.path} [${f.kind}] ${f.detail}`)
+            .join("\n");
+        const more = findings.length > 50 ? `\n  ... and ${findings.length - 50} more` : "";
+        return { code: 1, findings, message: `${header}\n${body}${more}`, stream: "stderr" };
+    }
+    if (options.quiet === true) {
+        return { code: 0, findings: [], message: "", stream: "stdout" };
+    }
+    return {
+        code: 0,
+        findings: [],
+        message: `verify_xbrief_drift: no legacy-layout drift -- \`${corpusPrefix}\` is canonical (#2109).`,
+        stream: "stdout",
+    };
+}
+//# sourceMappingURL=drift-gate.js.map

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

@@ -0,0 +1,7 @@
+export { detectLegacyVbriefLayout, type LegacyVbriefLayoutDetection, } from "./detect.js";
+export { BUILTIN_ALLOW_LIST, type DriftEvaluateOptions, type DriftEvaluateResult, type DriftFinding, type DriftScanMode, evaluateXbriefDrift, LEGACY_REFERENCE_PREFIX, scanCorpusToken, } from "./drift-gate.js";
+export { emitXbriefMigration, runXbriefMigration, runXbriefMigrationCli, type XbriefMigrationArgs, type XbriefMigrationIo, type XbriefMigrationOutcome, } from "./migrate-project.js";
+export { renderXbriefMigrationLine, xbriefMigrationGuidance } from "./signpost.js";
+export { assertFeatureEmissionAllowed, assertLayoutAwareWritePath, FeatureEmissionRejectedError, type JsonObject, type JsonValue, readDeclaredArtifactVersion, resolveLayoutAwareRelativePath, rewriteEmbeddedTokens, SplitLayoutRejectedError, TransformError, transformArtifactV06ToV08, transformArtifactV06ToV08Transactional, } from "./transforms.js";
+export { isPatchOnlyUpgrade, parseSemverPrefix } from "./version.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/xbrief-migrate/index.js

@@ -0,0 +1,7 @@
+export { detectLegacyVbriefLayout, } from "./detect.js";
+export { BUILTIN_ALLOW_LIST, evaluateXbriefDrift, LEGACY_REFERENCE_PREFIX, scanCorpusToken, } from "./drift-gate.js";
+export { emitXbriefMigration, runXbriefMigration, runXbriefMigrationCli, } from "./migrate-project.js";
+export { renderXbriefMigrationLine, xbriefMigrationGuidance } from "./signpost.js";
+export { assertFeatureEmissionAllowed, assertLayoutAwareWritePath, FeatureEmissionRejectedError, readDeclaredArtifactVersion, resolveLayoutAwareRelativePath, rewriteEmbeddedTokens, SplitLayoutRejectedError, TransformError, transformArtifactV06ToV08, transformArtifactV06ToV08Transactional, } from "./transforms.js";
+export { isPatchOnlyUpgrade, parseSemverPrefix } from "./version.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,33 @@
+export interface XbriefMigrationArgs {
+    readonly projectRoot: string;
+    readonly frameworkRoot?: string;
+    readonly force?: boolean;
+}
+export interface XbriefMigrationIo {
+    writeOut: (text: string) => void;
+    writeErr: (text: string) => void;
+}
+export type XbriefMigrationOutcome = {
+    readonly kind: "noop";
+    readonly message: string;
+} | {
+    readonly kind: "refused";
+    readonly message: string;
+} | {
+    readonly kind: "migrated";
+    readonly backupDir: string;
+    readonly files: number;
+} | {
+    readonly kind: "config";
+    readonly message: string;
+};
+/** Core orchestrator for the consumer xbrief rename (#2110). */
+export declare function runXbriefMigration(args: XbriefMigrationArgs, _io: XbriefMigrationIo): XbriefMigrationOutcome;
+/** Map a migration outcome to a process exit code and emit operator guidance. */
+export declare function emitXbriefMigration(outcome: XbriefMigrationOutcome, io: XbriefMigrationIo, options?: {
+    signpostOnly?: boolean;
+    projectRoot?: string;
+}): number;
+/** End-to-end migrate:xbrief handler including optional agents:refresh (#2110). */
+export declare function runXbriefMigrationCli(args: XbriefMigrationArgs, io: XbriefMigrationIo): number;
+//# sourceMappingURL=migrate-project.d.ts.map

package/dist/xbrief-migrate/migrate-project.js

@@ -0,0 +1,189 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { checkGitClean } from "../migrate-preflight/index.js";
+import { agentsRefreshPlan } from "../platform/agents-md.js";
+import { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, } from "./constants.js";
+import { detectLegacyVbriefLayout } from "./detect.js";
+import { renderXbriefMigrationLine, xbriefMigrationGuidance } from "./signpost.js";
+import { rewriteEmbeddedTokens, transformArtifactV06ToV08Transactional } from "./transforms.js";
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function collectFiles(root, acc = []) {
+    if (!isDirectory(root)) {
+        return acc;
+    }
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        const full = join(root, entry.name);
+        if (entry.isDirectory()) {
+            collectFiles(full, acc);
+        }
+        else if (entry.isFile()) {
+            acc.push(full);
+        }
+    }
+    return acc;
+}
+function mapRelativePath(relativePath) {
+    return relativePath
+        .split(/[/\\]/)
+        .map((segment) => segment.endsWith(LEGACY_ARTIFACT_SUFFIX)
+        ? segment.slice(0, -LEGACY_ARTIFACT_SUFFIX.length) + MIGRATED_ARTIFACT_SUFFIX
+        : segment)
+        .join("/");
+}
+function writeMigratedFile(srcPath, destPath) {
+    mkdirSync(dirname(destPath), { recursive: true });
+    if (srcPath.endsWith(LEGACY_ARTIFACT_SUFFIX)) {
+        const parsed = JSON.parse(readFileSync(srcPath, "utf8"));
+        const result = transformArtifactV06ToV08Transactional(parsed);
+        if (!result.ok) {
+            throw new Error(result.error);
+        }
+        writeFileSync(destPath, `${JSON.stringify(result.artifact, null, 2)}\n`, "utf8");
+        return;
+    }
+    const raw = readFileSync(srcPath, "utf8");
+    writeFileSync(destPath, rewriteEmbeddedTokens(raw), "utf8");
+}
+function backupLegacyTree(projectRoot, legacyDir) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const backupRoot = join(projectRoot, ".deft", `xbrief-migrate-backup-${stamp}`);
+    mkdirSync(backupRoot, { recursive: true });
+    cpSync(legacyDir, join(backupRoot, LEGACY_ARTIFACT_DIR), { recursive: true });
+    return backupRoot;
+}
+function migrateLegacyTree(projectRoot, legacyDir) {
+    const migratedDir = join(projectRoot, MIGRATED_ARTIFACT_DIR);
+    if (existsSync(migratedDir)) {
+        throw new Error(`refusing to migrate: '${MIGRATED_ARTIFACT_DIR}/' already exists alongside '${LEGACY_ARTIFACT_DIR}/'`);
+    }
+    const backupDir = backupLegacyTree(projectRoot, legacyDir);
+    const stagedDir = join(projectRoot, `.${MIGRATED_ARTIFACT_DIR}.migrate-staging`);
+    if (existsSync(stagedDir)) {
+        rmSync(stagedDir, { recursive: true, force: true });
+    }
+    mkdirSync(stagedDir, { recursive: true });
+    const files = collectFiles(legacyDir);
+    try {
+        for (const srcPath of files) {
+            const rel = relative(legacyDir, srcPath);
+            const destPath = join(stagedDir, mapRelativePath(rel));
+            writeMigratedFile(srcPath, destPath);
+        }
+        renameOrReplace(stagedDir, migratedDir);
+        rmSync(legacyDir, { recursive: true, force: true });
+        return { backupDir, files: files.length };
+    }
+    catch (err) {
+        rmSync(stagedDir, { recursive: true, force: true });
+        throw err;
+    }
+}
+function renameOrReplace(src, dest) {
+    if (existsSync(dest)) {
+        rmSync(dest, { recursive: true, force: true });
+    }
+    cpSync(src, dest, { recursive: true });
+    rmSync(src, { recursive: true, force: true });
+}
+function runAgentsRefresh(projectRoot, frameworkRoot, io) {
+    const plan = agentsRefreshPlan(projectRoot, { frameworkRoot });
+    const state = String(plan.state ?? "unknown");
+    if (state === "current") {
+        io.writeOut("AGENTS.md managed section is current — no changes.\n");
+        return 0;
+    }
+    if (state === "template-missing" || state === "template-malformed" || state === "unreadable") {
+        io.writeErr(`agents:refresh failed: ${state}\n`);
+        return 2;
+    }
+    const newContent = plan.new_content;
+    if (typeof newContent !== "string") {
+        io.writeErr("agents:refresh failed: plan produced no new_content\n");
+        return 2;
+    }
+    const path = String(plan.path ?? join(projectRoot, "AGENTS.md"));
+    writeFileSync(path, newContent, "utf8");
+    io.writeOut(`AGENTS.md updated (state=${state}).\n`);
+    return 0;
+}
+/** Core orchestrator for the consumer xbrief rename (#2110). */
+export function runXbriefMigration(args, _io) {
+    const projectRoot = resolve(args.projectRoot);
+    const detection = detectLegacyVbriefLayout(projectRoot);
+    if (!detection.legacyLayout) {
+        return {
+            kind: "noop",
+            message: "Project is already on the xbrief layout — nothing to migrate.",
+        };
+    }
+    const legacyDir = join(projectRoot, LEGACY_ARTIFACT_DIR);
+    if (!isDirectory(legacyDir)) {
+        return {
+            kind: "config",
+            message: `Legacy markers detected but '${LEGACY_ARTIFACT_DIR}/' directory is missing.`,
+        };
+    }
+    if (!args.force) {
+        const git = checkGitClean(projectRoot);
+        if (git.status === "WARN") {
+            return {
+                kind: "refused",
+                message: `${git.message} ${xbriefMigrationGuidance()} Pass --force to override.`,
+            };
+        }
+    }
+    try {
+        const { backupDir, files } = migrateLegacyTree(projectRoot, legacyDir);
+        return { kind: "migrated", backupDir, files };
+    }
+    catch (err) {
+        return {
+            kind: "config",
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/** Map a migration outcome to a process exit code and emit operator guidance. */
+export function emitXbriefMigration(outcome, io, options = {}) {
+    if (options.signpostOnly) {
+        const root = options.projectRoot ?? process.cwd();
+        io.writeOut(`${renderXbriefMigrationLine(root)}\n`);
+        return 0;
+    }
+    switch (outcome.kind) {
+        case "noop":
+            io.writeOut(`${outcome.message}\n`);
+            return 0;
+        case "refused":
+            io.writeErr(`migrate:xbrief refused: ${outcome.message}\n`);
+            return 1;
+        case "config":
+            io.writeErr(`migrate:xbrief: ${outcome.message}\n`);
+            return 2;
+        case "migrated":
+            io.writeOut(`Migrated ${outcome.files} file(s) from ${LEGACY_ARTIFACT_DIR}/ to ${MIGRATED_ARTIFACT_DIR}/.\n` +
+                `Backup written to ${outcome.backupDir}.\n`);
+            return 0;
+        default: {
+            const _exhaustive = outcome;
+            return _exhaustive;
+        }
+    }
+}
+/** End-to-end migrate:xbrief handler including optional agents:refresh (#2110). */
+export function runXbriefMigrationCli(args, io) {
+    const outcome = runXbriefMigration(args, io);
+    const code = emitXbriefMigration(outcome, io);
+    if (code !== 0 || outcome.kind !== "migrated") {
+        return code;
+    }
+    return runAgentsRefresh(resolve(args.projectRoot), args.frameworkRoot, io);
+}
+//# sourceMappingURL=migrate-project.js.map

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

@@ -0,0 +1,5 @@
+/** Operator guidance for the TS-native xbrief rename (#2034 / #2110). */
+export declare function xbriefMigrationGuidance(): string;
+/** One-line doctor / ritual signpost mirroring `renderPrecutoverLine` (#2110). */
+export declare function renderXbriefMigrationLine(projectRoot: string): string;
+//# sourceMappingURL=signpost.d.ts.map

package/dist/xbrief-migrate/signpost.js

@@ -0,0 +1,19 @@
+import { detectLegacyVbriefLayout } from "./detect.js";
+/** Operator guidance for the TS-native xbrief rename (#2034 / #2110). */
+export function xbriefMigrationGuidance() {
+    return "Run `deft migrate:xbrief` (or `task migrate:xbrief`) to convert vbrief/ to xbrief/ safely.";
+}
+/** One-line doctor / ritual signpost mirroring `renderPrecutoverLine` (#2110). */
+export function renderXbriefMigrationLine(projectRoot) {
+    const { legacyLayout, reasons } = detectLegacyVbriefLayout(projectRoot);
+    if (!legacyLayout) {
+        return "xBrief migration: none -- project is on the xbrief layout.";
+    }
+    const maxReasons = 3;
+    const shown = reasons.slice(0, maxReasons);
+    const remainder = reasons.length - shown.length;
+    const summary = shown.join("; ").replace(/\r?\n/g, " ");
+    const tail = remainder > 0 ? `${summary}; …and ${remainder} more marker(s)` : summary;
+    return `xBrief migration: legacy vbrief layout detected -- ${tail}. ${xbriefMigrationGuidance()}`;
+}
+//# sourceMappingURL=signpost.js.map

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

@@ -0,0 +1,46 @@
+export type JsonObject = Record<string, unknown>;
+export type JsonValue = string | number | boolean | null | JsonObject | JsonValue[];
+export declare class TransformError extends Error {
+    constructor(message: string);
+}
+export declare class FeatureEmissionRejectedError extends Error {
+    constructor(message: string);
+}
+export declare class SplitLayoutRejectedError extends Error {
+    constructor(message: string);
+}
+/** Return the artifact's declared `*BRIEFInfo.version`, if present. */
+export declare function readDeclaredArtifactVersion(artifact: JsonObject): string | null;
+/** Rewrite embedded path and reference tokens inside a string (idempotent). */
+export declare function rewriteEmbeddedTokens(value: string): string;
+/**
+ * Convert a single v0.6 in-document artifact to v0.8 semantics.
+ * Idempotent: v0.8 artifacts are returned unchanged (deep-cloned).
+ * Transactional: on failure the original input object is not mutated.
+ */
+export declare function transformArtifactV06ToV08(input: JsonObject): JsonObject;
+/**
+ * Apply `transformArtifactV06ToV08` inside a try/catch boundary.
+ * On error, returns the original artifact reference unchanged.
+ */
+export declare function transformArtifactV06ToV08Transactional(input: JsonObject): {
+    ok: true;
+    artifact: JsonObject;
+    changed: boolean;
+} | {
+    ok: false;
+    artifact: JsonObject;
+    error: string;
+};
+/**
+ * Locked rule #1 (#2034): refuse v0.8-only constructs unless the artifact declares v0.8.
+ * Fail closed when the version block is missing or unreadable.
+ */
+export declare function assertFeatureEmissionAllowed(targetArtifact: JsonObject, emission: JsonObject): void;
+/** Map a desired migrated-relative path to the legacy tree when required. */
+export declare function resolveLayoutAwareRelativePath(legacyLayout: boolean, relativePath: string): string;
+/**
+ * Locked rule #2 (#2034): never target `xbrief/` when the project still uses `vbrief/`.
+ */
+export declare function assertLayoutAwareWritePath(projectRoot: string, relativePath: string, legacyLayout: boolean): string;
+//# sourceMappingURL=transforms.d.ts.map