@davidorex/pi-context 0.31.0 → 0.32.0

package/dist/context-sdk.js

@@ -8,19 +8,20 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { readBlock, readBlockForDir, updateItemInBlock } from "./block-api.js";
-import { appendRelation, appendRelations, endpointIdentity, endpointKey, findUnmaterializedAssets, isSkeletonConfig, loadConfig, loadRelations, removeRelation, validateRelations, writeRelations, } from "./context.js";
+import { appendRelation, appendRelations, counterEndpoint, endpointIdentity, endpointKey, findUnmaterializedAssets, isSkeletonConfig, loadConfig, loadConfigForDir, loadRelations, primaryEndpoint, removeRelation, validateRelations, writeRelations, } from "./context.js";
 import { resolveContextDir, SCHEMAS_DIR, schemaPath, schemasDir, tryResolveContextDir } from "./context-dir.js";
 import { loadRegistry, resolveAlias, resolveSubstrateDir } from "./context-registry.js";
 import { cleanGitEnv } from "./git-env.js";
 import { getLensValidators } from "./lens-validator.js";
 import { findReferencesInRepo } from "./lens-view.js";
+import { getProjectMigrationRegistryForDir } from "./migration-registry-loader.js";
 import { addressInto, discoverArrayKey, pageArray } from "./read-element.js";
-import { validateFromFile } from "./schema-validator.js";
+import { ValidationError, validateBlockWithMigrationForDir, validateFromFile } from "./schema-validator.js";
 import { findNestedIdBearingArrays } from "./schema-write.js";
-import { resolveStatusVocabulary } from "./status-vocab.js";
+import { resolveStateDerivation, resolveStatusVocabulary } from "./status-vocab.js";
 import { topoSort } from "./topo.js";
 // Re-export substrate SDK so consumers can keep importing through context-sdk.
