@deftai/directive-core 0.66.2 → 0.68.0

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

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { resolveEvalPath, resolveProjectDefinitionPath } from "../../layout/resolve.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY } from "../../policy/plan-extensions.js";
+import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
 import { SUBSCRIPTION_HISTORY_SCHEMA } from "./constants.js";
 import { pyStrRepr } from "./python-repr.js";
 import { utcIso } from "./time.js";
@@ -128,93 +129,102 @@ export function subscribe(projectRoot, options) {
     if (chosen.length !== 1) {
         throw new Error(`subscribe() requires exactly one of --label / --milestone / --issue; got ${JSON.stringify(chosen)}`);
     }
-    const [data, path] = loadProjectDefinitionForMutation(projectRoot);
-    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`);
-    }
-    const planRec = plan;
-    migrateLegacyPolicyKey(planRec);
-    if (planRec[PLAN_POLICY_KEY] === undefined)
-        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`);
-    }
-    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'`);
-    }
-    const before = snapshotRules(rules);
-    let changed;
-    let message;
-    if (options.label !== undefined) {
-        [changed, message] = applySubscribeLabel(rules, options.label);
-    }
-    else if (options.milestone !== undefined) {
-        [changed, message] = applySubscribeMilestone(rules, options.milestone);
-    }
-    else {
-        throw new Error("subscribe() requires exactly one of label or milestone");
-    }
-    if (!changed)
-        return [false, message];
-    atomicWriteProjectDefinition(path, data);
-    recordSubscriptionChange(projectRoot, {
-        op: "subscribe",
-        label: options.label ?? null,
-        milestone: options.milestone ?? null,
-        before,
-        after: snapshotRules(rules),
-        actor: options.actor,
+    // 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);
+        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`);
+        }
+        const planRec = plan;
+        migrateLegacyPolicyKey(planRec);
+        if (planRec[PLAN_POLICY_KEY] === undefined)
+            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`);
+        }
+        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'`);
+        }
+        const before = snapshotRules(rules);
+        let changed;
+        let message;
+        if (options.label !== undefined) {
+            [changed, message] = applySubscribeLabel(rules, options.label);
+        }
+        else if (options.milestone !== undefined) {
+            [changed, message] = applySubscribeMilestone(rules, options.milestone);
+        }
+        else {
+            throw new Error("subscribe() requires exactly one of label or milestone");
+        }
+        if (!changed)
+            return [false, message];
+        atomicWriteProjectDefinition(path, data);
+        recordSubscriptionChange(projectRoot, {
+            op: "subscribe",
+            label: options.label ?? null,
+            milestone: options.milestone ?? null,
+            before,
+            after: snapshotRules(rules),
+            actor: options.actor,
+        });
+        return [true, message];
     });
-    return [true, message];
 }
 export function addIgnore(projectRoot, label) {
     if (!label.trim())
         throw new Error(`label must be a non-empty string; got ${JSON.stringify(label)}`);
-    const [data, path] = loadProjectDefinitionForMutation(projectRoot);
-    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`);
-    }
-    const planRec = plan;
-    migrateLegacyPolicyKey(planRec);
-    if (planRec[PLAN_POLICY_KEY] === undefined)
-        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`);
-    }
-    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'`);
-    }
-    const before = snapshotRules(raw);
-    for (const entry of raw) {
-        if (typeof entry === "object" &&
-            entry !== null &&
-            !Array.isArray(entry) &&
-            entry.label === label) {
-            return [false, `already-ignored (label=${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);
+        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`);
         }
-    }
-    raw.push({ label });
-    atomicWriteProjectDefinition(path, data);
-    const after = snapshotRules(raw);
-    recordSubscriptionChange(projectRoot, {
-        op: "ignore-label",
-        label,
-        before,
-        after,
-        actor: null,
+        const planRec = plan;
+        migrateLegacyPolicyKey(planRec);
+        if (planRec[PLAN_POLICY_KEY] === undefined)
+            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`);
+        }
+        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'`);
+        }
+        const before = snapshotRules(raw);
+        for (const entry of raw) {
+            if (typeof entry === "object" &&
+                entry !== null &&
+                !Array.isArray(entry) &&
+                entry.label === label) {
+                return [false, `already-ignored (label=${label})`];
+            }
+        }
+        raw.push({ label });
+        atomicWriteProjectDefinition(path, data);
+        const after = snapshotRules(raw);
+        recordSubscriptionChange(projectRoot, {
+            op: "ignore-label",
+            label,
+            before,
+            after,
+            actor: null,
+        });
+        return [true, `added ignore (label=${label})`];
     });
