@davidorex/pi-context 0.26.0 → 0.28.1

package/schemas/migrations.schema.json

@@ -0,0 +1,123 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "pi-context://schemas/migrations",
+	"version": "1.0.0",
+	"title": "pi-context substrate-persisted schema migration declarations",
+	"description": "Operator-authored declarations describing per-step schema version migrations. The migration-registry-loader reads this file at extension load (per cwd, cached) and converts each MigrationDecl into a MigrationFn registered against the per-process MigrationRegistry. kind='identity' asserts data is shape-compatible across the bump (no transform). kind='declarative-transform' carries a TransformSpec whose operations apply to dotted JSON paths on object-shaped block items.",
+	"type": "object",
+	"required": ["schema_version", "migrations"],
+	"additionalProperties": false,
+	"properties": {
+		"schema_version": {
+			"type": "string",
+			"description": "Schema version of this migrations.json file itself. Decoupled from the schema-version semver of any individual block schema it describes."
+		},
+		"migrations": {
+			"type": "array",
+			"description": "Ordered list of MigrationDecl entries. Order is informational; resolution walks fromVersion→toVersion edges per schemaName via the in-memory registry.",
+			"items": { "$ref": "#/definitions/MigrationDecl" }
+		}
+	},
+	"definitions": {
+		"MigrationDecl": {
+			"type": "object",
+			"required": ["schemaName", "fromVersion", "toVersion", "kind", "created_by", "created_at"],
+			"additionalProperties": false,
+			"properties": {
+				"schemaName": {
+					"type": "string",
+					"description": "Canonical schema id (matches the schema's $id minus the URN prefix). Conforms to assertSubstrateName alphabet (letters, digits, '-', '_')."
+				},
+				"fromVersion": {
+					"type": "string",
+					"description": "Semver string of the source schema version this migration walks forward from."
+				},
+				"toVersion": {
+					"type": "string",
+					"description": "Semver string of the destination schema version this migration produces. Must differ from fromVersion."
+				},
+				"kind": {
+					"type": "string",
+					"enum": ["identity", "declarative-transform"],
+					"description": "identity = operator asserts data shape is unchanged across the bump (no transform). declarative-transform = transform.operations[] applies to the data."
+				},
+				"transform": {
+					"$ref": "#/definitions/TransformSpec",
+					"description": "Required when kind='declarative-transform'; forbidden when kind='identity'. The presence/absence guard is enforced by the write-schema-migration Pi tool prior to AJV validation."
+				},
+				"created_by": {
+					"type": "string",
+					"description": "Operator identity (writer.user) recorded at declaration write."
+				},
+				"created_at": {
+					"type": "string",
+					"format": "date-time",
+					"description": "ISO-8601 timestamp recorded at declaration write."
+				}
+			}
+		},
+		"TransformSpec": {
+			"type": "object",
+			"required": ["operations"],
+			"additionalProperties": false,
+			"properties": {
+				"operations": {
+					"type": "array",
+					"description": "Ordered TransformOp sequence applied in order to the block-item data shape.",
+					"items": { "$ref": "#/definitions/TransformOp" }
+				}
+			}
+		},
+		"TransformOp": {
+			"oneOf": [
+				{
+					"type": "object",
+					"required": ["op", "from", "to"],
+					"additionalProperties": false,
+					"properties": {
+						"op": { "type": "string", "enum": ["rename"] },
+						"from": {
+							"type": "string",
+							"description": "Source JSON path in dotted notation prefixed with '$' (e.g. '$.field' or '$.nested.field')."
+						},
+						"to": { "type": "string" }
+					}
+				},
+				{
+					"type": "object",
+					"required": ["op", "path"],
+					"additionalProperties": false,
+					"properties": {
+						"op": { "type": "string", "enum": ["set"] },
+						"path": { "type": "string" },
+						"value": {
+							"description": "Value to set at path. Any JSON-serializable shape (string / number / boolean / null / array / object)."
+						}
+					}
+				},
+				{
+					"type": "object",
+					"required": ["op", "path"],
+					"additionalProperties": false,
+					"properties": {
+						"op": { "type": "string", "enum": ["delete"] },
+						"path": { "type": "string" }
+					}
+				},
+				{
+					"type": "object",
+					"required": ["op", "path", "type"],
+					"additionalProperties": false,
+					"properties": {
+						"op": { "type": "string", "enum": ["coerce"] },
+						"path": { "type": "string" },
+						"type": {
+							"type": "string",
+							"enum": ["string", "number", "boolean", "array", "object"]
+						}
+					}
+				}
+			]
+		}
+	}
+}

