@davidorex/pi-context 0.31.0 → 0.32.0

package/dist/ops-registry.js

@@ -19,9 +19,9 @@
 import path from "node:path";
 import { Type } from "typebox";
 import { appendToBlock, appendToNestedArray, nextId, readBlock, readBlockDir, removeFromBlock, removeFromNestedArray, updateItemInBlock, updateNestedArrayItem, upsertItemInBlock, writeBlock, } from "./block-api.js";
-import { adoptConception, amendConfigEntry, loadConfig, loadContext } from "./context.js";
+import { adoptConception, amendConfigEntry, loadConfig } from "./context.js";
 import { BootstrapNotFoundError, schemaPath, tryResolveContextDir } from "./context-dir.js";
-import { appendRelationByRef, appendRelationsByRef, completeTask, contextState, currentState, deriveBootstrapState, filterBlockItems, joinBlocks, readBlockItem, readBlockPage, removeRelationByRef, replaceRelationByRef, resolveItemById, resolveItemsByIds, validateContext, } from "./context-sdk.js";
+import { appendRelationByRef, appendRelationsByRef, completeTask, contextState, currentState, deriveBootstrapState, endpointKey, filterBlockItems, joinBlocks, readBlockItem, readBlockPage, removeRelationByRef, replaceRelationByRef, resolveItemById, resolveItemsByIds, validateContext, } from "./context-sdk.js";
 import { gatherExecutionContext } from "./execution-context.js";
 // initProject + the switch/list/archive helpers are defined in index.ts (shared
 // with the /context command handlers + the context-* tools). This is a cyclic
