@deftai/directive-core 0.81.0 → 0.83.0

package/dist/product-signal/submit.d.ts

@@ -32,7 +32,11 @@ export declare function runProductSignalEnable(projectRoot: string | null, confi
     exitCode: 0 | 1 | 2;
     text: string;
 };
-export declare function runProductSignalConsent(action: "grant" | "revoke"): {
+export interface ProductSignalConsentRunOptions {
+    readonly action: "grant" | "revoke";
+    readonly projectRoot?: string | null;
+}
+export declare function runProductSignalConsent(options: ProductSignalConsentRunOptions): {
     exitCode: 0 | 1;
     text: string;
 };

package/dist/product-signal/submit.js

@@ -3,7 +3,7 @@ import { join, resolve } from "node:path";
 import { enableProductSignal, formatProductSignalStatusLine, resolveProductSignal, } from "../policy/product-signal.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
 import { resolveActorName } from "./actor-name.js";
-import { grantProductSignalConsent, isProductSignalConsented, readProductSignalConsent, revokeProductSignalConsent, } from "./consent.js";
+import { authorizeProductSignalSink, grantProductSignalConsent, readProductSignalConsent, revokeProductSignalConsent, } from "./consent.js";
 import { evaluateProductSignalGates } from "./gates.js";
 import { GitHubPrivateSinkAdapter } from "./github-private-sink-adapter.js";
 import { collectInstallContext } from "./install-context.js";
@@ -105,15 +105,25 @@ export async function submitProductSignal(options) {
             payload,
         };
     }
+    const policy = resolveProductSignal(root);
+    const consent = readProductSignalConsent();
+    const sinkAuth = authorizeProductSignalSink(policy.sinkRepo, consent);
+    if (!sinkAuth.authorized) {
+        return {
+            outcome: "sink-unconsented",
+            exitCode: 0,
+            message: `${sinkAuth.message}\n`,
+            payload,
+        };
+    }
     if (options.dryRun) {
         return {
             outcome: "dry-run",
             exitCode: 0,
-            message: `[dry-run] payload valid for ${payload.surface}\n`,
+            message: `[dry-run] payload valid for ${payload.surface} (sink=${sinkAuth.configuredSink})\n`,
             payload,
         };
     }
