@deftai/directive-core 0.107.0 → 0.108.0

package/dist/swarm/worktrees.js

@@ -2,6 +2,7 @@ import { mkdirSync, readFileSync } from "node:fs";
 import { isAbsolute, resolve as pathResolve } from "node:path";
 import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { C3_FIELDS } from "./constants.js";
+import { ensureSubagentStatusDir } from "./subagent-status-dir.js";
 import { runText } from "./subprocess.js";
 export class WorktreeMapError extends Error {
     name = "WorktreeMapError";
@@ -24,6 +25,9 @@ export class WorktreeMapConfigError extends Error {
 export class WorktreePathEscapeError extends WorktreeMapError {
     name = "WorktreePathEscapeError";
 }
+export class WorktreeRevisionMismatchError extends WorktreeMapError {
+    name = "WorktreeRevisionMismatchError";
+}
 export const defaultGitRunner = (args, cwd) => runText(["git", ...args], { cwd });
 function resolvePath(raw, repoRoot) {
     const candidate = isAbsolute(raw) ? raw : pathResolve(repoRoot, raw);
@@ -44,14 +48,15 @@ function assertWorktreePathContained(repoRoot, worktreePath) {
 export function compareKey(pathStr) {
     return pathStr.replace(/\\/g, "/").toLowerCase();
 }
-/** Parse `git worktree list --porcelain` into `{compareKey: branch|null}`. */
+/** Parse `git worktree list --porcelain` into `{compareKey: {branch, head}}`. */
 export function parseWorktreePorcelain(text) {
     const registered = new Map();
     let currentPath = null;
     let currentBranch = null;
+    let currentHead = null;
     const flush = () => {
         if (currentPath !== null) {
-            registered.set(compareKey(currentPath), currentBranch);
+            registered.set(compareKey(currentPath), { branch: currentBranch, head: currentHead });
         }
     };
     for (const line of text.split("\n")) {
@@ -59,6 +64,11 @@ export function parseWorktreePorcelain(text) {
             flush();
             currentPath = pathResolve(line.slice("worktree ".length).trim());
             currentBranch = null;
+            currentHead = null;
+        }
+        else if (line.startsWith("HEAD ")) {
+            const oid = line.slice("HEAD ".length).trim().toLowerCase();
+            currentHead = oid.length > 0 ? oid : null;
         }
         else if (line.startsWith("branch ")) {
             const ref = line.slice("branch ".length).trim();
@@ -82,6 +92,24 @@ function gitWorktreeList(repoRoot, git) {
     }
     return parseWorktreePorcelain(proc.stdout);
 }
+function resolveCommitOid(repoRoot, revision, git) {
+    let proc;
+    try {
+        proc = git(["rev-parse", "--verify", "--end-of-options", `${revision}^{commit}`], repoRoot);
+    }
+    catch (exc) {
+        throw new WorktreeMapConfigError(`could not resolve base '${revision}' to a commit OID in ${repoRoot}: ${String(exc)}`);
+    }
+    if (proc.returncode !== 0) {
+        throw new WorktreeMapConfigError(`could not resolve base '${revision}' to a commit OID in ${repoRoot} ` +
+            `(rc=${proc.returncode}): ${proc.stderr.trim() || "<no stderr>"}`);
+    }
+    const oid = (proc.stdout.trim().split(/\s+/)[0] ?? "").toLowerCase();
+    if (!/^[0-9a-f]{40,64}$/.test(oid)) {
+        throw new WorktreeMapConfigError(`git rev-parse for base '${revision}' did not return a commit OID: ${JSON.stringify(oid)}`);
+    }
+    return oid;
+}
 function createWorktree(repoRoot, worktreePath, baseBranch, git) {
     mkdirSync(pathResolve(worktreePath, ".."), { recursive: true });
     let proc;
@@ -96,7 +124,13 @@ function createWorktree(repoRoot, worktreePath, baseBranch, git) {
             `(rc=${proc.returncode}): ${proc.stderr.trim() || "<no stderr>"}`);
     }
 }
-/** Resolve a story-to-worktree mapping into normalized C3 records (frozen contract). */
+/**
+ * Resolve a story-to-worktree mapping into normalized C3 records (frozen contract).
+ *
+ * Registered paths are reused only when their porcelain HEAD OID matches the
+ * requested base OID. That comparison is a snapshot at resolution time — not a
+ * pin on the worker's start revision (`swarm:launch` emits a manifest and stops).
+ */
 export function resolveWorktreeMap(mapping, baseBranch, createMissing = true, options = {}) {
     if (!Array.isArray(mapping)) {
         throw new WorktreeMapConfigError(`worktree map must be a list of records, got ${typeof mapping}`);
@@ -154,14 +188,24 @@ export function resolveWorktreeMap(mapping, baseBranch, createMissing = true, op
         });
     }
     const registered = gitWorktreeList(root, git);
+    const requestedOid = resolveCommitOid(root, trimmedBase, git);
     for (const entry of resolved) {
-        if (registered.has(entry._key)) {
+        const existing = registered.get(entry._key);
+        if (existing !== undefined) {
+            const actualOid = existing.head ?? "";
+            if (actualOid !== requestedOid) {
+                throw new WorktreeRevisionMismatchError(`registered worktree '${entry.worktree_path}' HEAD OID is ${actualOid || "(missing)"} ` +
+                    `but requested base '${trimmedBase}' resolves to ${requestedOid}; ` +
+                    `this is a snapshot check at resolution time, not a pin on the worker's start revision`);
+            }
+            ensureSubagentStatusDir(entry._abs);
             continue;
         }
         if (!createMissing) {
             throw new MissingWorktreeError(`story '${entry.story_id}' maps to '${entry.worktree_path}' which is not a registered git worktree and create_missing is disabled`);
         }
         createWorktree(root, entry._abs, trimmedBase, git);
+        ensureSubagentStatusDir(entry._abs);
     }
     return resolved.map(({ story_id, worktree_path, base_branch }) => ({
         story_id,

package/dist/triage/scope/mutations-core.d.ts

@@ -1,9 +1,5 @@
-export declare class ProjectDefinitionIOError extends Error {
-    readonly name = "ProjectDefinitionIOError";
-}
-export declare function projectDefinitionPath(projectRoot: string): string;
-export declare function loadProjectDefinitionForMutation(projectRoot: string): [Record<string, unknown>, string];
-export declare function atomicWriteProjectDefinition(path: string, data: Record<string, unknown>): void;
+export { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionPath, } from "../../vbrief-build/project-definition-io.js";
+export { ProjectDefinitionIOError } from "../../vbrief-build/types.js";
 export declare function recordSubscriptionChange(projectRoot: string, options: {
     op: string;
     label?: string | null;

package/dist/triage/scope/mutations-core.js

@@ -1,52 +1,20 @@
 import { randomUUID } from "node:crypto";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import { resolveProjectDefinitionPath } from "../../layout/resolve.js";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY } from "../../policy/plan-extensions.js";
-import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
+import { withProjectDefinitionMutation } from "../../vbrief-build/project-definition-mutation.js";
 import { resolveTriageCachePath } from "../cache-path.js";
 import { SUBSCRIPTION_HISTORY_SCHEMA } from "./constants.js";
 import { pyStrRepr } from "./python-repr.js";
 import { utcIso } from "./time.js";
-export class ProjectDefinitionIOError extends Error {
-    name = "ProjectDefinitionIOError";
-}
-export function projectDefinitionPath(projectRoot) {
-    return resolveProjectDefinitionPath(projectRoot);
-}
-export function loadProjectDefinitionForMutation(projectRoot) {
-    const path = projectDefinitionPath(projectRoot);
-    if (!existsSync(path)) {
-        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION not found at ${path}; run task triage:welcome / ` +
-            "task triage:bootstrap to scaffold one first.");
-    }
-    let raw;
-    try {
-        raw = readFileSync(path, "utf8");
-    }
-    catch (err) {
-        throw new ProjectDefinitionIOError(`Could not read PROJECT-DEFINITION at ${path}: ${String(err)}`);
-    }
-    let data;
-    try {
-        data = JSON.parse(raw);
-    }
-    catch (err) {
-        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION at ${path} is not valid JSON: ${String(err)}`);
-    }
-    if (typeof data !== "object" || data === null || Array.isArray(data)) {
-        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
-    }
-    return [data, path];
-}
-export function atomicWriteProjectDefinition(path, data) {
-    mkdirSync(dirname(path), { recursive: true });
-    const payload = `${JSON.stringify(data, null, 2)}\n`;
-    const tmp = join(tmpdir(), `${randomUUID()}.tmp`);
-    writeFileSync(tmp, payload, "utf8");
-    renameSync(tmp, path);
-}
+// One canonical PROJECT-DEFINITION identity (#3796). The resolver, loader,
+// error type, and write sink are the shared implementations the mutation
+// capability binds. Module-local duplicates used to resolve the layout path
+// directly -- ignoring the `DEFT_PROJECT_PATH` override the lock honours -- and
+// wrote through an uncontained temp sink, so a caller could lock one artifact
+// and load or persist another.
+export { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionPath, } from "../../vbrief-build/project-definition-io.js";
+export { ProjectDefinitionIOError } from "../../vbrief-build/types.js";
 function resolveActor(actor) {
     if (typeof actor === "string" && actor.trim())
         return actor;
@@ -133,11 +101,11 @@ export function subscribe(projectRoot, options) {
     // Serialise the read-modify-write + subscription-history append under the
     // shared PROJECT-DEFINITION mutation lock so concurrent mutators cannot lose
     // an update or emit out-of-order audit rows (#1260).
-    return projectDefinitionMutationLock(projectRoot, () => {
-        const [data, path] = loadProjectDefinitionForMutation(projectRoot);
+    return withProjectDefinitionMutation(projectRoot, (mutation) => {
+        const data = mutation.load();
         const plan = data.plan;
         if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} has a non-object 'plan' key`);
+            throw new Error(`PROJECT-DEFINITION at ${mutation.artifactLabel} has a non-object 'plan' key`);
         }
         const planRec = plan;
         migrateLegacyPolicyKey(planRec);
@@ -145,14 +113,14 @@ export function subscribe(projectRoot, options) {
             planRec[PLAN_POLICY_KEY] = {};
         const policy = planRec[PLAN_POLICY_KEY];
         if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} has a non-object 'plan.policy' key`);
+            throw new Error(`PROJECT-DEFINITION at ${mutation.artifactLabel} has a non-object 'plan.policy' key`);
         }
         const policyRec = policy;
         if (policyRec.triageScope === undefined)
             policyRec.triageScope = [];
         const rules = policyRec.triageScope;
         if (!Array.isArray(rules)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} has a non-list 'plan.policy.triageScope'`);
+            throw new Error(`PROJECT-DEFINITION at ${mutation.artifactLabel} has a non-list 'plan.policy.triageScope'`);
         }
         const before = snapshotRules(rules);
         let changed;
@@ -168,7 +136,7 @@ export function subscribe(projectRoot, options) {
         }
         if (!changed)
             return [false, message];
-        atomicWriteProjectDefinition(path, data);
+        mutation.persist(data);
         recordSubscriptionChange(projectRoot, {
             op: "subscribe",
             label: options.label ?? null,
@@ -185,11 +153,11 @@ export function addIgnore(projectRoot, label) {
         throw new Error(`label must be a non-empty string; got ${JSON.stringify(label)}`);
     // Serialise the read-modify-write + subscription-history append under the
     // shared PROJECT-DEFINITION mutation lock (#1260).
-    return projectDefinitionMutationLock(projectRoot, () => {
-        const [data, path] = loadProjectDefinitionForMutation(projectRoot);
+    return withProjectDefinitionMutation(projectRoot, (mutation) => {
+        const data = mutation.load();
         const plan = data.plan;
         if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} has a non-object 'plan' key`);
+            throw new Error(`PROJECT-DEFINITION at ${mutation.artifactLabel} has a non-object 'plan' key`);
         }
         const planRec = plan;
         migrateLegacyPolicyKey(planRec);
@@ -197,14 +165,14 @@ export function addIgnore(projectRoot, label) {
             planRec[PLAN_POLICY_KEY] = {};
         const policy = planRec[PLAN_POLICY_KEY];
         if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} has a non-object 'plan.policy' key`);
+            throw new Error(`PROJECT-DEFINITION at ${mutation.artifactLabel} has a non-object 'plan.policy' key`);
         }
         const policyRec = policy;
         if (policyRec.triageScopeIgnores === undefined)
             policyRec.triageScopeIgnores = [];
         const raw = policyRec.triageScopeIgnores;
         if (!Array.isArray(raw)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} has a non-list 'plan.policy.triageScopeIgnores'`);
+            throw new Error(`PROJECT-DEFINITION at ${mutation.artifactLabel} has a non-list 'plan.policy.triageScopeIgnores'`);
         }
         const before = snapshotRules(raw);
         for (const entry of raw) {
@@ -216,7 +184,7 @@ export function addIgnore(projectRoot, label) {
             }
         }
         raw.push({ label });
-        atomicWriteProjectDefinition(path, data);
+        mutation.persist(data);
         const after = snapshotRules(raw);
         recordSubscriptionChange(projectRoot, {
             op: "ignore-label",

package/dist/triage/scope-drift/add-ignore.js

@@ -1,39 +1,5 @@
-import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { resolveProjectDefinitionPath } from "../../layout/resolve.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY } from "../../policy/plan-extensions.js";
-import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
-function loadForMutation(projectRoot) {
-    const path = resolveProjectDefinitionPath(resolve(projectRoot));
-    if (!existsSync(path)) {
-        throw new Error(`PROJECT-DEFINITION not found at ${path}; run task triage:welcome / task triage:bootstrap to scaffold one first.`);
-    }
-    let raw;
-    try {
-        raw = readFileSync(path, "utf8");
-    }
-    catch (err) {
-        throw new Error(`Could not read PROJECT-DEFINITION at ${path}: ${String(err)}`);
-    }
-    let data;
-    try {
-        data = JSON.parse(raw);
-    }
-    catch (err) {
-        throw new Error(`PROJECT-DEFINITION at ${path} is not valid JSON: ${String(err)}`);
-    }
-    if (typeof data !== "object" || data === null || Array.isArray(data)) {
-        throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
-    }
-    return [data, path];
-}
-function atomicWrite(path, data) {
-    const dir = dirname(path);
-    const payload = `${JSON.stringify(data, null, 2)}\n`;
-    const tmp = join(dir, `.${Date.now()}.tmp`);
-    writeFileSync(tmp, payload, "utf8");
-    renameSync(tmp, path);
-}
+import { withProjectDefinitionMutation } from "../../vbrief-build/project-definition-mutation.js";
 /** Append a label/milestone ignore entry — mirrors Python `add_ignore`. */
 export function addIgnore(projectRoot, options) {
     const hasLabel = options.label !== undefined;
@@ -48,11 +14,11 @@ export function addIgnore(projectRoot, options) {
     }
     // Serialise the read-modify-write under the shared PROJECT-DEFINITION
     // mutation lock so concurrent mutators cannot lose an update (#1260).
-    return projectDefinitionMutationLock(projectRoot, () => {
-        const [data, path] = loadForMutation(projectRoot);
+    return withProjectDefinitionMutation(projectRoot, (mutation) => {
+        const data = mutation.load();
         const plan = data.plan;
         if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} has a non-object 'plan' key`);
+            throw new Error(`PROJECT-DEFINITION at ${mutation.artifactLabel} has a non-object 'plan' key`);
         }
         const planRec = plan;
         migrateLegacyPolicyKey(planRec);
@@ -74,7 +40,7 @@ export function addIgnore(projectRoot, options) {
             }
         }
         raw.push({ [key]: value });
-        atomicWrite(path, data);
+        mutation.persist(data);
         return { changed: true, message: `added ignore (${key}=${value})` };
     });
 }

package/dist/triage/subscribe/index.d.ts

@@ -3,12 +3,9 @@ export declare const SUBSCRIPTION_HISTORY_SCHEMA = "deft.triage.subscription-cha
 export declare const PROJECT_DEFINITION_REL_PATH = "xbrief/PROJECT-DEFINITION.xbrief.json";
 /** Python ``!r``-style quoting for parity with triage_subscribe.py messages. */
 export declare function pyRepr(value: string): string;
-export declare class ProjectDefinitionIOError extends Error {
-    constructor(message: string);
-}
+export { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionPath, } from "../../vbrief-build/project-definition-io.js";
+export { ProjectDefinitionIOError } from "../../vbrief-build/types.js";
 type TriageRule = Record<string, unknown>;
-export declare function loadProjectDefinitionForMutation(projectRoot: string): [Record<string, unknown>, string];
-export declare function atomicWriteProjectDefinition(path: string, data: Record<string, unknown>): void;
 export declare function recordSubscriptionChange(projectRoot: string, options: {
     op: string;
     label?: string | null;
@@ -34,5 +31,4 @@ export declare function unsubscribe(projectRoot: string, options?: {
     actor?: string | null;
 }): [boolean, string];
 export declare const RECONCILE_HINT: string;
-export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/triage/subscribe/index.js

@@ -1,9 +1,8 @@
 import { randomUUID } from "node:crypto";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
-import { basename, join } from "node:path";
-import { resolveProjectDefinitionPath } from "../../layout/resolve.js";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY } from "../../policy/plan-extensions.js";
-import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
+import { withProjectDefinitionMutation } from "../../vbrief-build/project-definition-mutation.js";
 import { resolveTriageCachePath } from "../cache-path.js";
 export const SUBSCRIPTION_HISTORY_REL_PATH = "xbrief/.triage-cache/subscription-history.jsonl";
 export const SUBSCRIPTION_HISTORY_SCHEMA = "deft.triage.subscription-change.v1";
@@ -12,61 +11,12 @@ export const PROJECT_DEFINITION_REL_PATH = "xbrief/PROJECT-DEFINITION.xbrief.jso
 export function pyRepr(value) {
     return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
 }
-export class ProjectDefinitionIOError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "ProjectDefinitionIOError";
-    }
-}
-function projectDefinitionPath(projectRoot) {
-    return resolveProjectDefinitionPath(projectRoot);
-}
-export function loadProjectDefinitionForMutation(projectRoot) {
-    const path = projectDefinitionPath(projectRoot);
-    if (!existsSync(path)) {
-        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION not found at ${path}; run task triage:welcome / ` +
-            "task triage:bootstrap to scaffold one first.");
-    }
-    let raw;
-    try {
-        raw = readFileSync(path, { encoding: "utf8" });
-    }
-    catch (exc) {
-        throw new ProjectDefinitionIOError(`Could not read PROJECT-DEFINITION at ${path}: ${String(exc)}`);
-    }
-    let data;
-    try {
-        data = JSON.parse(raw);
-    }
-    catch (exc) {
-        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION at ${path} is not valid JSON: ${String(exc)}`);
-    }
-    if (typeof data !== "object" || data === null || Array.isArray(data)) {
-        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
-    }
-    return [data, path];
-}
-export function atomicWriteProjectDefinition(path, data) {
-    const parent = join(path, "..");
-    mkdirSync(parent, { recursive: true });
-    const payload = JSON.stringify(data, null, 2);
-    const tmpName = join(parent, `${basename(path)}.${process.pid}.${Date.now()}.tmp`);
-    try {
-        writeFileSync(tmpName, payload.endsWith("\n") ? payload : `${payload}\n`, {
-            encoding: "utf8",
-        });
-        renameSync(tmpName, path);
-    }
-    catch (exc) {
-        try {
-            unlinkSync(tmpName);
-        }
-        catch {
-            // ignore
-        }
-        throw exc;
-    }
-}
+// One canonical PROJECT-DEFINITION identity (#3796) -- see the same note in
+// `triage/scope/mutations-core.ts`. These were module-local duplicates that
+// resolved the layout path directly instead of honouring the override the lock
+// uses, and wrote through their own temp sink.
+export { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionPath, } from "../../vbrief-build/project-definition-io.js";
+export { ProjectDefinitionIOError } from "../../vbrief-build/types.js";
 function snapshotRules(rules) {
     return JSON.parse(JSON.stringify(rules));
 }
@@ -251,10 +201,10 @@ function mutate(projectRoot, options) {
     // Serialise the read-modify-write + subscription-history append under the
     // shared PROJECT-DEFINITION mutation lock so concurrent mutators cannot lose
     // an update or emit out-of-order audit rows (#1260).
-    return projectDefinitionMutationLock(projectRoot, () => {
-        const [data, path] = loadProjectDefinitionForMutation(projectRoot);
+    return withProjectDefinitionMutation(projectRoot, (mutation) => {
+        const data = mutation.load();
         if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} has a non-object 'plan' key`);
+            throw new Error(`PROJECT-DEFINITION at ${mutation.artifactLabel} has a non-object 'plan' key`);
         }
         const plan = data.plan;
         migrateLegacyPolicyKey(plan);
@@ -266,7 +216,7 @@ function mutate(projectRoot, options) {
                 plan[PLAN_POLICY_KEY] = {};
             }
             else {
-                throw new Error(`PROJECT-DEFINITION at ${path} has a non-object 'plan.policy' key`);
+                throw new Error(`PROJECT-DEFINITION at ${mutation.artifactLabel} has a non-object 'plan.policy' key`);
             }
         }
         const policy = plan[PLAN_POLICY_KEY];
@@ -275,7 +225,7 @@ function mutate(projectRoot, options) {
                 policy.triageScope = [];
             }
             else {
-                throw new Error(`PROJECT-DEFINITION at ${path} has a non-list 'plan.policy.triageScope'`);
+                throw new Error(`PROJECT-DEFINITION at ${mutation.artifactLabel} has a non-list 'plan.policy.triageScope'`);
             }
         }
         const rules = policy.triageScope;
@@ -291,7 +241,7 @@ function mutate(projectRoot, options) {
         if (!changed) {
             return [false, message];
         }
-        atomicWriteProjectDefinition(path, data);
+        mutation.persist(data);
         const after = snapshotRules(rules);
         recordSubscriptionChange(projectRoot, {
             op: options.op,

package/dist/triage/welcome/writers.js

@@ -1,15 +1,11 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { containedWrite } from "../../fs/contained-write.js";
-import { assertWriteTargetSafe } from "../../fs/projection-containment.js";
-import { hasArtifactSuffix, resolveLifecycleFolder, resolveProjectDefinitionPath, } from "../../layout/resolve.js";
+import { hasArtifactSuffix, resolveLifecycleFolder } from "../../layout/resolve.js";
 import { migrateLegacyPolicyKey, PLAN_ONBOARDING_KEY, PLAN_POLICY_KEY, } from "../../policy/plan-extensions.js";
 import { stampChangedToken } from "../../policy/resolve.js";
-import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
+import { withProjectDefinitionMutation } from "../../vbrief-build/project-definition-mutation.js";
 import { AUDIT_LOG_REL_PATH, DEFAULT_RELIEF_AGE_DAYS, DEFAULT_WIP_CAP, SUBSCRIPTION_PRESETS, WELCOME_AUDIT_TAG, } from "./constants.js";
-function projectDefinitionPath(projectRoot) {
-    return resolveProjectDefinitionPath(projectRoot);
-}
 function utcIso() {
     return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 }
@@ -38,51 +34,10 @@ export function appendAuditEntry(projectRoot, entry, changed = true) {
     });
     return logPath;
 }
-/**
- * Atomically write PROJECT-DEFINITION JSON under projectRoot containment (#3077).
- * Containment root is projectRoot (not dirname(path)) so a force-added `xbrief/`
- * directory symlink fails closed before temp+rename — same class as #3042.
- */
-function atomicWrite(projectRoot, path, data) {
-    const root = resolve(projectRoot);
-    const targetAbs = resolve(path);
-    // Refuse leaf/parent symlinks and out-of-root targets before temp+rename.
-    assertWriteTargetSafe(root, targetAbs);
-    const dir = dirname(targetAbs);
-    const payload = `${JSON.stringify(data, null, 2)}\n`;
-    const tmpName = `.${Date.now()}.tmp`;
-    const tmp = join(dir, tmpName);
-    try {
-        // #2980 wave D / #3077: product write routes through containedWrite under projectRoot.
-        containedWrite({
-            root,
-            target: tmp,
-            data: payload,
-            mode: "create",
-        });
-        renameSync(tmp, targetAbs);
-    }
-    catch (err) {
-        try {
-            rmSync(tmp, { force: true });
-        }
-        catch {
-            /* best-effort cleanup */
-        }
-        throw err;
-    }
-}
 export function writeTriageScope(projectRoot, rules, options = { presetLabel: "custom" }) {
     // Serialise read-modify-write + audit append under the shared lock (#1260).
-    return projectDefinitionMutationLock(projectRoot, () => {
-        const path = projectDefinitionPath(projectRoot);
-        if (!existsSync(path))
-            throw new Error(`PROJECT-DEFINITION not found at ${path}`);
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
-        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
-        }
-        const data = parsed;
+    return withProjectDefinitionMutation(projectRoot, (mutation) => {
+        const data = mutation.load();
         const plan = data.plan;
         if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
             throw new Error("PROJECT-DEFINITION 'plan' is not an object");
@@ -97,7 +52,7 @@ export function writeTriageScope(projectRoot, rules, options = { presetLabel: "c
         const policyRec = policy;
         const previous = policyRec.triageScope;
         policyRec.triageScope = rules;
-        atomicWrite(projectRoot, path, data);
+        mutation.persist(data);
         const changed = JSON.stringify(previous) !== JSON.stringify(rules);
         const actor = options.actor ?? WELCOME_AUDIT_TAG;
         const auditEntry = [
@@ -117,15 +72,8 @@ export function writeTriageScope(projectRoot, rules, options = { presetLabel: "c
  * onboarding decision and MUST be representable without writing the value field.
  */
 export function writeWipCapDecision(projectRoot, options = {}) {
-    return projectDefinitionMutationLock(projectRoot, () => {
-        const path = projectDefinitionPath(projectRoot);
-        if (!existsSync(path))
-            throw new Error(`PROJECT-DEFINITION not found at ${path}`);
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
-        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
-        }
-        const data = parsed;
+    return withProjectDefinitionMutation(projectRoot, (mutation) => {
+        const data = mutation.load();
         const plan = data.plan;
         if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
             throw new Error("PROJECT-DEFINITION 'plan' is not an object");
@@ -149,7 +97,7 @@ export function writeWipCapDecision(projectRoot, options = {}) {
             next.value = options.value;
         }
         planRec[PLAN_ONBOARDING_KEY] = next;
-        atomicWrite(projectRoot, path, data);
+        mutation.persist(data);
         const changed = !alreadyDecided || previousRec.acceptedDefault !== acceptedDefault;
         const auditEntry = [
             `actor=${actor}`,
@@ -167,15 +115,8 @@ export function writeWipCap(projectRoot, wipCap, options = {}) {
         throw new Error(`wipCap must be a positive int, got ${JSON.stringify(wipCap)}`);
     }
     // Serialise read-modify-write + audit append under the shared lock (#1260).
-    return projectDefinitionMutationLock(projectRoot, () => {
-        const path = projectDefinitionPath(projectRoot);
-        if (!existsSync(path))
-            throw new Error(`PROJECT-DEFINITION not found at ${path}`);
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
-        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-            throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
-        }
-        const data = parsed;
+    return withProjectDefinitionMutation(projectRoot, (mutation) => {
+        const data = mutation.load();
         const plan = data.plan;
         if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
             throw new Error("PROJECT-DEFINITION 'plan' is not an object");
@@ -206,7 +147,7 @@ export function writeWipCap(projectRoot, wipCap, options = {}) {
         }
         planRec[PLAN_ONBOARDING_KEY] = onboardingRecord;
         if (previous === undefined && wipCap === DEFAULT_WIP_CAP) {
-            atomicWrite(projectRoot, path, data);
+            mutation.persist(data);
             const auditEntry = `actor=${actor} field=${PLAN_ONBOARDING_KEY}.wipCapDecided value=true ` +
                 `acceptedDefault=true changed=true note=default-no-materialize`;
             appendAuditEntry(projectRoot, auditEntry);
@@ -214,14 +155,14 @@ export function writeWipCap(projectRoot, wipCap, options = {}) {
         }
         if (previous !== undefined && wipCap === DEFAULT_WIP_CAP) {
             delete policyRec.wipCap;
-            atomicWrite(projectRoot, path, data);
+            mutation.persist(data);
             const auditEntry = `actor=${actor} field=plan.policy.wipCap action=cleared-to-default value=${wipCap} ` +
                 `previous=${JSON.stringify(previous)} changed=true`;
             appendAuditEntry(projectRoot, auditEntry);
             return [true, auditEntry];
         }
         policyRec.wipCap = wipCap;
-        atomicWrite(projectRoot, path, data);
+        mutation.persist(data);
         const changed = previous !== wipCap;
         const auditEntry = `actor=${actor} field=plan.policy.wipCap value=${wipCap} previous=${JSON.stringify(previous)} ` +
             `changed=${changed ? "true" : "false"}`;

package/dist/vbrief-build/index.d.ts

@@ -3,7 +3,8 @@ export { DEFAULT_STATUS_FOR_FOLDER, DEPRECATION_SENTINEL, EMITTED_VBRIEF_VERSION
 export { pythonJsonPretty } from "./json.js";
 export { cmdVbriefBuild, run, usage } from "./main.js";
 export { PARITY_SCENARIO_NAMES, renderScenarioOutput, runParityScenario, SAMPLE_PROJECT_MD, SAMPLE_ROADMAP_MD, SAMPLE_SPEC_MD, SAMPLE_SPEC_VBRIEF, } from "./parity-scenarios.js";
-export { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionMutationLock, projectDefinitionPath, } from "./project-definition-io.js";
+export { atomicWriteProjectDefinition, CONFIGURED_PROJECT_DEFINITION_LABEL, loadProjectDefinitionForMutation, type MutationLockDeps, ProjectDefinitionLockError, parseProjectDefinitionAt, projectDefinitionArtifactLabel, projectDefinitionMutationLock, projectDefinitionPath, } from "./project-definition-io.js";
+export { type ProjectDefinitionMutation, withProjectDefinitionMutation, } from "./project-definition-mutation.js";
 export { loadProjectInvariants, parseProjectInvariantsField } from "./project-invariants-io.js";
 export { buildScopeVbriefFromReconciled, defaultStatusForFolder, folderForStatus, migrationTimestamp, planStatusMatchesFolder, } from "./routing.js";
 export { deriveOverviewNarrative, extractTechStack, firstProseParagraph, parseRoadmapItems, resolveRepoUrl, } from "./sources.js";

package/dist/vbrief-build/index.js

@@ -3,7 +3,8 @@ export { DEFAULT_STATUS_FOR_FOLDER, DEPRECATION_SENTINEL, EMITTED_VBRIEF_VERSION
 export { pythonJsonPretty } from "./json.js";
 export { cmdVbriefBuild, run, usage } from "./main.js";
 export { PARITY_SCENARIO_NAMES, renderScenarioOutput, runParityScenario, SAMPLE_PROJECT_MD, SAMPLE_ROADMAP_MD, SAMPLE_SPEC_MD, SAMPLE_SPEC_VBRIEF, } from "./parity-scenarios.js";
-export { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionMutationLock, projectDefinitionPath, } from "./project-definition-io.js";
+export { atomicWriteProjectDefinition, CONFIGURED_PROJECT_DEFINITION_LABEL, loadProjectDefinitionForMutation, ProjectDefinitionLockError, parseProjectDefinitionAt, projectDefinitionArtifactLabel, projectDefinitionMutationLock, projectDefinitionPath, } from "./project-definition-io.js";
+export { withProjectDefinitionMutation, } from "./project-definition-mutation.js";
 export { loadProjectInvariants, parseProjectInvariantsField } from "./project-invariants-io.js";
 export { buildScopeVbriefFromReconciled, defaultStatusForFolder, folderForStatus, migrationTimestamp, planStatusMatchesFolder, } from "./routing.js";
 export { deriveOverviewNarrative, extractTechStack, firstProseParagraph, parseRoadmapItems, resolveRepoUrl, } from "./sources.js";