@davidorex/pi-context 0.31.0 → 0.32.0

package/samples/schemas/context-contracts.schema.json

@@ -10,6 +10,10 @@
   ],
   "additionalProperties": false,
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
     "contracts": {
       "type": "array",
       "items": {

package/samples/schemas/conventions.schema.json

@@ -9,6 +9,10 @@
     "rules"
   ],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
     "rules": {
       "type": "array",
       "items": {

package/samples/schemas/decisions.schema.json

@@ -9,6 +9,10 @@
     "decisions"
   ],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
     "decisions": {
       "type": "array",
       "items": {

package/samples/schemas/features.schema.json

@@ -9,6 +9,10 @@
     "features"
   ],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
     "features": {
       "type": "array",
       "items": {

package/samples/schemas/framework-gaps.schema.json

@@ -9,6 +9,10 @@
     "gaps"
   ],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
     "gaps": {
       "type": "array",
       "items": {

package/samples/schemas/issues.schema.json

@@ -9,6 +9,10 @@
     "issues"
   ],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
     "issues": {
       "type": "array",
       "items": {
@@ -90,6 +94,10 @@
             "type": "string",
             "description": "Commit message or reference if resolved"
           },
+          "resolved_at": {
+            "type": "string",
+            "description": "ISO-8601 timestamp when the issue was resolved"
+          },
           "oid": {
             "type": "string",
             "pattern": "^[0-9a-f]{32}$",
@@ -108,5 +116,25 @@
         }
       }
     }
+  },
+  "x-lifecycle": {
+    "field": "status",
+    "states": [
+      "open",
+      "resolved",
+      "deferred"
+    ],
+    "transitions": [
+      {
+        "from": "open",
+        "to": "resolved",
+        "required_authority": "any"
+      },
+      {
+        "from": "open",
+        "to": "deferred",
+        "required_authority": "user"
+      }
+    ]
   }
 }

package/samples/schemas/layer-plans.schema.json

@@ -9,6 +9,10 @@
     "plans"
   ],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
     "plans": {
       "type": "array",
       "items": {

package/samples/schemas/milestone.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "pi-context://schemas/milestone",
+  "version": "1.0.0",
+  "title": "Milestones",
+  "description": "Array-block of project milestones. A milestone is a pure phase-rollup checkpoint with no work of its own: its `status` (planned | reached) is DERIVED, never authored — a milestone is `reached` iff at least one phase is positioned in it (a phase_positioned_in_milestone edge) and the parent phase of every such edge buckets to complete, else `planned`. Phase membership lives in relations.json phase_positioned_in_milestone edges (phase -> milestone), not inline. `release` is an optional grouping string pending the normalized release entity.",
+  "type": "object",
+  "required": [
+    "milestones"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
+    "milestones": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "name",
+          "status"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^MILE-\\d{3,}$",
+            "description": "Stable canonical id; MILE-NNN (3+ digits), mirroring the STORY-/TASK-NNN convention."
+          },
+          "name": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "planned",
+              "reached"
+            ],
+            "description": "DERIVED phase-rollup, not authored: `reached` iff >=1 phase_positioned_in_milestone edge (in which the phase is the parent and the milestone the child) and the parent phase of every such edge buckets to complete; else `planned`. A milestone carries no work of its own; authored status is rejected by canon (substrate-derived-state)."
+          },
+          "release": {
+            "type": "string",
+            "description": "Optional release grouping label. Interim flat string pending the normalized release entity, which will subsume / edge this field."
+          },
+          "created_by": {
+            "type": "string"
+          },
+          "created_at": {
+            "type": "string"
+          },
+          "modified_by": {
+            "type": "string"
+          },
+          "modified_at": {
+            "type": "string"
+          },
+          "oid": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{32}$",
+            "description": "Content-independent substrate-stable item identity (content-addressed substrate identity, Cycle 3). Minted once at item birth via mintOid(substrate_id); immutable across content versions. Optional in the schema so pre-Cycle-3 items validate; stamped on next write."
+          },
+          "content_hash": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$",
+            "description": "SHA-256 (hex) of the RFC-8785-canonical content projection of this item (metadata fields excluded). Recomputed on every stamping write; moves with content, stable across metadata-only churn."
+          },
+          "content_parent": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$",
+            "description": "content_hash of the immediately-prior version of this item; set on a content-changing update, absent on the first (v1) version. Forms the per-item content version chain."
+          }
+        }
+      }
+    }
+  }
+}

