@deftai/directive-core 0.55.0

package/dist/vbrief-build/routing.js

@@ -0,0 +1,110 @@
+import { createScopeVbrief } from "./build.js";
+import { DEFAULT_STATUS_FOR_FOLDER, FOLDER_TO_STATUSES, MIGRATOR_METADATA_KEY, STATUS_TO_FOLDER, } from "./constants.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 function migrationTimestamp() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/** Return the canonical lifecycle folder for a schema status. */
+export function folderForStatus(status) {
+    const folder = STATUS_TO_FOLDER[status];
+    if (folder === undefined) {
+        throw new Error(`No lifecycle folder defined for status '${status}'; expected one of ${JSON.stringify(Object.keys(STATUS_TO_FOLDER).sort())}.`);
+    }
+    return folder;
+}
+/** Return the canonical default status the migrator uses for a folder. */
+export function defaultStatusForFolder(folder) {
+    const status = DEFAULT_STATUS_FOR_FOLDER[folder];
+    if (status === undefined) {
+        throw new Error(`Unknown lifecycle folder '${folder}'; expected one of ${JSON.stringify(Object.keys(DEFAULT_STATUS_FOR_FOLDER).sort())}.`);
+    }
+    return status;
+}
+/** Return true if ``status`` is permitted inside ``folder/`` per #506. */
+export function planStatusMatchesFolder(status, folder) {
+    const statuses = FOLDER_TO_STATUSES[folder];
+    if (statuses === undefined) {
+        return false;
+    }
+    return statuses.includes(status);
+}
+function narrativeStr(value) {
+    if (value === null || value === undefined) {
+        return "";
+    }
+    if (typeof value === "string") {
+        return value.trim();
+    }
+    return String(value).trim();
+}
+/** Build a scope vBRIEF dict from a reconciled item (#496 + #499 + #616). */
+export function buildScopeVbriefFromReconciled(reconciled, repoUrl = "", migrationTimestampOverride = null) {
+    const folder = String(reconciled.folder ?? "pending");
+    const status = String(reconciled.status ?? defaultStatusForFolder(folder));
+    const seedItem = {
+        number: reconciled.number ?? "",
+        title: reconciled.title ?? "Untitled",
+        phase: reconciled.phase ?? "",
+        tier: reconciled.tier ?? "",
+    };
+    const scope = createScopeVbrief(seedItem, repoUrl, status, String(reconciled.phase_description ?? ""));
+    const plan = scope.plan;
+    const planMeta = (plan.metadata ?? {});
+    const migratorMeta = (planMeta[MIGRATOR_METADATA_KEY] ?? {});
+    const store = (key, value) => {
+        const coerced = narrativeStr(value);
+        if (coerced) {
+            migratorMeta[key] = coerced;
+        }
+    };
+    store("Description", reconciled.description);
+    store("Description_source", reconciled.description_source);
+    store("Status_source", reconciled.status_source);
+    store("Title_source", reconciled.title_source);
+    store("SpecPhase", reconciled.spec_phase);
+    store("RoadmapSummary", reconciled.roadmap_summary);
+    store("SourceConflict", reconciled.source_conflict);
+    const sourceSection = narrativeStr(reconciled.source_section);
+    if (sourceSection) {
+        const narratives = (plan.narratives ?? {});
+        narratives.SourceSection = sourceSection;
+        plan.narratives = narratives;
+    }
+    if (Object.keys(migratorMeta).length > 0) {
+        planMeta[MIGRATOR_METADATA_KEY] = migratorMeta;
+        plan.metadata = planMeta;
+    }
+    else {
+        delete planMeta[MIGRATOR_METADATA_KEY];
+        if (Object.keys(planMeta).length > 0) {
+            plan.metadata = planMeta;
+        }
+        else {
+            delete plan.metadata;
+        }
+    }
+    if (reconciled.status === "completed") {
+        const envelope = (scope.vBRIEFInfo ?? {});
+        if (typeof envelope === "object" && envelope !== null && !Array.isArray(envelope)) {
+            if (envelope.updated === undefined) {
+                envelope.updated = migrationTimestampOverride ?? migrationTimestamp();
+            }
+            scope.vBRIEFInfo = envelope;
+        }
+    }
+    const extraRefs = reconciled.references;
+    if (Array.isArray(extraRefs) && extraRefs.length > 0) {
+        const existing = (plan.references ?? []).slice();
+        for (const ref of extraRefs) {
+            if (typeof ref === "object" && ref !== null && !Array.isArray(ref)) {
+                if (!existing.some((r) => JSON.stringify(r) === JSON.stringify(ref))) {
+                    existing.push(ref);
+                }
+            }
+        }
+        plan.references = existing;
+    }
+    return scope;
+}
+//# sourceMappingURL=routing.js.map

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

