@deftai/directive-core 0.55.0

package/dist/validate-content/validate-strategy-output.js

@@ -0,0 +1,120 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { isDatePrefixedVbriefFilename } from "./filename.js";
+const GENERATED_SPEC_PURPOSE = "<!-- Purpose: rendered specification -->";
+const GENERATED_SPEC_SOURCE = "<!-- Source of truth: vbrief/specification.vbrief.json -->";
+const LIFECYCLE_DIRS = ["proposed", "pending", "active", "completed", "cancelled"];
+function readTextSafe(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function isDirSafe(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isDeftFrameworkRoot(projectRoot) {
+    // Post-#1875 content/ move: the strategies/ marker lives under content/ in
+    // the SOURCE repo (the C1 flatten strips that prefix in a consumer deposit,
+    // where neither location exists). Accept either layout and never throw on a
+    // missing dir -- consumers legitimately have no strategies/ at all.
+    return (existsSync(join(projectRoot, "AGENTS.md")) &&
+        existsSync(join(projectRoot, "Taskfile.yml")) &&
+        (isDirSafe(join(projectRoot, "content", "strategies")) ||
+            isDirSafe(join(projectRoot, "strategies"))));
+}
+function hasCompleteLifecycle(vbriefDir) {
+    return LIFECYCLE_DIRS.every((folder) => {
+        const p = join(vbriefDir, folder);
+        return existsSync(p) && statSync(p).isDirectory();
+    });
+}
+function isPostCutoverFullSpecState(projectRoot) {
+    const vbriefDir = join(projectRoot, "vbrief");
+    const specMd = readTextSafe(join(projectRoot, "SPECIFICATION.md"));
+    return (existsSync(join(vbriefDir, "PROJECT-DEFINITION.vbrief.json")) &&
+        hasCompleteLifecycle(vbriefDir) &&
+        specMd.includes(GENERATED_SPEC_PURPOSE) &&
+        specMd.includes(GENERATED_SPEC_SOURCE));
+}
+/** Pure validator returning error strings (empty == pass). */
+export function validateStrategyOutput(projectRoot, strict = false) {
+    const root = resolve(projectRoot);
+    const errors = [];
+    const vbriefDir = join(root, "vbrief");
+    if (!existsSync(vbriefDir)) {
+        if (strict) {
+            errors.push("vbrief/ directory missing entirely. v0.20 strategies must emit at least " +
+                "vbrief/proposed/ (with date-prefixed files) + PROJECT-DEFINITION.vbrief.json.");
+        }
+        return errors;
+    }
+    const projDef = join(vbriefDir, "PROJECT-DEFINITION.vbrief.json");
+    if (!existsSync(projDef)) {
+        errors.push("Missing vbrief/PROJECT-DEFINITION.vbrief.json. " +
+            "All v0.20-conformant strategy output must include a complete project definition " +
+            "(see v0-20-contract.md and task project:render).");
+    }
+    const specLegacy = join(vbriefDir, "specification.vbrief.json");
+    if (existsSync(specLegacy) && !isDeftFrameworkRoot(root) && !isPostCutoverFullSpecState(root)) {
+        errors.push("Legacy artifact vbrief/specification.vbrief.json present. " +
+            "v0.20 strategies MUST NOT dual-write the old specification.vbrief.json " +
+            "alongside scope vBRIEFs in the lifecycle folders. " +
+            "See strategies/v0-20-contract.md (contract) and issue #1166.");
+    }
+    for (const dname of LIFECYCLE_DIRS) {
+        const dpath = join(vbriefDir, dname);
+        if (!existsSync(dpath) || !statSync(dpath).isDirectory())
+            continue;
+        for (const name of readdirSync(dpath).sort()) {
+            if (!name.endsWith(".vbrief.json"))
+                continue;
+            if (!isDatePrefixedVbriefFilename(name)) {
+                errors.push(`Non-conformant filename in vbrief/${dname}/: ${name}. ` +
+                    "v0.20 requires strict YYYY-MM-DD-<slug>.vbrief.json " +
+                    "(date prefix from creation). Bare names (e.g. scaffold.vbrief.json) " +
+                    "are pre-v0.20. See strategies/v0-20-contract.md and " +
+                    "vbrief/vbrief.md filename convention.");
+            }
+        }
+    }
+    return errors;
+}
+const FAILURE_HEADER = "❌ Strategy output shape validation FAILED (v0.20 contract gate)";
+const FAILURE_FOOTER = [
+    "",
+    "Reference: strategies/v0-20-contract.md (once landed) + " +
+        "https://github.com/deftai/directive/issues/1166 (s2-deterministic-gate)",
+    "Fix: re-run the emitting strategy after the contract migration " +
+        "stories land, or run `task migrate:vbrief` + `task project:render` " +
+        "+ `task scope:promote` as appropriate.",
+].join("\n");
+/** CLI-shaped evaluator mirroring `scripts/validate_strategy_output.py::main`. */
+export function evaluate(options = {}) {
+    const projectRoot = resolve(options.projectRoot ?? ".");
+    const errors = validateStrategyOutput(projectRoot, options.strict ?? false);
+    if (errors.length > 0) {
+        const lines = [FAILURE_HEADER];
+        for (const err of errors) {
+            lines.push(`  • ${err}`);
+        }
+        lines.push(FAILURE_FOOTER);
+        return { code: 1, message: lines.join("\n"), stream: "stderr" };
+    }
+    if (options.quiet) {
+        return { code: 0, message: "", stream: "none" };
+    }
+    return {
+        code: 0,
+        message: "✓ Strategy output shape conforms to v0.20 contract",
+        stream: "stdout",
+    };
+}
+//# sourceMappingURL=validate-strategy-output.js.map

package/dist/validate-content/verify-capacity.d.ts

@@ -0,0 +1,14 @@
+import type { EvaluateResult } from "./types.js";
+export declare const DEFICIT_TOLERANCE = 1;
+export interface VerifyCapacityOptions {
+    readonly projectRoot?: string;
+    readonly quiet?: boolean;
+    readonly now?: Date;
+}
+/**
+ * Pure evaluator for verify:capacity. Faithful to `scripts/verify_capacity.py`.
+ */
+export declare function evaluate(options?: VerifyCapacityOptions): EvaluateResult;
+/** CLI-shaped runner mirroring `scripts/verify_capacity.py::main`. */
+export declare function runMain(options?: VerifyCapacityOptions): EvaluateResult;
+//# sourceMappingURL=verify-capacity.d.ts.map

package/dist/validate-content/verify-capacity.js

@@ -0,0 +1,96 @@
+import { statSync } from "node:fs";
+import { resolve } from "node:path";
+import { pythonStringRepr, resolveCapacityAllocation } from "./capacity-policy.js";
+import { computeReport, renderReport } from "./capacity-show.js";
+export const DEFICIT_TOLERANCE = 1.0;
+function worstDeficit(report) {
+    let worstId = "";
+    let worst = 0;
+    for (const tally of report.buckets) {
+        const targetWeight = tally.target * report.totalBackward;
+        const deficit = Math.round((targetWeight - tally.backwardWeight) * 10000) / 10000;
+        if (deficit > worst) {
+            worst = deficit;
+            worstId = tally.bucketId;
+        }
+    }
+    return { worstId, worst };
+}
+/**
+ * Pure evaluator for verify:capacity. Faithful to `scripts/verify_capacity.py`.
+ */
+export function evaluate(options = {}) {
+    const projectRoot = resolve(options.projectRoot ?? ".");
+    try {
+        if (!statSync(projectRoot).isDirectory()) {
+            return {
+                code: 2,
+                message: `verify_capacity: --project-root is not a directory: ${projectRoot}\n` +
+                    "  Recovery: pass an existing project root.",
+                stream: "stderr",
+            };
+        }
+    }
+    catch {
+        return {
+            code: 2,
+            message: `verify_capacity: --project-root is not a directory: ${projectRoot}\n` +
+                "  Recovery: pass an existing project root.",
+            stream: "stderr",
+        };
+    }
+    const allocation = resolveCapacityAllocation(projectRoot);
+    const report = computeReport(projectRoot, { now: options.now, allocation });
+    const rendered = renderReport(report);
+    if (allocation.enforcement !== "enforce") {
+        return {
+            code: 0,
+            message: `${rendered}\n` +
+                "verify_capacity: OK -- advisory posture " +
+                `(enforcement=${pythonStringRepr(allocation.enforcement)}); deferring to ordering.`,
+            stream: "stdout",
+        };
+    }
+    if (!report.configured) {
+        return {
+            code: 0,
+            message: `${rendered}\nverify_capacity: OK -- no capacityAllocation buckets configured.`,
+            stream: "stdout",
+        };
+    }
+    if (report.advisoryMode) {
+        return {
+            code: 0,
+            message: `${rendered}\n` +
+                "verify_capacity: OK -- sample below minSampleSize " +
+                `(${report.classifiedCompletions}/${report.minSampleSize}); ` +
+                "capacity stays advisory until enough classified completions accrue.",
+            stream: "stdout",
+        };
+    }
+    const { worstId, worst } = worstDeficit(report);
+    if (worst > DEFICIT_TOLERANCE) {
+        return {
+            code: 1,
+            message: `${rendered}\n` +
+                `verify_capacity: DEFICIT -- bucket ${pythonStringRepr(worstId)} is starved by ` +
+                `${worst.toFixed(2)} (enforce posture; tolerance ${DEFICIT_TOLERANCE.toFixed(1)}). ` +
+                "Prioritize that bucket or relax its target.",
+            stream: "stderr",
+        };
+    }
+    return {
+        code: 0,
+        message: `${rendered}\nverify_capacity: OK -- all buckets within target tolerance.`,
+        stream: "stdout",
+    };
+}
+/** CLI-shaped runner mirroring `scripts/verify_capacity.py::main`. */
+export function runMain(options = {}) {
+    const result = evaluate(options);
+    if (result.code === 0 && options.quiet) {
+        return { code: 0, message: "", stream: "none" };
+    }
+    return result;
+}
+//# sourceMappingURL=verify-capacity.js.map

package/dist/vbrief-activate/activate.d.ts

@@ -0,0 +1,13 @@
+export interface ActivateResult {
+    readonly exitCode: 0 | 1;
+    readonly message: string;
+}
+export interface ActivateOptions {
+    readonly now?: Date;
+}
+/**
+ * Pure activator — returns ``{ exitCode, message }``. Faithful to
+ * ``scripts/vbrief_activate.py::activate``.
+ */
+export declare function activate(vbriefPath: string, options?: ActivateOptions): ActivateResult;
+//# sourceMappingURL=activate.d.ts.map

package/dist/vbrief-activate/activate.js

@@ -0,0 +1,184 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { basename, dirname } from "node:path";
+import { utcNowIso } from "../scope/vbrief-json.js";
+import { pythonJsonPretty } from "../vbrief-build/json.js";
+import { ACTIVE_FOLDER, ELIGIBLE_STATUSES_FOR_FLIP, formatEligibleStatusList, SOURCE_FOLDERS, TARGET_STATUS, } from "./constants.js";
+/** Map Node ``JSON.parse`` errors to CPython ``json.JSONDecodeError.msg`` for parity. */
+function nodeJsonErrorToPythonMsg(nodeMessage) {
+    if (nodeMessage.includes("Expected property name") ||
+        nodeMessage.includes("Expected double-quoted property name")) {
+        return "Expecting property name enclosed in double quotes";
+    }
+    if (nodeMessage.startsWith("Unexpected token") ||
+        nodeMessage.startsWith("Unexpected end of JSON input")) {
+        return "Expecting value";
+    }
+    if (nodeMessage.includes("Unexpected non-whitespace character after JSON")) {
+        return "Extra data";
+    }
+    const atPos = nodeMessage.indexOf(" at position ");
+    return atPos >= 0 ? nodeMessage.slice(0, atPos) : nodeMessage;
+}
+function loadVbrief(vbriefPath) {
+    let raw;
+    try {
+        raw = readFileSync(vbriefPath, "utf8");
+    }
+    catch (err) {
+        const e = err;
+        return {
+            payload: null,
+            error: `Could not read vBRIEF at ${vbriefPath}: ${String(e.message)}.`,
+        };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch (err) {
+        const e = err;
+        const lineCol = /\(line (\d+) column \d+\)/.exec(e.message);
+        const line = lineCol ? Number(lineCol[1]) : 1;
+        const pyMsg = nodeJsonErrorToPythonMsg(e.message);
+        return {
+            payload: null,
+            error: `vBRIEF at ${vbriefPath} is not valid JSON: ${pyMsg} (line ${line}).`,
+        };
+    }
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+        return {
+            payload: null,
+            error: `vBRIEF at ${vbriefPath} top-level value is not a JSON object.`,
+        };
+    }
+    return { payload: payload, error: null };
+}
+/**
+ * Pure activator — returns ``{ exitCode, message }``. Faithful to
+ * ``scripts/vbrief_activate.py::activate``.
+ */
+export function activate(vbriefPath, options = {}) {
+    const now = options.now ?? new Date();
+    if (!existsSync(vbriefPath)) {
+        return { exitCode: 1, message: `vBRIEF not found at ${vbriefPath}.` };
+    }
+    let st;
+    try {
+        st = statSync(vbriefPath);
+    }
+    catch (err) {
+        const e = err;
+        return {
+            exitCode: 1,
+            message: `Could not read vBRIEF at ${vbriefPath}: ${String(e.message)}.`,
+        };
+    }
+    if (!st.isFile()) {
+        return { exitCode: 1, message: `vBRIEF path ${vbriefPath} is not a regular file.` };
+    }
+    const { payload, error } = loadVbrief(vbriefPath);
+    if (error !== null || payload === null) {
+        return { exitCode: 1, message: error ?? "vBRIEF could not be loaded." };
+    }
+    const plan = payload.plan;
+    if (plan === null || typeof plan !== "object" || Array.isArray(plan)) {
+        return {
+            exitCode: 1,
+            message: `vBRIEF at ${vbriefPath} lacks a \`plan\` object -- malformed.`,
+        };
+    }
+    const planObj = plan;
+    const status = planObj.status;
+    if (typeof status !== "string" || status.length === 0) {
+        return { exitCode: 1, message: `vBRIEF at ${vbriefPath} lacks \`plan.status\` -- malformed.` };
+    }
+    const folder = basename(dirname(vbriefPath));
+    if (folder === ACTIVE_FOLDER && status === TARGET_STATUS) {
+        return { exitCode: 0, message: `No-op: ${vbriefPath} already active.` };
+    }
+    if (folder === ACTIVE_FOLDER) {
+        return {
+            exitCode: 1,
+            message: `vBRIEF is already in active/ but plan.status is '${status}', ` +
+                `not '${TARGET_STATUS}'. Use the appropriate task (e.g. ` +
+                "`task scope:unblock`) instead of `task vbrief:activate`.",
+        };
+    }
+    if (!SOURCE_FOLDERS.has(folder)) {
+        return {
+            exitCode: 1,
+            message: `vBRIEF is in ${folder}/ -- only pending/ vBRIEFs can be activated. ` +
+                "Use the lifecycle tasks (`task scope:promote`, etc.) to move it " +
+                "into pending/ first.",
+        };
+    }
+    if (!ELIGIBLE_STATUSES_FOR_FLIP.has(status)) {
+        return {
+            exitCode: 1,
+            message: `plan.status is '${status}' -- only ${formatEligibleStatusList()} can be flipped to ` +
+                `'${TARGET_STATUS}'.`,
+        };
+    }
+    planObj.status = TARGET_STATUS;
+    let info = payload.vBRIEFInfo;
+    if (info === undefined) {
+        info = {};
+        payload.vBRIEFInfo = info;
+    }
+    if (info === null || typeof info !== "object" || Array.isArray(info)) {
+        return {
+            exitCode: 1,
+            message: `vBRIEF at ${vbriefPath} has a non-object \`vBRIEFInfo\` -- malformed.`,
+        };
+    }
+    info.updated = utcNowIso(now);
+    const vbriefDir = dirname(dirname(vbriefPath));
+    const activeDir = `${vbriefDir}/${ACTIVE_FOLDER}`;
+    try {
+        mkdirSync(activeDir, { recursive: true });
+    }
+    catch (err) {
+        const e = err;
+        return { exitCode: 1, message: `Could not create ${activeDir}: ${String(e.message)}.` };
+    }
+    const fileName = basename(vbriefPath);
+    const dest = `${activeDir}/${fileName}`;
+    if (existsSync(dest)) {
+        return {
+            exitCode: 1,
+            message: `Refusing to overwrite existing destination ${dest}. Resolve the ` +
+                "collision manually before re-running `task vbrief:activate`.",
+        };
+    }
+    const tmp = `${dest}.tmp`;
+    try {
+        writeFileSync(tmp, pythonJsonPretty(payload), "utf8");
+        renameSync(tmp, dest);
+    }
+    catch (err) {
+        const e = err;
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        return { exitCode: 1, message: `Could not write ${dest}: ${String(e.message)}.` };
+    }
+    try {
+        unlinkSync(vbriefPath);
+    }
+    catch (err) {
+        const e = err;
+        return {
+            exitCode: 1,
+            message: `Wrote ${dest} but could not remove source ${vbriefPath}: ${String(e.message)}. ` +
+                "Manual cleanup required.",
+        };
+    }
+    return {
+        exitCode: 0,
+        message: `Activated ${fileName}: pending/ -> active/ (status: ${TARGET_STATUS}).`,
+    };
+}
+//# sourceMappingURL=activate.js.map

package/dist/vbrief-activate/constants.d.ts

@@ -0,0 +1,9 @@
+/** Folders the lifecycle move flows between (source allow-list). */
+export declare const SOURCE_FOLDERS: Set<string>;
+export declare const ACTIVE_FOLDER = "active";
+export declare const ELIGIBLE_STATUSES_FOR_FLIP: Set<string>;
+export declare const TARGET_STATUS = "running";
+export declare const ELIGIBLE_STATUSES_SORTED: readonly ["approved", "pending"];
+/** Python ``str(sorted(ELIGIBLE_STATUSES_FOR_FLIP))`` for error messages. */
+export declare function formatEligibleStatusList(): string;
+//# sourceMappingURL=constants.d.ts.map

package/dist/vbrief-activate/constants.js

@@ -0,0 +1,11 @@
+/** Folders the lifecycle move flows between (source allow-list). */
+export const SOURCE_FOLDERS = new Set(["pending"]);
+export const ACTIVE_FOLDER = "active";
+export const ELIGIBLE_STATUSES_FOR_FLIP = new Set(["pending", "approved"]);
+export const TARGET_STATUS = "running";
+export const ELIGIBLE_STATUSES_SORTED = ["approved", "pending"];
+/** Python ``str(sorted(ELIGIBLE_STATUSES_FOR_FLIP))`` for error messages. */
+export function formatEligibleStatusList() {
+    return `[${ELIGIBLE_STATUSES_SORTED.map((s) => `'${s}'`).join(", ")}]`;
+}
+//# sourceMappingURL=constants.js.map

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

@@ -0,0 +1,6 @@
+export type { ActivateOptions, ActivateResult } from "./activate.js";
+export { activate } from "./activate.js";
+export { ACTIVE_FOLDER, ELIGIBLE_STATUSES_FOR_FLIP, formatEligibleStatusList, SOURCE_FOLDERS, TARGET_STATUS, } from "./constants.js";
+export type { ParsedArgs, RunOptions } from "./main.js";
+export { cmdVbriefActivate, parseArgs, run } from "./main.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/vbrief-activate/index.js

@@ -0,0 +1,4 @@
+export { activate } from "./activate.js";
+export { ACTIVE_FOLDER, ELIGIBLE_STATUSES_FOR_FLIP, formatEligibleStatusList, SOURCE_FOLDERS, TARGET_STATUS, } from "./constants.js";
+export { cmdVbriefActivate, parseArgs, run } from "./main.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,14 @@
+export interface ParsedArgs {
+    readonly vbriefPath: string | null;
+    readonly error?: string;
+}
+/** Parse vbrief-activate CLI args, mirroring the Python argparse surface (#810). */
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+export interface RunOptions {
+    readonly now?: Date;
+}
+/** Run the activator and return the process exit code (parse errors -> 2). */
+export declare function run(argv: readonly string[], options?: RunOptions): number;
+/** CLI entry alias for task wiring. */
+export declare function cmdVbriefActivate(argv: readonly string[], options?: RunOptions): number;
+//# sourceMappingURL=main.d.ts.map

package/dist/vbrief-activate/main.js

@@ -0,0 +1,33 @@
+import { activate } from "./activate.js";
+/** Parse vbrief-activate CLI args, mirroring the Python argparse surface (#810). */
+export function parseArgs(argv) {
+    if (argv.length === 0) {
+        return { vbriefPath: null, error: "the following arguments are required: vbrief_path" };
+    }
+    if (argv.length > 1) {
+        return { vbriefPath: null, error: `unrecognized arguments: ${argv.slice(1).join(" ")}` };
+    }
+    return { vbriefPath: argv[0] ?? null };
+}
+/** Run the activator and return the process exit code (parse errors -> 2). */
+export function run(argv, options = {}) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`vbrief_activate.py: ${args.error}\n`);
+        return 2;
+    }
+    const vbriefPath = args.vbriefPath;
+    const result = activate(vbriefPath, options);
+    if (result.exitCode === 0) {
+        process.stdout.write(`${result.message}\n`);
+    }
+    else {
+        process.stderr.write(`${result.message}\n`);
+    }
+    return result.exitCode;
+}
+/** CLI entry alias for task wiring. */
+export function cmdVbriefActivate(argv, options = {}) {
+    return run(argv, options);
+}
+//# sourceMappingURL=main.js.map

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