package/samples/schemas/phase.schema.json

@@ -10,6 +10,10 @@
   ],
   "additionalProperties": false,
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
     "phases": {
       "type": "array",
       "items": {

package/samples/schemas/rationale.schema.json

@@ -9,6 +9,10 @@
     "rationales"
   ],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
     "rationales": {
       "type": "array",
       "items": {

package/samples/schemas/requirements.schema.json

@@ -9,6 +9,10 @@
     "requirements"
   ],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
     "requirements": {
       "type": "array",
       "items": {

package/samples/schemas/research.schema.json

@@ -9,6 +9,10 @@
     "research"
   ],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
     "research": {
       "type": "array",
       "items": {

package/samples/schemas/session-notes.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "pi-context://schemas/session-notes",
+  "version": "1.0.0",
+  "title": "Session Notes",
+  "description": "Per-session handoff records: focus, discoveries, questions, decisions made, current status, and next steps captured at session end for cross-session continuity.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "sessions"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string"
+    },
+    "sessions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "timestamp",
+          "focus",
+          "current_status",
+          "next_steps"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^SESSION-\\d{3}$"
+          },
+          "timestamp": {
+            "type": "string",
+            "description": "ISO-8601 with local offset"
+          },
+          "focus": {
+            "type": "string",
+            "description": "1-2 sentence summary of what the session covered"
+          },
+          "discoveries": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "questions": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "decisions_made": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "current_status": {
+            "type": "string",
+            "description": "Prose summary of where the project stands at session end"
+          },
+          "next_steps": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "oid": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{32}$",
+            "description": "Content-independent substrate-stable item identity (content-addressed substrate identity, Cycle 3). Minted once at item birth via mintOid(substrate_id); immutable across content versions. Optional in the schema so pre-Cycle-3 items validate; stamped on next write."
+          },
+          "content_hash": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$",
+            "description": "SHA-256 (hex) of the RFC-8785-canonical content projection of this item (metadata fields excluded). Recomputed on every stamping write; moves with content, stable across metadata-only churn."
+          },
+          "content_parent": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$",
+            "description": "content_hash of the immediately-prior version of this item; set on a content-changing update, absent on the first (v1) version. Forms the per-item content version chain."
+          }
+        }
+      }
+    }
+  }
+}

package/samples/schemas/spec-reviews.schema.json

