@davidorex/pi-context 0.31.0 → 0.33.0

package/samples/migrations.json

@@ -128,6 +128,14 @@
       "kind": "identity",
       "created_by": "human/davidryan@gmail.com",
       "created_at": "2026-05-31T07:48:18.893Z"
+    },
+    {
+      "schemaName": "config",
+      "fromVersion": "1.0.0",
+      "toVersion": "1.8.0",
+      "kind": "identity",
+      "created_by": "human/davidryan@gmail.com",
+      "created_at": "2026-07-02T00:00:00.000Z"
     }
   ]
 }

package/samples/schemas/context-contracts.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."
+    },
     "contracts": {
       "type": "array",
       "items": {

package/samples/schemas/conventions.schema.json

@@ -9,6 +9,10 @@
     "rules"
   ],
   "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."
+    },
     "rules": {
       "type": "array",
       "items": {

package/samples/schemas/decisions.schema.json

@@ -9,6 +9,10 @@
     "decisions"
   ],
   "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."
+    },
     "decisions": {
       "type": "array",
       "items": {

package/samples/schemas/features.schema.json

@@ -9,6 +9,10 @@
     "features"
   ],
   "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."
+    },
     "features": {
       "type": "array",
       "items": {

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

@@ -9,6 +9,10 @@
     "gaps"
   ],
   "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."
+    },
     "gaps": {
       "type": "array",
       "items": {
@@ -97,6 +101,11 @@
                     "tokens": 1000,
                     "words": 800
                   }
+                },
+                "content_pin": {
+                  "type": "string",
+                  "pattern": "^[0-9a-f]{64}$",
+                  "description": "SHA-256 of the referenced file at write time. Stamped by the write path when `file` names a readable file OUTSIDE the substrate dir (substrate-internal paths are living state, never pinned) and no pin exists; context-validate flags a pinned evidence entry whose current file hash drifted (anchor drift — re-review, never rewritten)."
                 }
               }
             }

package/samples/schemas/issues.schema.json

@@ -9,6 +9,10 @@
     "issues"
   ],
   "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."
+    },
     "issues": {
       "type": "array",
       "items": {
@@ -90,6 +94,10 @@
             "type": "string",
             "description": "Commit message or reference if resolved"
           },
+          "resolved_at": {
+            "type": "string",
+            "description": "ISO-8601 timestamp when the issue was resolved"
+          },
           "oid": {
             "type": "string",
             "pattern": "^[0-9a-f]{32}$",
@@ -108,5 +116,25 @@
         }
       }
     }
+  },
+  "x-lifecycle": {
+    "field": "status",
+    "states": [
+      "open",
+      "resolved",
+      "deferred"
+    ],
+    "transitions": [
+      {
+        "from": "open",
+        "to": "resolved",
+        "required_authority": "any"
+      },
+      {
+        "from": "open",
+        "to": "deferred",
+        "required_authority": "user"
+      }
+    ]
   }
 }

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

@@ -9,6 +9,10 @@
     "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": {

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": {
@@ -140,9 +144,43 @@
           "stale_conditions": {
             "type": "array",
             "items": {
-              "type": "string"
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["kind", "item", "bucket"],
+                  "properties": {
+                    "kind": { "const": "item-status" },
+                    "item": { "type": "string", "description": "Selector of the substrate item whose status this condition watches (a reference predicate, not an embedded entity — deliberately not named 'id')." },
+                    "bucket": { "type": "string", "description": "Status bucket that fires the condition when the watched item's status maps to it." }
+                  }
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["kind", "path"],
+                  "properties": {
+                    "kind": { "const": "file-changed" },
+                    "path": { "type": "string", "description": "Project-root-relative path whose content change fires the condition." },
+                    "baseline_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the file at grounding time. Stamped by the write path when absent and the file is readable; the condition fires when the current hash differs (or the file is gone)." }
+                  }
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["kind", "ref"],
+                  "properties": {
+                    "kind": { "const": "revision-moved" },
+                    "ref": { "type": "string", "description": "Git ref whose movement fires the condition." },
+                    "baseline_sha": { "type": "string", "description": "Commit the ref pointed at when grounding was current. Stamped by the write path when absent and the ref resolves; the condition fires when the ref moves." }
+                  }
+                }
+              ]
             },
-            "description": "Explicit list of conditions under which the research is no longer authoritative. A future staleness engine will read this to transition status from complete to stale automatically."
+            "description": "Conditions under which the research is no longer authoritative. Bare strings are human-judged only. Typed variants are machine-evaluated: context-validate flags a complete item whose condition fired as a staleness candidate, and context-reconcile (or a human) applies the complete-to-stale transition — never silently."
           },
           "citations": {
             "type": "array",
@@ -168,6 +206,11 @@
                 },
                 "retrieved_at": {
                   "type": "string"
+                },
+                "content_pin": {
+                  "type": "string",
+                  "pattern": "^[0-9a-f]{64}$",
+                  "description": "SHA-256 of the cited file at write time. Stamped by the write path when `path` names a readable file OUTSIDE the substrate dir (substrate-internal paths are living state, never pinned) and no pin exists; context-validate flags a pinned citation whose current file hash drifted."
                 }
               }
             }

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

@@ -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."
+    },
     "work_orders": {
       "type": "array",
       "items": {

package/schemas/config.schema.json

@@ -1,9 +1,9 @@
 {
 	"$schema": "http://json-schema.org/draft-07/schema#",
 	"$id": "pi-context://schemas/config",
-	"version": "1.6.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,13 +158,14 @@
 					"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." }
 				}
 			}
 		},
 		"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. 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), status-consistency (an item's status bucket must/must-not co-occur with a related item's status bucket across an edge), or derived-status (a rollup-declared kind's stored status must equal its derived membership-rollup status, both directions).",
 			"items": {
 				"oneOf": [
 					{
@@ -125,6 +199,18 @@
 							"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." }
 						}
+					},
+					{
+						"type": "object",
+						"required": ["id", "class", "block"],
+						"additionalProperties": false,
+						"properties": {
+							"id": { "type": "string", "description": "Stable invariant id, surfaced in diagnostics + the issue code field." },
+							"class": { "type": "string", "const": "derived-status", "description": "Invariant class: for a block kind whose status is mechanically derivable (declared via state_derivation.rollups), each item's STORED status must equal its DERIVED membership-rollup status. Divergence in EITHER direction (stored behind or ahead of the derivation) violates. A declaration naming a block with no matching rollups entry is inert." },
+							"block": { "type": "string", "description": "Data-file basename of the rollup block kind whose items the invariant ranges over (must match a state_derivation.rollups[].kind to have effect)." },
+							"severity": { "type": "string", "enum": ["error", "warning"], "default": "warning", "description": "Diagnostic severity on divergence. Defaults to warning: until write-time convergence and the reconcile repair path operate on a substrate, stored/derived divergence is expected steady state, not a write-blocking error." },
+							"message": { "type": "string", "description": "Optional message template. Tokens {id}, {block}, {stored} and {derived} substitute. Absent → generic default." }
+						}
 					}
 				]
 			}