@davidorex/pi-context 0.26.0 → 0.28.0

package/samples/schemas/verification.schema.json

@@ -1,34 +1,92 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "pi-context://schemas/verification",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "title": "Verification",
   "description": "Evidence that work meets its criteria. Per-item completion evidence linking implementation to acceptance via a verification_verifies_item edge.",
   "type": "object",
-  "required": ["verifications"],
+  "required": [
+    "verifications"
+  ],
   "properties": {
     "verifications": {
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["id", "status", "method"],
+        "required": [
+          "id",
+          "status",
+          "method"
+        ],
         "properties": {
-          "id": { "type": "string", "pattern": "^VER-\\d{3,}$" },
-          "status": { "type": "string", "enum": ["passed", "failed", "partial", "skipped"] },
-          "method": { "type": "string", "enum": ["command", "inspect", "test"] },
-          "evidence": { "type": "string", "description": "What was checked and what was found" },
-          "timestamp": { "type": "string" },
+          "id": {
+            "type": "string",
+            "pattern": "^VER-\\d{3,}$"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "passed",
+              "failed",
+              "partial",
+              "skipped"
+            ]
+          },
+          "method": {
+            "type": "string",
+            "enum": [
+              "command",
+              "inspect",
+              "test"
+            ]
+          },
+          "evidence": {
+            "type": "string",
+            "description": "What was checked and what was found"
+          },
+          "timestamp": {
+            "type": "string"
+          },
           "criteria_results": {
             "type": "array",
             "items": {
               "type": "object",
-              "required": ["criterion", "status"],
+              "required": [
+                "criterion",
+                "status"
+              ],
               "properties": {
-                "criterion": { "type": "string" },
-                "status": { "type": "string", "enum": ["passed", "failed", "skipped"] },
-                "evidence": { "type": "string" }
+                "criterion": {
+                  "type": "string"
+                },
+                "status": {
+                  "type": "string",
+                  "enum": [
+                    "passed",
+                    "failed",
+                    "skipped"
+                  ]
+                },
+                "evidence": {
+                  "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/work-orders.schema.json

@@ -0,0 +1,195 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$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.",
+  "type": "object",
+  "required": [
+    "work_orders"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "work_orders": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "title",
+          "status",
+          "target_agent",
+          "input_contract",
+          "context_blocks",
+          "output_contract",
+          "scope",
+          "real_check_criteria"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^WO-\\d{3,}$",
+            "description": "Canonical work-order id; WO-NNN uppercase + 3-digit zero-padded suffix."
+          },
+          "title": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "proposed",
+              "in-progress",
+              "real-check-passed",
+              "real-check-failed",
+              "completed",
+              "cancelled"
+            ],
+            "description": "Work-order lifecycle. Includes the real-check verdict states (real-check-passed / real-check-failed) — deterministic verification, never LLM self-report."
+          },
+          "target_agent": {
+            "type": "string",
+            "description": "Name of the privileged JIT-agent that consumes this work-order; resolves to <name>.agent.yaml in the agents tier."
+          },
+          "input_contract": {
+            "type": "object",
+            "description": "Typed JSON Schema describing what the agent receives as input at dispatch time."
+          },
+          "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).",
+            "items": {
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "name"
+                  ],
+                  "properties": {
+                    "name": {
+                      "type": "string"
+                    },
+                    "item": {
+                      "type": "string"
+                    },
+                    "depth": {
+                      "type": "integer",
+                      "minimum": 0
+                    },
+                    "focus": {
+                      "type": "object",
+                      "additionalProperties": {
+                        "type": "string"
+                      }
+                    }
+                  }
+                }
+              ]
+            }
+          },
+          "output_contract": {
+            "type": "object",
+            "description": "Typed JSON Schema describing the agent's return contract."
+          },
+          "scope": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Bounds within which the agent may make edits / run commands. Used by the capability composer to clamp the agent's grant at dispatch.",
+            "properties": {
+              "files": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "directories": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "operations": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "real_check_criteria": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "build_check_test"
+            ],
+            "description": "Deterministic real-check criteria gating acceptance. NEVER LLM self-report; verdict comes from deterministic real checks the agent cannot fake.",
+            "properties": {
+              "build_check_test": {
+                "type": "boolean",
+                "description": "Whether build+check+test exit-code gate applies (typically true)."
+              },
+              "runtime_demo": {
+                "type": "object",
+                "description": "Runtime demonstration command + expected outcome string-match.",
+                "properties": {
+                  "invocation": {
+                    "type": "string"
+                  },
+                  "expected": {
+                    "type": "string"
+                  }
+                }
+              },
+              "adversarial_probe": {
+                "type": "object",
+                "description": "Adversarial-probe target list — what artifacts a fresh-context agent should re-verify (deterministic real checks; never LLM self-report).",
+                "properties": {
+                  "targets": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "description": {
+            "type": "string"
+          },
+          "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/schemas/bootstrap.schema.json

@@ -1,22 +1,34 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "pi-context://schemas/bootstrap",
-  "version": "1.0.0",
-  "title": "pi-context bootstrap pointer",
-  "description": "Per-cwd bootstrap pointer at <cwd>/.pi-context.json declaring the substrate dir name. Read by resolveContextDir(cwd) before any substrate operation; substrate dir is config-driven per DEC-0015 (no hardcoded substrate-dir paths anywhere in pi-context, pi-jit-agents, pi-workflows, pi-behavior-monitors). Atomic-safety mechanism per FGAP-026 closure phase 1.1: written for legacy .project/-using repos containing {contextDir: '.project'} so substrate stays reachable when Phase 1.2 lands resolveContextDir replacing PROJECT_DIR + SCHEMAS_DIR constants. For new repos: written by /context init (prompt-required for dirName per DEC-0015; defaulting reintroduces hardcode-dressed-as-default this DEC rejects). Mutable post-init via /context migrate (Phase 10 of FGAP-026 closure) which atomically renames the dir + rewrites this pointer + updates config.root.",
+  "version": "1.1.0",
+ "title": "pi-context bootstrap pointer",
+ "description": "Per-cwd bootstrap pointer at <cwd>/.pi-context.json declaring the substrate dir name. Read by resolveContextDir(cwd) before any substrate operation; substrate dir is config-driven (no hardcoded substrate-dir paths anywhere in pi-context, pi-jit-agents, pi-workflows, pi-behavior-monitors). Written for legacy .project/-using repos containing {contextDir: '.project'} so substrate stays reachable across the resolver-replacement migration. For new repos: written by /context init (prompt-required for dirName; defaulting reintroduces hardcode-dressed-as-default). Mutable post-init via /context switch which atomically rewrites this pointer + stamps previous_contextDir + switched_at + switched_by supporting bidirectional pointer-flip (parallel to git switch). Schema bump 1.0.0 -> 1.1.0 adds three optional pointer-history fields; older 1.0.0 pointers remain valid (required: ['contextDir'] unchanged; missing optional fields resolve to undefined in-process).",
   "type": "object",
   "properties": {
     "contextDir": {
       "type": "string",
-      "description": "Directory name (relative to cwd) where the substrate lives. User-decided at /context init time per DEC-0015. For pre-existing repos using legacy .project/ convention, value is '.project' until /context migrate runs."
+ "description": "Directory name (relative to cwd) where the substrate lives. User-decided at /context init time. For pre-existing repos using legacy .project/ convention, value is '.project' until /context switch -c <new-dir> runs."
     },
     "version": {
       "type": "string",
-      "description": "Bootstrap pointer format version. '1.0.0' for the initial format. Future format changes increment via semver per FGAP-006 schema versioning discipline; migration registry handles transitions if breaking."
+ "description": "Bootstrap pointer format version. '1.0.0' for the initial format; '1.1.0' once the pointer-history fields (previous_contextDir, switched_at, switched_by) are populated by /context switch family. Future format changes increment via semver schema versioning discipline; migration registry handles transitions if breaking."
     },
     "created_at": {
       "type": "string",
-      "description": "ISO 8601 timestamp when the bootstrap pointer was first written. Forensic; helps trace when the substrate was bootstrapped for this repo."
+ "description": "ISO 8601 timestamp when the bootstrap pointer was first written. Forensic; helps trace when the substrate was bootstrapped for this repo. Preserved across /context switch operations (only switched_at + switched_by + previous_contextDir mutate on pointer-flip)."
+    },
+    "previous_contextDir": {
+      "type": "string",
+ "description": "ISO 8601 sibling: the contextDir value that this pointer carried IMMEDIATELY BEFORE the most-recent /context switch operation. Populated by flipBootstrapPointer; absent on freshly-bootstrapped pointers that have never been switched. Read by /context switch - to flip back to the prior substrate (parallel to git switch -)."
+    },
+    "switched_at": {
+      "type": "string",
+ "description": "ISO 8601 timestamp of the most-recent /context switch invocation that produced the current contextDir. Absent on freshly-bootstrapped pointers; populated by flipBootstrapPointer on every flip."
+    },
+    "switched_by": {
+      "type": "string",
+ "description": "Writer identity (verified terminal-operator stamped by auth-gate on confirm) attached to the most-recent /context switch invocation. Forensic; pairs with switched_at to attribute the pointer-flip. Absent on freshly-bootstrapped pointers."
     }
   },
   "required": ["contextDir"],

package/schemas/config.schema.json

@@ -1,9 +1,9 @@
 {
 	"$schema": "http://json-schema.org/draft-07/schema#",
 	"$id": "pi-context://schemas/config",
-	"version": "1.4.0",
+	"version": "1.5.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. Closes FGAP-001 (hierarchical block storage), FGAP-013 (status vocabulary registry), issue-089 class (PLAN- prefix collision) by making registries config-driven from line 1.",
+	"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",
 	"required": ["schema_version", "block_kinds"],
 	"additionalProperties": false,
@@ -11,11 +11,16 @@
 		"schema_version": {
 			"type": "string",
 			"pattern": "^\\d+\\.\\d+\\.\\d+$",
-			"description": "Semver of this config schema. Surfaces FGAP-006 at the meta-layer."
+			"description": "Semver of this config schema. Surfaces the schema-versioning gateway at the meta-layer."
 		},
 		"root": {
 			"type": "string",
-			"description": "Optional substrate-dir override. The substrate-dir name is set at /context init and recorded in the .pi-context.json bootstrap pointer (DEC-0015 — no shipped default); adoptConception writes this field at /context accept-all from the init-chosen dir. When absent, projectRoot resolves the substrate via the pointer (resolveContextDir). Not shipped by the packaged conception, which is a template. Closes GitHub issue #3 surface — relocatable per config."
+			"description": "Optional substrate-dir override. The substrate-dir name is set at /context init and recorded in the .pi-context.json bootstrap pointer; adoptConception writes this field at /context accept-all from the init-chosen dir. When absent, projectRoot resolves the substrate via the pointer (resolveContextDir). Not shipped by the packaged conception, which is a template. Relocatable per config."
+		},
+		"substrate_id": {
+			"type": "string",
+			"pattern": "^sub-[0-9a-f]{16}$",
+			"description": "Per-substrate root identity for content-addressed substrate identity (Cycle 3). Salts mintOid so item OIDs are distinct across substrates. Minted once via mintSubstrateId at /context init (Cycle 4) — established by hand for the active substrate + packaged samples this cycle — then immutable on disk; never re-minted on an item write. substrateIdForDir reads this field and throws loudly when absent (no degraded fallback)."
 		},
 		"naming": {
 			"type": "object",
@@ -24,7 +29,7 @@
 		},
 		"layers": {
 			"type": "array",
-			"description": "Work-altitude tier registry (L1..L5 or user-defined). FGAP-016 layer registry surface.",
+			"description": "Work-altitude tier registry (L1..L5 or user-defined). Layer registry surface.",
 			"items": {
 				"type": "object",
 				"required": ["id", "display_name"],
@@ -46,7 +51,7 @@
 				"properties": {
 					"canonical_id": { "type": "string", "description": "Opaque identifier (e.g. 'decisions-block')" },
 					"display_name": { "type": "string", "description": "Mutable user-facing label (e.g. 'Design Decisions')" },
-					"prefix": { "type": "string", "description": "Id-prefix token (e.g. 'DEC-'). Empty string is valid for slug-id blocks (e.g. conventions) that do not use prefix+number ids — such blocks are excluded from prefix-based id resolution (FGAP-062)." },
+					"prefix": { "type": "string", "description": "Id-prefix token (e.g. 'DEC-'). Empty string is valid for slug-id blocks (e.g. conventions) that do not use prefix+number ids — such blocks are excluded from prefix-based id resolution." },
 					"schema_path": { "type": "string", "description": "Relative path to schema file" },
 					"array_key": { "type": "string", "description": "Top-level array property in block JSON" },
 					"data_path": { "type": "string", "description": "Relative path to block data file" },
@@ -56,7 +61,7 @@
 		},
 		"status_buckets": {
 			"type": "object",
-			"description": "Per-project status normalization. Maps raw status string → bucket. FGAP-013 closure surface.",
+			"description": "Per-project status normalization. Maps raw status string → bucket.",
 			"additionalProperties": {
 				"type": "string",
 				"enum": ["complete", "in_progress", "blocked", "todo", "unknown"]
@@ -69,7 +74,7 @@
 		},
 		"relation_types": {
 			"type": "array",
-			"description": "Canonical relation_type registry (DEC-0013 single-source-of-truth pattern).",
+			"description": "Canonical relation_type registry.",
 			"items": {
 				"type": "object",
 				"required": ["canonical_id", "display_name", "category"],
@@ -86,7 +91,7 @@
 		},
 		"invariants": {
 			"type": "array",
-			"description": "Config-declared substrate invariants enforced generically by validateProject. Each names block kinds / relation_types / status values purely as DATA — no vocabulary literal lives in source (DEC-0025). User-overridable: a project ships only the invariants its conception requires. Discriminated by `class`: requires-edge (item must occupy an endpoint on ≥1 edge of a given relation_type) or status-consistency (an item's status bucket must/must-not co-occur with a related item's status bucket across an edge).",
+			"description": "Config-declared substrate invariants enforced generically by validateProject. Each names block kinds / relation_types / status values purely as DATA — no vocabulary literal lives in source. User-overridable: a project ships only the invariants its conception requires. Discriminated by `class`: requires-edge (item must occupy an endpoint on ≥1 edge of a given relation_type) or status-consistency (an item's status bucket must/must-not co-occur with a related item's status bucket across an edge).",
 			"items": {
 				"oneOf": [
 					{
@@ -94,14 +99,14 @@
 						"required": ["id", "class", "block", "relation_types", "direction"],
 						"additionalProperties": false,
 						"properties": {
-							"id":           { "type": "string", "description": "Stable invariant id, surfaced in diagnostics + the issue code field." },
-							"class":        { "type": "string", "const": "requires-edge", "description": "Invariant class: qualifying items must occupy an endpoint on an edge of one of relation_types." },
-							"block":        { "type": "string", "description": "Data-file basename of the block whose items the invariant ranges over (matched against ItemLocation.block)." },
-							"where":        { "type": "object", "description": "Optional field-equality predicate. Item qualifies only when EVERY (field,value) matches item[field] === value. Absent → all items qualify.", "additionalProperties": { "type": ["string", "number", "boolean"] } },
+							"id": { "type": "string", "description": "Stable invariant id, surfaced in diagnostics + the issue code field." },
+							"class": { "type": "string", "const": "requires-edge", "description": "Invariant class: qualifying items must occupy an endpoint on an edge of one of relation_types." },
+							"block": { "type": "string", "description": "Data-file basename of the block whose items the invariant ranges over (matched against ItemLocation.block)." },
+							"where": { "type": "object", "description": "Optional field-equality predicate. Item qualifies only when EVERY (field,value) matches item[field] === value. Absent → all items qualify.", "additionalProperties": { "type": ["string", "number", "boolean"] } },
 							"relation_types": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "canonical_ids of relation_types that satisfy the invariant. Qualifying item passes if ≥1 incident edge (in direction) has relation_type in this set." },
-							"direction":    { "type": "string", "enum": ["as_parent", "as_child"], "description": "Which endpoint the qualifying item must occupy. as_parent → item.id === edge.parent; as_child → item.id === edge.child." },
-							"severity":     { "type": "string", "enum": ["error", "warning"], "default": "error", "description": "Diagnostic severity when unsatisfied." },
-							"message":      { "type": "string", "description": "Optional message template. Tokens {id} and {block} substitute. Absent → generic default." }
+							"direction": { "type": "string", "enum": ["as_parent", "as_child"], "description": "Which endpoint the qualifying item must occupy. as_parent → item.id === edge.parent; as_child → item.id === edge.child." },
+							"severity": { "type": "string", "enum": ["error", "warning"], "default": "error", "description": "Diagnostic severity when unsatisfied." },
+							"message": { "type": "string", "description": "Optional message template. Tokens {id} and {block} substitute. Absent → generic default." }
 						}
 					},
 					{
@@ -109,16 +114,16 @@
 						"required": ["id", "class", "block", "relation_types", "direction"],
 						"additionalProperties": false,
 						"properties": {
-							"id":           { "type": "string", "description": "Stable invariant id, surfaced in diagnostics + the issue code field." },
-							"class":        { "type": "string", "const": "status-consistency", "description": "Invariant class: a qualifying item's status bucket must (require_target_bucket) or must-not (forbid_target_bucket) co-occur with a related item's status bucket across an incident edge." },
-							"block":        { "type": "string", "description": "Data-file basename of the block whose items the invariant ranges over (matched against ItemLocation.block)." },
+							"id": { "type": "string", "description": "Stable invariant id, surfaced in diagnostics + the issue code field." },
+							"class": { "type": "string", "const": "status-consistency", "description": "Invariant class: a qualifying item's status bucket must (require_target_bucket) or must-not (forbid_target_bucket) co-occur with a related item's status bucket across an incident edge." },
+							"block": { "type": "string", "description": "Data-file basename of the block whose items the invariant ranges over (matched against ItemLocation.block)." },
 							"relation_types": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "canonical_ids of relation_types whose edges are inspected for the related (target) item." },
-							"direction":    { "type": "string", "enum": ["as_parent", "as_child"], "description": "Which endpoint the qualifying item occupies on the inspected edge; the target item is the other endpoint." },
-							"when_bucket":  { "type": "string", "enum": ["complete", "in_progress", "blocked", "todo", "unknown"], "description": "Optional gate: only items whose own status bucket equals this are checked. Absent → all items in block are checked." },
+							"direction": { "type": "string", "enum": ["as_parent", "as_child"], "description": "Which endpoint the qualifying item occupies on the inspected edge; the target item is the other endpoint." },
+							"when_bucket": { "type": "string", "enum": ["complete", "in_progress", "blocked", "todo", "unknown"], "description": "Optional gate: only items whose own status bucket equals this are checked. Absent → all items in block are checked." },
 							"require_target_bucket": { "type": "string", "enum": ["complete", "in_progress", "blocked", "todo", "unknown"], "description": "Violation when the target item's status bucket differs from this. Mutually exclusive with forbid_target_bucket at runtime." },
-							"forbid_target_bucket":  { "type": "string", "enum": ["complete", "in_progress", "blocked", "todo", "unknown"], "description": "Violation when the target item's status bucket equals this. Mutually exclusive with require_target_bucket at runtime." },
-							"severity":     { "type": "string", "enum": ["error", "warning"], "default": "error", "description": "Diagnostic severity when violated." },
-							"message":      { "type": "string", "description": "Optional message template. Tokens {id} and {block} substitute. Absent → generic default." }
+							"forbid_target_bucket": { "type": "string", "enum": ["complete", "in_progress", "blocked", "todo", "unknown"], "description": "Violation when the target item's status bucket equals this. Mutually exclusive with require_target_bucket at runtime." },
+							"severity": { "type": "string", "enum": ["error", "warning"], "default": "error", "description": "Diagnostic severity when violated." },
+							"message": { "type": "string", "description": "Optional message template. Tokens {id} and {block} substitute. Absent → generic default." }
 						}
 					}
 				]
@@ -181,13 +186,40 @@
 		},
 		"installed_schemas": {
 			"type": "array",
-			"description": "Schemas the project has opted into via /context install (DEC-0011).",
+			"description": "Schemas the project has opted into via /context install.",
 			"items": { "type": "string" }
 		},
 		"installed_blocks": {
 			"type": "array",
-			"description": "Blocks the project has opted into via /context install (DEC-0011).",
+			"description": "Blocks the project has opted into via /context install.",
 			"items": { "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.",
+			"items": {
+				"type": "object",
+				"additionalProperties": false,
+				"required": ["canonical_id"],
+				"properties": {
+					"canonical_id": { "type": "string" },
+					"display_name": { "type": "string" },
+					"category": { "type": "string" },
+					"kind": {
+						"type": "string",
+						"description": "Composite-tool KIND identifier. When present, composite-loader binds instance_params to the named KIND library function and registers a per-instance Pi tool."
+					},
+					"instance_params": {
+						"type": "object",
+						"description": "Instance-scoped parameters — fixed at registration time, closure-bound by composite-loader. Runtime callsites cannot widen scope."
+					}
+				}
+			}
+		},
+		"tool_operations_forbidden": {
+			"type": "array",
+			"items": { "type": "string" },
+			"description": "Project-specific operation tokens forbidden from registration as composite operations (extends framework FORBIDDEN_WHOLESALE_OPERATIONS list — L5 project layer; gated by author-tool-grant Pi tool writer.kind=human)."
 		}
 	}
 }

package/schemas/context-registry.schema.json

@@ -0,0 +1,46 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$id": "pi-context://schemas/context-registry",
+	"version": "1.0.0",
+	"title": "pi-context project-root substrate registry",
+	"description": "Project-root locator file (<cwd>/.pi-context-registry.json) mapping each substrate's content-addressed substrate_id to its on-disk directory + alias list. Distinct from the per-substrate .pi-context.json bootstrap pointer: the pointer names the ACTIVE substrate dir, whereas this registry enumerates EVERY known substrate by its immutable substrate_id so a foreign <substrate_id>:<oid> / <alias>:<refname> locator can be resolved to a directory (Cycle-8 F2 resolver consumer). Written via registerSubstrate (upsert). The SoT-drift invariant in validateContext requires the active config.substrate_id to have an entry here whose dir resolves to the active substrate.",
+	"type": "object",
+	"required": ["version", "substrates"],
+	"additionalProperties": false,
+	"properties": {
+		"version": {
+			"type": "string",
+			"description": "Schema version of this registry file itself. Tracks REGISTRY_FILE_VERSION in context-registry.ts; decoupled from any individual substrate's identity or schema versions."
+		},
+		"substrates": {
+			"type": "object",
+			"description": "Map keyed by substrate_id (^sub-[0-9a-f]{16}$). Each value carries the substrate's directory (relative to the project root) + its alias list.",
+			"propertyNames": {
+				"pattern": "^sub-[0-9a-f]{16}$"
+			},
+			"additionalProperties": {
+				"$ref": "#/definitions/RegistryEntry"
+			}
+		}
+	},
+	"definitions": {
+		"RegistryEntry": {
+			"type": "object",
+			"required": ["dir", "aliases"],
+			"additionalProperties": false,
+			"properties": {
+				"dir": {
+					"type": "string",
+					"description": "Substrate directory. Resolved against the project root (path.resolve(cwd, dir)) when matched against the active substrate. Typically a project-root-relative bare dir name (e.g. '.context-jit-spec-v2')."
+				},
+				"aliases": {
+					"type": "array",
+					"description": "Human-facing alternate locators for this substrate (e.g. the legacy 'project' alias populated by the Phase-H migration). resolveAlias scans these to recover the substrate_id. Empty until aliases are assigned.",
+					"items": {
+						"type": "string"
+					}
+				}
+			}
+		}
+	}
+}