@@ -9,6 +9,10 @@
     "reviews"
   ],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
     "reviews": {
       "type": "array",
       "items": {

package/samples/schemas/story.schema.json

@@ -10,6 +10,10 @@
   ],
   "additionalProperties": false,
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
     "stories": {
       "type": "array",
       "items": {
@@ -29,6 +33,10 @@
           "title": {
             "type": "string"
           },
+          "user_kind": {
+            "type": "string",
+            "description": "Which user the story speaks for (e.g. cli-user, operator, agent) — the 'As a <user_kind>' subject of the story statement."
+          },
           "status": {
             "type": "string",
             "enum": [

package/samples/schemas/tasks.schema.json

@@ -9,6 +9,10 @@
     "tasks"
   ],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
     "tasks": {
       "type": "array",
       "items": {

package/samples/schemas/verification.schema.json

@@ -9,6 +9,10 @@
     "verifications"
   ],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
     "verifications": {
       "type": "array",
       "items": {

package/samples/schemas/work-orders.schema.json

@@ -10,6 +10,10 @@
   ],
   "additionalProperties": false,
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
     "work_orders": {
       "type": "array",
       "items": {

package/schemas/config.schema.json

@@ -1,9 +1,9 @@
 {
 	"$schema": "http://json-schema.org/draft-07/schema#",
 	"$id": "pi-context://schemas/config",
-	"version": "1.6.0",
+	"version": "1.8.0",
 	"title": "pi-context substrate config",
-	"description": "Self-bootstrapping config block. Validates the config that configures the substrate. ConfigBlock is the canonical registry for block kinds, status buckets, relation types, display strings, layers, naming aliases, hierarchy declarations, and lens specs.",
+	"description": "Self-bootstrapping config block. Validates the config that configures the substrate. ConfigBlock is the canonical registry for block kinds, status buckets, relation types, display strings, layers, naming aliases, hierarchy declarations, lens specs, and the state-derivation registry that drives currentState (focus / in-flight / next-actions / blocked / milestone-rollup).",
 	"type": "object",
 	"required": ["schema_version", "block_kinds"],
 	"additionalProperties": false,
@@ -67,6 +67,79 @@
 				"enum": ["complete", "in_progress", "blocked", "todo", "unknown"]
 			}
 		},
+		"state_derivation": {
+			"type": "object",
+			"description": "Config-declared derivation registry for currentState — the kind/relation/rank/status/head-size couplings that previously lived as hardcoded literals in the deriver. A substrate without it reports 'state-derivation not configured'.",
+			"additionalProperties": false,
+			"properties": {
+				"in_flight": {
+					"type": "object",
+					"description": "Which block kinds at which status bucket count as in-flight (drives inFlight + focus). Stock: kinds ['tasks'], bucket 'in_progress'.",
+					"additionalProperties": false,
+					"required": ["kinds", "bucket"],
+					"properties": {
+						"kinds": { "type": "array", "items": { "type": "string" } },
+						"bucket": { "type": "string" }
+					}
+				},
+				"focus_fallback": {
+					"type": "object",
+					"description": "Focus fallback when nothing is in-flight: an item of `kind` at status `bucket`. Stock: kind 'phase', bucket 'in_progress'.",
+					"additionalProperties": false,
+					"required": ["kind", "bucket"],
+					"properties": {
+						"kind": { "type": "string" },
+						"bucket": { "type": "string" }
+					}
+				},
+				"next_ranked": {
+					"type": "array",
+					"description": "Ordered cross-kind push order for nextActions. Each entry selects items of `kind` at `bucket`, labels them `label`, and emits its `reason_template` (with `{rank_value}`/`{id}` tokens substituted) as each item's `reason`; optional `rank_field` + `rank_order` rank within the entry (absent → topo over the dep/gate graph). Stock: tasks (topo) then issues (priority-ranked) then framework-gaps (priority-ranked).",
+					"items": {
+						"type": "object",
+						"additionalProperties": false,
+						"required": ["kind", "label", "bucket"],
+						"properties": {
+							"kind": { "type": "string" },
+							"label": { "type": "string" },
+							"bucket": { "type": "string" },
+							"rank_field": { "type": "string" },
+							"rank_order": { "type": "array", "items": { "type": "string" } },
+							"reason_template": { "type": "string", "description": "The `reason` string emitted for each item this entry surfaces. Tokens substituted literally: `{rank_value}` → the item's rank_field value (or 'unset' when absent; meaningful only for a field-ranked entry); `{id}` → the item id. Stock field-ranked (framework-gaps): 'open gap (priority {rank_value})'; stock topo (tasks): 'unblocked planned task'." }
+						}
+					}
+				},
+				"blocked_by": {
+					"type": "object",
+					"description": "The relation_types whose edges contribute blockers. Stock: ['task_depends_on_task', 'task_gated_by_item'].",
+					"additionalProperties": false,
+					"required": ["relation_types"],
+					"properties": {
+						"relation_types": { "type": "array", "items": { "type": "string" } }
+					}
+				},
+				"rollups": {
+					"type": "array",
+					"description": "Membership rollups (milestones). Each: items of `kind` whose members are parents of `membership_relation` edges; reached → `complete_status` when all members complete, else `incomplete_status`. Stock: milestone over phase_positioned_in_milestone, reached/planned.",
+					"items": {
+						"type": "object",
+						"additionalProperties": false,
+						"required": ["kind", "membership_relation", "complete_status", "incomplete_status"],
+						"properties": {
+							"kind": { "type": "string" },
+							"membership_relation": { "type": "string" },
+							"complete_status": { "type": "string" },
+							"incomplete_status": { "type": "string" }
+						}
+					}
+				},
+				"head_size": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Truncation cap for the nextActions head. Stock: 15."
+				}
+			}
+		},
 		"display_strings": {
 			"type": "object",
 			"description": "Validation-code / opaque-slug → display label map.",
@@ -85,7 +158,8 @@
 					"category": { "type": "string", "enum": ["ordering", "data_flow", "membership"] },
 					"cycle_allowed": { "type": "boolean" },
 					"source_kinds": { "type": "array", "items": { "type": "string" }, "description": "Block_kind canonical_ids this relation's source (edge.parent) may be; literal \"*\" = any kind. Optional; absence => endpoint-kind unchecked." },
-					"target_kinds": { "type": "array", "items": { "type": "string" }, "description": "Block_kind canonical_ids this relation's target (edge.child) may be; literal \"*\" = any kind. Optional; absence => endpoint-kind unchecked." }
+					"target_kinds": { "type": "array", "items": { "type": "string" }, "description": "Block_kind canonical_ids this relation's target (edge.child) may be; literal \"*\" = any kind. Optional; absence => endpoint-kind unchecked." },
+					"role_direction": { "type": "string", "enum": ["as_parent", "as_child"], "description": "Which stored endpoint holds the relation's PRIMARY semantic role — the single orientation source of truth. Category interprets the role (ordering=antecedent, membership=container, data_flow=source); this names where it sits: as_parent=edge.parent, as_child=edge.child. Optional: set only for relations with a per-role consumer (deriver/rollup/roadmap/promote/write/read); role-less relations omit it." }
 				}
 			}
 		},

package/schemas/migrations.schema.json

@@ -116,6 +116,31 @@
 							"enum": ["string", "number", "boolean", "array", "object"]
 						}
 					}
+				},
+				{
+					"type": "object",
+					"required": ["op", "path"],
+					"additionalProperties": false,
+					"properties": {
+						"op": { "type": "string", "enum": ["map_each"] },
+						"path": { "type": "string", "description": "Dotted '$'-prefixed path to the array whose elements are mapped." },
+						"table": {
+							"type": "object",
+							"description": "When present: each string element is replaced by table[element], or by {relation_type: element, item_endpoint: fallback} when unmatched.",
+							"additionalProperties": { "type": "object" }
+						},
+						"fallback": {
+							"type": "string",
+							"enum": ["parent", "child"],
+							"description": "item_endpoint used for an unmatched string element under `table`; defaults to 'parent' when absent."
+						},
+						"field": { "type": "string", "description": "When present (and `table` absent): set this field on every object element." },
+						"value": { "description": "Value assigned to `field` on each object element." }
+					},
+					"oneOf": [
+						{ "required": ["table"], "not": { "required": ["field"] } },
+						{ "required": ["field", "value"], "not": { "required": ["table"] } }
+					]
 				}
 			]
 		}

