@davidorex/pi-context 0.30.0 → 0.32.0

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

@@ -3,12 +3,16 @@
   "$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"
   ],
   "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Semver of the block schema this envelope was last written against. Stamped by the write path to the schema's current version; when it differs from the installed schema's version, the read/write gates walk the block through the registered migration chain (or fail loud when no chain reaches the current version). Absent on blocks not yet written by a stamping write path."
+    },
     "plans": {
       "type": "array",
       "items": {
@@ -45,7 +49,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/milestone.schema.json

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

package/samples/schemas/phase.schema.json

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

package/samples/schemas/rationale.schema.json

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

package/samples/schemas/requirements.schema.json

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

package/samples/schemas/research.schema.json

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

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

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

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

package/samples/schemas/story.schema.json

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

package/samples/schemas/tasks.schema.json

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

package/samples/schemas/verification.schema.json

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

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

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

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