@deftai/directive-core 0.78.0 → 0.79.1

package/dist/release-e2e/flags.js

@@ -3,6 +3,10 @@ import { REPO_SLUG_PREFIX } from "./constants.js";
 export function emit(label, status) {
     process.stderr.write(`[e2e] ${label}... ${status}\n`);
 }
+/** Copy-paste cleanup hint for leftover release-e2e temp repos (#2572). */
+export function formatTempRepoCleanupHint(owner, slug) {
+    return `gh repo delete ${owner}/${slug} --yes`;
+}
 export function generateRepoSlug(seams = {}) {
     if (seams.generateRepoSlug) {
         return seams.generateRepoSlug();
@@ -22,7 +26,7 @@ export function parseE2EFlags(argv) {
     let help = false;
     let owner = "deftai";
     let dryRun = false;
-    let keepRepo = false;
+    let destroyRepo = false;
     let projectRoot = null;
     let skipNpm = false;
     let legacyBridge = false;
@@ -37,8 +41,8 @@ export function parseE2EFlags(argv) {
         else if (arg === "--dry-run") {
             dryRun = true;
         }
-        else if (arg === "--keep-repo") {
-            keepRepo = true;
+        else if (arg === "--destroy-repo") {
+            destroyRepo = true;
         }
         else if (arg === "--skip-npm") {
             skipNpm = true;
@@ -79,6 +83,6 @@ export function parseE2EFlags(argv) {
             unknown.push(arg);
         }
     }
-    return { help, owner, dryRun, keepRepo, projectRoot, skipNpm, legacyBridge, unknown };
+    return { help, owner, dryRun, destroyRepo, projectRoot, skipNpm, legacyBridge, unknown };
 }
 //# sourceMappingURL=flags.js.map

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

package/dist/scope/transition.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, renameSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { InstrumentedVbriefCrud, persistCrudMetrics } from "../eval/crud-telemetry.js";
 import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
@@ -8,6 +8,7 @@ import { stampCompletionMetadata } from "./capacity-stamp.js";
 import { LIFECYCLE_FOLDERS, MOVE_LABELS, STATUS_PRECONDITIONS, STAY_LABELS, TRANSITIONS, } from "./constants.js";
 import { detectLifecycleFolder, updateDecomposedChildBackReferences, updateDecomposedParentBackReferences, } from "./decomposed-refs.js";
 import { syncProjectDefinitionAfterScopeMove } from "./project-definition-sync.js";
+import { syncSpecificationAfterScopeMove } from "./specification-sync.js";
 import { formatVbriefJson, utcNowIso } from "./vbrief-json.js";
 export function runTransition(action, filePath, now = new Date()) {
     if (!(action in TRANSITIONS)) {
@@ -101,30 +102,57 @@ export function runTransition(action, filePath, now = new Date()) {
     }
     const formatted = formatVbriefJson(data);
     const crud = new InstrumentedVbriefCrud({ now: () => now });
-    const writeResult = crud.update(resolvedPath, formatted, { trustedWrite: true });
-    if (!writeResult.ok) {
-        return { ok: false, message: writeResult.error ?? `CRUD update failed for ${resolvedPath}` };
-    }
-    try {
-        persistCrudMetrics(projectRoot, crud.getMetrics());
-    }
-    catch {
-        /* best-effort telemetry persistence */
-    }
     if (targetFolder !== null) {
         const destDir = join(vbriefRoot, targetFolder);
         mkdirSync(destDir, { recursive: true });
         const destPath = join(destDir, basename);
-        renameSync(resolvedPath, destPath);
+        if (existsSync(destPath)) {
+            return { ok: false, message: `Target already exists: ${destPath}` };
+        }
+        // #2578: stamp terminal status at the destination path in the same write as
+        // folder placement — never leave a non-terminal status under completed/.
+        const writeResult = crud.update(destPath, formatted, { trustedWrite: true });
+        if (!writeResult.ok) {
+            return { ok: false, message: writeResult.error ?? `CRUD update failed for ${destPath}` };
+        }
+        try {
+            unlinkSync(resolvedPath);
+        }
+        catch (err) {
+            try {
+                unlinkSync(destPath);
+            }
+            catch {
+                /* best-effort rollback */
+            }
+            return { ok: false, message: `Failed to remove source after move: ${String(err)}` };
+        }
+        try {
+            persistCrudMetrics(projectRoot, crud.getMetrics());
+        }
+        catch {
+            /* best-effort telemetry persistence */
+        }
         updateDecomposedParentBackReferences(data, resolvedPath, destPath, vbriefRoot);
         updateDecomposedChildBackReferences(data, resolvedPath, destPath, vbriefRoot);
         syncProjectDefinitionAfterScopeMove(data, resolvedPath, destPath, vbriefRoot, targetStatus);
+        syncSpecificationAfterScopeMove(data, resolvedPath, destPath, vbriefRoot, targetStatus);
         const actionLabel = MOVE_LABELS[act] ?? act.charAt(0).toUpperCase() + act.slice(1);
         return {
             ok: true,
             message: `${actionLabel} ${basename}: ${currentFolder}/ -> ${targetFolder}/ (status: ${targetStatus})`,
         };
     }
+    const writeResult = crud.update(resolvedPath, formatted, { trustedWrite: true });
+    if (!writeResult.ok) {
+        return { ok: false, message: writeResult.error ?? `CRUD update failed for ${resolvedPath}` };
+    }
+    try {
+        persistCrudMetrics(projectRoot, crud.getMetrics());
+    }
+    catch {
+        /* best-effort telemetry persistence */
+    }
     const actionLabel = STAY_LABELS[act] ?? act.charAt(0).toUpperCase() + act.slice(1);
     return {
         ok: true,

package/dist/session/cache-recovery.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Format a consumer-runnable `deft cache fetch-all` recovery command (#2574).
+ *
+ * Uses the space-separated CLI surface (not the colon task alias) and always
+ * includes required `--source` / `--repo` flags so following the hint literally
+ * reaches the handler instead of `unknown verb 'cache:fetch-all'`.
+ */
+export declare function formatCacheFetchAllRecoveryCommand(repo: string | null, options?: {
+    force?: boolean;
+}): string;
+/**
+ * Branch-aware recovery hint (#1953 Option 3, #2574 argv fix).
+ * Age-stale (or age+drift mixed) → --force bypasses TTL; drift-only → plain refetch.
+ */
+export declare function recoveryHintForStaleFailure(causes: Readonly<{
+    ageStale: boolean;
+    driftDetected: boolean;
+}>, repo?: string | null): string;
+//# sourceMappingURL=cache-recovery.d.ts.map