package/skill-narrative.md

@@ -13,7 +13,7 @@ pi-context manages structured project state in the substrate directory — a dir
 </objective>
 
 <block_files>
-Blocks are JSON files under the substrate root (one per block kind, each an array of items). Each block has a corresponding schema in `<root>/schemas/`. When you write to a block via the tools, the data is validated against its schema before persisting. Writes are atomic (tmp file + rename) and serialised per block via `withBlockLock`. The substrate root is the dir chosen at init (recorded in the `.pi-context.json` bootstrap pointer) and written to `config.json`'s `root` field by `/context accept-all`; the framework ships no default substrate-dir name. block-api routes through `resolveContextDir(cwd)` — which resolves `config.root` when set and otherwise falls back to the pointer — so a relocated root reaches every read/write site.
+Blocks are JSON files under the substrate root (one per block kind, each an array of items). Each block has a corresponding schema in `<root>/schemas/`. When you write to a block via the tools, the data is validated against its schema before persisting. Writes are atomic (tmp file + rename) and serialised per block via `withBlockLock`. The substrate root is the dir chosen at init (recorded in the `.pi-context.json` bootstrap pointer) and written to `config.json`'s `root` field at init (skeleton config) and again by `/context accept-all`; the framework ships no default substrate-dir name. block-api routes through `resolveContextDir(cwd)` — which resolves `config.root` when set and otherwise falls back to the pointer — so a relocated root reaches every read/write site.
 
 Each item in an identity-bearing block carries a three-layer identity, not a refname alone: `id` (the mutable human label, e.g. a kind-prefixed refname), `oid` (a content-independent 32-hex identity minted once at the item's birth and immutable thereafter, salted by the substrate's `substrate_id`), `content_hash` (a SHA-256 over the item's content projection — the item minus its metadata fields — so identical content deduplicates), and `content_parent` (the prior version's `content_hash`, forming a per-item version chain that advances only when content actually changed). A write carrying a different incoming `oid` is rejected. Identity stamping is a no-op unless the block's array subschema declares all three identity fields, scoping content-addressing to canonical schemas and leaving bespoke/test schemas untouched.
 </block_files>