package/schemas/relations.schema.json

@@ -1,23 +1,54 @@
 {
 	"$schema": "http://json-schema.org/draft-07/schema#",
 	"$id": "pi-context://schemas/relations",
-	"version": "1.0.0",
+	"version": "2.0.0",
 	"title": "pi-context closure-table relations",
-	"description": "Generic closure-table substrate. One row per (parent, child, relation_type) edge. Multiple parallel hierarchies coexist as different relation_type values. Reassignment is a single field write. The schema is intentionally permissive on edge.parent's namespace — disambiguation between hierarchy edges (parent ∈ canonical ids) and lens edges (parent ∈ lens.bins) is cross-document and lives at substrate-SDK validateRelations(). Cycle detection lives at SDK traversal primitives.",
+	"description": "Generic closure-table substrate. One row per (parent, child, relation_type) edge. Multiple parallel hierarchies coexist as different relation_type values. Reassignment is a single field write. Endpoints are DUAL-FORM (content-addressed-substrate-identity arc, Cycle 5): a LEGACY string (canonical id OR lens bin name — disambiguated cross-document at validateRelations), OR a structured EdgeEndpoint object — {kind:'item', oid, refname?, substrate_id?, content_hash?} for an item endpoint, or {kind:'lens_bin', bin} for a virtual lens-bin parent. Existing string data validates against the string branch unchanged. Disambiguation between hierarchy edges (parent ∈ canonical ids) and lens edges (parent ∈ lens.bins) is cross-document and lives at substrate-SDK validateRelations(). Cycle detection lives at SDK traversal primitives. Cross-substrate RESOLUTION of foreign (substrate_id-bearing) endpoints is Cycle 8 — this schema only accepts the FORM.",
+	"$defs": {
+		"endpoint": {
+			"description": "An edge endpoint. Dual-form: a legacy string, or a structured EdgeEndpoint object.",
+			"oneOf": [
+				{
+					"type": "string",
+					"description": "LEGACY form. Either a canonical id (DEC-NNNN, FGAP-NNN, issue-NNN) or a bin name from a lens definition. Mixing is intentional — a lens bin acts as a virtual parent node. A 'project:'/'<alias>:'-prefixed string is a cross-substrate sentinel treated as unresolved until Cycle 8."
+				},
+				{
+					"type": "object",
+					"description": "Structured ITEM endpoint. oid is the content-addressed object id (dedup identity); refname is the legacy canonical id (consumer node identity). substrate_id present → foreign endpoint (Cycle-8 resolution). content_hash carried for drift detection.",
+					"required": ["kind", "oid"],
+					"additionalProperties": false,
+					"properties": {
+						"kind": { "const": "item" },
+						"oid": { "type": "string", "description": "Content-addressed object id." },
+						"refname": { "type": "string", "description": "Legacy canonical id / human-readable refname." },
+						"substrate_id": {
+							"type": "string",
+							"description": "Owning substrate id when the endpoint is FOREIGN; absent for same-substrate."
+						},
+						"content_hash": { "type": "string", "description": "Content hash carried for Cycle-8 drift detection." }
+					}
+				},
+				{
+					"type": "object",
+					"description": "Structured LENS_BIN endpoint — a virtual lens-bin parent node. NEVER resolves to an item.",
+					"required": ["kind", "bin"],
+					"additionalProperties": false,
+					"properties": {
+						"kind": { "const": "lens_bin" },
+						"bin": { "type": "string", "description": "Lens bin label." }
+					}
+				}
+			]
+		}
+	},
 	"type": "array",
 	"items": {
 		"type": "object",
 		"required": ["parent", "child", "relation_type"],
 		"additionalProperties": false,
 		"properties": {
-			"parent": {
-				"type": "string",
-				"description": "Either a canonical id (DEC-NNNN, FGAP-NNN, issue-NNN) or a bin name from a lens definition. Mixing is intentional — a lens bin acts as a virtual parent node."
-			},
-			"child": {
-				"type": "string",
-				"description": "Canonical id of the member item."
-			},
+			"parent": { "$ref": "#/$defs/endpoint" },
+			"child": { "$ref": "#/$defs/endpoint" },
 			"relation_type": {
 				"type": "string",
 				"description": "Lens id, hierarchy edge type, or registered relation_type canonical_id. Allows multiple parallel hierarchies over the same items."

package/skill-narrative.md

@@ -3,25 +3,31 @@ name: pi-context
 description: >
   Schema-driven project state management with typed JSON blocks, schema validation,
   substrate config, lens views, closure-table relations, and cross-block referential
-  integrity. Use when managing .project/ blocks, scaffolding project structure,
+  integrity. Use when managing substrate blocks, scaffolding project structure,
   installing block kinds from the packaged samples catalog, validating project state,
   rendering lens views, or adding work items.
 ---
 
 <objective>
-pi-context manages structured project state in `.project/` — a directory of JSON block files validated against schemas. The substrate (config + lenses + closure-table relations) is degree-zero state that defines where the rest lives and how items group into views.
+pi-context manages structured project state in the substrate directory — a directory of JSON block files validated against schemas. The substrate (config + lenses + closure-table relations) is degree-zero state that defines where the rest lives and how items group into views.
 </objective>
 
 <block_files>
-Blocks are JSON files under the substrate root (e.g., `gaps.json`, `decisions.json`). 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 (DEC-0015). 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 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>
 
+<content_addressing>
+On a stamping write the item's content projection (a shallow copy with the metadata fields removed) is persisted to `<substrate-dir>/objects/<content_hash>.json` — a content-addressed object store (idempotent, atomic tmp+rename; identical content yields a byte-identical file). The store is git-tracked: it is the integrity/version store, and gitignoring it would lose pinning. Object persistence is deferred until after the whole block clears schema validation, so a validation failure never orphans an object. The metadata fields excluded from the content hash are the mandatory floor `{id, oid, content_hash, content_parent}` (never hashable, never pullable into the hash by an override) plus a discretionary set (the author fields and `closed_by`/`closed_at`); a schema's item subschema may redefine the discretionary set via `x-identity.metadata_fields`, but the floor is always unioned in.
+</content_addressing>
+
 <schema_validation>
 Every block write validates against `<root>/schemas/<blockname>.schema.json`. If the schema file doesn't exist, writes proceed without validation. Validation errors include the specific JSON Schema violations.
 </schema_validation>
 
 <context_init>
-`/context init <dir>` creates the substrate skeleton: the `.pi-context.json` bootstrap pointer (declaring the substrate-dir name per DEC-0015) plus the substrate root and its `schemas/` directory. Nothing is imposed — no `config.json`, no schemas, and no starter blocks are written (DEC-0011 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) 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>
 
 <context_accept_all>
@@ -35,17 +41,31 @@ The installable catalog IS the packaged conception (`samples/conception.json`):
 </context_install>
 
 <substrate_config>
-`.project/config.json` is the substrate bootstrap. Its `root` field declares where every other block, schema, agent, and template lives — closing the GitHub #3 surface where downstream consumers had to assume `.project/`. `naming` aliases canonical block ids to display names (used by `/context view` rendering). `hierarchy` declares legal closure-table edges (parent block → child block via relation_type). `lenses` declares named projections over a target block. `installed_schemas` / `installed_blocks` are the install manifest consumed by `/context install`.
+`<substrate-dir>/config.json` is the substrate bootstrap. Its `root` field declares where every other block, schema, agent, and template lives — consumers resolve that dir via the `.pi-context.json` pointer plus `config.root`, never by assuming a fixed directory name. Its `substrate_id` field is the per-substrate root identity (pattern `sub-` followed by 16 hex), minted once and immutable on disk; it salts oid minting and identifies the substrate in the project-root registry. `naming` aliases canonical block ids to display names (used by `/context view` rendering). `hierarchy` declares legal closure-table edges (parent block → child block via relation_type). `lenses` declares named projections over a target block. `installed_schemas` / `installed_blocks` are the install manifest consumed by `/context install`.
 
-`config.json` and `relations.json` are exempt from `root` redirection — they always live at `.project/` because they are the substrate that defines `root`. All other state lives under `<config.root>/...` per `resolveContextDir(cwd)`. The package ships their schemas in `schemas/` (config.schema.json, relations.schema.json) and resolves them via three-tier search: project override > user override > package-shipped.
+`config.json` and `relations.json` are exempt from `config.root` redirection — they always live at the substrate-dir root (the dir chosen at bootstrap, resolved via the `.pi-context.json` pointer, suggested `.context`) because they are the substrate that defines `root`. The substrate-dir root is whatever was chosen at bootstrap, not necessarily `.project`. All other state lives under `<config.root>/...` per `resolveContextDir(cwd)`. The package ships their schemas in `schemas/` (config.schema.json, relations.schema.json) and resolves them via three-tier search: project override > user override > package-shipped.
 
 The `loadContext(cwd)` SDK returns an mtime-keyed cached snapshot of `{ config, relations, configMtime, relationsMtime }` for one cwd. Consumers must not mutate.
 </substrate_config>
 
+<cross_substrate>
+A project can carry multiple substrates. The `.pi-context.json` bootstrap pointer names the single ACTIVE substrate dir; a separate project-root, git-tracked `.pi-context-registry.json` enumerates ALL substrates — a version plus `substrates: { <substrate_id>: { dir, aliases[] } }`. `resolveSubstrateDir(cwd, substrate_id)` and `resolveAlias(cwd, alias)` look up the registry and return null on a clean miss.
+
+`resolveRef(cwd, ref)` classifies any endpoint into one of four statuses: `active` — resolved in the active substrate's index (a bare oid/refname, or any lens_bin endpoint, which is always active without an item lookup); `foreign` — a structured endpoint carrying a `substrate_id`, or an `<alias>:<refname>` string whose alias is registered, resolved in the foreign substrate's index; `dangling` — a locator naming a registered substrate where the oid/refname is absent; `unregistered` — a `substrate_id` or alias the registry does not carry. A string with a NON-leading `:` (the parse gates on `colon > 0`) is first attempted as an `<alias>:<refname>` parse; a leading-colon string is not alias-parsed.
+
+Source-of-truth-drift invariant: `validateContext` requires the active `config.substrate_id` to have a registry entry whose `dir` resolves to the active substrate. A mismatch yields `substrate_id_registry_mismatch`; a missing entry yields `substrate_id_unregistered`.
+</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`.
+</schema_versioning>
+
 <lens_views>
 Lenses are named projections over a target block. A lens declares `id`, `target` (block name), `relation_type`, `derived_from_field` (optional — synthesizes edges from a per-item field instead of requiring authored edges), `bins` (named groupings), and `render_uncategorized`.
 
-Edges live in `.project/relations.json` as a closure table — each row is `{ parent, child, relation_type }`. `parent` is either a canonical id (hierarchy edges) or a lens.bins value (lens edges); disambiguation lives in `validateRelations`.
+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.
+
+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.
 
@@ -61,7 +81,9 @@ The lens-view algorithm: `edgesForLens(lens, items, authoredEdges)` returns synt
 </context_view>
 
 <substrate_validation>
-`validateRelations(cwd)` (exposed as the `context-validate-relations` tool) checks the closure-table edges in `relations.json` against the config + per-block item snapshots. Diagnostics codes: `edge_unknown_relation_type`, `edge_parent_not_in_bins`, `edge_unresolved_parent`, `edge_unresolved_child`, `edge_parent_wrong_block`, `edge_child_wrong_block`, `edge_cycle_detected`. Returns `{ status: "clean" | "warnings" | "invalid", issues[] }` where each issue carries the offending edge or cycle path.
+`validateRelations(cwd)` (exposed as the `context-validate-relations` tool) checks the closure-table edges in `relations.json` against the config + per-block item snapshots, with the `resolveRef` hook classifying foreign endpoints. Diagnostics codes: `edge_unknown_relation_type`, `edge_parent_not_in_bins`, `edge_unresolved_parent`, `edge_unresolved_child`, `edge_parent_wrong_block`, `edge_child_wrong_block`, `edge_cycle_detected`. Returns `{ status: "clean" | "warnings" | "invalid", issues[] }` where each issue carries the offending edge or cycle path.
+
+`validateContext(cwd)` (the `context-validate` tool) layers the registry/identity invariants over cross-block referential integrity: `substrate_id_unregistered` and `substrate_id_registry_mismatch` (the source-of-truth-drift guard on the active substrate), `edge_endpoint_dangling` and `edge_endpoint_unregistered` (a structured endpoint naming a registered-but-absent or unregistered substrate), and `nested_id_bearing_array` (a schema embedding an id-bearing array instead of using a membership edge). Config-declared `invariants[]` and registered lens-validators are checked in the same pass.
 
 Two derived substrate tools complement validation: `context-edges-for-lens` returns the materialized `Edge[]` for a named lens (synthetic from `derived_from_field` or filtered authored edges); `context-walk-descendants` returns the transitive descendant id list from a parent under a given relation_type.
 </substrate_validation>
@@ -95,21 +117,20 @@ Item-level reads complement whole-block `read-block` (which is all-or-nothing an
 </duplicate_detection>
 
 <context_validate>
-Two separate validators address two concerns:
+Two surfaces address related concerns. Cross-block referential integrity is EDGE-based: there are no per-block inline-FK field checks (no `task.phase`, `task.depends_on`, `decision.phase`, `gap.resolved_by`, `requirement.traces_to`/`depends_on`, `verification.target`, `rationale.related_decisions` scans) — `relations.json` closure-table edges are the sole reference surface.
 
-`/context validate` (the `context-validate` tool) checks cross-block referential integrity:
-- task.phase references a valid phase
-- task.depends_on references valid task IDs
-- decision.phase references a valid phase
-- gap.resolved_by references a valid ID
-- requirement.traces_to references valid phase/task IDs
-- requirement.depends_on references valid requirement IDs
-- verification.target references a valid target ID
-- rationale.related_decisions references valid decision IDs
+`/context validate` (the `context-validate` tool → `validateContext`) is the project-wide check. It runs:
+- Source-of-truth drift: when the active `config.substrate_id` is set, the project-root `.pi-context-registry.json` must carry an entry whose dir resolves to the active substrate dir (`substrate_id_unregistered`, `substrate_id_registry_mismatch`).
+- Edge integrity: each edge's `parent`/`child` is classified via the unified id index across substrates — an endpoint naming an unregistered substrate alias/id errors (`edge_endpoint_unregistered`), one that resolves to no item errors (`edge_endpoint_dangling`); a `relation_type` absent from `config.relation_types[]` errors; when a relation_type declares `source_kinds`/`target_kinds`, an endpoint whose resolved block kind is outside the (non-`*`) declared set errors.
+- Cycle detection: delegated to `validateRelations`; only its `edge_cycle_detected` diagnostics are merged in.
+- Config-declared invariants: `requires-edge` and `status-consistency` classes are enforced generically from `config.invariants[]` DATA — no block/status/relation_type vocabulary is hardcoded in source; each invariant's emitted code is its own `inv.id`.
+- Status-vocabulary: an item `status` value with no key in the declared vocabulary is a warning (`status_unknown_value`).
+- Nested id-bearing array: a schema array at nesting depth ≥ 1 whose item shape carries an `id` is a warning to promote it to a top-level entity + membership edge (`nested_id_bearing_array`).
+- Lens validators: every validator registered via `registerLensValidator` is dispatched and its issues merged; a throwing validator surfaces as a warning (`lens_validator_failed:<name>`).
 
-Returns errors (broken dependency references) and warnings (unresolved cross-references).
+Returns issues with `severity` error/warning; status is `invalid` (any error), `warnings`, or `clean`.
 
-The `context-validate-relations` tool (see `<substrate_validation>`) validates closure-table edges in `relations.json` — a separate concern from cross-block ID resolution.
+The lower-level `context-validate-relations` tool (→ `validateRelations`, see `<substrate_validation>`) checks the closure-table edges in `relations.json` in isolation: unregistered relation_type (`edge_unknown_relation_type`), lens-bin parent not among a lens's bins (`edge_parent_not_in_bins`), unresolved/wrong-block parent or child (`edge_unresolved_parent`, `edge_unresolved_child`, `edge_parent_wrong_block`, `edge_child_wrong_block`), and cycles (`edge_cycle_detected`).
 </context_validate>
 
 <update_check>
@@ -117,7 +138,7 @@ On `session_start`, checks npm registry for newer versions of `@davidorex/pi-pro
 </update_check>
 
 <success_criteria>
-- `.project/`, `.project/schemas/`, `.project/phases/`, and `.project/config.json` exist after `/context init`
+- `<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.
 - `installed_schemas` / `installed_blocks` declared in `config.json` are reified by `/context install`; `--update` overwrites
 - Block writes validate against schemas — invalid data rejected with specific error
 - `/context status` returns current derived state without errors