@deftai/directive-core 0.55.0

package/dist/vbrief-build/constants.js

@@ -0,0 +1,34 @@
+/** Canonical ``vBRIEFInfo.version`` emitted on scope vBRIEFs (#533). */
+export const EMITTED_VBRIEF_VERSION = "0.6";
+/** Migrator provenance namespace under ``plan.metadata`` (#616). */
+export const MIGRATOR_METADATA_KEY = "x-migrator";
+export const PROJECT_DEFINITION_REL_PATH = "vbrief/PROJECT-DEFINITION.vbrief.json";
+export const DEPRECATION_SENTINEL = "<!-- deft:deprecated-redirect -->";
+export const INTERNAL_REFERENCE_TYPES = new Set([
+    "x-vbrief/plan",
+    "x-vbrief/spec-section",
+    "x-vbrief/user-request",
+]);
+export const EXTERNAL_REFERENCE_TYPES = new Set([
+    "x-vbrief/github-issue",
+    "x-vbrief/github-pr",
+    "x-vbrief/jira-ticket",
+    "x-vbrief/web-page",
+]);
+export const FOLDER_TO_STATUSES = {
+    proposed: ["draft", "proposed"],
+    pending: ["approved", "pending"],
+    active: ["running", "blocked"],
+    completed: ["completed"],
+    cancelled: ["cancelled"],
+};
+export const STATUS_TO_FOLDER = Object.fromEntries(Object.entries(FOLDER_TO_STATUSES).flatMap(([folder, statuses]) => statuses.map((status) => [status, folder])));
+export const LIFECYCLE_FOLDERS = Object.keys(FOLDER_TO_STATUSES);
+export const DEFAULT_STATUS_FOR_FOLDER = {
+    proposed: "proposed",
+    pending: "pending",
+    active: "running",
+    completed: "completed",
+    cancelled: "cancelled",
+};
+//# sourceMappingURL=constants.js.map

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

@@ -0,0 +1,12 @@
+export { createScopeVbrief, referenceHasRequiredFields, referenceWithDefaultTrust, setTodayForTests, slugify, TODAY, } from "./build.js";
+export { DEFAULT_STATUS_FOR_FOLDER, DEPRECATION_SENTINEL, EMITTED_VBRIEF_VERSION, EXTERNAL_REFERENCE_TYPES, FOLDER_TO_STATUSES, INTERNAL_REFERENCE_TYPES, LIFECYCLE_FOLDERS, MIGRATOR_METADATA_KEY, PROJECT_DEFINITION_REL_PATH, STATUS_TO_FOLDER, } from "./constants.js";
+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 { buildScopeVbriefFromReconciled, defaultStatusForFolder, folderForStatus, migrationTimestamp, planStatusMatchesFolder, } from "./routing.js";
+export { deriveOverviewNarrative, extractTechStack, firstProseParagraph, parseRoadmapItems, resolveRepoUrl, } from "./sources.js";
+export { createSpeckitScopeVbrief, dependenciesForItem, edgeNodes, migrateSpeckitPlan, speckitIpIndex, speckitIpSlug, } from "./speckit.js";
+export type { CompletedRoadmapItem, JsonObject, RoadmapItem } from "./types.js";
+export { ProjectDefinitionIOError } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/vbrief-build/index.js

@@ -0,0 +1,11 @@
+export { createScopeVbrief, referenceHasRequiredFields, referenceWithDefaultTrust, setTodayForTests, slugify, TODAY, } from "./build.js";
+export { DEFAULT_STATUS_FOR_FOLDER, DEPRECATION_SENTINEL, EMITTED_VBRIEF_VERSION, EXTERNAL_REFERENCE_TYPES, FOLDER_TO_STATUSES, INTERNAL_REFERENCE_TYPES, LIFECYCLE_FOLDERS, MIGRATOR_METADATA_KEY, PROJECT_DEFINITION_REL_PATH, STATUS_TO_FOLDER, } from "./constants.js";
+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 { buildScopeVbriefFromReconciled, defaultStatusForFolder, folderForStatus, migrationTimestamp, planStatusMatchesFolder, } from "./routing.js";
+export { deriveOverviewNarrative, extractTechStack, firstProseParagraph, parseRoadmapItems, resolveRepoUrl, } from "./sources.js";
+export { createSpeckitScopeVbrief, dependenciesForItem, edgeNodes, migrateSpeckitPlan, speckitIpIndex, speckitIpSlug, } from "./speckit.js";
+export { ProjectDefinitionIOError } from "./types.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,3 @@
+/** Python ``json.dumps(..., indent=2, ensure_ascii=False, sort_keys=False)`` + trailing newline. */
+export declare function pythonJsonPretty(value: unknown, indent?: number): string;
+//# sourceMappingURL=json.d.ts.map

