@davidorex/pi-context 0.31.0 → 0.33.0

package/dist/context-sdk.js

@@ -7,20 +7,21 @@ import { execSync } from "node:child_process";
 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 { readBlock, readBlockForDir, resolveGitRefOrNull, updateItemInBlock } from "./block-api.js";
+import { computeFileBytesHash } from "./content-hash.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,80 @@ 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;
+    });
+}
+/**
+ * Rollup-aware completeness — the ONE truth model for "is this item complete"
+ * (FEAT-011 — FGAP-116). A kind declared in `state_derivation.rollups` is
+ * DERIVED-status: complete iff it has ≥1 member (via the rollup's membership
+ * relation, oriented by `role_direction`) and every member is complete under
+ * this same function (recursively rollup-aware; a `visiting` guard makes a
+ * membership cycle derive not-complete instead of recursing forever). Every
+ * other kind is complete iff its status buckets to "complete". SHARED by
+ * `currentState` (gate satisfaction + the milestones facet) and the
+ * `derived-status` invariant class in `validateContext`, so the derivation and
+ * the divergence detector cannot disagree.
  */
+export function derivedRollupComplete(index, edges, roleDirection, rollupByKind, bucketOf, itemId, visiting = new Set()) {
+    const loc = index.byRefname.get(itemId);
+    if (loc === undefined)
+        return false;
+    const entry = rollupByKind.get(loc.block);
+    if (entry === undefined)
+        return bucketOf(loc.item) === "complete";
+    if (visiting.has(itemId))
+        return false;
+    visiting.add(itemId);
+    const dir = roleDirection.get(entry.membership_relation) ?? "as_child";
+    const memberIds = edges
+        .filter((e) => e.relation_type === entry.membership_relation && endpointKey(primaryEndpoint(e, dir)) === itemId)
+        .map((e) => endpointKey(counterEndpoint(e, dir)));
+    return (memberIds.length >= 1 &&
+        memberIds.every((memberId) => derivedRollupComplete(index, edges, roleDirection, rollupByKind, bucketOf, memberId, visiting)));
+}
 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 +626,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 +649,223 @@ 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);
-        return loc !== undefined && bucket(loc.item) === "complete";
-    };
-    const depParentsOf = (taskId) => edges
-        .filter((e) => e.relation_type === "task_depends_on_task" && endpointKey(e.child) === taskId)
+    // Per-relation role_direction declarations (FGAP-113) — consulted by the
+    // rollup-aware completeness check below, the blocking partition, and the
+    // milestones rollup. Hoisted above isCompleted so all three read ONE map.
+    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);
+    }
+    // A target is complete when it resolves to a known item that IS complete under
+    // its kind's truth model (FEAT-011 criterion 1 — FGAP-116):
+    //   • a kind declared in `sd.rollups` is DERIVED-status — its stored status
+    //     field is canon-forbidden to author and may lag, so completeness is the
+    //     membership rollup itself (≥1 member, every member complete), recursively
+    //     rollup-aware for nested rollup kinds, with a visiting-set guard so a
+    //     membership cycle derives not-complete instead of recursing forever;
+    //   • every other kind keeps the SHARED status-vocab bucketing (as TASK-065
+    //     left it, the same check the status-consistency invariant engine uses),
+    //     byte-identical to the prior behavior.
+    // The milestones[] rollup below consumes THIS function for its reached
+    // verdict, so gate satisfaction and the reported milestone status agree by
+    // construction within a single read — the two can no longer split-brain. The
+    // derived-status invariant class evaluates the SAME shared helper, so
+    // validate-side divergence verdicts match the derivation too.
+    // Kind set + membership relation come from config (`sd.rollups` +
+    // role_direction); no kind / relation literal here (DEC-0025).
+    const rollupEntryByKind = new Map(sd.rollups.map((entry) => [entry.kind, entry]));
+    const isCompleted = (itemId) => derivedRollupComplete(index, edges, roleDirection, rollupEntryByKind, bucket, itemId);
+    // 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 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;
+            // The reached verdict IS the rollup-aware isCompleted — the same function
+            // gate satisfaction consults — so the reported milestone status and the
+            // gates it releases cannot diverge within this read (FEAT-011 criterion 1).
+            const reached = isCompleted(loc.id);
+            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 +1226,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 +1335,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.
+ */
+export 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 +1619,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
@@ -1471,6 +1849,264 @@ function matchesWhere(item, where) {
             return false;
     return true;
 }