@@ -27,11 +27,11 @@ Every block write validates against `<root>/schemas/<blockname>.schema.json`. If
 </schema_validation>
 
 <context_init>
-`/context init <substrate-dir>` creates the substrate skeleton: the `.pi-context.json` bootstrap pointer (declaring the chosen substrate-dir name) plus the substrate root and its `schemas/` directory. Nothing is imposed — no `config.json`, no schemas, and no starter blocks are written (ship-no-defaults). Idempotent: re-running preserves existing dirs. Populate the substrate next with `/context accept-all` (adopt the canonical conception) followed by `/context install`.
+`/context init <substrate-dir>` creates the substrate skeleton: the `.pi-context.json` bootstrap pointer (declaring the chosen substrate-dir name), the substrate root and its `schemas/` directory, a minimal SKELETON `config.json` (`schema_version`, empty `block_kinds`, `root`, and a minted + project-registered `substrate_id` — no vocabulary), and the catalog's `config` migration declarations seeded into `migrations.json`. No catalog vocabulary, schemas, or starter blocks are imposed (ship-no-defaults). Idempotent: re-running preserves existing dirs and never clobbers an existing `config.json`. Populate the substrate next with `/context accept-all` (adopt the canonical conception) followed by `/context install`.
 </context_init>
 
 <context_accept_all>
