@davidorex/pi-context 0.26.0

package/dist/rename-canonical-id.d.ts

@@ -0,0 +1,64 @@
+/**
+ * canonical_id rename engine (FGAP-060 / DEC-0035).
+ *
+ * canonical_ids are primary-key-permanent — the steady state is "never rename".
+ * The rare, deliberate rename routes exclusively through `renameCanonicalId`,
+ * which rewrites every substrate surface that carries the id as DATA and
+ * REPORTS (never rewrites) every out-of-substrate occurrence (analysis MDs,
+ * git history) so the operator can follow up manually.
+ *
+ * Edge model (DEC-0013): inter-item references live ONLY as relations.json
+ * edges — there is NO inline-FK field on item schemas, so the engine performs
+ * NO inline-FK sweep. Item renames touch (1) the item's home block id field and
+ * (2) every edge whose parent/child equals the old id.
+ *
+ * Five canonical_id kinds exist; this engine implements four:
+ *   - item          (a block item's id, e.g. DEC-0001)
+ *   - relation_type (a config.relation_types[].canonical_id)
+ *   - lens          (a config.lenses[].id)
+ *   - layer         (a config.layers[].id)
+ * The fifth — block_kind — THROWS unsupported: a block_kind rename requires a
+ * coupled file / data_path / array_key / schema_path filesystem cascade, which
+ * is tracked separately.
+ *
+ * Write discipline:
+ *   - Guards (existence / collision / block_kind / unknown-kind) throw BEFORE
+ *     any write — a guard failure leaves the substrate byte-untouched.
+ *   - dryRun computes the would-change counts but performs ZERO writes.
+ *   - All config-surface changes accumulate into a single deep-cloned config
+ *     object written ONCE via writeConfig (never multiple config writes).
+ */
+export type RenameKind = "item" | "relation_type" | "lens" | "layer";
+export interface RenameReport {
+    kind: string;
+    oldId: string;
+    newId: string;
+    dryRun: boolean;
+    /** Per-surface rewrite tally — each entry is one (file, field) surface that
+     * carried ≥1 occurrence of oldId, with the count of occurrences rewritten. */
+    substrateRewrites: {
+        file: string;
+        field: string;
+        count: number;
+    }[];
+    /** Out-of-substrate occurrences — REPORT ONLY, never rewritten. */
+    outOfSubstrate: {
+        source: string;
+        context: string;
+    }[];
+}
+/**
+ * Rename a canonical_id of `kind` from `oldId` to `newId`.
+ *
+ * Returns a {@link RenameReport} describing every substrate surface rewritten
+ * (or that WOULD be rewritten, under `dryRun`) plus every out-of-substrate
+ * occurrence found (always report-only).
+ *
+ * Throws on: kind=block_kind (unsupported), unknown kind, missing config,
+ * oldId not present for the kind, or collision (newId already exists for the
+ * kind). All such throws occur before any write.
+ */
+export declare function renameCanonicalId(cwd: string, kind: string, oldId: string, newId: string, opts?: {
+    dryRun?: boolean;
+}): RenameReport;
+//# sourceMappingURL=rename-canonical-id.d.ts.map

package/dist/rename-canonical-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rename-canonical-id.d.ts","sourceRoot":"","sources":["../src/rename-canonical-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AASH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,eAAe,GAAG,MAAM,GAAG,OAAO,CAAC;AAErE,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB;kFAC8E;IAC9E,iBAAiB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACpE,mEAAmE;IACnE,cAAc,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAChC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GACzB,YAAY,CA2Qd"}

package/dist/rename-canonical-id.js

