@davidorex/pi-context 0.29.0 → 0.31.0

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

@@ -3,7 +3,7 @@
   "$id": "pi-context://schemas/layer-plans",
   "version": "1.0.1",
   "title": "Layer Restructure Plans",
-  "description": "Plans for restructuring the .project/ directory from flat-block storage into a layered artifact-ownership model. Each plan names its conceptual source (e.g. Muni five-layer), describes each layer's purpose and its current-vs-target block mapping, and sequences the enactment into phases with exit criteria. Layer plans are themselves L2 specification-layer artifacts — they are spec-level decisions about how the framework organizes project state.",
+  "description": "Plans for restructuring substrate storage into a layered artifact-ownership model. Each plan names its conceptual source (e.g. a layered architecture model), describes each layer's purpose and its current-vs-target block mapping, and sequences the enactment into phases with exit criteria. Layer plans are themselves L2 specification-layer artifacts — they are spec-level decisions about how the framework organizes project state.",
   "type": "object",
   "required": [
     "plans"
@@ -45,7 +45,7 @@
           },
           "model": {
             "type": "string",
-            "description": "Conceptual source — e.g. 'Muni five-layer'"
+            "description": "Conceptual source — e.g. 'a layered architecture model'"
           },
           "description": {
             "type": "string",

package/samples/schemas/research.schema.json

@@ -55,7 +55,7 @@
               "L4",
               "L5"
             ],