package/dist/vbrief-build/json.js

@@ -0,0 +1,5 @@
+/** Python ``json.dumps(..., indent=2, ensure_ascii=False, sort_keys=False)`` + trailing newline. */
+export function pythonJsonPretty(value, indent = 2) {
+    return `${JSON.stringify(value, null, indent)}\n`;
+}
+//# sourceMappingURL=json.js.map

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

@@ -0,0 +1,5 @@
+export declare function usage(): void;
+/** Run one or all parity scenarios; writes JSON payload to stdout. */
+export declare function run(argv: string[]): number;
+export declare function cmdVbriefBuild(argv: string[]): number;
+//# sourceMappingURL=main.d.ts.map

package/dist/vbrief-build/main.js

@@ -0,0 +1,65 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PARITY_SCENARIO_NAMES, renderScenarioOutput, runParityScenario, } from "./parity-scenarios.js";
+export function usage() {
+    process.stderr.write("usage: vbrief-build [--scenario NAME | --all] [--fixture-root PATH]\n");
+}
+/** Run one or all parity scenarios; writes JSON payload to stdout. */
+export function run(argv) {
+    let scenario = null;
+    let all = false;
+    let fixtureRoot = null;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--scenario") {
+            scenario = argv[i + 1] ?? null;
+            i += 1;
+        }
+        else if (arg === "--all") {
+            all = true;
+        }
+        else if (arg === "--fixture-root") {
+            fixtureRoot = argv[i + 1] ?? null;
+            i += 1;
+        }
+        else if (arg === "-h" || arg === "--help") {
+            usage();
+            return 0;
+        }
+        else {
+            process.stderr.write(`vbrief-build: error: unexpected argument: ${arg}\n`);
+            usage();
+            return 2;
+        }
+    }
+    if (!all && !scenario) {
+        usage();
+        return 2;
+    }
+    const ownedFixture = fixtureRoot === null;
+    const root = fixtureRoot ?? mkdtempSync(join(tmpdir(), "deft-vbrief-build-"));
+    try {
+        const names = all ? [...PARITY_SCENARIO_NAMES] : [scenario];
+        const results = names.map((name) => runParityScenario(name, { fixtureRoot: root }));
+        const payload = all ? results : results[0];
+        process.stdout.write(renderScenarioOutput(payload));
+        return 0;
+    }
+    finally {
+        if (ownedFixture) {
+            rmSync(root, { recursive: true, force: true });
+        }
+    }
+}
+export function cmdVbriefBuild(argv) {
+    try {
+        return run(argv);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`vbrief-build: error: ${msg}\n`);
+        return 2;
+    }
+}
+//# sourceMappingURL=main.js.map

package/dist/vbrief-build/parity-scenarios.d.ts

@@ -0,0 +1,19 @@
+import type { JsonObject } from "./types.js";
+export declare const SAMPLE_ROADMAP_MD = "# Roadmap\n\n## Phase 1 -- Foundation\n\n- **#100** -- Add widget support\n- **#101** -- Fix login bug\n\n## Phase 2 -- Features\n\n- **#200** -- Dashboard redesign\n\n## Completed\n\n- ~~#50 -- Initial setup~~\n";
+export declare const SAMPLE_SPEC_VBRIEF: JsonObject;
+export declare const SAMPLE_PROJECT_MD: string;
+export declare const SAMPLE_SPEC_MD: string;
+export interface ParityScenarioContext {
+    readonly fixtureRoot: string;
+}
+export interface ParityScenarioResult {
+    readonly scenario: string;
+    readonly ok: boolean;
+    readonly payload: unknown;
+}
+/** Execute a named parity scenario and return structured payload. */
+export declare function runParityScenario(name: string, ctx: ParityScenarioContext): ParityScenarioResult;
+export declare const PARITY_SCENARIO_NAMES: readonly ["slugify-basic", "create-scope-vbrief", "reference-trust-levels", "parse-roadmap", "resolve-repo-url", "extract-tech-stack", "first-prose-paragraph", "derive-overview", "routing-map", "build-reconciled", "speckit-edge-deps", "create-speckit-scope", "project-definition-roundtrip", "migrate-speckit-plan", "extract-tech-stack-eos", "speckit-ip-index-edge", "repo-url-trailing-slashes"];
+/** Render scenario output bytes for parity compare. */
+export declare function renderScenarioOutput(result: ParityScenarioResult): string;
+//# sourceMappingURL=parity-scenarios.d.ts.map

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