@@ -0,0 +1,378 @@
+/**
+ * canonical_id rename engine (FGAP-060 / DEC-0035).
+ *
+ * canonical_ids are primary-key-permanent — the steady state is "never rename".
+ * The rare, deliberate rename routes exclusively through `renameCanonicalId`,
+ * which rewrites every substrate surface that carries the id as DATA and
+ * REPORTS (never rewrites) every out-of-substrate occurrence (analysis MDs,
+ * git history) so the operator can follow up manually.
+ *
+ * Edge model (DEC-0013): inter-item references live ONLY as relations.json
+ * edges — there is NO inline-FK field on item schemas, so the engine performs
+ * NO inline-FK sweep. Item renames touch (1) the item's home block id field and
+ * (2) every edge whose parent/child equals the old id.
+ *
+ * Five canonical_id kinds exist; this engine implements four:
+ *   - item          (a block item's id, e.g. DEC-0001)
+ *   - relation_type (a config.relation_types[].canonical_id)
+ *   - lens          (a config.lenses[].id)
+ *   - layer         (a config.layers[].id)
+ * The fifth — block_kind — THROWS unsupported: a block_kind rename requires a
+ * coupled file / data_path / array_key / schema_path filesystem cascade, which
+ * is tracked separately.
+ *
+ * Write discipline:
+ *   - Guards (existence / collision / block_kind / unknown-kind) throw BEFORE
+ *     any write — a guard failure leaves the substrate byte-untouched.
+ *   - dryRun computes the would-change counts but performs ZERO writes.
+ *   - All config-surface changes accumulate into a single deep-cloned config
+ *     object written ONCE via writeConfig (never multiple config writes).
+ */
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { readBlock, updateItemInBlock, writeBlock } from "./block-api.js";
+import { loadConfig, loadRelations, writeConfig, writeRelations } from "./context.js";
+import { buildIdIndex } from "./context-sdk.js";
+/**
+ * Rename a canonical_id of `kind` from `oldId` to `newId`.
+ *
+ * Returns a {@link RenameReport} describing every substrate surface rewritten
+ * (or that WOULD be rewritten, under `dryRun`) plus every out-of-substrate
+ * occurrence found (always report-only).
+ *
+ * Throws on: kind=block_kind (unsupported), unknown kind, missing config,
+ * oldId not present for the kind, or collision (newId already exists for the
+ * kind). All such throws occur before any write.
+ */
+export function renameCanonicalId(cwd, kind, oldId, newId, opts) {
+    const dryRun = opts?.dryRun ?? false;
+    const report = {
+        kind,
+        oldId,
+        newId,
+        dryRun,
+        substrateRewrites: [],
+        outOfSubstrate: [],
+    };
+    if (kind === "block_kind") {
+        throw new Error("renameCanonicalId: kind 'block_kind' is not supported — a block_kind canonical_id rename requires a coupled file/data_path/array_key/schema_path cascade (buildIdIndex resolves loc.block by file basename). Tracked separately; use display_name for relabeling.");
+    }
+    const config = loadConfig(cwd);
+    if (!config) {
+        throw new Error("renameCanonicalId: no config.json");
+    }
+    // Single deep-cloned config accumulator: every config-surface rewrite mutates
+    // THIS object; a single writeConfig at the end (when !dryRun and changed)
+    // commits all surfaces atomically. Never write config more than once.
+    const nextConfig = JSON.parse(JSON.stringify(config));
+    let configChanged = false;
+    if (kind === "item") {
+        const idx = buildIdIndex(cwd);
+        const loc = idx.get(oldId);
+        if (!loc)
+            throw new Error(`renameCanonicalId: item '${oldId}' not found`);
+        if (idx.has(newId))
+            throw new Error(`renameCanonicalId: collision — item '${newId}' already exists`);
+        // Home block id field.
+        if (!dryRun) {
+            updateItemInBlock(cwd, loc.block, loc.arrayKey, (i) => i.id === oldId, { id: newId });
+        }
+        report.substrateRewrites.push({ file: `${loc.block}.json`, field: "id", count: 1 });
+        // Edges: rewrite parent and/or child wherever they equal oldId. Each
+        // endpoint occurrence counts once (an edge with oldId on BOTH endpoints
+        // counts as 2).
+        const edges = loadRelations(cwd);
+        let n = 0;
+        const next = edges.map((e) => {
+            let p = e.parent;
+            let c = e.child;
+            if (p === oldId) {
+                p = newId;
+                n++;
+            }
+            if (c === oldId) {
+                c = newId;
+                n++;
+            }
+            return { ...e, parent: p, child: c };
+        });
+        if (n > 0) {
+            if (!dryRun)
+                writeRelations(cwd, next);
+            report.substrateRewrites.push({ file: "relations.json", field: "parent/child", count: n });
+        }
+    }
+    else if (kind === "relation_type") {
+        const rt = config.relation_types ?? [];
+        if (!rt.some((r) => r.canonical_id === oldId)) {
+            throw new Error(`renameCanonicalId: relation_type '${oldId}' not found`);
+        }
+        if (rt.some((r) => r.canonical_id === newId)) {
+            throw new Error(`renameCanonicalId: collision — relation_type '${newId}' already exists`);
+        }
+        // config.relation_types[].canonical_id
+        for (const r of nextConfig.relation_types ?? []) {
+            if (r.canonical_id === oldId) {
+                r.canonical_id = newId;
+                configChanged = true;
+                report.substrateRewrites.push({ file: "config.json", field: "relation_types[].canonical_id", count: 1 });
+            }
+        }
+        // config.invariants[].relation_types[] (array of strings)
+        let invCount = 0;
+        for (const inv of nextConfig.invariants ?? []) {
+            if (!Array.isArray(inv.relation_types))
+                continue;
+            inv.relation_types = inv.relation_types.map((v) => {
+                if (v === oldId) {
+                    invCount++;
+                    return newId;
+                }
+                return v;
+            });
+        }
+        if (invCount > 0) {
+            configChanged = true;
+            report.substrateRewrites.push({ file: "config.json", field: "invariants[].relation_types[]", count: invCount });
+        }
+        // config.lenses[].relation_type
+        let lensCount = 0;
+        for (const l of nextConfig.lenses ?? []) {
+            if (l.relation_type === oldId) {
+                l.relation_type = newId;
+                lensCount++;
+            }
+        }
+        if (lensCount > 0) {
+            configChanged = true;
+            report.substrateRewrites.push({ file: "config.json", field: "lenses[].relation_type", count: lensCount });
+        }
+        // config.hierarchy[].relation_type
+        let hierCount = 0;
+        for (const h of nextConfig.hierarchy ?? []) {
+            if (h.relation_type === oldId) {
+                h.relation_type = newId;
+                hierCount++;
+            }
+        }
+        if (hierCount > 0) {
+            configChanged = true;
+            report.substrateRewrites.push({ file: "config.json", field: "hierarchy[].relation_type", count: hierCount });
+        }
+        // relations.json edges by relation_type
+        const edges = loadRelations(cwd);
+        let n = 0;
+        const next = edges.map((e) => {
+            if (e.relation_type === oldId) {
+                n++;
+                return { ...e, relation_type: newId };
+            }
+            return e;
+        });
+        if (n > 0) {
+            if (!dryRun)
+                writeRelations(cwd, next);
+            report.substrateRewrites.push({ file: "relations.json", field: "relation_type", count: n });
+        }
+        // context-contracts block (ONLY if its data file exists). Each contract's
+        // bundle_relation_types[].relation_type is rewritten. Absent block →
+        // silently skip (this repo's .project has no context-contracts data file).
+        try {
+            const ccData = readBlock(cwd, "context-contracts");
+            let ccCount = 0;
+            let arrayKey;
+            for (const [k, v] of Object.entries(ccData)) {
+                if (Array.isArray(v)) {
+                    arrayKey = k;
+                    break;
+                }
+            }
+            if (arrayKey) {
+                const contracts = ccData[arrayKey];
+                for (const contract of contracts) {
+                    const brt = contract.bundle_relation_types;
+                    if (!Array.isArray(brt))
+                        continue;
+                    for (const entry of brt) {
+                        if (entry && entry.relation_type === oldId) {
+                            entry.relation_type = newId;
+                            ccCount++;
+                        }
+                    }
+                }
+                if (ccCount > 0) {
+                    if (!dryRun)
+                        writeBlock(cwd, "context-contracts", ccData);
+                    report.substrateRewrites.push({
+                        file: "context-contracts.json",
+                        field: "bundle_relation_types[].relation_type",
+                        count: ccCount,
+                    });
+                }
+            }
+        }
+        catch {
+            // context-contracts block absent — skip silently.
+        }
+    }
+    else if (kind === "lens") {
+        const ls = config.lenses ?? [];
+        if (!ls.some((l) => l.id === oldId))
+            throw new Error(`renameCanonicalId: lens '${oldId}' not found`);
+        if (ls.some((l) => l.id === newId)) {
+            throw new Error(`renameCanonicalId: collision — lens '${newId}' already exists`);
+        }
+        // config.lenses[].id
+        let idCount = 0;
+        for (const l of nextConfig.lenses ?? []) {
+            if (l.id === oldId) {
+                l.id = newId;
+                idCount++;
+            }
+        }
+        if (idCount > 0) {
+            configChanged = true;
+            report.substrateRewrites.push({ file: "config.json", field: "lenses[].id", count: idCount });
+        }
+        // config.lenses[].members[].lens (composition member references)
+        let memberCount = 0;
+        for (const l of nextConfig.lenses ?? []) {
+            for (const m of l.members ?? []) {
+                if (m.lens === oldId) {
+                    m.lens = newId;
+                    memberCount++;
+                }
+            }
+        }
+        if (memberCount > 0) {
+            configChanged = true;
+            report.substrateRewrites.push({ file: "config.json", field: "lenses[].members[].lens", count: memberCount });
+        }
+    }
+    else if (kind === "layer") {
+        const ly = config.layers ?? [];
+        if (!ly.some((l) => l.id === oldId))
+            throw new Error(`renameCanonicalId: layer '${oldId}' not found`);
+        if (ly.some((l) => l.id === newId)) {
+            throw new Error(`renameCanonicalId: collision — layer '${newId}' already exists`);
+        }
+        // config.layers[].id
+        let idCount = 0;
+        for (const l of nextConfig.layers ?? []) {
+            if (l.id === oldId) {
+                l.id = newId;
+                idCount++;
+            }
+        }
+        if (idCount > 0) {
+            configChanged = true;
+            report.substrateRewrites.push({ file: "config.json", field: "layers[].id", count: idCount });
+        }
+        // config.block_kinds[].layer (FK to layers[].id)
+        let bkCount = 0;
+        for (const bk of nextConfig.block_kinds ?? []) {
+            if (bk.layer === oldId) {
+                bk.layer = newId;
+                bkCount++;
+            }
+        }
+        if (bkCount > 0) {
+            configChanged = true;
+            report.substrateRewrites.push({ file: "config.json", field: "block_kinds[].layer", count: bkCount });
+        }
+    }
+    else {
+        throw new Error(`renameCanonicalId: unknown kind '${kind}'`);
+    }
+    // ── config.naming alias key (ALL kinds) ───────────────────────────────────
+    // The naming map keys are canonical ids → display labels. A rename of the id
+    // must carry its alias key forward (value preserved). This folds into the
+    // SAME config write.
+    if (nextConfig.naming && Object.hasOwn(nextConfig.naming, oldId)) {
+        const value = nextConfig.naming[oldId];
+        delete nextConfig.naming[oldId];
+        nextConfig.naming[newId] = value;
+        configChanged = true;
+        report.substrateRewrites.push({ file: "config.json", field: "naming", count: 1 });
+    }
+    // ── Single config write ───────────────────────────────────────────────────
+    if (configChanged && !dryRun) {
+        writeConfig(cwd, nextConfig);
+    }
+    // ── Out-of-substrate scan (report-only, ALL kinds, NEVER rewrite) ──────────
+    collectAnalysisMatches(cwd, oldId, report);
+    collectGitMatches(cwd, oldId, report);
+    return report;
+}
+/**
+ * Recursively walk `<cwd>/analysis/**.md`; for each file whose text contains
+ * oldId, push a report-only entry. Skips silently when the analysis dir is
+ * absent. NEVER rewrites file content.
+ */
+function collectAnalysisMatches(cwd, oldId, report) {
+    const analysisDir = path.join(cwd, "analysis");
+    if (!fs.existsSync(analysisDir))
+        return;
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.isFile() && entry.name.endsWith(".md")) {
+                let text;
+                try {
+                    text = fs.readFileSync(full, "utf-8");
+                }
+                catch {
+                    continue;
+                }
+                if (text.includes(oldId)) {
+                    const rel = path.relative(cwd, full);
+                    const firstLine = text.split("\n").find((ln) => ln.includes(oldId));
+                    report.outOfSubstrate.push({
+                        source: rel,
+                        context: firstLine ? firstLine.trim() : "matches in analysis md",
+                    });
+                }
+            }
+        }
+    };
+    walk(analysisDir);
+}
+/**
+ * Best-effort `git log --oneline -S<oldId>` against `cwd`; each output line
+ * becomes a report-only entry. Any failure (no git, not a repo, etc.) is
+ * swallowed — the scan is purely informational.
+ */
+function collectGitMatches(cwd, oldId, report) {
+    try {
+        const out = execSync(`git log --oneline -S${shellQuote(oldId)}`, {
+            cwd,
+            stdio: ["ignore", "pipe", "ignore"],
+            encoding: "utf-8",
+        });
+        for (const line of out.split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed.length > 0) {
+                report.outOfSubstrate.push({ source: "git", context: trimmed });
+            }
+        }
+    }
+    catch {
+        // no git / not a repo / no matches with nonzero exit — skip silently.
+    }
+}
+/** Single-quote a token for safe shell interpolation (escapes embedded quotes). */
+function shellQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+//# sourceMappingURL=rename-canonical-id.js.map