-`/context accept-all` adopts the package's canonical packaged conception (`samples/conception.json`) as the substrate's `config.json` — the full vocabulary (`block_kinds`, `relation_types`, `lenses`, `invariants`) plus the `installed_schemas` / `installed_blocks` manifest — with `root` set to the actual substrate dir. It writes `config.json` only (run `/context install` after to materialize the schemas + starter blocks) and is idempotent: it never overwrites an existing `config.json` (offer, don't impose). This is the accept-all path; per-entry step-through curation is a separate surface.
+`/context accept-all` adopts the package's canonical packaged conception (`samples/conception.json`) as the substrate's `config.json` — the full vocabulary (`block_kinds`, `relation_types`, `lenses`, `invariants`) plus the `installed_schemas` / `installed_blocks` manifest — with `root` set to the actual substrate dir. It writes `config.json` only (run `/context install` after to materialize the schemas + starter blocks) and is idempotent: it never overwrites a populated `config.json` (offer, don't impose); the vocabulary-empty skeleton `config.json` written by init IS overwritten by the catalog, with the skeleton's on-disk `substrate_id` preserved. This is the accept-all path; per-entry step-through curation is a separate surface.
 </context_accept_all>
 
 <context_install>
@@ -59,7 +59,7 @@ Source-of-truth-drift invariant: `validateContext` requires the active `config.s
 </cross_substrate>
 
 <schema_versioning>
-Schemas are draft-07 JSON-Schema, one per block kind, under `<substrate-dir>/schemas/`. Package-shipped substrate-singleton schemas carry a `pi-context://schemas/<name>` `$id` plus a `version`. `<substrate-dir>/migrations.json` is the per-substrate schema-version migration registry. A schema `version` bump REQUIRES a companion migration declared via the `write-schema-migration` tool; without one, reading or writing an item that declares an older `schema_version` throws a version mismatch. Migration kinds are `identity` (shape-compatible, no transform) or `declarative-transform` (a TransformSpec of rename/set/delete/coerce on dotted paths). The loaded registry resolves the migration edge at the next read/write, so items walk forward without a process restart. A `block:<name>` reference resolves to `<contextDir>/schemas/<name>.schema.json`.
+Schemas are draft-07 JSON-Schema, one per block kind, under `<substrate-dir>/schemas/`. Package-shipped substrate-singleton schemas carry a `pi-context://schemas/<name>` `$id` plus a `version`. `<substrate-dir>/migrations.json` is the per-substrate schema-version migration registry. A schema `version` bump REQUIRES a companion migration declared via the `write-schema-migration` tool; without one, reading or writing an item that declares an older `schema_version` throws a version mismatch. Migration kinds are `identity` (shape-compatible, no transform) or `declarative-transform` (a TransformSpec of rename/set/delete/coerce/map_each on dotted paths; `map_each` addresses an array — table mode maps each string element through a lookup, with unmatched elements becoming `{relation_type, item_endpoint}` under a parent/child fallback, and set-on-each mode sets a field on every object element). The loaded registry resolves the migration edge at the next read/write, so items walk forward without a process restart. Config loading is migration-aware: a `config.json` whose `schema_version` lags the bundled config schema is walked forward through the `config` migration chain in memory at load (the on-disk file is never rewritten); every substrate-lifecycle ceremony — init / accept-all / install / update / check-status / switch (existing-target and switch-back forms; the target substrate is seeded right after the pointer flip) / resolve-conflict / resolve-blocked — seeds the catalog's `config` identity declaration into `migrations.json` (idempotent) before its first config read, and a version mismatch with no resolvable chain throws. The ceremonies that reach identity-stamping writes (update, install, resolve-blocked) also establish substrate identity at entry: a config carrying no `substrate_id` gets one minted, persisted, and registered before the first stamping write — a pre-identity substrate heals on the sanctioned ceremony instead of refusing — reported in the ceremony result under `substrateIdEstablished` (live runs only; an established identity is never re-minted). On the write side, versioned-document envelopes converge: every block schema declares an optional top-level `schema_version`, and the write path stamps it (config.json's and migrations.json's included) to the owning schema's current `version` on every sanctioned write — an incoming envelope claiming an older version is first walked forward through the registered chain (or refused with the file left byte-unchanged when no chain reaches the current version), then persisted at the current version; reads of a stamped block validate the whole envelope migration-aware. A substrate whose installed schemas predate the `schema_version` property keeps writing unchanged until `/context update` lands it. A `block:<name>` reference resolves to `<contextDir>/schemas/<name>.schema.json`.
 </schema_versioning>
 
 <lens_views>
@@ -67,6 +67,8 @@ Lenses are named projections over a target block. A lens declares `id`, `target`
 
 Edges live in `<substrate-dir>/relations.json` as a closure table — each row is `{ parent, child, relation_type, ordinal? }`. `relation_type` is a lens id, a hierarchy edge type, or a registered `relation_types[].canonical_id`; `ordinal` orders siblings within `(parent, relation_type)`. Endpoints (both `parent` and `child`) are dual-form: a legacy string (a canonical id, a lens bin name, or an `<alias>:<refname>` cross-substrate sentinel; disambiguation lives in `validateRelations`), OR a structured item endpoint `{ kind: "item", oid, refname?, substrate_id?, content_hash? }` where a present `substrate_id` marks a foreign endpoint and `content_hash` is carried for drift detection, OR a structured lens-bin endpoint `{ kind: "lens_bin", bin }` — a virtual parent that never resolves to an item.
 
+Edge orientation is declared once, read everywhere. Storage is uniform (`edge.parent` = source endpoint, `edge.child` = target endpoint); which endpoint holds a relation's PRIMARY semantic role (prerequisite/predecessor/gate for `ordering`, container for `membership`, source for `data_flow`) is `config.relation_types[].role_direction` — `as_parent` (primary at `edge.parent`) or `as_child` (primary at `edge.child`), optional and set only for relations with a per-role consumer. The `primaryEndpoint(edge, role_direction)` / `counterEndpoint(edge, role_direction)` helpers read the endpoint under that declaration, and the blocked/ready deriver (`state_derivation.blocked_by` gate-vs-dependency split), the milestone rollup, the derived roadmap (precedes + membership), and `promote-item`'s lineage edge all route through it rather than hardcoding parent/child. Authoring: `append-relation` / `append-relations` take EITHER raw `--parent`/`--child` OR role-typed `--primary`/`--counter` (mapped to parent/child via `role_direction`; mutually exclusive) — a bare `--parent`/`--child` append of a relation that is BOTH role-bearing and orientation-ambiguous (its source/target kinds overlap, incl. `"*"`) is rejected in favor of `--primary`/`--counter`, while a role-less or disjoint-kind relation appends bare unchanged. Reading: `context-walk-descendants` / `walk-ancestors` on a disjoint-kind relation queried from the wrong endpoint THROWS naming the correct op instead of returning an ambiguous `[]`. `replace-relation` writes raw endpoints verbatim (bypassing the orientation gate) — the re-orient affordance; run `context-validate` after.
+
 The single-form rule: ALL inter-item relationships are closure-table edges. Embedded nested id-bearing arrays and FK-as-field are forbidden — a nested id-bearing array in a schema is flagged `nested_id_bearing_array` by `validateContext` with the remediation "promote to a top-level entity + membership edge". Containment is a membership edge carrying `ordinal`; the nested id-bearing array → top-level entity block + ordinal-bearing membership edges promotion is performed by the canonicalizer (the context-dir-migration `canonicalizeSubstrate` machinery, run as a repo-side migration script under `scripts/migration/` — not a packaged pi-context tool). (Distinct from the `promote-item` tool, which is a cross-substrate derivation: it promotes a substrate item INTO another registered substrate as a new content-addressed item, recording an `item_derived_from_item` lineage edge in the destination.)
 
 The lens-view algorithm: `edgesForLens(lens, items, authoredEdges)` returns synthetic edges (when `derived_from_field` is set) or filtered authored edges (otherwise). `groupByLens(items, lens, lensEdges)` produces a `Map<binName, ItemRecord[]>`. `walkDescendants(parentId, relationType, edges)` traverses the closure table from any parent.
@@ -140,7 +142,7 @@ On `session_start`, checks npm registry for newer versions of `@davidorex/pi-pro
 </update_check>
 
 <success_criteria>
-- `<substrate-dir>/`, `<substrate-dir>/schemas/`, and the `.pi-context.json` bootstrap pointer exist after `/context init <substrate-dir>` (init is skeleton-only: no `config.json`, no schemas, no blocks until accept-all + install). Phases are not a directory — they live as an in-block array under `phase.json` (plural `phases` key); there is no `phases/` dir.
+- `<substrate-dir>/`, `<substrate-dir>/schemas/`, the `.pi-context.json` bootstrap pointer, a skeleton `config.json`, and a seeded `migrations.json` exist after `/context init <substrate-dir>` (init imposes no catalog: no vocabulary, no schemas, no blocks until accept-all + install). Phases are not a directory — they live as an in-block array under `phase.json` (plural `phases` key); there is no `phases/` dir.
 - `installed_schemas` / `installed_blocks` declared in `config.json` are reified by `/context install`; `--update` re-syncs installed schemas through the migration registry (forward-migrate block items on a version bump, or refuse and leave unchanged when items can't be safely migrated), but populated block data is never overwritten (preserved) — only empty or absent blocks receive the catalog starter
 - Block writes validate against schemas — invalid data rejected with specific error
 - `/context status` returns current derived state without errors