-    return [true, `added ignore (label=${label})`];
 }
 //# sourceMappingURL=mutations-core.js.map

package/dist/triage/scope/resolve.js

@@ -1,9 +1,10 @@
 import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { resolve } from "node:path";
+import { resolveProjectDefinitionPath } from "../../layout/resolve.js";
 import { readPlanPolicy } from "../../policy/plan-extensions.js";
-import { DEFAULT_TRIAGE_SCOPE, PROJECT_DEFINITION_REL_PATH } from "./constants.js";
+import { DEFAULT_TRIAGE_SCOPE } from "./constants.js";
 export function projectDefinitionPath(projectRoot) {
-    return join(resolve(projectRoot), PROJECT_DEFINITION_REL_PATH);
+    return resolveProjectDefinitionPath(resolve(projectRoot));
 }
 export function loadProjectDefinition(projectRoot) {
     const path = projectDefinitionPath(projectRoot);

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

@@ -1,13 +1,10 @@
-import { existsSync, mkdtempSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+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";
-const PROJECT_DEFINITION_REL_PATH = "vbrief/PROJECT-DEFINITION.vbrief.json";
-function projectDefinitionPath(projectRoot) {
-    return join(resolve(projectRoot), PROJECT_DEFINITION_REL_PATH);
-}
+import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
 function loadForMutation(projectRoot) {
-    const path = projectDefinitionPath(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.`);
     }
@@ -49,32 +46,36 @@ export function addIgnore(projectRoot, options) {
     if (typeof value !== "string" || !value.trim()) {
         throw new Error(`${key} must be a non-empty string; got ${JSON.stringify(value)}`);
     }
-    const [data, path] = loadForMutation(projectRoot);
-    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`);
-    }
-    const planRec = plan;
-    migrateLegacyPolicyKey(planRec);
-    let policy = planRec[PLAN_POLICY_KEY];
-    if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
-        policy = {};
-        planRec[PLAN_POLICY_KEY] = policy;
-    }
-    const policyRec = policy;
-    const raw = Array.isArray(policyRec.triageScopeIgnores)
-        ? policyRec.triageScopeIgnores
-        : [];
-    policyRec.triageScopeIgnores = raw;
-    for (const entry of raw) {
-        if (typeof entry === "object" && entry !== null && !Array.isArray(entry)) {
-            if (entry[key] === value) {
-                return { changed: false, message: `already-ignored (${key}=${value})` };
+    // 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);
+        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`);
+        }
+        const planRec = plan;
+        migrateLegacyPolicyKey(planRec);
+        let policy = planRec[PLAN_POLICY_KEY];
+        if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+            policy = {};
+            planRec[PLAN_POLICY_KEY] = policy;
+        }
+        const policyRec = policy;
+        const raw = Array.isArray(policyRec.triageScopeIgnores)
+            ? policyRec.triageScopeIgnores
+            : [];
+        policyRec.triageScopeIgnores = raw;
+        for (const entry of raw) {
+            if (typeof entry === "object" && entry !== null && !Array.isArray(entry)) {
+                if (entry[key] === value) {
+                    return { changed: false, message: `already-ignored (${key}=${value})` };
+                }
             }
         }
-    }
-    raw.push({ [key]: value });
-    atomicWrite(path, data);
-    return { changed: true, message: `added ignore (${key}=${value})` };
+        raw.push({ [key]: value });
+        atomicWrite(path, data);
+        return { changed: true, message: `added ignore (${key}=${value})` };
+    });
 }
 //# sourceMappingURL=add-ignore.js.map

package/dist/triage/scope-drift/scope-rules.js

@@ -1,10 +1,10 @@
 import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { resolve } from "node:path";
+import { resolveProjectDefinitionPath } from "../../layout/resolve.js";
 import { readPlanPolicy } from "../../policy/plan-extensions.js";
-const PROJECT_DEFINITION_REL_PATH = "vbrief/PROJECT-DEFINITION.vbrief.json";
 const DEFAULT_TRIAGE_SCOPE = [{ rule: "all-open" }];
 function loadProjectDefinition(projectRoot) {
-    const path = join(resolve(projectRoot), PROJECT_DEFINITION_REL_PATH);
+    const path = resolveProjectDefinitionPath(resolve(projectRoot));
     if (!existsSync(path))
         return null;
     try {

package/dist/triage/subscribe/index.js

@@ -3,6 +3,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlink
 import { basename, join } from "node:path";
 import { resolveEvalPath, resolveProjectDefinitionPath } from "../../layout/resolve.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY } from "../../policy/plan-extensions.js";
+import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.js";
 export const SUBSCRIPTION_HISTORY_REL_PATH = "vbrief/.eval/subscription-history.jsonl";
 export const SUBSCRIPTION_HISTORY_SCHEMA = "deft.triage.subscription-change.v1";
 export const PROJECT_DEFINITION_REL_PATH = "vbrief/PROJECT-DEFINITION.vbrief.json";
@@ -246,57 +247,62 @@ function mutate(projectRoot, options) {
     if (chosen.length !== 1) {
         throw new Error(`${options.op}() requires exactly one of --label / --milestone / --issue; got ${JSON.stringify(chosen)}`);
     }
-    const [data, path] = loadProjectDefinitionForMutation(projectRoot);
-    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`);
-    }
-    const plan = data.plan;
-    migrateLegacyPolicyKey(plan);
-    const existingPolicy = plan[PLAN_POLICY_KEY];
-    if (typeof existingPolicy !== "object" ||
-        existingPolicy === null ||
-        Array.isArray(existingPolicy)) {
-        if (existingPolicy === undefined) {
-            plan[PLAN_POLICY_KEY] = {};
+    // 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);
+        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`);
         }
-        else {
-            throw new Error(`PROJECT-DEFINITION at ${path} has a non-object 'plan.policy' key`);
+        const plan = data.plan;
+        migrateLegacyPolicyKey(plan);
+        const existingPolicy = plan[PLAN_POLICY_KEY];
+        if (typeof existingPolicy !== "object" ||
+            existingPolicy === null ||
+            Array.isArray(existingPolicy)) {
+            if (existingPolicy === undefined) {
+                plan[PLAN_POLICY_KEY] = {};
+            }
+            else {
+                throw new Error(`PROJECT-DEFINITION at ${path} has a non-object 'plan.policy' key`);
+            }
         }
-    }
-    const policy = plan[PLAN_POLICY_KEY];
-    if (!Array.isArray(policy.triageScope)) {
-        if (policy.triageScope === undefined) {
-            policy.triageScope = [];
+        const policy = plan[PLAN_POLICY_KEY];
+        if (!Array.isArray(policy.triageScope)) {
+            if (policy.triageScope === undefined) {
+                policy.triageScope = [];
+            }
+            else {
+                throw new Error(`PROJECT-DEFINITION at ${path} has a non-list 'plan.policy.triageScope'`);
+            }
+        }
+        const rules = policy.triageScope;
+        const before = snapshotRules(rules);
+        let changed;
+        let message;
+        if (options.op === "subscribe") {
+            [changed, message] = applySubscribe(rules, options.label, options.milestone, options.issue, options.issueNote ?? "added via task triage:subscribe");
         }
         else {
-            throw new Error(`PROJECT-DEFINITION at ${path} has a non-list 'plan.policy.triageScope'`);
+            [changed, message] = applyUnsubscribe(rules, options.label, options.milestone, options.issue);
         }
-    }
-    const rules = policy.triageScope;
-    const before = snapshotRules(rules);
-    let changed;
-    let message;
-    if (options.op === "subscribe") {
-        [changed, message] = applySubscribe(rules, options.label, options.milestone, options.issue, options.issueNote ?? "added via task triage:subscribe");
-    }
-    else {
-        [changed, message] = applyUnsubscribe(rules, options.label, options.milestone, options.issue);
-    }
-    if (!changed) {
-        return [false, message];
-    }
-    atomicWriteProjectDefinition(path, data);
-    const after = snapshotRules(rules);
-    recordSubscriptionChange(projectRoot, {
-        op: options.op,
-        label: options.label,
-        milestone: options.milestone,
-        issue: options.issue,
-        before,
-        after,
-        actor: options.actor,
+        if (!changed) {
+            return [false, message];
+        }
+        atomicWriteProjectDefinition(path, data);
+        const after = snapshotRules(rules);
+        recordSubscriptionChange(projectRoot, {
+            op: options.op,
+            label: options.label,
+            milestone: options.milestone,
+            issue: options.issue,
+            before,
+            after,
+            actor: options.actor,
+        });
+        return [true, message];
     });
-    return [true, message];
 }
 export function subscribe(projectRoot, options = {}) {
     return mutate(projectRoot, { op: "subscribe", ...options });

package/dist/triage/welcome/writers.js

@@ -2,6 +2,7 @@ import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renam
 import { dirname, join, resolve } from "node:path";
 import { hasArtifactSuffix, resolveLifecycleFolder, resolveProjectDefinitionPath, } from "../../layout/resolve.js";
 import { migrateLegacyPolicyKey, PLAN_POLICY_KEY } from "../../policy/plan-extensions.js";
+import { projectDefinitionMutationLock } from "../../vbrief-build/project-definition-io.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);
@@ -27,77 +28,91 @@ function atomicWrite(path, data) {
     renameSync(tmp, path);
 }
 export function writeTriageScope(projectRoot, rules, options = { presetLabel: "custom" }) {
-    const path = projectDefinitionPath(projectRoot);
-    if (!existsSync(path))
-        throw new Error(`PROJECT-DEFINITION not found at ${path}`);
-    const data = JSON.parse(readFileSync(path, "utf8"));
-    const plan = data.plan;
-    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
-        throw new Error("PROJECT-DEFINITION 'plan' is not an object");
-    }
-    const planRec = plan;
-    migrateLegacyPolicyKey(planRec);
-    let policy = planRec[PLAN_POLICY_KEY];
-    if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
-        policy = {};
-        planRec[PLAN_POLICY_KEY] = policy;
-    }
-    const policyRec = policy;
-    const previous = policyRec.triageScope;
-    policyRec.triageScope = rules;
-    atomicWrite(path, data);
-    const changed = JSON.stringify(previous) !== JSON.stringify(rules);
-    const actor = options.actor ?? WELCOME_AUDIT_TAG;
-    const auditEntry = [
-        `actor=${actor}`,
-        "field=plan.policy.triageScope",
-        `preset=${options.presetLabel}`,
-        `rule_count=${rules.length}`,
-        `changed=${changed ? "true" : "false"}`,
-    ].join(" ");
-    appendAuditEntry(projectRoot, auditEntry);
-    return [changed, auditEntry];
+    // 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;
+        const plan = data.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+            throw new Error("PROJECT-DEFINITION 'plan' is not an object");
+        }
+        const planRec = plan;
+        migrateLegacyPolicyKey(planRec);
+        let policy = planRec[PLAN_POLICY_KEY];
+        if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+            policy = {};
+            planRec[PLAN_POLICY_KEY] = policy;
+        }
+        const policyRec = policy;
+        const previous = policyRec.triageScope;
+        policyRec.triageScope = rules;
+        atomicWrite(path, data);
+        const changed = JSON.stringify(previous) !== JSON.stringify(rules);
+        const actor = options.actor ?? WELCOME_AUDIT_TAG;
+        const auditEntry = [
+            `actor=${actor}`,
+            "field=plan.policy.triageScope",
+            `preset=${options.presetLabel}`,
+            `rule_count=${rules.length}`,
+            `changed=${changed ? "true" : "false"}`,
+        ].join(" ");
+        appendAuditEntry(projectRoot, auditEntry);
+        return [changed, auditEntry];
+    });
 }
 export function writeWipCap(projectRoot, wipCap, options = {}) {
     if (!Number.isInteger(wipCap) || wipCap < 1) {
         throw new Error(`wipCap must be a positive int, got ${JSON.stringify(wipCap)}`);
     }
-    const path = projectDefinitionPath(projectRoot);
-    if (!existsSync(path))
-        throw new Error(`PROJECT-DEFINITION not found at ${path}`);
-    const data = JSON.parse(readFileSync(path, "utf8"));
-    const plan = data.plan;
-    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
-        throw new Error("PROJECT-DEFINITION 'plan' is not an object");
-    }
-    const planRec = plan;
-    migrateLegacyPolicyKey(planRec);
-    let policy = planRec[PLAN_POLICY_KEY];
-    if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
-        policy = {};
-        planRec[PLAN_POLICY_KEY] = policy;
-    }
-    const policyRec = policy;
-    const previous = policyRec.wipCap;
-    const actor = options.actor ?? WELCOME_AUDIT_TAG;
-    if (previous === undefined && wipCap === DEFAULT_WIP_CAP) {
-        return [false, ""];
-    }
-    if (previous !== undefined && wipCap === DEFAULT_WIP_CAP) {
-        delete policyRec.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;
+        const plan = data.plan;
+        if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+            throw new Error("PROJECT-DEFINITION 'plan' is not an object");
+        }
+        const planRec = plan;
+        migrateLegacyPolicyKey(planRec);
+        let policy = planRec[PLAN_POLICY_KEY];
+        if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+            policy = {};
+            planRec[PLAN_POLICY_KEY] = policy;
+        }
+        const policyRec = policy;
+        const previous = policyRec.wipCap;
+        const actor = options.actor ?? WELCOME_AUDIT_TAG;
+        if (previous === undefined && wipCap === DEFAULT_WIP_CAP) {
+            return [false, ""];
+        }
+        if (previous !== undefined && wipCap === DEFAULT_WIP_CAP) {
+            delete policyRec.wipCap;
+            atomicWrite(path, 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(path, data);
-        const auditEntry = `actor=${actor} field=plan.policy.wipCap action=cleared-to-default value=${wipCap} ` +
-            `previous=${JSON.stringify(previous)} changed=true`;
+        const changed = previous !== wipCap;
+        const auditEntry = `actor=${actor} field=plan.policy.wipCap value=${wipCap} previous=${JSON.stringify(previous)} ` +
+            `changed=${changed ? "true" : "false"}`;
         appendAuditEntry(projectRoot, auditEntry);
-        return [true, auditEntry];
-    }
-    policyRec.wipCap = wipCap;
-    atomicWrite(path, data);
-    const changed = previous !== wipCap;
-    const auditEntry = `actor=${actor} field=plan.policy.wipCap value=${wipCap} previous=${JSON.stringify(previous)} ` +
-        `changed=${changed ? "true" : "false"}`;
-    appendAuditEntry(projectRoot, auditEntry);
-    return [changed, auditEntry];
+        return [changed, auditEntry];
+    });
 }
 function daysInPending(path, now) {
     try {

package/dist/vbrief-build/project-definition-io.js

@@ -1,6 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync, } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { PROJECT_DEFINITION_REL_PATH } from "./constants.js";
 import { pythonJsonPretty } from "./json.js";
 import { ProjectDefinitionIOError } from "./types.js";
@@ -18,8 +19,12 @@ function defaultSleep(ms) {
 export function projectDefinitionMutationLock(projectRoot, fn, deps = {}) {
     const sleepMs = deps.sleepMs ?? defaultSleep;
     const now = deps.now ?? Date.now;
-    const path = projectDefinitionPath(projectRoot);
-    const lockPath = join(dirname(path), `${path.split(/[/\\]/).pop()}.lock`);
+    // Derive the sidecar lock path from the layout-aware resolved PROJECT-DEFINITION
+    // path (xbrief/ when migrated, else vbrief/) so the lock lives next to the real
+    // artifact and every mutator sharing a project root contends on the same lock,
+    // instead of the constant vbrief/ path which would strand a stray lock (#1260).
+    const path = resolveProjectDefinitionPath(resolve(projectRoot));
+    const lockPath = `${path}.lock`;
     mkdirSync(dirname(lockPath), { recursive: true });
     if (mutationThreadLock.held) {
         throw new Error("project definition mutation lock is not reentrant");