@deftai/directive-core 0.106.0 → 0.108.0

package/dist/triage/evaluate/value.d.ts

@@ -0,0 +1,12 @@
+import { type GithubIssueSnapshot, type ValueAdvice } from "./types.js";
+export declare class ReservedClearanceError extends Error {
+    name: string;
+}
+export declare function assertNoReservedClearance(text: string, label: string): void;
+/**
+ * Value MAY recommend critique via `critique-recommend:`.
+ * It MUST NOT stamp the reserved ADR-005 clearance grammar.
+ */
+export declare function buildValueAdvice(issue: GithubIssueSnapshot | null): ValueAdvice;
+export declare function formatValueField(advice: ValueAdvice): string;
+//# sourceMappingURL=value.d.ts.map

package/dist/triage/evaluate/value.js

@@ -0,0 +1,33 @@
+import { CRITIQUE_RECOMMEND_FIELD, RESERVED_CLEARANCE_RE, } from "./types.js";
+export class ReservedClearanceError extends Error {
+    name = "ReservedClearanceError";
+}
+export function assertNoReservedClearance(text, label) {
+    if (RESERVED_CLEARANCE_RE.test(text)) {
+        throw new ReservedClearanceError(`${label} must not emit the reserved clearance line ` +
+            "`design-critique: warranted | not warranted, because …`");
+    }
+}
+/**
+ * Value MAY recommend critique via `critique-recommend:`.
+ * It MUST NOT stamp the reserved ADR-005 clearance grammar.
+ */
+export function buildValueAdvice(issue) {
+    const labels = issue?.labels ?? [];
+    const stamped = labels.some((label) => label === "design-critique:mechanism-shaped");
+    const reason = stamped
+        ? "GitHub label design-critique:mechanism-shaped is present; author still stamps clearance"
+        : "no mechanism-shaped stamp; critique not recommended from evaluation";
+    const advice = {
+        [CRITIQUE_RECOMMEND_FIELD]: stamped,
+        reason,
+    };
+    assertNoReservedClearance(JSON.stringify(advice), "value advice");
+    return advice;
+}
+export function formatValueField(advice) {
+    const line = `${CRITIQUE_RECOMMEND_FIELD}: ${advice[CRITIQUE_RECOMMEND_FIELD] ? "true" : "false"}`;
+    assertNoReservedClearance(`${line}\n${advice.reason}`, "value field");
+    return `${line}\n${advice.reason}`;
+}
+//# sourceMappingURL=value.js.map

package/dist/triage/evaluate/wip-census.d.ts

@@ -0,0 +1,5 @@
+import type { WipCensus, WipHit } from "./types.js";
+/** Parent-owned. Evaluators must never receive this object. */
+export declare function collectWipCensus(projectRoot: string, issues: readonly number[]): WipCensus;
+export declare function wipHitsForIssue(census: WipCensus, issue: number): WipHit[];
+//# sourceMappingURL=wip-census.d.ts.map

package/dist/triage/evaluate/wip-census.js

