@deftai/directive-core 0.72.0 → 0.73.1

package/dist/init-deposit/refresh.js

@@ -7,6 +7,7 @@
  *
  * Refs #1942, #1430, #1671.
  */
+import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { platform as osPlatform } from "node:os";
 import { join, resolve } from "node:path";
@@ -20,8 +21,8 @@ import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { DEV_FALLBACK } from "../platform/constants.js";
 import { checkLocalEngineIntegrity, classify, ENGINE_PACKAGE, plan, renderGlobalInstall, resolveEngine, } from "../resolution/index.js";
 import { gitPorcelain } from "../story-ready/git.js";
-import { ensureInitGitignoreLines } from "./gitignore.js";
-import { depositStagePaths, isInstallerManagedPath, printCommitGuidance } from "./hygiene.js";
+import { ensureInitGitignoreLines, isDepositTrackedInGit } from "./gitignore.js";
+import { depositStagePaths, isInstallerManagedPath, printCommitGuidance, pruneStrayDepositPaths, } from "./hygiene.js";
 import { parseInitArgv } from "./init-deposit.js";
 import { buildLegacyRefusalJson, buildLegacyRefusalMessage, detectLegacyLayout, LEGACY_LAYOUT_REFUSED_EXIT_CODE, LegacyLayoutRefusedError, } from "./legacy-detect.js";
 import { printMigrateNudgeIfNeeded } from "./migrate.js";
