@deftai/directive-core 0.68.1 → 0.69.0

package/dist/session/session-start.js

@@ -4,6 +4,7 @@ import { MIGRATE_COMPLETION_NUDGE, shouldEmitMigrateNudge } from "../init-deposi
 import { disclosureLine } from "../policy/disclosure.js";
 import { resolvePolicy } from "../policy/resolve.js";
 import { runDefaultMode } from "../triage/welcome/default-mode.js";
+import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
 import { verifyRequiredTools } from "../verify-env/verify-tools.js";
 import { defaultGitRunner, gitHead, worktreePath } from "./git.js";
 import { newRitualStatePayload, ritualStatePath, ritualStep, writeRitualState, } from "./ritual-sentinel.js";
@@ -194,10 +195,30 @@ export function runSessionStart(projectRoot, options = {}) {
     const quickSteps = recordDeferredSteps(QUICK_STEPS, deferrals, instant);
     const gatedSteps = recordDeferredSteps(GATED_STEPS, deferrals, instant);
     const lines = [];
+    // Resolve USER.md via the shared first-hit-wins resolver so the alignment
+    // step finds preferences automatically in mismatched / headless sandboxes
+    // with zero manual DEFT_USER_PATH (#2271 / #2124). Never throws: an absent
+    // USER.md degrades to a clear diagnostic below.
+    const resolveUserMd = options.resolveUserMd ?? ((root) => resolveUserMdPath({ projectRoot: root }));
+    const userMd = resolveUserMd(projectRoot);
     if (!quickSteps.alignment) {
         const message = "Deft Directive active -- AGENTS.md loaded.";
-        quickSteps.alignment = ritualStep({ ok: true, ts: instant, message });
+        // Sanitize newlines on the data-derived path/diagnostic before they land in
+        // the ritual-step message / terminal output (matches doctor's CWE-116
+        // handling); DEFT_USER_PATH is only trimmed, so an embedded newline could
+        // otherwise survive into multi-line output.
+        const safePath = userMd.path.replace(/\r?\n/g, " ");
+        const safeDiagnostic = userMd.diagnostic.replace(/\r?\n/g, " ");
+        const userMdLine = userMd.found
+            ? `USER.md resolved (${userMd.rung}): ${safePath}`
+            : safeDiagnostic;
+        quickSteps.alignment = ritualStep({
+            ok: true,
+            ts: instant,
+            message: `${message} ${userMdLine}`,
+        });
         lines.push(message);
+        lines.push(userMdLine);
     }
     if (!quickSteps.branch_policy) {
         const result = resolvePolicy(projectRoot);
@@ -287,6 +308,12 @@ export function runSessionStart(projectRoot, options = {}) {
         state_path: statePath,
         quick_steps: quickSteps,
         gated_steps: gatedSteps,
+        user_md: {
+            path: userMd.path,
+            rung: userMd.rung,
+            found: userMd.found,
+            diagnostic: userMd.diagnostic,
+        },
         message: code === 0 ? "session ritual recorded" : "session ritual failed",
     };
     return { code, payload: resultPayload, lines };

package/dist/user-config/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./resolve-user-md.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/user-config/index.js

@@ -0,0 +1,2 @@
+export * from "./resolve-user-md.js";
+//# sourceMappingURL=index.js.map

package/dist/user-config/resolve-user-md.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared USER.md resolver (#2271).
+ *
+ * Resolves the USER.md user-config file across an explicit first-hit-wins
+ * search order so session-start, the CLI bootstrap, and doctor all share a
+ * single source of truth for "where does USER.md live?" — and so it resolves
+ * automatically in mismatched / headless sandboxes where `$HOME` is not a
+ * persistent mount (the #2124 Cowork gap) with zero manual `DEFT_USER_PATH`.
+ *
+ * Search order (first hit wins):
+ *   1. `DEFT_USER_PATH` — explicit override, highest precedence, points at the
+ *      USER.md file directly. Always wins as the resolved path whether or not
+ *      the file exists yet (presence is reported separately via `found`).
+ *   2. Workspace-local bridged config (`<projectRoot>/.deft/USER.md`) — a
+ *      persistent location inside the workspace that survives a non-persistent
+ *      `$HOME`.
+ *   3. Bridged platform config dir (`%APPDATA%\deft\USER.md` on Windows,
+ *      `~/.config/deft/USER.md` elsewhere) — the historical default location.
+ *   4. Sensible default (the rung-3 path) + a `no USER.md found; using
+ *      defaults` diagnostic. This branch NEVER throws.
+ */
+/** Exact diagnostic phrase emitted when USER.md is absent on every rung. */
+export declare const NO_USER_MD_DIAGNOSTIC = "no USER.md found; using defaults";
+/** The USER.md filename joined onto every candidate config directory. */
+export declare const USER_MD_FILENAME = "USER.md";
+/**
+ * Workspace-local config directory (relative to the project root). This is the
+ * bridged, persistent location inside the workspace that keeps preferences
+ * reachable even when the platform config dir under `$HOME` is not mounted.
+ */
+export declare const WORKSPACE_LOCAL_CONFIG_DIR = ".deft";
+/** Which search rung produced the resolved path. */
+export type UserMdRung = "env-override" | "workspace-local" | "platform-config" | "default";
+export interface ResolveUserMdResult {
+    /**
+     * The resolved USER.md path. For rungs 2-3 this is always an existing file.
+     * For rung 1 (`env-override`) it is the override path whether or not the file
+     * exists yet (check `found`). For the `default` rung it is the sensible
+     * default location (which does not exist).
+     */
+    readonly path: string;
+    /** Which search rung matched. */
+    readonly rung: UserMdRung;
+    /** True when a USER.md file actually exists at `path`. */
+    readonly found: boolean;
+    /** One-line human-readable diagnostic describing the resolution boundary. */
+    readonly diagnostic: string;
+    /** Candidate paths inspected, in search order (for diagnostics / tests). */
+    readonly searched: readonly string[];
+}
+export interface ResolveUserMdOptions {
+    /** Workspace root for the workspace-local rung. Defaults to `process.cwd()`. */
+    readonly projectRoot?: string;
+    /** Environment source (reads `DEFT_USER_PATH` / `APPDATA`). Defaults to `process.env`. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Platform id for the platform-config rung. Defaults to `process.platform`. */
+    readonly platform?: NodeJS.Platform;
+    /** Home directory for the platform-config rung. Defaults to `os.homedir()`. */
+    readonly homeDir?: string;
+    /** File-existence probe. Defaults to an `existsSync` + `isFile` check. */
+    readonly fileExists?: (path: string) => boolean;
+}
+/**
+ * Resolve the platform config directory (`%APPDATA%\deft` / `~/.config/deft`).
+ * Mirrors `init-deposit`'s `userConfigDir()` platform branch but takes the
+ * platform / env / home as injectable inputs and deliberately does NOT honor
+ * `DEFT_USER_PATH` — that override is rung 1, handled by the caller.
+ */
+export declare function platformUserConfigDir(platform: NodeJS.Platform, env: NodeJS.ProcessEnv, homeDir: string): string;
+/**
+ * Resolve the USER.md path across the first-hit-wins search order. Never
+ * throws: an absent USER.md degrades to the sensible default location with a
+ * clear `no USER.md found; using defaults` diagnostic.
+ */
+export declare function resolveUserMdPath(options?: ResolveUserMdOptions): ResolveUserMdResult;
+//# sourceMappingURL=resolve-user-md.d.ts.map

package/dist/user-config/resolve-user-md.js

@@ -0,0 +1,120 @@
+/**
+ * Shared USER.md resolver (#2271).
+ *
+ * Resolves the USER.md user-config file across an explicit first-hit-wins
+ * search order so session-start, the CLI bootstrap, and doctor all share a
+ * single source of truth for "where does USER.md live?" — and so it resolves
+ * automatically in mismatched / headless sandboxes where `$HOME` is not a
+ * persistent mount (the #2124 Cowork gap) with zero manual `DEFT_USER_PATH`.
+ *
+ * Search order (first hit wins):
+ *   1. `DEFT_USER_PATH` — explicit override, highest precedence, points at the
+ *      USER.md file directly. Always wins as the resolved path whether or not
+ *      the file exists yet (presence is reported separately via `found`).
+ *   2. Workspace-local bridged config (`<projectRoot>/.deft/USER.md`) — a
+ *      persistent location inside the workspace that survives a non-persistent
+ *      `$HOME`.
+ *   3. Bridged platform config dir (`%APPDATA%\deft\USER.md` on Windows,
+ *      `~/.config/deft/USER.md` elsewhere) — the historical default location.
+ *   4. Sensible default (the rung-3 path) + a `no USER.md found; using
+ *      defaults` diagnostic. This branch NEVER throws.
+ */
+import { statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+/** Exact diagnostic phrase emitted when USER.md is absent on every rung. */
+export const NO_USER_MD_DIAGNOSTIC = "no USER.md found; using defaults";
+/** The USER.md filename joined onto every candidate config directory. */
+export const USER_MD_FILENAME = "USER.md";
+/**
+ * Workspace-local config directory (relative to the project root). This is the
+ * bridged, persistent location inside the workspace that keeps preferences
+ * reachable even when the platform config dir under `$HOME` is not mounted.
+ */
+export const WORKSPACE_LOCAL_CONFIG_DIR = ".deft";
+function defaultFileExists(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        // Any stat error (ENOENT, permission, ...) means "not a resolvable USER.md
+        // file". Deliberately NOT falling back to existsSync, which cannot tell a
+        // directory from a file and would report a dir at this path as a found file.
+        return false;
+    }
+}
+/**
+ * Resolve the platform config directory (`%APPDATA%\deft` / `~/.config/deft`).
+ * Mirrors `init-deposit`'s `userConfigDir()` platform branch but takes the
+ * platform / env / home as injectable inputs and deliberately does NOT honor
+ * `DEFT_USER_PATH` — that override is rung 1, handled by the caller.
+ */
+export function platformUserConfigDir(platform, env, homeDir) {
+    if (platform === "win32") {
+        const appData = env.APPDATA?.trim();
+        return appData ? join(appData, "deft") : join(homeDir, "AppData", "Roaming", "deft");
+    }
+    return join(homeDir, ".config", "deft");
+}
+/**
+ * Resolve the USER.md path across the first-hit-wins search order. Never
+ * throws: an absent USER.md degrades to the sensible default location with a
+ * clear `no USER.md found; using defaults` diagnostic.
+ */
+export function resolveUserMdPath(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const homeDir = options.homeDir ?? homedir();
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const fileExists = options.fileExists ?? defaultFileExists;
+    const searched = [];
+    // Rung 1: DEFT_USER_PATH override (full file path); always wins.
+    const override = env.DEFT_USER_PATH?.trim();
+    if (override) {
+        const overridePath = resolve(override);
+        searched.push(overridePath);
+        const found = fileExists(overridePath);
+        return {
+            path: overridePath,
+            rung: "env-override",
+            found,
+            diagnostic: found
+                ? `USER.md resolved from DEFT_USER_PATH: ${overridePath}`
+                : `USER.md path from DEFT_USER_PATH does not exist yet: ${overridePath}`,
+            searched,
+        };
+    }
+    // Rung 2: workspace-local bridged config.
+    const workspacePath = resolve(join(projectRoot, WORKSPACE_LOCAL_CONFIG_DIR, USER_MD_FILENAME));
+    searched.push(workspacePath);
+    if (fileExists(workspacePath)) {
+        return {
+            path: workspacePath,
+            rung: "workspace-local",
+            found: true,
+            diagnostic: `USER.md resolved from workspace-local config: ${workspacePath}`,
+            searched,
+        };
+    }
+    // Rung 3: bridged platform config dir.
+    const platformPath = join(platformUserConfigDir(platform, env, homeDir), USER_MD_FILENAME);
+    searched.push(platformPath);
+    if (fileExists(platformPath)) {
+        return {
+            path: platformPath,
+            rung: "platform-config",
+            found: true,
+            diagnostic: `USER.md resolved from platform config dir: ${platformPath}`,
+            searched,
+        };
+    }
+    // Rung 4: sensible default + diagnostic (never throws).
+    return {
+        path: platformPath,
+        rung: "default",
+        found: false,
+        diagnostic: `${NO_USER_MD_DIAGNOSTIC} (searched: ${searched.join(", ")})`,
+        searched,
+    };
+}
+//# sourceMappingURL=resolve-user-md.js.map

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

@@ -10,4 +10,14 @@ 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";
+/**
+ * Filename of the explicit deprecation marker written into a legacy `vbrief/`
+ * root that is retained for read-compatibility after convergence (#2270). Its
+ * presence is what tells `doctor` the folder is NOT an active source of truth.
+ */
+export declare const VBRIEF_DEPRECATION_MARKER_FILENAME: "DEPRECATED.md";
+/** Sentinel line identifying a deft-written `vbrief/` deprecation marker (#2270). */
+export declare const VBRIEF_DEPRECATION_MARKER_SENTINEL: "<!-- deft:vbrief-deprecated -->";
+/** Body written into the retained legacy `vbrief/` deprecation marker (#2270). */
+export declare const VBRIEF_DEPRECATION_MARKER_BODY: "<!-- deft:vbrief-deprecated -->\n# Deprecated: legacy `vbrief/` root\n\nThis project has migrated to the `xbrief/` lifecycle layout. This `vbrief/`\ndirectory is retained only for read-compatibility and is **not** an active\nsource of truth. Do not add new scope work here — use `xbrief/` instead.\n\nOnce you no longer need read-compatibility with the legacy layout, delete this\n`vbrief/` directory. Re-running `deft migrate:xbrief` re-checks convergence.\n";
 //# sourceMappingURL=constants.d.ts.map

package/dist/xbrief-migrate/constants.js

@@ -11,4 +11,23 @@ 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";
+/**
+ * Filename of the explicit deprecation marker written into a legacy `vbrief/`
+ * root that is retained for read-compatibility after convergence (#2270). Its
+ * presence is what tells `doctor` the folder is NOT an active source of truth.
+ */
+export const VBRIEF_DEPRECATION_MARKER_FILENAME = "DEPRECATED.md";
+/** Sentinel line identifying a deft-written `vbrief/` deprecation marker (#2270). */
+export const VBRIEF_DEPRECATION_MARKER_SENTINEL = "<!-- deft:vbrief-deprecated -->";
+/** Body written into the retained legacy `vbrief/` deprecation marker (#2270). */
+export const VBRIEF_DEPRECATION_MARKER_BODY = `${VBRIEF_DEPRECATION_MARKER_SENTINEL}
+# Deprecated: legacy \`vbrief/\` root
+
+This project has migrated to the \`xbrief/\` lifecycle layout. This \`vbrief/\`
+directory is retained only for read-compatibility and is **not** an active
+source of truth. Do not add new scope work here — use \`xbrief/\` instead.
+
+Once you no longer need read-compatibility with the legacy layout, delete this
+\`vbrief/\` directory. Re-running \`deft migrate:xbrief\` re-checks convergence.
+`;
 //# sourceMappingURL=constants.js.map

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

@@ -3,9 +3,43 @@ export interface LegacyVbriefLayoutDetection {
     legacyLayout: boolean;
     reasons: string[];
 }
+/**
+ * Discriminated convergence state of the `vbrief/` + `xbrief/` lifecycle roots
+ * (#2270). Distinguishes the ambiguous dual-empty-root case that `migrate:xbrief`
+ * must converge from the states that are already unambiguous.
+ *
+ * - `none` — neither root carries content (nothing to converge).
+ * - `xbrief-only` — canonical `xbrief/` with content and no `vbrief/`.
+ * - `xbrief-marker` — `vbrief/` retained behind an explicit deprecation marker.
+ * - `empty-vbrief` — a stray, fully-migrated empty `vbrief/` (the ambiguous root
+ *   to clean up: remove it, or mark it when read-compat retention is requested).
+ * - `legacy-only` — `vbrief/` holds content and there is no canonical `xbrief/`;
+ *   a full migration is required.
+ * - `dual-populated` — both roots hold content with no marker; converge by
+ *   marking the legacy tree deprecated (never destructively merged).
+ */
+export type XbriefConvergenceState = "none" | "xbrief-only" | "xbrief-marker" | "empty-vbrief" | "legacy-only" | "dual-populated";
+/** Structured convergence probe of the two lifecycle roots (#2270). */
+export interface XbriefConvergenceDetection {
+    state: XbriefConvergenceState;
+    vbriefPresent: boolean;
+    vbriefEmpty: boolean;
+    vbriefHasMarker: boolean;
+    xbriefPresent: boolean;
+    xbriefHasContent: boolean;
+}
 /**
  * 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;
+/**
+ * Classify the convergence state of the `vbrief/` and `xbrief/` lifecycle roots
+ * so the orchestrator can converge to a single unambiguous root (#2270). Unlike
+ * {@link detectLegacyVbriefLayout} (which only asks "is there anything legacy?"),
+ * this probe distinguishes the ambiguous dual-empty-root case from an already
+ * unambiguous layout, and never falls back to a `run migrate:xbrief` dead end
+ * for a `vbrief/` that is merely an empty leftover.
+ */
+export declare function detectXbriefConvergence(projectRoot: string): XbriefConvergenceDetection;
 //# sourceMappingURL=detect.d.ts.map

package/dist/xbrief-migrate/detect.js

@@ -1,6 +1,7 @@
 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";
+import { hasVbriefDeprecationMarker, isEffectivelyEmptyDir } from "./fs-helpers.js";
 function isDirectory(path) {
     try {
         return statSync(path).isDirectory();
@@ -78,4 +79,36 @@ export function detectLegacyVbriefLayout(projectRoot) {
     const reasonList = [...reasons];
     return { legacyLayout: reasonList.length > 0, reasons: reasonList };
 }
+/**
+ * Classify the convergence state of the `vbrief/` and `xbrief/` lifecycle roots
+ * so the orchestrator can converge to a single unambiguous root (#2270). Unlike
+ * {@link detectLegacyVbriefLayout} (which only asks "is there anything legacy?"),
+ * this probe distinguishes the ambiguous dual-empty-root case from an already
+ * unambiguous layout, and never falls back to a `run migrate:xbrief` dead end
+ * for a `vbrief/` that is merely an empty leftover.
+ */
+export function detectXbriefConvergence(projectRoot) {
+    const legacyDir = join(projectRoot, LEGACY_ARTIFACT_DIR);
+    const migratedDir = join(projectRoot, MIGRATED_ARTIFACT_DIR);
+    const vbriefPresent = isDirectory(legacyDir);
+    const vbriefHasMarker = vbriefPresent && hasVbriefDeprecationMarker(legacyDir);
+    const vbriefEmpty = vbriefPresent && !vbriefHasMarker && isEffectivelyEmptyDir(legacyDir);
+    const xbriefPresent = isDirectory(migratedDir);
+    const xbriefHasContent = xbriefPresent && !isEffectivelyEmptyDir(migratedDir);
+    let state;
+    if (vbriefHasMarker) {
+        state = "xbrief-marker";
+    }
+    else if (!vbriefPresent) {
+        state = xbriefHasContent ? "xbrief-only" : "none";
+    }
+    else if (vbriefEmpty) {
+        state = "empty-vbrief";
+    }
+    else {
+        // vbrief/ holds real content and carries no marker.
+        state = xbriefHasContent ? "dual-populated" : "legacy-only";
+    }
+    return { state, vbriefPresent, vbriefEmpty, vbriefHasMarker, xbriefPresent, xbriefHasContent };
+}
 //# sourceMappingURL=detect.js.map

package/dist/xbrief-migrate/fs-helpers.d.ts

@@ -1,3 +1,16 @@
 /** True when `path` exists and is a directory; false on any stat error. */
 export declare function isDirectory(path: string): boolean;
+/**
+ * True when `dir` holds no meaningful content at any depth — a "fully migrated"
+ * lifecycle root. Empty subdirectories and VCS placeholder files (`.gitkeep`,
+ * `.keep`) are ignored, so a scaffolded-but-empty `vbrief/proposed/` tree still
+ * counts as empty. A missing directory is trivially empty (#2270).
+ */
+export declare function isEffectivelyEmptyDir(dir: string): boolean;
+/**
+ * True when `dir` carries a deft-written deprecation marker identifying it as a
+ * retained-for-read-compat legacy root rather than an active source of truth
+ * (#2270). Matched on the sentinel so an unrelated `DEPRECATED.md` is ignored.
+ */
+export declare function hasVbriefDeprecationMarker(dir: string): boolean;
 //# sourceMappingURL=fs-helpers.d.ts.map

package/dist/xbrief-migrate/fs-helpers.js

@@ -1,4 +1,6 @@
-import { statSync } from "node:fs";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { VBRIEF_DEPRECATION_MARKER_FILENAME, VBRIEF_DEPRECATION_MARKER_SENTINEL, } from "./constants.js";
 /** True when `path` exists and is a directory; false on any stat error. */
 export function isDirectory(path) {
     try {
@@ -8,4 +10,47 @@ export function isDirectory(path) {
         return false;
     }
 }
+/** Placeholder files that do not count as real content when judging emptiness. */
+const PLACEHOLDER_FILES = new Set([".gitkeep", ".keep"]);
+/**
+ * True when `dir` holds no meaningful content at any depth — a "fully migrated"
+ * lifecycle root. Empty subdirectories and VCS placeholder files (`.gitkeep`,
+ * `.keep`) are ignored, so a scaffolded-but-empty `vbrief/proposed/` tree still
+ * counts as empty. A missing directory is trivially empty (#2270).
+ */
+export function isEffectivelyEmptyDir(dir) {
+    if (!isDirectory(dir)) {
+        return true;
+    }
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isFile()) {
+            if (PLACEHOLDER_FILES.has(entry.name)) {
+                continue;
+            }
+            return false;
+        }
+        // A symlink (to a file or dir) is real content: `isFile`/`isDirectory` both
+        // report false for symlink dirents, so treat it explicitly as non-empty.
+        if (entry.isSymbolicLink()) {
+            return false;
+        }
+        if (entry.isDirectory() && !isEffectivelyEmptyDir(join(dir, entry.name))) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * True when `dir` carries a deft-written deprecation marker identifying it as a
+ * retained-for-read-compat legacy root rather than an active source of truth
+ * (#2270). Matched on the sentinel so an unrelated `DEPRECATED.md` is ignored.
+ */
+export function hasVbriefDeprecationMarker(dir) {
+    try {
+        return readFileSync(join(dir, VBRIEF_DEPRECATION_MARKER_FILENAME), "utf8").includes(VBRIEF_DEPRECATION_MARKER_SENTINEL);
+    }
+    catch {
+        return false;
+    }
+}
 //# sourceMappingURL=fs-helpers.js.map

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

@@ -1,7 +1,9 @@
 export { detectStaleUnmanagedHeader, type HeaderPatchOutcome, type HeaderRewriteResult, type HeaderTokenReplacement, LEGACY_HEADER_TOKENS, patchAgentsMdHeader, renderHeaderPatchSummary, renderStaleHeaderLine, rewriteUnmanagedHeaderTokens, type StaleHeaderDetection, } from "./agents-header.js";
-export { detectLegacyVbriefLayout, type LegacyVbriefLayoutDetection, } from "./detect.js";
+export { VBRIEF_DEPRECATION_MARKER_BODY, VBRIEF_DEPRECATION_MARKER_FILENAME, VBRIEF_DEPRECATION_MARKER_SENTINEL, } from "./constants.js";
+export { detectLegacyVbriefLayout, detectXbriefConvergence, type LegacyVbriefLayoutDetection, type XbriefConvergenceDetection, type XbriefConvergenceState, } 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 { hasVbriefDeprecationMarker, isDirectory, isEffectivelyEmptyDir, } from "./fs-helpers.js";
+export { convergeLegacyVbriefRoot, emitXbriefMigration, runXbriefMigration, runXbriefMigrationCli, type VbriefConvergeAction, 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";

package/dist/xbrief-migrate/index.js

@@ -1,7 +1,9 @@
 export { detectStaleUnmanagedHeader, LEGACY_HEADER_TOKENS, patchAgentsMdHeader, renderHeaderPatchSummary, renderStaleHeaderLine, rewriteUnmanagedHeaderTokens, } from "./agents-header.js";
-export { detectLegacyVbriefLayout, } from "./detect.js";
+export { VBRIEF_DEPRECATION_MARKER_BODY, VBRIEF_DEPRECATION_MARKER_FILENAME, VBRIEF_DEPRECATION_MARKER_SENTINEL, } from "./constants.js";
+export { detectLegacyVbriefLayout, detectXbriefConvergence, } 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 { hasVbriefDeprecationMarker, isDirectory, isEffectivelyEmptyDir, } from "./fs-helpers.js";
+export { convergeLegacyVbriefRoot, 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";

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

@@ -2,11 +2,18 @@ export interface XbriefMigrationArgs {
     readonly projectRoot: string;
     readonly frameworkRoot?: string;
     readonly force?: boolean;
+    /**
+     * Retain a fully-migrated `vbrief/` for read-compatibility behind an explicit
+     * deprecation marker instead of removing it (#2270). Default: remove.
+     */
+    readonly keepLegacy?: boolean;
 }
 export interface XbriefMigrationIo {
     writeOut: (text: string) => void;
     writeErr: (text: string) => void;
 }
+/** How the legacy `vbrief/` root was converged to an unambiguous state (#2270). */
+export type VbriefConvergeAction = "removed" | "marker";
 export type XbriefMigrationOutcome = {
     readonly kind: "noop";
     readonly message: string;
@@ -17,11 +24,26 @@ export type XbriefMigrationOutcome = {
     readonly kind: "migrated";
     readonly backupDir: string;
     readonly files: number;
+} | {
+    readonly kind: "converged";
+    readonly action: VbriefConvergeAction;
+    readonly already: boolean;
+    readonly message: string;
 } | {
     readonly kind: "config";
     readonly message: string;
 };
-/** Core orchestrator for the consumer xbrief rename (#2110). */
+/**
+ * Converge a leftover legacy `vbrief/` root to an unambiguous state (#2270).
+ * An effectively-empty tree is removed by default (single canonical root); a
+ * tree with real content — or an empty tree when `retain` is requested — is
+ * kept for read-compat behind an explicit deprecation marker. Idempotent: a
+ * missing dir or an already-marked dir is a no-op.
+ */
+export declare function convergeLegacyVbriefRoot(projectRoot: string, options: {
+    retain: boolean;
+}): VbriefConvergeAction;
+/** Core orchestrator for the consumer xbrief rename (#2110) + convergence (#2270). */
 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?: {