-            "description": "Which Muni layer the research informs. L1 identity/domain; L2 specification; L3 work; L4 execution; L5 memory."
+            "description": "Which architecture layer the research informs. L1 identity/domain; L2 specification; L3 work; L4 execution; L5 memory."
           },
           "type": {
             "type": "string",

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

@@ -3,7 +3,7 @@
   "$id": "pi-context://schemas/work-orders",
   "version": "1.0.1",
   "title": "Work Orders",
-  "description": "Orchestrator-authored work-order spec for the privileged JIT-agent that drives the in-pi bounded code-change loop. A work-order names the target agent, the typed input/output contracts, the substrate-block context handoff, the bounded scope within which the agent may operate, and the deterministic real-check criteria gating acceptance (deterministic verification; never LLM self-report — verdict comes from real checks the agent cannot fake). Substrate-block handoff to the consuming agent uses the ContextBlockRef shape: each context_blocks entry is either a string for whole-block injection, or an object { name, item?, depth?, focus? } for item-specific injection. To handoff a single work-order item to the consuming agent, the agent's .agent.yaml contextBlocks declares { name: \"work-orders\", item: \"WO-NNN\" }; the compiler injects the resolved item under template key _work_orders_item (with companion _work_orders_raw / _work_orders_depth / _work_orders_focus). Authorship: orchestrator is sole spec author; capability-widening edits are writer.kind=human.",
+  "description": "Orchestrator-authored work-order spec for the privileged JIT-agent that drives the bounded code-change loop. A work-order names the target agent, the typed input/output contracts, the substrate-block context handoff, the bounded scope within which the agent may operate, and the deterministic real-check criteria gating acceptance (deterministic verification; never LLM self-report — verdict comes from real checks the agent cannot fake). Substrate-block handoff to the consuming agent uses the ContextBlockRef shape: each context_blocks entry is either a string for whole-block injection, or an object { name, item?, depth?, focus? } for item-specific injection. To handoff a single work-order item to the consuming agent, the agent's .agent.yaml contextBlocks declares { name: \"work-orders\", item: \"WO-NNN\" }; the compiler injects the resolved item under template key _work_orders_item (with companion _work_orders_raw / _work_orders_depth / _work_orders_focus). Authorship: orchestrator is sole spec author; capability-widening edits are writer.kind=human.",
   "type": "object",
   "required": [
     "work_orders"
@@ -57,7 +57,7 @@
           },
           "context_blocks": {
             "type": "array",
-            "description": "Substrate-block references the privileged agent's .agent.yaml will consume via contextBlocks. Each entry: string for whole-block injection (_<name>), OR object { name, item?, depth?, focus? } for item-specific injection (per the existing ContextBlockRef shape in packages/pi-jit-agents/src/types.ts).",
+            "description": "Substrate-block references the privileged agent's .agent.yaml will consume via contextBlocks. Each entry: string for whole-block injection (_<name>), OR object { name, item?, depth?, focus? } for item-specific injection (per the ContextBlockRef shape defined by your agent layer).",
             "items": {
               "oneOf": [
                 {

package/schemas/config.schema.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "http://json-schema.org/draft-07/schema#",
 	"$id": "pi-context://schemas/config",
-	"version": "1.5.0",
+	"version": "1.6.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.",
 	"type": "object",
@@ -194,6 +194,30 @@
 			"description": "Blocks the project has opted into via /context install.",
 			"items": { "type": "string" }
 		},
+		"installed_from": {
+			"type": "object",
+			"description": "Install baseline of the installed schemas: catalog source + per-schema content fingerprint recorded at install time so installed-vs-catalog drift can be detected. Blocks are user data and are not baselined. Written by /context install; preserved verbatim (including `at`) on an idempotent re-install whose catalog + assets are unchanged.",
+			"required": ["catalog", "catalog_version", "at", "assets"],
+			"additionalProperties": false,
+			"properties": {
+				"catalog": { "type": "string", "description": "pi-context package \"name@version\" the install baseline was taken from." },
+				"catalog_version": { "type": "string", "description": "samples/conception.json schema_version at baseline time." },
+				"at": { "type": "string", "description": "ISO-8601 timestamp of when this baseline content was established." },
+				"assets": {
+					"type": "object",
+					"description": "Per installed schema (keyed by canonical_id): content fingerprint + the schema file's own declared version.",
+					"additionalProperties": {
+						"type": "object",
+						"required": ["content_hash", "version"],
+						"additionalProperties": false,
+						"properties": {
+							"content_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+							"version": { "type": "string" }
+						}
+					}
+				}
+			}
+		},
 		"tool_operations": {
 			"type": "array",
 			"description": "Operation-granular tool grant vocabulary. Each entry names a Pi tool (or coarser operation) that can be granted to a privileged JIT-agent. Operation-granular, opt-in from empty default.",

package/schemas/pending-blocked.schema.json

@@ -0,0 +1,190 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "pi-context://schemas/pending-blocked",
+	"version": "1.0.0",
+	"title": "pi-context substrate-persisted pending-blocked resync records",
+	"description": "Records of catalog-ahead schema resyncs that `update` refused (blocked) on the last live run. Each entry pins the target catalog schema (by content_hash into the object store) plus the migration chain reaching it, so `resolve-blocked` can re-validate the corrected block against the SAME pinned target the run blocked on, then — on pass — register the chain, write the target schema, advance the merge base, and clear the entry. Replaced wholesale each live `update` run (an empty set removes the file); never an append-only log.",
+	"type": "object",
+	"required": ["schema_version", "entries"],
+	"additionalProperties": false,
+	"properties": {
+		"schema_version": {
+			"type": "string",
+			"description": "Schema version of this pending-blocked.json file itself. Decoupled from any block schema version it references."
+		},
+		"entries": {
+			"type": "array",
+			"description": "One PendingBlockedEntry per schema the last live update run refused (blocked). The set is replaced wholesale each live run; an empty set means the file is removed.",
+			"items": { "$ref": "#/definitions/PendingBlockedEntry" }
+		}
+	},
+	"definitions": {
+		"PendingBlockedEntry": {
+			"type": "object",
+			"required": ["name", "reason", "target_hash", "chain", "blocked_at"],
+			"additionalProperties": false,
+			"properties": {
+				"name": {
+					"type": "string",
+					"description": "Canonical schema id (block_kind canonical_id) the resync was refused for."
+				},
+				"from": {
+					"type": "string",
+					"description": "Installed schema version the resync would walk forward FROM (the block's declared version pre-resync). Omitted when unreadable."
+				},
+				"to": {
+					"type": "string",
+					"description": "Target catalog schema version the resync would advance TO. Omitted when unreadable."
+				},
+				"reason": {
+					"type": "string",
+					"enum": ["no-migration-chain", "validation-failed"],
+					"description": "Why the live resync refused: no-migration-chain = no shipped chain reaches the catalog version; validation-failed = the forward-migrated items fail the catalog schema."
+				},
+				"target_hash": {
+					"type": "string",
+					"pattern": "^[0-9a-f]{64}$",
+					"description": "content_hash of the pinned target catalog schema body, stored in the object store. resolve-blocked re-validates the corrected block against THIS body."
+				},
+				"chain": {
+					"type": "array",
+					"description": "Ordered MigrationDecl list reaching the target version (one per hop). Empty when reason='no-migration-chain' (no chain reaches the target).",
+					"items": { "$ref": "#/definitions/MigrationDecl" }
+				},
+				"failures": {
+					"type": "array",
+					"description": "For reason='validation-failed', the per-item constraint failures the live resync produced. Omitted for no-migration-chain.",
+					"items": { "$ref": "#/definitions/BlockValidationFailure" }
+				},
+				"premarker_hash": {
+					"type": "string",
+					"pattern": "^[0-9a-f]{64}$",
+					"description": "content_hash of the wrapped pre-marker block-file bytes, stored in the object store, written when a live update inscribed git-style failure markers into the validation-blocked block file. Present only on marker-bearing entries; lets the caller restore the block file to its pre-marker bytes. Omitted when no markers were written."
+				},
+				"blocked_at": {
+					"type": "string",
+					"format": "date-time",
+					"description": "ISO-8601 timestamp the live update run recorded the block refusal."
+				}
+			}
+		},
+		"BlockValidationFailure": {
+			"type": "object",
+			"required": ["instancePath", "keyword", "message"],
+			"additionalProperties": false,
+			"properties": {
+				"itemId": {
+					"type": "string",
+					"description": "Failing block item's `id` when the instancePath resolves to one; omitted for envelope-level errors."
+				},
+				"instancePath": {
+					"type": "string",
+					"description": "AJV raw JSON pointer of the failing constraint."
+				},
+				"keyword": {
+					"type": "string",
+					"description": "AJV constraint keyword that failed (or 'error' for a synthetic non-AJV throw)."
+				},
+				"message": {
+					"type": "string",
+					"description": "AJV constraint message text."
+				}
+			}
+		},
+		"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)."
+				},
+				"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."
+				},
+				"kind": {
+					"type": "string",
+					"enum": ["identity", "declarative-transform"],
+					"description": "identity = data shape 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'."
+				},
+				"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" },
+						"to": { "type": "string" }
+					}
+				},
+				{
+					"type": "object",
+					"required": ["op", "path"],
+					"additionalProperties": false,
+					"properties": {
+						"op": { "type": "string", "enum": ["set"] },
+						"path": { "type": "string" },
+						"value": {}
+					}
+				},
+				{
+					"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/skill-narrative.md

@@ -35,13 +35,15 @@ Every block write validates against `<root>/schemas/<blockname>.schema.json`. If
 </context_accept_all>
 
 <context_install>
-`/context install` reconciles the substrate against the `installed_schemas` and `installed_blocks` lists declared in `config.json`. For each declared name it copies the matching asset from the package-shipped samples catalog (`samples/schemas/` for schemas, `samples/blocks/` for starter blocks) into the substrate. Default behavior is skip-if-exists (preserves user edits); pass `--update` to overwrite and report the asset as `updated`. Sources missing from the catalog are reported as `notFound`. Empty install lists are not an error — the result is a clean no-op message instructing the user to edit `config.json`.
+`/context install` (reflected CLI op: `pi-context context-install [--update]`, `authGated`) reconciles the substrate against the `installed_schemas` and `installed_blocks` lists declared in `config.json`. The slash command and the CLI op run the same install engine — the op's `--update` maps to the same migration-aware overwrite the slash command's `--update` does. For each declared name it copies the matching asset from the package-shipped samples catalog (`samples/schemas/` for schemas, `samples/blocks/` for starter blocks) into the substrate. Default behavior is skip-if-exists (preserves user edits). Pass `--update` to re-sync installed SCHEMAS through the migration registry: a same-version body change (or a non-versioned schema) is a verbatim re-sync (reported `resynced`); a schema `version` bump forward-migrates the populated block's items through the shipped catalog migration chain and re-validates them against the new schema (reported `migrated`); a bump with no safe migration — no shipped chain reaching the catalog version, or items that would fail the new schema — is refused, leaving BOTH the installed schema file AND the block file byte-unchanged (reported `blocked`). Preview drift first with `/context check-status`. Populated block data is never overwritten — a block holding items is preserved (reported as `preserved`) regardless of `--update`, while empty or absent blocks receive the catalog starter. Sources missing from the catalog are reported as `notFound`. Empty install lists are not an error — the result is a clean no-op message instructing the user to edit `config.json`. Install also records an install baseline in `config.installed_from`: the catalog source (`catalog` = pi-context `name@version`, `catalog_version` = conception `schema_version`), a baseline timestamp, and a per-schema fingerprint (`assets[canonical_id]` = content hash + the schema's own version) of the installed SCHEMAS — the basis for installed-vs-catalog drift detection. The baseline covers schemas only (blocks are user data). A re-install on an unchanged substrate is idempotent: the existing baseline is preserved verbatim (timestamp included) so `config.json` stays byte-identical. `/context check-status` is a separate read-only command that previews drift between the installed schemas and the catalog: it compares each installed schema against its recorded baseline, the catalog's current schema, and the currently-installed file, and reports `in-sync` / `catalog-ahead` (the package shipped a newer schema) / `locally-modified` (the installed file was edited) / `both-diverged` / `no-baseline` / `missing-catalog` / `missing-installed`. For each schema behind the catalog (`catalog-ahead` / `both-diverged`) it additionally surfaces which schema is behind and by what version gap — `behind` plus a `version_delta` carrying the baseline → catalog version pair (a declared version bump) or a content-only basis when the catalog body moved with the version string unchanged. It writes nothing. The reflected CLI op is `pi-context context-check-status --json`.
 
-The installable catalog IS the packaged conception (`samples/conception.json`): its `block_kinds` enumerate the available kinds, each carrying its schema (`samples/schemas/`) and starter block (`samples/blocks/`). The generated installable-catalog table below lists the authoritative names — declare any subset in `installed_*` and run `/context install`, or take the whole conception via `/context accept-all`.
+The installable catalog IS the packaged conception (`samples/conception.json`): its `block_kinds` enumerate the available kinds, each carrying its schema (`samples/schemas/`) and starter block (`samples/blocks/`). The generated installable-catalog table below lists the authoritative names — declare any subset in `installed_*` and run `/context install`, or take the whole conception via `/context accept-all`. To inspect a catalog schema body itself, `pi-context read-catalog-schema --kind <canonical_id>` fetches and prints the verbatim bundled `*.schema.json` (the raw JSON Schema — `properties` / `definitions` / `$id`, distinct from the `read-samples-catalog` summary projection), so after `/context check-status` flags a schema behind the catalog you can diff that body locally against the installed `<substrate>/schemas/<name>.schema.json` without hunting through `node_modules`. It is read-only and package-intrinsic (reads the bundled catalog, mutates nothing).
 </context_install>
 
 <substrate_config>
-`<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`.
+`<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`. `installed_from` is the optional install baseline `/context install` records — the catalog source plus a per-schema content fingerprint of the installed schemas — for installed-vs-catalog drift detection.
+
+A fresh substrate adopted via `/context accept-all` carries advisory (severity-`warning`) convention-articulation invariants: every decision, feature, and task should carry an `item_governed_by_convention` edge to a convention it follows, or an `item_acknowledges_missing_convention` edge to a missing-convention gap. `context-validate` reports an artifact that articulates neither as a warning (it does not error), so the advice surfaces without blocking writes; satisfy it by adding one of those two edges (`append-relation`) when filing or amending the artifact.
 
 `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.
 
@@ -85,7 +87,7 @@ The lens-view algorithm: `edgesForLens(lens, items, authoredEdges)` returns synt
 
 `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.
+Three 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-lens-view` projects a config-declared lens as a binned item-view — a bin→count summary, or one bin's items paged by `offset`/`limit`; `context-walk-descendants` returns the transitive descendant id list from a parent under a given relation_type.
 </substrate_validation>
 
 <block_item_reads>
@@ -139,7 +141,7 @@ On `session_start`, checks npm registry for newer versions of `@davidorex/pi-pro
 
 <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.
-- `installed_schemas` / `installed_blocks` declared in `config.json` are reified by `/context install`; `--update` overwrites
+- `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
 - `/context validate` returns no errors for well-formed cross-block references

package/skills/pi-context/SKILL.md

@@ -46,6 +46,62 @@ Append a closure-table relation (edge: parent, child, relation_type, optional or
 | `child` | string | yes | Canonical id of the child endpoint |
 | `relation_type` | string | yes | Registered relation_type canonical_id / hierarchy edge type / lens id |
 | `ordinal` | integer | no | Optional sibling-ordering within (parent, relation_type) |
+| `dryRun` | boolean | no | Preview without writing relations.json |
+</tool>
+
+<tool name="remove-relation">
+Remove the single closure-table relation (edge) matching parent+child+relation_type from relations.json. Matches on the SAME (parent, child, relation_type) dedup identity append-relation uses, so it is the symmetric inverse of append-relation (ordinal is NOT part of identity). An absent edge is an idempotent no-op. Reference integrity is NOT checked here — run context-validate after if the removal changes resolvability.
+
+*Remove a relation/edge between two items (the inverse of append-relation)*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `parent` | string | yes | Canonical id (or lens bin name) of the parent endpoint |
+| `child` | string | yes | Canonical id of the child endpoint |
+| `relation_type` | string | yes | Registered relation_type canonical_id / hierarchy edge type / lens id |
+| `dryRun` | boolean | no | Preview without writing relations.json |
+</tool>
+
+<tool name="replace-relation">
+Atomically replace one closure-table relation with another in a SINGLE write (no half-state: the old edge and the new edge never coexist on disk). The old edge is matched on the (parent, child, relation_type) dedup identity; the new edge is written with its optional ordinal. If the old edge is absent the call is effectively an append of the new edge. Reference integrity is NOT checked here — run context-validate after.
+
+*Atomically swap one relation/edge for another in a single write*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `old_parent` | string | yes | Parent endpoint selector of the edge to remove |
+| `old_child` | string | yes | Child endpoint selector of the edge to remove |
+| `old_relation_type` | string | yes | relation_type of the edge to remove |
+| `parent` | string | yes | Parent endpoint selector of the replacement edge |
+| `child` | string | yes | Child endpoint selector of the replacement edge |
+| `relation_type` | string | yes | relation_type of the replacement edge |
+| `ordinal` | integer | no | Optional sibling-ordering within (parent, relation_type) for the new edge |
+| `dryRun` | boolean | no | Preview without writing relations.json |
+</tool>
+
+<tool name="append-relations">
+Append MANY closure-table relations to relations.json in a single write. Each edge is an object { parent, child, relation_type, ordinal? }. Per-(parent, child, relation_type) duplicates are skipped (against on-disk edges AND earlier edges in the same batch). Returns appended/skipped counts. Reference integrity is NOT checked here — run context-validate after. Creates relations.json if absent.
+
+*Create many relations/edges between items in one write*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `edges` | unknown | yes | JSON array of { parent, child, relation_type, ordinal? } selector objects (parent/child are id/lens-bin selectors) |
+| `dryRun` | boolean | no | Preview without writing relations.json |
+</tool>
+
+<tool name="upsert-block-item">
+Append-or-replace an item in a project block array by id: if an item with the same idField value exists it is REPLACED (full-shape replacement, not shallow-merge — use update-block-item for merge); otherwise the item is appended. Schema validation is automatic. idField defaults to 'id'.
+
+*Append-or-replace a full block item by id (replacement, not merge)*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `block` | string | yes | Block name (e.g., 'issues', 'decisions') |
+| `arrayKey` | string | yes | Array key in the block (e.g., 'issues', 'decisions') |
+| `item` | unknown | yes | Full item object to upsert — must conform to block schema |
+| `idField` | string | no | Field used as the upsert key (default 'id') |
+| `dryRun` | boolean | no | Preview the upsert without writing |
 </tool>
 
 <tool name="promote-item">
@@ -155,6 +211,13 @@ Get derived context state — source metrics, block summaries, planning lifecycl
 
 </tool>
 
+<tool name="context-check-status">
+Read-only installed-vs-catalog schema drift report — per installed schema the drift state, the baseline and catalog versions, and for behind schemas (catalog-ahead / both-diverged) the version delta (baseline -> catalog) or the content-only basis when the version string is unchanged. The front of the check-status -> update --dryRun -> update sequence; writes nothing.
+
+*Report installed-vs-catalog schema drift + the version gap for behind schemas (read-only)*
+
+</tool>
+
 <tool name="context-validate">
 Validate cross-block referential integrity — check that IDs referenced across blocks exist.
 
@@ -193,6 +256,16 @@ Enumerate installable sample block kinds (packaged view): per kind — title, de
 | `kind` | string | no | Filter to one block_kind canonical_id (e.g. 'tasks') |
 </tool>
 
+<tool name="read-catalog-schema">
+Fetch and print the verbatim catalog schema body (raw JSON Schema: properties/definitions/$id) for a named block kind — diffable locally against the installed `<substrate>/schemas/<name>.schema.json` without touching node_modules. Read-only; the projection-returning sibling is read-samples-catalog.
+
+*Fetch and print the verbatim catalog schema body for a named block kind (raw JSON Schema, diffable locally)*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `kind` | string | yes | Catalog block_kind canonical_id (e.g. 'tasks') |
+</tool>
+
 <tool name="context-current-state">
 Derive 'where are we + what's next' purely from the substrate — focus, in-flight tasks, ranked atomic-next actions (open framework-gaps then unblocked planned tasks), and blocked tasks. No writes; nothing hand-stored.
 
@@ -258,6 +331,27 @@ Create or replace a substrate block-kind JSON Schema. operation 'create' require
 | `dryRun` | boolean | no | Meta-validate without writing |
 </tool>
 
+<tool name="resolve-conflict">
+Commit the reconciliation of a schema merge conflict surfaced by update. Run this AFTER reconciling a both-diverged conflict update reported: it writes the reconciled schema body (meta-validated, atomic, operation 'replace') AND advances the merge base for that schema to the packaged catalog body. Advancing the base is the step a bare write-schema lacks — without it, update's 3-way merge re-derives the SAME conflict on every subsequent run because the base never moves off the original pre-conflict body. With the base advanced to the catalog, the next update sees the schema as locally-modified (base === catalog ≠ your body) and the deterministic merge takes your reconciled body (base === theirs → ours) — auto-merging with zero conflicts and preserving your resolution. If schema is omitted, the current on-disk schema is treated as already reconciled and only the base is advanced. The calling agent runs this; no subordinate resolver is spawned.
+
+*Commit a reconciled schema conflict: write the resolved body + advance the merge base to the catalog so update stops re-reporting it (run after reconciling an update conflict)*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `schemaName` | string | yes | Schema name without extension (e.g., 'tasks') |
+| `schema` | unknown | no | The reconciled schema body R (whole JSON Schema object, draft-07; accepts a JSON string). If omitted, the current on-disk schema is treated as already reconciled and only the merge base is advanced. |
+</tool>
+
+<tool name="resolve-blocked">
+Commit the resolution of a blocked schema surfaced by update. Run AFTER fixing the block's items (or widening the local schema): when the block file carries git-style failure markers (written by update), strips the full-line marker sentinels first, then re-validates the corrected block against the pinned target schema from the pending-blocked record; on pass registers the migration chain, writes the target schema, advances the merge base to the target (so a subsequent update converges instead of re-blocking), and clears the pending entry; on fail reports the remaining per-item failures and writes nothing.
+
+*Commit a blocked schema's resolution: strip any git-style failure markers, re-validate the corrected block against the pinned target, then write the target schema + advance the base + clear the pending record (run after fixing the items update reported blocked)*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `schemaName` | string | yes | Schema name with a pending-blocked entry (from update's blocked report) |
+</tool>
+
 <tool name="write-schema-migration">
 Declare a schema version-bump migration into substrate (migrations.json). operation 'create' appends a new declaration; 'replace' overwrites an existing declaration matched by (schemaName, fromVersion); 'remove' drops a declaration. kind='identity' asserts the bump is shape-compatible (no data transform); kind='declarative-transform' carries a TransformSpec of rename/set/delete/coerce operations on dotted JSON paths. The loaded MigrationRegistry resolves the recorded edge at next read/write so block items declaring an older schema_version walk forward without process restart. Requires user authorization via interactive confirmation at the pi-dispatch auth-gate; on confirm, the verified terminal-operator identity is stamped as writer.
 
@@ -291,6 +385,36 @@ Adopt the canonical packaged conception (samples/conception.json) as this substr
 
 </tool>
 
+<tool name="context-install">
+Install (materialize) the schemas and starter blocks declared in config.json's installed_schemas / installed_blocks from the package samples catalog. Default skip-if-exists (installed files never overwritten without --update); populated block data is always preserved (even with --update); empty or absent blocks get the catalog starter. Records the install baseline (config.installed_from: catalog source + per-schema fingerprint) for installed-vs-catalog drift detection (schemas only). A re-install on an unchanged substrate is idempotent.
+
+*Install declared schemas + starter blocks from the samples catalog (skip-if-exists; --update re-syncs schemas + replaces empty blocks; records the config.installed_from baseline)*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `update` | boolean | no | When true, re-sync existing installed schemas (migration-aware) and replace empty blocks with the catalog starter; populated block data is never overwritten. When false (default), skip existing files. |
+</tool>
+
+<tool name="update">
+Bring the installed substrate model (schemas) current with the packaged catalog. Per installed schema, consults the read-only drift check and routes by state: an already-current (in-sync) schema is a no-op; a schema the package shipped a newer version of (catalog-ahead) is re-synced through the migration-aware path; a schema edited locally (locally-modified / both-diverged) is reconciled by a deterministic 3-way merge of base (the as-installed body in the object store, keyed by the recorded baseline content_hash) × ours (the installed schema) × theirs (the catalog schema) — disjoint edits auto-merge so both the user's and the catalog's changes survive (required / enum / array-valued type nodes merge as sets), and a schema with irreconcilable per-path conflicts is left unmodified — the conflict set is returned in the op output (under conflicts) alongside a readable report, and the calling agent reconciles it then commits via resolve-conflict — which writes the reconciled body AND advances the merge base to the catalog so update stops re-reporting it (no subordinate resolver is spawned); undecidable / absent schemas (no-baseline / missing-catalog / missing-installed) are reported, not touched. Update also additively propagates catalog-new config-registry entries (relation_types / invariants / block_kinds / lenses) that are absent from the substrate config, preserving every user-authored entry and any locally-diverged body of an existing entry (additive-only — present entries are never overwritten). Update reports, under migrationsRegistered, the migration declarations a version-bump resync registers into migrations.json (each as schema / from / to). A blocked (refused) catalog-ahead schema additionally carries its diagnostic detail under blockedDetail (one entry per blocked schema): the refusal reason — no-migration-chain (no shipped chain reaches the catalog version) vs validation-failed (the forward-migrated items fail the catalog schema) — the installed -> catalog version pair, and for a validation failure the per-item failures naming the failing item id, field, and constraint. A live blocked resync also persists a pending-blocked record (pinning the target catalog schema + the chain reaching it) consumable by resolve-blocked, which commits the resolution once the block's items are fixed. Pass dryRun to preview the per-schema action plan; dryRun predicts the precise per-schema catalog-ahead outcome (resync / migrate / block / merge / conflict) by running the forward-migration + re-validation in memory, the per-blocked-schema diagnostic detail, the config-registry entries that would be added, AND the migration declarations that would be registered, writing nothing. When a catalog-ahead resync is blocked because the block's items fail the catalog schema (validation-failed), update inscribes git-style failure markers INTO the block file at the offending items (full-line `<<<<<<< BLOCKED …` / `>>>>>>> target: …` sentinels), pinning the pre-marker bytes so resolve-blocked can strip the markers and re-validate; the schema and migrations.json stay byte-unchanged. A dryRun preview writes no markers.
+
+*Update the installed schema model from the catalog (3-way merges locally-modified schemas, preserving non-conflicting edits; conflicts → returned in the op output + a report for the calling agent to reconcile and commit via resolve-conflict; a blocked resync carries blockedDetail — reason, version pair, per-item failures — and persists a pending-blocked record (target catalog schema + the chain reaching it) resolved via resolve-blocked once the block's items are fixed; a validation-failed block is marked in place with git-style failure markers (recoverable; stripped + re-validated by resolve-blocked); --dry-run predicts the precise per-schema outcome — resync / migrate / block / merge / conflict — via in-memory forward-migration + re-validation, writing nothing)*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `dryRun` | boolean | no | Preview the per-schema action plan without writing anything. |
+</tool>
+
+<tool name="validate-block-items">
+Validate a block's items against the catalog schema version — returns the per-item failures (item id, field, constraint) without writing. Resolves the block's catalog block_kind, loads the installed block, forward-migrates its items in memory through the shipped chain when the block lags the catalog version (a fresh registry; never warms the project's cache), and validates against the catalog schema body. Returns block / from (the block's declared version) / to (the catalog version) / valid / failures[] (each: itemId — the failing item's id when the instancePath resolves to one — instancePath, keyword, message). Read-only: never overwrites the schema, the block, or migrations.json. An unknown block or a missing installed block file throws.
+
+*Validate a block's items against the catalog schema version — returns the per-item failures (item id, field, constraint) without writing*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `block` | string | yes | Block name (e.g. 'tasks') |
+</tool>
+
 <tool name="context-switch">
 Flip the bootstrap pointer to a different substrate dir (parallel to git switch). Default: flip to an existing substrate at target_dir (requires config.json present). create_new=true: bootstrap a fresh substrate at target_dir AND flip in one operation. to_previous=true: flip back to the pointer's previous_contextDir (target_dir ignored).
 
@@ -319,7 +443,6 @@ Move a non-active substrate dir to archive/<dir>/. Refuses to archive the active
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `target_dir` | string | yes | Substrate dir name to archive (e.g. '.project'). Refused if it is the active substrate. |
-| `writer` | object | no | DispatchContext.writer — stamped by auth-gate on operator confirm. |
 </tool>
 
 <tool name="filter-block-items">
@@ -424,6 +547,19 @@ Materialize the Edge[] for a named lens — synthetic edges from derived_from_fi
 | `lensId` | string | yes | Lens id from config.lenses[].id |
 </tool>
 
+<tool name="context-lens-view">
+Project a config-declared lens (config.lenses[]) as a binned item-view. Without --bin, a bin->count summary (always under the read cap). With --bin, that bin's items paged by --offset/--limit. Serves target, composition, and hand-curated lenses.
+
+*Project a config-declared lens as a binned item-view — bin->count summary, or one bin's items paged*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `lensId` | string | yes | Lens id from config.lenses[].id |
+| `bin` | string | no | Return this bin's items paged; omit for a bin->count summary |
+| `offset` | integer | no | Per-bin page start index (default 0) |
+| `limit` | integer | no | Per-bin page size (default 50) |
+</tool>
+
 <tool name="context-walk-descendants">
 Walk closure-table descendants of a parent id under a given relation_type. Returns string[] of descendant ids (may be empty if no children or relations.json absent).
 
@@ -512,7 +648,7 @@ List every roadmap in <config.root>/roadmap.json with id, title, optional status
 <command name="/context">
 Context state management
 
-Subcommands: `init`, `switch`, `list`, `archive`, `install`, `accept-all`, `view`, `lens-curate`, `roadmap-list`, `roadmap-view`, `roadmap-validate`, `status`, `add-work`, `validate`, `help`
+Subcommands: `init`, `switch`, `list`, `archive`, `install`, `check-status`, `accept-all`, `view`, `lens-curate`, `roadmap-list`, `roadmap-view`, `roadmap-validate`, `status`, `add-work`, `validate`, `help`
 </command>
 
 </commands_reference>
@@ -522,7 +658,7 @@ Subcommands: `init`, `switch`, `list`, `archive`, `install`, `accept-all`, `view
 </events>
 
 <bundled_resources>
-11 schemas, 34 samples bundled.
+12 schemas, 34 samples bundled.
 See references/bundled-resources.md for full inventory.
 </bundled_resources>
 
@@ -660,13 +796,15 @@ Every block write validates against `<root>/schemas/<blockname>.schema.json`. If
 </context_accept_all>
 
 <context_install>
-`/context install` reconciles the substrate against the `installed_schemas` and `installed_blocks` lists declared in `config.json`. For each declared name it copies the matching asset from the package-shipped samples catalog (`samples/schemas/` for schemas, `samples/blocks/` for starter blocks) into the substrate. Default behavior is skip-if-exists (preserves user edits); pass `--update` to overwrite and report the asset as `updated`. Sources missing from the catalog are reported as `notFound`. Empty install lists are not an error — the result is a clean no-op message instructing the user to edit `config.json`.
+`/context install` (reflected CLI op: `pi-context context-install [--update]`, `authGated`) reconciles the substrate against the `installed_schemas` and `installed_blocks` lists declared in `config.json`. The slash command and the CLI op run the same install engine — the op's `--update` maps to the same migration-aware overwrite the slash command's `--update` does. For each declared name it copies the matching asset from the package-shipped samples catalog (`samples/schemas/` for schemas, `samples/blocks/` for starter blocks) into the substrate. Default behavior is skip-if-exists (preserves user edits). Pass `--update` to re-sync installed SCHEMAS through the migration registry: a same-version body change (or a non-versioned schema) is a verbatim re-sync (reported `resynced`); a schema `version` bump forward-migrates the populated block's items through the shipped catalog migration chain and re-validates them against the new schema (reported `migrated`); a bump with no safe migration — no shipped chain reaching the catalog version, or items that would fail the new schema — is refused, leaving BOTH the installed schema file AND the block file byte-unchanged (reported `blocked`). Preview drift first with `/context check-status`. Populated block data is never overwritten — a block holding items is preserved (reported as `preserved`) regardless of `--update`, while empty or absent blocks receive the catalog starter. Sources missing from the catalog are reported as `notFound`. Empty install lists are not an error — the result is a clean no-op message instructing the user to edit `config.json`. Install also records an install baseline in `config.installed_from`: the catalog source (`catalog` = pi-context `name@version`, `catalog_version` = conception `schema_version`), a baseline timestamp, and a per-schema fingerprint (`assets[canonical_id]` = content hash + the schema's own version) of the installed SCHEMAS — the basis for installed-vs-catalog drift detection. The baseline covers schemas only (blocks are user data). A re-install on an unchanged substrate is idempotent: the existing baseline is preserved verbatim (timestamp included) so `config.json` stays byte-identical. `/context check-status` is a separate read-only command that previews drift between the installed schemas and the catalog: it compares each installed schema against its recorded baseline, the catalog's current schema, and the currently-installed file, and reports `in-sync` / `catalog-ahead` (the package shipped a newer schema) / `locally-modified` (the installed file was edited) / `both-diverged` / `no-baseline` / `missing-catalog` / `missing-installed`. For each schema behind the catalog (`catalog-ahead` / `both-diverged`) it additionally surfaces which schema is behind and by what version gap — `behind` plus a `version_delta` carrying the baseline → catalog version pair (a declared version bump) or a content-only basis when the catalog body moved with the version string unchanged. It writes nothing. The reflected CLI op is `pi-context context-check-status --json`.
 
