@davidorex/pi-context 0.31.0 → 0.33.0

package/dist/ops-registry.js

@@ -16,12 +16,13 @@
  * phase (the auth-gate at the pi-agent-dispatch layer remains the enforcement
  * point, unchanged by this relocation).
  */
+import fs from "node:fs";
 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, loadRelations } 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, buildIdIndex, completeTask, contextState, currentState, deriveBootstrapState, endpointKey, evaluateConfigInvariants, filterBlockItems, joinBlocks, orientAppendInput, 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
@@ -29,12 +30,12 @@ import { gatherExecutionContext } from "./execution-context.js";
 // registerAll runs at extension-load time, after both modules' top-level
 // function bindings exist, and the helpers are only referenced inside op `run`
 // closures (lazy), never at this module's top level.
-import { archiveSubstrate, checkStatus, initProject, installContext, listSubstrates, readCatalogSchemaText, resolveBlocked, resolveConflict, switchAndCreate, switchToExisting, switchToPrevious, updateContext, validateBlockItemsAgainstCatalog, } from "./index.js";
+import { archiveSubstrate, checkStatus, convergeDerivedStatusAfterWrite, initProject, installContext, listSubstrates, readCatalogSchemaText, reconcileContext, resolveBlocked, resolveConflict, switchAndCreate, switchToExisting, switchToPrevious, updateContext, validateBlockItemsAgainstCatalog, } from "./index.js";
 import { edgesForLensByName, findReferencesInRepo, loadLensView, validateContextRelations, walkAncestorsByLens, walkLensDescendants, } from "./lens-view.js";
 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,39 +116,133 @@ 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 } : {}),