+/**
+ * Evaluate every config-declared invariant (requires-edge, status-consistency,
+ * derived-status) against the given substrate state, returning the issue set.
+ * The ONE evaluation path shared by `validateContext` (read-side sweep) and
+ * the ops-layer write-time gate (delta-scoped surfacing/refusal of newly-
+ * introduced violations) — the two consumers cannot classify differently.
+ * Unknown invariant classes are skipped (forward-compat).
+ */
+export function evaluateConfigInvariants(cwd, config, index, relations) {
+    const issues = [];
+    // ── Config-declared invariants (DEC-0025: vocabulary-neutral) ─────────
+    // Replaces the two previously-hardcoded invariants (completed-task-has-
+    // verification, decision-cites-forcing-artifact). Every block / status /
+    // relation_type / direction literal comes from config.invariants[] DATA;
+    // this loop contains no vocabulary literal. Each requires-edge invariant:
+    // items in `block` matching `where` must occupy `direction`'s endpoint on
+    // ≥1 edge whose relation_type ∈ relation_types — else a diagnostic.
+    for (const inv of config.invariants ?? []) {
+        if (inv.class !== "requires-edge")
+            continue; // forward-compat: skip unknown classes
+        const relTypeSet = new Set(inv.relation_types);
+        const satisfied = new Set();
+        for (const edge of relations) {
+            if (!relTypeSet.has(edge.relation_type))
+                continue;
+            satisfied.add(inv.direction === "as_parent" ? endpointKey(edge.parent) : endpointKey(edge.child));
+        }
+        for (const loc of index.byRefname.values()) {
+            const id = loc.id;
+            if (loc.block !== inv.block)
+                continue;
+            if (!matchesWhere(loc.item, inv.where))
+                continue;
+            if (satisfied.has(id))
+                continue;
+            issues.push({
+                severity: inv.severity ?? "error",
+                message: (inv.message ?? `Item '{id}' in block '{block}' violates invariant '${inv.id}'`)
+                    .replaceAll("{id}", id)
+                    .replaceAll("{block}", inv.block),
+                block: inv.block,
+                field: `${id}.${inv.id}`,
+                code: inv.id,
+            });
+        }
+    }
+    // ── status-consistency invariants (DEC-0040 / FGAP-073) ──────────────
+    // Cross-block status drift: for each item in inv.block (optionally gated
+    // by when_bucket on the item's own status bucket), inspect edges whose
+    // relation_type ∈ inv.relation_types and whose inv.direction endpoint is
+    // the item; the OTHER endpoint is the target. Violation when the target's
+    // status bucket differs from require_target_bucket, or equals
+    // forbid_target_bucket. Vocabulary-free — every literal comes from `inv`
+    // or the config-resolved status vocabulary; no block/status/relation
+    // string is hardcoded. vocab resolved once, outside the loop.
+    const vocab = resolveStatusVocabulary(cwd);
+    const bucketOf = (item) => vocab[String(item.status)] ?? "unknown";
+    for (const inv of config.invariants ?? []) {
+        if (inv.class !== "status-consistency")
+            continue;
+        const relSet = new Set(inv.relation_types);
+        for (const loc of index.byRefname.values()) {
+            const id = loc.id;
+            if (loc.block !== inv.block)
+                continue;
+            if (inv.when_bucket && bucketOf(loc.item) !== inv.when_bucket)
+                continue;
+            for (const edge of relations) {
+                if (!relSet.has(edge.relation_type))
+                    continue;
+                const selfIsParent = inv.direction === "as_parent";
+                if ((selfIsParent ? endpointKey(edge.parent) : endpointKey(edge.child)) !== id)
+                    continue;
+                const otherId = selfIsParent ? endpointKey(edge.child) : endpointKey(edge.parent);
+                const otherLoc = index.byRefname.get(otherId);
+                if (!otherLoc)
+                    continue; // dangling endpoint handled by edge-integrity above
+                const otherBucket = bucketOf(otherLoc.item);
+                const violateRequire = inv.require_target_bucket !== undefined && otherBucket !== inv.require_target_bucket;
+                const violateForbid = inv.forbid_target_bucket !== undefined && otherBucket === inv.forbid_target_bucket;
+                if (violateRequire || violateForbid) {
+                    issues.push({
+                        severity: inv.severity ?? "error",
+                        message: (inv.message ?? `Item '{id}' (block '{block}') status-consistency '${inv.id}'`)
+                            .replaceAll("{id}", id)
+                            .replaceAll("{block}", inv.block),
+                        block: inv.block,
+                        field: `${id}.${inv.id}`,
+                        code: inv.id,
+                    });
+                }
+            }
+        }
+    }
+    // ── derived-status invariants (FEAT-011 — FGAP-116) ───────────────────
+    // For a rollup-declared kind (state_derivation.rollups), each item's
+    // STORED status must equal its DERIVED membership-rollup status —
+    // divergence in EITHER direction (stored behind or ahead of the
+    // derivation) is reported. Completeness comes from the SAME shared
+    // helper currentState's gate satisfaction uses (derivedRollupComplete),
+    // so validate-side verdicts match the derivation by construction. A
+    // declaration naming a block with no matching rollups entry is inert
+    // (the invariant has nothing to derive against). Vocabulary-free: kind,
+    // membership relation, and the status strings all come from config.
+    {
+        const sdInv = resolveStateDerivation(cwd);
+        const declared = (config.invariants ?? []).filter((inv) => inv.class === "derived-status");
+        if (sdInv !== null && declared.length > 0) {
+            const rollupByKind = new Map(sdInv.rollups.map((r) => [r.kind, r]));
+            const roleDir = new Map();
+            for (const rt of config.relation_types ?? []) {
+                if (rt.role_direction !== undefined)
+                    roleDir.set(rt.canonical_id, rt.role_direction);
+            }
+            for (const inv of declared) {
+                const entry = rollupByKind.get(inv.block);
+                if (entry === undefined)
+                    continue;
+                for (const loc of index.byRefname.values()) {
+                    if (loc.block !== inv.block)
+                        continue;
+                    const derived = derivedRollupComplete(index, relations, roleDir, rollupByKind, bucketOf, loc.id)
+                        ? entry.complete_status
+                        : entry.incomplete_status;
+                    const stored = String(loc.item.status);
+                    if (stored === derived)
+                        continue;
+                    issues.push({
+                        severity: inv.severity ?? "warning",
+                        message: (inv.message ??
+                            `Item '{id}' (block '{block}') stored status '{stored}' diverges from its derived rollup status '{derived}' (derived-status '${inv.id}')`)
+                            .replaceAll("{id}", loc.id)
+                            .replaceAll("{block}", inv.block)
+                            .replaceAll("{stored}", stored)
+                            .replaceAll("{derived}", derived),
+                        block: inv.block,
+                        field: `${loc.id}.${inv.id}`,
+                        code: inv.id,
+                    });
+                }
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Declared-baseline currency sweep (FEAT-011 criterion 6 — TASK-089), the ONE
+ * evaluation path shared by `validateContext` (flags) and `reconcileContext`
+ * (the complete-to-stale transition) — detector and repair cannot disagree.
+ * Field-driven and vocabulary-neutral: no block-name literals — any item
+ * carrying a `stale_conditions` array is condition-evaluable, and any
+ * array-of-object field entry carrying a `content_pin` beside a `path`/`file`
+ * is drift-checkable. Bare-string conditions are never machine-judged. Typed
+ * conditions are judged only on items whose status buckets `complete` (the
+ * transition's precondition); pin drift elsewhere degrades to the flag-only
+ * `anchor-drift` kind. Unstamped baselines (no `baseline_hash`/`baseline_sha`
+ * — e.g. the file/ref was unreadable at write) are never judged.
+ */
+export function evaluateStalenessCandidates(cwd, index) {
+    const out = [];
+    const ctxRoot = tryResolveContextDir(cwd);
+    if (ctxRoot === null)
+        return out;
+    const projectRoot = path.dirname(ctxRoot);
+    const idx = index ?? buildIdIndex(cwd);
+    const vocab = resolveStatusVocabulary(cwd);
+    const bucketOf = (item) => vocab[String(item.status)] ?? "unknown";
+    const substrateAbs = path.resolve(ctxRoot);
+    // Substrate-internal paths are living state, not groundable artifacts — the
+    // write choke never stamps them, and a hand-authored pin/baseline on one is
+    // never judged here (it would drift on every substrate write and flag forever).
+    const isSubstrateInternal = (rel) => {
+        const abs = path.resolve(projectRoot, rel);
+        return abs === substrateAbs || abs.startsWith(substrateAbs + path.sep);
+    };
+    const fileHashOrNull = (rel) => {
+        const abs = path.resolve(projectRoot, rel);
+        try {
+            if (!fs.statSync(abs).isFile())
+                return null;
+            return computeFileBytesHash(abs);
+        }
+        catch {
+            return null;
+        }
+    };
+    for (const loc of idx.byRefname.values()) {
+        const item = loc.item;
+        const hasConditions = Array.isArray(item.stale_conditions);
+        const completeBucket = bucketOf(item) === "complete";
+        const firedReasons = [];
+        if (hasConditions && completeBucket) {
+            for (const cond of item.stale_conditions) {
+                if (!cond || typeof cond !== "object" || Array.isArray(cond))
+                    continue; // bare strings stay human-only
+                const c = cond;
+                if (c.kind === "item-status" && typeof c.item === "string" && typeof c.bucket === "string") {
+                    const target = idx.byRefname.get(c.item);
+                    if (target !== undefined && bucketOf(target.item) === c.bucket) {
+                        firedReasons.push(`stale condition fired: item '${c.item}' bucketed '${c.bucket}'`);
+                    }
+                }
+                else if (c.kind === "file-changed" &&
+                    typeof c.path === "string" &&
+                    typeof c.baseline_hash === "string" &&
+                    !isSubstrateInternal(c.path)) {
+                    const now = fileHashOrNull(c.path);
+                    if (now === null) {
+                        firedReasons.push(`stale condition fired: file '${c.path}' is gone`);
+                    }
+                    else if (now !== c.baseline_hash) {
+                        firedReasons.push(`stale condition fired: file '${c.path}' changed from its baseline`);
+                    }
+                }
+                else if (c.kind === "revision-moved" && typeof c.ref === "string" && typeof c.baseline_sha === "string") {
+                    const now = resolveGitRefOrNull(projectRoot, c.ref);
+                    if (now !== null && now !== c.baseline_sha) {
+                        firedReasons.push(`stale condition fired: ref '${c.ref}' moved from '${c.baseline_sha.slice(0, 12)}'`);
+                    }
+                }
+            }
+        }
+        const driftReasons = [];
+        for (const [field, value] of Object.entries(item)) {
+            if (!Array.isArray(value))
+                continue;
+            for (const el of value) {
+                if (!el || typeof el !== "object" || Array.isArray(el))
+                    continue;
+                const rec = el;
+                if (typeof rec.content_pin !== "string")
+                    continue;
+                const rel = typeof rec.path === "string" ? rec.path : typeof rec.file === "string" ? rec.file : null;
+                if (rel === null || isSubstrateInternal(rel))
+                    continue;
+                const now = fileHashOrNull(rel);
+                if (now === null) {
+                    driftReasons.push(`pin drift: '${field}' entry file '${rel}' is gone`);
+                }
+                else if (now !== rec.content_pin) {
+                    driftReasons.push(`pin drift: '${field}' entry file '${rel}' changed since pinned`);
+                }
+            }
+        }
+        if (hasConditions && completeBucket && (firedReasons.length > 0 || driftReasons.length > 0)) {
+            out.push({
+                id: loc.id,
+                block: loc.block,
+                kind: "staleness-candidate",
+                reasons: [...firedReasons, ...driftReasons],
+            });
+        }
+        else if (driftReasons.length > 0) {
+            out.push({ id: loc.id, block: loc.block, kind: "anchor-drift", reasons: driftReasons });
+        }
+    }
+    return out;
+}
 /**
  * Validate cross-block referential integrity against the EDGE model
  * (DEC-0013: `relations.json` closure-table edges are THE reference surface).
@@ -1553,7 +2189,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 +2242,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
@@ -1687,90 +2310,11 @@ export function validateContext(cwd) {
             /* validateRelations is best-effort for cycle detection; a throw here
                must not mask the authoritative edge-integrity issues collected above. */
         }
-        // ── Config-declared invariants (DEC-0025: vocabulary-neutral) ─────────
-        // Replaces the two previously-hardcoded invariants (completed-task-has-
-        // verification, decision-cites-forcing-artifact). Every block / status /
-        // relation_type / direction literal comes from config.invariants[] DATA;
-        // this loop contains no vocabulary literal. Each requires-edge invariant:
-        // items in `block` matching `where` must occupy `direction`'s endpoint on
-        // ≥1 edge whose relation_type ∈ relation_types — else a diagnostic.
-        for (const inv of config.invariants ?? []) {
-            if (inv.class !== "requires-edge")
-                continue; // forward-compat: skip unknown classes
-            const relTypeSet = new Set(inv.relation_types);
-            const satisfied = new Set();
-            for (const edge of relations) {
-                if (!relTypeSet.has(edge.relation_type))
-                    continue;
-                satisfied.add(inv.direction === "as_parent" ? endpointKey(edge.parent) : endpointKey(edge.child));
-            }
-            for (const loc of index.byRefname.values()) {
-                const id = loc.id;
-                if (loc.block !== inv.block)
-                    continue;
-                if (!matchesWhere(loc.item, inv.where))
-                    continue;
-                if (satisfied.has(id))
-                    continue;
-                issues.push({
-                    severity: inv.severity ?? "error",
-                    message: (inv.message ?? `Item '{id}' in block '{block}' violates invariant '${inv.id}'`)
-                        .replaceAll("{id}", id)
-                        .replaceAll("{block}", inv.block),
-                    block: inv.block,
-                    field: `${id}.${inv.id}`,
-                    code: inv.id,
-                });
-            }
-        }
-        // ── status-consistency invariants (DEC-0040 / FGAP-073) ──────────────
-        // Cross-block status drift: for each item in inv.block (optionally gated
-        // by when_bucket on the item's own status bucket), inspect edges whose
-        // relation_type ∈ inv.relation_types and whose inv.direction endpoint is
-        // the item; the OTHER endpoint is the target. Violation when the target's
-        // status bucket differs from require_target_bucket, or equals
-        // forbid_target_bucket. Vocabulary-free — every literal comes from `inv`
-        // or the config-resolved status vocabulary; no block/status/relation
-        // string is hardcoded. vocab resolved once, outside the loop.
-        const vocab = resolveStatusVocabulary(cwd);
-        const bucketOf = (item) => vocab[String(item.status)] ?? "unknown";
-        for (const inv of config.invariants ?? []) {
-            if (inv.class !== "status-consistency")
-                continue;
-            const relSet = new Set(inv.relation_types);
-            for (const loc of index.byRefname.values()) {
-                const id = loc.id;
-                if (loc.block !== inv.block)
-                    continue;
-                if (inv.when_bucket && bucketOf(loc.item) !== inv.when_bucket)
-                    continue;
-                for (const edge of relations) {
-                    if (!relSet.has(edge.relation_type))
-                        continue;
-                    const selfIsParent = inv.direction === "as_parent";
-                    if ((selfIsParent ? endpointKey(edge.parent) : endpointKey(edge.child)) !== id)
-                        continue;
-                    const otherId = selfIsParent ? endpointKey(edge.child) : endpointKey(edge.parent);
-                    const otherLoc = index.byRefname.get(otherId);
-                    if (!otherLoc)
-                        continue; // dangling endpoint handled by edge-integrity above
-                    const otherBucket = bucketOf(otherLoc.item);
-                    const violateRequire = inv.require_target_bucket !== undefined && otherBucket !== inv.require_target_bucket;
-                    const violateForbid = inv.forbid_target_bucket !== undefined && otherBucket === inv.forbid_target_bucket;
-                    if (violateRequire || violateForbid) {
-                        issues.push({
-                            severity: inv.severity ?? "error",
-                            message: (inv.message ?? `Item '{id}' (block '{block}') status-consistency '${inv.id}'`)
-                                .replaceAll("{id}", id)
-                                .replaceAll("{block}", inv.block),
-                            block: inv.block,
-                            field: `${id}.${inv.id}`,
-                            code: inv.id,
-                        });
-                    }
-                }
-            }
-        }
+        // ── Config-declared invariants — the three classes evaluate through the
+        // SHARED evaluateConfigInvariants helper (also consumed by the write-time
+        // gate at the ops layer), so validate-side and write-side verdicts are
+        // identical by construction (the TASK-062 edge-gate lift pattern).
+        issues.push(...evaluateConfigInvariants(cwd, config, index, relations));
     }
     // Cross-block status-vocabulary check (FGAP-025): an item status value absent
     // from the declared vocabulary silently buckets to "unknown" in currentState /
@@ -1796,6 +2340,22 @@ export function validateContext(cwd) {
             }
         }
     }
+    // ── Declared-baseline staleness sweep (FEAT-011 criterion 6 — TASK-089) ──
+    // Fired typed stale_conditions and drifted content pins, through the SAME
+    // evaluateStalenessCandidates helper context-reconcile's transition sweep
+    // uses (identical verdicts). Warning-only, and validate NEVER mutates — the
+    // complete-to-stale transition belongs to reconcile or a human.
+    for (const cand of evaluateStalenessCandidates(cwd, index)) {
+        issues.push({
+            severity: "warning",
+            message: cand.kind === "staleness-candidate"
+                ? `Item '${cand.id}' (block '${cand.block}') is a staleness candidate — ${cand.reasons.join("; ")}. Apply the complete-to-stale transition via context-reconcile or by hand; validate never mutates.`
+                : `Item '${cand.id}' (block '${cand.block}') has drifted anchors — ${cand.reasons.join("; ")}. Re-review the cited locations; the flag never rewrites.`,
+            block: cand.block,
+            field: `${cand.id}.${cand.kind}`,
+            code: cand.kind,
+        });
+    }
     // ── Nested id-bearing array warning (content-addressed substrate identity,
     // Cycle 9.2) ─────────────────────────────────────────────────────────────
     // Schema-level, independent of block DATA + config: enumerate the active
@@ -1864,6 +2424,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 {
@@ -1872,13 +2485,44 @@ export function validateContext(cwd) {
     };
 }
 /**
- * Gate task completion on verification. Reads the verification block to confirm
- * a passing verification entry exists, asserts a `verification_verifies_item`
- * closure-table edge links that verification (parent) to this task (child), then
- * atomically updates the task status to "completed". The edge IS the linkage —
- * no `verification` field is embedded on the task (the verification → task
+ * 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;
+    }
+}
+/**
+ * Verification-gated task completion — the closure transition ATOM. Reads the
+ * verification block to confirm a passing verification entry exists, FILES the
+ * `verification_verifies_item` closure-table edge itself (verification as
+ * parent, task as child; idempotent — an exact pre-existing edge is a no-op via
+ * appendRelation's dedup), then updates the task status to "completed", all in
+ * one call. Filing the edge here rather than requiring a prior append-relation
+ * is load-bearing: an error-severity invariant pair (passed-verification-
+ * verifies-completed-task / completed-task-has-verification) forbids BOTH
+ * intermediate resting states, so no two-op sequence can thread the write-time
+ * gate — only the joint end-state is legal. The edge IS the linkage — no
+ * `verification` field is embedded on the task (the verification → task
  * `verification.target`/`target_type` fields were removed from the verification
- * schema in favor of the edge; this gate reads the edge, not the removed fields).
+ * schema in favor of the edge).
  */
 export function completeTask(cwd, taskId, verificationId, ctx) {
     // 1. Read and validate verification entry
@@ -1917,14 +2561,14 @@ export function completeTask(cwd, taskId, verificationId, ctx) {
     if (currentStatus === "cancelled") {
         throw new Error(`Task '${taskId}' is already cancelled`);
     }
-    // 3. Assert the verification_verifies_item edge: verification (parent) →
-    // task (child). The closure-table edge — not a verification field — is the
-    // canonical linkage. Inbound edges point AT the task; compare the parent
-    // endpoint via endpointKey (the codebase's endpoint-comparison idiom).
-    const verifiesEdge = findReferencesInRepo(cwd, taskId, "inbound").find((e) => e.relation_type === "verification_verifies_item" && endpointKey(e.parent) === verificationId);
-    if (!verifiesEdge) {
-        throw new Error(`verification '${verificationId}' does not verify task '${taskId}' — no verification_verifies_item edge; file the link (append-relation parent=${verificationId} child=${taskId} relation_type=verification_verifies_item) before completing`);
-    }
+    // 3. File the verification_verifies_item edge: verification (parent) →
+    // task (child), through the same porcelain a standalone append-relation
+    // uses (registered-type + endpoint-kind validation, atomic write,
+    // exact-duplicate no-op). The closure-table edge — not a verification
+    // field — is the canonical linkage; filing it in the SAME call that flips
+    // status makes closure a single transition atom under the write-time
+    // invariant gate.
+    const { appended } = appendRelationByRef(cwd, { parent: verificationId, child: taskId, relation_type: "verification_verifies_item" }, ctx);
     // 4. Update task status. The edge is the linkage — no `verification` field is
     // embedded (a populated additionalProperties:false tasks schema would reject it).
     updateItemInBlock(cwd, "tasks", "tasks", (t) => t.id === taskId, { status: "completed" }, ctx);
@@ -1933,6 +2577,7 @@ export function completeTask(cwd, taskId, verificationId, ctx) {
         verificationId,
         verificationStatus: String(verification.status),
         previousStatus: currentStatus,
+        edgeAppended: appended,
     };
 }
 //# sourceMappingURL=context-sdk.js.map