@deftai/directive-core 0.77.0 → 0.79.0

package/dist/release-e2e/greenfield-python-free-smoke.js

@@ -46,12 +46,23 @@ function packTarballPath(packDir, pkgDir) {
     const scoped = manifest.name.replaceAll("@", "").replaceAll("/", "-");
     return join(packDir, `${scoped}-${manifest.version}.tgz`);
 }
-function runStep(spawn, label, cmd, args, options = {}) {
+function runStep(spawn, label, cmd, args, options = {}, onProgress) {
+    onProgress?.(`greenfield smoke: ${label} — starting`);
+    const startedMs = Date.now();
     const result = spawn(cmd, args, options);
+    const elapsedMs = Date.now() - startedMs;
     if (result.status !== 0) {
         const detail = (result.stderr || result.stdout || "").trim();
-        return [false, `${label} failed (exit ${result.status}): ${detail.slice(-800)}`];
+        const timeoutHint = options.timeoutMs !== undefined && result.status === 128
+            ? `; subprocess killed after ${elapsedMs}ms (spawn budget ${options.timeoutMs}ms — likely hang or timeout)`
+            : "";
+        onProgress?.(`greenfield smoke: ${label} — failed (exit ${result.status}) after ${elapsedMs}ms`);
+        return [
+            false,
+            `${label} failed (exit ${result.status})${timeoutHint}: ${detail.slice(-800) || "(no captured output)"}`,
+        ];
     }
+    onProgress?.(`greenfield smoke: ${label} — OK (${elapsedMs}ms)`);
     return [true, `${label} OK`];
 }
 /**
@@ -77,6 +88,8 @@ export function rehearseGreenfieldPythonFreeSmoke(repoRoot, seams = {}, options
         return [false, "greenfield-python-free-smoke FAIL: pnpm command prefix is empty"];
     }
     const spawn = seams.spawnText ?? spawnText;
+    const onProgress = options.onProgress;
+    onProgress?.("greenfield smoke: workspace prep starting");
     const work = mkdtempSync(join(tmpdir(), "deft-greenfield-smoke-"));
     const packDir = join(work, "packs");
     mkdirSync(packDir, { recursive: true });
@@ -98,24 +111,28 @@ export function rehearseGreenfieldPythonFreeSmoke(repoRoot, seams = {}, options
                 cwd: repoRoot,
                 env: envBase,
                 timeoutMs: 120_000,
-            });
+            }, onProgress);
             if (!ok)
                 return [false, `greenfield smoke: ${reason}`];
             [ok, reason] = runStep(spawn, "pnpm build", pnpmCmd, [...pnpmArgs, "run", "build"], {
                 cwd: repoRoot,
                 env: envBase,
                 timeoutMs: 120_000,
-            });
+            }, onProgress);
             if (!ok)
                 return [false, `greenfield smoke: ${reason}`];
         }
+        else {
+            onProgress?.("greenfield smoke: skipping workspace prep (DEFT_GREENFIELD_SKIP_PREP=1)");
+        }
+        onProgress?.("greenfield smoke: aligning npm package versions");
         [ok, reason] = alignNpmPackageVersions(repoRoot, SMOKE_VERSION);
         if (!ok)
             return [false, `greenfield smoke: ${reason}`];
         const packed = [];
         for (const pkg of NPM_PUBLISH_PACKAGES) {
             const pkgDir = join(repoRoot, "packages", pkg);
-            [ok, reason] = runStep(spawn, `npm pack packages/${pkg}`, npm, ["pack", "--pack-destination", packDir], { cwd: pkgDir, env: envBase, timeoutMs: 120_000 });
+            [ok, reason] = runStep(spawn, `npm pack packages/${pkg}`, npm, ["pack", "--pack-destination", packDir], { cwd: pkgDir, env: envBase, timeoutMs: 120_000 }, onProgress);
             if (!ok)
                 return [false, `greenfield smoke: ${reason}`];
             const tgz = packTarballPath(packDir, pkgDir);
@@ -127,7 +144,7 @@ export function rehearseGreenfieldPythonFreeSmoke(repoRoot, seams = {}, options
         [ok, reason] = runStep(spawn, "npm install -g", npm, ["install", "-g", ...packed], {
             env: envBase,
             timeoutMs: 120_000,
-        });
+        }, onProgress);
         if (!ok)
             return [false, `greenfield smoke: ${reason}`];
         const deft = join(npmPrefix, "bin", "deft");
@@ -139,9 +156,10 @@ export function rehearseGreenfieldPythonFreeSmoke(repoRoot, seams = {}, options
             cwd: work,
             env: pyFree,
             timeoutMs: 120_000,
-        });
+        }, onProgress);
         if (!ok)
             return [false, `greenfield smoke: ${reason}`];
+        onProgress?.("greenfield smoke: seeding fixture PROJECT-DEFINITION");
         seedMinimalProjectDefinition(projectDir);
         const depositDir = join(projectDir, ".deft", "core");
         const artifacts = collectPythonArtifacts(depositDir);
@@ -159,13 +177,15 @@ export function rehearseGreenfieldPythonFreeSmoke(repoRoot, seams = {}, options
             PATH: `${join(npmPrefix, "bin")}:${pyFree.PATH ?? ""}`,
             DEFT_SESSION_RITUAL_SKIP: "1",
         };
+        onProgress?.("greenfield smoke: running consumer task deft:check (engine-invoke path)");
         [ok, reason] = runStep(spawn, "task deft:check", task, ["deft:check"], {
             cwd: projectDir,
             env: checkEnv,
             timeoutMs: 180_000,
-        });
+        }, onProgress);
         if (!ok)
             return [false, `greenfield smoke: ${reason}`];
+        onProgress?.("greenfield smoke: all steps passed");
         return [
             true,
             "greenfield-python-free-smoke: directive init + task deft:check passed with Python absent from PATH",

package/dist/release-e2e/main.js

@@ -1,6 +1,6 @@
 import { resolveProjectRoot } from "../release/paths.js";
 import { EXIT_CONFIG_ERROR, EXIT_OK, EXIT_VIOLATION, RELEASE_E2E_HELP } from "./constants.js";
-import { emit, generateRepoSlug, parseE2EFlags } from "./flags.js";
+import { emit, formatTempRepoCleanupHint, generateRepoSlug, parseE2EFlags } from "./flags.js";
 import { destroyTempRepo, provisionTempRepo } from "./gh-ops.js";
 import { runLegacyBridgeLeg } from "./legacy-bridge-leg.js";
 import { runRehearsal } from "./rehearsal.js";
@@ -18,7 +18,13 @@ export function runE2e(config, seams = {}) {
             emit("Legacy-bridge leg", "DRYRUN (would run the pinned legacy -> bridge -> npm-hybrid migration leg; reads the " +
                 "Tier-0 SoT lastGoInstaller(), pending-pin while null)");
         }
-        emit("Destroy temp repo", `DRYRUN (would run \`gh repo delete ${owner}/${slug} --yes\`)`);
+        const cleanupHint = formatTempRepoCleanupHint(owner, slug);
+        if (config.destroyRepo) {
+            emit("Destroy temp repo", `DRYRUN (would run \`${cleanupHint}\`)`);
+        }
+        else {
+            emit("Temp repo cleanup", `DRYRUN (would keep ${owner}/${slug}; manual cleanup: ${cleanupHint})`);
+        }
         return EXIT_OK;
     }
     // Opt-in #1912 leg: local + self-contained (no temp GitHub repo), so run it
@@ -49,19 +55,19 @@ export function runE2e(config, seams = {}) {
         }
     }
     finally {
-        if (config.keepRepo) {
-            emit(`Destroy ${owner}/${slug}`, "SKIP (--keep-repo set; manual cleanup required: " +
-                `gh repo delete ${owner}/${slug} --yes)`);
-        }
-        else {
+        const cleanupHint = formatTempRepoCleanupHint(owner, slug);
+        if (config.destroyRepo) {
             const [destroyOk, destroyReason] = destroyTempRepo(owner, slug, seams);
             if (destroyOk) {
                 emit(`Destroy ${owner}/${slug}`, `OK (${destroyReason})`);
             }
             else {
-                emit(`Destroy ${owner}/${slug}`, `WARN (${destroyReason}); manual cleanup hint: gh repo delete ${owner}/${slug} --yes`);
+                emit(`Destroy ${owner}/${slug}`, `WARN (${destroyReason}); manual cleanup: ${cleanupHint}`);
             }
         }
+        else {
+            emit(`Temp repo ${owner}/${slug}`, `KEEP (manual cleanup: ${cleanupHint})`);
+        }
     }
     return rehearsalRc !== EXIT_OK ? rehearsalRc : legacyBridgeRc;
 }
@@ -84,7 +90,7 @@ export function cmdReleaseE2e(args, seams = {}) {
         owner: flags.owner,
         projectRoot,
         dryRun: flags.dryRun,
-        keepRepo: flags.keepRepo,
+        destroyRepo: flags.destroyRepo,
         skipNpm: flags.skipNpm,
         legacyBridge: flags.legacyBridge,
         repoSlug: null,

package/dist/release-e2e/types.d.ts

@@ -3,7 +3,8 @@ export interface E2EConfig {
     owner: string;
     projectRoot: string;
     dryRun: boolean;
-    keepRepo: boolean;
+    /** When true, attempt gh repo delete after rehearsal (#2572 opt-in privileged mode). */
+    destroyRepo: boolean;
     /** When true, skip the npm publish dry-run rehearsal step (#1910). */
     skipNpm: boolean;
     /**
@@ -20,7 +21,8 @@ export interface ParsedE2EFlags {
     help: boolean;
     owner: string;
     dryRun: boolean;
-    keepRepo: boolean;
+    /** When true, attempt gh repo delete after rehearsal (#2572 opt-in privileged mode). */
+    destroyRepo: boolean;
     projectRoot: string | null;
     skipNpm: boolean;
     /** Opt-in: run the pinned legacy->bridge->npm-hybrid migration leg (#1912). */

package/dist/resolution/classify.d.ts

@@ -30,7 +30,7 @@ export interface ClassifySeams {
     /** Pre-cutover probe; defaults to the shared `detectPreCutover` detector. */
     readonly preCutoverProbe?: (cwd: string) => boolean;
 }
-/** Default engine probe: try `directive --version`, then `deft --version`. */
+/** Default engine probe: in-process identity, then `directive` / `deft` on PATH. */
 export declare function defaultEngineProbe(): EngineProbeResult;
 /**
  * Classify a project directory into the orthogonal resolution fact-set. All I/O

package/dist/resolution/classify.js

@@ -11,13 +11,16 @@
  *  - deposited payload version-> `../doctor/manifest.ts` + `../init-deposit/constants.ts`
  *  - committed pin            -> `./pin.ts`
  */
-import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { locateManifest, manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
+import { readCorePackageVersion } from "../engine-version.js";
 import { CANONICAL_INSTALL_ROOT } from "../init-deposit/constants.js";
 import { extractManagedSection, parseManagedSectionAttrs } from "../platform/agents-md.js";
+import { ENV_VAR } from "../platform/constants.js";
 import { detectPreCutover } from "../vbrief-validate/precutover.js";
+import { resolveCommandOnPath, spawnCommandText } from "../verify-env/command-spawn.js";
 import { readPin } from "./pin.js";
 /** App-source markers used for the `hasAppCode` heuristic. */
 const APP_CODE_MARKERS = [
@@ -57,22 +60,44 @@ function defaultReadText(p) {
         return null;
     }
 }
-function probeEngineVersion(binary) {
+function parseVersionFromOutput(out) {
+    const match = SEMVER_IN_TEXT_RE.exec(out);
+    return match?.[1] ?? null;
+}
+/**
+ * Prefer the engine version from the already-loaded core package when doctor /
+ * update are executing inside `@deftai/directive` (#2606).
+ */
+function readInProcessEngineVersion() {
+    const envVersion = process.env[ENV_VAR]?.trim();
+    if (envVersion) {
+        return parseVersionFromOutput(envVersion) ?? envVersion;
+    }
     try {
-        const out = execFileSync(binary, ["--version"], {
-            encoding: "utf8",
-            timeout: 5000,
-            stdio: ["ignore", "pipe", "ignore"],
-        });
-        const match = SEMVER_IN_TEXT_RE.exec(out);
-        return match?.[1] ?? null;
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+        if (!existsSync(pkgPath)) {
+            return null;
+        }
+        return readCorePackageVersion();
     }
     catch {
         return null;
     }
 }
-/** Default engine probe: try `directive --version`, then `deft --version`. */
+function probeEngineVersion(binary) {
+    const resolved = resolveCommandOnPath(binary);
+    const result = spawnCommandText(resolved ?? binary, ["--version"], { timeoutMs: 5000 });
+    if (result.status !== 0) {
+        return null;
+    }
+    return parseVersionFromOutput(result.stdout);
+}
+/** Default engine probe: in-process identity, then `directive` / `deft` on PATH. */
 export function defaultEngineProbe() {
+    const inProcess = readInProcessEngineVersion();
+    if (inProcess !== null) {
+        return { reachable: true, version: inProcess };
+    }
     for (const binary of ["directive", "deft"]) {
         const version = probeEngineVersion(binary);
         if (version !== null) {

package/dist/scope/project-definition-sync.js

@@ -1,158 +1,10 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { referenceTypeMatches } from "@deftai/directive-types";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
-import { formatVbriefJson } from "./vbrief-json.js";
-import { relativeToVbrief, resolveVbriefRef, scopeIdsForFilename } from "./vbrief-ref.js";
-function rewriteProjectDefinitionPlanReference(ref, oldResolved, newRel, vbriefRoot) {
-    if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
-        return false;
-    }
-    const r = ref;
-    if (!referenceTypeMatches(String(r.type ?? ""), "plan")) {
-        return false;
-    }
-    const resolved = resolveVbriefRef(r.uri, vbriefRoot);
-    if (resolved === null || resolve(resolved) !== resolve(oldResolved)) {
-        return false;
-    }
-    const uri = r.uri;
-    const newUri = typeof uri === "string" && uri.startsWith("file://") ? `file://${newRel}` : newRel;
-    if (newUri === uri) {
-        return false;
-    }
-    r.uri = newUri;
-    return true;
-}
-function projectItemReferencesScope(item, oldResolved, newResolved, vbriefRoot) {
-    const metadata = item.metadata;
-    if (typeof metadata === "object" && metadata !== null && !Array.isArray(metadata)) {
-        const meta = metadata;
-        const sourcePath = meta.source_path;
-        if (typeof sourcePath === "string") {
-            const resolved = resolveVbriefRef(sourcePath, vbriefRoot);
-            if (resolved !== null && [oldResolved, newResolved].includes(resolve(resolved))) {
-                return true;
-            }
-        }
-        const metadataRefs = meta.references;
-        if (Array.isArray(metadataRefs)) {
-            for (const ref of metadataRefs) {
-                if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
-                    continue;
-                }
-                const r = ref;
-                if (!referenceTypeMatches(String(r.type ?? ""), "plan")) {
-                    continue;
-                }
-                const resolved = resolveVbriefRef(r.uri, vbriefRoot);
-                if (resolved !== null && [oldResolved, newResolved].includes(resolve(resolved))) {
-                    return true;
-                }
-            }
-        }
-    }
-    const refs = item.references;
-    if (Array.isArray(refs)) {
-        for (const ref of refs) {
-            if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
-                continue;
-            }
-            const r = ref;
-            if (!referenceTypeMatches(String(r.type ?? ""), "plan")) {
-                continue;
-            }
-            const resolved = resolveVbriefRef(r.uri, vbriefRoot);
-            if (resolved !== null && [oldResolved, newResolved].includes(resolve(resolved))) {
-                return true;
-            }
-        }
-    }
-    return false;
-}
-function projectItemMatchesScope(item, scopeData, oldPath, newPath, vbriefRoot) {
-    const oldResolved = resolve(oldPath);
-    const newResolved = resolve(newPath);
-    if (projectItemReferencesScope(item, oldResolved, newResolved, vbriefRoot)) {
-        return true;
-    }
-    const itemId = item.id;
-    if (typeof itemId === "string" &&
-        scopeIdsForFilename(resolve(newPath).split(/[/\\]/).pop() ?? "").has(itemId)) {
-        return true;
-    }
-    const scopePlan = scopeData.plan;
-    const scopeTitle = typeof scopePlan === "object" && scopePlan !== null && !Array.isArray(scopePlan)
-        ? scopePlan.title
-        : undefined;
-    const itemTitle = item.title;
-    return (typeof scopeTitle === "string" && typeof itemTitle === "string" && itemTitle === scopeTitle);
-}
+import { syncRegistryArtifactAfterScopeMove } from "./registry-artifact-sync.js";
 /** Best-effort sync of PROJECT-DEFINITION after a lifecycle move (#1527). */
 export function syncProjectDefinitionAfterScopeMove(scopeData, oldPath, newPath, vbriefRoot, targetStatus) {
-    const newRel = relativeToVbrief(newPath, vbriefRoot);
-    if (newRel === null) {
-        return;
-    }
     const projectRoot = dirname(resolve(vbriefRoot));
     const projectDefPath = resolveProjectDefinitionPath(projectRoot);
-    if (!existsSync(projectDefPath)) {
-        return;
-    }
-    try {
-        const projectDef = JSON.parse(readFileSync(projectDefPath, "utf8"));
-        const plan = projectDef.plan;
-        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
-            return;
-        }
-        const p = plan;
-        let changed = false;
-        const oldResolved = resolve(oldPath);
-        const refs = p.references;
-        if (Array.isArray(refs)) {
-            for (const ref of refs) {
-                if (rewriteProjectDefinitionPlanReference(ref, oldResolved, newRel, vbriefRoot)) {
-                    changed = true;
-                }
-            }
-        }
-        const items = p.items;
-        if (Array.isArray(items)) {
-            for (const item of items) {
-                if (typeof item !== "object" || item === null || Array.isArray(item)) {
-                    continue;
-                }
-                const i = item;
-                if (!projectItemMatchesScope(i, scopeData, oldPath, newPath, vbriefRoot)) {
-                    continue;
-                }
-                if (i.status !== targetStatus) {
-                    i.status = targetStatus;
-                    changed = true;
-                }
-                let metadata = i.metadata;
-                if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
-                    metadata = {};
-                    i.metadata = metadata;
-                }
-                const meta = metadata;
-                const targetFolder = dirname(resolve(newPath)).split(/[/\\]/).pop() ?? "";
-                if (meta.source_path !== newRel) {
-                    meta.source_path = newRel;
-                    changed = true;
-                }
-                if (meta.lifecycle_folder !== targetFolder) {
-                    meta.lifecycle_folder = targetFolder;
-                    changed = true;
-                }
-            }
-        }
-        if (changed) {
-            writeFileSync(projectDefPath, formatVbriefJson(projectDef), "utf8");
-        }
-    }
-    catch {
-        /* best-effort */
-    }
+    syncRegistryArtifactAfterScopeMove(projectDefPath, scopeData, oldPath, newPath, vbriefRoot, targetStatus);
 }
 //# sourceMappingURL=project-definition-sync.js.map

package/dist/scope/registry-artifact-sync.d.ts

@@ -0,0 +1,3 @@
+/** Best-effort sync of a registry artifact (PROJECT-DEFINITION, specification, etc.) after a lifecycle move. */
+export declare function syncRegistryArtifactAfterScopeMove(registryPath: string, scopeData: Record<string, unknown>, oldPath: string, newPath: string, vbriefRoot: string, targetStatus: string): void;
+//# sourceMappingURL=registry-artifact-sync.d.ts.map

package/dist/scope/registry-artifact-sync.js

@@ -0,0 +1,159 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { referenceTypeMatches } from "@deftai/directive-types";
+import { formatVbriefJson } from "./vbrief-json.js";
+import { relativeToVbrief, resolveVbriefRef, scopeIdsForFilename } from "./vbrief-ref.js";
+function rewriteRegistryPlanReference(ref, oldResolved, newRel, vbriefRoot) {
+    if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
+        return false;
+    }
+    const r = ref;
+    if (!referenceTypeMatches(String(r.type ?? ""), "plan")) {
+        return false;
+    }
+    const resolved = resolveVbriefRef(r.uri, vbriefRoot);
+    if (resolved === null || resolve(resolved) !== resolve(oldResolved)) {
+        return false;
+    }
+    const uri = r.uri;
+    const newUri = typeof uri === "string" && uri.startsWith("file://") ? `file://${newRel}` : newRel;
+    if (newUri === uri) {
+        return false;
+    }
+    r.uri = newUri;
+    return true;
+}
+function registryItemReferencesScope(item, oldResolved, newResolved, vbriefRoot) {
+    const metadata = item.metadata;
+    if (typeof metadata === "object" && metadata !== null && !Array.isArray(metadata)) {
+        const meta = metadata;
+        const sourcePath = meta.source_path;
+        if (typeof sourcePath === "string") {
+            const resolved = resolveVbriefRef(sourcePath, vbriefRoot);
+            if (resolved !== null && [oldResolved, newResolved].includes(resolve(resolved))) {
+                return true;
+            }
+        }
+        const metadataRefs = meta.references;
+        if (Array.isArray(metadataRefs)) {
+            for (const ref of metadataRefs) {
+                if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
+                    continue;
+                }
+                const r = ref;
+                if (!referenceTypeMatches(String(r.type ?? ""), "plan")) {
+                    continue;
+                }
+                const resolved = resolveVbriefRef(r.uri, vbriefRoot);
+                if (resolved !== null && [oldResolved, newResolved].includes(resolve(resolved))) {
+                    return true;
+                }
+            }
+        }
+    }
+    const refs = item.references;
+    if (Array.isArray(refs)) {
+        for (const ref of refs) {
+            if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
+                continue;
+            }
+            const r = ref;
+            if (!referenceTypeMatches(String(r.type ?? ""), "plan")) {
+                continue;
+            }
+            const resolved = resolveVbriefRef(r.uri, vbriefRoot);
+            if (resolved !== null && [oldResolved, newResolved].includes(resolve(resolved))) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function registryItemMatchesScope(item, scopeData, oldPath, newPath, vbriefRoot) {
+    const oldResolved = resolve(oldPath);
+    const newResolved = resolve(newPath);
+    if (registryItemReferencesScope(item, oldResolved, newResolved, vbriefRoot)) {
+        return true;
+    }
+    const itemId = item.id;
+    if (typeof itemId === "string" &&
+        scopeIdsForFilename(resolve(newPath).split(/[/\\]/).pop() ?? "").has(itemId)) {
+        return true;
+    }
+    const scopePlan = scopeData.plan;
+    const scopeTitle = typeof scopePlan === "object" && scopePlan !== null && !Array.isArray(scopePlan)
+        ? scopePlan.title
+        : undefined;
+    const itemTitle = item.title;
+    return (typeof scopeTitle === "string" && typeof itemTitle === "string" && itemTitle === scopeTitle);
+}
+/** Best-effort sync of a registry artifact (PROJECT-DEFINITION, specification, etc.) after a lifecycle move. */
+export function syncRegistryArtifactAfterScopeMove(registryPath, scopeData, oldPath, newPath, vbriefRoot, targetStatus) {
+    const newRel = relativeToVbrief(newPath, vbriefRoot);
+    if (newRel === null) {
+        return;
+    }
+    if (!existsSync(registryPath)) {
+        return;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(registryPath, "utf8"));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return;
+        }
+        const registry = parsed;
+        const plan = registry.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+            return;
+        }
+        const p = plan;
+        let changed = false;
+        const oldResolved = resolve(oldPath);
+        const refs = p.references;
+        if (Array.isArray(refs)) {
+            for (const ref of refs) {
+                if (rewriteRegistryPlanReference(ref, oldResolved, newRel, vbriefRoot)) {
+                    changed = true;
+                }
+            }
+        }
+        const items = p.items;
+        if (Array.isArray(items)) {
+            for (const item of items) {
+                if (typeof item !== "object" || item === null || Array.isArray(item)) {
+                    continue;
+                }
+                const i = item;
+                if (!registryItemMatchesScope(i, scopeData, oldPath, newPath, vbriefRoot)) {
+                    continue;
+                }
+                if (i.status !== targetStatus) {
+                    i.status = targetStatus;
+                    changed = true;
+                }
+                let metadata = i.metadata;
+                if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
+                    metadata = {};
+                    i.metadata = metadata;
+                }
+                const meta = metadata;
+                const targetFolder = dirname(resolve(newPath)).split(/[/\\]/).pop() ?? "";
+                if (meta.source_path !== newRel) {
+                    meta.source_path = newRel;
+                    changed = true;
+                }
+                if (meta.lifecycle_folder !== targetFolder) {
+                    meta.lifecycle_folder = targetFolder;
+                    changed = true;
+                }
+            }
+        }
+        if (changed) {
+            writeFileSync(registryPath, formatVbriefJson(registry), "utf8");
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+}
+//# sourceMappingURL=registry-artifact-sync.js.map