+/**
+ * Coerce a filing op's optional `relations` param (may arrive as a JSON string
+ * from the CLI, like Type.Unknown item payloads) and shape-check each entry
+ * before any write happens — a malformed entry must refuse the filing BEFORE
+ * the item lands, not mid-edge-loop. Enforces the direction/role mutual
+ * exclusion (exactly one per entry), mirroring the standalone porcelain's
+ * parent/child vs primary/counter pair exclusion.
+ */
+function coerceBirthRelations(raw) {
+    let value = raw;
+    if (typeof value === "string") {
+        try {
+            value = JSON.parse(value);
+        }
+        catch {
+            throw new Error("relations parameter must be a JSON array, got unparseable string");
+        }
+    }
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("relations parameter must be a JSON array");
+    return value.map((entry, i) => {
+        const e = entry;
+        const shapeError = () => new Error(`relations[${i}] must be {relation_type: string, other: string, ordinal?: integer} plus EXACTLY ONE of direction: "as_parent"|"as_child" (raw form) or role: "primary"|"counter" (role-typed form)`);
+        if (e === null || typeof e !== "object" || typeof e.relation_type !== "string" || typeof e.other !== "string") {
+            throw shapeError();
+        }
+        const hasDirection = e.direction !== undefined;
+        const hasRole = e.role !== undefined;
+        if (hasDirection === hasRole)
+            throw shapeError(); // both or neither
+        if (hasDirection && e.direction !== "as_parent" && e.direction !== "as_child")
+            throw shapeError();
+        if (hasRole && e.role !== "primary" && e.role !== "counter")
+            throw shapeError();
+        return {
+            relation_type: e.relation_type,
+            other: e.other,
+            ...(hasDirection ? { direction: e.direction } : {}),
+            ...(hasRole ? { role: e.role } : {}),
+            ...(e.ordinal !== undefined ? { ordinal: e.ordinal } : {}),
+        };
+    });
+}
+/**
+ * Map one coerced birth entry to the {@link appendRelationByRef} input, with
+ * the new item at the entry's endpoint: the raw form fills parent/child, the
+ * role form fills primary/counter (the SAME role-typed pair the standalone
+ * append-relation flags fill), so orientAppendInput applies its mapping and
+ * guards verbatim — no orientation logic lives here.
+ */
+function birthRelationToAppendInput(itemId, rel) {
+    const ordinalPart = rel.ordinal !== undefined ? { ordinal: rel.ordinal } : {};
+    if (rel.role !== undefined) {
+        return {
+            relation_type: rel.relation_type,
+            ...(rel.role === "primary" ? { primary: itemId, counter: rel.other } : { primary: rel.other, counter: itemId }),
+            ...ordinalPart,
+        };
+    }
+    return {
+        relation_type: rel.relation_type,
+        parent: rel.direction === "as_parent" ? itemId : rel.other,
+        child: rel.direction === "as_parent" ? rel.other : itemId,
+        ...ordinalPart,
+    };
+}
+/**
+ * File a new item's birth edges through the same validated porcelain a
+ * standalone append-relation uses (registered-type + endpoint-kind gate,
+ * role-direction mapping + orientation-ambiguity guard, atomic write,
+ * exact-duplicate no-op), with the new item at each entry's endpoint. Runs
+ * AFTER the item write (its id must resolve as an endpoint) inside the same
+ * op run, so the write-time invariant gate judges item + edges as one
+ * transition atom; a throw here is byte-restored by the pipeline wrapper
+ * (all-or-nothing).
+ */
+function appendBirthRelations(cwd, itemId, relations, ctx) {
+    for (const rel of relations) {
+        appendRelationByRef(cwd, birthRelationToAppendInput(itemId, rel), ctx);
+    }
+}
+/**
+ * Preview-parity orientation check for dryRun filings: run the SAME
+ * role-mapping + ambiguity guard the live edge write applies
+ * (orientAppendInput), against the registry only — endpoint resolution stays
+ * out because the item is unwritten under a preview. A preview thereby
+ * refuses exactly the entries the live run would orientation-refuse.
+ */
+function assertBirthRelationsOrientable(cwd, itemId, relations) {
+    if (relations.length === 0)
+        return;
+    const config = loadConfig(cwd);
+    for (const rel of relations) {
+        orientAppendInput(config, birthRelationToAppendInput(itemId, rel));
+    }
+}
+/** Shared birth-relations entry schema for the filing ops (append + upsert). */
+const BIRTH_RELATION_ENTRY = Type.Object({
+    relation_type: Type.String({ description: "Registered relation_type canonical_id" }),
+    direction: Type.Optional(Type.Union([Type.Literal("as_parent"), Type.Literal("as_child")], {
+        description: "RAW orientation — which edge endpoint the NEW item occupies. Exactly one of direction/role per entry.",
+    })),
+    role: Type.Optional(Type.Union([Type.Literal("primary"), Type.Literal("counter")], {
+        description: "ROLE-TYPED orientation — the semantic role the NEW item holds, mapped to parent/child via the relation's declared role_direction (same mapping as append-relation --primary/--counter). REQUIRED for role-bearing orientation-ambiguous relation_types (same-kind or wildcard endpoints), where the raw form is rejected. Exactly one of direction/role per entry.",
     })),
-    phaseOrder: view.phaseOrder,
-    cycles: view.cycles,
-    edges: view.edges,
+    other: Type.String({ description: "Selector of the other endpoint (canonical id / <alias>:<refname>)" }),
+    ordinal: Type.Optional(Type.Integer({ description: "Optional sibling-ordering within (parent, relation_type)" })),
 });
 export const ops = [
     {
         name: "append-block-item",
         label: "Append Block Item",
-        description: "Append an item to an array in a project block file. Schema validation is automatic. Set autoId:true to allocate the next id from the block's id pattern when the item has no id.",
-        promptSnippet: "Append items to project blocks (issues, decisions, or any user-defined block)",
+        description: "Append an item to an array in a project block file. Schema validation is automatic. Set autoId:true to allocate " +
+            "the next id from the block's id pattern when the item has no id. Optional relations file the item's BIRTH edges " +
+            "in the same op run, after id allocation — each entry names the relation_type, the other endpoint's selector, and " +
+            "EXACTLY ONE orientation: direction (as_parent | as_child — the raw endpoint the new item occupies) or role " +
+            "(primary | counter — the semantic role the new item holds, mapped via the relation's declared role_direction; " +
+            "required for role-bearing orientation-ambiguous relation_types such as the gated-by / derived-from / supersedes " +
+            "/ depends families, where the raw form is rejected). Filing item + edges as one atom lets a new item satisfy " +
+            "error-severity birth-edge invariants (e.g. a decision must cite a forcing artifact) that would refuse the bare " +
+            "item under the write-time gate.",
+        promptSnippet: "Append items to project blocks (issues, decisions, or any user-defined block), with optional atomic birth edges",
         examples: [
             `pi-context append-block-item --block framework-gaps --arrayKey gaps --autoId true --item @/tmp/fgap.json --writer '{"kind":"human","user":"you@example.com"}' --json`,
+            `pi-context append-block-item --block decisions --arrayKey decisions --autoId true --item @/tmp/dec.json --relations '[{"relation_type":"decision_addresses_gap","direction":"as_parent","other":"FGAP-001"},{"relation_type":"decision_derived_from_item","role":"counter","other":"TASK-001"}]' --writer '{"kind":"human","user":"you@example.com"}' --json`,
         ],
         parameters: Type.Object({
             block: Type.String({ description: "Block name (e.g., 'issues', 'decisions')" }),
@@ -156,6 +251,9 @@ export const ops = [
             autoId: Type.Optional(Type.Boolean({
                 description: "When true and the item has no id, allocate the next id from the block's id pattern",
             })),
+            relations: Type.Optional(Type.Array(BIRTH_RELATION_ENTRY, {
+                description: "Birth edges filed atomically with the item, after id allocation, via the same validated append-relation porcelain (each entry oriented by direction OR role)",
+            })),
         }),
         surface: "use",
         run(cwd, params, ctx) {
@@ -168,17 +266,27 @@ export const ops = [
                     throw new Error(`item parameter must be a JSON object, got unparseable string`);
                 }
             }
+            const relations = coerceBirthRelations(params.relations);
             // Auto-id allocation (FGAP-084 dual-surface twin of file-block-item --auto-id)
             if (params.autoId && params.item && typeof params.item === "object" && !params.item.id) {
                 params.item.id = nextId(cwd, params.block);
             }
+            if (relations.length > 0 && (typeof params.item?.id !== "string" || params.item.id.length === 0)) {
+                throw new Error("relations requires the appended item to carry an id (supply item.id or set autoId:true) — birth edges need the new item's endpoint selector");
+            }
             // Id-uniqueness is enforced atomically inside appendToBlock's
             // withBlockLock critical section (block-api assertAppendIdUnique) —
             // the single enforcement point. The prior racy readBlock-then-append
             // tool-layer check was removed in favour of that library guard.
             appendToBlock(cwd, params.block, params.arrayKey, params.item, ctx);
+            // Birth edges AFTER the item lands (its id must resolve as an endpoint),
+            // inside the same op run so the write-time gate judges item + edges as
+            // one transition atom; a failed edge throws and the pipeline wrapper
+            // byte-restores the whole write (all-or-nothing).
+            appendBirthRelations(cwd, String(params.item.id), relations, ctx);
             const id = params.item?.id ? ` '${params.item.id}'` : "";
-            return `Appended item${id} to ${params.block}.${params.arrayKey}`;
+            const edges = relations.length > 0 ? ` with ${relations.length} birth relation(s)` : "";
+            return `Appended item${id} to ${params.block}.${params.arrayKey}${edges}`;
         },
     },
     {
@@ -211,17 +319,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 +352,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 +423,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 +484,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 +514,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)`;
@@ -398,8 +534,16 @@ export const ops = [
         label: "Upsert Block Item",
         description: "Append-or-replace an item in a project block array by id: if an item with the same idField value exists it is " +
             "REPLACED (full-shape replacement, not shallow-merge — use update-block-item for merge); otherwise the item is " +
-            "appended. Schema validation is automatic. idField defaults to 'id'.",
-        promptSnippet: "Append-or-replace a full block item by id (replacement, not merge)",
+            "appended. Schema validation is automatic. idField defaults to 'id'. Optional relations file BIRTH edges in the " +
+            "same op run when the upsert resolves to an APPEND — each entry names the relation_type, the other endpoint's " +
+            "selector, and EXACTLY ONE orientation: direction (as_parent | as_child, raw) or role (primary | counter, mapped " +
+            "via the relation's declared role_direction; required for role-bearing orientation-ambiguous relation_types) — " +
+            "one atom under the write-time gate, so a new filing can satisfy error-severity birth-edge invariants. dryRun " +
+            "previews the upsert AND runs the same orientation guard over the entries (a preview refuses what the live run " +
+            "would orientation-refuse; endpoint resolution stays out — the item is unwritten). When the upsert resolves to a " +
+            "REPLACE, supplying relations refuses the write (birth edges are for new items; file edges on an existing item " +
+            "via append-relation).",
+        promptSnippet: "Append-or-replace a full block item by id (replacement, not merge), with optional atomic birth edges",
         examples: [
             `pi-context upsert-block-item --block tasks --arrayKey tasks --item @/tmp/task.json --writer '{"kind":"human","user":"you@example.com"}' --json`,
         ],
@@ -409,6 +553,9 @@ export const ops = [
             item: Type.Unknown({ description: "Full item object to upsert — must conform to block schema" }),
             idField: Type.Optional(Type.String({ description: "Field used as the upsert key (default 'id')" })),
             dryRun: Type.Optional(Type.Boolean({ description: "Preview the upsert without writing" })),
+            relations: Type.Optional(Type.Array(BIRTH_RELATION_ENTRY, {
+                description: "Birth edges filed atomically with an APPEND-mode upsert, each entry oriented by direction OR role (refused on replace mode — use append-relation for existing items)",
+            })),
         }),
         surface: "use",
         run(cwd, params, ctx) {
@@ -421,17 +568,36 @@ export const ops = [
                     throw new Error(`item parameter must be a JSON object, got unparseable string`);
                 }
             }
+            const relations = coerceBirthRelations(params.relations);
             const idField = params.idField ?? "id";
+            const idVal = params.item?.[idField];
+            if (relations.length > 0 && (typeof idVal !== "string" || idVal.length === 0)) {
+                throw new Error(`relations requires the upserted item to carry a string '${idField}' — birth edges need the new item's endpoint selector`);
+            }
             // Under dryRun upsertItemInBlock computes mode + builds + validates the prospective
             // whole block, writing nothing (TASK-011 shared preview path).
             const { mode } = upsertItemInBlock(cwd, params.block, params.arrayKey, params.item, idField, ctx, {
                 dryRun: params.dryRun,
             });
