@davidorex/pi-context 0.30.0 → 0.32.0

package/dist/roadmap-plan.js

@@ -1,10 +1,15 @@
 /**
- * Roadmap + plan substrate primitives — pure functions over typed blocks.
+ * Roadmap substrate primitives — the roadmap as a DERIVED view over the
+ * milestone block + authored relations (FGAP-042). There is no roadmap block,
+ * no roadmap.json, and no ROADMAP- id: the roadmap IS the milestone-block
+ * items ordered by the `milestone_precedes_milestone` closure-table edges,
+ * with per-milestone membership resolved through `phase_positioned_in_milestone`
+ * and per-phase membership through `task_positioned_in_phase`.
  *
- * Module landing pattern follows lens-view.ts: pure functions take cwd +
- * identifiers, return structured results or { error } records. Subcommand
- * handlers and tool execute() shells in index.ts are thin wrappers that
- * route results to ctx.ui.notify, pi.sendMessage, or AgentToolResult.
+ * Module landing pattern follows lens-view.ts: pure functions take cwd,
+ * return structured results or { error } records. Subcommand handlers and
+ * tool execute() shells in index.ts are thin wrappers that route results to
+ * ctx.ui.notify, pi.sendMessage, or AgentToolResult.
  *
  * Status vocabulary normalization: STATUS_VOCABULARY_DEFAULTS maps each
  * schema's native status enum (issues uses open|resolved|deferred;
@@ -16,23 +21,17 @@
  * `config.status_buckets` over the defaults — users override per-project
  * by editing config.json (FGAP-013 closed).
  *
- * Diagnostic display strings: validateRoadmaps() emits issues whose
+ * Diagnostic display strings: validateRoadmap() emits issues whose
  * `code` field is an opaque slug; the human-readable message is
  * resolved via `diagMessage(cwd, code, fallback)` which checks
  * `config.display_strings[code]` and falls back to embedded English.
  * This is the pi-context divergence: main hardcodes English; pi-context
  * routes the message through config so per-project / per-locale
  * overrides are config-driven.
- *
- * Topological sort + cycle detection (topoSort) is shared utility used by
- * loadRoadmap (over phase_depends_on edges) and loadPlan (over
- * plan_item_depends_on edges) per DEC-0012's edges-only authoring contract.
  */
-import { readBlock } from "./block-api.js";
-import { endpointKey, loadContext } from "./context.js";
-import { availableBlocks } from "./context-sdk.js";
+import { counterEndpoint, endpointKey, loadContext, primaryEndpoint, } from "./context.js";
+import { buildIdIndex, currentState } from "./context-sdk.js";
 import { registerLensValidator } from "./lens-validator.js";
-import { loadLensView } from "./lens-view.js";
 import { resolveStatusVocabulary, STATUS_VOCABULARY_DEFAULTS } from "./status-vocab.js";
 import { topoSort } from "./topo.js";
 export { resolveStatusVocabulary, STATUS_VOCABULARY_DEFAULTS };
