@deftai/directive-core 0.106.0 → 0.108.0

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

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

package/dist/triage/subscribe/index.js

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

package/dist/triage/welcome/writers.js

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

package/dist/value/feedback-file.d.ts

@@ -1,6 +1,10 @@
 import { type GhRestSeams } from "../scm/gh-rest.js";
 export declare const DEFAULT_UPSTREAM_REPO = "deftai/directive";
 export declare const FRAMEWORK_GAP_TITLE_PREFIX = "[framework-gap]";
+/** Sole sanctioned title classification (#3713). Does not write `adoption-blocker`. */
+export declare const ADOPTION_BLOCKER_TITLE_TOKEN = "BLOCKER";
+/** Strip source prefix and the optional BLOCKER token so marked/unmarked titles dedup. */
+export declare function stripTitleClassificationTokens(title: string): string;
 export type FeedbackFileOutcome = "draft" | "filed" | "skipped-maintainer" | "blocked-policy" | "blocked-duplicate" | "blocked-no-confirm" | "error-bad-args" | "error-config" | "error-network";
 export interface FeedbackGapInput {
     readonly summary: string;
@@ -8,6 +12,11 @@ export interface FeedbackGapInput {
     readonly expected?: string;
     readonly actual?: string;
     readonly sessionNotes?: string;
+    /** Consumer hard-stop judgment. Advisory title token only — never applies a label. */
+    readonly adoptionBlocker?: boolean;
+    readonly flowAndVersion?: string;
+    readonly alternatives?: string;
+    readonly recoveryCost?: string;
 }
 export interface FeedbackFileOptions extends FeedbackGapInput {
     readonly projectRoot?: string | null;
@@ -29,10 +38,12 @@ export interface FeedbackFileResult {
 }
 /** True when the resolved project root is the directive maintainer source checkout. */
 export declare function isMaintainerFrameworkRepo(projectRoot: string): boolean;
-/** Normalize a title for duplicate comparison (#1709). */
+/** Normalize a title for duplicate comparison (#1709 / #3713). */
 export declare function normalizeForDedup(title: string): string;
 /** Build the upstream issue title for a framework-gap report. */
-export declare function buildFrameworkGapTitle(summary: string): string;
+export declare function buildFrameworkGapTitle(summary: string, options?: {
+    adoptionBlocker?: boolean;
+}): string;
 /** Build the structured framework-gap issue body. */
 export declare function buildFrameworkGapBody(input: FeedbackGapInput): string;
 export interface DuplicateMatch {
@@ -49,6 +60,10 @@ export interface FeedbackFileCliArgs {
     expected?: string;
     actual?: string;
     sessionNotes?: string;
+    adoptionBlocker?: boolean;
+    flowAndVersion?: string;
+    alternatives?: string;
+    recoveryCost?: string;
     confirm?: boolean;
     dryRun?: boolean;
     json?: boolean;

package/dist/value/feedback-file.js

@@ -7,6 +7,21 @@ import { GhRestError, restCreateIssue, restIssueListPaginated, } from "../scm/gh
 import { resolveProjectRoot } from "../scope/project-context.js";
 export const DEFAULT_UPSTREAM_REPO = "deftai/directive";
 export const FRAMEWORK_GAP_TITLE_PREFIX = "[framework-gap]";
+/** Sole sanctioned title classification (#3713). Does not write `adoption-blocker`. */
+export const ADOPTION_BLOCKER_TITLE_TOKEN = "BLOCKER";
+const FRAMEWORK_GAP_PREFIX_RE = /^\[framework-gap\]\s*/i;
+const BLOCKER_TITLE_TOKEN_RE = /^BLOCKER\b[:\s-]*/i;
+/** Strip source prefix and the optional BLOCKER token so marked/unmarked titles dedup. */
+export function stripTitleClassificationTokens(title) {
+    let rest = title.trim();
+    let previous = "";
+    while (rest !== previous) {
+        previous = rest;
+        rest = rest.replace(FRAMEWORK_GAP_PREFIX_RE, "").trim();
+        rest = rest.replace(BLOCKER_TITLE_TOKEN_RE, "").trim();
+    }
+    return rest;
+}
 function sanitizeOneLine(value) {
     return value.replace(/\r?\n/g, " ").trim();
 }
@@ -18,23 +33,54 @@ function sectionOrPlaceholder(value, placeholder) {
 export function isMaintainerFrameworkRepo(projectRoot) {
     return isFrameworkRepoRoot(resolve(projectRoot));
 }
-/** Normalize a title for duplicate comparison (#1709). */
+/** Normalize a title for duplicate comparison (#1709 / #3713). */
 export function normalizeForDedup(title) {
-    return title
-        .trim()
-        .replace(/^\[framework-gap\]\s*/i, "")
+    return stripTitleClassificationTokens(title)
         .toLowerCase()
         .replace(/[^\p{L}\p{N}]+/gu, " ")
         .trim();
 }
 /** Build the upstream issue title for a framework-gap report. */
-export function buildFrameworkGapTitle(summary) {
+export function buildFrameworkGapTitle(summary, options) {
     const clean = sanitizeOneLine(summary);
+    if (options?.adoptionBlocker) {
+        const rest = stripTitleClassificationTokens(clean);
+        return `${FRAMEWORK_GAP_TITLE_PREFIX} ${ADOPTION_BLOCKER_TITLE_TOKEN} ${rest}`;
+    }
     if (clean.toLowerCase().startsWith(FRAMEWORK_GAP_TITLE_PREFIX.toLowerCase())) {
         return clean;
     }
     return `${FRAMEWORK_GAP_TITLE_PREFIX} ${clean}`;
 }
+function buildAdoptionImpactSection(input) {
+    if (!input.adoptionBlocker) {
+        return [];
+    }
+    return [
+        "## Adoption impact",
+        "",
+        "This report is a consumer hard-stop: the consumer cannot complete an intended Directive flow and has no reasonable workaround.",
+        "",
+        `Title token: \`${ADOPTION_BLOCKER_TITLE_TOKEN}\`. This token does not apply the \`adoption-blocker\` ranking label. A privileged actor applies that label after the body-evidence test.`,
+        "",
+        "### Affected consumer flow and version",
+        "",
+        sectionOrPlaceholder(input.flowAndVersion, "_(not provided)_"),
+        "",
+        "### Documented alternatives attempted",
+        "",
+        sectionOrPlaceholder(input.alternatives, "_(not provided — why documented alternatives are not a reasonable workaround)_"),
+        "",
+        "### Observed recovery cost",
+        "",
+        sectionOrPlaceholder(input.recoveryCost, "_(not provided)_"),
+        "",
+        "### Triage owner and date",
+        "",
+        "_(to be filled by a privileged actor when applying `adoption-blocker`)_",
+        "",
+    ];
+}
 /** Build the structured framework-gap issue body. */
 export function buildFrameworkGapBody(input) {
     const summary = sanitizeOneLine(input.summary);
@@ -59,6 +105,7 @@ export function buildFrameworkGapBody(input) {
         "",
         sectionOrPlaceholder(input.sessionNotes, "_(not provided)_"),
         "",
+        ...buildAdoptionImpactSection(input),
         "---",
         "_Filed via `task feedback:file` from a directive consumer project (Refs #1709 value-feedback gap escalation)._",
         "",
@@ -126,7 +173,7 @@ export function runFeedbackFile(options) {
     }
     const projectRoot = resolve(projectRootRaw);
     const repo = resolveRepo(options);
-    const title = buildFrameworkGapTitle(summary);
+    const title = buildFrameworkGapTitle(summary, { adoptionBlocker: options.adoptionBlocker });
     const body = buildFrameworkGapBody(options);
     if (isMaintainerFrameworkRepo(projectRoot)) {
         return {
@@ -254,6 +301,8 @@ export function parseFeedbackFileArgs(argv) {
             out.dryRun = true;
         else if (arg === "--json")
             out.json = true;
+        else if (arg === "--blocker")
+            out.adoptionBlocker = true;
         else if (arg === "--summary") {
             out.summary = argv[++i];
         }
@@ -287,6 +336,27 @@ export function parseFeedbackFileArgs(argv) {
         else if (arg?.startsWith("--session-notes=")) {
             out.sessionNotes = arg.slice("--session-notes=".length);
         }
+        else if (arg === "--flow" || arg === "--flow-and-version") {
+            out.flowAndVersion = argv[++i];
+        }
+        else if (arg?.startsWith("--flow=")) {
+            out.flowAndVersion = arg.slice("--flow=".length);
+        }
+        else if (arg?.startsWith("--flow-and-version=")) {
+            out.flowAndVersion = arg.slice("--flow-and-version=".length);
+        }
+        else if (arg === "--alternatives") {
+            out.alternatives = argv[++i];
+        }
+        else if (arg?.startsWith("--alternatives=")) {
+            out.alternatives = arg.slice("--alternatives=".length);
+        }
+        else if (arg === "--recovery-cost") {
+            out.recoveryCost = argv[++i];
+        }
+        else if (arg?.startsWith("--recovery-cost=")) {
+            out.recoveryCost = arg.slice("--recovery-cost=".length);
+        }
         else if (arg === "--repo") {
             out.repo = argv[++i];
         }
@@ -327,6 +397,10 @@ export function feedbackFileMain(argv) {
         expected: args.expected,
         actual: args.actual,
         sessionNotes: args.sessionNotes,
+        adoptionBlocker: args.adoptionBlocker,
+        flowAndVersion: args.flowAndVersion,
+        alternatives: args.alternatives,
+        recoveryCost: args.recoveryCost,
         confirm: args.confirm,
         dryRun: args.dryRun,
         json: args.json,

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

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

package/dist/vbrief-build/index.js

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

package/dist/vbrief-build/parity-scenarios.js

@@ -2,7 +2,7 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { createScopeVbrief, referenceWithDefaultTrust, slugify } from "./build.js";
 import { pythonJsonPretty } from "./json.js";
-import { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionMutationLock, } from "./project-definition-io.js";
+import { withProjectDefinitionMutation } from "./project-definition-mutation.js";
 import { buildScopeVbriefFromReconciled, folderForStatus, planStatusMatchesFolder, } from "./routing.js";
 import { deriveOverviewNarrative, extractTechStack, firstProseParagraph, parseRoadmapItems, resolveRepoUrl, } from "./sources.js";
 import { createSpeckitScopeVbrief, dependenciesForItem, edgeNodes, migrateSpeckitPlan, speckitIpIndex, speckitIpSlug, } from "./speckit.js";
@@ -209,11 +209,11 @@ export function runParityScenario(name, ctx) {
             const pdPath = join(vbriefDir, "PROJECT-DEFINITION.xbrief.json");
             writeFileSync(pdPath, pythonJsonPretty(seed), "utf8");
             let roundtrip = {};
-            projectDefinitionMutationLock(ctx.fixtureRoot, () => {
-                const [data, path] = loadProjectDefinitionForMutation(ctx.fixtureRoot);
+            withProjectDefinitionMutation(ctx.fixtureRoot, (mutation) => {
+                const data = mutation.load();
                 data.plan.policy = { wipCap: 12 };
-                atomicWriteProjectDefinition(path, data);
-                roundtrip = JSON.parse(readFileSync(path, "utf8"));
+                mutation.persist(data);
+                roundtrip = JSON.parse(readFileSync(mutation.artifactPath, "utf8"));
             });
             return { scenario: name, ok: true, payload: roundtrip };
         }

package/dist/vbrief-build/project-definition-io.d.ts

@@ -1,4 +1,15 @@
 import type { JsonObject } from "./types.js";
+/** Setup override for a noncanonical PROJECT-DEFINITION path. */
+export declare const ENV_PROJECT_PATH = "DEFT_PROJECT_PATH";
+/**
+ * Constant display label for a PROJECT-DEFINITION reached through the
+ * `DEFT_PROJECT_PATH` override (#3796). A configured path is operator- or
+ * environment-supplied data, so lock and loader diagnostics name this label
+ * instead of interpolating the raw path. Matches the label already used by
+ * `verify:vbrief-conformance` so one artifact reads the same way on every
+ * diagnostic surface.
+ */
+export declare const CONFIGURED_PROJECT_DEFINITION_LABEL = "<configured PROJECT-DEFINITION>";
 /**
  * Absolute path to the PROJECT-DEFINITION artifact. Layout-aware (#2302):
  * resolves `xbrief/PROJECT-DEFINITION.xbrief.json` on a migrated tree, else the
@@ -6,14 +17,63 @@ import type { JsonObject } from "./types.js";
  * name the path that actually applies to the project's layout.
  */
 export declare function projectDefinitionPath(projectRoot: string): string;
+/**
+ * Control-safe label for an artifact path in a human diagnostic (#3796).
+ * A configured artifact collapses to {@link CONFIGURED_PROJECT_DEFINITION_LABEL};
+ * a layout-resolved canonical artifact keeps its path because the layout
+ * resolver derived it rather than reading it from configuration.
+ */
+export declare function projectDefinitionArtifactLabel(artifactPath: string): string;
+/** Result of probing whether a recorded lock owner PID is still running. */
+export type ProcessLiveness = "dead" | "alive" | "unknown";
+/**
+ * Why an acquisition attempt could not take the lock. Only `contended` is
+ * ordinary traffic; the rest fail closed to manual recovery (#3796).
+ */
+export type LockBlockedReason = "contended" | "owner-alive" | "owner-liveness-unknown" | "malformed-lock-directory" | "legacy-file-sidecar";
 export interface MutationLockDeps {
     readonly sleepMs?: (ms: number) => void;
-    readonly now?: () => number;
+    /**
+     * Monotonic millisecond clock. One budget is derived from a single reading of
+     * this clock and shared by every retry and recovery branch (#3796), so a
+     * wall-clock step or a recovery detour cannot extend the acquisition window.
+     */
+    readonly monotonicNowMs?: () => number;
+    /** Total acquisition budget in milliseconds. */
+    readonly acquisitionBudgetMs?: number;
+    /**
+     * Three-state liveness oracle. Only `dead` authorises an automatic reap;
+     * `alive` (including possible PID reuse) and `unknown` fail closed.
+     */
+    readonly probeProcess?: (pid: number) => ProcessLiveness;
+    readonly writeOwner?: (fd: number, payload: string) => number;
+    readonly renameLock?: (source: string, destination: string) => void;
+    /** Test seam: fires after the stale owner entry is unlinked, before `rmdir`. */
+    readonly beforeLockDirRemove?: (lockPath: string) => void;
 }
-/** Serialise PROJECT-DEFINITION read-modify-write critical sections. */
-export declare function projectDefinitionMutationLock<T>(projectRoot: string, fn: () => T, deps?: MutationLockDeps): T;
+/** Acquisition failed within the shared budget. `reason` names the blocker. */
+export declare class ProjectDefinitionLockError extends Error {
+    readonly reason: LockBlockedReason;
+    constructor(message: string, reason: LockBlockedReason);
+}
+/**
+ * Serialise PROJECT-DEFINITION read-modify-write critical sections.
+ *
+ * Acquisition publishes a fully-materialised, non-empty owner directory by
+ * renaming it onto the public lock pathname, so no contender can observe a
+ * partial lock. Prefer {@link withProjectDefinitionMutation} in
+ * `project-definition-mutation.ts`: it binds load/parse/persist to the captured
+ * artifact path so a caller cannot lock one identity and write another (#3796).
+ */
+export declare function projectDefinitionMutationLock<T>(projectRoot: string, fn: (artifactPath: string) => T, deps?: MutationLockDeps): T;
 /** Read PROJECT-DEFINITION.vbrief.json and return ``(data, path)``. */
 export declare function loadProjectDefinitionForMutation(projectRoot: string): [JsonObject, string];
+/**
+ * Load and parse the PROJECT-DEFINITION at an already-captured path (#3796).
+ * Diagnostics name the artifact through {@link projectDefinitionArtifactLabel}
+ * so a configured path is never interpolated raw.
+ */
+export declare function parseProjectDefinitionAt(path: string): JsonObject;
 /** Atomically write ``data`` to ``path`` as pretty-printed JSON. */
 export declare function atomicWriteProjectDefinition(path: string, data: JsonObject): void;
 //# sourceMappingURL=project-definition-io.d.ts.map