-            const idVal = params.item?.[idField];
+            if (relations.length > 0 && mode === "updated") {
+                // Birth edges are a NEW-item affordance. Throwing here (post-write) is
+                // safe: the pipeline wrapper byte-restores the substrate on inner-op
+                // throw, so the replacement never persists (all-or-nothing).
+                throw new Error(`relations was supplied but the upsert resolved to REPLACE for '${idVal}' — birth edges are for new items; file edges on an existing item via append-relation`);
+            }
             const idDesc = idVal !== undefined ? ` '${idVal}'` : "";
-            return params.dryRun
-                ? `would upsert item${idDesc} (${mode}) in ${params.block}.${params.arrayKey}`
-                : `Upserted item${idDesc} (${mode}) to ${params.block}.${params.arrayKey}`;
+            if (params.dryRun) {
+                // Preview parity: run the SAME role-mapping + orientation-ambiguity
+                // guard the live edge write applies, against the registry only — the
+                // item is unwritten, so endpoint resolution stays out. A preview
+                // refuses exactly the entries the live run would orientation-refuse.
+                assertBirthRelationsOrientable(cwd, String(idVal), relations);
+                const edgePreview = relations.length > 0 ? `; would file ${relations.length} birth relation(s)` : "";
+                return `would upsert item${idDesc} (${mode}) in ${params.block}.${params.arrayKey}${edgePreview}`;
+            }
+            appendBirthRelations(cwd, String(idVal), relations, ctx);
+            const edges = relations.length > 0 ? ` with ${relations.length} birth relation(s)` : "";
+            return `Upserted item${idDesc} (${mode}) to ${params.block}.${params.arrayKey}${edges}`;
         },
     },
     {
@@ -680,7 +846,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 +1034,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 is not complete is reported in blockedBy and held out of nextActions; completeness follows the target kind's truth model — a rollup-declared kind (state_derivation.rollups, e.g. milestone) completes by its DERIVED membership rollup, the same verdict the milestones facet reports, so one read never self-contradicts and a derived-status kind's stored status field is never consulted; every other kind completes by its status bucketing to complete. 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 +1228,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 +1245,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 +1322,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 +1342,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." })),
@@ -1190,6 +1356,24 @@ export const ops = [
             return { json: result };
         },
     },
