@deftai/directive-core 0.68.1 → 0.69.0

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

@@ -3,9 +3,9 @@ import { dirname, join, relative, resolve } from "node:path";
 import { checkGitClean } from "../migrate-preflight/index.js";
 import { agentsRefreshPlan } from "../platform/agents-md.js";
 import { patchAgentsMdHeader, renderHeaderPatchSummary } from "./agents-header.js";
-import { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, } from "./constants.js";
-import { detectLegacyVbriefLayout } from "./detect.js";
-import { isDirectory } from "./fs-helpers.js";
+import { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, VBRIEF_DEPRECATION_MARKER_BODY, VBRIEF_DEPRECATION_MARKER_FILENAME, } from "./constants.js";
+import { detectLegacyVbriefLayout, detectXbriefConvergence } from "./detect.js";
+import { hasVbriefDeprecationMarker, isDirectory, isEffectivelyEmptyDir } from "./fs-helpers.js";
 import { renderXbriefMigrationLine, xbriefMigrationGuidance } from "./signpost.js";
 import { rewriteEmbeddedTokens, transformArtifactV06ToV08Transactional } from "./transforms.js";
 function collectFiles(root, acc = []) {
@@ -52,7 +52,7 @@ function backupLegacyTree(projectRoot, legacyDir) {
     cpSync(legacyDir, join(backupRoot, LEGACY_ARTIFACT_DIR), { recursive: true });
     return backupRoot;
 }
-function migrateLegacyTree(projectRoot, legacyDir) {
+function migrateLegacyTree(projectRoot, legacyDir, options) {
     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}/'`);
@@ -71,7 +71,15 @@ function migrateLegacyTree(projectRoot, legacyDir) {
             writeMigratedFile(srcPath, destPath);
         }
         renameOrReplace(stagedDir, migratedDir);
-        rmSync(legacyDir, { recursive: true, force: true });
+        // Converge to a single unambiguous root: the fully-migrated legacy tree is
+        // either removed (default) or retained for read-compat behind an explicit
+        // deprecation marker so it never looks like an active source of truth (#2270).
+        if (options.keepLegacy) {
+            writeVbriefDeprecationMarker(legacyDir);
+        }
+        else {
+            rmSync(legacyDir, { recursive: true, force: true });
+        }
         return { backupDir, files: files.length };
     }
     catch (err) {
@@ -79,6 +87,36 @@ function migrateLegacyTree(projectRoot, legacyDir) {
         throw err;
     }
 }
+/** Idempotently write the legacy-root deprecation marker (#2270). */
+function writeVbriefDeprecationMarker(legacyDir) {
+    mkdirSync(legacyDir, { recursive: true });
+    if (hasVbriefDeprecationMarker(legacyDir)) {
+        return;
+    }
+    writeFileSync(join(legacyDir, VBRIEF_DEPRECATION_MARKER_FILENAME), VBRIEF_DEPRECATION_MARKER_BODY, "utf8");
+}
+/**
+ * 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 function convergeLegacyVbriefRoot(projectRoot, options) {
+    const legacyDir = join(projectRoot, LEGACY_ARTIFACT_DIR);
+    if (!isDirectory(legacyDir)) {
+        return "removed";
+    }
+    if (hasVbriefDeprecationMarker(legacyDir)) {
+        return "marker";
+    }
+    if (isEffectivelyEmptyDir(legacyDir) && !options.retain) {
+        rmSync(legacyDir, { recursive: true, force: true });
+        return "removed";
+    }
+    writeVbriefDeprecationMarker(legacyDir);
+    return "marker";
+}
 function renameOrReplace(src, dest) {
     if (existsSync(dest)) {
         rmSync(dest, { recursive: true, force: true });
@@ -107,9 +145,58 @@ function runAgentsRefresh(projectRoot, frameworkRoot, io) {
     io.writeOut(`AGENTS.md updated (state=${state}).\n`);
     return 0;
 }
-/** Core orchestrator for the consumer xbrief rename (#2110). */
+/** Core orchestrator for the consumer xbrief rename (#2110) + convergence (#2270). */
 export function runXbriefMigration(args, _io) {
     const projectRoot = resolve(args.projectRoot);
+    const legacyDir = join(projectRoot, LEGACY_ARTIFACT_DIR);
+    const keepLegacy = args.keepLegacy ?? false;
+    const convergence = detectXbriefConvergence(projectRoot);
+    switch (convergence.state) {
+        // Already converged: legacy root is retained behind an explicit marker.
+        // Rerun is a pure no-op (no re-removal, no duplicate marker) — idempotent.
+        case "xbrief-marker":
+            return {
+                kind: "converged",
+                action: "marker",
+                already: true,
+                message: `Legacy '${LEGACY_ARTIFACT_DIR}/' already carries a deprecation marker — layout already converged.`,
+            };
+        // Ambiguous dual-empty root: a fully-migrated empty legacy tree. Converge to
+        // a single canonical root by removing it (or marking it when read-compat
+        // retention is requested); never leave two indistinguishable empty roots.
+        // Read-compat retention is only honored when a canonical xbrief/ actually
+        // has content — marking an empty legacy root with no canonical replacement
+        // would strand the project behind a marker that claims a migration that
+        // never happened, so that case always removes the stray empty root.
+        case "empty-vbrief": {
+            const retain = keepLegacy && convergence.xbriefHasContent;
+            const action = convergeLegacyVbriefRoot(projectRoot, { retain });
+            let message;
+            if (action === "removed") {
+                message = convergence.xbriefHasContent
+                    ? `Converged layout: removed empty legacy '${LEGACY_ARTIFACT_DIR}/' — single '${MIGRATED_ARTIFACT_DIR}/' root.`
+                    : `Converged layout: removed empty legacy '${LEGACY_ARTIFACT_DIR}/' — no canonical '${MIGRATED_ARTIFACT_DIR}/' root to migrate to yet.`;
+            }
+            else {
+                message = `Converged layout: wrote deprecation marker to legacy '${LEGACY_ARTIFACT_DIR}/' (retained for read-compat).`;
+            }
+            return { kind: "converged", action, already: false, message };
+        }
+        // Legacy content coexisting with a populated canonical xbrief/. We never
+        // destructively merge; converge non-destructively by marking the legacy
+        // tree deprecated so it no longer looks like an active source of truth.
+        case "dual-populated": {
+            convergeLegacyVbriefRoot(projectRoot, { retain: true });
+            return {
+                kind: "converged",
+                action: "marker",
+                already: false,
+                message: `Converged layout: '${MIGRATED_ARTIFACT_DIR}/' is canonical; wrote deprecation marker to legacy '${LEGACY_ARTIFACT_DIR}/' (retained for read-compat).`,
+            };
+        }
+        default:
+            break;
+    }
     const detection = detectLegacyVbriefLayout(projectRoot);
     if (!detection.legacyLayout) {
         return {
@@ -117,7 +204,6 @@ export function runXbriefMigration(args, _io) {
             message: "Project is already on the xbrief layout — nothing to migrate.",
         };
     }
-    const legacyDir = join(projectRoot, LEGACY_ARTIFACT_DIR);
     if (!isDirectory(legacyDir)) {
         return {
             kind: "config",
@@ -134,7 +220,7 @@ export function runXbriefMigration(args, _io) {
         }
     }
     try {
-        const { backupDir, files } = migrateLegacyTree(projectRoot, legacyDir);
+        const { backupDir, files } = migrateLegacyTree(projectRoot, legacyDir, { keepLegacy });
         return { kind: "migrated", backupDir, files };
     }
     catch (err) {
@@ -165,6 +251,9 @@ export function emitXbriefMigration(outcome, io, options = {}) {
             io.writeOut(`Migrated ${outcome.files} file(s) from ${LEGACY_ARTIFACT_DIR}/ to ${MIGRATED_ARTIFACT_DIR}/.\n` +
                 `Backup written to ${outcome.backupDir}.\n`);
             return 0;
+        case "converged":
+            io.writeOut(`${outcome.message}\n`);
+            return 0;
         default: {
             const _exhaustive = outcome;
             return _exhaustive;

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

@@ -1,5 +1,11 @@
 /** Operator guidance for the TS-native xbrief rename (#2034 / #2110). */
 export declare function xbriefMigrationGuidance(): string;
-/** One-line doctor / ritual signpost mirroring `renderPrecutoverLine` (#2110). */
+/**
+ * One-line doctor / ritual signpost mirroring `renderPrecutoverLine` (#2110),
+ * reporting an unambiguous convergence state (#2270). A migrated project reads
+ * as `xbrief active` plus either `vbrief legacy marker` or `vbrief removed`; a
+ * stray empty legacy root is called out as a pending convergence rather than a
+ * generic "run migrate" dead end — never a dual-empty-root ambiguity.
+ */
 export declare function renderXbriefMigrationLine(projectRoot: string): string;
 //# sourceMappingURL=signpost.d.ts.map

package/dist/xbrief-migrate/signpost.js

@@ -1,13 +1,28 @@
-import { detectLegacyVbriefLayout } from "./detect.js";
+import { detectLegacyVbriefLayout, detectXbriefConvergence } 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). */
+/**
+ * One-line doctor / ritual signpost mirroring `renderPrecutoverLine` (#2110),
+ * reporting an unambiguous convergence state (#2270). A migrated project reads
+ * as `xbrief active` plus either `vbrief legacy marker` or `vbrief removed`; a
+ * stray empty legacy root is called out as a pending convergence rather than a
+ * generic "run migrate" dead end — never a dual-empty-root ambiguity.
+ */
 export function renderXbriefMigrationLine(projectRoot) {
+    const convergence = detectXbriefConvergence(projectRoot);
+    // Converged: legacy vbrief/ retained for read-compat behind an explicit marker.
+    if (convergence.state === "xbrief-marker") {
+        return "xBrief migration: converged -- xbrief active, vbrief legacy marker (read-compat).";
+    }
+    // Ambiguous dual-empty root: canonical xbrief/ (or none) plus a stray empty vbrief/.
+    if (convergence.state === "empty-vbrief") {
+        return `xBrief migration: converge pending -- xbrief active, empty legacy vbrief/ present. ${xbriefMigrationGuidance()}`;
+    }
     const { legacyLayout, reasons } = detectLegacyVbriefLayout(projectRoot);
     if (!legacyLayout) {
-        return "xBrief migration: none -- project is on the xbrief layout.";
+        return "xBrief migration: none -- xbrief active, vbrief removed.";
     }
     const maxReasons = 3;
     const shown = reasons.slice(0, maxReasons);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.68.1",
+  "version": "0.69.0",
   "description": "TypeScript engine core for the Directive framework.",
   "type": "module",
   "main": "./dist/index.js",
@@ -90,6 +90,10 @@
       "types": "./dist/release-e2e/index.d.ts",
       "default": "./dist/release-e2e/index.js"
     },
+    "./resolution": {
+      "types": "./dist/resolution/index.d.ts",
+      "default": "./dist/resolution/index.js"
+    },
     "./pr-merge-readiness": {
       "types": "./dist/pr-merge-readiness/index.d.ts",
       "default": "./dist/pr-merge-readiness/index.js"
@@ -245,8 +249,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.68.1",
-    "@deftai/directive-types": "^0.68.1",
+    "@deftai/directive-content": "^0.69.0",
+    "@deftai/directive-types": "^0.69.0",
     "archiver": "^8.0.0"
   },
   "scripts": {