@@ -0,0 +1,39 @@
+import { readPlanSequence } from "../../plan-sequence/store.js";
+import { listXbriefHits } from "./xbrief-refs.js";
+function hitsForIssues(hits, issues, kind) {
+    return hits
+        .filter((hit) => issues.has(hit.issue))
+        .map((hit) => ({ kind, path: hit.path, issue: hit.issue }));
+}
+/** Parent-owned. Evaluators must never receive this object. */
+export function collectWipCensus(projectRoot, issues) {
+    const wanted = new Set(issues);
+    const activeHits = listXbriefHits(projectRoot, "active");
+    const pendingHits = listXbriefHits(projectRoot, "pending");
+    const planHits = [];
+    const sequence = readPlanSequence(projectRoot);
+    if (sequence !== null) {
+        for (const entry of sequence.entries) {
+            const fromField = entry.issue;
+            const fromId = Number.parseInt(entry.id.trim().replace(/^#/u, ""), 10);
+            const asNumber = typeof fromField === "number" ? fromField : fromId;
+            if (!Number.isFinite(asNumber) || !wanted.has(asNumber)) {
+                continue;
+            }
+            planHits.push({
+                kind: "plan-sequence",
+                path: ".deft/plan-sequence.json",
+                issue: asNumber,
+            });
+        }
+    }
+    return {
+        active: hitsForIssues(activeHits, wanted, "active-xbrief"),
+        pending: hitsForIssues(pendingHits, wanted, "pending-xbrief"),
+        planSequence: planHits,
+    };
+}
+export function wipHitsForIssue(census, issue) {
+    return [...census.active, ...census.pending, ...census.planSequence].filter((hit) => hit.issue === issue);
+}
+//# sourceMappingURL=wip-census.js.map

package/dist/triage/evaluate/worktrees.d.ts

@@ -0,0 +1,8 @@
+import type { GitRunner } from "./types.js";
+export declare class EvaluatorWorktreeError extends Error {
+    name: string;
+}
+export declare function addEvaluatorWorktree(projectRoot: string, issue: number, invocationId: string, originSha: string, git?: GitRunner): string;
+/** Verb-owned remove. Not a shared core git-worktree helper. */
+export declare function removeEvaluatorWorktree(projectRoot: string, worktreePath: string, git?: GitRunner): void;
+//# sourceMappingURL=worktrees.d.ts.map

package/dist/triage/evaluate/worktrees.js

@@ -0,0 +1,68 @@
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { defaultGitRunner as swarmGitRunner, } from "../../swarm/worktrees.js";
+import { evaluatorWorktreePath } from "./paths.js";
+export class EvaluatorWorktreeError extends Error {
+    name = "EvaluatorWorktreeError";
+}
+function toSwarm(git) {
+    return (args, cwd) => git(args, cwd);
+}
+export function addEvaluatorWorktree(projectRoot, issue, invocationId, originSha, git = swarmGitRunner) {
+    const sha = originSha.trim();
+    if (sha.length === 0) {
+        throw new EvaluatorWorktreeError("originSha is required for a detached evaluator worktree");
+    }
+    const worktreePath = evaluatorWorktreePath(projectRoot, issue, invocationId);
+    mkdirSync(dirname(resolve(worktreePath)), { recursive: true });
+    const proc = toSwarm(git)(["worktree", "add", "--detach", worktreePath, sha], projectRoot);
+    if (proc.returncode !== 0) {
+        throw new EvaluatorWorktreeError(`git worktree add --detach failed for issue ${issue}: ${proc.stderr.trim() || "<no stderr>"}`);
+    }
+    return worktreePath;
+}
+function forceDeleteWorktreeDir(worktreePath) {
+    if (!existsSync(worktreePath)) {
+        return;
+    }
+    rmSync(worktreePath, { recursive: true, force: true });
+}
+function worktreeStillRegistered(git, projectRoot, worktreePath) {
+    const listed = git(["worktree", "list", "--porcelain"], projectRoot);
+    if (listed.returncode !== 0) {
+        return true;
+    }
+    const needle = resolve(worktreePath).replace(/\\/g, "/").toLowerCase();
+    for (const line of listed.stdout.split(/\r?\n/u)) {
+        if (!line.startsWith("worktree ")) {
+            continue;
+        }
+        const listedPath = line.slice("worktree ".length).replace(/\\/g, "/").toLowerCase();
+        if (listedPath === needle) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Verb-owned remove. Not a shared core git-worktree helper. */
+export function removeEvaluatorWorktree(projectRoot, worktreePath, git = swarmGitRunner) {
+    const runner = toSwarm(git);
+    const proc = runner(["worktree", "remove", "--force", worktreePath], projectRoot);
+    if (proc.returncode === 0) {
+        return;
+    }
+    const firstError = proc.stderr.trim() || "<no stderr>";
+    forceDeleteWorktreeDir(worktreePath);
+    runner(["worktree", "prune"], projectRoot);
+    const retry = runner(["worktree", "remove", "--force", worktreePath], projectRoot);
+    if (retry.returncode === 0) {
+        return;
+    }
+    forceDeleteWorktreeDir(worktreePath);
+    runner(["worktree", "prune"], projectRoot);
+    if (!worktreeStillRegistered(runner, projectRoot, worktreePath) && !existsSync(worktreePath)) {
+        return;
+    }
+    throw new EvaluatorWorktreeError(`git worktree remove failed for ${worktreePath}: ${firstError}; fallback: ${retry.stderr.trim() || "<no stderr>"}`);
+}
+//# sourceMappingURL=worktrees.js.map

package/dist/triage/evaluate/xbrief-refs.d.ts

@@ -0,0 +1,8 @@
+export interface XbriefHit {
+    readonly issue: number;
+    readonly path: string;
+    readonly folder: "active" | "pending" | "proposed" | "completed" | "cancelled";
+}
+export declare function issueNumbersFromXbriefJson(raw: unknown): number[];
+export declare function listXbriefHits(root: string, folder: XbriefHit["folder"]): XbriefHit[];
+//# sourceMappingURL=xbrief-refs.d.ts.map

package/dist/triage/evaluate/xbrief-refs.js

@@ -0,0 +1,60 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const ISSUE_URI_RE = /\/issues\/(\d+)\b/u;
+const ISSUE_HASH_RE = /(?:Issue\s+)?#(\d+)\b/u;
+function numbersFromUnknown(value, into) {
+    if (typeof value === "string") {
+        for (const re of [ISSUE_URI_RE, ISSUE_HASH_RE]) {
+            const match = re.exec(value);
+            if (match?.[1] !== undefined) {
+                into.add(Number.parseInt(match[1], 10));
+            }
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            numbersFromUnknown(item, into);
+        }
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        for (const nested of Object.values(value)) {
+            numbersFromUnknown(nested, into);
+        }
+    }
+}
+export function issueNumbersFromXbriefJson(raw) {
+    const found = new Set();
+    if (raw === null || typeof raw !== "object") {
+        return [];
+    }
+    const plan = raw.plan;
+    numbersFromUnknown(plan?.references, found);
+    return [...found];
+}
+export function listXbriefHits(root, folder) {
+    const dir = join(root, "xbrief", folder);
+    if (!existsSync(dir)) {
+        return [];
+    }
+    const hits = [];
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith(".xbrief.json") && !name.endsWith(".vbrief.json")) {
+            continue;
+        }
+        const path = join(dir, name);
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        for (const issue of issueNumbersFromXbriefJson(parsed)) {
+            hits.push({ issue, path, folder });
+        }
+    }
+    return hits;
+}
+//# sourceMappingURL=xbrief-refs.js.map

package/dist/triage/help/registry-data.d.ts

@@ -23,6 +23,17 @@ export declare const registryData: {
             readonly see_also: readonly ["task triage:bootstrap", "task cache:fetch-all", "#1119 / D5"];
             readonly placeholder: false;
         };
+        readonly "task triage:evaluate": {
+            readonly name: "task triage:evaluate";
+            readonly summary: "Isolated validity + parent WIP census + value advice";
+            readonly refs: "(#3648)";
+            readonly description: "Stage A issue-eval: detached origin/master worktrees own validity and ADR/contract reads; the parent on the live working set owns WIP census (xbrief/active, xbrief/pending, plan-sequence); GitHub REST owns open PRs/issues/duplicates. Writes a gitignored sink under .deft-scratch/issue-eval/<sha12>/<invocation-id>/. No GitHub writes. No candidates-log row. Value may set critique-recommend: and must not emit the reserved design-critique clearance line. Fan-out default 4, override --concurrency N.";
+            readonly usage: "task triage:evaluate -- <N...> [--concurrency N] [--repo OWNER/NAME] [--json]";
+            readonly flags: readonly [readonly ["<N...>", "(required)", "Issue numbers to evaluate."], readonly ["--concurrency N", "4", "Parallel evaluator cap (bind, not a measured existing cap)."], readonly ["--repo OWNER/NAME", "(git remote / env)", "Upstream repo for REST reads."], readonly ["--json", "(off)", "Emit the structured EvaluateResult."], readonly ["--project-root PATH", "(cwd)", "Project root override (Taskfile threads USER_WORKING_DIR)."]];
+            readonly examples: readonly ["task triage:evaluate -- 3648", "task triage:evaluate -- 10 11 --concurrency 2 --json"];
+            readonly see_also: readonly ["task triage:queue", "task triage:accept", "skills/deft-directive-issue-eval/SKILL.md", "#3648"];
+            readonly placeholder: false;
+        };
         readonly "task triage:accept": {
             readonly name: "task triage:accept";
             readonly summary: "Mark issue accepted; chains into scope:promote w/ flag";
@@ -444,12 +455,12 @@ export declare const registryData: {
         readonly "task scope:complete": {
             readonly name: "task scope:complete";
             readonly summary: "active/ -> completed/ (set status completed)";
-            readonly refs: "(#845)";
-            readonly description: "Mark an active vBRIEF complete and move it to vbrief/completed/. Terminal transition; use scope:undo if you need reversibility (refused on terminal actions per D15).";
-            readonly usage: "task scope:complete -- <file>";
-            readonly flags: readonly [readonly ["<file>", "(required)", "Path to vBRIEF."], readonly ["--project-root PATH", "(detected)", "Consumer project root override."]];
-            readonly examples: readonly ["task scope:complete -- vbrief/active/2026-05-19-foo.vbrief.json"];
-            readonly see_also: readonly ["task scope:fail", "task scope:cancel", "#1119 / #845"];
+            readonly refs: "(#845, #3041, #3721)";
+            readonly description: "Mark an active vBRIEF complete and move it to vbrief/completed/. Terminal transition; use scope:undo if you need reversibility (refused on terminal actions per D15). Code-bearing completion requires delivery evidence: --merge-commit and --pr. Those flags feed the delivery gate; they do not skip literal-AC.";
+            readonly usage: "task scope:complete -- <file> [--merge-commit SHA] [--pr N]";
+            readonly flags: readonly [readonly ["<file>", "(required)", "Path to vBRIEF."], readonly ["--project-root PATH", "(detected)", "Consumer project root override."], readonly ["--merge-commit SHA", "(required for code-bearing)", "Merge commit SHA for delivery evidence (#3041)."], readonly ["--pr N", "(required for code-bearing)", "Merged PR number for delivery evidence (#3041)."], readonly ["--pr-base BRANCH", "(optional)", "PR base branch for delivery evidence."], readonly ["--delivery-branch BRANCH", "(optional)", "Delivery branch tip for completed-tracked."]];
+            readonly examples: readonly ["task scope:complete -- vbrief/active/2026-05-19-foo.vbrief.json", "task scope:complete -- xbrief/active/story.xbrief.json --merge-commit abc123 --pr 42"];
+            readonly see_also: readonly ["task scope:fail", "task scope:cancel", "#1119 / #845", "#3041"];
             readonly placeholder: false;
         };
         readonly "task scope:fail": {
@@ -530,7 +541,7 @@ export declare const registryData: {
             readonly placeholder: false;
         };
     };
-    readonly categoriesTriage: readonly [readonly ["Session-start", readonly ["task triage:summary", "task verify:cache-fresh"]], readonly ["State verbs (mutate audit log)", readonly ["task triage:accept", "task triage:defer", "task triage:reject", "task triage:needs-ac", "task triage:mark-duplicate", "task triage:reset", "task triage:status", "task triage:history"]], readonly ["Read verbs", readonly ["task triage:queue", "task triage:audit", "task triage:show", "task triage:scope", "task triage:scope-drift", "task triage:classify"]], readonly ["Lifecycle", readonly ["task triage:bootstrap", "task triage:welcome", "task triage:reconcile"]], readonly ["Bulk variants", readonly ["task triage:bulk-accept", "task triage:bulk-reject", "task triage:bulk-defer", "task triage:bulk-needs-ac", "task triage:refresh-active", "task triage:smoketest"]], readonly ["Subscription mutation", readonly ["task triage:subscribe", "task triage:unsubscribe"]], readonly ["Archive / rotation", readonly ["task triage:audit:prune", "task triage:archive-list", "task triage:restore-from-archive", "task triage:audit-log:rotate", "task triage:metrics"]], readonly ["Framework eval (#1703)", readonly ["task eval:health", "task eval:triggers", "task eval:run", "task eval:report"]]];
+    readonly categoriesTriage: readonly [readonly ["Session-start", readonly ["task triage:summary", "task verify:cache-fresh"]], readonly ["State verbs (mutate audit log)", readonly ["task triage:accept", "task triage:defer", "task triage:reject", "task triage:needs-ac", "task triage:mark-duplicate", "task triage:reset", "task triage:status", "task triage:history"]], readonly ["Read verbs", readonly ["task triage:queue", "task triage:evaluate", "task triage:audit", "task triage:show", "task triage:scope", "task triage:scope-drift", "task triage:classify"]], readonly ["Lifecycle", readonly ["task triage:bootstrap", "task triage:welcome", "task triage:reconcile"]], readonly ["Bulk variants", readonly ["task triage:bulk-accept", "task triage:bulk-reject", "task triage:bulk-defer", "task triage:bulk-needs-ac", "task triage:refresh-active", "task triage:smoketest"]], readonly ["Subscription mutation", readonly ["task triage:subscribe", "task triage:unsubscribe"]], readonly ["Archive / rotation", readonly ["task triage:audit:prune", "task triage:archive-list", "task triage:restore-from-archive", "task triage:audit-log:rotate", "task triage:metrics"]], readonly ["Framework eval (#1703)", readonly ["task eval:health", "task eval:triggers", "task eval:run", "task eval:report"]]];
     readonly categoriesScope: readonly [readonly ["Promote / demote", readonly ["task scope:promote", "task scope:demote"]], readonly ["Activate / complete", readonly ["task scope:activate", "task scope:complete", "task scope:fail", "task scope:cancel", "task scope:block", "task scope:unblock"]], readonly ["Reversibility", readonly ["task scope:undo", "task scope:restore"]], readonly ["Decomposition", readonly ["task scope:decompose"]]];
     readonly scriptSubcommandMap: {
         readonly triage_actions: {
@@ -575,6 +586,9 @@ export declare const registryData: {
         readonly triage_reconcile: {
             readonly __default__: "task triage:reconcile";
         };
+        readonly triage_evaluate: {
+            readonly __default__: "task triage:evaluate";
+        };
         readonly triage_queue: {
             readonly queue: "task triage:queue";
             readonly show: "task triage:show";

package/dist/triage/help/registry-data.js

@@ -34,6 +34,35 @@ export const registryData = {
             see_also: ["task triage:bootstrap", "task cache:fetch-all", "#1119 / D5"],
             placeholder: false,
         },
+        "task triage:evaluate": {
+            name: "task triage:evaluate",
+            summary: "Isolated validity + parent WIP census + value advice",
+            refs: "(#3648)",
+            description: "Stage A issue-eval: detached origin/master worktrees own validity and ADR/contract reads; the parent on the live working set owns WIP census (xbrief/active, xbrief/pending, plan-sequence); GitHub REST owns open PRs/issues/duplicates. Writes a gitignored sink under .deft-scratch/issue-eval/<sha12>/<invocation-id>/. No GitHub writes. No candidates-log row. Value may set critique-recommend: and must not emit the reserved design-critique clearance line. Fan-out default 4, override --concurrency N.",
+            usage: "task triage:evaluate -- <N...> [--concurrency N] [--repo OWNER/NAME] [--json]",
+            flags: [
+                ["<N...>", "(required)", "Issue numbers to evaluate."],
+                ["--concurrency N", "4", "Parallel evaluator cap (bind, not a measured existing cap)."],
+                ["--repo OWNER/NAME", "(git remote / env)", "Upstream repo for REST reads."],
+                ["--json", "(off)", "Emit the structured EvaluateResult."],
+                [
+                    "--project-root PATH",
+                    "(cwd)",
+                    "Project root override (Taskfile threads USER_WORKING_DIR).",
+                ],
+            ],
+            examples: [
+                "task triage:evaluate -- 3648",
+                "task triage:evaluate -- 10 11 --concurrency 2 --json",
+            ],
+            see_also: [
+                "task triage:queue",
+                "task triage:accept",
+                "skills/deft-directive-issue-eval/SKILL.md",
+                "#3648",
+            ],
+            placeholder: false,
+        },
         "task triage:accept": {
             name: "task triage:accept",
             summary: "Mark issue accepted; chains into scope:promote w/ flag",
@@ -782,15 +811,30 @@ export const registryData = {
         "task scope:complete": {
             name: "task scope:complete",
             summary: "active/ -> completed/ (set status completed)",
-            refs: "(#845)",
-            description: "Mark an active vBRIEF complete and move it to vbrief/completed/. Terminal transition; use scope:undo if you need reversibility (refused on terminal actions per D15).",
-            usage: "task scope:complete -- <file>",
+            refs: "(#845, #3041, #3721)",
+            description: "Mark an active vBRIEF complete and move it to vbrief/completed/. Terminal transition; use scope:undo if you need reversibility (refused on terminal actions per D15). Code-bearing completion requires delivery evidence: --merge-commit and --pr. Those flags feed the delivery gate; they do not skip literal-AC.",
+            usage: "task scope:complete -- <file> [--merge-commit SHA] [--pr N]",
             flags: [
                 ["<file>", "(required)", "Path to vBRIEF."],
                 ["--project-root PATH", "(detected)", "Consumer project root override."],
+                [
+                    "--merge-commit SHA",
+                    "(required for code-bearing)",
+                    "Merge commit SHA for delivery evidence (#3041).",
+                ],
+                [
+                    "--pr N",
+                    "(required for code-bearing)",
+                    "Merged PR number for delivery evidence (#3041).",
+                ],
+                ["--pr-base BRANCH", "(optional)", "PR base branch for delivery evidence."],
+                ["--delivery-branch BRANCH", "(optional)", "Delivery branch tip for completed-tracked."],
             ],
-            examples: ["task scope:complete -- vbrief/active/2026-05-19-foo.vbrief.json"],
-            see_also: ["task scope:fail", "task scope:cancel", "#1119 / #845"],
+            examples: [
+                "task scope:complete -- vbrief/active/2026-05-19-foo.vbrief.json",
+                "task scope:complete -- xbrief/active/story.xbrief.json --merge-commit abc123 --pr 42",
+            ],
+            see_also: ["task scope:fail", "task scope:cancel", "#1119 / #845", "#3041"],
             placeholder: false,
         },
         "task scope:fail": {
@@ -930,6 +974,7 @@ export const registryData = {
             "Read verbs",
             [
                 "task triage:queue",
+                "task triage:evaluate",
                 "task triage:audit",
                 "task triage:show",
                 "task triage:scope",
@@ -1024,6 +1069,9 @@ export const registryData = {
         triage_reconcile: {
             __default__: "task triage:reconcile",
         },
+        triage_evaluate: {
+            __default__: "task triage:evaluate",
+        },
         triage_queue: {
             queue: "task triage:queue",
             show: "task triage:show",

package/dist/triage/index.d.ts

@@ -13,6 +13,7 @@ export * as bulk from "./bulk/index.js";
 export * as cachePath from "./cache-path.js";
 export * from "./cache-path.js";
 export * as classify from "./classify/index.js";
+export * as evaluate from "./evaluate/index.js";
 export * as help from "./help/index.js";
 export * as queue from "./queue/index.js";
 export * as reconcile from "./reconcile/index.js";

package/dist/triage/index.js

@@ -13,6 +13,7 @@ export * as bulk from "./bulk/index.js";
 export * as cachePath from "./cache-path.js";
 export * from "./cache-path.js";
 export * as classify from "./classify/index.js";
+export * as evaluate from "./evaluate/index.js";
 export * as help from "./help/index.js";
 export * as queue from "./queue/index.js";
 export * as reconcile from "./reconcile/index.js";

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