+    {
+        name: "context-reconcile",
+        label: "Context Reconcile",
+        description: "Converge stored substrate state with its derivation (the repair half of the derived-status invariant class). For every block kind a derived-status invariant declares (paired with its state_derivation.rollups entry), computes each item's stored-vs-derived status delta using the SAME completeness helper the state derivation's gate satisfaction and context-validate use — the preview, the detector, and the repair cannot disagree. The sweep also includes declared-baseline STALENESS: every stale_conditions-bearing item whose status buckets complete and whose typed condition fired (item-status / file-changed / revision-moved) or whose citation content pin drifted transitions to stale — the same evaluateStalenessCandidates verdict context-validate flags with; flag-only anchor-drift items never transition. --dryRun returns the exact delta + transition sets a live run would apply (deltas: id, block, from stored value, to derived value, declaring invariant; stalenessTransitions: id, block, from, to stale, firing reasons), writing nothing. A live run applies exactly those sets through the standard validated write path — identity-stamped, envelope-stamped, attested to the invoking writer — and reports the applied counts; a converge-write is not authoring, the written value IS the derivation, and the stale transition applies a condition the item itself declared. Scope: derived-status deltas + declared-staleness transitions ONLY — the op never writes an authored-status kind (feature/gap/issue/task buckets are human judgment) and never touches prose; those classes are flagged for review by context-validate, not auto-repaired. Ceremony discipline: seeds the catalog config migration declarations at entry, and a live run on a substrate with no substrate_id establishes the identity first (reported under substrateIdEstablished). A converged substrate is a clean no-op both ways.",
+        promptSnippet: "Converge stored rollup-kind statuses with their derivation and apply declared complete-to-stale transitions (--dryRun previews the exact sets; live applies through the validated write path; never touches authored statuses or prose)",
+        examples: [`pi-context context-reconcile --dryRun true --json`],
+        parameters: Type.Object({
+            dryRun: Type.Optional(Type.Boolean({ description: "Preview the exact delta set without writing anything." })),
+        }),
+        surface: "use",
+        authGated: true,
+        run(cwd, params, ctx) {
+            const result = reconcileContext(cwd, { dryRun: params.dryRun === true }, ctx);
+            if (result.error)
+                return result.error;
+            return { json: result };
+        },
+    },
     {
         name: "validate-block-items",
         label: "Validate Block Items",
@@ -1467,21 +1651,26 @@ export const ops = [
     {
         name: "complete-task",
         label: "Complete Task",
-        description: "Complete a task with verification gate — requires a passing verification entry targeting the task.",
-        promptSnippet: "Complete a task — gates on passing verification before updating status",
+        description: "Complete a task with verification gate — the closure ATOM. Requires a passing verification entry, then FILES " +
+            "the verification_verifies_item edge itself (idempotent — a pre-existing exact edge is a no-op) and flips the " +
+            "task status to completed in one op run, so the write-time invariant gate judges the joint end-state. No prior " +
+            "append-relation step is needed (a standalone edge or status write would be refused by error-severity closure " +
+            "invariants; this op IS the legal transition).",
+        promptSnippet: "Complete a task — gates on passing verification, files the verification edge itself, then flips status (one atom)",
         examples: [
             `pi-context complete-task --taskId TASK-001 --verificationId VER-001 --writer '{"kind":"human","user":"you@example.com"}' --json`,
         ],
         parameters: Type.Object({
             taskId: Type.String({ description: "Task ID to complete" }),
             verificationId: Type.String({
-                description: "Verification entry ID (must target this task with status 'passed')",
+                description: "Verification entry ID (must have status 'passed'; the op files the linking edge itself)",
             }),
         }),
         surface: "use",
         run(cwd, params, ctx) {
             const result = completeTask(cwd, params.taskId, params.verificationId, ctx);
-            return `Task '${result.taskId}' completed (was '${result.previousStatus}'). Verification: ${result.verificationId} (${result.verificationStatus})`;
+            const edge = result.edgeAppended ? "edge filed" : "edge pre-existing";
+            return `Task '${result.taskId}' completed (was '${result.previousStatus}'). Verification: ${result.verificationId} (${result.verificationStatus}, ${edge})`;
         },
     },
     {
@@ -1553,7 +1742,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 +1760,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 +1821,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) };
         },
     },
 ];