package/dist/scope/specification-sync.d.ts

@@ -0,0 +1,3 @@
+/** Best-effort sync of specification.xbrief.json after a lifecycle move (#2566). */
+export declare function syncSpecificationAfterScopeMove(scopeData: Record<string, unknown>, oldPath: string, newPath: string, vbriefRoot: string, targetStatus: string): void;
+//# sourceMappingURL=specification-sync.d.ts.map

package/dist/scope/specification-sync.js

@@ -0,0 +1,16 @@
+import { dirname, resolve } from "node:path";
+import { resolveSpecArtifactPath } from "../layout/resolve.js";
+import { syncRegistryArtifactAfterScopeMove } from "./registry-artifact-sync.js";
+/** Best-effort sync of specification.xbrief.json after a lifecycle move (#2566). */
+export function syncSpecificationAfterScopeMove(scopeData, oldPath, newPath, vbriefRoot, targetStatus) {
+    const projectRoot = dirname(resolve(vbriefRoot));
+    let specPath;
+    try {
+        specPath = resolveSpecArtifactPath(projectRoot);
+    }
+    catch {
+        return;
+    }
+    syncRegistryArtifactAfterScopeMove(specPath, scopeData, oldPath, newPath, vbriefRoot, targetStatus);
+}
+//# sourceMappingURL=specification-sync.js.map