-The installable catalog IS the packaged conception (`samples/conception.json`): its `block_kinds` enumerate the available kinds, each carrying its schema (`samples/schemas/`) and starter block (`samples/blocks/`). The generated installable-catalog table below lists the authoritative names — declare any subset in `installed_*` and run `/context install`, or take the whole conception via `/context accept-all`.
+The installable catalog IS the packaged conception (`samples/conception.json`): its `block_kinds` enumerate the available kinds, each carrying its schema (`samples/schemas/`) and starter block (`samples/blocks/`). The generated installable-catalog table below lists the authoritative names — declare any subset in `installed_*` and run `/context install`, or take the whole conception via `/context accept-all`. To inspect a catalog schema body itself, `pi-context read-catalog-schema --kind <canonical_id>` fetches and prints the verbatim bundled `*.schema.json` (the raw JSON Schema — `properties` / `definitions` / `$id`, distinct from the `read-samples-catalog` summary projection), so after `/context check-status` flags a schema behind the catalog you can diff that body locally against the installed `<substrate>/schemas/<name>.schema.json` without hunting through `node_modules`. It is read-only and package-intrinsic (reads the bundled catalog, mutates nothing).
 </context_install>
 
 <substrate_config>
-`<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`.
+`<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`. `installed_from` is the optional install baseline `/context install` records — the catalog source plus a per-schema content fingerprint of the installed schemas — for installed-vs-catalog drift detection.
+
+A fresh substrate adopted via `/context accept-all` carries advisory (severity-`warning`) convention-articulation invariants: every decision, feature, and task should carry an `item_governed_by_convention` edge to a convention it follows, or an `item_acknowledges_missing_convention` edge to a missing-convention gap. `context-validate` reports an artifact that articulates neither as a warning (it does not error), so the advice surfaces without blocking writes; satisfy it by adding one of those two edges (`append-relation`) when filing or amending the artifact.
 
 `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.
 
@@ -710,7 +848,7 @@ The lens-view algorithm: `edgesForLens(lens, items, authoredEdges)` returns synt
 
 `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.
+Three 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-lens-view` projects a config-declared lens as a binned item-view — a bin→count summary, or one bin's items paged by `offset`/`limit`; `context-walk-descendants` returns the transitive descendant id list from a parent under a given relation_type.
 </substrate_validation>
 
 <block_item_reads>
@@ -764,7 +902,7 @@ On `session_start`, checks npm registry for newer versions of `@davidorex/pi-pro
 
 <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.
-- `installed_schemas` / `installed_blocks` declared in `config.json` are reified by `/context install`; `--update` overwrites
+- `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
 - `/context validate` returns no errors for well-formed cross-block references

package/skills/pi-context/references/bundled-resources.md

@@ -1,12 +1,13 @@
 # Bundled Resources
 
-## schemas/ (11 files)
+## schemas/ (12 files)
 
 - `schemas/bootstrap.schema.json`
 - `schemas/config.schema.json`
 - `schemas/context-registry.schema.json`
 - `schemas/layer.schema.json`
 - `schemas/migrations.schema.json`
+- `schemas/pending-blocked.schema.json`
 - `schemas/priority.schema.json`
 - `schemas/relations.schema.json`
 - `schemas/severity.schema.json`