@@ -1735,6 +1894,10 @@ export const gatedTools = ops.filter((o) => o.authGated).map((o) => o.name);
  * covered when its cwd-form sibling is covered.
  */
 export const INTENTIONALLY_UNEXPOSED_WRITERS = [
+    {
+        libraryFn: "convergeDerivedStatusAfterWrite",
+        reason: "post-write convergence hook, invoked by the CONVERGE_AFTER_OPS module-init wrapper around every rollup-input-mutating op's run() — op-backed transitively at runtime, but the static classifier cannot see a wrapper-installed call; its explicit ceremony surface is context-reconcile",
+    },
     { libraryFn: "writeConfig", safeOp: "amend-config", reason: "scoped guarded config mutation" },
     { libraryFn: "writeSchema", safeOp: "write-schema", reason: "raw bypasses the create/replace + migration check" },
     { libraryFn: "updateSchema", safeOp: "write-schema", reason: "no mutator-scripting surface" },
@@ -1880,6 +2043,187 @@ export function buildDispatchContextFromExecute(params, extCtx) {
     const modelId = extCtx.model?.id;
     return { writer: { kind: "agent", agent_id: modelId && modelId.length > 0 ? modelId : "pi-agent" } };
 }
+/**
+ * Converge-on-write (FEAT-011 criterion 2 — FGAP-116): the sanctioned mutating
+ * ops that can change a rollup INPUT (a member item's status; a membership
+ * edge; an id every edge keys on) run the derived-status convergence hook
+ * AFTER their own write lands — so every op-surface write leaves rollup-kind
+ * stored statuses equal to their derivation. The hook is config-driven
+ * opt-in (no derived-status invariant → empty set → no writes) and
+ * best-effort (its failure never fails the landed write; the invariant +
+ * context-reconcile remain the net — see convergeDerivedStatusAfterWrite).
+ * Nested-item ops are excluded: item statuses are top-level fields, so a
+ * nested write cannot change a rollup input. Wrapping happens ONCE here at
+ * module init, over the ops DATA — no per-op body edits, no dispatch-path
+ * fork; both consumers (registerAll pi tools + the reflecting CLI) execute
+ * the wrapped run.
+ */
+const CONVERGE_AFTER_OPS = new Set([
+    "append-block-item",
+    "upsert-block-item",
+    "update-block-item",
+    "remove-block-item",
+    "write-block",
+    "complete-task",
+    "append-relation",
+    "append-relations",
+    "remove-relation",
+    "replace-relation",
+    "rename-canonical-id",
+    "promote-item",
+]);
+/**
+ * Evaluate every config invariant against the substrate's current state,
+ * keyed per violation instance (`code|field`) for delta comparison. Returns
+ * null when the substrate is unreadable or declares no invariants — the gate
+ * is config-driven opt-in and NEVER breaks a write on legacy/undeclared
+ * substrates. Uses the SAME evaluateConfigInvariants path validateContext
+ * runs, so write-side and validate-side verdicts are identical (TASK-062
+ * lift pattern).
+ */
+function invariantSnapshot(cwd) {
+    try {
+        const config = loadConfig(cwd);
+        if (!config || (config.invariants ?? []).length === 0)
+            return null;
+        const index = buildIdIndex(cwd);
+        const relations = loadRelations(cwd);
+        const issues = evaluateConfigInvariants(cwd, config, index, relations);
+        return new Map(issues.map((i) => [`${i.code}|${i.field ?? ""}`, { severity: i.severity, message: i.message }]));
+    }
+    catch {
+        return null;
+    }
+}
+/** Snapshot every top-level substrate *.json for a byte-exact refusal restore. */
+function substrateJsonSnapshot(cwd) {
+    try {
+        const dir = tryResolveContextDir(cwd);
+        if (dir === null)
+            return null;
+        const files = new Map();
+        for (const name of fs.readdirSync(dir)) {
+            if (!name.endsWith(".json"))
+                continue;
+            files.set(name, fs.readFileSync(path.join(dir, name)));
+        }
+        return { dir, files };
+    }
+    catch {
+        return null;
+    }
+}
+function restoreSubstrateJson(snapshot) {
+    for (const name of fs.readdirSync(snapshot.dir)) {
+        if (!name.endsWith(".json"))
+            continue;
+        if (!snapshot.files.has(name))
+            fs.unlinkSync(path.join(snapshot.dir, name));
+    }
+    for (const [name, bytes] of snapshot.files) {
+        fs.writeFileSync(path.join(snapshot.dir, name), bytes);
+    }
+}
+/** Attach write-side warnings to an op result without disturbing its shape class. */
+function attachWriteWarnings(result, warnings) {
+    if (typeof result === "string") {
+        return `${result}\n${warnings.map((w) => `write-warning: ${w}`).join("\n")}`;
+    }
+    if (result !== null && typeof result === "object" && "json" in result) {
+        const jsonValue = result.json;
+        if (jsonValue !== null && typeof jsonValue === "object" && !Array.isArray(jsonValue)) {
+            return { ...result, json: { ...jsonValue, writeWarnings: warnings } };
+        }
+    }
+    return result;
+}
+/**
+ * The write pipeline (FEAT-011 criteria 2 + 5 — one module-init pass over the
+ * ops DATA; both consumers — registerAll pi tools and the reflecting CLI —
+ * execute the wrapped run):
+ *
+ *  1. CONVERGE-ON-WRITE: after the op's write lands, rollup-kind stored
+ *     statuses are converged with their derivation (config-driven opt-in;
+ *     best-effort — see convergeDerivedStatusAfterWrite). Runs BEFORE the
+ *     gate evaluation so the gate judges the final converged state and a
+ *     divergence the convergence itself repairs is never flagged.
+ *  2. DELTA-SCOPED WRITE-TIME INVARIANT GATE: the config invariants are
+ *     evaluated before and after the write through the SAME helper
+ *     validateContext uses. Only violations ABSENT before and PRESENT after
+ *     (newly introduced by this write) act: error severity REFUSES the write
+ *     — every top-level substrate *.json is byte-restored from the pre-write
+ *     snapshot and the op throws naming the violations; warning severity is
+ *     surfaced on the op result (appended `write-warning:` lines on string
+ *     results; a `writeWarnings` array inside {json} object payloads).
+ *     Pre-existing violations never block or warn — legacy substrates stay
+ *     fully writable (the delta scope IS the expand-contract analogue).
+ *
+ *  3. ALL-OR-NOTHING ON THROW: an inner-op throw mid-composite (a birth edge
+ *     failing after the item landed; complete-task's status flip failing
+ *     after its edge landed) byte-restores the substrate from the same
+ *     pre-write snapshot before rethrowing, so a composite op never persists
+ *     a partial write the gate did not judge.
+ *
+ * dryRun invocations (append-relations --dryRun) preview without writing and
+ * bypass the pipeline entirely. Ops THROW on failure and return success
+ * strings / {json} on success, so any settled return means the write landed;
+ * sync/async contracts are preserved per op. Nested-item ops are excluded
+ * (item statuses are top-level fields).
+ */
+for (const op of ops) {
+    if (!CONVERGE_AFTER_OPS.has(op.name))
+        continue;
+    const inner = op.run.bind(op);
+    op.run = (cwd, params, ctx) => {
+        const isDryRun = params.dryRun === true;
+        const pre = isDryRun ? null : invariantSnapshot(cwd);
+        const snapshot = pre === null ? null : substrateJsonSnapshot(cwd);
+        const finish = (settled) => {
+            if (isDryRun)
+                return settled;
+            convergeDerivedStatusAfterWrite(cwd, ctx);
+            if (pre === null)
+                return settled;
+            const post = invariantSnapshot(cwd);
+            if (post === null)
+                return settled;
+            const fresh = [...post].filter(([key]) => !pre.has(key));
+            if (fresh.length === 0)
+                return settled;
+            const freshErrors = fresh.filter(([, v]) => v.severity === "error");
+            if (freshErrors.length > 0 && snapshot !== null) {
+                restoreSubstrateJson(snapshot);
+                throw new Error(`${op.name} refused — the write would introduce ${freshErrors.length} invariant violation(s) (substrate restored byte-exact): ${freshErrors
+                    .map(([, v]) => v.message)
+                    .join("; ")}`);
+            }
+            const freshWarnings = fresh.filter(([, v]) => v.severity !== "error").map(([, v]) => v.message);
+            return freshWarnings.length > 0 ? attachWriteWarnings(settled, freshWarnings) : settled;
+        };
+        // Op-level all-or-nothing: an inner-op throw MID-COMPOSITE (e.g. a birth
+        // edge or the complete-task status flip failing after an earlier write in
+        // the same run landed) byte-restores the whole substrate before
+        // rethrowing — without this, partial writes persist in states the gate
+        // never judged. Restore is snapshot-gated like the refusal path (null on
+        // dryRun / no-invariant substrates) and idempotent if finish() already
+        // restored on a gate refusal.
+        const restoreAndRethrow = (err) => {
+            if (snapshot !== null)
+                restoreSubstrateJson(snapshot);
+            throw err;
+        };
+        let result;
+        try {
+            result = inner(cwd, params, ctx);
+        }
+        catch (err) {
+            return restoreAndRethrow(err);
+        }
+        return result instanceof Promise ? result.then(finish, restoreAndRethrow) : finish(result);
+    };
+    op.description +=
+        " Write pipeline: after this op's write, rollup-kind stored statuses converge with their derivation, and the config invariants are re-evaluated delta-scoped — a violation newly introduced by this write refuses it at error severity (substrate byte-restored) or is surfaced on the result at warning severity (write-warning lines / writeWarnings); pre-existing violations never block.";
+}
 /**
  * Register every op in `ops` as a pi tool. Each tool's execute body is the
  * uniform wrapper around the op's run(): coerce params, build the attestation