@@ -109,8 +108,8 @@ function diagMessage(cwd, code, fallback) {
  *   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
+ * Caller chooses whether cycles are fatal: validateRoadmap surfaces
+ * roadmap_milestone_cycle; loadRoadmap returns the cycles[] alongside a
  * partial order so renderRoadmap can show what it could and what
  * couldn't be ordered.
  */
@@ -118,326 +117,293 @@ function diagMessage(cwd, code, fallback) {
 // consume it without a roadmap-plan <-> context-sdk import cycle. Re-exported
 // here to preserve the existing import surface (barrel + roadmap-plan.test).
 export { topoSort };
-const ROADMAP_STATUS_ENUM = new Set(["draft", "active", "paused", "complete", "archived"]);
+// ── Derived roadmap over milestone_precedes_milestone (FGAP-042) ────────────
+//
+// Roadmap order is the precedes-DAG over milestone-block items: authoring the
+// order = appending milestone_precedes_milestone edges to relations.json. The
+// renderer is pure-textual: per-milestone adjacency lines are sourced from
+// MilestoneRoadmapView.edges, not inferred from `order` consecutive pairs (a
+// fabrication pattern in branching DAGs).
+// The roadmap selects its three domain relations by canonical_id
+// (milestone_precedes_milestone for the precedes DAG, phase_positioned_in_milestone
+// + task_positioned_in_phase for the membership tiers), but the ORIENTATION of
+// each edge — which endpoint is the predecessor / container — is read from the
+// relation's declared `role_direction` (FGAP-113) via primaryEndpoint /
+// counterEndpoint, not hardcoded parent/child picks. The former module constants
+// are inlined at their (few) use sites so no relation-name literal is duplicated
+// as an orientation carrier.
 /**
- * Defensive read of roadmap.json. Returns the parsed array (may be empty)
- * or null when the block is absent / unreadable. Validator and listRoadmaps
- * treat absence as a non-defect (opt-in block).
+ * The declared orientation of a roadmap relation, or the roadmap's `fallback`
+ * when the config does not register a `role_direction` for it (FGAP-113). The
+ * fallbacks preserve the pre-metadata hardcoded orientation exactly:
+ * `milestone_precedes_milestone` → `as_parent` (predecessor at `edge.parent`);
+ * the two `*_positioned_in_*` membership relations → `as_child` (container at
+ * `edge.child`, member at `edge.parent`).
  */
-function readRoadmaps(cwd) {
-    try {
-        const data = readBlock(cwd, "roadmap");
-        return Array.isArray(data.roadmaps) ? data.roadmaps : [];
-    }
-    catch {
-        return null;
-    }
+function roadmapRoleDirection(config, relationType, fallback) {
+    return config?.relation_types?.find((r) => r.canonical_id === relationType)?.role_direction ?? fallback;
 }
+// Error codes flip status to invalid; warning codes to warnings; info codes
+// (roadmap_milestone_isolated) NEVER affect status and are excluded from the
+// lens-validator merge.
+const ROADMAP_ERROR_CODES = new Set([
+    "roadmap_precedes_endpoint_missing",
+    "roadmap_milestone_cycle",
+    "roadmap_milestone_missing",
+]);
+const ROADMAP_WARNING_CODES = new Set(["roadmap_status_unknown_value"]);
 /**
- * Determine whether a milestone is satisfied: when both evidence_block and
- * evidence_query are present, read the block defensively and return true
- * iff at least one item has every evidence_query key matching by ===.
- * Missing block / read error / no query → false (validator surfaces a
- * separate diagnostic where appropriate).
- */
-function evaluateMilestone(cwd, m) {
-    if (!m.evidence_block || !m.evidence_query)
-        return false;
-    let items;
-    try {
-        const data = readBlock(cwd, m.evidence_block);
-        const arrayKey = Object.keys(data).find((k) => Array.isArray(data[k]));
-        if (!arrayKey)
-            return false;
-        items = data[arrayKey];
-    }
-    catch {
-        return false;
-    }
-    const query = m.evidence_query;
-    for (const item of items) {
-        let match = true;
-        for (const [k, v] of Object.entries(query)) {
-            if (item[k] !== v) {
-                match = false;
-                break;
-            }
-        }
-        if (match)
-            return true;
-    }
-    return false;
-}
-/**
- * Load a single roadmap by id. Returns the materialized RoadmapView or a
- * structured { error } when config / block / id is missing.
+ * Load the derived roadmap. Returns the materialized MilestoneRoadmapView or
+ * a structured { error } when no config exists. Zero milestone-block items is
+ * a VALID empty view (not an error) — the roadmap is opt-in by authoring
+ * milestones + edges.
  *
  * 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.
+ *   1. Load context; bail when no <substrate-dir>/config.json.
+ *   2. Index the substrate; milestones = index items whose block is
+ *      "milestone" (stable block scan order).
+ *   3. Scope the milestone_precedes_milestone edges to those whose BOTH
+ *      endpoints are milestone ids; topoSort (preds = parents of a
+ *      milestone's incoming precedes edges) derives order + cycles.
+ *   4. Per milestone: status + phaseCount from currentState(cwd).milestones
+ *      (the config-declared derived rollup; a milestone absent from that list
+ *      reports the rollup pattern's incomplete default "planned" with
+ *      phaseCount 0); phases = parents of phase_positioned_in_milestone edges
+ *      (child = the milestone), each with tasks = parents of
+ *      task_positioned_in_phase edges (child = the phase) and a
+ *      rollupPhaseStatus over the resolved task items; the milestone-level
+ *      rollup aggregates all member phases' task items in one call.
  *
  * The returned `edges` field is the authoritative scoped subset that the
- * renderer consumes for per-phase adjacency lines.
+ * renderer consumes for per-milestone adjacency lines.
  */
-export function loadRoadmap(cwd, roadmapId) {
+export function loadRoadmap(cwd) {
     const ctx = loadContext(cwd);
     if (!ctx.config) {
         return {
             error: "No <substrate-dir>/config.json — run /context init <substrate-dir> first, then declare lenses + install assets.",
         };
     }
-    const roadmaps = readRoadmaps(cwd);
-    if (roadmaps === null) {
-        return {
-            error: "no roadmap.json — install via <substrate-dir>/config.json's installed_blocks then author roadmap.json",
-        };
-    }
-    const roadmap = roadmaps.find((r) => r.id === roadmapId);
-    if (!roadmap) {
-        const known = roadmaps.map((r) => r.id).join(", ") || "(none)";
-        return { error: `Roadmap '${roadmapId}' not found. Known: ${known}` };
+    const index = buildIdIndex(cwd);
+    const milestoneItems = index.items.filter((loc) => loc.block === "milestone");
+    if (milestoneItems.length === 0) {
+        return { milestones: [], order: [], cycles: [], edges: [] };
     }
+    const milestoneIds = new Set(milestoneItems.map((loc) => loc.id));
+    // Precedes DAG: predecessor at the PRIMARY endpoint (as_parent fallback), so a
+    // milestone's preds are the PRIMARY endpoints of edges where the milestone is
+    // the COUNTER (successor) endpoint. The endpoint-membership filter below is
+    // orientation-independent (both endpoints must be milestones either way).
+    const precedesRel = "milestone_precedes_milestone";
+    const precedesDir = roadmapRoleDirection(ctx.config, precedesRel, "as_parent");
+    const edges = ctx.relations.filter((e) => e.relation_type === precedesRel &&
+        milestoneIds.has(endpointKey(e.parent)) &&
+        milestoneIds.has(endpointKey(e.child)));
+    const { order, cycles } = topoSort(milestoneItems, (loc) => loc.id, (loc) => edges
+        .filter((e) => endpointKey(counterEndpoint(e, precedesDir)) === loc.id)
+        .map((e) => endpointKey(primaryEndpoint(e, precedesDir))));
+    const phaseMembershipRel = "phase_positioned_in_milestone";
+    const phaseDir = roadmapRoleDirection(ctx.config, phaseMembershipRel, "as_child");
+    const taskMembershipRel = "task_positioned_in_phase";
+    const taskDir = roadmapRoleDirection(ctx.config, taskMembershipRel, "as_child");
     const vocabulary = resolveStatusVocabulary(cwd);
-    const phases = roadmap.phases.map((phase) => {
-        const lensView = loadLensView(cwd, phase.lens);
-        const items = "error" in lensView ? [] : lensView.items;
-        const status = rollupPhaseStatus(items, vocabulary);
-        const milestone = phase.milestone ? roadmap.milestones?.find((m) => m.id === phase.milestone) : undefined;
-        const milestoneSatisfied = milestone ? evaluateMilestone(cwd, milestone) : undefined;
-        return { phase, lensView, status, milestone, milestoneSatisfied };
+    // One currentState call: the config-declared milestone rollup supplies each
+    // milestone's derived status (reached/planned) + phaseCount.
+    const derivedMilestones = new Map(currentState(cwd).milestones.map((m) => [m.id, m]));
+    const milestones = milestoneItems.map((loc) => {
+        const derived = derivedMilestones.get(loc.id);
+        // Member phases: the milestone is the CONTAINER (primary); its members are
+        // the COUNTER endpoints of phase_positioned_in_milestone edges pointing at it.
+        const memberPhaseIds = ctx.relations
+            .filter((e) => e.relation_type === phaseMembershipRel && endpointKey(primaryEndpoint(e, phaseDir)) === loc.id)
+            .map((e) => endpointKey(counterEndpoint(e, phaseDir)));
+        const allTaskItems = [];
+        const phases = memberPhaseIds.map((phaseId) => {
+            const phaseLoc = index.byRefname.get(phaseId);
+            const taskIds = ctx.relations
+                .filter((e) => e.relation_type === taskMembershipRel && endpointKey(primaryEndpoint(e, taskDir)) === phaseId)
+                .map((e) => endpointKey(counterEndpoint(e, taskDir)));
+            const taskItems = taskIds.map((taskId) => {
+                const taskLoc = index.byRefname.get(taskId);
+                return taskLoc ? { ...taskLoc.item, id: taskId } : { id: taskId };
+            });
+            allTaskItems.push(...taskItems);
+            const tasks = taskItems.map((item) => ({
+                id: item.id,
+                ...(typeof item.status === "string" ? { status: item.status } : {}),
+                ...(typeof item.title === "string" ? { title: item.title } : {}),
+            }));
+            return {
+                id: phaseId,
+                ...(typeof phaseLoc?.item.name === "string" ? { name: phaseLoc.item.name } : {}),
+                ...(typeof phaseLoc?.item.status === "string" ? { status: phaseLoc.item.status } : {}),
+                tasks,
+                rollup: rollupPhaseStatus(taskItems, vocabulary),
+            };
+        });
+        return {
+            id: loc.id,
+            ...(typeof loc.item.name === "string" ? { name: loc.item.name } : {}),
+            status: derived?.status ?? "planned",
+            phaseCount: derived?.phaseCount ?? 0,
+            phases,
+            rollup: rollupPhaseStatus(allTaskItems, vocabulary),
+        };
     });
-    const inRoadmap = new Set(roadmap.phases.map((p) => p.id));
-    const edges = ctx.relations.filter((e) => e.relation_type === "phase_depends_on" &&
-        inRoadmap.has(endpointKey(e.parent)) &&
-        inRoadmap.has(endpointKey(e.child)));
-    const { order, cycles } = topoSort(roadmap.phases, (p) => p.id, (p) => edges.filter((e) => endpointKey(e.child) === p.id).map((e) => endpointKey(e.parent)));
-    return { roadmap, phases, phaseOrder: order, cycles, edges };
+    return { milestones, order, cycles, edges };
 }
 /**
- * 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 function listRoadmaps(cwd) {
-    const roadmaps = readRoadmaps(cwd);
-    if (!roadmaps)
-        return [];
-    return roadmaps.map((r) => ({
-        id: r.id,
-        title: r.title,
-        ...(r.status ? { status: r.status } : {}),
-        phaseCount: r.phases.length,
-    }));
-}
-/**
- * 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.
+ * Validate the derived roadmap. 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) contributes the error-code issues into validateContext's output.
+ *
+ * Codes:
+ *   roadmap_precedes_endpoint_missing (error) — a milestone_precedes_milestone
+ *     edge endpoint that is not a milestone-block item (absent OR wrong kind).
+ *   roadmap_milestone_cycle (error) — a cycle in the precedes graph.
+ *   roadmap_milestone_missing (error) — a phase_positioned_in_milestone edge
+ *     whose child is not a known milestone.
+ *   roadmap_status_unknown_value (warning) — a member phase whose task rollup
+ *     buckets unknown with total > 0 (items lack a recognised status value).
+ *   roadmap_milestone_isolated (info) — a milestone with zero precedes edges
+ *     while at least one precedes edge exists elsewhere. Info NEVER flips
+ *     status: status = invalid iff any error-code issue; warnings iff any
+ *     warning-code issue; else clean.
  *
- * Roadmap.json absent → { status: "clean", issues: [] } (opt-in block;
- * absence is not a defect).
+ * No config → { status: "clean", issues: [] } (nothing to validate).
  */
-export function validateRoadmaps(cwd) {
+export function validateRoadmap(cwd) {
     const issues = [];
     const ctx = loadContext(cwd);
     if (!ctx.config)
         return { status: "clean", issues: [] };
-    const roadmaps = readRoadmaps(cwd);
-    if (!roadmaps || roadmaps.length === 0)
-        return { status: "clean", issues: [] };
-    const lensIds = new Set((ctx.config.lenses ?? []).map((l) => l.id));
-    const blockNames = new Set(availableBlocks(cwd).map((b) => b.name));
-    const vocabulary = resolveStatusVocabulary(cwd);
-    const errorCodes = new Set([
-        "roadmap_lens_missing",
-        "roadmap_phase_dep_missing",
-        "roadmap_phase_cycle",
-        "roadmap_composition_cycle",
-    ]);
-    for (const roadmap of roadmaps) {
-        // roadmap.status — must be in known enum (warning when not).
-        if (roadmap.status !== undefined && !ROADMAP_STATUS_ENUM.has(roadmap.status)) {
-            issues.push({
-                code: "roadmap_status_unknown_value",
-                message: diagMessage(cwd, "roadmap_status_unknown_value", `Roadmap '${roadmap.id}' has unknown status '${roadmap.status}'. Known: ${Array.from(ROADMAP_STATUS_ENUM).join(", ")}`),
-                roadmap_id: roadmap.id,
-            });
-        }
-        const inRoadmap = new Set(roadmap.phases.map((p) => p.id));
-        const milestoneIds = new Set((roadmap.milestones ?? []).map((m) => m.id));
-        // Per-phase checks: lens existence + composition cycle + status rollup
-        // for unknown-status warning + milestone validation (independent of
-        // lens resolution — milestone diagnostics surface even when the lens
-        // itself fails to load).
-        for (const phase of roadmap.phases) {
-            let lensResolved = false;
-            if (!lensIds.has(phase.lens)) {
+    const index = buildIdIndex(cwd);
+    const milestoneIds = new Set(index.items.filter((loc) => loc.block === "milestone").map((loc) => loc.id));
+    // Precedes-edge endpoint integrity — BOTH endpoints must be milestone-block
+    // items (an id resolving to another block is "wrong kind", equally missing).
+    // This is an orientation-independent both-endpoints check, so it needs no
+    // role_direction; it selects the relation by canonical_id only.
+    for (const e of ctx.relations) {
+        if (e.relation_type !== "milestone_precedes_milestone")
+            continue;
+        for (const endpoint of [e.parent, e.child]) {
+            const key = endpointKey(endpoint);
+            if (!milestoneIds.has(key)) {
                 issues.push({
-                    code: "roadmap_lens_missing",
-                    message: diagMessage(cwd, "roadmap_lens_missing", `Phase '${phase.id}' in roadmap '${roadmap.id}' references unknown lens '${phase.lens}'.`),
-                    roadmap_id: roadmap.id,
-                    phase_id: phase.id,
+                    code: "roadmap_precedes_endpoint_missing",
+                    message: diagMessage(cwd, "roadmap_precedes_endpoint_missing", `milestone_precedes_milestone edge {parent:${endpointKey(e.parent)}, child:${endpointKey(e.child)}} references '${key}' which is not a milestone-block item.`),
+                    milestone_id: key,
                 });
             }
-            else {
-                const lensView = loadLensView(cwd, phase.lens);
-                if ("error" in lensView) {
-                    if (lensView.error.includes("composition_cycle_detected")) {
-                        issues.push({
-                            code: "roadmap_composition_cycle",
-                            message: diagMessage(cwd, "roadmap_composition_cycle", `Phase '${phase.id}' in roadmap '${roadmap.id}' resolves to composition lens with cycle: ${lensView.error}`),
-                            roadmap_id: roadmap.id,
-                            phase_id: phase.id,
-                        });
-                    }
-                }
-                else {
-                    lensResolved = true;
-                    const status = rollupPhaseStatus(lensView.items, vocabulary);
-                    if (status.bucket === "unknown" && status.total > 0) {
-                        issues.push({
-                            code: "roadmap_status_unknown_value",
-                            message: diagMessage(cwd, "roadmap_status_unknown_value", `Phase '${phase.id}' in roadmap '${roadmap.id}' rolls up to bucket 'unknown' across ${status.total} item(s) — items lack a recognised status enum value.`),
-                            roadmap_id: roadmap.id,
-                            phase_id: phase.id,
-                        });
-                    }
-                }
-            }
-            // Milestone evidence_block + evidence_query checks — independent
-            // of lens resolution outcome.
-            if (phase.milestone) {
-                const milestone = roadmap.milestones?.find((m) => m.id === phase.milestone);
-                if (milestone) {
-                    if (milestone.evidence_block && !blockNames.has(milestone.evidence_block)) {
-                        issues.push({
-                            code: "roadmap_milestone_evidence_block_missing",
-                            message: diagMessage(cwd, "roadmap_milestone_evidence_block_missing", `Milestone '${milestone.id}' in roadmap '${roadmap.id}' references evidence_block '${milestone.evidence_block}' which is not loaded.`),
-                            roadmap_id: roadmap.id,
-                            phase_id: phase.id,
-                        });
-                    }
-                    if (milestone.evidence_query !== undefined) {
-                        const q = milestone.evidence_query;
-                        const ok = q !== null &&
-                            typeof q === "object" &&
-                            !Array.isArray(q) &&
-                            Object.values(q).every((v) => v === null || ["string", "number", "boolean"].includes(typeof v));
-                        if (!ok) {
-                            issues.push({
-                                code: "roadmap_milestone_query_invalid",
-                                message: diagMessage(cwd, "roadmap_milestone_query_invalid", `Milestone '${milestone.id}' in roadmap '${roadmap.id}' has invalid evidence_query — expected plain object with primitive values only.`),
-                                roadmap_id: roadmap.id,
-                                phase_id: phase.id,
-                            });
-                        }
-                    }
-                }
-            }
-            void lensResolved;
         }
-        // Dangling phase_depends_on edges — both endpoints must be in this roadmap
-        // when at least one endpoint is. (A phase_depends_on edge whose neither
-        // endpoint matches any roadmap phase is silently skipped — it may belong
-        // to a different roadmap.)
-        for (const e of ctx.relations) {
-            if (e.relation_type !== "phase_depends_on")
-                continue;
-            const pKey = endpointKey(e.parent);
-            const cKey = endpointKey(e.child);
-            const parentIn = inRoadmap.has(pKey);
-            const childIn = inRoadmap.has(cKey);
-            if (parentIn !== childIn) {
-                const dangling = parentIn ? cKey : pKey;
-                issues.push({
-                    code: "roadmap_phase_dep_missing",
-                    message: diagMessage(cwd, "roadmap_phase_dep_missing", `phase_depends_on edge {parent:${pKey}, child:${cKey}} in roadmap '${roadmap.id}' references phase '${dangling}' that is not declared in this roadmap.`),
-                    roadmap_id: roadmap.id,
-                    phase_id: dangling,
-                });
-            }
+    }
+    // Phase-membership integrity — a phase_positioned_in_milestone edge's CONTAINER
+    // (the milestone, at the relation's PRIMARY endpoint) must be a known milestone.
+    const phaseMembershipRel = "phase_positioned_in_milestone";
+    const phaseDir = roadmapRoleDirection(ctx.config, phaseMembershipRel, "as_child");
+    for (const e of ctx.relations) {
+        if (e.relation_type !== phaseMembershipRel)
+            continue;
+        const milestoneKey = endpointKey(primaryEndpoint(e, phaseDir));
+        if (!milestoneIds.has(milestoneKey)) {
+            issues.push({
+                code: "roadmap_milestone_missing",
+                message: diagMessage(cwd, "roadmap_milestone_missing", `phase_positioned_in_milestone edge {parent:${endpointKey(e.parent)}, child:${endpointKey(e.child)}} references milestone '${milestoneKey}' that is not declared in the milestone block.`),
+                milestone_id: milestoneKey,
+                phase_id: endpointKey(counterEndpoint(e, phaseDir)),
+            });
         }
-        // Phase cycles — re-run topoSort over the in-roadmap edge subset.
-        const scopedEdges = ctx.relations.filter((e) => e.relation_type === "phase_depends_on" &&
-            inRoadmap.has(endpointKey(e.parent)) &&
-            inRoadmap.has(endpointKey(e.child)));
-        const { cycles } = topoSort(roadmap.phases, (p) => p.id, (p) => scopedEdges.filter((e) => endpointKey(e.child) === p.id).map((e) => endpointKey(e.parent)));
-        for (const cycle of cycles) {
+    }
+    // Derived-view checks (cycles + per-phase rollup + isolation) read the same
+    // derivation the load path produces.
+    const view = loadRoadmap(cwd);
+    if (!("error" in view)) {
+        for (const cycle of view.cycles) {
             issues.push({
-                code: "roadmap_phase_cycle",
-                message: diagMessage(cwd, "roadmap_phase_cycle", `Phase cycle in roadmap '${roadmap.id}': ${cycle.join(" → ")}`),
-                roadmap_id: roadmap.id,
+                code: "roadmap_milestone_cycle",
+                message: diagMessage(cwd, "roadmap_milestone_cycle", `Milestone cycle in milestone_precedes_milestone edges: ${cycle.join(" → ")}`),
                 cycle,
             });
         }
-        // milestoneIds is referenced for symmetry with future expansion; mark
-        // usage to satisfy noUnusedLocals without inserting noise downstream.
-        void milestoneIds;
+        for (const m of view.milestones) {
+            for (const p of m.phases) {
+                if (p.rollup.bucket === "unknown" && p.rollup.total > 0) {
+                    issues.push({
+                        code: "roadmap_status_unknown_value",
+                        message: diagMessage(cwd, "roadmap_status_unknown_value", `Phase '${p.id}' in milestone '${m.id}' rolls up to bucket 'unknown' across ${p.rollup.total} item(s) — items lack a recognised status enum value.`),
+                        milestone_id: m.id,
+                        phase_id: p.id,
+                    });
+                }
+            }
+        }
+        if (view.edges.length > 0) {
+            const connected = new Set();
+            for (const e of view.edges) {
+                connected.add(endpointKey(e.parent));
+                connected.add(endpointKey(e.child));
+            }
+            for (const m of view.milestones) {
+                if (!connected.has(m.id)) {
+                    issues.push({
+                        code: "roadmap_milestone_isolated",
+                        message: diagMessage(cwd, "roadmap_milestone_isolated", `Milestone '${m.id}' participates in no milestone_precedes_milestone edge while other milestones are ordered.`),
+                        milestone_id: m.id,
+                    });
+                }
+            }
+        }
     }
+    // Info codes are excluded from status: invalid iff any error-code issue;
+    // warnings iff any warning-code issue; else clean.
     let status = "clean";
-    for (const i of issues) {
-        if (errorCodes.has(i.code)) {
-            status = "invalid";
-            break;
-        }
+    if (issues.some((i) => ROADMAP_ERROR_CODES.has(i.code)))
+        status = "invalid";
+    else if (issues.some((i) => ROADMAP_WARNING_CODES.has(i.code)))
         status = "warnings";
-    }
     return { status, issues };
 }
 /**
- * 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.
+ * Render a loaded MilestoneRoadmapView as pure-textual markdown — NO mermaid,
+ * NO diagrams, NO graph syntax. Per-milestone **Preceded by:** adjacency lines
+ * are sourced strictly from view.edges (sorted alphabetically; "—" when the
+ * milestone has no incoming precedes edges). Cycle-participating milestones
+ * are surfaced under a separate "**Unordered (cycle participants):**" heading
+ * and a "**Cycles detected:**" line. The renderer never infers adjacency from
+ * `order` consecutive pairs (that pattern fabricates sibling edges in
+ * branching DAGs).
  */
-export function renderRoadmap(view, naming) {
+export function renderRoadmap(view) {
     const lines = [];
-    const r = view.roadmap;
-    lines.push(`# Roadmap: ${r.title} (${r.id})`);
+    const byId = new Map(view.milestones.map((m) => [m.id, m]));
+    lines.push("# Roadmap (derived)");
+    lines.push("");
+    lines.push(`**Milestones:** ${view.milestones.length}  |  **Ordered:** ${view.order.length}  |  **Cycles:** ${view.cycles.length}`);
     lines.push("");
-    lines.push(`**Status:** ${r.status ?? "(unspecified)"}`);
-    lines.push(`**Phases:** ${r.phases.length}  |  **Ordered:** ${view.phaseOrder.length}  |  **Cycles:** ${view.cycles.length}`);
+    lines.push("## Milestone order");
     lines.push("");
-    if (r.description) {
-        lines.push(r.description);
+    if (view.milestones.length === 0) {
+        lines.push("(no milestones)");
         lines.push("");
     }
-    lines.push("## Phase order");
-    lines.push("");
-    const phaseById = new Map(r.phases.map((p) => [p.id, p]));
-    if (view.phaseOrder.length === 0) {
+    else if (view.order.length === 0) {
         lines.push("(no acyclic ordering possible — see cycles below)");
         lines.push("");
     }
     else {
-        view.phaseOrder.forEach((id, idx) => {
-            const p = phaseById.get(id);
-            lines.push(`${idx + 1}. ${id} — ${p?.name ?? "(unknown)"}`);
+        view.order.forEach((id, idx) => {
+            const m = byId.get(id);
+            lines.push(`${idx + 1}. ${id} — ${m?.name ?? "(unnamed)"} [${m?.status ?? "planned"}]`);
         });
         lines.push("");
     }
-    const orderedSet = new Set(view.phaseOrder);
-    const cycleOnly = r.phases.filter((p) => !orderedSet.has(p.id));
+    const orderedSet = new Set(view.order);
+    const cycleOnly = view.milestones.filter((m) => !orderedSet.has(m.id));
     if (cycleOnly.length > 0) {
-        lines.push("**Unordered (cycle-participating):**");
-        for (const p of cycleOnly) {
-            lines.push(`- ${p.id} — ${p.name}`);
+        lines.push("**Unordered (cycle participants):**");
+        for (const m of cycleOnly) {
+            lines.push(`- ${m.id} — ${m.name ?? "(unnamed)"}`);
         }
         lines.push("");
     }
@@ -446,98 +412,68 @@ export function renderRoadmap(view, naming) {
         lines.push(`**Cycles detected:** ${rendered}`);
         lines.push("");
     }
-    lines.push("## Phases");
+    if (view.milestones.length === 0) {
+        return lines.join("\n").replace(/\n+$/, "\n");
+    }
+    lines.push("## Milestones");
     lines.push("");
-    // Render in phaseOrder first, then any cycle-only phases (deduped, input order).
-    const phaseViewById = new Map(view.phases.map((pv) => [pv.phase.id, pv]));
-    const renderOrder = [];
-    for (const id of view.phaseOrder)
-        renderOrder.push(id);
-    for (const p of cycleOnly)
-        renderOrder.push(p.id);
+    // Render in topo order first, then any cycle-only milestones (input order).
+    const renderOrder = [...view.order, ...cycleOnly.map((m) => m.id)];
     for (const id of renderOrder) {
-        const pv = phaseViewById.get(id);
-        if (!pv)
+        const m = byId.get(id);
+        if (!m)
             continue;
-        const p = pv.phase;
-        lines.push(`### ${p.name} (${p.id}) [${pv.status.bucket}]`);
+        lines.push(`### ${m.name ?? "(unnamed)"} (${m.id}) [${m.status}]`);
         lines.push("");
-        const lensTargetLabel = (() => {
-            if (!("error" in pv.lensView)) {
-                const lens = pv.lensView.lens;
-                if (lens.kind === "composition") {
-                    return `${(lens.targets ?? []).map((t) => naming?.[t] ?? t).join(", ")} (composition)`;
-                }
-                if (lens.target)
-                    return naming?.[lens.target] ?? lens.target;
-            }
-            return p.lens;
-        })();
-        lines.push(`**Lens:** ${p.lens}${lensTargetLabel !== p.lens ? ` (${lensTargetLabel})` : ""}`);
         const incoming = view.edges
-            .filter((e) => endpointKey(e.child) === p.id)
+            .filter((e) => endpointKey(e.child) === m.id)
             .map((e) => endpointKey(e.parent))
             .sort();
-        lines.push(`**Depends on:** ${incoming.length > 0 ? incoming.join(", ") : "—"}`);
-        const c = pv.status.counts;
-        lines.push(`**Counts:** complete=${c.complete} in_progress=${c.in_progress} blocked=${c.blocked} todo=${c.todo} unknown=${c.unknown} (total=${pv.status.total})`);
+        lines.push(`**Preceded by:** ${incoming.length > 0 ? incoming.join(", ") : "—"}`);
+        const c = m.rollup.counts;
+        lines.push(`**Rollup:** complete=${c.complete} in_progress=${c.in_progress} blocked=${c.blocked} todo=${c.todo} unknown=${c.unknown} (total=${m.rollup.total})`);
         lines.push("");
-        if ("error" in pv.lensView) {
-            lines.push(`**Lens error:** ${pv.lensView.error}`);
+        for (const p of m.phases) {
+            lines.push(`#### ${p.name ?? "(unnamed)"} (${p.id}) [${p.status ?? "(unspecified)"}]`);
             lines.push("");
-        }
-        else {
-            const items = pv.lensView.items;
-            if (items.length > 0) {
-                lines.push(`| Item     | Status   | Title    |`);
-                lines.push(`|----------|----------|----------|`);
-                for (const item of items) {
-                    const status = typeof item.status === "string" ? item.status : "";
-                    const titleStr = typeof item.title === "string" ? item.title : "";
-                    lines.push(`| ${item.id} | ${status} | ${titleStr} |`);
+            if (p.tasks.length === 0) {
+                lines.push("(no tasks)");
+                lines.push("");
+            }
+            else {
+                lines.push("| Task | Status |");
+                lines.push("|------|--------|");
+                for (const t of p.tasks) {
+                    lines.push(`| ${t.title ?? t.id} | ${t.status ?? ""} |`);
                 }
                 lines.push("");
             }
         }
-        if (pv.milestone) {
-            const verdict = pv.milestoneSatisfied ? "satisfied" : "not yet satisfied";
-            lines.push(`**Milestone:** ${pv.milestone.id} — ${pv.milestone.name} — ${verdict}`);
-            lines.push("");
-        }
-        if (p.exit_criteria && p.exit_criteria.length > 0) {
-            lines.push("**Exit criteria:**");
-            for (const crit of p.exit_criteria)
-                lines.push(`- ${crit}`);
-            lines.push("");
-        }
     }
     return lines.join("\n").replace(/\n+$/, "\n");
 }
-// ── Lens-validator dispatch registration (Divergence 3) ─────────────────────
+// ── Lens-validator dispatch registration ─────────────────────────────────────
 //
 // Module-init side-effect: validateContext in context-sdk.ts iterates all
 // registered lens-validators and merges their issues into the project-
 // validation result. roadmap-plan registers itself here so import of this
 // module from index.ts wires the dispatch automatically — no hardcoded
-// import in context-sdk.ts.
+// import in context-sdk.ts. Only error-code issues contribute to the merge:
+// warnings and info stay on the context-roadmap-validate surface.
 registerLensValidator({
     name: "roadmap",
     validate: (cwd) => {
-        const result = validateRoadmaps(cwd);
-        const errorCodes = new Set([
-            "roadmap_lens_missing",
-            "roadmap_phase_dep_missing",
-            "roadmap_phase_cycle",
-            "roadmap_composition_cycle",
-        ]);
-        const issues = result.issues.map((ri) => ({
+        const result = validateRoadmap(cwd);
+        const issues = result.issues
+            .filter((ri) => ROADMAP_ERROR_CODES.has(ri.code))
+            .map((ri) => ({
             code: ri.code,
-            severity: errorCodes.has(ri.code) ? "error" : "warning",
+            severity: "error",
             message: ri.message,
-            block: ri.roadmap_id ? `roadmap.${ri.roadmap_id}` : "roadmap",
+            block: "milestone",
             ...(ri.phase_id ? { field: `phase.${ri.phase_id}` } : {}),
         }));
-        const status = issues.length === 0 ? "clean" : issues.some((i) => i.severity === "error") ? "invalid" : "warnings";
+        const status = issues.length === 0 ? "clean" : "invalid";
         return { status, issues };
     },
 });