@@ -0,0 +1,13 @@
+import type { JsonObject } from "./types.js";
+/** Canonical YYYY-MM-DD date used across ingestion / migration filenames. */
+export declare let TODAY: string;
+/** Test hook: pin the module-level TODAY constant. */
+export declare function setTodayForTests(value: string): void;
+/** Convert a title to a filename-safe slug. */
+export declare function slugify(text: string): string;
+/** Return a copied reference with the default TrustLevel filled when known. */
+export declare function referenceWithDefaultTrust(ref: JsonObject): JsonObject;
+export declare function referenceHasRequiredFields(ref: JsonObject | null): boolean;
+/** Build a scope vBRIEF dict for a roadmap or issue item. */
+export declare function createScopeVbrief(item: JsonObject, repoUrl?: string, status?: string, phaseDescription?: string): JsonObject;
+//# sourceMappingURL=build.d.ts.map

package/dist/vbrief-build/build.js

@@ -0,0 +1,123 @@
+import { EMITTED_VBRIEF_VERSION, EXTERNAL_REFERENCE_TYPES, INTERNAL_REFERENCE_TYPES, MIGRATOR_METADATA_KEY, } from "./constants.js";
+/** Canonical YYYY-MM-DD date used across ingestion / migration filenames. */
+export let TODAY = new Date().toISOString().slice(0, 10);
+/** Test hook: pin the module-level TODAY constant. */
+export function setTodayForTests(value) {
+    TODAY = value;
+}
+/** Convert a title to a filename-safe slug. */
+export function slugify(text) {
+    let slug = text.toLowerCase().trim();
+    slug = slug.replace(/[^a-z0-9\s_-]/g, "");
+    slug = slug.replace(/[\s_]+/g, "-");
+    slug = slug.replace(/-+/g, "-");
+    return slug.slice(0, 60).replace(/^-+|-+$/g, "");
+}
+/**
+ * Strip trailing ``/`` characters, mirroring Python ``str.rstrip("/")``.
+ *
+ * A linear loop (no regex) so there is no backtracking — this replaces the
+ * polynomial ``/\/+$/`` form CodeQL flagged as ``js/polynomial-redos`` while
+ * preserving byte-identical behaviour with the frozen Python oracle.
+ */
+function stripTrailingSlashes(value) {
+    let result = value;
+    while (result.endsWith("/")) {
+        result = result.slice(0, -1);
+    }
+    return result;
+}
+/** Return a copied reference with the default TrustLevel filled when known. */
+export function referenceWithDefaultTrust(ref) {
+    const normalized = structuredClone(ref);
+    if ("TrustLevel" in normalized) {
+        return normalized;
+    }
+    const refType = normalized.type;
+    if (typeof refType === "string" && INTERNAL_REFERENCE_TYPES.has(refType)) {
+        normalized.TrustLevel = "internal";
+    }
+    else if (typeof refType === "string" && EXTERNAL_REFERENCE_TYPES.has(refType)) {
+        normalized.TrustLevel = "external";
+    }
+    return normalized;
+}
+function githubIssueReference(params) {
+    const cleanedRepo = stripTrailingSlashes(String(params.repoUrl ?? "").trim());
+    const cleanedNumber = String(params.number ?? "")
+        .trim()
+        .replace(/^#+/, "")
+        .trim();
+    if (!cleanedRepo || !cleanedNumber) {
+        return null;
+    }
+    const cleanedTitle = String(params.title ?? "").trim();
+    const refTitle = cleanedTitle && cleanedTitle !== "Untitled"
+        ? `Issue #${cleanedNumber}: ${cleanedTitle}`
+        : `Issue #${cleanedNumber}`;
+    return {
+        uri: `${cleanedRepo}/issues/${cleanedNumber}`,
+        type: "x-vbrief/github-issue",
+        title: refTitle,
+    };
+}
+export function referenceHasRequiredFields(ref) {
+    if (ref === null) {
+        return false;
+    }
+    for (const key of ["uri", "type"]) {
+        const value = ref[key];
+        if (typeof value !== "string" || value.trim().length === 0) {
+            return false;
+        }
+    }
+    return true;
+}
+/** Build a scope vBRIEF dict for a roadmap or issue item. */
+export function createScopeVbrief(item, repoUrl = "", status = "pending", phaseDescription = "") {
+    const number = String(item.number ?? "")
+        .trim()
+        .replace(/^#+/, "")
+        .trim();
+    const title = (String(item.title ?? "Untitled") || "Untitled").trim() || "Untitled";
+    const phase = item.phase ?? "";
+    const tier = item.tier ?? "";
+    const descLabel = number ? `#${number}: ${title}` : title;
+    const vbrief = {
+        vBRIEFInfo: {
+            version: EMITTED_VBRIEF_VERSION,
+            description: `Scope vBRIEF for ${descLabel}`,
+        },
+        plan: {
+            title,
+            status,
+            narratives: {},
+            items: [],
+        },
+    };
+    const migratorMeta = {};
+    if (phase) {
+        migratorMeta.Phase = String(phase);
+    }
+    if (tier) {
+        migratorMeta.Tier = String(tier);
+    }
+    if (phaseDescription) {
+        migratorMeta.PhaseDescription = phaseDescription;
+    }
+    if (Object.keys(migratorMeta).length > 0) {
+        const plan = vbrief.plan;
+        const metadata = (plan.metadata ?? {});
+        metadata[MIGRATOR_METADATA_KEY] = migratorMeta;
+        plan.metadata = metadata;
+    }
+    const canonicalRef = githubIssueReference({ repoUrl, number, title });
+    const trustedRef = referenceHasRequiredFields(canonicalRef) && canonicalRef !== null
+        ? referenceWithDefaultTrust(canonicalRef)
+        : null;
+    if (trustedRef !== null && referenceHasRequiredFields(trustedRef)) {
+        vbrief.plan.references = [trustedRef];
+    }
+    return vbrief;
+}
+//# sourceMappingURL=build.js.map

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

@@ -0,0 +1,13 @@
+/** Canonical ``vBRIEFInfo.version`` emitted on scope vBRIEFs (#533). */
+export declare const EMITTED_VBRIEF_VERSION = "0.6";
+/** Migrator provenance namespace under ``plan.metadata`` (#616). */
+export declare const MIGRATOR_METADATA_KEY = "x-migrator";
+export declare const PROJECT_DEFINITION_REL_PATH = "vbrief/PROJECT-DEFINITION.vbrief.json";
+export declare const DEPRECATION_SENTINEL = "<!-- deft:deprecated-redirect -->";
+export declare const INTERNAL_REFERENCE_TYPES: Set<string>;
+export declare const EXTERNAL_REFERENCE_TYPES: Set<string>;
+export declare const FOLDER_TO_STATUSES: Readonly<Record<string, readonly string[]>>;
+export declare const STATUS_TO_FOLDER: Readonly<Record<string, string>>;
+export declare const LIFECYCLE_FOLDERS: string[];
+export declare const DEFAULT_STATUS_FOR_FOLDER: Readonly<Record<string, string>>;
+//# sourceMappingURL=constants.d.ts.map