@@ -155,14 +156,20 @@ function syncBareVersionMarker(projectDir, version) {
     const normalized = normalizeVersion(version);
     if (!normalized || normalized === DEV_FALLBACK)
         return;
-    const vbriefDir = resolveLifecycleRoot(projectDir);
+    let vbriefDir = null;
+    try {
+        vbriefDir = resolveLifecycleRoot(projectDir);
+    }
+    catch {
+        // No xbrief/ layout present — write the root-level derivative instead.
+    }
     let targetDir = projectDir;
     try {
-        if (statSync(vbriefDir).isDirectory())
+        if (vbriefDir !== null && statSync(vbriefDir).isDirectory())
             targetDir = vbriefDir;
     }
     catch {
-        // vbrief/ absent — write the root-level derivative instead
+        // xbrief/ absent — write the root-level derivative instead
     }
     try {
         mkdirSync(targetDir, { recursive: true });
@@ -212,11 +219,12 @@ function unquoteGitPath(path) {
     }
     return path;
 }
-function porcelainStatusPaths(porcelain) {
-    const paths = [];
+function porcelainStatusEntries(porcelain) {
+    const entries = [];
     for (const line of porcelain.split("\n")) {
         if (line.length < 4)
             continue;
+        const status = line.slice(0, 2);
         let rest = line.slice(3);
         const arrow = rest.indexOf(" -> ");
         if (arrow >= 0)
@@ -224,43 +232,102 @@ function porcelainStatusPaths(porcelain) {
         const trimmed = unquoteGitPath(rest.trim());
         if (!trimmed)
             continue;
-        paths.push(trimmed.replace(/\\/g, "/"));
+        entries.push({ status, path: trimmed.replace(/\\/g, "/") });
     }
-    return paths;
+    return entries;
 }
-function classifyChangedPaths(changed) {
+function classifyChangedEntries(changed) {
     const core = [];
     const installerManaged = [];
-    for (const path of changed) {
+    for (const entry of changed) {
+        const { path } = entry;
         if (!path)
             continue;
         if (path.startsWith(".deft/core/") || path === ".deft/core") {
-            core.push(path);
+            core.push(entry);
         }
         else if (isInstallerManagedPath(path)) {
-            installerManaged.push(path);
+            installerManaged.push(entry);
         }
     }
     return { core, installerManaged };
 }
+function isCrlfNoiseCandidate(status) {
+    return status.includes("M") && /^[ M]+$/.test(status);
+}
+function normalizeGitNameList(output) {
+    return output
+        .split("\n")
+        .map((line) => line.trim().replace(/\\/g, "/"))
+        .filter(Boolean);
+}
+function gitSemanticDiffNames(projectRoot, paths) {
+    if (paths.length === 0)
+        return [];
+    try {
+        const args = ["diff", "--ignore-cr-at-eol", "--name-only", "--", ...paths];
+        const worktree = execFileSync("git", args, {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const cached = execFileSync("git", ["diff", "--cached", "--ignore-cr-at-eol", "--name-only", "--", ...paths], {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return [...new Set([...normalizeGitNameList(worktree), ...normalizeGitNameList(cached)])];
+    }
+    catch {
+        return null;
+    }
+}
 /** Framework-managed uncommitted paths after refresh (#1671). */
-export function frameworkRefreshSideEffects(projectDir, readPorcelain = gitPorcelain) {
+export function frameworkRefreshSideEffects(projectDir, options) {
+    const readPorcelain = options?.readPorcelain ?? gitPorcelain;
+    const readSemanticDiffNames = options?.readSemanticDiffNames ?? gitSemanticDiffNames;
     const porcelain = readPorcelain(projectDir);
     if (porcelain === null)
-        return [];
-    const changed = porcelainStatusPaths(porcelain);
-    const { core, installerManaged } = classifyChangedPaths(changed);
-    const files = [...core, ...installerManaged].sort();
-    return files.length > 0 ? files : [];
+        return { files: [], crlfOnlyCoreFiles: [] };
+    const changed = porcelainStatusEntries(porcelain);
+    const { core, installerManaged } = classifyChangedEntries(changed);
+    const semanticCoreNames = core.length > 0
+        ? readSemanticDiffNames(projectDir, core.map((entry) => entry.path))
+        : [];
+    const semanticCoreSet = semanticCoreNames === null ? null : new Set(semanticCoreNames);
+    const coreFiles = [];
+    const crlfOnlyCoreFiles = [];
+    for (const entry of core) {
+        if (semanticCoreSet !== null &&
+            isCrlfNoiseCandidate(entry.status) &&
+            !semanticCoreSet.has(entry.path)) {
+            crlfOnlyCoreFiles.push(entry.path);
+            continue;
+        }
+        coreFiles.push(entry.path);
+    }
+    const files = [...coreFiles, ...installerManaged.map((entry) => entry.path)].sort();
+    return { files, crlfOnlyCoreFiles: crlfOnlyCoreFiles.sort() };
 }
-export function printRefreshSideEffects(io, files) {
-    if (files.length === 0)
+export function printRefreshSideEffects(io, effects) {
+    if (effects.crlfOnlyCoreFiles.length > 0) {
+        io.printf("\nWindows line-ending note (#2118): suppressed .deft/core CRLF/LF-only noise; " +
+            "ensure .gitattributes contains `.deft/core/** text eol=lf`.\n");
+    }
+    if (effects.files.length === 0)
         return;
+    if (effects.payloadSwapped === false) {
+        io.printf("\nFramework-managed files still have semantic uncommitted changes:\n");
+        for (const file of effects.files) {
+            io.printf(`  ${file}\n`);
+        }
+        return;
+    }
     io.printf("\nAGENTS.md refresh side effects (#1671): the refresh and framework payload swap\n");
     io.printf("left these framework files with uncommitted changes -- they belong in the\n");
     io.printf("framework deposit commit (the installer stages them before printing the\n");
     io.printf("`git add` list below, so there are no post-stage stragglers):\n");
-    for (const file of files) {
+    for (const file of effects.files) {
         io.printf(`  ${file}\n`);
     }
 }
@@ -301,7 +368,8 @@ export function buildUpdateSummaryJson(result, options, updateState) {
         user_config_dir: "",
         skills_created: false,
         payload_layout: "vendored",
-        strategy: "file-swap",
+        strategy: result.strategy,
+        already_current: result.alreadyCurrent,
         dirty_tree: false,
         dirty_files: [],
         staged_paths: result.stagedPaths,
@@ -313,9 +381,12 @@ export function buildUpdateSummaryJson(result, options, updateState) {
     };
 }
 export function printUpdateComplete(result, io, updateState) {
-    io.printf("\n✓ Deft framework payload refreshed.\n\n");
+    io.printf(result.alreadyCurrent
+        ? "\nOK Deft framework payload already current.\n\n"
+        : "\nOK Deft framework payload refreshed.\n\n");
     io.printf(`  Location     : ${result.deftDir}\n`);
     io.printf(`  Content      : v${normalizeVersion(result.contentVersion)}\n`);
+    io.printf(`  Strategy     : ${result.strategy}\n`);
     if (updateState) {
         io.printf(`  State        : ${updateState}\n`);
     }
@@ -350,29 +421,49 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     const engineVersion = readEngine();
     const contentVersion = readContentPackageVersion(contentRoot, readPackageVersion);
     const versionSkewNotice = buildVersionSkewNotice(engineVersion, contentVersion, previousDepositVersion);
-    await copyContent(contentRoot, deftDir);
-    await prunePythonArtifactsFromDeposit(deftDir, projectDir, io);
-    const nowIso = seams.nowIso ?? (() => new Date().toISOString().replace(/\.\d{3}Z$/, "Z"));
-    const manifestFields = {
-        ref: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,
-        sha: "content-package",
-        tag: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,
-        installRoot: CANONICAL_INSTALL_ROOT,
-        fetchedAt: nowIso(),
-        fetchedBy: "directive-update",
-        ...(previousManagedBy ? { managedBy: previousManagedBy } : {}),
-    };
-    const writtenManifestPath = writeInstallManifest(projectDir, deftDir, manifestFields);
-    // #2064: retire a stale legacy .deft/VERSION now that the canonical
-    // .deft/core/VERSION has been rewritten (folded in from install-upgrade so no
-    // manifest behavior is lost by the redirect). Best-effort; never fatal.
-    migrateLegacyInstallManifest(projectDir, writtenManifestPath);
-    // #2055: regenerate the bare .deft-version derivative so it agrees with the
-    // freshly written manifest tag (otherwise doctor's manifest-agreement check
-    // fails and the operator must hand-edit the marker).
-    syncBareVersionMarker(projectDir, contentVersion);
+    const alreadyCurrent = previousDepositVersion !== null &&
+        normalizeVersion(previousDepositVersion) === normalizeVersion(contentVersion);
+    const strategy = alreadyCurrent ? "no-op" : "file-swap";
+    if (alreadyCurrent) {
+        io.printf("[deft update] Framework payload already current; skipping payload copy.\n");
+        migrateLegacyInstallManifest(projectDir, join(deftDir, "VERSION"));
+    }
+    else {
+        await copyContent(contentRoot, deftDir);
+        await prunePythonArtifactsFromDeposit(deftDir, projectDir, io);
+        // #2347: prune framework-source paths that the content package does not ship.
+        // The additive file-swap never removes them, causing the deposit-hygiene
+        // advisory to persist across every upgrade until manually cleaned.
+        await pruneStrayDepositPaths(deftDir, contentRoot, io);
+        const nowIso = seams.nowIso ?? (() => new Date().toISOString().replace(/\.\d{3}Z$/, "Z"));
+        const manifestFields = {
+            ref: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,
+            sha: "content-package",
+            tag: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,
+            installRoot: CANONICAL_INSTALL_ROOT,
+            fetchedAt: nowIso(),
+            fetchedBy: "directive-update",
+            ...(previousManagedBy ? { managedBy: previousManagedBy } : {}),
+        };
+        const writtenManifestPath = writeInstallManifest(projectDir, deftDir, manifestFields);
+        // #2064: retire a stale legacy .deft/VERSION now that the canonical
+        // .deft/core/VERSION has been rewritten (folded in from install-upgrade so no
+        // manifest behavior is lost by the redirect). Best-effort; never fatal.
+        migrateLegacyInstallManifest(projectDir, writtenManifestPath);
+        // #2055: regenerate the bare .deft-version derivative so it agrees with the
+        // freshly written manifest tag (otherwise doctor's manifest-agreement check
+        // fails and the operator must hand-edit the marker). No-op refreshes skip
+        // this projection because the manifest tag was not rewritten (#2118).
+        syncBareVersionMarker(projectDir, contentVersion);
+    }
     const agentsMdUpdated = writeAgentsMd(projectDir, deftDir, io);
-    await depositNeutralization(projectDir, io);
+    // #2148: the deft-core-guard CI workflow is only meaningful when the deposit
+    // is git-tracked (committed vendor layout). On an npm-managed (gitignored)
+    // deposit it creates untracked noise after every `directive update`. Probe
+    // git-tracked status once and share the result with the gitignore upkeep below.
+    const depositTracked = isDepositTrackedInGit(projectDir, seams.gitLsFiles);
+    const skipGuardWorkflow = depositTracked !== true;
+    await depositNeutralization(projectDir, io, { skipGuardWorkflow });
     // #2266: non-destructive `.gitignore` upkeep for framework-owned paths. This
     // NEVER un-tracks a committed deposit -- `ensureInitGitignoreLines` only writes
     // `.gitignore` and leaves an already-tracked `.deft/core` tracked. The
@@ -383,12 +474,27 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     if (args.nonInteractive) {
         taskfileWired = ensureTaskfile(projectDir, io);
     }
-    const { stagePaths, staged, stagedPaths } = depositStagePaths(projectDir, {
-        includeTaskfile: taskfileWired,
-    });
-    printCommitGuidance(io, stagePaths, staged);
     const readPorcelain = seams.gitPorcelain ?? gitPorcelain;
-    printRefreshSideEffects(io, frameworkRefreshSideEffects(projectDir, readPorcelain));
+    const effects = frameworkRefreshSideEffects(projectDir, {
+        readPorcelain,
+        readSemanticDiffNames: seams.gitSemanticDiffNames ?? gitSemanticDiffNames,
+    });
+    let stagedPaths = [];
+    if (!alreadyCurrent || effects.files.length > 0) {
+        const stagedResult = depositStagePaths(projectDir, {
+            includeTaskfile: taskfileWired,
+            includeCore: !alreadyCurrent,
+        });
+        stagedPaths = stagedResult.stagedPaths;
+        if (!alreadyCurrent) {
+            printCommitGuidance(io, stagedResult.stagePaths, stagedResult.staged);
+        }
+        else if (stagedResult.stagedPaths.length > 0) {
+            io.printf("\nUpdated installer-managed projections for the current framework deposit:\n");
+            io.printf(`  git add ${stagedResult.stagedPaths.join(" ")}\n`);
+        }
+    }
+    printRefreshSideEffects(io, { ...effects, payloadSwapped: !alreadyCurrent });
     if (versionSkewNotice) {
         io.printf(`${versionSkewNotice}\n`);
     }
@@ -398,6 +504,8 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         contentVersion,
         engineVersion,
         previousDepositVersion,
+        alreadyCurrent,
+        strategy,
         agentsMdUpdated,
         versionSkewNotice,
         legacyLayout: false,
@@ -499,7 +607,9 @@ export async function runRefreshDepositCli(options) {
     }
     try {
         const result = await runRefreshDeposit(options, io, options.seams);
-        const state = classification?.state;
+        const state = result.alreadyCurrent
+            ? "current"
+            : classification?.state;
         if (options.jsonOut) {
             options.writeOut(`${JSON.stringify(buildUpdateSummaryJson(result, options, state), null, 2)}\n`);
             printUpdateComplete(result, { printf: options.writeErr }, state);

package/dist/init-deposit/scaffold.d.ts

@@ -67,6 +67,16 @@ export declare function ensureCodeqlPathsIgnore(projectDir: string, io: InitDepo
 export declare function ensureCoreGuardWorkflow(projectDir: string, io: InitDepositIo): boolean;
 export declare function pruneFrameworkSelfTests(projectDir: string, io: InitDepositIo): Promise<boolean>;
 export declare function pruneVendoredTsTests(projectDir: string, io: InitDepositIo): Promise<number>;
+export interface DepositNeutralizationOptions {
+    /**
+     * #2148: skip depositing `.github/workflows/deft-core-guard.yml` when the
+     * framework deposit is not git-tracked (npm-managed / gitignored layout). The
+     * guard CI check is meaningless when there is no committed `.deft/core/**` to
+     * guard; skipping it prevents the file from re-appearing as untracked noise
+     * after every `directive update`.
+     */
+    readonly skipGuardWorkflow?: boolean;
+}
 /** Best-effort #1430 neutralization deposit (mirrors depositNeutralization). */
-export declare function depositNeutralization(projectDir: string, io: InitDepositIo): Promise<void>;
+export declare function depositNeutralization(projectDir: string, io: InitDepositIo, options?: DepositNeutralizationOptions): Promise<void>;
 //# sourceMappingURL=scaffold.d.ts.map

package/dist/init-deposit/scaffold.js

@@ -10,8 +10,8 @@ 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";
+import { MIGRATED_ARTIFACT_DIR } from "../xbrief-migrate/constants.js";
 import { CANONICAL_INSTALL_ROOT } from "./constants.js";
 import { installerManagedGuardEre } from "./hygiene.js";
 export { CANONICAL_INSTALL_ROOT };
@@ -22,6 +22,7 @@ const FRAMEWORK_SELF_TEST_REL = ".deft/core/tests";
 const VENDORED_TS_PACKAGES_REL = ".deft/core/packages";
 const VENDORED_TS_TEST_RE = /\.(test|spec)\.(c|m)?[jt]sx?$/i;
 const CORE_GITATTRIBUTES_LINES = [
+    `${CORE_GLOB} text eol=lf`,
     `${CORE_GLOB} linguist-generated=true`,
     `${CORE_GLOB} linguist-vendored=true`,
 ];
@@ -322,7 +323,7 @@ function vbriefLifecycleDirsPresent(consumerVbrief) {
     });
 }
 export async function writeConsumerVbrief(projectDir, deftDir, io) {
-    const consumerVbrief = resolveLifecycleRoot(projectDir);
+    const consumerVbrief = join(projectDir, MIGRATED_ARTIFACT_DIR);
     const schemasDst = join(consumerVbrief, "schemas");
     const vbriefMdDst = join(consumerVbrief, "vbrief.md");
     const schemasPresent = existsSync(schemasDst) && statSync(schemasDst).isDirectory();
@@ -584,7 +585,7 @@ export function ensureGitattributes(projectDir, io) {
     const present = new Set(existing.split("\n").map((line) => line.trim()));
     const additions = CORE_GITATTRIBUTES_LINES.filter((line) => !present.has(line));
     if (additions.length === 0) {
-        io.printf(`.gitattributes already marks ${CORE_GLOB} as generated/vendored — skipping.\n`);
+        io.printf(`.gitattributes already marks ${CORE_GLOB} as LF-pinned/generated/vendored — skipping.\n`);
         return false;
     }
     let body = existing;
@@ -594,13 +595,13 @@ export function ensureGitattributes(projectDir, io) {
         body += "\n";
     body +=
         "# Deft framework: the vendored payload is packaged framework code, not\n" +
-            "# consumer source. Mark it generated + vendored so language stats and\n" +
-            "# diffs treat .deft/core/** as machine-managed (#1430).\n";
+            "# consumer source. Pin LF endings and mark it generated + vendored so\n" +
+            "# Git does not rewrite it and diffs treat .deft/core/** as machine-managed (#1430, #2118).\n";
     for (const add of additions) {
         body += `${add}\n`;
     }
     writeFileSync(path, body, "utf8");
-    io.printf(`.gitattributes updated with linguist markers: ${additions.join(", ")}\n`);
+    io.printf(`.gitattributes updated with Deft core markers: ${additions.join(", ")}\n`);
     return true;
 }
 function greptilePatternPresent(patterns, glob) {
@@ -774,12 +775,12 @@ export async function pruneVendoredTsTests(projectDir, io) {
     return removed;
 }
 /** Best-effort #1430 neutralization deposit (mirrors depositNeutralization). */
-export async function depositNeutralization(projectDir, io) {
+export async function depositNeutralization(projectDir, io, options = {}) {
     const steps = [
         () => ensureGitattributes(projectDir, io),
         () => ensureGreptileIgnore(projectDir, io),
         () => ensureCodeqlPathsIgnore(projectDir, io),
-        () => ensureCoreGuardWorkflow(projectDir, io),
+        ...(options.skipGuardWorkflow ? [] : [() => ensureCoreGuardWorkflow(projectDir, io)]),
         () => pruneFrameworkSelfTests(projectDir, io),
         async () => (await pruneVendoredTsTests(projectDir, io)) > 0,
     ];

package/dist/integration-e2e/helpers.js

@@ -77,12 +77,12 @@ export function populateCacheLayout(cacheRoot, repo, issueNumbers) {
 }
 export function createConsumerProject(parent) {
     const root = join(parent, "consumer");
-    mkdirSync(join(root, "vbrief", "proposed"), { recursive: true });
-    mkdirSync(join(root, "vbrief", "pending"), { recursive: true });
-    mkdirSync(join(root, "vbrief", "active"), { recursive: true });
-    mkdirSync(join(root, "vbrief", "completed"), { recursive: true });
-    mkdirSync(join(root, "vbrief", "cancelled"), { recursive: true });
-    writeFileSync(join(root, "vbrief", "specification.vbrief.json"), `${JSON.stringify({
+    mkdirSync(join(root, "xbrief", "proposed"), { recursive: true });
+    mkdirSync(join(root, "xbrief", "pending"), { recursive: true });
+    mkdirSync(join(root, "xbrief", "active"), { recursive: true });
+    mkdirSync(join(root, "xbrief", "completed"), { recursive: true });
+    mkdirSync(join(root, "xbrief", "cancelled"), { recursive: true });
+    writeFileSync(join(root, "xbrief", "specification.xbrief.json"), `${JSON.stringify({
         vBRIEFInfo: { version: "0.5" },
         plan: {
             title: "Consumer Project",
@@ -96,7 +96,7 @@ export function createConsumerProject(parent) {
     return root;
 }
 export function writeScopeVbrief(projectRoot, folder, filename, status = "proposed") {
-    const target = join(projectRoot, "vbrief", folder, filename);
+    const target = join(projectRoot, "xbrief", folder, filename);
     writeFileSync(target, `${JSON.stringify({
         vBRIEFInfo: { version: "0.5" },
         plan: {

package/dist/layout/index.d.ts

@@ -1,2 +1,2 @@
-export { ARTIFACT_SUFFIXES, hasArtifactSuffix, isLifecycleArtifactPath, LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, LIFECYCLE_DIR_NAMES, type LifecycleLayout, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, projectDefinitionFilename, projectDefinitionRelPath, resolveAuditDir, resolveAuditPath, resolveEvalDir, resolveEvalPath, resolveLifecycleFolder, resolveLifecycleLayout, resolveLifecycleRoot, resolveProjectDefinitionPath, resolveSpecArtifactPath, specArtifactRelPath, stripArtifactSuffix, } from "./resolve.js";
+export { ARTIFACT_SUFFIXES, hasArtifactSuffix, isLifecycleArtifactPath, LIFECYCLE_DIR_NAMES, type LifecycleLayout, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, projectDefinitionFilename, projectDefinitionRelPath, resolveAuditDir, resolveAuditPath, resolveEvalDir, resolveEvalPath, resolveLifecycleFolder, resolveLifecycleLayout, resolveLifecycleRoot, resolveProjectDefinitionPath, resolveSpecArtifactPath, specArtifactRelPath, stripArtifactSuffix, } from "./resolve.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/layout/index.js

@@ -1,2 +1,2 @@
-export { ARTIFACT_SUFFIXES, hasArtifactSuffix, isLifecycleArtifactPath, LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, LIFECYCLE_DIR_NAMES, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, projectDefinitionFilename, projectDefinitionRelPath, resolveAuditDir, resolveAuditPath, resolveEvalDir, resolveEvalPath, resolveLifecycleFolder, resolveLifecycleLayout, resolveLifecycleRoot, resolveProjectDefinitionPath, resolveSpecArtifactPath, specArtifactRelPath, stripArtifactSuffix, } from "./resolve.js";
+export { ARTIFACT_SUFFIXES, hasArtifactSuffix, isLifecycleArtifactPath, LIFECYCLE_DIR_NAMES, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, projectDefinitionFilename, projectDefinitionRelPath, resolveAuditDir, resolveAuditPath, resolveEvalDir, resolveEvalPath, resolveLifecycleFolder, resolveLifecycleLayout, resolveLifecycleRoot, resolveProjectDefinitionPath, resolveSpecArtifactPath, specArtifactRelPath, stripArtifactSuffix, } from "./resolve.js";
 //# sourceMappingURL=index.js.map

package/dist/layout/resolve.d.ts

@@ -1,28 +1,39 @@
-import { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY } from "../xbrief-migrate/constants.js";
-export { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, };
+import { LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY } from "../xbrief-migrate/constants.js";
+export { LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, };
 /**
- * Lifecycle directory names recognized by the layout-aware resolver, in
- * preference order (migrated `xbrief` first, legacy `vbrief` second).
+ * Lifecycle directory names recognized by the layout-aware resolver and path
+ * validators. Includes both `xbrief` (canonical) and `vbrief` (legacy) so that
+ * path-validation helpers remain accurate during and after migration.
  */
 export declare const LIFECYCLE_DIR_NAMES: readonly ["xbrief", "vbrief"];
 /**
- * Artifact filename suffixes recognized by the layout-aware resolver, in
- * preference order (`.xbrief.json` first, `.vbrief.json` second).
+ * Artifact filename suffixes recognized by the layout-aware resolver and path
+ * validators. Includes both `.xbrief.json` (canonical) and `.vbrief.json`
+ * (legacy) so that path-validation helpers remain accurate during and after
+ * migration.
  */
 export declare const ARTIFACT_SUFFIXES: readonly [".xbrief.json", ".vbrief.json"];
-/** The on-disk lifecycle layout an engine call site should resolve against (#2109). */
+/** The on-disk lifecycle layout an engine call site should resolve against (#2109 / #2112). */
 export interface LifecycleLayout {
-    /** The lifecycle directory name -- `xbrief` when migrated, else `vbrief`. */
-    readonly artifactDir: typeof MIGRATED_ARTIFACT_DIR | typeof LEGACY_ARTIFACT_DIR;
-    /** The artifact filename suffix matching `artifactDir`. */
-    readonly artifactSuffix: typeof MIGRATED_ARTIFACT_SUFFIX | typeof LEGACY_ARTIFACT_SUFFIX;
-    /** The `*BRIEFInfo` root key matching `artifactDir`. */
-    readonly infoRootKey: typeof MIGRATED_INFO_ROOT_KEY | typeof LEGACY_INFO_ROOT_KEY;
-    /** Absolute path to the resolved lifecycle root (`<projectRoot>/<artifactDir>`). */
+    /** The lifecycle directory name -- always `xbrief` after the vbrief read path removal (#2112). */
+    readonly artifactDir: typeof MIGRATED_ARTIFACT_DIR;
+    /** The artifact filename suffix -- always `.xbrief.json` after #2112. */
+    readonly artifactSuffix: typeof MIGRATED_ARTIFACT_SUFFIX;
+    /** The `xBRIEFInfo` root key. */
+    readonly infoRootKey: typeof MIGRATED_INFO_ROOT_KEY;
+    /** Absolute path to the resolved lifecycle root (`<projectRoot>/xbrief`). */
     readonly root: string;
-    /** True when the resolved layout is the migrated `xbrief` layout. */
-    readonly migrated: boolean;
+    /** Always `true` -- the legacy vbrief read path was removed in #2112. */
+    readonly migrated: true;
 }
+/**
+ * Returns the layout root for non-layout-sensitive helpers (#2112).
+ *
+ * - If a valid `xbrief/` layout exists, returns its root.
+ * - If only `vbrief/` exists (legacy-only), throws so the caller surfaces the migrate hint.
+ * - If neither exists (empty/new project), falls back to `<projectRoot>/xbrief/` canonical path.
+ */
+export declare function resolveLayoutRootOrCanonical(projectRoot: string): string;
 /** True when `name` ends with any recognized artifact suffix (.xbrief.json or .vbrief.json). */
 export declare function hasArtifactSuffix(name: string): boolean;
 /**
@@ -31,24 +42,30 @@ export declare function hasArtifactSuffix(name: string): boolean;
  */
 export declare function stripArtifactSuffix(name: string): string;
 /**
- * True when a POSIX-style path is a lifecycle artifact under either layout
- * root (`xbrief/` or `vbrief/`) carrying either artifact suffix.
+ * True when a POSIX-style path is a lifecycle artifact path carrying a
+ * recognized lifecycle directory prefix (`xbrief/` or `vbrief/`) and a
+ * recognized artifact suffix. The `vbrief/` prefix and `.vbrief.json` suffix
+ * remain recognized for path-validation purposes during and after migration.
  */
 export declare function isLifecycleArtifactPath(posix: string): boolean;
 /**
- * Resolve the active lifecycle layout for `projectRoot` (#2109 part 1).
+ * Resolve the active lifecycle layout for `projectRoot` (#2109 part 1 / #2112).
+ *
+ * Requires the migrated `xbrief/` layout: the `xbrief/` directory must exist
+ * AND contain at least one `.xbrief.json` artifact. If no such layout is found,
+ * throws with a clear error directing the operator to run `deft migrate:xbrief`.
+ *
+ * The legacy `vbrief/` read-path fallback was removed in #2112 (0.73.0 MINOR).
+ * Projects that have not migrated must run `deft migrate:xbrief` first.
  *
- * Prefers the migrated `xbrief/` layout only when BOTH the `xbrief/` directory
- * exists AND it contains at least one `.xbrief.json` artifact; otherwise falls
- * back to the legacy `vbrief/` layout. With only `vbrief/` present (today's
- * repo) the result is the legacy layout, so existing behavior is unchanged.
+ * @throws {Error} When no `xbrief/` layout with `.xbrief.json` artifacts exists.
  */
 export declare function resolveLifecycleLayout(projectRoot: string): LifecycleLayout;
 /** Convenience accessor for the absolute resolved lifecycle root directory. */
 export declare function resolveLifecycleRoot(projectRoot: string): string;
 /**
- * Absolute path to a lifecycle folder under the resolved layout root
- * (e.g. `<root>/<xbrief|vbrief>/active`). Layout-aware (#2109 part 2a).
+ * Absolute path to a lifecycle folder under the resolved `xbrief/` layout root
+ * (e.g. `<root>/xbrief/active`). Layout-aware (#2109 part 2a / #2112).
  */
 export declare function resolveLifecycleFolder(projectRoot: string, folder: string): string;
 /** Absolute path to the layout-aware `.eval/` directory for version-eval results (#1703). */
@@ -68,20 +85,19 @@ export declare function projectDefinitionFilename(projectRoot: string): string;
 export declare function resolveProjectDefinitionPath(projectRoot: string): string;
 /**
  * POSIX-style display path to the resolved PROJECT-DEFINITION artifact relative
- * to the project root (e.g. `vbrief/PROJECT-DEFINITION.vbrief.json`).
+ * to the project root (e.g. `xbrief/PROJECT-DEFINITION.xbrief.json`).
  */
 export declare function projectDefinitionRelPath(projectRoot: string): string;
 /**
- * Absolute path to the resolved specification artifact (#2132).
+ * Absolute path to the resolved specification artifact (#2132 / #2112).
  *
- * Prefers `xbrief/specification.xbrief.json` on a migrated tree; falls back to
- * `vbrief/specification.vbrief.json` on an unmigrated tree. Consistent with the
- * layout resolver used by the #2109 Part-2a call-site sweep.
+ * Returns `xbrief/specification.xbrief.json`; throws when no migrated xbrief/
+ * layout is present (see `resolveLifecycleLayout`).
  */
 export declare function resolveSpecArtifactPath(projectRoot: string): string;
 /**
  * POSIX-style display path to the resolved specification artifact relative to
- * the project root (e.g. `xbrief/specification.xbrief.json`).
+ * the project root (`xbrief/specification.xbrief.json`).
  */
 export declare function specArtifactRelPath(projectRoot: string): string;
 //# sourceMappingURL=resolve.d.ts.map