@@ -0,0 +1,321 @@
+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 { 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";
+export const SAMPLE_ROADMAP_MD = `# Roadmap
+
+## Phase 1 -- Foundation
+
+- **#100** -- Add widget support
+- **#101** -- Fix login bug
+
+## Phase 2 -- Features
+
+- **#200** -- Dashboard redesign
+
+## Completed
+
+- ~~#50 -- Initial setup~~
+`;
+export const SAMPLE_SPEC_VBRIEF = {
+    vBRIEFInfo: { version: "0.5", description: "Test spec" },
+    plan: {
+        title: "Test Specification",
+        status: "approved",
+        narratives: {
+            Overview: "A test project for migration.",
+            Architecture: "Simple architecture.",
+        },
+        items: [{ id: "t1.1", title: "Task one", status: "completed" }],
+    },
+};
+export const SAMPLE_PROJECT_MD = "# Test Project\n\n" +
+    "## Project Configuration\n\n" +
+    "**Tech Stack**: Python\n\n" +
+    "**Generated by**: deft-setup skill\n" +
+    "**Date**: 2026-04-01\n";
+export const SAMPLE_SPEC_MD = "# Test Specification\n\n" + "A test specification.\n\n" + "**Generated by**: spec_render.py\n";
+function reconciledBase(overrides = {}) {
+    return {
+        task_id: "#99",
+        number: "99",
+        title: "Widget feature",
+        description: "Add a widget.",
+        description_source: "SPECIFICATION.md",
+        status: "pending",
+        status_source: "default",
+        folder: "pending",
+        phase: "Phase 1",
+        phase_description: "",
+        tier: "",
+        spec_phase: "",
+        roadmap_summary: "",
+        source_conflict: "",
+        title_source: "",
+        override_applied: false,
+        synthetic_id: "",
+        original_task_id: "",
+        ...overrides,
+    };
+}
+/** Execute a named parity scenario and return structured payload. */
+export function runParityScenario(name, ctx) {
+    switch (name) {
+        case "slugify-basic":
+            return {
+                scenario: name,
+                ok: true,
+                payload: {
+                    hello: slugify("Hello World"),
+                    special: slugify("Add widget (v2)!"),
+                    underscores: slugify("task_id_foo"),
+                },
+            };
+        case "create-scope-vbrief":
+            return {
+                scenario: name,
+                ok: true,
+                payload: createScopeVbrief({ number: "99", title: "Test feature", phase: "Phase 1", tier: "Tier 1" }, "https://github.com/owner/repo"),
+            };
+        case "reference-trust-levels":
+            return {
+                scenario: name,
+                ok: true,
+                payload: {
+                    internal: referenceWithDefaultTrust({
+                        type: "x-vbrief/plan",
+                        uri: "specification.vbrief.json",
+                    }),
+                    external: referenceWithDefaultTrust({
+                        type: "x-vbrief/github-issue",
+                        uri: "https://github.com/o/r/issues/1",
+                        title: "Issue #1",
+                    }),
+                    preset: referenceWithDefaultTrust({
+                        type: "x-vbrief/github-issue",
+                        uri: "https://github.com/o/r/issues/1",
+                        title: "Issue #1",
+                        TrustLevel: "internal",
+                    }),
+                },
+            };
+        case "parse-roadmap": {
+            const roadmapPath = join(ctx.fixtureRoot, "ROADMAP.md");
+            writeFileSync(roadmapPath, SAMPLE_ROADMAP_MD, "utf8");
+            const parsed = parseRoadmapItems(roadmapPath);
+            return { scenario: name, ok: true, payload: parsed };
+        }
+        case "resolve-repo-url":
+            return {
+                scenario: name,
+                ok: true,
+                payload: {
+                    fromRepository: resolveRepoUrl({
+                        vBRIEFInfo: { repository: "owner/repo" },
+                    }),
+                    fromRef: resolveRepoUrl({
+                        plan: {
+                            references: [{ uri: "https://github.com/acme/widget/issues/1" }],
+                        },
+                    }),
+                    empty: resolveRepoUrl(null),
+                },
+            };
+        case "extract-tech-stack":
+            return {
+                scenario: name,
+                ok: true,
+                payload: extractTechStack(SAMPLE_PROJECT_MD),
+            };
+        case "first-prose-paragraph":
+            return {
+                scenario: name,
+                ok: true,
+                payload: firstProseParagraph(SAMPLE_SPEC_MD),
+            };
+        case "derive-overview":
+            return {
+                scenario: name,
+                ok: true,
+                payload: {
+                    fromSpec: deriveOverviewNarrative(SAMPLE_SPEC_VBRIEF, null, null, 0),
+                    fromSpecMd: deriveOverviewNarrative(null, SAMPLE_SPEC_MD, null, 0),
+                    placeholder: deriveOverviewNarrative(null, null, null, 3),
+                },
+            };
+        case "routing-map":
+            return {
+                scenario: name,
+                ok: true,
+                payload: {
+                    running: folderForStatus("running"),
+                    matches: planStatusMatchesFolder("running", "active"),
+                },
+            };
+        case "build-reconciled":
+            return {
+                scenario: name,
+                ok: true,
+                payload: buildScopeVbriefFromReconciled(reconciledBase({
+                    status: "completed",
+                    folder: "completed",
+                    source_section: "ROADMAP Completed section",
+                }), "https://github.com/acme/widget", "2026-04-23T00:00:00Z"),
+            };
+        case "speckit-edge-deps":
+            return {
+                scenario: name,
+                ok: true,
+                payload: {
+                    nodes: edgeNodes({ from: "a", to: "b" }),
+                    legacy: edgeNodes({ source: "x", target: "y" }),
+                    deps: dependenciesForItem("ip-2", [
+                        { type: "blocks", from: "ip-1", to: "ip-2" },
+                        { type: "blocks", source: "ip-0", target: "ip-2" },
+                    ]),
+                    slug: speckitIpSlug("IP-1: Widget phase", "ip-1"),
+                    index: speckitIpIndex({ id: "phase-ip-3", title: "IP 3: Build" }, 9),
+                },
+            };
+        case "create-speckit-scope":
+            return {
+                scenario: name,
+                ok: true,
+                payload: createSpeckitScopeVbrief({
+                    title: "IP-1: Foundation",
+                    narrative: {
+                        Description: "Build the foundation.",
+                        Acceptance: "Tests pass.",
+                        Traces: "REQ-1",
+                    },
+                }, { ipIndex: 1, dependencies: ["ip-0"], specRef: "../specification.vbrief.json" }),
+            };
+        case "project-definition-roundtrip": {
+            const vbriefDir = join(ctx.fixtureRoot, "vbrief");
+            mkdirSync(vbriefDir, { recursive: true });
+            const seed = {
+                vBRIEFInfo: { version: "0.6" },
+                plan: {
+                    title: "Parity project",
+                    status: "running",
+                    policy: { wipCap: 10 },
+                    items: [],
+                },
+            };
+            const pdPath = join(vbriefDir, "PROJECT-DEFINITION.vbrief.json");
+            writeFileSync(pdPath, pythonJsonPretty(seed), "utf8");
+            let roundtrip = {};
+            projectDefinitionMutationLock(ctx.fixtureRoot, () => {
+                const [data, path] = loadProjectDefinitionForMutation(ctx.fixtureRoot);
+                data.plan.policy = { wipCap: 12 };
+                atomicWriteProjectDefinition(path, data);
+                roundtrip = JSON.parse(readFileSync(path, "utf8"));
+            });
+            return { scenario: name, ok: true, payload: roundtrip };
+        }
+        case "migrate-speckit-plan": {
+            const vbriefDir = join(ctx.fixtureRoot, "vbrief");
+            mkdirSync(vbriefDir, { recursive: true });
+            const planPath = join(vbriefDir, "plan.vbrief.json");
+            const planFixture = {
+                vBRIEFInfo: { version: "0.5", description: "Speckit plan" },
+                plan: {
+                    title: "Session",
+                    items: [
+                        {
+                            id: "ip-1",
+                            title: "IP-1: Foundation",
+                            narrative: { Description: "Build it." },
+                        },
+                    ],
+                    edges: [],
+                },
+            };
+            writeFileSync(planPath, pythonJsonPretty(planFixture), "utf8");
+            const [ok, actions] = migrateSpeckitPlan(planPath, {
+                pendingDir: join(vbriefDir, "pending"),
+                today: "2026-04-23",
+            });
+            const pendingFiles = ["pending"];
+            let pendingContent = null;
+            try {
+                const pendingPath = join(vbriefDir, "pending", "2026-04-23-ip001-foundation.vbrief.json");
+                pendingContent = JSON.parse(readFileSync(pendingPath, "utf8"));
+            }
+            catch {
+                pendingContent = null;
+            }
+            const rewrittenPlan = JSON.parse(readFileSync(planPath, "utf8"));
+            return {
+                scenario: name,
+                ok,
+                payload: { actions, pendingContent, rewrittenPlan, pendingFiles },
+            };
+        }
+        case "extract-tech-stack-eos":
+            // Regression coverage for the ``\Z`` (absolute end-of-string) anchor bug:
+            // a ``## Tech Stack`` section that runs to end-of-string must be captured.
+            return {
+                scenario: name,
+                ok: true,
+                payload: {
+                    endOfString: extractTechStack("## Tech Stack\nRust + TypeScript"),
+                    trailingNewline: extractTechStack("## Tech Stack\nRust + TypeScript\n"),
+                    followedByHeading: extractTechStack("## Tech Stack\nRust\n## Next\nmore"),
+                    multiLine: extractTechStack("## Tech Stack\nRust\nVitest\n"),
+                },
+            };
+        case "speckit-ip-index-edge":
+            return {
+                scenario: name,
+                ok: true,
+                payload: {
+                    longDigits: speckitIpIndex({ id: "12345678901234" }, 1),
+                    trailingWhitespace: speckitIpIndex({ id: "ip-7   " }, 1),
+                    trailingNewline: speckitIpIndex({ id: "ip-8\n" }, 1),
+                    titleFallback: speckitIpIndex({ id: "phase", title: "IP-3: Build" }, 9),
+                    noDigits: speckitIpIndex({ id: "phase-x", title: "no ip" }, 5),
+                },
+            };
+        case "repo-url-trailing-slashes":
+            return {
+                scenario: name,
+                ok: true,
+                payload: {
+                    single: createScopeVbrief({ number: "5", title: "T" }, "https://github.com/o/r/"),
+                    multiple: createScopeVbrief({ number: "6", title: "U" }, "https://github.com/o/r///"),
+                    spaced: createScopeVbrief({ number: "7", title: "V" }, "  https://github.com/o/r//  "),
+                },
+            };
+        default:
+            return { scenario: name, ok: false, payload: { error: `unknown scenario: ${name}` } };
+    }
+}
+export const PARITY_SCENARIO_NAMES = [
+    "slugify-basic",
+    "create-scope-vbrief",
+    "reference-trust-levels",
+    "parse-roadmap",
+    "resolve-repo-url",
+    "extract-tech-stack",
+    "first-prose-paragraph",
+    "derive-overview",
+    "routing-map",
+    "build-reconciled",
+    "speckit-edge-deps",
+    "create-speckit-scope",
+    "project-definition-roundtrip",
+    "migrate-speckit-plan",
+    "extract-tech-stack-eos",
+    "speckit-ip-index-edge",
+    "repo-url-trailing-slashes",
+];
+/** Render scenario output bytes for parity compare. */
+export function renderScenarioOutput(result) {
+    return pythonJsonPretty(result);
+}
+//# sourceMappingURL=parity-scenarios.js.map

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

@@ -0,0 +1,13 @@
+import type { JsonObject } from "./types.js";
+export declare function projectDefinitionPath(projectRoot: string): string;
+export interface MutationLockDeps {
+    readonly sleepMs?: (ms: number) => void;
+    readonly now?: () => number;
+}
+/** Serialise PROJECT-DEFINITION read-modify-write critical sections. */
+export declare function projectDefinitionMutationLock<T>(projectRoot: string, fn: () => T, deps?: MutationLockDeps): T;
+/** Read PROJECT-DEFINITION.vbrief.json and return ``(data, path)``. */
+export declare function loadProjectDefinitionForMutation(projectRoot: string): [JsonObject, string];
+/** 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

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

@@ -0,0 +1,117 @@
+import { randomBytes } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { PROJECT_DEFINITION_REL_PATH } from "./constants.js";
+import { pythonJsonPretty } from "./json.js";
+import { ProjectDefinitionIOError } from "./types.js";
+const mutationThreadLock = { held: false };
+export function projectDefinitionPath(projectRoot) {
+    return join(projectRoot, PROJECT_DEFINITION_REL_PATH);
+}
+function defaultSleep(ms) {
+    const end = Date.now() + ms;
+    while (Date.now() < end) {
+        /* spin */
+    }
+}
+/** Serialise PROJECT-DEFINITION read-modify-write critical sections. */
+export function projectDefinitionMutationLock(projectRoot, fn, deps = {}) {
+    const sleepMs = deps.sleepMs ?? defaultSleep;
+    const now = deps.now ?? Date.now;
+    const path = projectDefinitionPath(projectRoot);
+    const lockPath = join(dirname(path), `${path.split(/[/\\]/).pop()}.lock`);
+    mkdirSync(dirname(lockPath), { recursive: true });
+    if (mutationThreadLock.held) {
+        throw new Error("project definition mutation lock is not reentrant");
+    }
+    mutationThreadLock.held = true;
+    let fd;
+    try {
+        const deadline = now() + 30_000;
+        while (true) {
+            try {
+                fd = openSync(lockPath, "a+");
+                const existing = readFileSync(lockPath);
+                if (existing.length === 0) {
+                    writeSync(fd, Buffer.from("\0"));
+                }
+                break;
+            }
+            catch (err) {
+                const code = err.code;
+                if (code !== "EACCES" && code !== "EBUSY") {
+                    throw err;
+                }
+                if (now() > deadline) {
+                    throw err;
+                }
+                sleepMs(20);
+            }
+        }
+        return fn();
+    }
+    finally {
+        if (fd !== undefined) {
+            closeSync(fd);
+        }
+        mutationThreadLock.held = false;
+        try {
+            if (existsSync(lockPath)) {
+                unlinkSync(lockPath);
+            }
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+/** Read PROJECT-DEFINITION.vbrief.json and return ``(data, path)``. */
+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) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new ProjectDefinitionIOError(`Could not read PROJECT-DEFINITION at ${path}: ${msg}`);
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION at ${path} is not valid JSON: ${msg}`);
+    }
+    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 [structuredClone(data), path];
+}
+/** Atomically write ``data`` to ``path`` as pretty-printed JSON. */
+export function atomicWriteProjectDefinition(path, data) {
+    mkdirSync(dirname(path), { recursive: true });
+    const payload = pythonJsonPretty(data).replace(/\n$/, "");
+    const tmp = join(dirname(path), `${path.split(/[/\\]/).pop()}.${randomBytes(4).toString("hex")}.tmp`);
+    try {
+        writeFileSync(tmp, payload.endsWith("\n") ? payload : `${payload}\n`, {
+            encoding: "utf8",
+        });
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* best-effort */
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=project-definition-io.js.map

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

@@ -0,0 +1,13 @@
+import type { JsonObject } from "./types.js";
+export { DEFAULT_STATUS_FOR_FOLDER, FOLDER_TO_STATUSES, LIFECYCLE_FOLDERS, STATUS_TO_FOLDER, } from "./constants.js";
+/** Return an ISO-8601 UTC timestamp for ``vBRIEFInfo.updated`` stamps. */
+export declare function migrationTimestamp(): string;
+/** Return the canonical lifecycle folder for a schema status. */
+export declare function folderForStatus(status: string): string;
+/** Return the canonical default status the migrator uses for a folder. */
+export declare function defaultStatusForFolder(folder: string): string;
+/** Return true if ``status`` is permitted inside ``folder/`` per #506. */
+export declare function planStatusMatchesFolder(status: string, folder: string): boolean;
+/** Build a scope vBRIEF dict from a reconciled item (#496 + #499 + #616). */
+export declare function buildScopeVbriefFromReconciled(reconciled: JsonObject, repoUrl?: string, migrationTimestampOverride?: string | null): JsonObject;
+//# sourceMappingURL=routing.d.ts.map