-    const policy = resolveProductSignal(root);
     const adapter = new GitHubPrivateSinkAdapter({ sinkRepo: policy.sinkRepo });
     const result = await adapter.submit(payload, { gapText: options.gapText });
     if (result.outcome === "submitted") {
@@ -131,11 +141,13 @@ export async function submitProductSignal(options) {
 export function runProductSignalStatus(projectRoot) {
     const root = resolveProjectRoot(projectRoot ?? undefined) ?? process.cwd();
     const policy = resolveProductSignal(root);
-    const consented = isProductSignalConsented();
+    const consent = readProductSignalConsent();
+    const configuredSink = policy.sinkRepo;
+    const sinkAuth = authorizeProductSignalSink(configuredSink, consent);
     const last = readLastSubmitSummary(root);
     const lines = [
         formatProductSignalStatusLine(policy),
-        `[deft product-signal] consented=${String(consented)}`,
+        `[deft product-signal] consented=${String(consent !== null)} configuredSink=${configuredSink} consentedSink=${sinkAuth.consentedSink ?? "none"} sinksMatch=${String(sinkAuth.sinksMatch)}`,
         last ? `[deft product-signal] ${last}` : "[deft product-signal] last submit: none",
     ];
     return { exitCode: 0, text: `${lines.join("\n")}\n` };
@@ -148,12 +160,15 @@ export function runProductSignalEnable(projectRoot, confirm) {
     const result = enableProductSignal(root, { confirm });
     return { exitCode: result.exitCode, text: result.stdout };
 }
-export function runProductSignalConsent(action) {
-    if (action === "grant") {
-        const record = grantProductSignalConsent();
+export function runProductSignalConsent(options) {
+    if (options.action === "grant") {
+        const root = resolveProjectRoot(options.projectRoot ?? undefined);
+        const sinkRepo = root !== null ? resolveProductSignal(root).sinkRepo : undefined;
+        const record = grantProductSignalConsent({ sinkRepo });
         return {
             exitCode: 0,
-            text: `product-signal consent granted (tier=${record.tier}, version=${record.consentVersion}).\n`,
+            text: `product-signal consent granted (tier=${record.tier}, version=${record.consentVersion}, ` +
+                `sinkRepo=${record.sinkRepo ?? "unknown"}).\n`,
         };
     }
     const ok = revokeProductSignalConsent();
@@ -216,24 +231,29 @@ export function parseProductSignalSubmitArgs(argv) {
     }
     return { surface, dryRun, json, projectRoot, nps };
 }
+function parseOptionalProjectRootArg(argv, fallback) {
+    const rootIdx = argv.indexOf("--project-root");
+    if (rootIdx >= 0) {
+        return argv[rootIdx + 1] ?? fallback;
+    }
+    const eqArg = argv.find((a) => a.startsWith("--project-root="));
+    if (eqArg !== undefined) {
+        return eqArg.slice("--project-root=".length) || fallback;
+    }
+    return fallback;
+}
 /** CLI module entrypoint for dispatch (#2693). */
 export async function productSignalMain(argv = process.argv.slice(2)) {
     const sub = argv[0];
     if (sub === "status") {
-        const rootIdx = argv.indexOf("--project-root");
-        const root = rootIdx >= 0
-            ? (argv[rootIdx + 1] ?? ".")
-            : (argv.find((a) => a.startsWith("--project-root="))?.split("=")[1] ?? ".");
+        const root = parseOptionalProjectRootArg(argv, ".") ?? ".";
         const result = runProductSignalStatus(root);
         process.stdout.write(result.text);
         return result.exitCode;
     }
     if (sub === "enable") {
         const confirm = argv.includes("--confirm");
-        const rootIdx = argv.indexOf("--project-root");
-        const root = rootIdx >= 0
-            ? (argv[rootIdx + 1] ?? ".")
-            : (argv.find((a) => a.startsWith("--project-root="))?.split("=")[1] ?? ".");
+        const root = parseOptionalProjectRootArg(argv, ".") ?? ".";
         const result = runProductSignalEnable(root, confirm);
         process.stdout.write(result.text);
         return result.exitCode;
@@ -245,7 +265,11 @@ export async function productSignalMain(argv = process.argv.slice(2)) {
             process.stderr.write("usage: product-signal consent -- --grant|--revoke\n");
             return 1;
         }
-        const result = runProductSignalConsent(grant ? "grant" : "revoke");
+        const root = parseOptionalProjectRootArg(argv, null);
+        const result = runProductSignalConsent({
+            action: grant ? "grant" : "revoke",
+            projectRoot: root,
+        });
         process.stdout.write(result.text);
         return result.exitCode;
     }

package/dist/release/native-steps.js

@@ -6,7 +6,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { isTerminalLifecyclePath, reconcile, scanVbriefDir } from "../intake/reconcile-issues.js";
+import { buildLifecycleReport, isTerminalLifecyclePath, scanLifecycleAnchors, } from "../intake/reconcile-issues.js";
 import { LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, resolveLifecycleFolder, resolveLifecycleRoot, } from "../layout/resolve.js";
 import { renderRoadmap } from "../render/roadmap-render.js";
 import { fetchIssueStatesForRelease } from "./issue-state-fetch.js";
@@ -35,15 +35,22 @@ export function checkVbriefLifecycleSyncNative(projectRoot, repo) {
         vbriefDir = join(projectRoot, MIGRATED_ARTIFACT_DIR);
     }
     try {
-        const issueToVbriefs = scanVbriefDir(vbriefDir);
-        const fetchResult = fetchIssueStatesForRelease(repo, new Set(issueToVbriefs.keys()), {
+        const anchors = scanLifecycleAnchors(vbriefDir);
+        const anchorIssueNumbers = new Set();
+        for (const anchor of anchors) {
+            const num = anchor.issue_number;
+            if (num !== null) {
+                anchorIssueNumbers.add(num);
+            }
+        }
+        const fetchResult = fetchIssueStatesForRelease(repo, anchorIssueNumbers, {
             cwd: projectRoot,
         });
         if (!fetchResult.ok) {
             return [false, -1, fetchResult.reason];
         }
         const issueStateMap = fetchResult.states;
-        const report = reconcile(issueToVbriefs, issueStateMap);
+        const report = buildLifecycleReport(anchors, issueStateMap, false);
         const mismatches = [];
         for (const entry of report.no_open_issue) {
             const files = (entry.vbrief_files ?? []);

package/dist/render/framework-commands.js

@@ -82,6 +82,9 @@ export const COMMANDS = {
     "verify:wip-cap": spec("verify:wip-cap", "preflight_wip_cap:main", {
         projectRootArg: "--project-root",
     }),
+    "verify:orphan-active": spec("verify:orphan-active", "verify_orphan_active:main", {
+        projectRootArg: "--project-root",
+    }),
     "verify:pack-drift": spec("verify:pack-drift", "pack_render:main", {
         defaultArgs: ["--check"],
         cwd: "framework",
@@ -102,6 +105,7 @@ export const COMMANDS = {
         "verify:branch",
         "verify:cache-fresh",
         "verify:wip-cap",
+        "verify:orphan-active",
         "vbrief:validate",
         "verify-strategy-output",
     ]),
@@ -120,6 +124,7 @@ export const COMMANDS = {
         "verify:cache-fresh",
         "verify:pack-drift",
         "verify:wip-cap",
+        "verify:orphan-active",
         "vbrief:validate",
         "verify-strategy-output",
     ]),
@@ -293,6 +298,7 @@ const ENTRYPOINT_VERB = {
     "verify_no_task_runtime:main": "verify-no-task-runtime",
     "preflight_cache:main": "preflight-cache",
     "preflight_wip_cap:main": "verify-wip-cap",
+    "verify_orphan_active:main": "verify-orphan-active",
     "pack_render:main": "pack-render",
     "validate_strategy_output:main": "validate-strategy-output",
     "vbrief_validate:main": "vbrief-validate",

package/dist/scope/brief-io.d.ts

@@ -0,0 +1,26 @@
+import type { JsonObject } from "../vbrief-build/types.js";
+export declare class BriefIOError extends Error {
+    constructor(message: string);
+}
+/** Canonical brief serialization (single source of truth with vbrief-build). */
+export declare function formatBriefJson(data: unknown): string;
+export type ReadBriefResult = {
+    readonly ok: true;
+    readonly data: JsonObject;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** Read a scope brief for in-memory mutation (parse only; no validation gate on read). */
+export declare function readBriefForMutation(filePath: string): ReadBriefResult;
+/** Fail-closed schema + folder/status validation before persist. */
+export declare function validateBriefForPersist(filePath: string, data: JsonObject, vbriefRoot: string): string | null;
+export type AtomicWriteBriefResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** Validate then atomically persist a brief (temp file + rename). */
+export declare function atomicWriteBrief(filePath: string, data: JsonObject, vbriefRoot: string): AtomicWriteBriefResult;
+//# sourceMappingURL=brief-io.d.ts.map

package/dist/scope/brief-io.js

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { atomicWriteText } from "../cache/io.js";
+import { hasArtifactSuffix } from "../layout/resolve.js";
+import { pythonJsonPretty } from "../vbrief-build/json.js";
+import { validateFolderStatus } from "../vbrief-validate/folder-status.js";
+import { validateVbriefSchema } from "../vbrief-validate/schema.js";
+export class BriefIOError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BriefIOError";
+    }
+}
+/** Canonical brief serialization (single source of truth with vbrief-build). */
+export function formatBriefJson(data) {
+    return pythonJsonPretty(data);
+}
+/** Read a scope brief for in-memory mutation (parse only; no validation gate on read). */
+export function readBriefForMutation(filePath) {
+    const resolvedPath = resolve(filePath);
+    if (!existsSync(resolvedPath)) {
+        return { ok: false, message: `File not found: ${resolvedPath}` };
+    }
+    const basename = resolvedPath.split(/[/\\]/).pop() ?? "";
+    if (!hasArtifactSuffix(basename)) {
+        return {
+            ok: false,
+            message: `Not a vBRIEF file (expected .vbrief.json or .xbrief.json): ${basename}`,
+        };
+    }
+    let raw;
+    try {
+        raw = readFileSync(resolvedPath, "utf8");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, message: `Could not read ${resolvedPath}: ${msg}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return { ok: false, message: `Invalid JSON in ${resolvedPath}: ${String(err)}` };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { ok: false, message: `Top-level value in ${resolvedPath} is not a JSON object` };
+    }
+    return { ok: true, data: parsed };
+}
+/** Fail-closed schema + folder/status validation before persist. */
+export function validateBriefForPersist(filePath, data, vbriefRoot) {
+    const errors = [
+        ...validateVbriefSchema(data, filePath),
+        ...validateFolderStatus(filePath, data, vbriefRoot),
+    ];
+    if (errors.length === 0) {
+        return null;
+    }
+    return errors.join("; ");
+}
+/** Validate then atomically persist a brief (temp file + rename). */
+export function atomicWriteBrief(filePath, data, vbriefRoot) {
+    const validationError = validateBriefForPersist(filePath, data, vbriefRoot);
+    if (validationError !== null) {
+        return { ok: false, message: validationError };
+    }
+    try {
+        atomicWriteText(filePath, formatBriefJson(data));
+        return { ok: true };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, message: `Failed to write ${filePath}: ${msg}` };
+    }
+}
+//# sourceMappingURL=brief-io.js.map

package/dist/scope/decompose.js

@@ -12,7 +12,7 @@ import { referenceTypeMatches } from "@deftai/directive-types";
 import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, resolveLifecycleRoot, } from "../layout/resolve.js";
 import { referenceWithDefaultTrust, slugify } from "../vbrief-build/build.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
-import { formatVbriefJson } from "./vbrief-json.js";
+import { formatBriefJson } from "./vbrief-json.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -54,7 +54,7 @@ function loadJson(path) {
 }
 function writeJson(path, data) {
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, formatVbriefJson(data), "utf8");
+    writeFileSync(path, formatBriefJson(data), "utf8");
 }
 // ---------------------------------------------------------------------------
 // Story quality helpers (ported from _vbrief_story_quality.py)

package/dist/scope/decomposed-refs.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
-import { formatVbriefJson } from "./vbrief-json.js";
+import { formatBriefJson } from "./vbrief-json.js";
 import { collectChildUris, collectPlanRefs, resolveVbriefRef } from "./vbrief-ref.js";
 function rewriteOnePlanRef(value, oldParentResolved, newParentRel, vbriefDir) {
     if (typeof value !== "string" || value.length === 0) {
@@ -53,7 +53,7 @@ function rewriteParentChildReference(parentPath, oldChildResolved, newChildRel,
     }
     if (changed) {
         try {
-            writeFileSync(parentPath, formatVbriefJson(parentData), "utf8");
+            writeFileSync(parentPath, formatBriefJson(parentData), "utf8");
         }
         catch {
             return false;
@@ -127,7 +127,7 @@ function rewriteChildParentReference(childPath, oldParentResolved, newParentRel,
     }
     if (changed) {
         try {
-            writeFileSync(childPath, formatVbriefJson(childData), "utf8");
+            writeFileSync(childPath, formatBriefJson(childData), "utf8");
         }
         catch {
             return false;

package/dist/scope/demote.js

@@ -5,7 +5,7 @@ import { hasArtifactSuffix, resolveLifecycleFolder } from "../layout/resolve.js"
 import { stripTrailingPathSeparators } from "../text/redos-safe.js";
 import { append, canonicalLogPath, latestForPath, newDecisionId } from "./audit-log.js";
 import { resolveProjectRoot } from "./project-context.js";
-import { formatVbriefJson, utcNowIso } from "./vbrief-json.js";
+import { formatBriefJson, utcNowIso } from "./vbrief-json.js";
 import { canonicalRelpath } from "./vbrief-ref.js";
 export const DEFAULT_OLDER_THAN_DAYS = 45;
 export const SOURCE_FOLDER = "pending";
@@ -85,7 +85,7 @@ export function demoteOne(filePath, projectRoot, reason, options = {}) {
     const timestamp = utcNowIso(now);
     planObj.status = TARGET_STATUS;
     planObj.updated = timestamp;
-    writeFileSync(resolved, formatVbriefJson(data), "utf8");
+    writeFileSync(resolved, formatBriefJson(data), "utf8");
     const vbriefRoot = dirname(dirname(resolved));
     const targetDir = join(vbriefRoot, TARGET_FOLDER);
     mkdirSync(targetDir, { recursive: true });

package/dist/scope/project-definition-sync.d.ts

@@ -1,3 +1,3 @@
-/** Best-effort sync of PROJECT-DEFINITION after a lifecycle move (#1527). */
-export declare function syncProjectDefinitionAfterScopeMove(scopeData: Record<string, unknown>, oldPath: string, newPath: string, vbriefRoot: string, targetStatus: string): void;
+/** Fail-closed sync of PROJECT-DEFINITION after a lifecycle move (#1527 / #2131). */
+export declare function syncProjectDefinitionAfterScopeMove(scopeData: Record<string, unknown>, oldPath: string, newPath: string, vbriefRoot: string, targetStatus: string): string | null;
 //# sourceMappingURL=project-definition-sync.d.ts.map

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

@@ -1,10 +1,22 @@
 import { dirname, resolve } from "node:path";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
+import { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
 import { syncRegistryArtifactAfterScopeMove } from "./registry-artifact-sync.js";
-/** Best-effort sync of PROJECT-DEFINITION after a lifecycle move (#1527). */
+/** Fail-closed sync of PROJECT-DEFINITION after a lifecycle move (#1527 / #2131). */
 export function syncProjectDefinitionAfterScopeMove(scopeData, oldPath, newPath, vbriefRoot, targetStatus) {
     const projectRoot = dirname(resolve(vbriefRoot));
-    const projectDefPath = resolveProjectDefinitionPath(projectRoot);
-    syncRegistryArtifactAfterScopeMove(projectDefPath, scopeData, oldPath, newPath, vbriefRoot, targetStatus);
+    try {
+        projectDefinitionMutationLock(projectRoot, () => {
+            const projectDefPath = resolveProjectDefinitionPath(projectRoot);
+            syncRegistryArtifactAfterScopeMove(projectDefPath, scopeData, oldPath, newPath, vbriefRoot, targetStatus, {
+                loadForMutation: () => loadProjectDefinitionForMutation(projectRoot),
+                persist: (path, data) => atomicWriteProjectDefinition(path, data),
+            });
+        });
+        return null;
+    }
+    catch (err) {
+        return err instanceof Error ? err.message : String(err);
+    }
 }
 //# sourceMappingURL=project-definition-sync.js.map

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

@@ -1,3 +1,8 @@
+import type { JsonObject } from "../vbrief-build/types.js";
+export interface RegistryArtifactPersistHooks {
+    readonly loadForMutation?: () => [JsonObject, string];
+    readonly persist?: (path: string, data: JsonObject) => void;
+}
 /** 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;
+export declare function syncRegistryArtifactAfterScopeMove(registryPath: string, scopeData: Record<string, unknown>, oldPath: string, newPath: string, vbriefRoot: string, targetStatus: string, hooks?: RegistryArtifactPersistHooks): void;
 //# sourceMappingURL=registry-artifact-sync.d.ts.map

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

@@ -1,7 +1,8 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
-import { formatVbriefJson } from "./vbrief-json.js";
+import { atomicWriteText } from "../cache/io.js";
+import { formatBriefJson } from "./brief-io.js";
 import { relativeToVbrief, resolveVbriefRef, scopeIdsForFilename } from "./vbrief-ref.js";
 function rewriteRegistryPlanReference(ref, oldResolved, newRel, vbriefRoot) {
     if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
@@ -88,20 +89,30 @@ function registryItemMatchesScope(item, scopeData, oldPath, newPath, vbriefRoot)
     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) {
+export function syncRegistryArtifactAfterScopeMove(registryPath, scopeData, oldPath, newPath, vbriefRoot, targetStatus, hooks = {}) {
     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;
+        let registry;
+        if (hooks.loadForMutation !== undefined) {
+            if (!existsSync(registryPath)) {
+                return;
+            }
+            const [loaded] = hooks.loadForMutation();
+            registry = loaded;
+        }
+        else {
+            if (!existsSync(registryPath)) {
+                return;
+            }
+            const parsed = JSON.parse(readFileSync(registryPath, "utf8"));
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                return;
+            }
+            registry = parsed;
         }
-        const registry = parsed;
         const plan = registry.plan;
         if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
             return;
@@ -149,11 +160,18 @@ export function syncRegistryArtifactAfterScopeMove(registryPath, scopeData, oldP
             }
         }
         if (changed) {
-            writeFileSync(registryPath, formatVbriefJson(registry), "utf8");
+            if (hooks.persist !== undefined) {
+                hooks.persist(registryPath, registry);
+            }
+            else {
+                atomicWriteText(registryPath, formatBriefJson(registry));
+            }
         }
     }
-    catch {
-        /* best-effort */
+    catch (err) {
+        if (hooks.loadForMutation !== undefined || hooks.persist !== undefined) {
+            throw err;
+        }
     }
 }
 //# sourceMappingURL=registry-artifact-sync.js.map

package/dist/scope/transition.js

@@ -1,15 +1,16 @@
-import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
+import { existsSync, mkdirSync, 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";
 import { hasArtifactSuffix } from "../layout/resolve.js";
 import { append, canonicalLogPath, newDecisionId } from "./audit-log.js";
+import { atomicWriteBrief, formatBriefJson, readBriefForMutation } from "./brief-io.js";
 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";
+import { utcNowIso } from "./vbrief-json.js";
 export function runTransition(action, filePath, now = new Date()) {
     if (!(action in TRANSITIONS)) {
         const valid = Object.keys(TRANSITIONS).sort().join(", ");
@@ -43,13 +44,11 @@ export function runTransition(action, filePath, now = new Date()) {
                 `File is in ${currentFolder}/.`,
         };
     }
-    let data;
-    try {
-        data = JSON.parse(readFileSync(resolvedPath, "utf8"));
-    }
-    catch (err) {
-        return { ok: false, message: `Invalid JSON in ${resolvedPath}: ${String(err)}` };
+    const readResult = readBriefForMutation(resolvedPath);
+    if (!readResult.ok) {
+        return { ok: false, message: readResult.message };
     }
+    const data = readResult.data;
     const plan = data.plan;
     if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
         return { ok: false, message: `Missing or invalid 'plan' object in ${resolvedPath}` };
@@ -100,7 +99,7 @@ export function runTransition(action, filePath, now = new Date()) {
     if (act === "complete") {
         stampCompletionMetadata(planObj, projectRoot, nowIso);
     }
-    const formatted = formatVbriefJson(data);
+    const formatted = formatBriefJson(data);
     const crud = new InstrumentedVbriefCrud({ now: () => now });
     if (targetFolder !== null) {
         const destDir = join(vbriefRoot, targetFolder);
@@ -111,10 +110,11 @@ export function runTransition(action, filePath, now = new Date()) {
         }
         // #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 });
+        const writeResult = atomicWriteBrief(destPath, data, vbriefRoot);
         if (!writeResult.ok) {
-            return { ok: false, message: writeResult.error ?? `CRUD update failed for ${destPath}` };
+            return { ok: false, message: writeResult.message };
         }
+        crud.recordTrustedUpdate(destPath, formatted);
         try {
             unlinkSync(resolvedPath);
         }
@@ -135,18 +135,26 @@ export function runTransition(action, filePath, now = new Date()) {
         }
         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);
+        const pdSyncError = syncProjectDefinitionAfterScopeMove(data, resolvedPath, destPath, vbriefRoot, targetStatus);
+        if (pdSyncError !== null) {
+            return {
+                ok: false,
+                message: `${actionLabel} ${basename}: brief moved to ${targetFolder}/ but ` +
+                    `PROJECT-DEFINITION sync failed: ${pdSyncError}`,
+            };
+        }
+        syncSpecificationAfterScopeMove(data, resolvedPath, destPath, vbriefRoot, targetStatus);
         return {
             ok: true,
             message: `${actionLabel} ${basename}: ${currentFolder}/ -> ${targetFolder}/ (status: ${targetStatus})`,
         };
     }
-    const writeResult = crud.update(resolvedPath, formatted, { trustedWrite: true });
+    const writeResult = atomicWriteBrief(resolvedPath, data, vbriefRoot);
     if (!writeResult.ok) {
-        return { ok: false, message: writeResult.error ?? `CRUD update failed for ${resolvedPath}` };
+        return { ok: false, message: writeResult.message };
     }
+    crud.recordTrustedUpdate(resolvedPath, formatted);
     try {
         persistCrudMetrics(projectRoot, crud.getMetrics());
     }

package/dist/scope/undo.js

@@ -4,7 +4,7 @@ import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/project
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { append, canonicalLogPath, newDecisionId, readAll } from "./audit-log.js";
 import { REVERSIBLE_ACTIONS, TERMINAL_ACTIONS } from "./constants.js";
-import { formatVbriefJson, utcNowIso } from "./vbrief-json.js";
+import { formatBriefJson, utcNowIso } from "./vbrief-json.js";
 function vbriefRoot(projectRoot) {
     return resolveLifecycleRoot(projectRoot);
 }
@@ -185,7 +185,7 @@ function moveAndFlip(srcFile, destFolder, newStatus, timestamp, projectRoot) {
     const planObj = plan;
     planObj.status = newStatus;
     planObj.updated = timestamp;
-    writeFileSync(srcFile, formatVbriefJson(data), "utf8");
+    writeFileSync(srcFile, formatBriefJson(data), "utf8");
     mkdirSync(destFolder, { recursive: true });
     const destPath = join(destFolder, basename(srcFile));
     renameSync(srcFile, destPath);

package/dist/scope/vbrief-json.d.ts

@@ -1,4 +1,3 @@
-/** Format vBRIEF JSON like Python json.dumps(..., indent=2, ensure_ascii=False) + newline. */
-export declare function formatVbriefJson(data: unknown): string;
+export { formatBriefJson } from "./brief-io.js";
 export declare function utcNowIso(now?: Date): string;
 //# sourceMappingURL=vbrief-json.d.ts.map

package/dist/scope/vbrief-json.js

@@ -1,7 +1,4 @@
-/** Format vBRIEF JSON like Python json.dumps(..., indent=2, ensure_ascii=False) + newline. */
-export function formatVbriefJson(data) {
-    return `${JSON.stringify(data, null, 2)}\n`;
-}
+export { formatBriefJson } from "./brief-io.js";
 export function utcNowIso(now = new Date()) {
     return now.toISOString().replace(/\.\d{3}Z$/, "Z");
 }