@davidorex/pi-context 0.31.0 → 0.32.0

package/dist/roadmap-plan.d.ts

@@ -1,5 +1,35 @@
+/**
+ * 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,
+ * 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;
+ * decisions uses open|enacted|superseded; tasks uses
+ * todo|in_progress|completed; etc.) to a normalized StatusBucket that
+ * cross-block aggregation can compare against. Per the pi-context
+ * divergence from main, the active vocabulary is resolved via
+ * `resolveStatusVocabulary(cwd)` which merges
+ * `config.status_buckets` over the defaults — users override per-project
+ * by editing config.json (FGAP-013 closed).
+ *
+ * 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.
+ */
 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";
@@ -43,144 +73,136 @@ export declare function rollupPhaseStatus(items: ItemRecord[], vocabulary?: Reco
  *   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.
  */
 export { topoSort };
 /**
- * Phase entry as authored in roadmap.json. NO depends_on field — ordering
- * lives in relations.json per DEC-0012.
+ * One task row in a phase's membership — the parent of a
+ * task_positioned_in_phase edge, resolved against the substrate index.
+ * `title` is populated only when the resolved item carries a string `title`
+ * field (the stock tasks schema declares `description`, not `title`, so it
+ * stays undefined there and renderers fall back to the id).
  */
-export interface PhaseSpec {
+export interface TaskRow {
     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>;
+    status?: string;
+    title?: string;
 }
 /**
- * Roadmap entry as authored in roadmap.json's roadmaps[] array.
+ * One member phase of a milestone: the parent of a
+ * phase_positioned_in_milestone edge, with its tasks (parents of
+ * task_positioned_in_phase edges targeting it) and a status rollup over those
+ * task items.
  */
-export interface RoadmapSpec {
+export interface PhaseRollupView {
     id: string;
-    title: string;
-    description?: string;
+    name?: string;
     status?: string;
-    phases: PhaseSpec[];
-    milestones?: MilestoneSpec[];
+    tasks: TaskRow[];
+    rollup: PhaseStatus;
 }
 /**
- * Per-phase loaded view: phase spec + its lens-view (or error) + status
- * rollup over the lens's items + optional milestone resolution.
+ * One milestone in the derived roadmap. `status` + `phaseCount` come from
+ * currentState's config-declared milestone rollup (reached/planned); `rollup`
+ * aggregates ALL member phases' task items in a single rollupPhaseStatus pass.
  */
-export interface PhaseView {
-    phase: PhaseSpec;
-    lensView: LoadedLensView | {
-        error: string;
-    };
-    status: PhaseStatus;
-    milestone?: MilestoneSpec;
-    milestoneSatisfied?: boolean;
+export interface MilestoneView {
+    id: string;
+    name?: string;
+    status: string;
+    phaseCount: number;
+    phases: PhaseRollupView[];
+    rollup: PhaseStatus;
 }
 /**
- * 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).
+ * The materialized derived roadmap. `milestones` carries MilestoneView entries
+ * in stable block scan order. `order` is the topo order over the
+ * milestone_precedes_milestone edges scoped to milestone-block items — partial
+ * when cycles are present (cycle-participating milestones are absent from
+ * `order` and surfaced separately in `cycles`). `edges` is the authoritative
+ * scoped subset of authored precedes edges and is the renderer's sole source
+ * for per-milestone adjacency lines (the renderer never infers adjacency from
+ * `order` consecutive pairs — that pattern fabricates sibling edges in
+ * branching DAGs and is forbidden).
  */
-export interface RoadmapView {
-    roadmap: RoadmapSpec;
-    phases: PhaseView[];
-    phaseOrder: string[];
+export interface MilestoneRoadmapView {
+    milestones: MilestoneView[];
+    order: 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";
+    code: "roadmap_precedes_endpoint_missing" | "roadmap_milestone_cycle" | "roadmap_milestone_missing" | "roadmap_status_unknown_value" | "roadmap_milestone_isolated";
     message: string;
-    roadmap_id?: string;
+    milestone_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.
+ * 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 declare function loadRoadmap(cwd: string, roadmapId: string): RoadmapView | {
+export declare function loadRoadmap(cwd: string): MilestoneRoadmapView | {
     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.
+ * 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.
  *
- * Roadmap.json absent → { status: "clean", issues: [] } (opt-in block;
- * absence is not a defect).
+ * 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.
+ *
+ * No config → { status: "clean", issues: [] } (nothing to validate).
  */
-export declare function validateRoadmaps(cwd: string): {
+export declare function validateRoadmap(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.
+ * 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 declare function renderRoadmap(view: RoadmapView, naming: Record<string, string> | undefined): string;
+export declare function renderRoadmap(view: MilestoneRoadmapView): string;
 //# sourceMappingURL=roadmap-plan.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"roadmap-plan.d.ts","sourceRoot":"","sources":["../src/roadmap-plan.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"roadmap-plan.d.ts","sourceRoot":"","sources":["../src/roadmap-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAGN,KAAK,IAAI,EAET,KAAK,UAAU,EAGf,KAAK,YAAY,EACjB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AACxF,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAQrC,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,CAAC;AAE/D,MAAM,WAAW,WAAW;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACrC,KAAK,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,WAAW,CA0B7G;AAaD;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAE,QAAQ,EAAE,CAAC;AAmCpB;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,oBAAoB;IACpC,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;IACnB,KAAK,EAAE,IAAI,EAAE,CAAC;CACd;AAED,MAAM,WAAW,sBAAsB;IACtC,IAAI,EACD,mCAAmC,GACnC,yBAAyB,GACzB,2BAA2B,GAC3B,8BAA8B,GAC9B,4BAA4B,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAYD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CA0FjF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG;IAC7C,MAAM,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;IACzC,MAAM,EAAE,sBAAsB,EAAE,CAAC;CACjC,CAgHA;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAuFhE"}