@davidorex/pi-context 0.30.0 → 0.31.0

package/dist/schema-merge.js

@@ -0,0 +1,176 @@
+/**
+ * Deterministic key/path-level draft-07 3-way schema merge (FEAT-006 T3 —
+ * TASK-036). Pure, no I/O: given the recorded merge BASE (the installed-from
+ * baseline schema body), OURS (the currently-installed, locally-edited body),
+ * and THEIRS (the catalog's current body), produce a merged body plus the set of
+ * irreconcilable per-path conflicts.
+ *
+ * Value equality throughout is canonical-JSON equality (`canonicalJson(a) ===
+ * canonicalJson(b)`) so structurally-equal-but-key-reordered values compare
+ * equal and the merge is order-insensitive + deterministic.
+ *
+ * The caller (`updateContext`) writes the merged body ONLY when the returned
+ * conflict set is empty; a non-empty conflict set means the merged body is left
+ * as OURS at the conflicting node(s) and the caller refrains from writing.
+ */
+import { canonicalJson } from "./content-hash.js";
+/**
+ * Module-private absent-key sentinel. A unique object (referential identity) so
+ * no representable JSON value can collide with "this key is absent on this
+ * side"; distinct from `null`/`undefined`, both of which are legitimate present
+ * values in a JSON document.
+ */
+const MISSING = Symbol("schema-merge:MISSING");
+function isMissing(v) {
+    return v === MISSING;
+}
+/** A plain JSON object: not MISSING, not null, not an array. */
+function isPlainObject(v) {
+    return !isMissing(v) && typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Present-and-an-array. */
+function isArrayValue(v) {
+    return !isMissing(v) && Array.isArray(v);
+}
+/** Canonical-JSON value equality (both sides must be present). */
+function valuesEqual(a, b) {
+    return canonicalJson(a) === canonicalJson(b);
+}
+/** `obj[key]` if the key is an own property, else MISSING. */
+function get(obj, key) {
+    return Object.hasOwn(obj, key) ? obj[key] : MISSING;
+}
+/**
+ * Whether the node at `path` (with the present sides all arrays) is a SET-ARRAY:
+ * an array whose order/duplication is not semantically meaningful, mergeable as
+ * a set. Applies when the LAST path segment is `required` or `enum`, OR when the
+ * path's last segment is `type` (a `type` whose value is an array is a JSON
+ * Schema type-union list — set-semantic).
+ */
+function isSetArrayPath(path) {
+    const last = path.includes(".") ? path.slice(path.lastIndexOf(".") + 1) : path;
+    return last === "required" || last === "enum" || last === "type";
+}
+/**
+ * 3-way set merge honoring adds AND removes, conflict-free:
+ *   result = (ours ∩ theirs) ∪ (ours \ base) ∪ (theirs \ base)
+ * Element identity is canonical-JSON. The result is returned as an array sorted
+ * by each element's canonical JSON for determinism. A MISSING base is treated as
+ * the empty set.
+ */
+function mergeSetArray(base, ours, theirs) {
+    const baseArr = isArrayValue(base) ? base : [];
+    const baseKeys = new Set(baseArr.map((e) => canonicalJson(e)));
+    const oursByKey = new Map();
+    for (const e of ours)
+        oursByKey.set(canonicalJson(e), e);
+    const theirsByKey = new Map();
+    for (const e of theirs)
+        theirsByKey.set(canonicalJson(e), e);
+    const resultByKey = new Map();
+    // (ours ∩ theirs): survivors present on both edited sides.
+    for (const [k, e] of oursByKey) {
+        if (theirsByKey.has(k))
+            resultByKey.set(k, e);
+    }
+    // (ours \ base): additions ours made.
+    for (const [k, e] of oursByKey) {
+        if (!baseKeys.has(k))
+            resultByKey.set(k, e);
+    }
+    // (theirs \ base): additions theirs made.
+    for (const [k, e] of theirsByKey) {
+        if (!baseKeys.has(k))
+            resultByKey.set(k, e);
+    }
+    const keys = [...resultByKey.keys()].sort();
+    return keys.map((k) => resultByKey.get(k));
+}
+/**
+ * Recursive 3-way merge of one node. Pushes any irreconcilable disagreement onto
+ * the shared `conflicts` array (tagged with `path`) and returns the merged value
+ * (which may be the MISSING sentinel to signal a key deletion to the parent
+ * object-merge).
+ */
+function merge3(base, ours, theirs, path, conflicts) {
+    const basePresent = !isMissing(base);
+    const oursPresent = !isMissing(ours);
+    const theirsPresent = !isMissing(theirs);
+    // --- Add / remove handling (at least one side MISSING) ---------------------
+    if (!(basePresent && oursPresent && theirsPresent)) {
+        const presentCount = (basePresent ? 1 : 0) + (oursPresent ? 1 : 0) + (theirsPresent ? 1 : 0);
+        if (presentCount === 0)
+            return MISSING; // (cannot occur from a present parent)
+        if (presentCount === 1) {
+            // Present on exactly one side → take that side's value.
+            return oursPresent ? ours : theirsPresent ? theirs : base;
+        }
+        // presentCount === 2: exactly one side is MISSING.
+        if (!basePresent) {
+            // Both ours + theirs added this key (base absent). Equal adds converge;
+            // differing adds conflict.
+            if (valuesEqual(ours, theirs))
+                return ours;
+            conflicts.push({ path, base: undefined, ours, theirs });
+            return ours;
+        }
+        // One of ours/theirs removed the key; the OTHER (non-base) side is present.
+        const otherPresent = oursPresent ? ours : theirs;
+        if (valuesEqual(base, otherPresent)) {
+            // The surviving side left the value unchanged vs base ⇒ honor the removal.
+            return MISSING;
+        }
+        // Delete-vs-modify: one side removed it while the other changed it → conflict.
+        conflicts.push({ path, base, ours, theirs });
+        return ours;
+    }
+    // --- All three present -----------------------------------------------------
+    // Plain-object node: recurse per key over the sorted union.
+    if (isPlainObject(base) && isPlainObject(ours) && isPlainObject(theirs)) {
+        const keys = [...new Set([...Object.keys(base), ...Object.keys(ours), ...Object.keys(theirs)])].sort();
+        const out = {};
+        for (const k of keys) {
+            const childPath = path ? `${path}.${k}` : k;
+            const merged = merge3(get(base, k), get(ours, k), get(theirs, k), childPath, conflicts);
+            if (!isMissing(merged))
+                out[k] = merged; // omit deleted keys
+        }
+        return out;
+    }
+    // SET-ARRAY node: required / enum / type-union list, all-three-arrays.
+    if (isSetArrayPath(path) && isArrayValue(base) && isArrayValue(ours) && isArrayValue(theirs)) {
+        return mergeSetArray(base, ours, theirs);
+    }
+    // --- Atomic 3-way (scalars; non-set arrays like allOf/anyOf/oneOf/
+    // x-lifecycle.transitions; object-vs-scalar kind mismatch) -----------------
+    if (valuesEqual(base, ours))
+        return theirs; // ours unchanged → take theirs
+    if (valuesEqual(base, theirs))
+        return ours; // theirs unchanged → take ours
+    if (valuesEqual(ours, theirs))
+        return ours; // both changed the same way → converged
+    conflicts.push({ path, base, ours, theirs });
+    return ours; // leave the conflicting node as ours
+}
+/**
+ * Deterministic 3-way merge of three draft-07 schema bodies.
+ *
+ * @param base   the recorded merge baseline body
+ * @param ours   the currently-installed (locally-edited) body
+ * @param theirs the catalog's current body
+ * @returns `{ merged, conflicts }` — `merged` is the merged object (conflicting
+ *          nodes left as OURS); `conflicts` is the per-path disagreement set. The
+ *          caller writes `merged` only when `conflicts` is empty.
+ */
+export function mergeSchema(base, ours, theirs) {
+    const conflicts = [];
+    const merged = merge3(base, ours, theirs, "", conflicts);
+    // The top-level call is over three objects, so merge3 returns an object
+    // (never MISSING — the three roots are present plain objects in every
+    // caller path; a defensive empty-object fallback keeps the return typed).
+    return {
+        merged: isPlainObject(merged) ? merged : {},
+        conflicts,
+    };
+}
+//# sourceMappingURL=schema-merge.js.map

package/dist/schema-merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-merge.js","sourceRoot":"","sources":["../src/schema-merge.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@davidorex/pi-context",
-	"version": "0.30.0",
+	"version": "0.31.0",
 	"publishConfig": {
 		"access": "public"
 	},
@@ -20,6 +20,7 @@
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
 	"exports": {
+		"./package.json": "./package.json",
 		".": {
 			"types": "./dist/index.d.ts",
 			"default": "./dist/index.js"

package/samples/conception.json

@@ -327,6 +327,20 @@
       "source_kinds": ["tasks"],
       "target_kinds": ["decisions"]
     },
+    {
+      "canonical_id": "item_governed_by_convention",
+      "display_name": "governed by convention",
+      "category": "data_flow",
+      "source_kinds": ["decisions", "features", "tasks"],
+      "target_kinds": ["conventions"]
+    },
+    {
+      "canonical_id": "item_acknowledges_missing_convention",
+      "display_name": "acknowledges missing convention",
+      "category": "data_flow",
+      "source_kinds": ["decisions", "features", "tasks"],
+      "target_kinds": ["framework-gaps"]
+    },
     {
       "canonical_id": "item_derived_from_item",
       "display_name": "derived from",
@@ -479,6 +493,42 @@
       "forbid_target_bucket": "unknown",
       "severity": "warning",
       "message": "Task '{id}' is governed by a superseded or cancelled decision"
+    },
+    {
+      "id": "decision-articulates-convention",
+      "class": "requires-edge",
+      "block": "decisions",
+      "relation_types": [
+        "item_governed_by_convention",
+        "item_acknowledges_missing_convention"
+      ],
+      "direction": "as_parent",
+      "severity": "warning",
+      "message": "Decision '{id}' articulates no governing convention — add an item_governed_by_convention edge to a convention, or an item_acknowledges_missing_convention edge to a missing-convention gap"
+    },
+    {
+      "id": "feature-articulates-convention",
+      "class": "requires-edge",
+      "block": "features",
+      "relation_types": [
+        "item_governed_by_convention",
+        "item_acknowledges_missing_convention"
+      ],
+      "direction": "as_parent",
+      "severity": "warning",
+      "message": "Feature '{id}' articulates no governing convention — add an item_governed_by_convention edge to a convention, or an item_acknowledges_missing_convention edge to a missing-convention gap"
+    },
+    {
+      "id": "task-articulates-convention",
+      "class": "requires-edge",
+      "block": "tasks",
+      "relation_types": [
+        "item_governed_by_convention",
+        "item_acknowledges_missing_convention"
+      ],
+      "direction": "as_parent",
+      "severity": "warning",
+      "message": "Task '{id}' articulates no governing convention — add an item_governed_by_convention edge to a convention, or an item_acknowledges_missing_convention edge to a missing-convention gap"
     }
   ],
   "tool_operations": [],

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

@@ -3,7 +3,7 @@
   "$id": "pi-context://schemas/framework-gaps",
   "version": "1.1.1",
   "title": "Framework Gaps",
-  "description": "Capability gaps in the pi-project-workflows framework — pieces that must exist natively for the target artifact-ownership model to be expressible as configuration rather than hand-enactment. Each gap carries evidence (file + line references), impact, canonical engineering vocabulary for the missing capability, proposed resolution, and lifecycle state. Framework gaps are distinct from feature-level defects: they describe what the framework cannot yet express at all, not bugs in expressible functionality.",
+  "description": "Capability gaps in the framework — pieces that must exist natively for the target artifact-ownership model to be expressible as configuration rather than hand-enactment. Each gap carries evidence (file + line references), impact, canonical engineering vocabulary for the missing capability, proposed resolution, and lifecycle state. Framework gaps are distinct from feature-level defects: they describe what the framework cannot yet express at all, not bugs in expressible functionality.",
   "type": "object",
   "required": [
     "gaps"

package/samples/schemas/issues.schema.json

@@ -43,7 +43,7 @@
           },
           "location": {
             "type": "string",
-            "description": "File path + line number, e.g. packages/pi-workflows/src/dag.ts:219"
+            "description": "File path + line number, e.g. src/module/file.ts:NNN"
           },
           "status": {
             "type": "string",
@@ -74,7 +74,7 @@
           },
           "package": {
             "type": "string",
-            "description": "Which monorepo package this issue touches (e.g. pi-workflows, pi-project, pi-behavior-monitors)"
+            "description": "Which package/module this issue touches (e.g. package-a, package-b)"
           },
           "source": {
             "type": "string",

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