@deftai/directive-core 0.67.0 → 0.68.0

package/dist/swarm/launch.js

@@ -126,17 +126,17 @@ function projectRel(projectRoot, path) {
         return path.replace(/\\/g, "/");
     }
 }
-function indexActiveStories(projectRoot) {
-    const activeDir = resolveLifecycleFolder(projectRoot, "active");
+function indexStoriesInFolder(projectRoot, folder) {
+    const dir = resolveLifecycleFolder(projectRoot, folder);
     const index = [];
-    if (!existsSync(activeDir)) {
+    if (!existsSync(dir)) {
         return index;
     }
-    for (const name of readdirSync(activeDir).sort()) {
+    for (const name of readdirSync(dir).sort()) {
         if (!hasArtifactSuffix(name)) {
             continue;
         }
-        const path = join(activeDir, name);
+        const path = join(dir, name);
         const data = loadJson(path);
         if (data === null) {
             continue;
@@ -146,6 +146,18 @@ function indexActiveStories(projectRoot) {
     }
     return index;
 }
+function indexActiveStories(projectRoot) {
+    return indexStoriesInFolder(projectRoot, "active");
+}
+/**
+ * True when a brief in `xbrief/completed/` (or the legacy `vbrief/completed/`)
+ * references the given issue number in its `references[]` / `Traces`. Used by
+ * finalize-cohort (#2247) to classify an incidental closing ref to an
+ * already-completed issue as a benign skip rather than a hard error.
+ */
+export function completedBriefReferencesIssue(projectRoot, issue) {
+    return indexStoriesInFolder(projectRoot, "completed").some((s) => s.issues.has(issue));
+}
 export function looksLikePath(token) {
     return (token.endsWith(".json") ||
         token.includes("/") ||

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

@@ -4,6 +4,7 @@ export * from "./cache.js";
 export * from "./constants.js";
 export * from "./derive-group.js";
 export * from "./ranking-labels.js";
+export * from "./reconcile-live-state.js";
 export * from "./render.js";
 export * from "./repo.js";
 export * from "./scope-ignores-filter.js";

package/dist/triage/queue/index.js

@@ -4,6 +4,7 @@ export * from "./cache.js";
 export * from "./constants.js";
 export * from "./derive-group.js";
 export * from "./ranking-labels.js";
+export * from "./reconcile-live-state.js";
 export * from "./render.js";
 export * from "./repo.js";
 export * from "./scope-ignores-filter.js";

package/dist/triage/queue/project.d.ts

@@ -1,6 +1,11 @@
 export interface ProjectDefinition {
     readonly plan?: unknown;
 }
-/** Read vbrief/PROJECT-DEFINITION.vbrief.json. Returns null if absent/invalid. */
+/**
+ * Read the layout-resolved PROJECT-DEFINITION artifact (#2207). Resolves the
+ * `xbrief/` layout on migrated trees and falls back to `vbrief/` otherwise, so
+ * `plan.policy.triageRankingLabels` load correctly after the #2109 rename.
+ * Returns null if absent/invalid.
+ */
 export declare function loadProjectDefinition(projectRoot: string): ProjectDefinition | null;
 //# sourceMappingURL=project.d.ts.map

package/dist/triage/queue/project.js

@@ -1,9 +1,14 @@
 import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { PROJECT_DEFINITION_REL_PATH } from "./constants.js";
-/** Read vbrief/PROJECT-DEFINITION.vbrief.json. Returns null if absent/invalid. */
+import { resolve } from "node:path";
+import { resolveProjectDefinitionPath } from "../../layout/resolve.js";
+/**
+ * Read the layout-resolved PROJECT-DEFINITION artifact (#2207). Resolves the
+ * `xbrief/` layout on migrated trees and falls back to `vbrief/` otherwise, so
+ * `plan.policy.triageRankingLabels` load correctly after the #2109 rename.
+ * Returns null if absent/invalid.
+ */
 export function loadProjectDefinition(projectRoot) {
-    const path = join(resolve(projectRoot), PROJECT_DEFINITION_REL_PATH);
+    const path = resolveProjectDefinitionPath(resolve(projectRoot));
     if (!existsSync(path)) {
         return null;
     }

package/dist/triage/queue/reconcile-live-state.d.ts

@@ -0,0 +1,42 @@
+import type { CachedIssue } from "./types.js";
+/**
+ * Resolve the set of issue numbers that are currently OPEN on the live SCM.
+ *
+ * Returns `null` when the live state could not be determined (offline, gh
+ * missing / unauthenticated, REST error). Callers MUST treat `null` as "do not
+ * reconcile" and fall back to the cached view -- a transient read failure must
+ * never empty the queue.
+ */
+export type LiveOpenIssuesReader = (repo: string) => ReadonlySet<number> | null;
+/**
+ * Default reader: one batched, paginated REST list (`state=open`, PRs excluded)
+ * routed through the scm gh-rest shim. Prefers REST over GraphQL and issues a
+ * single logical lookup for the whole open set rather than N per-issue calls.
+ * Any failure is swallowed to `null` so the queue degrades to cached rendering.
+ *
+ * Latency ceiling: no explicit `limit` is passed ON PURPOSE. The reconcile drops
+ * any candidate absent from this set, so a truncated page would incorrectly drop
+ * genuinely-open issues (a false-negative is worse than the latency). The set is
+ * therefore the COMPLETE live-open list, bounded only by `restIssueListPaginated`'s
+ * pagination cap (`REST_PAGINATION_MAX_PAGES` * per-page = 100 * 100 = 10,000 open
+ * issues); a repo with more open issues than that raises rather than silently
+ * truncating. In practice open-issue counts are 10^1-10^2, so this is 1-2 REST
+ * pages. Batch here, never per-candidate.
+ */
+export declare function defaultLiveOpenIssuesReader(repo: string): ReadonlySet<number> | null;
+/**
+ * Reconcile cached candidate issues against live open/closed state before the
+ * queue renders (#2238). The cached candidate set records `state`, but that
+ * value goes stale as soon as an issue is closed/merged and the cache has not
+ * yet refreshed -- so honoring the cached flag alone is insufficient.
+ *
+ * Drops any candidate whose number is NOT in the live-open set. When the reader
+ * returns `null` (state undeterminable) the candidates pass through unchanged so
+ * a network / auth failure never silently empties the queue.
+ *
+ * `reader` defaults to {@link defaultLiveOpenIssuesReader}; tests (and the CLI)
+ * inject a stub via this optional parameter -- there is no module-level mutable
+ * seam, so nothing test-only leaks into the package's public API.
+ */
+export declare function reconcileLiveOpenState(issues: readonly CachedIssue[], repo: string, reader?: LiveOpenIssuesReader): readonly CachedIssue[];
+//# sourceMappingURL=reconcile-live-state.d.ts.map

package/dist/triage/queue/reconcile-live-state.js

@@ -0,0 +1,54 @@
+import { restIssueListPaginated } from "../../scm/gh-rest.js";
+/**
+ * Default reader: one batched, paginated REST list (`state=open`, PRs excluded)
+ * routed through the scm gh-rest shim. Prefers REST over GraphQL and issues a
+ * single logical lookup for the whole open set rather than N per-issue calls.
+ * Any failure is swallowed to `null` so the queue degrades to cached rendering.
+ *
+ * Latency ceiling: no explicit `limit` is passed ON PURPOSE. The reconcile drops
+ * any candidate absent from this set, so a truncated page would incorrectly drop
+ * genuinely-open issues (a false-negative is worse than the latency). The set is
+ * therefore the COMPLETE live-open list, bounded only by `restIssueListPaginated`'s
+ * pagination cap (`REST_PAGINATION_MAX_PAGES` * per-page = 100 * 100 = 10,000 open
+ * issues); a repo with more open issues than that raises rather than silently
+ * truncating. In practice open-issue counts are 10^1-10^2, so this is 1-2 REST
+ * pages. Batch here, never per-candidate.
+ */
+export function defaultLiveOpenIssuesReader(repo) {
+    try {
+        const rows = restIssueListPaginated(repo, { state: "open", excludePulls: true });
+        const open = new Set();
+        for (const row of rows) {
+            const n = row.number;
+            if (typeof n === "number" && Number.isInteger(n)) {
+                open.add(n);
+            }
+        }
+        return open;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Reconcile cached candidate issues against live open/closed state before the
+ * queue renders (#2238). The cached candidate set records `state`, but that
+ * value goes stale as soon as an issue is closed/merged and the cache has not
+ * yet refreshed -- so honoring the cached flag alone is insufficient.
+ *
+ * Drops any candidate whose number is NOT in the live-open set. When the reader
+ * returns `null` (state undeterminable) the candidates pass through unchanged so
+ * a network / auth failure never silently empties the queue.
+ *
+ * `reader` defaults to {@link defaultLiveOpenIssuesReader}; tests (and the CLI)
+ * inject a stub via this optional parameter -- there is no module-level mutable
+ * seam, so nothing test-only leaks into the package's public API.
+ */
+export function reconcileLiveOpenState(issues, repo, reader = defaultLiveOpenIssuesReader) {
+    const liveOpen = reader(repo);
+    if (liveOpen === null) {
+        return issues;
+    }
+    return issues.filter((issue) => liveOpen.has(issue.number));
+}
+//# sourceMappingURL=reconcile-live-state.js.map

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 });