@deftai/directive-core 0.65.0 → 0.66.1

package/dist/architecture/sor-preflight.js

@@ -15,6 +15,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { basename, extname, join, resolve } from "node:path";
+import { hasArtifactSuffix, LIFECYCLE_DIR_NAMES } from "../layout/resolve.js";
 // ---------------------------------------------------------------------------
 // Classification constants
 // ---------------------------------------------------------------------------
@@ -699,11 +700,12 @@ export function scanDiff(diffText) {
 function changedStoryRecords(projectRoot, changedPaths) {
     const records = [];
     for (const rel of changedPaths) {
-        if (!rel.endsWith(".vbrief.json"))
+        if (!hasArtifactSuffix(rel))
             continue;
-        if (!rel.startsWith("vbrief/active/") &&
-            !rel.startsWith("vbrief/pending/") &&
-            !rel.startsWith("vbrief/proposed/"))
+        const inStoryFolder = LIFECYCLE_DIR_NAMES.some((dir) => rel.startsWith(`${dir}/active/`) ||
+            rel.startsWith(`${dir}/pending/`) ||
+            rel.startsWith(`${dir}/proposed/`));
+        if (!inStoryFolder)
             continue;
         const path = join(resolve(projectRoot), rel);
         const [payload, error] = loadJsonFile(path);

package/dist/capacity/backfill.js

@@ -1,7 +1,9 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { referenceTypeMatches } from "@deftai/directive-types";
 import { sortedStringifyCompact } from "../codebase/json.js";
+import { hasArtifactSuffix, resolveLifecycleFolder } from "../layout/resolve.js";
 import { classifyBucket, loadBucketMatchers, resolveCapacityAllocation, SOURCE_MATCH, } from "../policy/capacity.js";
 export const COMPLETED_FOLDER = "completed";
 export const CACHE_RELPATH = [".deft-cache", "github-issue"];
@@ -32,7 +34,7 @@ export function extractIssueRef(plan) {
             continue;
         }
         const rec = ref;
-        if (rec.type !== "x-vbrief/github-issue") {
+        if (!referenceTypeMatches(String(rec.type ?? ""), "github-issue")) {
             continue;
         }
         const uri = rec.uri;
@@ -186,14 +188,14 @@ export async function backfill(projectRoot, options = {}) {
         result.exit_code = 2;
         return result;
     }
-    const completedDir = join(resolve(projectRoot), "vbrief", COMPLETED_FOLDER);
+    const completedDir = resolveLifecycleFolder(projectRoot, COMPLETED_FOLDER);
     if (!existsSync(completedDir)) {
         return result;
     }
     let paths;
     try {
         paths = readdirSync(completedDir)
-            .filter((name) => name.endsWith(".vbrief.json"))
+            .filter((name) => hasArtifactSuffix(name))
             .sort();
     }
     catch {

package/dist/capacity/show.js

@@ -1,5 +1,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { referenceTypeMatches } from "@deftai/directive-types";
+import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { recommendAutonomyLevel, resolveAutonomy } from "../policy/autonomy.js";
 import { CAPACITY_UNIT_COST, DEFAULT_CAPACITY_UNIT, resolveCapacityAllocation, } from "../policy/capacity.js";
 import { DEFAULT_PENDING_DECISIONS_THRESHOLD, pendingDecisionsNudgeLine, summarizeDecisionBacklog, } from "../policy/decisions.js";
@@ -25,7 +27,7 @@ function planHasChildren(plan) {
     }
     return refs.some((ref) => typeof ref === "object" &&
         ref !== null &&
-        ref.type === "x-vbrief/plan");
+        referenceTypeMatches(String(ref.type ?? ""), "plan"));
 }
 function coerceCost(value) {
     if (typeof value === "boolean") {
@@ -109,7 +111,7 @@ export function iterVbriefPlans(vbriefRoot) {
             continue;
         }
         for (const name of names.sort()) {
-            if (!name.endsWith(".vbrief.json")) {
+            if (!hasArtifactSuffix(name)) {
                 continue;
             }
             const child = join(folderPath, name);
@@ -158,7 +160,7 @@ function resolveEffectiveUnit(unitRequested, costEligible, costWithActual) {
 export function computeReport(projectRoot, options = {}) {
     const now = options.now ?? new Date();
     const allocation = options.allocation ?? resolveCapacityAllocation(projectRoot);
-    const vbriefRoot = join(resolve(projectRoot), "vbrief");
+    const vbriefRoot = resolveLifecycleRoot(projectRoot);
     const records = iterVbriefPlans(vbriefRoot).map(([folder, plan]) => classifyRecord(plan, folder, allocation, now));
     const tallies = new Map();
     for (const bucket of allocation.buckets) {

package/dist/category-b-namespace/index.d.ts

@@ -0,0 +1,39 @@
+type JsonObject = Record<string, unknown>;
+export interface CategoryBKeyRename {
+    readonly legacyKey: string;
+    readonly namespacedKey: string;
+}
+/** The locked Category B renames (#1650): directive's own config, not xbrief data. */
+export declare const CATEGORY_B_KEY_RENAMES: readonly CategoryBKeyRename[];
+/** Raised when both the bare and namespaced form of a Category B key exist. */
+export declare class CategoryBConflictError extends Error {
+    constructor(legacyKey: string, namespacedKey: string);
+}
+export interface NamespaceResult {
+    readonly doc: JsonObject;
+    readonly changed: boolean;
+    readonly renamedKeys: readonly string[];
+}
+/**
+ * Idempotently rename Category B bare plan keys to their namespaced form.
+ * Mutates and returns the supplied document. Throws {@link CategoryBConflictError}
+ * when a plan carries both the bare and namespaced form of the same key.
+ */
+export declare function namespaceCategoryBPlan(doc: unknown): NamespaceResult;
+export interface CorpusMigrationConflict {
+    readonly path: string;
+    readonly message: string;
+}
+export interface CorpusMigrationResult {
+    readonly scanned: number;
+    readonly changed: readonly string[];
+    readonly conflicts: readonly CorpusMigrationConflict[];
+}
+/**
+ * Walk `vbrief/**\/*.vbrief.json` under projectRoot and namespace every
+ * Category B key in place. Idempotent: a second run reports zero changes.
+ * Files with a bare/namespaced conflict are reported, not rewritten.
+ */
+export declare function migrateCategoryBCorpus(projectRoot: string): CorpusMigrationResult;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/category-b-namespace/index.js

@@ -0,0 +1,120 @@
+/**
+ * Category B corpus codemod (#1650 / #2034).
+ *
+ * Renames the two grandfathered bare directive-config plan keys (`policy`,
+ * `completedNote`) to their `x-directive/` namespaced form across the vBRIEF
+ * corpus so the #1620 conformance gate can drop its temporary ALLOW_LIST.
+ *
+ * The transform is idempotent (already-namespaced artifacts are unchanged) and
+ * order-preserving (the namespaced key takes the legacy key's slot, keeping
+ * artifact diffs minimal).
+ */
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
+import { LEGACY_PLAN_COMPLETED_NOTE_KEY, LEGACY_PLAN_POLICY_KEY, PLAN_COMPLETED_NOTE_KEY, PLAN_POLICY_KEY, } from "../policy/plan-extensions.js";
+/** The locked Category B renames (#1650): directive's own config, not xbrief data. */
+export const CATEGORY_B_KEY_RENAMES = [
+    { legacyKey: LEGACY_PLAN_POLICY_KEY, namespacedKey: PLAN_POLICY_KEY },
+    { legacyKey: LEGACY_PLAN_COMPLETED_NOTE_KEY, namespacedKey: PLAN_COMPLETED_NOTE_KEY },
+];
+/** Raised when both the bare and namespaced form of a Category B key exist. */
+export class CategoryBConflictError extends Error {
+    constructor(legacyKey, namespacedKey) {
+        super(`plan has both bare '${legacyKey}' and namespaced '${namespacedKey}' -- ` +
+            "resolve the conflict by hand before migrating.");
+        this.name = "CategoryBConflictError";
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Idempotently rename Category B bare plan keys to their namespaced form.
+ * Mutates and returns the supplied document. Throws {@link CategoryBConflictError}
+ * when a plan carries both the bare and namespaced form of the same key.
+ */
+export function namespaceCategoryBPlan(doc) {
+    if (!isPlainObject(doc)) {
+        return { doc: doc, changed: false, renamedKeys: [] };
+    }
+    const plan = doc.plan;
+    if (!isPlainObject(plan)) {
+        return { doc, changed: false, renamedKeys: [] };
+    }
+    const renames = CATEGORY_B_KEY_RENAMES.filter((rename) => rename.legacyKey in plan);
+    if (renames.length === 0) {
+        return { doc, changed: false, renamedKeys: [] };
+    }
+    for (const { legacyKey, namespacedKey } of renames) {
+        if (namespacedKey in plan) {
+            throw new CategoryBConflictError(legacyKey, namespacedKey);
+        }
+    }
+    const renameMap = new Map(renames.map((r) => [r.legacyKey, r.namespacedKey]));
+    const rebuilt = {};
+    for (const [key, value] of Object.entries(plan)) {
+        rebuilt[renameMap.get(key) ?? key] = value;
+    }
+    doc.plan = rebuilt;
+    return { doc, changed: true, renamedKeys: renames.map((r) => r.namespacedKey) };
+}
+function collectVbriefFiles(dir, acc = []) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return acc;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            collectVbriefFiles(full, acc);
+        }
+        else if (entry.isFile() && hasArtifactSuffix(entry.name)) {
+            acc.push(full);
+        }
+    }
+    return acc;
+}
+/**
+ * Walk `vbrief/**\/*.vbrief.json` under projectRoot and namespace every
+ * Category B key in place. Idempotent: a second run reports zero changes.
+ * Files with a bare/namespaced conflict are reported, not rewritten.
+ */
+export function migrateCategoryBCorpus(projectRoot) {
+    const root = resolve(projectRoot);
+    const vbriefDir = resolveLifecycleRoot(root);
+    let scanned = 0;
+    const changed = [];
+    const conflicts = [];
+    for (const file of collectVbriefFiles(vbriefDir)) {
+        if (!statSync(file).isFile()) {
+            continue;
+        }
+        scanned += 1;
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        const relPath = relative(root, file).replace(/\\/g, "/");
+        let result;
+        try {
+            result = namespaceCategoryBPlan(parsed);
+        }
+        catch (err) {
+            conflicts.push({ path: relPath, message: err instanceof Error ? err.message : String(err) });
+            continue;
+        }
+        if (result.changed) {
+            writeFileSync(file, `${JSON.stringify(result.doc, null, 2)}\n`, "utf8");
+            changed.push(relPath);
+        }
+    }
+    return { scanned, changed: changed.sort(), conflicts };
+}
+//# sourceMappingURL=index.js.map

package/dist/codebase/default-extractor.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, globSync, readdirSync, readFileSync, realpathSync, statSync, } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
+import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { extractCodeStructure, loadJsonFile } from "../verify-source/code-structure-validate.js";
 import { sortedStringifyPretty } from "./json.js";
 import { CODEBASE_MAP_FORMAT_VERSION, CODEBASE_MAP_KIND, CODEBASE_PROVIDER_CONTRACT_VERSION, } from "./projection-registry.js";
@@ -100,7 +101,7 @@ function sourcePathRel(projectRoot, sourcePath) {
 }
 /** Return the authored codeStructure source path used by the default extractor. */
 export function defaultCodeStructurePath(projectRoot, codeStructurePath) {
-    return codeStructurePath ?? join(projectRoot, "vbrief", "PROJECT-DEFINITION.vbrief.json");
+    return codeStructurePath ?? resolveProjectDefinitionPath(projectRoot);
 }
 function stableId(value) {
     let slug = "";

package/dist/codebase/map.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { extractCodeStructure, loadJsonFile } from "../verify-source/code-structure-validate.js";
 import { CodeStructureConfigError, configErrorToDict, defaultCodeStructurePath, } from "./default-extractor.js";
 import { sortedStringifyPretty } from "./json.js";
@@ -73,7 +74,7 @@ export function projectionOutputPath(projectRoot, explicitOutput) {
     if (explicitOutput !== undefined && explicitOutput !== null && explicitOutput.length > 0) {
         return explicitOutput;
     }
-    const projectDefinition = join(projectRoot, "vbrief", "PROJECT-DEFINITION.vbrief.json");
+    const projectDefinition = resolveProjectDefinitionPath(projectRoot);
     if (!existsSync(projectDefinition)) {
         return DEFAULT_OUTPUT_PATH;
     }

package/dist/codebase/provider.js

@@ -4,6 +4,8 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join, posix, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { contentRoot } from "../content-root.js";
+import { resolveProjectDefinitionPath } from "../layout/resolve.js";
+import { readPlanPolicy } from "../policy/plan-extensions.js";
 import { loadJsonFile } from "../verify-source/code-structure-validate.js";
 import { CODEBASE_MAP_SCHEMA_PATH } from "./constants.js";
 import { buildCodebaseMap, CodeStructureConfigError, configErrorToDict, defaultCodeStructurePath, fileSha256, } from "./default-extractor.js";
@@ -254,7 +256,7 @@ function isSafeRelativePath(value) {
     return !text.split("/").includes("..");
 }
 function projectDefinitionPath(projectRoot) {
-    return join(projectRoot, "vbrief", "PROJECT-DEFINITION.vbrief.json");
+    return resolveProjectDefinitionPath(projectRoot);
 }
 function expectValue(expect, ...keys) {
     if (typeof expect !== "object" || expect === null || Array.isArray(expect)) {
@@ -282,7 +284,7 @@ export function loadProviderArtifactPolicy(projectRoot, kind = CODEBASE_MAP_KIND
     if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
         return providerArtifactPolicyEmpty();
     }
-    const policy = plan.policy;
+    const policy = readPlanPolicy(plan);
     if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
         return providerArtifactPolicyEmpty();
     }

package/dist/content-contracts/standards/_helpers.js

@@ -70,7 +70,7 @@ const SKIP_DIRS = new Set([
     // broke CI when dependency versions drifted (#1993 follow-up).
     "node_modules",
 ]);
-const MIGRATION_ARTIFACT_TREES = ["vbrief/migration"];
+const MIGRATION_ARTIFACT_TREES = ["xbrief/migration", "vbrief/migration"];
 export function isMigrationArtifact(rel) {
     if (MIGRATION_ARTIFACT_TREES.some((t) => rel.startsWith(`${t}/`))) {
         return true;

package/dist/doctor/checks.js

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 import { detectLegacyLayout, legacyLayoutSignpostLine, } from "../init-deposit/legacy-detect.js";
 import { detectCanonicalVendoredManifest, isNpmManaged, NPM_MANAGED_SENTINEL_KEY, NPM_MANAGED_SENTINEL_VALUE, } from "../init-deposit/migrate.js";
+import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { findSkillPathsInText } from "../text/redos-safe.js";
 import { CANONICAL_UPGRADE_COMMAND, GO_BRIDGE_RELEASES_URL, UPGRADING_DOC_URL, } from "./constants.js";
 import { isDeprecationRedirectStub, locateManifest, manifestCandidatePaths, manifestTagToVersion, parseInstallManifest, parseInstallRootFromAgentsMd, parseManifest, } from "./manifest.js";
@@ -127,7 +128,7 @@ export function checkManifestAgreement(projectRoot, installRoot, seams = {}) {
     const manifestPath = locateManifest(projectRoot, installRoot, isFile);
     const expectedManifestPath = manifestPath ?? manifestCandidatePaths(projectRoot, installRoot)[0];
     const bareCandidates = [
-        join(projectRoot, "vbrief", ".deft-version"),
+        join(resolveLifecycleRoot(projectRoot), ".deft-version"),
         join(projectRoot, ".deft-version"),
     ];
     const barePath = bareCandidates.find((p) => isFile(p)) ?? null;

package/dist/doctor/doctor-state.js

@@ -1,7 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { resolveEvalPath } from "../layout/resolve.js";
 import { CLEAN_WINDOW_HOURS, DIRTY_WINDOW_HOURS, ENV_STATE_PATH } from "./constants.js";
-const STATE_PARENT = join("vbrief", ".eval");
 const STATE_FILENAME = "doctor-state.json";
 export function statePath(projectRoot) {
     const override = process.env[ENV_STATE_PATH]?.trim();
@@ -10,7 +10,7 @@ export function statePath(projectRoot) {
             ? join(process.env.HOME ?? projectRoot, override.slice(1))
             : override;
     }
-    return join(projectRoot, STATE_PARENT, STATE_FILENAME);
+    return resolveEvalPath(projectRoot, STATE_FILENAME);
 }
 function parseIso(ts) {
     if (typeof ts !== "string" || !ts) {

package/dist/encoding/patterns.js

@@ -78,6 +78,25 @@ export const SCANNABLE_EXTENSIONS = new Set([
  * POSIX form. Ported verbatim from the Python `BUILTIN_ALLOW_LIST`.
  */
 export const BUILTIN_ALLOW_LIST = [
+    // Migrated xbrief/ layout (#2109). The #798 vBRIEF legitimately carries
+    // mojibake byte sequences as its subject matter; keep it allow-listed under
+    // the canonical layout.
+    "xbrief/active/*-798-*.xbrief.json",
+    "xbrief/completed/*-798-*.xbrief.json",
+    "xbrief/cancelled/*-798-*.xbrief.json",
+    "xbrief/pending/*-798-*.xbrief.json",
+    "xbrief/proposed/*-798-*.xbrief.json",
+    ".deft/core/xbrief/active/*-798-*.xbrief.json",
+    ".deft/core/xbrief/completed/*-798-*.xbrief.json",
+    ".deft/core/xbrief/cancelled/*-798-*.xbrief.json",
+    ".deft/core/xbrief/pending/*-798-*.xbrief.json",
+    ".deft/core/xbrief/proposed/*-798-*.xbrief.json",
+    "deft/xbrief/active/*-798-*.xbrief.json",
+    "deft/xbrief/completed/*-798-*.xbrief.json",
+    "deft/xbrief/cancelled/*-798-*.xbrief.json",
+    "deft/xbrief/pending/*-798-*.xbrief.json",
+    "deft/xbrief/proposed/*-798-*.xbrief.json",
+    // Legacy vbrief/ layout (back-compat read support; removed by #2112).
     "vbrief/active/*-798-*.vbrief.json",
     "vbrief/completed/*-798-*.vbrief.json",
     "vbrief/cancelled/*-798-*.vbrief.json",

package/dist/encoding/scan.js

@@ -1,4 +1,5 @@
 import { readFileSync } from "node:fs";
+import { hasArtifactSuffix, LIFECYCLE_DIR_NAMES } from "../layout/resolve.js";
 import { MOJIBAKE_PATTERNS, NO_BOM_EXTENSIONS, REPLACEMENT_CHAR, UTF8_BOM, VBRIEF_CONTROL_CHAR_LABELS, } from "./patterns.js";
 import { pythonSplitlines, stripMarkdownQuotes } from "./text.js";
 /** Render a finding as the Python oracle does: `  path:line [label] context`. */
@@ -95,11 +96,11 @@ export function scanFile(relPath, fullPath) {
 }
 /** Return true for in-flight vBRIEF files that may receive issue ingest. */
 export function isVbriefNarrativeControlScope(relPath) {
-    if (!relPath.endsWith(".vbrief.json")) {
+    if (!hasArtifactSuffix(relPath)) {
         return false;
     }
     const normalized = `/${relPath.replace(/\\/g, "/")}`;
-    return normalized.includes("/vbrief/proposed/") || normalized.includes("/vbrief/active/");
+    return LIFECYCLE_DIR_NAMES.some((dir) => normalized.includes(`/${dir}/proposed/`) || normalized.includes(`/${dir}/active/`));
 }
 function tabIsNonIndentation(value, index) {
     const lineStart = value.lastIndexOf("\n", index - 1) + 1;

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export * as codebase from "./codebase/index.js";
 export * as doctor from "./doctor/index.js";
 export * from "./encoding/index.js";
 export * as intake from "./intake/index.js";
+export * as layout from "./layout/index.js";
 export * as legacyBridge from "./legacy-bridge/index.js";
 export * as lifecycle from "./lifecycle/index.js";
 export * as orchestration from "./orchestration/index.js";
@@ -49,6 +50,7 @@ export * as vbriefValidation from "./vbrief-validation/index.js";
 export * as verifyEnv from "./verify-env/index.js";
 export * as verifySource from "./verify-source/index.js";
 export * as wipCap from "./wip-cap/index.js";
+export * as xbriefMigrate from "./xbrief-migrate/index.js";
 export declare const CORE_PACKAGE: "@deftai/directive-core";
 /** Returns identifying metadata for the core engine package. */
 export declare function engineInfo(): EngineInfo;

package/dist/index.js

@@ -16,6 +16,7 @@ export * as codebase from "./codebase/index.js";
 export * as doctor from "./doctor/index.js";
 export * from "./encoding/index.js";
 export * as intake from "./intake/index.js";
+export * as layout from "./layout/index.js";
 export * as legacyBridge from "./legacy-bridge/index.js";
 export * as lifecycle from "./lifecycle/index.js";
 export * as orchestration from "./orchestration/index.js";
@@ -49,6 +50,7 @@ export * as vbriefValidation from "./vbrief-validation/index.js";
 export * as verifyEnv from "./verify-env/index.js";
 export * as verifySource from "./verify-source/index.js";
 export * as wipCap from "./wip-cap/index.js";
+export * as xbriefMigrate from "./xbrief-migrate/index.js";
 export const CORE_PACKAGE = "@deftai/directive-core";
 /** Returns identifying metadata for the core engine package. */
 export function engineInfo() {

package/dist/init-deposit/refresh.js

@@ -14,6 +14,7 @@ import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
 import { readCorePackageVersion } from "../engine-version.js";
+import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { DEV_FALLBACK } from "../platform/constants.js";
 import { gitPorcelain } from "../story-ready/git.js";
 import { parseInitArgv } from "./init-deposit.js";
@@ -92,7 +93,7 @@ function syncBareVersionMarker(projectDir, version) {
     const normalized = normalizeVersion(version);
     if (!normalized || normalized === DEV_FALLBACK)
         return;
-    const vbriefDir = join(projectDir, "vbrief");
+    const vbriefDir = resolveLifecycleRoot(projectDir);
     let targetDir = projectDir;
     try {
         if (statSync(vbriefDir).isDirectory())

package/dist/init-deposit/scaffold.js

@@ -10,6 +10,7 @@ import { mkdir, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { platform } from "node:os";
 import { dirname, join, relative } from "node:path";
 import { copyTree } from "../deposit/copy-tree.js";
+import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { agentsRefreshPlan } from "../platform/agents-md.js";
 export const CANONICAL_INSTALL_ROOT = ".deft/core";
 export const CORE_GLOB = ".deft/core/**";
@@ -262,7 +263,7 @@ function vbriefLifecycleDirsPresent(consumerVbrief) {
     });
 }
 export async function writeConsumerVbrief(projectDir, deftDir, io) {
-    const consumerVbrief = join(projectDir, "vbrief");
+    const consumerVbrief = resolveLifecycleRoot(projectDir);
     const schemasDst = join(consumerVbrief, "schemas");
     const vbriefMdDst = join(consumerVbrief, "vbrief.md");
     const schemasPresent = existsSync(schemasDst) && statSync(schemasDst).isDirectory();

package/dist/install-upgrade/index.d.ts

@@ -1,6 +1,8 @@
 export interface InstallUpgradeArgs {
     readonly projectRoot: string;
     readonly frameworkRoot: string;
+    readonly migrate?: boolean;
+    readonly force?: boolean;
 }
 export interface InstallUpgradeIo {
     writeOut: (text: string) => void;

package/dist/install-upgrade/index.js

@@ -3,10 +3,12 @@ import { join, relative, resolve } from "node:path";
 import { locateManifest, manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
 import { readCorePackageVersion } from "../engine-version.js";
 import { buildInstallManifestText, CANONICAL_INSTALL_ROOT, } from "../init-deposit/scaffold.js";
+import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { agentsRefreshPlan } from "../platform/agents-md.js";
 import { DEV_FALLBACK } from "../platform/constants.js";
 import { resolveVersion } from "../platform/resolve-version.js";
 import { detectPreCutoverLegacy, frozenPreCutoverMigrationGuidance, } from "../vbrief-validate/precutover.js";
+import { detectLegacyVbriefLayout, emitXbriefMigration, isPatchOnlyUpgrade, renderXbriefMigrationLine, runXbriefMigration, } from "../xbrief-migrate/index.js";
 const ENGINE_PACKAGE_FALLBACK = "0.0.0";
 /**
  * Resolve the framework version for an upgrade (#2053).
@@ -71,7 +73,10 @@ function readManagedByAt(installRoot) {
     }
 }
 function versionMarkerPaths(projectRoot) {
-    return [join(projectRoot, "vbrief", ".deft-version"), join(projectRoot, ".deft-version")];
+    return [
+        join(resolveLifecycleRoot(projectRoot), ".deft-version"),
+        join(projectRoot, ".deft-version"),
+    ];
 }
 function readVersionMarker(projectRoot) {
     for (const candidate of versionMarkerPaths(projectRoot)) {
@@ -173,6 +178,24 @@ function runAgentsRefresh(projectRoot, frameworkRoot, io) {
     io.writeOut(`AGENTS.md updated (state=${state}).\n`);
     return 0;
 }
+function handleLegacyXbriefLayout(args, io, recorded, normalizedVersion) {
+    const detection = detectLegacyVbriefLayout(args.projectRoot);
+    if (!detection.legacyLayout) {
+        return 0;
+    }
+    io.writeOut(`${renderXbriefMigrationLine(args.projectRoot)}\n`);
+    const patchInert = isPatchOnlyUpgrade(recorded, normalizedVersion);
+    if (!args.migrate || patchInert) {
+        return 0;
+    }
+    const outcome = runXbriefMigration({
+        projectRoot: args.projectRoot,
+        frameworkRoot: args.frameworkRoot,
+        force: args.force,
+    }, io);
+    const code = emitXbriefMigration(outcome, io, { projectRoot: args.projectRoot });
+    return code;
+}
 /** Port of ``run upgrade`` / ``task install:upgrade`` for the consumer task surface (#1061 / #2022). */
 export function runInstallUpgrade(args, io) {
     const projectRoot = resolve(args.projectRoot);
@@ -189,13 +212,16 @@ export function runInstallUpgrade(args, io) {
     const recorded = readVersionMarker(projectRoot);
     if (recorded === normalizedVersion) {
         io.writeOut(`Project already at ${normalizedVersion}. Nothing to do.\n`);
+        const xbriefCode = handleLegacyXbriefLayout(args, io, recorded, normalizedVersion);
+        if (xbriefCode !== 0)
+            return xbriefCode;
         return runAgentsRefresh(projectRoot, agentsRoot, io);
     }
     const legacy = detectPreCutoverLegacy(projectRoot);
     if (legacy.length > 0) {
         io.writeOut(`Pre-v0.20 document model detected (${legacy.join(", ")}). ${frozenPreCutoverMigrationGuidance()}\n`);
     }
-    const vbriefDir = join(projectRoot, "vbrief");
+    const vbriefDir = resolveLifecycleRoot(projectRoot);
     const targetDir = existsSync(vbriefDir) && statSync(vbriefDir).isDirectory() ? vbriefDir : projectRoot;
     writeVersionMarker(targetDir, normalizedVersion);
     const writtenManifestPath = installRoot !== null
@@ -217,6 +243,9 @@ export function runInstallUpgrade(args, io) {
         io.writeOut(`Updated .deft-version from ${recorded} to ${normalizedVersion}.\n`);
     }
     io.writeOut(`If legacy SPECIFICATION.md or PROJECT.md content remains, see UPGRADING.md § Frozen pre-v0.20 document-model migration (#2068).\n`);
+    const xbriefCode = handleLegacyXbriefLayout(args, io, recorded, normalizedVersion);
+    if (xbriefCode !== 0)
+        return xbriefCode;
     return runAgentsRefresh(projectRoot, agentsRoot, io);
 }
 //# sourceMappingURL=index.js.map

package/dist/intake/issue-emit.d.ts

@@ -1,5 +1,5 @@
 import type { ScmCallFn } from "./reconcile-issues.js";
-export declare const GITHUB_ISSUE_REF_TYPE = "x-vbrief/github-issue";
+export declare const GITHUB_ISSUE_REF_TYPE = "x-xbrief/github-issue";
 export declare const EXTERNAL_TRUST_LEVEL = "external";
 export declare class IssueEmitError extends Error {
     constructor(message: string);

package/dist/intake/issue-emit.js

@@ -1,10 +1,11 @@
 import { globSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, relative, resolve } from "node:path";
+import { referenceTypeMatches } from "@deftai/directive-types";
 import { call } from "../scm/call.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
 import { resolveProjectRepo } from "../slice/project-context.js";
-export const GITHUB_ISSUE_REF_TYPE = "x-vbrief/github-issue";
+export const GITHUB_ISSUE_REF_TYPE = "x-xbrief/github-issue";
 export const EXTERNAL_TRUST_LEVEL = "external";
 const ISSUE_URL_PATTERN = /https?:\/\/\S+?\/issues\/\d+/;
 export class IssueEmitError extends Error {
@@ -44,7 +45,7 @@ export function existingGithubIssueRef(data) {
     for (const ref of refs) {
         if (ref !== null && typeof ref === "object" && !Array.isArray(ref)) {
             const obj = ref;
-            if (obj.type === GITHUB_ISSUE_REF_TYPE) {
+            if (referenceTypeMatches(String(obj.type ?? ""), "github-issue")) {
                 const uri = obj.uri ?? obj.url;
                 return typeof uri === "string" && uri.length > 0 ? uri : "";
             }