package/dist/rename-canonical-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rename-canonical-id.js","sourceRoot":"","sources":["../src/rename-canonical-id.ts"],"names":[],"mappings":"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"}

package/dist/roadmap-plan.d.ts

@@ -0,0 +1,186 @@
+import { type Edge, type ItemRecord, type StatusBucket } from "./context.js";
+import { type LoadedLensView } from "./lens-view.js";
+import { resolveStatusVocabulary, STATUS_VOCABULARY_DEFAULTS } from "./status-vocab.js";
+import { topoSort } from "./topo.js";
+export type { StatusBucket } from "./status-vocab.js";
+export { resolveStatusVocabulary, STATUS_VOCABULARY_DEFAULTS };
+export interface PhaseStatus {
+    bucket: StatusBucket;
+    counts: Record<StatusBucket, number>;
+    total: number;
+}
+/**
+ * Bucket each item's status field against the vocabulary; return counts
+ * + the rolled-up bucket (most-blocking bucket present, or unknown when
+ * items array is empty / no items have a status field).
+ *
+ * Rollup precedence (most-blocking wins for the bucket field):
+ *   blocked > in_progress > todo > complete > unknown
+ * — meaning a phase with any blocked item rolls up as blocked even if
+ * other items are complete; a phase with all-complete items rolls up
+ * complete. This matches typical product-management roadmap-status
+ * conventions (a phase isn't "in progress" if everything's done; it's
+ * "complete"; a phase with anything blocked needs attention).
+ *
+ * Vocabulary defaults to STATUS_VOCABULARY_DEFAULTS when omitted —
+ * loaders that have already resolved per-project overrides via
+ * resolveStatusVocabulary should pass the resolved map in to keep
+ * config.status_buckets-driven mappings consistent across a single load.
+ */
+export declare function rollupPhaseStatus(items: ItemRecord[], vocabulary?: Record<string, StatusBucket>): PhaseStatus;
+/**
+ * Generic topological sort with cycle detection. Implementation:
+ * Kahn's algorithm — repeatedly remove nodes with no incoming edges,
+ * append to order, decrement in-degree of their dependents. Any nodes
+ * remaining after the in-degree pass form one or more cycles; the
+ * cycle-finding pass uses DFS with recursion-stack tracking to extract
+ * each distinct cycle path.
+ *
+ * Returns:
+ *   order — node ids in dependency-respecting order. Independent nodes
+ *     appear in input order (Kahn's algorithm preserves insertion order
+ *     within a stratum).
+ *   cycles — array of cycle paths, each as a string[] starting and
+ *     ending with the same id. Empty when graph is acyclic.
+ *
+ * Caller chooses whether cycles are fatal: validateRoadmaps surfaces
+ * roadmap_phase_cycle; loadRoadmap returns the cycles[] alongside a
+ * partial order so renderRoadmap can show what it could and what
+ * couldn't be ordered.
+ */
+export { topoSort };
+/**
+ * Phase entry as authored in roadmap.json. NO depends_on field — ordering
+ * lives in relations.json per DEC-0012.
+ */
+export interface PhaseSpec {
+    id: string;
+    name: string;
+    description?: string;
+    lens: string;
+    milestone?: string;
+    exit_criteria?: string[];
+}
+/**
+ * Inline milestone declared by a roadmap. evidence_block + evidence_query
+ * together drive milestoneSatisfied evaluation: milestone is satisfied
+ * when at least one item in evidence_block matches every key/value in
+ * evidence_query by ===.
+ */
+export interface MilestoneSpec {
+    id: string;
+    name: string;
+    criterion?: string;
+    evidence_block?: string;
+    evidence_query?: Record<string, unknown>;
+}
+/**
+ * Roadmap entry as authored in roadmap.json's roadmaps[] array.
+ */
+export interface RoadmapSpec {
+    id: string;
+    title: string;
+    description?: string;
+    status?: string;
+    phases: PhaseSpec[];
+    milestones?: MilestoneSpec[];
+}
+/**
+ * Per-phase loaded view: phase spec + its lens-view (or error) + status
+ * rollup over the lens's items + optional milestone resolution.
+ */
+export interface PhaseView {
+    phase: PhaseSpec;
+    lensView: LoadedLensView | {
+        error: string;
+    };
+    status: PhaseStatus;
+    milestone?: MilestoneSpec;
+    milestoneSatisfied?: boolean;
+}
+/**
+ * Materialized roadmap view. `phases` carries PhaseView entries in
+ * authored input order. `phaseOrder` is the topo order over the
+ * `phase_depends_on` edges scoped to in-roadmap phases — partial when
+ * cycles are present (cycle-participating phases are absent from
+ * phaseOrder and surfaced separately in `cycles`). `edges` is the
+ * authoritative scoped subset of authored edges and is the renderer's
+ * sole source for per-phase adjacency lines (the renderer never infers
+ * adjacency from phaseOrder consecutive pairs — that pattern fabricates
+ * sibling edges in branching DAGs and is forbidden).
+ */
+export interface RoadmapView {
+    roadmap: RoadmapSpec;
+    phases: PhaseView[];
+    phaseOrder: string[];
+    cycles: string[][];
+    edges: Edge[];
+}
+export interface RoadmapValidationIssue {
+    code: "roadmap_lens_missing" | "roadmap_phase_dep_missing" | "roadmap_phase_cycle" | "roadmap_milestone_evidence_block_missing" | "roadmap_milestone_query_invalid" | "roadmap_composition_cycle" | "roadmap_status_unknown_value";
+    message: string;
+    roadmap_id?: string;
+    phase_id?: string;
+    cycle?: string[];
+}
+/**
+ * Load a single roadmap by id. Returns the materialized RoadmapView or a
+ * structured { error } when config / block / id is missing.
+ *
+ * Algorithm:
+ *   1. Load context; bail when no .project/config.json.
+ *   2. Defensively read roadmap.json; bail when absent.
+ *   3. Lookup the roadmap by id; bail when unknown.
+ *   4. Build PhaseView[] in authored input order (loadLensView per phase,
+ *      rollupPhaseStatus over the resulting items, milestone resolution
+ *      where declared).
+ *   5. Compute the in-roadmap edge subset (phase_depends_on edges whose
+ *      both endpoints are in the roadmap) and topo-sort to derive
+ *      phaseOrder + cycles.
+ *
+ * The returned `edges` field is the authoritative scoped subset that the
+ * renderer consumes for per-phase adjacency lines.
+ */
+export declare function loadRoadmap(cwd: string, roadmapId: string): RoadmapView | {
+    error: string;
+};
+/**
+ * Discovery — returns one summary entry per roadmap. Empty array when
+ * roadmap.json is absent (listing is discovery; absence is the truthful
+ * answer, not an error).
+ */
+export declare function listRoadmaps(cwd: string): Array<{
+    id: string;
+    title: string;
+    status?: string;
+    phaseCount: number;
+}>;
+/**
+ * Validate every roadmap × phase × milestone. Codes are opaque slugs;
+ * display strings resolve via diagMessage (config.display_strings →
+ * embedded English fallback). The pi-context lens-validator dispatch
+ * (registered at module bottom) maps these to ContextValidationIssue-
+ * compatible records and merges them into validateContext's output.
+ *
+ * Roadmap.json absent → { status: "clean", issues: [] } (opt-in block;
+ * absence is not a defect).
+ */
+export declare function validateRoadmaps(cwd: string): {
+    status: "clean" | "warnings" | "invalid";
+    issues: RoadmapValidationIssue[];
+};
+/**
+ * Render a loaded RoadmapView as pure-textual markdown — NO mermaid, NO
+ * diagrams, NO graph syntax. Per-phase **Depends on:** adjacency lines
+ * are sourced strictly from view.edges (sorted alphabetically; "—" when
+ * the phase has no incoming phase_depends_on edges). Cycle-participating
+ * phases are surfaced under a separate "**Unordered (cycle-participating):**"
+ * heading and a "**Cycles detected:**" line. The renderer never infers
+ * adjacency from phaseOrder consecutive pairs (that pattern fabricates
+ * sibling edges in branching DAGs).
+ *
+ * naming consulted only for lens-target display labels; phase / roadmap
+ * ids render as-is.
+ */
+export declare function renderRoadmap(view: RoadmapView, naming: Record<string, string> | undefined): string;
+//# sourceMappingURL=roadmap-plan.d.ts.map

package/dist/roadmap-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roadmap-plan.d.ts","sourceRoot":"","sources":["../src/roadmap-plan.ts"],"names":[],"mappings":"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"}