-export { displayName, edgesForLens, endpointBin, endpointIdentity, endpointKey, groupByLens, listUncategorized, loadConfig, loadContext, loadRelations, normalizeEndpoint, synthesizeFromField, validateRelations, walkDescendants, } from "./context.js";
+export { counterEndpoint, displayName, edgesForLens, endpointBin, endpointIdentity, endpointKey, groupByLens, listUncategorized, loadConfig, loadContext, loadRelations, normalizeEndpoint, primaryEndpoint, synthesizeFromField, validateRelations, walkDescendants, } from "./context.js";
 export function availableBlocks(cwd) {
     const workflowDir = tryResolveContextDir(cwd);
     if (workflowDir === null)
@@ -527,14 +528,51 @@ export function contextState(cwd) {
  * `.project` substrate. No writes; tolerant of absent optional blocks (every
  * branch defaults to empty rather than throwing).
  *
- * Edge-direction contract for blocked/ready derivation (verified against
- * roadmap-plan.ts:471 — the topoSort-deps mapping for phase_depends_on uses the
- * identical convention): a `task_depends_on_task` edge `{parent: D, child: T}`
+ * Edge-direction contract for blocked/ready derivation (the same convention as
+ * roadmap-plan's topoSort-preds mapping for milestone_precedes_milestone —
+ * preds are parents of edges whose child is the node): a
+ * `task_depends_on_task` edge `{parent: D, child: T}`
  * means task T DEPENDS ON task D, so D must reach status "completed" before T is
  * unblocked. (relation name source_verb_target = task_depends_on_task ⇒ child is
  * the source/dependent, parent is the target/prerequisite; config display_name
  * "depends on task".)
+ *
+ * Readiness ALSO honors `task_gated_by_item` gates (FGAP-061 NOW slice): a
+ * `task_gated_by_item` edge `{parent: T, child: G}` means task T is GATED BY
+ * item G (the gate target, of any kind — gap/decision/feature/task/…), so G must
+ * reach the "complete" bucket before T's gate releases. A planned task with any
+ * gate target NOT in the "complete" bucket is reported in `blocked` (the target
+ * id present in `blockedBy`, unioned with unsatisfied dep-parents) and excluded
+ * from `nextActions`; a gate target reaching "complete" releases the gate. Gate
+ * satisfaction is `bucket(target) === "complete"` via the same status-vocabulary
+ * the status-consistency invariant engine uses — kind-general, no per-kind
+ * special-casing (gap→closed, decision→enacted, feature→complete, task→completed
+ * all bucket to "complete"). A dangling gate target (id resolves to no item) is
+ * treated as satisfied/non-blocking, mirroring the dangling-dep guard.
+ *
+ * Scope is strictly the literal relation_type `task_gated_by_item`:
+ * `decision_gated_by_item` and other non-task `*_gated_by_item` edges are inert
+ * here (currentState buckets only tasks). A gate target in a terminal-abandoned
+ * status (wontfix/superseded/cancelled — buckets to "unknown", NOT "complete")
+ * keeps the gated task blocked under the `=== "complete"` rule; promoting such
+ * states to gate-releasing, and config-driven generalization to all gate
+ * relation kinds, is the FEAT-004 refinement boundary, out of scope here.
+ */
+/**
+ * Render a `next_ranked` entry's `reason_template`, substituting `{token}`
+ * occurrences from `tokens` (every value stringified). Tokens absent from the
+ * map are left literal. An undefined template yields the empty string — the
+ * deriver carries no kind-coupled reason default; the stock registry declares
+ * the templates that reproduce the canonical reason strings.
  */
+function renderReasonTemplate(template, tokens) {
+    if (template === undefined)
+        return "";
+    return template.replace(/\{(\w+)\}/g, (match, key) => {
+        const v = tokens[key];
+        return v !== undefined ? v : match;
+    });
+}
 export function currentState(cwd) {
     // Tolerate any substrate-read failure (no .project, malformed config, etc.)
     // by collapsing to the empty state — this is a pure read surface.
@@ -559,12 +597,22 @@ export function currentState(cwd) {
     // a raw item.status string to its StatusBucket, defaulting to "unknown".
     const vocab = resolveStatusVocabulary(cwd);
     const bucket = (item) => vocab[String(item.status)] ?? "unknown";
-    // ── inFlight: tasks-block items bucketing to in_progress ───────────────────
+    // Resolve the config-declared derivation registry (TASK-020 / FGAP-017). When
+    // it is ABSENT, every coupling below is unconfigured, so the function returns
+    // the truthful "state-derivation not configured" signal — a state distinct
+    // from a configured-but-empty substrate (which derives normally to
+    // `focus: "no active focus."` + empty arrays). All 16 couplings below read
+    // `sd.*`; no kind / relation / rank / status / head-size literal remains.
+    const sd = resolveStateDerivation(cwd);
+    if (sd === null) {
+        return { focus: "state-derivation not configured", inFlight: [], nextActions: [], blocked: [], milestones: [] };
+    }
+    // ── inFlight: items of an `in_flight.kinds` block bucketing to in_flight.bucket ─
     const inFlight = [];
     for (const loc of index.byRefname.values()) {
-        if (loc.block !== "tasks")
+        if (!sd.in_flight.kinds.includes(loc.block))
             continue;
-        if (bucket(loc.item) !== "in_progress")
+        if (bucket(loc.item) !== sd.in_flight.bucket)
             continue;
         inFlight.push({
             id: loc.id,
@@ -572,108 +620,207 @@ export function currentState(cwd) {
             description: typeof loc.item.description === "string" ? loc.item.description : "",
         });
     }
-    // Task dependency adjacency from task_depends_on_task edges: for task T,
-    // depParents(T) = parents of edges {parent, child:T}. T is unblocked iff
-    // every dep parent that resolves to a known item is completed (deps pointing
-    // at unknown ids are treated as satisfied — a dangling edge is a relations
-    // integrity concern surfaced by validateRelations, not a blocker here).
-    const isCompleted = (taskId) => {
-        const loc = index.byRefname.get(taskId);
+    // A target is complete when it resolves to a known item whose status buckets to
+    // "complete" — the SHARED status-vocab completeness notion (as TASK-065 left it,
+    // the same check the status-consistency invariant engine uses), kind-general and
+    // not a per-derivation literal.
+    const isCompleted = (itemId) => {
+        const loc = index.byRefname.get(itemId);
         return loc !== undefined && bucket(loc.item) === "complete";
     };
-    const depParentsOf = (taskId) => edges
-        .filter((e) => e.relation_type === "task_depends_on_task" && endpointKey(e.child) === taskId)
+    // Blocking-relation adjacency, driven by `sd.blocked_by.relation_types`. The
+    // two stock relations use OPPOSITE endpoint directions, preserved exactly:
+    //   • task_depends_on_task — DEPENDENCY direction: parents of edges whose CHILD
+    //     is the item (the prerequisites of the item).
+    //   • task_gated_by_item   — GATE direction: children of edges whose PARENT is
+    //     the item (the gate targets the item waits on).
+    // A relation present in the set with no known direction rule defaults to the
+    // DEPENDENCY direction (parent-of-edge-with-child=item). Which relations
+    // participate is gated on membership in `sd.blocked_by.relation_types`, so an
+    // empty/absent relation is simply not consulted.
+    // Partition the configured blocking relations into GATE-direction vs
+    // DEPENDENCY-direction by each relation's declared `role_direction` (FGAP-113),
+    // replacing the former single `task_gated_by_item` string literal:
+    //   • role_direction === "as_child" → GATE direction: the relation's PRIMARY
+    //     role (the gate) sits at edge.child and the waiting item at edge.parent, so
+    //     the item's gates are the CHILDREN of edges whose PARENT is the item.
+    //   • otherwise (as_parent OR unset) → DEPENDENCY direction: the item's
+    //     prerequisites are the PARENTS of edges whose CHILD is the item.
+    // For the stock set {task_depends_on_task (as_parent), task_gated_by_item
+    // (as_child)} this partition is identical to the pre-change literal split, so
+    // blocked / nextActions / blockedBy stay byte-identical; any *_gated_by_item
+    // sibling later added to blocked_by routes to the gate direction by
+    // construction (no literal to extend). A blocked_by relation the config does
+    // NOT register with a role_direction reads as the DEPENDENCY default.
+    const blockedByRels = new Set(sd.blocked_by.relation_types);
+    const roleDirection = new Map();
+    for (const rt of loadConfig(cwd)?.relation_types ?? []) {
+        if (rt.role_direction !== undefined)
+            roleDirection.set(rt.canonical_id, rt.role_direction);
+    }
+    const gateDirRels = new Set([...blockedByRels].filter((rt) => roleDirection.get(rt) === "as_child"));
+    const depDirRels = new Set([...blockedByRels].filter((rt) => roleDirection.get(rt) !== "as_child"));
+    const dependencyPredsOf = (itemId) => edges
+        .filter((e) => depDirRels.has(e.relation_type) && endpointKey(e.child) === itemId)
         .map((e) => endpointKey(e.parent));
-    const incompleteDeps = (taskId) => depParentsOf(taskId).filter((dep) => index.byRefname.has(dep) && !isCompleted(dep));
-    // Collect all to-do (ready/queued) tasks once — drives both blocked + ready
-    // derivations. "todo" bucket = planned/queued work (raw status "planned"
-    // buckets to todo under STATUS_VOCABULARY_DEFAULTS).
+    const gatePredsOf = (itemId) => edges
+        .filter((e) => gateDirRels.has(e.relation_type) && endpointKey(e.parent) === itemId)
+        .map((e) => endpointKey(e.child));
+    // All preds (deps ∪ gates) in discovery order — used by the topo ordering below.
+    const allPredsOf = (itemId) => [...dependencyPredsOf(itemId), ...gatePredsOf(itemId)];
+    const incompletePreds = (itemId) => dependencyPredsOf(itemId).filter((dep) => index.byRefname.has(dep) && !isCompleted(dep));
+    const unsatisfiedGates = (itemId) => gatePredsOf(itemId).filter((target) => index.byRefname.has(target) && !isCompleted(target));
+    // The "planned tasks" set is the next_ranked entry that has NO rank_field (the
+    // stock tasks entry, topo-ordered). It drives both blocked + ready derivations.
+    const topoEntry = sd.next_ranked.find((e) => e.rank_field === undefined);
     const plannedTasks = [];
-    for (const loc of index.byRefname.values()) {
-        if (loc.block === "tasks" && bucket(loc.item) === "todo")
-            plannedTasks.push({ id: loc.id, loc });
+    if (topoEntry !== undefined) {
+        for (const loc of index.byRefname.values()) {
+            if (loc.block === topoEntry.kind && bucket(loc.item) === topoEntry.bucket) {
+                plannedTasks.push({ id: loc.id, loc });
+            }
+        }
     }
-    // ── blocked: planned tasks with at least one incomplete dep parent ─────────
+    // blockedBy(T) = UNION of T's unsatisfied dependency-direction preds and
+    // unsatisfied gate-direction targets, de-duplicated while preserving discovery
+    // order (deps first, then gates). With no gate relation configured / no gate
+    // edges present this collapses to the dependency-only set.
+    const blockersOf = (taskId) => {
+        const result = [];
+        const seen = new Set();
+        for (const blocker of [...incompletePreds(taskId), ...unsatisfiedGates(taskId)]) {
+            if (seen.has(blocker))
+                continue;
+            seen.add(blocker);
+            result.push(blocker);
+        }
+        return result;
+    };
+    // ── blocked: planned tasks with at least one unsatisfied dep or gate ─────────
     const blocked = [];
     const blockedIds = new Set();
     for (const { id, loc } of plannedTasks) {
-        const blockedBy = incompleteDeps(id);
+        const blockedBy = blockersOf(id);
         if (blockedBy.length > 0) {
             blocked.push({ id, block: loc.block, blockedBy });
             blockedIds.add(id);
         }
     }
     // ── nextActions (atomic-next, ranked) ──────────────────────────────────────
+    // Iterate `sd.next_ranked` IN ARRAY ORDER — array order IS the cross-kind push
+    // order (stock: topo-ordered tasks, then priority-ranked issues, then
+    // priority-ranked gaps).
     const nextActions = [];
-    // 1. Open framework-gaps (gaps bucketing to todo — raw status "identified"
-    //    buckets to todo under STATUS_VOCABULARY_DEFAULTS), ranked
-    //    P0 > P1 > P2 > P3 (missing priority sorts last) then by id.
-    const priorityRank = { P0: 0, P1: 1, P2: 2, P3: 3 };
-    const openGaps = [];
-    for (const loc of index.byRefname.values()) {
-        if (loc.block !== "framework-gaps")
-            continue;
-        if (bucket(loc.item) !== "todo")
-            continue;
-        openGaps.push({ id: loc.id, priority: typeof loc.item.priority === "string" ? loc.item.priority : undefined });
-    }
-    openGaps.sort((a, b) => {
-        const ra = a.priority !== undefined ? (priorityRank[a.priority] ?? 99) : 99;
-        const rb = b.priority !== undefined ? (priorityRank[b.priority] ?? 99) : 99;
-        if (ra !== rb)
-            return ra - rb;
-        return a.id.localeCompare(b.id);
-    });
-    for (const g of openGaps) {
-        nextActions.push({
-            id: g.id,
-            kind: "framework-gap",
-            ...(g.priority !== undefined ? { priority: g.priority } : {}),
-            reason: `open gap (priority ${g.priority ?? "unset"})`,
-        });
+    for (const entry of sd.next_ranked) {
+        if (entry.rank_field !== undefined) {
+            // Field-ranked entry (stock: framework-gaps by `priority`). Select items of
+            // `entry.kind` at `entry.bucket`, rank by index in `entry.rank_order` (value
+            // not listed → large sentinel 99) then by id.
+            const rankField = entry.rank_field;
+            const rankIndex = {};
+            (entry.rank_order ?? []).forEach((v, i) => {
+                rankIndex[v] = i;
+            });
+            const selected = [];
+            for (const loc of index.byRefname.values()) {
+                if (loc.block !== entry.kind)
+                    continue;
+                if (bucket(loc.item) !== entry.bucket)
+                    continue;
+                const raw = loc.item[rankField];
+                selected.push({ id: loc.id, value: typeof raw === "string" ? raw : undefined });
+            }
+            selected.sort((a, b) => {
+                const ra = a.value !== undefined ? (rankIndex[a.value] ?? 99) : 99;
+                const rb = b.value !== undefined ? (rankIndex[b.value] ?? 99) : 99;
+                if (ra !== rb)
+                    return ra - rb;
+                return a.id.localeCompare(b.id);
+            });
+            for (const s of selected) {
+                nextActions.push({
+                    id: s.id,
+                    kind: entry.label,
+                    ...(s.value !== undefined ? { [rankField]: s.value } : {}),
+                    reason: renderReasonTemplate(entry.reason_template, { rank_value: s.value ?? "unset", id: s.id }),
+                });
+            }
+        }
+        else {
+            // Topo-ordered entry (stock: tasks). Ready = planned items NOT in `blocked`,
+            // ordered via topoSort over the planned nodes with preds = dependency preds
+            // ∪ gate targets. topoSort only counts edges between graph nodes, so preds
+            // outside the planned set (completed / non-task) don't gate the ordering.
+            const { order } = topoSort(plannedTasks, (t) => t.id, (t) => allPredsOf(t.id));
+            for (const id of order) {
+                if (blockedIds.has(id))
+                    continue;
+                nextActions.push({ id, kind: entry.label, reason: renderReasonTemplate(entry.reason_template, { id }) });
+            }
+        }
     }
-    // 2. Ready tasks: planned tasks NOT in `blocked`, ordered via topoSort over
-    //    the planned-task nodes with deps = their task_depends_on_task parents.
-    //    topoSort only counts edges between nodes present in the graph, so deps
-    //    pointing outside the planned set (e.g. already-completed prerequisites)
-    //    don't gate the ordering — we then filter the resulting order to the
-    //    ready (unblocked + planned) subset.
-    const { order } = topoSort(plannedTasks, (t) => t.id, (t) => depParentsOf(t.id));
-    for (const id of order) {
-        if (blockedIds.has(id))
-            continue;
-        nextActions.push({ id, kind: "task", reason: "unblocked planned task" });
+    // Cap nextActions at the config-declared scannable head — derivation can
+    // surface a long backlog; the head is the actionable slice for "what's next".
+    const cappedNextActions = nextActions.slice(0, sd.head_size);
+    // ── milestones: config-declared membership rollups ──────────────────────────
+    // For each `sd.rollups` entry, orientation is read from the membership
+    // relation's declared `role_direction` (FGAP-113): the CONTAINER (the rollup
+    // item itself) sits at the PRIMARY endpoint, its MEMBERS at the COUNTER
+    // endpoint. `phase_positioned_in_milestone` is `as_child` (container=milestone
+    // at edge.child, member=phase at edge.parent), so `primaryEndpoint`===child /
+    // `counterEndpoint`===parent reproduces the prior filter-child / map-parent
+    // selection exactly. A membership relation the config does not register with a
+    // `role_direction` defaults to `as_child` (the pre-FGAP-113 container=child
+    // convention). The rollup emits `complete_status` when ≥1 member exists and
+    // every member id resolves to a known item bucketing to complete; else
+    // `incomplete_status` (covering no-members + any-incomplete). Every comparison
+    // routes through bucket() — no raw status literal.
+    const milestones = [];
+    for (const entry of sd.rollups) {
+        const dir = roleDirection.get(entry.membership_relation) ?? "as_child";
+        for (const loc of index.byRefname.values()) {
+            if (loc.block !== entry.kind)
+                continue;
+            const memberIds = edges
+                .filter((e) => e.relation_type === entry.membership_relation && endpointKey(primaryEndpoint(e, dir)) === loc.id)
+                .map((e) => endpointKey(counterEndpoint(e, dir)));
+            const phaseCount = memberIds.length;
+            const allComplete = memberIds.every((memberId) => isCompleted(memberId));
+            const reached = phaseCount >= 1 && allComplete;
+            milestones.push({
+                id: loc.id,
+                status: reached ? entry.complete_status : entry.incomplete_status,
+                phaseCount,
+            });
+        }
     }
-    // Cap nextActions at a scannable head (first 15) — derivation can surface a
-    // long backlog; the head is the actionable slice for "what's next".
-    const NEXT_ACTIONS_CAP = 15;
-    const cappedNextActions = nextActions.slice(0, NEXT_ACTIONS_CAP);
+    milestones.sort((a, b) => a.id.localeCompare(b.id));
     // ── focus: single derived string ───────────────────────────────────────────
     let focus;
     if (inFlight.length > 0) {
         focus = `in-flight: ${inFlight.map((t) => t.id).join(", ")}`;
     }
     else {
-        // Fall back to a phase bucketing to in_progress (phase.json phases[]
-        // array-block).
-        let inProgressPhase = null;
+        // Fall back to the first item of `focus_fallback.kind` bucketing to
+        // `focus_fallback.bucket` (stock: an in-progress phase).
+        let fallbackItem = null;
         for (const loc of index.byRefname.values()) {
-            if (loc.block !== "phase")
+            if (loc.block !== sd.focus_fallback.kind)
                 continue;
-            if (bucket(loc.item) !== "in_progress")
+            if (bucket(loc.item) !== sd.focus_fallback.bucket)
                 continue;
-            inProgressPhase = { id: loc.id, name: typeof loc.item.name === "string" ? loc.item.name : undefined };
+            fallbackItem = { id: loc.id, name: typeof loc.item.name === "string" ? loc.item.name : undefined };
             break;
         }
-        if (inProgressPhase !== null) {
-            const label = inProgressPhase.name ? `${inProgressPhase.id} (${inProgressPhase.name})` : inProgressPhase.id;
-            focus = `phase: ${label}`;
+        if (fallbackItem !== null) {
+            const label = fallbackItem.name ? `${fallbackItem.id} (${fallbackItem.name})` : fallbackItem.id;
+            focus = `${sd.focus_fallback.kind}: ${label}`;
         }
         else {
             focus = "no active focus.";
         }
     }
-    return { focus, inFlight, nextActions: cappedNextActions, blocked };
+    return { focus, inFlight, nextActions: cappedNextActions, blocked, milestones };
 }
 // discoverArrayKey lives in read-element.ts (the lowest pure layer) and is
 // imported above — ONE copy of the single-top-level-array heuristic shared by
@@ -1034,22 +1181,31 @@ export function resolveItemsByIds(cwd, ids) {
 }
 // ── Relation porcelain (selector → structured EdgeEndpoint → raw append) ─────
 /**
- * Load + JSON-parse a foreign substrate dir's config.json WITHOUT pointer
- * resolution or AJV validation — best-effort, returns null on absence/parse
- * failure. Used only to feed `expectedBlockForId`'s prefix invariant when
- * indexing a foreign substrate in the porcelain; the foreign substrate's own
- * write path already AJV-validated its config, so a re-validate here would only
- * add a failure mode to a read.
+ * Load a foreign substrate dir's config.json PREFERRING the migration-aware
+ * loader (`loadConfigForDir`: migrate-then-validate) so this reader sees the
+ * SAME config shape `loadConfig` sees once a shape-changing config migration
+ * exists (no split-brain read of the same file). Best-effort in two tiers:
+ * when the migration-aware load fails (unresolvable version, invalid), fall
+ * back to the prior raw parse — the consumer is `expectedBlockForId`'s prefix
+ * invariant, which is better fed an unvalidated `block_kinds` than none (a
+ * null config would silently disable the invariant and let a mis-filed
+ * foreign id resolve instead of degrading). Absent or unparsable → null,
+ * exactly the prior contract.
  */
 function loadConfigForDirBestEffort(substrateDir) {
     const p = path.join(substrateDir, "config.json");
     if (!fs.existsSync(p))
         return null;
     try {
-        return JSON.parse(fs.readFileSync(p, "utf-8"));
+        return loadConfigForDir(substrateDir);
     }
     catch {
-        return null;
+        try {
+            return JSON.parse(fs.readFileSync(p, "utf-8"));
+        }
+        catch {
+            return null;
+        }
     }
 }
 /**
@@ -1134,24 +1290,180 @@ function edgeIdentityKey(edge) {
     return `${endpointIdentity(edge.parent)} ${endpointIdentity(edge.child)} ${edge.relation_type}`;
 }
 /**
- * Friendly-selector relation append (Cycle 5 porcelain). Resolves `parent` /
- * `child` STRING selectors to structured `EdgeEndpoint`s via
- * `resolveRelationSelector`, then delegates to the raw `appendRelation` plumbing
- * (atomic, AJV-validated, exact-duplicate no-op — same deferred-integrity
- * semantics). Keeps the string param surface its callers (the append-relation
- * Pi tool + the orchestrator CLI) already expose.
+ * Shared edge-registry validator (TASK-062). The single source of edge
+ * registration + endpoint-kind semantics, invoked BOTH at write time (the
+ * `appendRelationByRef` / `appendRelationsByRef` porcelain, so a bad edge throws
+ * before the raw write) AND post-hoc in {@link validateContext} (so write-time
+ * and validate-time verdicts are guaranteed identical).
+ *
+ * Returns an ARRAY of human-readable error messages — empty when the edge is
+ * acceptable. Each message is byte-identical to the wording `validateContext`
+ * historically emitted inline, so the validate-time issue stream is unchanged;
+ * the write path joins the array into the thrown Error message.
+ *
+ * Checks (registration + source/target-kind ONLY — NO `category` check; the
+ * relation_type `category` attribute has no per-edge referent anywhere in code):
+ *  - (a) `edge.relation_type` MUST be registered in `config.relation_types[]`
+ *        (matched by `canonical_id`). Unregistered → the registration message;
+ *        when unregistered the kind check is short-circuited (no rt to read).
+ *  - (b) PRESENCE-GATED source/target-kind membership: a relation_type with
+ *        NEITHER `source_kinds` NOR `target_kinds` is unchecked (mirrors the
+ *        `if (!rt.source_kinds && !rt.target_kinds) continue;` gate). When a set
+ *        is present, the resolved endpoint block (via `resolve(...).loc.block`)
+ *        MUST be in it, honoring the `"*"` wildcard. A lens_bin / dangling /
+ *        unregistered endpoint carries no `loc` and is skipped for the kind
+ *        check (endpoint-resolution failures are validateContext's own surface,
+ *        not this helper's).
+ *
+ * `resolve` is the caller-supplied endpoint resolver (the same pass-bound
+ * `resolveRef` closure validateContext builds; the write path builds a fresh one
+ * over a freshly-built active index).
+ */
+export function validateEdgeAgainstRegistry(edge, config, resolve) {
+    const errors = [];
+    const parentKey = endpointKey(edge.parent);
+    const childKey = endpointKey(edge.child);
+    const rt = (config.relation_types ?? []).find((r) => r.canonical_id === edge.relation_type);
+    if (!rt) {
+        errors.push(`Edge relation_type '${edge.relation_type}' is not registered in config.relation_types`);
+        // Short-circuit: with no registered relation_type there is no source/target
+        // metadata to gate on (mirrors validateContext's `if (!rt) continue;`).
+        return errors;
+    }
+    // Presence gate — neither set declared → endpoint kinds unchecked.
+    if (!rt.source_kinds && !rt.target_kinds)
+        return errors;
+    const parentLoc = resolve(edge.parent).loc;
+    const childLoc = resolve(edge.child).loc;
+    if (parentLoc && rt.source_kinds && !(rt.source_kinds.includes("*") || rt.source_kinds.includes(parentLoc.block))) {
+        errors.push(`Edge ${parentKey} -> ${childKey}: source kind '${parentLoc.block}' not in source_kinds [${rt.source_kinds.join(", ")}] for relation_type '${edge.relation_type}'`);
+    }
+    if (childLoc && rt.target_kinds && !(rt.target_kinds.includes("*") || rt.target_kinds.includes(childLoc.block))) {
+        errors.push(`Edge ${parentKey} -> ${childKey}: target kind '${childLoc.block}' not in target_kinds [${rt.target_kinds.join(", ")}] for relation_type '${edge.relation_type}'`);
+    }
+    return errors;
+}
+/**
+ * Build the per-call edge-validation resolver for the WRITE-TIME porcelain — a
+ * `resolveRef` closure bound to a freshly-built active index + a fresh foreign
+ * cache for this write, plus the loaded config. Mirrors the pass-bound resolver
+ * validateContext constructs, so the two paths resolve endpoints identically.
+ * Returns `null` when no config is present (a pre-bootstrap substrate has no
+ * relation_types registry to validate against → write-time check is a no-op,
+ * matching validateContext's `if (config)` gate).
+ */
+function buildWriteTimeEdgeValidator(cwd) {
+    const config = loadConfig(cwd);
+    if (!config)
+        return null;
+    const activeIndex = buildIdIndex(cwd);
+    const foreignCache = new Map();
+    const resolve = (ref) => resolveRef(cwd, ref, { activeIndex, foreignCache });
+    return { config, resolve };
+}
+/**
+ * Single-edge write-time gate (TASK-062): build the validator for `cwd` and
+ * THROW if `edge` fails the shared registry check. A no-op when no config is
+ * present (pre-bootstrap substrate). The thrown message names the offending
+ * endpoint kind / relation_type / expected kinds (the helper's wording).
+ */
+function assertEdgeValidForWrite(cwd, edge) {
+    const validator = buildWriteTimeEdgeValidator(cwd);
+    if (!validator)
+        return;
+    const edgeErrors = validateEdgeAgainstRegistry(edge, validator.config, validator.resolve);
+    if (edgeErrors.length > 0) {
+        throw new Error(`Edge rejected at write time (invalid relation_type / endpoint kind): ${edgeErrors.join("; ")}`);
+    }
+}
+/**
+ * Whether a role-bearing relation is orientation-AMBIGUOUS: its `source_kinds`
+ * and `target_kinds` overlap (a shared kind, or either side unconstrained / the
+ * `"*"` wildcard), so a bare `{parent, child}` append cannot be reliably oriented
+ * from the endpoint kinds alone. Disjoint-kind relations are self-orienting — the
+ * `validateEdgeAgainstRegistry` source/target-kind gate already rejects an
+ * inversion — so a bare append of them stays allowed.
+ */
+function relationKindsOverlap(rt) {
+    const s = rt?.source_kinds;
+    const t = rt?.target_kinds;
+    if (!s || !t)
+        return true; // an unconstrained endpoint is universal → overlaps everything
+    if (s.includes("*") || t.includes("*"))
+        return true;
+    return s.some((k) => t.includes(k));
+}
+/**
+ * Resolve a {@link RelationAppendInput} (raw `{parent,child}` OR role-typed
+ * `{primary,counter}`) to the canonical `{parent, child}` STRING selectors the raw
+ * plumbing consumes, applying the FGAP-113 write-orientation rules:
+ *  - the raw and role-typed pairs are mutually exclusive; exactly one complete
+ *    pair must be supplied.
+ *  - the role-typed form maps `primary`/`counter` → `parent`/`child` via the
+ *    relation's declared `role_direction`; it throws when the relation declares no
+ *    `role_direction` (there is no primary/counter role to map).
+ *  - a bare `{parent,child}` append of a role-BEARING relation that is
+ *    orientation-ambiguous (same-kind / wildcard endpoints) is REJECTED, directing
+ *    the author to `--primary`/`--counter`. The porcelain never guesses or swaps.
+ *  - a bare append of a role-less relation, or of a role-bearing DISJOINT-kind
+ *    relation (self-orienting via the kind gate), passes through unchanged.
+ */
+function orientAppendInput(config, rel) {
+    const hasRole = rel.primary !== undefined || rel.counter !== undefined;
+    const hasRaw = rel.parent !== undefined || rel.child !== undefined;
+    if (hasRole && hasRaw) {
+        throw new Error(`Relation append for '${rel.relation_type}': --primary/--counter and --parent/--child are mutually exclusive; supply exactly one orientation pair.`);
+    }
+    const rt = (config?.relation_types ?? []).find((r) => r.canonical_id === rel.relation_type);
+    const roleDir = rt?.role_direction;
+    const ordinalPart = rel.ordinal !== undefined ? { ordinal: rel.ordinal } : {};
+    if (hasRole) {
+        if (rel.primary === undefined || rel.counter === undefined) {
+            throw new Error(`Relation append for '${rel.relation_type}': the role-typed form needs BOTH --primary and --counter.`);
+        }
+        if (roleDir === undefined) {
+            throw new Error(`Relation '${rel.relation_type}' declares no role_direction, so it has no primary/counter role to map — author it with --parent/--child.`);
+        }
+        const parent = roleDir === "as_parent" ? rel.primary : rel.counter;
+        const child = roleDir === "as_parent" ? rel.counter : rel.primary;
+        return { parent, child, relation_type: rel.relation_type, ...ordinalPart };
+    }
+    if (rel.parent === undefined || rel.child === undefined) {
+        throw new Error(`Relation append for '${rel.relation_type}': supply either --parent and --child, or --primary and --counter.`);
+    }
+    if (roleDir !== undefined && relationKindsOverlap(rt)) {
+        throw new Error(`Relation '${rel.relation_type}' carries a declared role_direction and is orientation-ambiguous (its ` +
+            `source and target kinds overlap), so a bare --parent/--child append cannot be reliably oriented. Re-issue ` +
+            `with --primary/--counter (primary = the endpoint holding the relation's semantic role, stored at edge.${roleDir === "as_parent" ? "parent" : "child"}).`);
+    }
+    return { parent: rel.parent, child: rel.child, relation_type: rel.relation_type, ...ordinalPart };
+}
+/**
+ * Friendly-selector relation append (Cycle 5 porcelain). Accepts EITHER raw
+ * `{parent, child}` selectors OR the role-typed `{primary, counter}` form
+ * (FGAP-113), resolves the (possibly role-mapped) STRING selectors to structured
+ * `EdgeEndpoint`s via `resolveRelationSelector`, then delegates to the raw
+ * `appendRelation` plumbing (atomic, AJV-validated, exact-duplicate no-op — same
+ * deferred-integrity semantics). Keeps the string param surface its callers (the
+ * append-relation Pi tool + the orchestrator CLI) already expose.
  *
  * Returns `{ appended, edge }` where `edge` is the RESOLVED structured edge
  * actually written (so callers can report / dry-run-validate the structured
  * form).
  */
 export function appendRelationByRef(cwd, rel, ctx, opts) {
+    const oriented = orientAppendInput(loadConfig(cwd), rel);
     const edge = {
-        parent: resolveRelationSelector(cwd, rel.parent),
-        child: resolveRelationSelector(cwd, rel.child),
-        relation_type: rel.relation_type,
-        ...(rel.ordinal !== undefined ? { ordinal: rel.ordinal } : {}),
+        parent: resolveRelationSelector(cwd, oriented.parent),
+        child: resolveRelationSelector(cwd, oriented.child),
+        relation_type: oriented.relation_type,
+        ...(oriented.ordinal !== undefined ? { ordinal: oriented.ordinal } : {}),
     };
+    // Write-time edge-registry gate (TASK-062): reject an unregistered
+    // relation_type or a source/target-kind-violating endpoint BEFORE any write
+    // (dryRun included — preview must surface the same rejection). The shared
+    // helper guarantees this verdict is identical to validateContext's.
+    assertEdgeValidForWrite(cwd, edge);
     if (opts?.dryRun) {
         // Preview parity: run the SAME validation the write path applies (the
         // prospective Edge[] against the whole relations schema — what
@@ -1262,12 +1574,33 @@ export function replaceRelationByRef(cwd, rels, ctx, opts) {
  * `validateContext`).
  */
 export function appendRelationsByRef(cwd, edges, ctx, opts) {
-    const resolved = edges.map((rel) => ({
-        parent: resolveRelationSelector(cwd, rel.parent),
-        child: resolveRelationSelector(cwd, rel.child),
-        relation_type: rel.relation_type,
-        ...(rel.ordinal !== undefined ? { ordinal: rel.ordinal } : {}),
-    }));
+    // Orient every input once against the loaded config (FGAP-113): a role-typed
+    // {primary,counter} edge maps to parent/child via role_direction; a bare
+    // {parent,child} append of an orientation-ambiguous role-bearing relation is
+    // rejected here (before any write), directing the author to --primary/--counter.
+    const config = loadConfig(cwd);
+    const resolved = edges.map((rel) => {
+        const oriented = orientAppendInput(config, rel);
+        return {
+            parent: resolveRelationSelector(cwd, oriented.parent),
+            child: resolveRelationSelector(cwd, oriented.child),
+            relation_type: oriented.relation_type,
+            ...(oriented.ordinal !== undefined ? { ordinal: oriented.ordinal } : {}),
+        };
+    });
+    // Write-time edge-registry gate (TASK-062): every resolved edge in the batch
+    // is checked BEFORE any write (dryRun included). Build the validator once for
+    // the batch (config + active index built once) and reject if any edge fails —
+    // an all-or-nothing batch (no partial write past a bad edge).
+    const validator = buildWriteTimeEdgeValidator(cwd);
+    if (validator) {
+        for (const edge of resolved) {
+            const edgeErrors = validateEdgeAgainstRegistry(edge, validator.config, validator.resolve);
+            if (edgeErrors.length > 0) {
+                throw new Error(`Edge rejected at write time (invalid relation_type / endpoint kind): ${edgeErrors.join("; ")}`);
+            }
+        }
+    }
     if (opts?.dryRun) {
         // Preview parity: replay the bulk dedup the raw appendRelations applies —
         // skip an edge whose identity is already on disk OR earlier in THIS batch
@@ -1553,7 +1886,6 @@ export function validateContext(cwd) {
     // false-pass a zero-edge substrate. The edge-integrity loop below is a
     // no-op on empty relations, so it needs no separate guard.
     if (config) {
-        const registeredRelTypes = new Set((config.relation_types ?? []).map((rt) => rt.canonical_id));
         // Per-pass foreign-index cache (Constraint 3): N foreign edges into the same
         // registered substrate build that substrate's index ONCE within this pass.
         const foreignCache = new Map();
@@ -1607,60 +1939,48 @@ export function validateContext(cwd) {
                     code: "edge_endpoint_dangling",
                 });
             }
-            if (!registeredRelTypes.has(edge.relation_type)) {
-                issues.push({
-                    severity: "error",
-                    message: `Edge relation_type '${edge.relation_type}' is not registered in config.relation_types`,
-                    block: "relations",
-                    field: `${parentKey}->${childKey}`,
-                });
-            }
         }
-        // ── Edge endpoint-kind check (FGAP-086, DEC-0037) ─────────────────────
-        // Presence-gated: a relation_type with neither source_kinds nor
-        // target_kinds is unchecked, so the frozen .project substrate (whose
-        // relation_types carry no endpoint metadata) is not retroactively failed.
-        // When metadata is present, an edge endpoint whose resolved block is not in
-        // the declared kind set (and the set is not the "*" wildcard) is an error.
-        // loc.block is the data-file basename; the source/target_kinds name
-        // block_kind canonical_ids — the loc.block==canonical_id assumption is
-        // inherited from the invariant loop below (~:1140), where inv.block (a
-        // canonical_id) is matched directly against loc.block.
+        // ── Edge registration + endpoint-kind check (FGAP-086, DEC-0037; TASK-062
+        // factored into the shared validateEdgeAgainstRegistry helper so the
+        // write-time porcelain and this validate-time loop reach an IDENTICAL
+        // verdict). The helper performs (a) relation_type-registration and
+        // (b) PRESENCE-GATED source/target-kind membership ("*" wildcard honored);
+        // a relation_type with neither kind set is unchecked (the frozen .project
+        // substrate, whose relation_types carry no endpoint metadata, is not
+        // retroactively failed). Its returned messages are byte-identical to the
+        // wording this loop historically emitted inline (registration message +
+        // source/target kind messages), each mapped to the same issue shape
+        // (severity error, block "relations", field parent->child, no code).
+        // Order discipline (TASK-062): context-validate prints issues[], so the
+        // emission order is a UX surface and must match the pre-refactor two-pass
+        // shape — ALL relation_type-registration issues across every edge first,
+        // THEN ALL source/target-kind issues across every edge (class-grouped, not
+        // interleaved per edge). The shared helper returns both classes per edge;
+        // we collect once then partition by message text (registration messages
+        // carry "is not registered"; kind messages carry "source kind"/"target
+        // kind"). Issue set/count/wording/severity and the registration
+        // short-circuit are unchanged — this is order-only.
+        const registrationIssues = [];
+        const kindIssues = [];
         for (const edge of relations) {
-            const rt = config.relation_types?.find((r) => r.canonical_id === edge.relation_type);
-            if (!rt)
-                continue; // unregistered relation_type already reported above
-            if (!rt.source_kinds && !rt.target_kinds)
-                continue; // metadata absent → unchecked
             const parentKey = endpointKey(edge.parent);
             const childKey = endpointKey(edge.child);
-            // Use the resolved location for item endpoints (active OR foreign), so a
-            // foreign item's block is kind-checked against source/target_kinds too. A
-            // lens_bin endpoint (endpointKind:"lens_bin") carries no loc and is skipped
-            // — it never routes through item-block resolution.
-            const parentRes = resolve(edge.parent);
-            const childRes = resolve(edge.child);
-            const parentLoc = parentRes.loc;
-            const childLoc = childRes.loc;
-            if (parentLoc &&
-                rt.source_kinds &&
-                !(rt.source_kinds.includes("*") || rt.source_kinds.includes(parentLoc.block))) {
-                issues.push({
+            for (const message of validateEdgeAgainstRegistry(edge, config, resolve)) {
+                const issue = {
                     severity: "error",
-                    message: `Edge ${parentKey} -> ${childKey}: source kind '${parentLoc.block}' not in source_kinds [${rt.source_kinds.join(", ")}] for relation_type '${edge.relation_type}'`,
+                    message,
                     block: "relations",
                     field: `${parentKey}->${childKey}`,
-                });
-            }
-            if (childLoc && rt.target_kinds && !(rt.target_kinds.includes("*") || rt.target_kinds.includes(childLoc.block))) {
-                issues.push({
-                    severity: "error",
-                    message: `Edge ${parentKey} -> ${childKey}: target kind '${childLoc.block}' not in target_kinds [${rt.target_kinds.join(", ")}] for relation_type '${edge.relation_type}'`,
-                    block: "relations",
-                    field: `${parentKey}->${childKey}`,
-                });
+                };
+                if (message.includes("is not registered")) {
+                    registrationIssues.push(issue);
+                }
+                else {
+                    kindIssues.push(issue);
+                }
             }
         }
+        issues.push(...registrationIssues, ...kindIssues);
         // Cycle detection — delegate to validateRelations. It performs its own
         // lens/hierarchy/relation_type resolution and emits several edge codes;
         // only its cycle diagnostics are merged here (the parent/child/relation_type
@@ -1864,6 +2184,59 @@ export function validateContext(cwd) {
             });
         }
     }
+    // ── Substrate-wide block schema-validity sweep ────────────────────────────
+    // The composed verdict must cover schema validity, not only edge/invariant
+    // integrity: invalidity introduced WITHOUT a write to the block (a schema
+    // resync, a hand edit, catalog drift) previously sat behind a clean verdict
+    // until the next write to that block failed. For every block that has BOTH a
+    // schema in <substrateDir>/schemas/ AND a block file, validate the whole
+    // block against its installed schema — migration-aware when the envelope is
+    // stamped (validateBlockWithMigrationForDir walks a lagging version through
+    // the registered chain), raw otherwise (the same helper: absent version ⇒
+    // straight validate). Every failure surfaces as an ERROR naming the block,
+    // the failing item id (resolved from the AJV instancePath), and the
+    // field/keyword. Guarded per block so one unreadable file cannot mask the
+    // rest of the sweep; pointer-less projects degrade gracefully (no sweep —
+    // there is no substrate to validate), matching validateContext's class rule.
+    {
+        const substrateDir = tryResolveContextDir(cwd);
+        const schemasDir = substrateDir ? path.join(substrateDir, "schemas") : null;
+        if (substrateDir && schemasDir && fs.existsSync(schemasDir)) {
+            const registry = getProjectMigrationRegistryForDir(substrateDir);
+            for (const schemaFile of fs.readdirSync(schemasDir).filter((f) => f.endsWith(".schema.json"))) {
+                const blockName = schemaFile.slice(0, -".schema.json".length);
+                const blockFile = path.join(substrateDir, `${blockName}.json`);
+                if (!fs.existsSync(blockFile))
+                    continue;
+                try {
+                    const blockData = JSON.parse(fs.readFileSync(blockFile, "utf-8"));
+                    validateBlockWithMigrationForDir(substrateDir, blockName, blockData, registry);
+                }
+                catch (err) {
+                    if (err instanceof ValidationError) {
+                        for (const e of err.errors) {
+                            const itemId = blockItemIdForInstancePath(cwd, blockName, e.instancePath);
+                            issues.push({
+                                severity: "error",
+                                message: `Block '${blockName}' fails its installed schema at ${e.instancePath || "(envelope)"}${itemId ? ` (item '${itemId}')` : ""}: ${e.keyword} ${e.message ?? ""}`.trimEnd(),
+                                block: blockName,
+                                ...(itemId !== undefined ? { field: itemId } : {}),
+                                code: "block_schema_invalid",
+                            });
+                        }
+                    }
+                    else {
+                        issues.push({
+                            severity: "error",
+                            message: `Block '${blockName}' failed schema-validity sweep: ${err instanceof Error ? err.message : String(err)}`,
+                            block: blockName,
+                            code: "block_schema_invalid",
+                        });
+                    }
+                }
+            }
+        }
+    }
     const errorCount = issues.filter((i) => i.severity === "error").length;
     const warningCount = issues.filter((i) => i.severity === "warning").length;
     return {
@@ -1871,6 +2244,31 @@ export function validateContext(cwd) {
         issues,
     };
 }
+/**
+ * Resolve the failing block item's `id` from an AJV `instancePath` of the form
+ * `/<arrayKey>/<index>[/...]` by re-reading the block file. Returns undefined
+ * for envelope-level paths or when the item carries no string id.
+ */
+function blockItemIdForInstancePath(cwd, blockName, instancePath) {
+    const m = /^\/([^/]+)\/(\d+)/.exec(instancePath);
+    if (!m)
+        return undefined;
+    try {
+        const substrateDir = resolveContextDir(cwd);
+        const data = JSON.parse(fs.readFileSync(path.join(substrateDir, `${blockName}.json`), "utf-8"));
+        const arr = data[m[1]];
+        if (!Array.isArray(arr))
+            return undefined;
+        const item = arr[Number(m[2])];
+        if (!item || typeof item !== "object")
+            return undefined;
+        const id = item.id;
+        return typeof id === "string" ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Gate task completion on verification. Reads the verification block to confirm
  * a passing verification entry exists, asserts a `verification_verifies_item`