@@ -34,7 +34,7 @@ import { edgesForLensByName, findReferencesInRepo, loadLensView, validateContext
 import { promoteItem } from "./promote-item.js";
 import { addressInto, pageArray, renderReadText, structureForRead } from "./read-element.js";
 import { renameCanonicalId } from "./rename-canonical-id.js";
-import { listRoadmaps, loadRoadmap, renderRoadmap, validateRoadmaps } from "./roadmap-plan.js";
+import { loadRoadmap, renderRoadmap, validateRoadmap } from "./roadmap-plan.js";
 import { samplesCatalog } from "./samples-catalog.js";
 import { readSchema, writeSchemaChecked } from "./schema-write.js";
 import { truncateHead } from "./truncate.js";
@@ -115,31 +115,6 @@ export function boundedJsonOutput(r) {
     const { over, totalBytes } = overReadCap(s);
     return over ? { data: null, truncated: true, totalBytes, complete: false } : r.json;
 }
-// ── serializeRoadmapView ────────────────────────────────────────────────────
-// Strip non-serializable fields (suggestionTemplate fn, grouped Map) from the
-// embedded LoadedLensView records before tool serialization. Relocated verbatim
-// from the extension factory; consumed by the context-roadmap-load op.
-const serializeRoadmapView = (view) => ({
-    roadmap: view.roadmap,
-    phases: view.phases.map((pv) => ({
-        phase: pv.phase,
-        lensView: "error" in pv.lensView
-            ? pv.lensView
-            : {
-                lens: pv.lensView.lens,
-                items: pv.lensView.items,
-                edges: pv.lensView.edges,
-                grouped: Object.fromEntries(pv.lensView.grouped),
-                uncategorized: pv.lensView.uncategorized,
-            },
-        status: pv.status,
-        ...(pv.milestone ? { milestone: pv.milestone } : {}),
-        ...(pv.milestoneSatisfied !== undefined ? { milestoneSatisfied: pv.milestoneSatisfied } : {}),
-    })),
-    phaseOrder: view.phaseOrder,
-    cycles: view.cycles,
-    edges: view.edges,
-});
 export const ops = [
     {
         name: "append-block-item",
@@ -211,17 +186,30 @@ export const ops = [
     {
         name: "append-relation",
         label: "Append Relation",
-        description: "Append a closure-table relation (edge: parent, child, relation_type, optional ordinal) to relations.json. " +
-            "Shape is AJV-validated; an exact-duplicate edge (same parent+child+relation_type) is a no-op. Reference " +
-            "integrity (endpoints resolve, relation_type registered, no cycle) is NOT checked here — run context-validate " +
-            "after. Creates relations.json if absent.",
-        promptSnippet: "Create a relation/edge between two items (parent→child under a relation_type)",
+        description: "Append a closure-table relation (edge: relation_type, optional ordinal) to relations.json. Orient the edge with " +
+            "EITHER raw --parent/--child OR the role-typed --primary/--counter (which maps to parent/child via the relation's " +
+            "declared role_direction); the two pairs are mutually exclusive. A bare --parent/--child append of a relation that " +
+            "is BOTH role-bearing and orientation-ambiguous (its source/target kinds overlap) is rejected — re-issue with " +
+            "--primary/--counter. Shape is AJV-validated; an exact-duplicate edge (same parent+child+relation_type) is a no-op. " +
+            "Reference integrity (endpoints resolve, relation_type registered, no cycle) is NOT checked here — run " +
+            "context-validate after. Creates relations.json if absent.",
+        promptSnippet: "Create a relation/edge between two items (raw --parent/--child, or role-typed --primary/--counter mapped via role_direction)",
         examples: [
             `pi-context append-relation --parent VER-001 --child TASK-001 --relation_type verification_verifies_item --writer '{"kind":"human","user":"you@example.com"}' --json`,
         ],
         parameters: Type.Object({
-            parent: Type.String({ description: "Canonical id (or lens bin name) of the parent endpoint" }),
-            child: Type.String({ description: "Canonical id of the child endpoint" }),
+            parent: Type.Optional(Type.String({
+                description: "Parent-endpoint selector (canonical id / <alias>:<refname> / lens bin) — RAW orientation. Mutually exclusive with --primary/--counter.",
+            })),
+            child: Type.Optional(Type.String({
+                description: "Child-endpoint selector — RAW orientation. Mutually exclusive with --primary/--counter.",
+            })),
+            primary: Type.Optional(Type.String({
+                description: "Selector of the endpoint holding the relation's PRIMARY semantic role (ROLE-TYPED orientation; mapped to parent/child via the relation's declared role_direction). Requires --counter; the relation_type must declare role_direction.",
+            })),
+            counter: Type.Optional(Type.String({
+                description: "Selector of the endpoint holding the relation's COUNTER role (ROLE-TYPED orientation). Requires --primary.",
+            })),
             relation_type: Type.String({
                 description: "Registered relation_type canonical_id / hierarchy edge type / lens id",
             }),
@@ -231,26 +219,32 @@ export const ops = [
         surface: "use",
         run(cwd, params, ctx) {
             // Cycle-5 porcelain: STRING selectors (bare refname / <alias>:<refname> /
-            // lens-bin) are resolved to structured EdgeEndpoints and written via the
-            // raw plumbing. The param surface stays string-typed; messaging uses the
-            // raw selectors (params.*), not the resolved structured endpoints. Under
-            // dryRun the byRef fn validates the prospective relations + dedup-checks
-            // without writing (TASK-010 shared preview path).
-            const { appended } = appendRelationByRef(cwd, {
-                parent: params.parent,
-                child: params.child,
+            // lens-bin) are resolved to structured EdgeEndpoints and written via the raw
+            // plumbing. The append accepts EITHER raw --parent/--child OR the role-typed
+            // --primary/--counter form (FGAP-113); messaging renders the RESOLVED stored
+            // orientation (endpointKey of the returned edge), so a role-typed call reports
+            // the parent/child it actually filed. Under dryRun the byRef fn validates the
+            // prospective relations + dedup-checks without writing (TASK-010 shared
+            // preview path).
+            const { appended, edge } = appendRelationByRef(cwd, {
+                ...(params.parent !== undefined ? { parent: params.parent } : {}),
+                ...(params.child !== undefined ? { child: params.child } : {}),
+                ...(params.primary !== undefined ? { primary: params.primary } : {}),
+                ...(params.counter !== undefined ? { counter: params.counter } : {}),
                 relation_type: params.relation_type,
                 ...(params.ordinal !== undefined ? { ordinal: params.ordinal } : {}),
             }, ctx, { dryRun: params.dryRun });
+            const from = endpointKey(edge.parent);
+            const to = endpointKey(edge.child);
             const ordinalNote = params.ordinal !== undefined ? ` (ordinal ${params.ordinal})` : "";
             if (params.dryRun) {
                 return appended
-                    ? `would append relation ${params.parent} -[${params.relation_type}]-> ${params.child}${ordinalNote}`
-                    : `would no-op (duplicate): relation ${params.parent} -[${params.relation_type}]-> ${params.child}`;
+                    ? `would append relation ${from} -[${params.relation_type}]-> ${to}${ordinalNote}`
+                    : `would no-op (duplicate): relation ${from} -[${params.relation_type}]-> ${to}`;
             }
             return appended
-                ? `Appended relation ${params.parent} -[${params.relation_type}]-> ${params.child}${ordinalNote}`
-                : `Relation ${params.parent} -[${params.relation_type}]-> ${params.child} already exists — no-op`;
+                ? `Appended relation ${from} -[${params.relation_type}]-> ${to}${ordinalNote}`
+                : `Relation ${from} -[${params.relation_type}]-> ${to} already exists — no-op`;
         },
     },
     {
@@ -296,7 +290,9 @@ export const ops = [
         description: "Atomically replace one closure-table relation with another in a SINGLE write (no half-state: the old edge and " +
             "the new edge never coexist on disk). The old edge is matched on the (parent, child, relation_type) dedup identity; " +
             "the new edge is written with its optional ordinal. If the old edge is absent the call is effectively an append of " +
-            "the new edge. Reference integrity is NOT checked here — run context-validate after.",
+            "the new edge. This op takes RAW parent/child (old + new) and BYPASSES the write-time orientation gate that " +
+            "append-relation applies — it writes the endpoints verbatim, so it is the affordance for re-orienting an existing " +
+            "edge; reference integrity is NOT checked here — run context-validate after.",
         promptSnippet: "Atomically swap one relation/edge for another in a single write",
         examples: [
             `pi-context replace-relation --old_parent TASK-001 --old_child DEC-0001 --old_relation_type task_informed_by_decision --parent TASK-001 --child DEC-0002 --relation_type task_informed_by_decision --writer '{"kind":"human","user":"you@example.com"}' --json`,
@@ -355,17 +351,20 @@ export const ops = [
     {
         name: "append-relations",
         label: "Append Relations (bulk)",
-        description: "Append MANY closure-table relations to relations.json in a single write. Each edge is an object " +
-            "{ parent, child, relation_type, ordinal? }. Per-(parent, child, relation_type) duplicates are skipped (against " +
-            "on-disk edges AND earlier edges in the same batch). Returns appended/skipped counts. Reference integrity is NOT " +
-            "checked here — run context-validate after. Creates relations.json if absent.",
-        promptSnippet: "Create many relations/edges between items in one write",
+        description: "Append MANY closure-table relations to relations.json in a single write. Each edge is an object with " +
+            "{ relation_type, ordinal? } plus EITHER a raw { parent, child } pair OR the role-typed { primary, counter } pair " +
+            "(mapped to parent/child via the relation's declared role_direction); the two pairs are mutually exclusive per edge, " +
+            "and a bare { parent, child } for an orientation-ambiguous role-bearing relation rejects the whole batch before any " +
+            "write. Per-(parent, child, relation_type) duplicates are skipped (against on-disk edges AND earlier edges in the " +
+            "same batch). Returns appended/skipped counts. Reference integrity is NOT checked here — run context-validate " +
+            "after. Creates relations.json if absent.",
+        promptSnippet: "Create many relations/edges between items in one write (raw or role-typed per edge)",
         examples: [
             `pi-context append-relations --edges '[{"parent":"FEAT-008","child":"TASK-042","relation_type":"feature_decomposed_into_task"}]' --writer '{"kind":"human","user":"you@example.com"}' --json`,
         ],
         parameters: Type.Object({
             edges: Type.Unknown({
-                description: "JSON array of { parent, child, relation_type, ordinal? } selector objects (parent/child are id/lens-bin selectors)",
+                description: "JSON array of edge objects. Each edge is { relation_type, ordinal? } plus EITHER a raw { parent, child } pair OR the role-typed { primary, counter } pair (mapped to parent/child via the relation's declared role_direction); the two orientation pairs are mutually exclusive per edge. Selectors are id / <alias>:<refname> / lens-bin.",
             }),
             dryRun: Type.Optional(Type.Boolean({ description: "Preview without writing relations.json" })),
         }),
@@ -382,12 +381,16 @@ export const ops = [
                 }
             }
             if (!Array.isArray(edges)) {
-                throw new Error(`edges parameter must be a JSON array of { parent, child, relation_type, ordinal? } objects`);
+                throw new Error(`edges parameter must be a JSON array of relation edge objects`);
             }
             // Under dryRun the byRef fn replays the on-disk + in-batch dedup and
             // validates the prospective relations without writing (TASK-010 shared
-            // preview path).
-            const { appended, skipped } = appendRelationsByRef(cwd, edges, ctx, { dryRun: params.dryRun });
+            // preview path). Each edge accepts raw {parent,child} or role-typed
+            // {primary,counter} (FGAP-113); orientation + the ambiguous-bare-append
+            // reject are applied inside appendRelationsByRef before any write.
+            const { appended, skipped } = appendRelationsByRef(cwd, edges, ctx, {
+                dryRun: params.dryRun,
+            });
             return params.dryRun
                 ? `would append ${appended}, skip ${skipped} (duplicates)`
                 : `appended ${appended}, skipped ${skipped} (duplicates)`;
@@ -680,7 +683,7 @@ export const ops = [
     {
         name: "context-check-status",
         label: "Context Check Status",
-        description: "Read-only installed-vs-catalog schema drift report — per installed schema the drift state, the baseline and catalog versions, and for behind schemas (catalog-ahead / both-diverged) the version delta (baseline -> catalog) or the content-only basis when the version string is unchanged. The front of the check-status -> update --dryRun -> update sequence; writes nothing.",
+        description: "Read-only installed-vs-catalog schema drift report — per installed schema the drift state, the baseline and catalog versions, and for behind schemas (catalog-ahead / both-diverged) the version delta (baseline -> catalog) or the content-only basis when the version string is unchanged. The front of the check-status -> update --dryRun -> update sequence. Like every substrate-lifecycle ceremony it seeds the catalog's config migration declarations into migrations.json (idempotent) before its first config read, so a version-lagging legacy substrate is diagnosable; beyond that seed it writes nothing.",
         promptSnippet: "Report installed-vs-catalog schema drift + the version gap for behind schemas (read-only)",
         examples: [`pi-context context-check-status --json`],
         parameters: Type.Object({}),
@@ -868,8 +871,8 @@ export const ops = [
     {
         name: "context-current-state",
         label: "Context Current State",
-        description: "Derive 'where are we + what's next' purely from the substrate — focus, in-flight tasks, ranked atomic-next actions (open framework-gaps then unblocked planned tasks), and blocked tasks. No writes; nothing hand-stored.",
-        promptSnippet: "Derive current project state — focus, in-flight, next actions, blocked",
+        description: "Derive 'where are we + what's next' purely from the substrate — focus, in-flight items, ranked atomic-next actions, blocked items, and milestone rollups. Every facet derives from the config-declared `state_derivation` registry: which block kinds + status bucket count as in-flight, the focus fallback kind + bucket, the ordered cross-kind next-actions push order with per-entry ranking (a named field + ordered value list, e.g. gap priority P0..P3) or topo ordering over the blocking-relation graph, the relation_types whose edges contribute blockers (the stock set being `task_depends_on_task` dependencies + `task_gated_by_item` gates), the membership rollups (e.g. milestones over `phase_positioned_in_milestone`) with their complete/incomplete status strings, and the next-actions head-size cap. A blocked item's dependency/gate target that has not reached the complete bucket is reported in blockedBy and held out of nextActions; a target reaching its complete status releases it. A substrate whose config declares no `state_derivation` reports focus 'state-derivation not configured' with empty arrays. No writes; nothing hand-stored.",
+        promptSnippet: "Derive current project state from the config-declared state_derivation registry — focus, in-flight, ranked next actions, blocked, milestone rollups",
         examples: [`pi-context context-current-state --json`],
         parameters: Type.Object({}),
         surface: "use",
@@ -1062,7 +1065,7 @@ export const ops = [
     {
         name: "resolve-blocked",
         label: "Resolve Blocked",
-        description: "Commit the resolution of a blocked schema surfaced by update. Run AFTER fixing the block's items (or widening the local schema): when the block file carries git-style failure markers (written by update), strips the full-line marker sentinels first, then re-validates the corrected block against the pinned target schema from the pending-blocked record; on pass registers the migration chain, writes the target schema, advances the merge base to the target (so a subsequent update converges instead of re-blocking), and clears the pending entry; on fail reports the remaining per-item failures and writes nothing.",
+        description: "Commit the resolution of a blocked schema surfaced by update. Run AFTER fixing the block's items (or widening the local schema): when the block file carries git-style failure markers (written by update), strips the full-line marker sentinels first, then re-validates the corrected block against the pinned target schema from the pending-blocked record; on pass registers the migration chain, writes the target schema, advances the merge base to the target (so a subsequent update converges instead of re-blocking), and clears the pending entry; on fail reports the remaining per-item failures and writes nothing. The commit is all-or-nothing: a throw partway through it restores every touched file byte-exact — migrations.json, the installed schema, the block file, config.json, and the pending record — and reports the failure, never a partial commit. On a substrate whose config carries no substrate_id, resolve-blocked establishes the identity at entry (mints, persists, registers) before the commit's stamping write and reports it under substrateIdEstablished.",
         promptSnippet: "Commit a blocked schema's resolution: strip any git-style failure markers, re-validate the corrected block against the pinned target, then write the target schema + advance the base + clear the pending record (run after fixing the items update reported blocked)",
         examples: [`pi-context resolve-blocked --schemaName tasks --yes --json`],
         parameters: Type.Object({
@@ -1079,7 +1082,7 @@ export const ops = [
     {
         name: "write-schema-migration",
         label: "Write Schema Migration",
-        description: "Declare a schema version-bump migration into substrate (migrations.json). operation 'create' appends a new declaration; 'replace' overwrites an existing declaration matched by (schemaName, fromVersion); 'remove' drops a declaration. kind='identity' asserts the bump is shape-compatible (no data transform); kind='declarative-transform' carries a TransformSpec of rename/set/delete/coerce operations on dotted JSON paths. The loaded MigrationRegistry resolves the recorded edge at next read/write so block items declaring an older schema_version walk forward without process restart. Requires user authorization via interactive confirmation at the pi-dispatch auth-gate; on confirm, the verified terminal-operator identity is stamped as writer.",
+        description: "Declare a schema version-bump migration into substrate (migrations.json). operation 'create' appends a new declaration; 'replace' overwrites an existing declaration matched by (schemaName, fromVersion); 'remove' drops a declaration. kind='identity' asserts the bump is shape-compatible (no data transform); kind='declarative-transform' carries a TransformSpec of rename/set/delete/coerce/map_each operations on dotted JSON paths; map_each addresses an array — table mode maps each string element through a lookup (unmatched elements become {relation_type, item_endpoint} with parent/child fallback), set-on-each mode sets a field on every object element. The loaded MigrationRegistry resolves the recorded edge at next read/write so block items declaring an older schema_version walk forward without process restart. Requires user authorization via interactive confirmation at the pi-dispatch auth-gate; on confirm, the verified terminal-operator identity is stamped as writer.",
         promptSnippet: "Declare a schema version-bump migration (identity or declarative-transform) into migrations.json",
         examples: [
             `pi-context write-schema-migration --operation create --schemaName tasks --fromVersion 1.0.0 --toVersion 1.1.0 --kind identity --writer '{"kind":"human","user":"you@example.com"}' --json`,
@@ -1156,7 +1159,7 @@ export const ops = [
     {
         name: "context-install",
         label: "Context Install",
-        description: "Install (materialize) the schemas and starter blocks declared in config.json's installed_schemas / installed_blocks from the package samples catalog. Default skip-if-exists (installed files never overwritten without --update); populated block data is always preserved (even with --update); empty or absent blocks get the catalog starter. Records the install baseline (config.installed_from: catalog source + per-schema fingerprint) for installed-vs-catalog drift detection (schemas only). A re-install on an unchanged substrate is idempotent.",
+        description: "Install (materialize) the schemas and starter blocks declared in config.json's installed_schemas / installed_blocks from the package samples catalog. Default skip-if-exists (installed files never overwritten without --update); populated block data is always preserved (even with --update); empty or absent blocks get the catalog starter. Records the install baseline (config.installed_from: catalog source + per-schema fingerprint) for installed-vs-catalog drift detection (schemas only). A re-install on an unchanged substrate is idempotent. On a substrate whose config carries no substrate_id, install establishes the identity at entry (mints, persists to config.json, registers in the project registry) and reports it under substrateIdEstablished; an established identity is never re-minted.",
         promptSnippet: "Install declared schemas + starter blocks from the samples catalog (skip-if-exists; --update re-syncs schemas + replaces empty blocks; records the config.installed_from baseline)",
         examples: ["pi-context context-install --json", "pi-context context-install --update true --json"],
         parameters: Type.Object({
@@ -1176,8 +1179,8 @@ export const ops = [
     {
         name: "update",
         label: "Update Installed Model",
-        description: "Bring the installed substrate model (schemas) current with the packaged catalog. Per installed schema, consults the read-only drift check and routes by state: an already-current (in-sync) schema is a no-op; a schema the package shipped a newer version of (catalog-ahead) is re-synced through the migration-aware path; a schema edited locally (locally-modified / both-diverged) is reconciled by a deterministic 3-way merge of base (the as-installed body in the object store, keyed by the recorded baseline content_hash) × ours (the installed schema) × theirs (the catalog schema) — disjoint edits auto-merge so both the user's and the catalog's changes survive (required / enum / array-valued type nodes merge as sets), and a schema with irreconcilable per-path conflicts is left unmodified — the conflict set is returned in the op output (under conflicts) alongside a readable report, and the calling agent reconciles it then commits via resolve-conflict — which writes the reconciled body AND advances the merge base to the catalog so update stops re-reporting it (no subordinate resolver is spawned); undecidable / absent schemas (no-baseline / missing-catalog / missing-installed) are reported, not touched. Update also additively propagates catalog-new config-registry entries (relation_types / invariants / block_kinds / lenses) that are absent from the substrate config, preserving every user-authored entry and any locally-diverged body of an existing entry (additive-only — present entries are never overwritten). Update reports, under migrationsRegistered, the migration declarations a version-bump resync registers into migrations.json (each as schema / from / to). A blocked (refused) catalog-ahead schema additionally carries its diagnostic detail under blockedDetail (one entry per blocked schema): the refusal reason — no-migration-chain (no shipped chain reaches the catalog version) vs validation-failed (the forward-migrated items fail the catalog schema) — the installed -> catalog version pair, and for a validation failure the per-item failures naming the failing item id, field, and constraint. A live blocked resync also persists a pending-blocked record (pinning the target catalog schema + the chain reaching it) consumable by resolve-blocked, which commits the resolution once the block's items are fixed. Pass dryRun to preview the per-schema action plan; dryRun predicts the precise per-schema catalog-ahead outcome (resync / migrate / block / merge / conflict) by running the forward-migration + re-validation in memory, the per-blocked-schema diagnostic detail, the config-registry entries that would be added, AND the migration declarations that would be registered, writing nothing. When a catalog-ahead resync is blocked because the block's items fail the catalog schema (validation-failed), update inscribes git-style failure markers INTO the block file at the offending items (full-line `<<<<<<< BLOCKED …` / `>>>>>>> target: …` sentinels), pinning the pre-marker bytes so resolve-blocked can strip the markers and re-validate; the schema and migrations.json stay byte-unchanged. A dryRun preview writes no markers.",
-        promptSnippet: "Update the installed schema model from the catalog (3-way merges locally-modified schemas, preserving non-conflicting edits; conflicts → returned in the op output + a report for the calling agent to reconcile and commit via resolve-conflict; a blocked resync carries blockedDetail — reason, version pair, per-item failures — and persists a pending-blocked record (target catalog schema + the chain reaching it) resolved via resolve-blocked once the block's items are fixed; a validation-failed block is marked in place with git-style failure markers (recoverable; stripped + re-validated by resolve-blocked); --dry-run predicts the precise per-schema outcome — resync / migrate / block / merge / conflict — via in-memory forward-migration + re-validation, writing nothing)",
+        description: "Bring the installed substrate model (schemas) current with the packaged catalog. Per installed schema, consults the read-only drift check and routes by state: an already-current (in-sync) schema is a no-op; a schema the package shipped a newer version of (catalog-ahead) is re-synced through the migration-aware path; a schema edited locally (locally-modified / both-diverged) is reconciled by a deterministic 3-way merge of base (the as-installed body in the object store, keyed by the recorded baseline content_hash) × ours (the installed schema) × theirs (the catalog schema) — disjoint edits auto-merge so both the user's and the catalog's changes survive (required / enum / array-valued type nodes merge as sets), and a schema with irreconcilable per-path conflicts is left unmodified — the conflict set is returned in the op output (under conflicts) alongside a readable report, and the calling agent reconciles it then commits via resolve-conflict — which writes the reconciled body AND advances the merge base to the catalog so update stops re-reporting it (no subordinate resolver is spawned); undecidable / absent schemas (no-baseline / missing-catalog / missing-installed) are reported, not touched. Update also additively propagates catalog-new config-registry entries (relation_types / invariants / block_kinds / lenses) that are absent from the substrate config, preserving every user-authored entry and any locally-diverged body of an existing entry (additive-only — present entries are never overwritten). Update reports, under migrationsRegistered, the migration declarations a version-bump resync registers into migrations.json (each as schema / from / to). A blocked (refused) catalog-ahead schema additionally carries its diagnostic detail under blockedDetail (one entry per blocked schema): the refusal reason — no-migration-chain (no shipped chain reaches the catalog version) vs validation-failed (the forward-migrated items fail the catalog schema) vs write-failed (a non-validation throw at the write boundary, e.g. the block writer's duplicate-item-id guard; the failures entry carries the thrown message, the items were NOT flagged invalid, and no markers or pending-blocked record are produced) — the installed -> catalog version pair, and for a validation failure the per-item failures naming the failing item id, field, and constraint. A live blocked resync also persists a pending-blocked record (pinning the target catalog schema + the chain reaching it) consumable by resolve-blocked, which commits the resolution once the block's items are fixed. Pass dryRun to preview the per-schema action plan; dryRun predicts the precise per-schema catalog-ahead outcome (resync / migrate / block / merge / conflict) by running the forward-migration + re-validation in memory, the per-blocked-schema diagnostic detail, the config-registry entries that would be added, AND the migration declarations that would be registered, writing nothing beyond the idempotent ceremony seed of the catalog's config migration declarations into migrations.json (every substrate-lifecycle ceremony seeds at entry, before its first config read, so a version-lagging legacy substrate heals instead of throwing). When a catalog-ahead resync is blocked because the block's items fail the catalog schema (validation-failed), update inscribes git-style failure markers INTO the block file at the offending items (full-line `<<<<<<< BLOCKED …` / `>>>>>>> target: …` sentinels), pinning the pre-marker bytes so resolve-blocked can strip the markers and re-validate; the schema and migrations.json stay byte-unchanged. A dryRun preview writes no markers. Because update applies per-component (a blocked schema rolls back only itself; the additive registry propagation writes regardless), a run that refuses any schema while applying registry additions or other-schema resyncs/migrations/merges reports the partiality under partialApplication — applied and notApplied channel mirrors plus a one-line summary naming what was applied alongside what was refused and why — so a blocked run never reads as a no-op; dryRun reports the predicted partiality in the same shape. On a substrate whose config carries no substrate_id, a LIVE update establishes the identity at entry (mints, persists to config.json, registers in the project registry) before its first identity-stamping write — so a pre-identity substrate heals on the ceremony instead of refusing — and reports it under substrateIdEstablished; an established identity is never re-minted, and dryRun (no stamping writes) establishes nothing.",
+        promptSnippet: "Update the installed schema model from the catalog (3-way merges locally-modified schemas, preserving non-conflicting edits; conflicts → returned in the op output + a report for the calling agent to reconcile and commit via resolve-conflict; a blocked resync carries blockedDetail — reason (no-migration-chain / validation-failed / write-failed for a non-validation write-boundary throw), version pair, per-item failures — and a validation-failed block persists a pending-blocked record (target catalog schema + the chain reaching it) resolved via resolve-blocked once the block's items are fixed; a validation-failed block is marked in place with git-style failure markers (recoverable; stripped + re-validated by resolve-blocked); --dry-run predicts the precise per-schema outcome — resync / migrate / block / merge / conflict — via in-memory forward-migration + re-validation, writing nothing; a run that refuses any schema while applying registry additions or other-schema updates surfaces the partiality under partialApplication with a one-line summary, so a blocked run never reads as a no-op)",
         examples: [`pi-context update --dryRun true --json`],
         parameters: Type.Object({
             dryRun: Type.Optional(Type.Boolean({ description: "Preview the per-schema action plan without writing anything." })),
@@ -1553,7 +1556,7 @@ export const ops = [
     {
         name: "context-walk-descendants",
         label: "Context Walk Descendants",
-        description: "Walk closure-table descendants of a parent id under a given relation_type. Returns string[] of descendant ids (may be empty if no children or relations.json absent).",
+        description: "Walk closure-table descendants of a parent id under a given relation_type. Returns string[] of descendant ids (may be empty if no children or relations.json absent). For a DISJOINT-kind relation, querying from the wrong (target-kind) end THROWS naming walk-ancestors instead of silently returning []; same-kind / wildcard relations return [] honestly.",
         promptSnippet: "Walk closure-table descendants under a relation_type",
         examples: [
             `pi-context context-walk-descendants --parentId FEAT-008 --relationType feature_decomposed_into_task --json`,
@@ -1571,7 +1574,7 @@ export const ops = [
     {
         name: "walk-ancestors",
         label: "Walk Ancestors",
-        description: "Walk closure-table ancestors of an item id under a given relation_type — reverse-direction counterpart to context-walk-descendants. Returns string[] of ancestor ids (may be empty if no parents or relations.json absent).",
+        description: "Walk closure-table ancestors of an item id under a given relation_type — reverse-direction counterpart to context-walk-descendants. Returns string[] of ancestor ids (may be empty if no parents or relations.json absent). For a DISJOINT-kind relation, querying from the wrong (source-kind) end THROWS naming context-walk-descendants instead of silently returning []; same-kind / wildcard relations return [] honestly.",
         promptSnippet: "Walk closure-table ancestors under a relation_type",
         examples: [`pi-context walk-ancestors --itemId TASK-042 --relationType feature_decomposed_into_task --json`],
         parameters: Type.Object({
@@ -1632,75 +1635,45 @@ export const ops = [
     {
         name: "context-roadmap-load",
         label: "Context: load roadmap",
-        description: "Load a roadmap by id and return the materialized RoadmapView (phases, lens-views, status rollup, milestone resolution, scoped phase_depends_on edges, topo-ordered phaseOrder + cycles). Phase ordering lives in relations.json with relation_type='phase_depends_on'.",
-        promptSnippet: "Load a roadmap by id",
-        examples: [`pi-context context-roadmap-load --roadmapId ROADMAP-001 --json`],
-        parameters: Type.Object({
-            roadmapId: Type.String({ description: "ROADMAP-NNN id from <config.root>/roadmap.json" }),
-        }),
+        description: "Load the derived roadmap view over the milestone_precedes_milestone DAG: milestone-block items topo-ordered by the authored precedes edges (order + cycles), each milestone carrying its derived status/phaseCount (currentState's milestone rollup), its member phases (parents of phase_positioned_in_milestone edges), each phase's tasks (parents of task_positioned_in_phase edges), and per-phase + per-milestone status rollups. Adjacency comes strictly from the authored edges — never inferred from order. Zero milestones is a valid empty view.",
+        promptSnippet: "Load the derived milestone roadmap view",
+        examples: [`pi-context context-roadmap-load --json`],
+        parameters: Type.Object({}),
         surface: "use",
-        run(cwd, params) {
-            const view = loadRoadmap(cwd, params.roadmapId);
-            if ("error" in view) {
-                const read = structureForRead(view, { whole: true, label: `roadmap ${params.roadmapId} (error)` });
-                return { read };
-            }
-            // whole: a structured RoadmapView (phases + lens-views + rollups) — keep
-            // the view shape intact rather than paging an inner array.
-            const read = structureForRead(serializeRoadmapView(view), {
-                whole: true,
-                label: `roadmap ${params.roadmapId}`,
-            });
+        run(cwd, _params) {
+            const view = loadRoadmap(cwd);
+            // whole: a structured MilestoneRoadmapView (milestones + rollups + edges)
+            // — keep the view shape intact rather than paging an inner array.
+            const read = structureForRead(view, { whole: true, label: "roadmap (derived)" });
             return { read };
         },
     },
     {
         name: "context-roadmap-render",
         label: "Context: render roadmap",
-        description: "Render a roadmap by id as pure-textual markdown — phase order list, per-phase adjacency lines (sourced from view.edges, alphabetically sorted), status rollup counts, milestone resolution, exit criteria. NO mermaid / graph syntax: per-phase **Depends on:** lines come strictly from authored phase_depends_on edges scoped to in-roadmap phases.",
-        promptSnippet: "Render a roadmap as markdown",
-        examples: [`pi-context context-roadmap-render --roadmapId ROADMAP-001`],
-        parameters: Type.Object({
-            roadmapId: Type.String({ description: "ROADMAP-NNN id from <config.root>/roadmap.json" }),
-        }),
+        description: "Render the derived roadmap as pure-textual markdown — milestone order list (topo over the authored milestone_precedes_milestone edges), per-milestone sections with **Preceded by:** adjacency lines sourced strictly from those edges (alphabetically sorted; '—' when none), per-milestone rollup counts, and per-phase task tables. Cycle participants surface under a separate heading with a Cycles-detected line. NO mermaid / graph syntax; adjacency is never inferred from order consecutive pairs.",
+        promptSnippet: "Render the derived milestone roadmap as markdown",
+        examples: [`pi-context context-roadmap-render`],
+        parameters: Type.Object({}),
         surface: "use",
-        run(cwd, params) {
-            const view = loadRoadmap(cwd, params.roadmapId);
+        run(cwd, _params) {
+            const view = loadRoadmap(cwd);
             if ("error" in view) {
                 return { json: view };
             }
-            const naming = loadContext(cwd).config?.naming;
-            return renderRoadmap(view, naming);
+            return renderRoadmap(view);
         },
     },
     {
         name: "context-roadmap-validate",
-        label: "Context: validate roadmap(s)",
-        description: "Validate every roadmap × phase × milestone in <config.root>/roadmap.json. Codes: roadmap_lens_missing, roadmap_phase_dep_missing, roadmap_phase_cycle, roadmap_composition_cycle, roadmap_milestone_evidence_block_missing, roadmap_milestone_query_invalid, roadmap_status_unknown_value. Display strings flow through config.display_strings (pi-context divergence). Optional roadmapId filter restricts issue list to a single roadmap.",
-        promptSnippet: "Validate roadmaps",
-        examples: [`pi-context context-roadmap-validate --roadmapId ROADMAP-001 --json`],
-        parameters: Type.Object({
-            roadmapId: Type.Optional(Type.String({ description: "Filter to issues matching this roadmap_id (omit for full-project validation)" })),
-        }),
-        surface: "use",
-        run(cwd, params) {
-            const result = validateRoadmaps(cwd);
-            const filtered = params.roadmapId
-                ? result.issues.filter((i) => !i.roadmap_id || i.roadmap_id === params.roadmapId)
-                : result.issues;
-            return { json: { status: result.status, issues: filtered } };
-        },
-    },
-    {
-        name: "context-roadmap-list",
-        label: "Context: list roadmaps",
-        description: "List every roadmap in <config.root>/roadmap.json with id, title, optional status, and phase count. Returns [] when roadmap.json absent (opt-in block; absence is the truthful answer).",
-        promptSnippet: "List roadmaps",
-        examples: [`pi-context context-roadmap-list --json`],
+        label: "Context: validate roadmap",
+        description: "Validate the derived roadmap over the milestone_precedes_milestone edges. Error codes: roadmap_precedes_endpoint_missing (a precedes-edge endpoint that is not a milestone-block item), roadmap_milestone_cycle (a cycle in the precedes graph), roadmap_milestone_missing (a phase_positioned_in_milestone edge whose child is not a known milestone). Warning: roadmap_status_unknown_value (a member phase whose task rollup buckets unknown with items present). Info: roadmap_milestone_isolated (a milestone with zero precedes edges while others are ordered) — info never affects status: invalid iff any error-code issue, warnings iff any warning-code issue, else clean. Display strings flow through config.display_strings (pi-context divergence).",
+        promptSnippet: "Validate the derived milestone roadmap",
+        examples: [`pi-context context-roadmap-validate --json`],
         parameters: Type.Object({}),
         surface: "use",
         run(cwd, _params) {
-            return { json: listRoadmaps(cwd) };
+            return { json: validateRoadmap(cwd) };
         },
     },
 ];