@@ -0,0 +1,16 @@
+import type { CompletedRoadmapItem, JsonObject, RoadmapItem } from "./types.js";
+/** Parse ROADMAP.md and extract items as structured data. */
+export declare function parseRoadmapItems(roadmapPath: string): {
+    readonly items: RoadmapItem[];
+    readonly phaseDescriptions: Record<string, string>;
+    readonly completedItems: CompletedRoadmapItem[];
+};
+/** Resolve the GitHub repository URL from spec_vbrief metadata. */
+export declare function resolveRepoUrl(specVbrief: JsonObject | null | undefined): string;
+/** Extract a tech-stack string from PROJECT.md content. */
+export declare function extractTechStack(projectContent: string): string;
+/** Return the first non-empty prose paragraph from markdown content. */
+export declare function firstProseParagraph(content: string): string;
+/** Derive an Overview narrative for PROJECT-DEFINITION.vbrief.json (#417). */
+export declare function deriveOverviewNarrative(specVbrief: JsonObject | null | undefined, specMdContent: string | null | undefined, projectContent: string | null | undefined, scopeItemCount: number): string;
+//# sourceMappingURL=sources.d.ts.map

package/dist/vbrief-build/sources.js

@@ -0,0 +1,294 @@
+import { readFileSync } from "node:fs";
+import { DEPRECATION_SENTINEL } from "./constants.js";
+/** Parse ROADMAP.md and extract items as structured data. */
+export function parseRoadmapItems(roadmapPath) {
+    try {
+        readFileSync(roadmapPath);
+    }
+    catch {
+        return { items: [], phaseDescriptions: {}, completedItems: [] };
+    }
+    const content = readFileSync(roadmapPath, "utf8");
+    const items = [];
+    const completedItems = [];
+    const phaseDescriptions = {};
+    let currentPhase = "";
+    let currentTier = "";
+    let inCompleted = false;
+    const descLines = [];
+    let capturingDesc = false;
+    let syntheticCounter = 0;
+    for (const line of content.split("\n")) {
+        const phaseMatch = line.match(/^##\s+(.+)/);
+        if (phaseMatch) {
+            if (currentPhase && descLines.length > 0) {
+                phaseDescriptions[currentPhase] = descLines.join("\n").trim();
+            }
+            descLines.length = 0;
+            currentPhase = phaseMatch[1]?.trim() ?? "";
+            currentTier = "";
+            if (currentPhase.toLowerCase().includes("completed")) {
+                inCompleted = true;
+                capturingDesc = false;
+            }
+            else {
+                inCompleted = false;
+                capturingDesc = true;
+            }
+            continue;
+        }
+        const tierMatch = line.match(/^###\s+(.+)/);
+        if (tierMatch) {
+            if (currentPhase && descLines.length > 0 && capturingDesc) {
+                phaseDescriptions[currentPhase] = descLines.join("\n").trim();
+                descLines.length = 0;
+                capturingDesc = false;
+            }
+            currentTier = tierMatch[1]?.trim() ?? "";
+            continue;
+        }
+        if (capturingDesc && !inCompleted) {
+            const stripped = line.trim();
+            if (stripped && !stripped.startsWith("-")) {
+                descLines.push(stripped);
+                continue;
+            }
+            if (stripped.startsWith("-")) {
+                if (descLines.length > 0) {
+                    phaseDescriptions[currentPhase] = descLines.join("\n").trim();
+                    descLines.length = 0;
+                }
+                capturingDesc = false;
+            }
+            else {
+                if (descLines.length > 0) {
+                    descLines.push("");
+                }
+                continue;
+            }
+        }
+        if (!currentPhase) {
+            continue;
+        }
+        if (inCompleted) {
+            const compMatch = line.match(/^-\s+~~(?:#?(\d+)\s*--?\s*)?(.+?)~~/);
+            if (compMatch) {
+                completedItems.push({
+                    number: compMatch[1] ?? "",
+                    title: compMatch[2]?.trim() ?? "",
+                    phase: currentPhase,
+                });
+            }
+            continue;
+        }
+        const itemMatch = line.match(/^-\s+\*\*#(\d+)\*\*\s+--\s+(.+)/);
+        if (itemMatch) {
+            items.push({
+                number: itemMatch[1] ?? "",
+                title: itemMatch[2]?.trim() ?? "",
+                phase: currentPhase,
+                tier: currentTier,
+            });
+            continue;
+        }
+        const taskMatch = line.match(/^-\s+(?:\*\*)?`([^`]+)`(?:\*\*)?\s+(.+)/);
+        if (taskMatch) {
+            items.push({
+                number: "",
+                title: taskMatch[2]?.trim() ?? "",
+                phase: currentPhase,
+                tier: currentTier,
+                task_id: taskMatch[1]?.trim() ?? "",
+            });
+            continue;
+        }
+        const genericMatch = line.match(/^-\s+(.+)/);
+        if (genericMatch) {
+            const title = genericMatch[1]?.trim() ?? "";
+            if (!title) {
+                continue;
+            }
+            syntheticCounter += 1;
+            items.push({
+                number: "",
+                title,
+                phase: currentPhase,
+                tier: currentTier,
+                synthetic_id: `roadmap-${syntheticCounter}`,
+            });
+        }
+    }
+    if (currentPhase && descLines.length > 0 && !inCompleted) {
+        phaseDescriptions[currentPhase] = descLines.join("\n").trim();
+    }
+    return { items, phaseDescriptions, completedItems };
+}
+/** Resolve the GitHub repository URL from spec_vbrief metadata. */
+export function resolveRepoUrl(specVbrief) {
+    if (specVbrief) {
+        const vbriefInfo = specVbrief.vBRIEFInfo;
+        if (typeof vbriefInfo === "object" && vbriefInfo !== null && !Array.isArray(vbriefInfo)) {
+            const repo = vbriefInfo.repository;
+            if (typeof repo === "string" && repo.length > 0) {
+                return `https://github.com/${repo}`;
+            }
+        }
+        const plan = specVbrief.plan;
+        if (typeof plan === "object" && plan !== null && !Array.isArray(plan)) {
+            const refs = plan.references;
+            if (Array.isArray(refs)) {
+                for (const ref of refs) {
+                    if (typeof ref !== "object" || ref === null || Array.isArray(ref)) {
+                        continue;
+                    }
+                    const uri = String(ref.uri ?? "");
+                    let host = "";
+                    try {
+                        host = new URL(uri).hostname;
+                    }
+                    catch {
+                        host = "";
+                    }
+                    if (host === "github.com" || host === "www.github.com") {
+                        const parts = uri.split("github.com/").pop()?.split("/") ?? [];
+                        if (parts.length >= 2) {
+                            return `https://github.com/${parts[0]}/${parts[1]}`;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return "";
+}
+/** Extract a tech-stack string from PROJECT.md content. */
+export function extractTechStack(projectContent) {
+    const boldMatch = projectContent.match(/\*\*Tech\s+Stack\*\*\s*:\s*(.+)/i);
+    if (boldMatch) {
+        return boldMatch[1]?.trim() ?? "";
+    }
+    // Python oracle: re.search(r"##\s+Tech\s+Stack\s*\n(.*?)(?=\n##\s|\Z)", ...,
+    // re.IGNORECASE | re.DOTALL). The capture is the minimal (lazy) run after the
+    // heading up to the next "\n## " heading OR the absolute end of string (\Z).
+    // We decompose into linear primitives: a non-backtracking heading match, then
+    // a slice up to the first "\n##\s" (or the whole remainder). This removes the
+    // lazy-dotAll polynomial source (js/polynomial-redos) AND fixes the prior
+    // ``\Z`` mistranslation (a literal ``Z``) that diverged from the oracle when a
+    // ``## Tech Stack`` section ran to end-of-string. See scripts/_vbrief_sources.py:193.
+    const headingMatch = projectContent.match(/##\s+Tech\s+Stack\s*\n/i);
+    if (headingMatch?.index !== undefined) {
+        const bodyStart = headingMatch.index + headingMatch[0].length;
+        const remainder = projectContent.slice(bodyStart);
+        const nextHeading = remainder.match(/\n##\s/);
+        const body = nextHeading?.index !== undefined ? remainder.slice(0, nextHeading.index) : remainder;
+        const section = body.trim();
+        if (section) {
+            return section;
+        }
+    }
+    const plainMatch = projectContent.match(/Tech\s+Stack\s*:\s*(.+)/i);
+    if (plainMatch) {
+        return plainMatch[1]?.trim() ?? "";
+    }
+    return "";
+}
+/** Return the first non-empty prose paragraph from markdown content. */
+export function firstProseParagraph(content) {
+    if (!content) {
+        return "";
+    }
+    let firstH1 = "";
+    let inCodeBlock = false;
+    const paragraphLines = [];
+    const flush = () => {
+        if (paragraphLines.length > 0) {
+            return paragraphLines.join(" ").trim();
+        }
+        return "";
+    };
+    for (const line of content.split("\n")) {
+        const stripped = line.trim();
+        if (stripped.startsWith("```")) {
+            inCodeBlock = !inCodeBlock;
+            continue;
+        }
+        if (inCodeBlock) {
+            continue;
+        }
+        if (/^#\s+/.test(stripped) && !firstH1) {
+            firstH1 = stripped.replace(/^#\s+/, "").trim();
+            continue;
+        }
+        if (stripped.startsWith("#")) {
+            const para = flush();
+            if (para) {
+                return para;
+            }
+            paragraphLines.length = 0;
+            continue;
+        }
+        if (stripped.startsWith("-") ||
+            stripped.startsWith("*") ||
+            stripped.startsWith(">") ||
+            stripped.startsWith("|") ||
+            /^\d+\.\s/.test(stripped)) {
+            const para = flush();
+            if (para) {
+                return para;
+            }
+            paragraphLines.length = 0;
+            continue;
+        }
+        if (!stripped) {
+            const para = flush();
+            if (para) {
+                return para;
+            }
+            paragraphLines.length = 0;
+            continue;
+        }
+        paragraphLines.push(stripped);
+    }
+    const para = flush();
+    if (para) {
+        return para;
+    }
+    return firstH1;
+}
+/** Derive an Overview narrative for PROJECT-DEFINITION.vbrief.json (#417). */
+export function deriveOverviewNarrative(specVbrief, specMdContent, projectContent, scopeItemCount) {
+    if (specVbrief) {
+        const plan = specVbrief.plan;
+        if (typeof plan === "object" && plan !== null && !Array.isArray(plan)) {
+            const narratives = plan.narratives;
+            if (typeof narratives === "object" && narratives !== null && !Array.isArray(narratives)) {
+                const ov = narratives.Overview;
+                if (typeof ov === "string" && ov.trim().length > 0) {
+                    return ov.trim();
+                }
+            }
+        }
+    }
+    if (specMdContent && !specMdContent.includes(DEPRECATION_SENTINEL)) {
+        const derived = firstProseParagraph(specMdContent);
+        if (derived) {
+            return derived;
+        }
+    }
+    if (projectContent && !projectContent.includes(DEPRECATION_SENTINEL)) {
+        const derived = firstProseParagraph(projectContent);
+        if (derived) {
+            return derived;
+        }
+    }
+    if (scopeItemCount > 0) {
+        return ("Project overview was not auto-derived during migration. " +
+            `${scopeItemCount} scope item(s) were created in vbrief/pending/. ` +
+            "Update vbrief/PROJECT-DEFINITION.vbrief.json narratives['Overview'] " +
+            "manually to describe your project.");
+    }
+    return ("Project overview was not auto-derived during migration. " +
+        "Update vbrief/PROJECT-DEFINITION.vbrief.json narratives['Overview'] " +
+        "manually to describe your project.");
+}
+//# sourceMappingURL=sources.js.map

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

@@ -0,0 +1,23 @@
+import type { JsonObject } from "./types.js";
+/** Return (from_id, to_id) for a vBRIEF edge, reading both dialects. */
+export declare function edgeNodes(edge: JsonObject): [string, string];
+/** Return item IDs that block ``itemId`` (bilingual reader). */
+export declare function dependenciesForItem(itemId: string, edges: readonly JsonObject[]): string[];
+/** Return a slug for a speckit IP item filename. */
+export declare function speckitIpSlug(title: string, itemId: string): string;
+/** Derive the numeric IP index for a speckit plan item. */
+export declare function speckitIpIndex(item: JsonObject, fallbackIndex: number): number;
+/** Build a Phase 4 scope vBRIEF dict for a speckit implementation phase. */
+export declare function createSpeckitScopeVbrief(item: JsonObject, options: {
+    readonly ipIndex: number;
+    readonly dependencies: readonly string[];
+    readonly specRef: string;
+}): JsonObject;
+/** Translate a speckit-shaped ``plan.vbrief.json`` into scope vBRIEFs. */
+export declare function migrateSpeckitPlan(planPath: string, options?: {
+    readonly pendingDir?: string;
+    readonly date?: string;
+    readonly specRef?: string;
+    readonly today?: string;
+}): [boolean, string[]];
+//# sourceMappingURL=speckit.d.ts.map

package/dist/vbrief-build/speckit.js

@@ -0,0 +1,212 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename } from "node:path";
+import { referenceWithDefaultTrust, slugify } from "./build.js";
+import { EMITTED_VBRIEF_VERSION } from "./constants.js";
+import { pythonJsonPretty } from "./json.js";
+/** Return (from_id, to_id) for a vBRIEF edge, reading both dialects. */
+export function edgeNodes(edge) {
+    if (typeof edge !== "object" || edge === null || Array.isArray(edge)) {
+        return ["", ""];
+    }
+    const src = edge.from ?? edge.source ?? "";
+    const tgt = edge.to ?? edge.target ?? "";
+    return [String(src || ""), String(tgt || "")];
+}
+/** Return item IDs that block ``itemId`` (bilingual reader). */
+export function dependenciesForItem(itemId, edges) {
+    const deps = [];
+    for (const edge of edges ?? []) {
+        if (typeof edge !== "object" || edge === null || Array.isArray(edge)) {
+            continue;
+        }
+        if (edge.type !== "blocks") {
+            continue;
+        }
+        const [src, tgt] = edgeNodes(edge);
+        if (tgt === itemId && src && !deps.includes(src)) {
+            deps.push(src);
+        }
+    }
+    return deps;
+}
+/** Return a slug for a speckit IP item filename. */
+export function speckitIpSlug(title, itemId) {
+    let source = (title || itemId || "").trim();
+    source = source.replace(/^\s*IP[\s-]*\d+\s*[:-]\s*/i, "");
+    const slug = slugify(source);
+    return slug || slugify(itemId) || "ip-phase";
+}
+/** Derive the numeric IP index for a speckit plan item. */
+export function speckitIpIndex(item, fallbackIndex) {
+    const itemId = String(item.id ?? "");
+    // Python oracle: re.search(r"(\d+)\s*$", item_id). Digits and whitespace are
+    // disjoint classes, so trimming trailing whitespace first and anchoring with
+    // /(\d+)$/ is parity-exact while removing the polynomial backtracking CodeQL
+    // flagged (js/polynomial-redos). See scripts/_vbrief_speckit.py:69.
+    const tail = itemId.trimEnd().match(/(\d+)$/);
+    if (tail) {
+        return Number.parseInt(tail[1] ?? "0", 10);
+    }
+    const title = String(item.title ?? "");
+    const lead = title.match(/IP[\s-]*(\d+)/i);
+    if (lead) {
+        return Number.parseInt(lead[1] ?? "0", 10);
+    }
+    return fallbackIndex;
+}
+function nonEmptyText(value, fallback) {
+    const text = String(value ?? "").trim();
+    return text || fallback;
+}
+function vbriefRelativeSpecRef(specRef) {
+    let normalized = specRef.trim();
+    while (normalized.startsWith("../")) {
+        normalized = normalized.slice(3);
+    }
+    return normalized || "specification.vbrief.json";
+}
+/** Build a Phase 4 scope vBRIEF dict for a speckit implementation phase. */
+export function createSpeckitScopeVbrief(item, options) {
+    const specRef = vbriefRelativeSpecRef(options.specRef);
+    const fallbackTitle = `IP-${options.ipIndex}`;
+    const title = nonEmptyText(item.title, fallbackTitle);
+    const rawNarrative = item.narrative;
+    const narrative = typeof rawNarrative === "object" && rawNarrative !== null && !Array.isArray(rawNarrative)
+        ? rawNarrative
+        : {};
+    const pick = (...keys) => {
+        for (const key of keys) {
+            const value = narrative[key];
+            if (typeof value === "string" && value.trim().length > 0) {
+                return value.trim();
+            }
+        }
+        return "";
+    };
+    const description = pick("Description", "Summary") || title || fallbackTitle;
+    const acceptance = pick("Acceptance", "AcceptanceCriteria");
+    const traces = pick("Traces", "Trace", "Requirements") || fallbackTitle;
+    const defaultAcceptance = `Acceptance criteria for IP-${options.ipIndex} (copy from specification.vbrief.json).`;
+    const narratives = {
+        Description: description,
+        Acceptance: acceptance || defaultAcceptance,
+        Traces: traces,
+    };
+    for (const extra of ["Phase", "PhaseDescription", "Tier"]) {
+        const value = narrative[extra];
+        if (typeof value === "string" && value.trim().length > 0) {
+            narratives[extra] = value.trim();
+        }
+    }
+    const references = [
+        referenceWithDefaultTrust({ type: "x-vbrief/plan", uri: specRef }),
+    ];
+    const itemRefs = item.references;
+    if (Array.isArray(itemRefs)) {
+        for (const ref of itemRefs) {
+            if (typeof ref === "object" &&
+                ref !== null &&
+                !Array.isArray(ref) &&
+                ref.type !== "x-vbrief/plan") {
+                references.push(referenceWithDefaultTrust(ref));
+            }
+        }
+    }
+    const metadata = { kind: "phase" };
+    if (options.dependencies.length > 0) {
+        metadata.dependencies = [...options.dependencies];
+    }
+    return {
+        vBRIEFInfo: {
+            version: EMITTED_VBRIEF_VERSION,
+            description: `Scope vBRIEF for speckit IP-${options.ipIndex}`,
+        },
+        plan: {
+            title,
+            status: "pending",
+            narratives,
+            items: [],
+            metadata,
+            references,
+        },
+    };
+}
+/** Translate a speckit-shaped ``plan.vbrief.json`` into scope vBRIEFs. */
+export function migrateSpeckitPlan(planPath, options = {}) {
+    const actions = [];
+    if (!existsSync(planPath)) {
+        return [false, [`ERROR: plan.vbrief.json not found at ${planPath}`]];
+    }
+    let planData;
+    try {
+        planData = JSON.parse(readFileSync(planPath, "utf8"));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return [false, [`ERROR: invalid JSON in ${basename(planPath)}: ${msg}`]];
+    }
+    const planRoot = typeof planData === "object" && planData !== null ? planData : {};
+    const plan = typeof planRoot.plan === "object" && planRoot.plan !== null && !Array.isArray(planRoot.plan)
+        ? planRoot.plan
+        : {};
+    const items = Array.isArray(plan.items) ? plan.items : [];
+    const edges = Array.isArray(plan.edges) ? plan.edges : [];
+    if (items.length === 0) {
+        return [false, ["ERROR: plan.vbrief.json has no items to migrate (empty speckit plan?)"]];
+    }
+    const planDir = planPath.replace(/[/\\][^/\\]+$/, "");
+    const pendingDir = options.pendingDir ?? `${planDir}/pending`;
+    mkdirSync(pendingDir, { recursive: true });
+    const effectiveDate = options.date ?? options.today ?? new Date().toISOString().slice(0, 10);
+    const specRef = options.specRef ?? "specification.vbrief.json";
+    for (let idx = 0; idx < items.length; idx += 1) {
+        const item = items[idx];
+        if (typeof item !== "object" || item === null || Array.isArray(item)) {
+            continue;
+        }
+        const itemObj = item;
+        const ipIndex = speckitIpIndex(itemObj, idx + 1);
+        const itemId = String(itemObj.id ?? `ip-${ipIndex}`);
+        const dependencies = dependenciesForItem(itemId, edges);
+        const slug = speckitIpSlug(String(itemObj.title ?? ""), itemId);
+        const ipToken = `ip${String(ipIndex).padStart(3, "0")}`;
+        const filename = `${effectiveDate}-${ipToken}-${slug}.vbrief.json`;
+        const target = `${pendingDir}/${filename}`;
+        try {
+            readFileSync(target);
+            actions.push(`SKIP   pending/${filename} already exists`);
+            continue;
+        }
+        catch {
+            /* create new file */
+        }
+        const scope = createSpeckitScopeVbrief(itemObj, {
+            ipIndex,
+            dependencies,
+            specRef,
+        });
+        writeFileSync(target, pythonJsonPretty(scope), { encoding: "utf8" });
+        actions.push(`CREATE pending/${filename} (IP-${ipIndex})`);
+    }
+    const envelope = typeof planRoot.vBRIEFInfo === "object" &&
+        planRoot.vBRIEFInfo !== null &&
+        !Array.isArray(planRoot.vBRIEFInfo)
+        ? { ...planRoot.vBRIEFInfo }
+        : {};
+    envelope.version = EMITTED_VBRIEF_VERSION;
+    envelope.description =
+        "Session-level tactical plan (migrated from speckit plan). " +
+            "Scope vBRIEFs live in vbrief/pending/.";
+    const sessionPlan = {
+        vBRIEFInfo: envelope,
+        plan: {
+            title: String(plan.title ?? "Session plan") || "Session plan",
+            status: "running",
+            items: [],
+        },
+    };
+    writeFileSync(planPath, pythonJsonPretty(sessionPlan), { encoding: "utf8" });
+    actions.push(`REWRITE ${basename(planPath)} -> session-todo scaffold`);
+    return [true, actions];
+}
+//# sourceMappingURL=speckit.js.map

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

@@ -0,0 +1,18 @@
+export type JsonObject = Record<string, unknown>;
+export declare class ProjectDefinitionIOError extends Error {
+    constructor(message: string);
+}
+export interface RoadmapItem {
+    readonly number: string;
+    readonly title: string;
+    readonly phase: string;
+    readonly tier: string;
+    readonly task_id?: string;
+    readonly synthetic_id?: string;
+}
+export interface CompletedRoadmapItem {
+    readonly number: string;
+    readonly title: string;
+    readonly phase: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/vbrief-build/types.js

@@ -0,0 +1,7 @@
+export class ProjectDefinitionIOError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ProjectDefinitionIOError";
+    }
+}
+//# sourceMappingURL=types.js.map