@davidorex/pi-context 0.26.0 → 0.28.1

package/samples/migrations.json

@@ -0,0 +1,133 @@
+{
+  "schema_version": "1.0.0",
+  "migrations": [
+    {
+      "schemaName": "context-contracts",
+      "fromVersion": "1.0.0",
+      "toVersion": "1.0.1",
+      "kind": "identity",
+      "created_by": "human/davidryan@gmail.com",
+      "created_at": "2026-05-31T07:48:18.891Z"
+    },
+    {
+      "schemaName": "conventions",
+      "fromVersion": "1.0.0",
+      "toVersion": "1.0.1",
+      "kind": "identity",
+      "created_by": "human/davidryan@gmail.com",
+      "created_at": "2026-05-31T07:48:18.891Z"
+    },
+    {
+      "schemaName": "decisions",
+      "fromVersion": "1.0.0",
+      "toVersion": "1.0.1",
+      "kind": "identity",
+      "created_by": "human/davidryan@gmail.com",
+      "created_at": "2026-05-31T07:48:18.891Z"
+    },
+    {
+      "schemaName": "features",
+      "fromVersion": "1.0.0",
+      "toVersion": "1.0.1",
+      "kind": "identity",
+      "created_by": "human/davidryan@gmail.com",
+      "created_at": "2026-05-31T07:48:18.892Z"
+    },
+    {
+      "schemaName": "framework-gaps",
+      "fromVersion": "1.1.0",
+      "toVersion": "1.1.1",
+      "kind": "identity",
+      "created_by": "human/davidryan@gmail.com",
+      "created_at": "2026-05-31T07:48:18.892Z"
+    },
+    {
+      "schemaName": "issues",
+      "fromVersion": "1.0.0",
+      "toVersion": "1.0.1",
+      "kind": "identity",
+      "created_by": "human/davidryan@gmail.com",
+      "created_at": "2026-05-31T07:48:18.892Z"
+    },
+    {
+      "schemaName": "layer-plans",
+      "fromVersion": "1.0.0",
+      "toVersion": "1.0.1",
+      "kind": "identity",
+      "created_by": "human/davidryan@gmail.com",
+      "created_at": "2026-05-31T07:48:18.892Z"
+    },
+    {
+      "schemaName": "phase",
+      "fromVersion": "2.0.0",
+      "toVersion": "2.0.1",
+      "kind": "identity",
+      "created_by": "human/davidryan@gmail.com",
+      "created_at": "2026-05-31T07:48:18.892Z"
+    },
+    {
+      "schemaName": "rationale",
+      "fromVersion": "1.0.0",
+      "toVersion": "1.0.1",
+      "kind": "identity",
+      "created_by": "human/davidryan@gmail.com",
+      "created_at": "2026-05-31T07:48:18.893Z"
+    },
+    {
+      "schemaName": "requirements",
+      "fromVersion": "1.0.0",
+      "toVersion": "1.0.1",
+      "kind": "identity",
+      "created_by": "human/davidryan@gmail.com",
+      "created_at": "2026-05-31T07:48:18.893Z"
+    },
+    {
+      "schemaName": "research",
+      "fromVersion": "1.0.0",
+      "toVersion": "1.0.1",
+      "kind": "identity",
+      "created_by": "human/davidryan@gmail.com",
+      "created_at": "2026-05-31T07:48:18.893Z"
+    },
+    {
+      "schemaName": "spec-reviews",
+      "fromVersion": "1.0.0",
+      "toVersion": "1.0.1",
+      "kind": "identity",
+      "created_by": "human/davidryan@gmail.com",
+      "created_at": "2026-05-31T07:48:18.893Z"
+    },
+    {
+      "schemaName": "story",
+      "fromVersion": "1.0.0",
+      "toVersion": "1.0.1",
+      "kind": "identity",
+      "created_by": "human/davidryan@gmail.com",
+      "created_at": "2026-05-31T07:48:18.893Z"
+    },
+    {
+      "schemaName": "tasks",
+      "fromVersion": "1.0.0",
+      "toVersion": "1.0.1",
+      "kind": "identity",
+      "created_by": "human/davidryan@gmail.com",
+      "created_at": "2026-05-31T07:48:18.893Z"
+    },
+    {
+      "schemaName": "verification",
+      "fromVersion": "1.0.0",
+      "toVersion": "1.0.1",
+      "kind": "identity",
+      "created_by": "human/davidryan@gmail.com",
+      "created_at": "2026-05-31T07:48:18.893Z"
+    },
+    {
+      "schemaName": "work-orders",
+      "fromVersion": "1.0.0",
+      "toVersion": "1.0.1",
+      "kind": "identity",
+      "created_by": "human/davidryan@gmail.com",
+      "created_at": "2026-05-31T07:48:18.893Z"
+    }
+  ]
+}

package/samples/schemas/context-contracts.schema.json

@@ -1,9 +1,9 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "pi-context://schemas/context-contracts",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "title": "Context contracts",
-  "description": "Per-work-unit-kind context contracts declaring which relation_types compose the execution bundle (DEC-0017 surface; FGAP-030 closure). Each contract is keyed by a plain-string unit_kind type tag (carve-out from DEC-0013's edges-only constraint — unit_kind is a type marker, not a reference to a substrate item).",
+  "description": "Per-work-unit-kind context contracts declaring which relation_types compose the execution bundle. Each contract is keyed by a plain-string unit_kind type tag (carve-out from the edges-only constraint on inter-item relationships — unit_kind is a type marker, not a reference to a substrate item).",
   "type": "object",
   "required": [
     "contracts"
@@ -29,7 +29,7 @@
           },
           "unit_kind": {
             "type": "string",
-            "description": "Type tag for the unit kind this contract composes context for (e.g. 'task', 'decision', 'verification'). Plain-string keyed lookup — NOT a substrate-block-item reference (DEC-0013 carve-out for type tags)."
+            "description": "Type tag for the unit kind this contract composes context for (e.g. 'task', 'decision', 'verification'). Plain-string keyed lookup — NOT a substrate-block-item reference (type tags are a carve-out from the edges-only constraint on inter-item relationships)."
           },
           "bundle_relation_types": {
             "type": "array",
@@ -59,7 +59,7 @@
                 },
                 "applicability_predicate": {
                   "type": "string",
-                  "description": "Optional FGAP-010 territory; reserved for relevance-scoping language."
+                  "description": "Optional relevance-scoping predicate; reserved for a future scoping language."
                 }
               }
             }
@@ -81,6 +81,21 @@
           },
           "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/conventions.schema.json

@@ -1,34 +1,90 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "pi-context://schemas/conventions",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "title": "Conventions",
   "description": "Code and process conventions the project follows. Rules with enforcement methods (lint, review, test) that agents must comply with when writing code. Injected into agent prompts as constraints.",
   "type": "object",
-  "required": ["rules"],
+  "required": [
+    "rules"
+  ],
   "properties": {
     "rules": {
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["id", "description", "enforcement", "severity"],
+        "required": [
+          "id",
+          "description",
+          "enforcement",
+          "severity"
+        ],
         "properties": {
-          "id": { "type": "string" },
-          "description": { "type": "string", "x-prompt-budget": { "tokens": 1000, "words": 800 } },
-          "enforcement": { "type": "string", "enum": ["lint", "test", "review", "manual"] },
-          "severity": { "type": "string", "enum": ["error", "warning", "info"] }
+          "id": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string",
+            "x-prompt-budget": {
+              "tokens": 1000,
+              "words": 800
+            }
+          },
+          "enforcement": {
+            "type": "string",
+            "enum": [
+              "lint",
+              "test",
+              "review",
+              "manual"
+            ]
+          },
+          "severity": {
+            "type": "string",
+            "enum": [
+              "error",
+              "warning",
+              "info"
+            ]
+          },
+          "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."
+          }
         }
       }
     },
     "test_conventions": {
       "type": "object",
-      "required": ["runner_command", "file_pattern"],
+      "required": [
+        "runner_command",
+        "file_pattern"
+      ],
       "properties": {
-        "runner_command": { "type": "string" },
-        "file_pattern": { "type": "string" }
+        "runner_command": {
+          "type": "string"
+        },
+        "file_pattern": {
+          "type": "string"
+        }
       }
     },
-    "lint_command": { "type": "string" },
-    "lint_scope": { "type": "string" }
+    "lint_command": {
+      "type": "string"
+    },
+    "lint_scope": {
+      "type": "string"
+    }
   }
 }

package/samples/schemas/decisions.schema.json

@@ -1,35 +1,61 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "pi-context://schemas/decisions",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "title": "Decisions",
   "description": "Live decision log; each entry is open, enacted, or superseded, with supporting references and intra-item options.",
   "type": "object",
-  "required": ["decisions"],
+  "required": [
+    "decisions"
+  ],
   "properties": {
     "decisions": {
       "type": "array",
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["id", "title", "status", "context", "decision", "consequences", "created_by", "created_at"],
+        "required": [
+          "id",
+          "title",
+          "status",
+          "context",
+          "decision",
+          "consequences",
+          "created_by",
+          "created_at"
+        ],
         "properties": {
-          "id": { "type": "string", "pattern": "^DEC-\\d{4}$" },
-          "title": { "type": "string" },
+          "id": {
+            "type": "string",
+            "pattern": "^DEC-\\d{4}$"
+          },
+          "title": {
+            "type": "string"
+          },
           "status": {
             "type": "string",
-            "enum": ["open", "enacted", "superseded"],
+            "enum": [
+              "open",
+              "enacted",
+              "superseded"
+            ],
             "description": "open = decision needs to be made; gates work. enacted = ratified by user authority; new constraint is in code and forward-looking constraint blocks. superseded = withdrawn without enactment; the entry was filed under proliferation pressure or on incorrect framing and is acknowledged as not-a-real-decision. Reasoning for supersession lives in consequences. Entry is preserved; not deleted."
           },
           "context": {
             "type": "string",
             "description": "Forces at play; what must be resolved and why. Grounded in citations to the forcing artifact and supporting research.",
-            "x-prompt-budget": { "tokens": 1000, "words": 800 }
+            "x-prompt-budget": {
+              "tokens": 1000,
+              "words": 800
+            }
           },
           "decision": {
             "type": "string",
             "description": "The chosen direction. Populated at creation as the proposed direction and edited if needed at the moment of enactment. Only mandate-compliant, structurally-correct candidates appear here.",
-            "x-prompt-budget": { "tokens": 1000, "words": 800 }
+            "x-prompt-budget": {
+              "tokens": 1000,
+              "words": 800
+            }
           },
           "options_considered": {
             "type": "array",
@@ -37,18 +63,36 @@
             "items": {
               "type": "object",
               "additionalProperties": false,
-              "required": ["label", "description"],
+              "required": [
+                "label",
+                "description"
+              ],
               "properties": {
-                "label": { "type": "string" },
-                "description": { "type": "string" },
-                "tradeoffs": { "type": "string" },
-                "rejected_reason": { "type": "string", "description": "Populated only post-enactment for the non-chosen options." }
+                "label": {
+                  "type": "string"
+                },
+                "description": {
+                  "type": "string"
+                },
+                "tradeoffs": {
+                  "type": "string"
+                },
+                "rejected_reason": {
+                  "type": "string",
+                  "description": "Populated only post-enactment for the non-chosen options."
+                }
               }
             }
           },
           "consequences": {
             "type": "array",
-            "items": { "type": "string", "x-prompt-budget": { "tokens": 1000, "words": 800 } },
+            "items": {
+              "type": "string",
+              "x-prompt-budget": {
+                "tokens": 1000,
+                "words": 800
+              }
+            },
             "description": "What follows from the decision if enacted — what becomes easier, harder, or impossible; which constraint blocks or code files change."
           },
           "references": {
@@ -57,31 +101,84 @@
             "items": {
               "type": "object",
               "additionalProperties": false,
-              "required": ["label"],
+              "required": [
+                "label"
+              ],
               "properties": {
-                "label": { "type": "string" },
-                "path": { "type": "string" },
-                "lines": { "type": "string" },
-                "commit": { "type": "string" }
+                "label": {
+                  "type": "string"
+                },
+                "path": {
+                  "type": "string"
+                },
+                "lines": {
+                  "type": "string"
+                },
+                "commit": {
+                  "type": "string"
+                }
               }
             }
           },
-          "created_by": { "type": "string" },
-          "created_at": { "type": "string" },
-          "enacted_by": { "type": "string", "description": "User identifier; populated on status transition to enacted. Requires user authority." },
-          "enacted_at": { "type": "string" }
+          "created_by": {
+            "type": "string"
+          },
+          "created_at": {
+            "type": "string"
+          },
+          "enacted_by": {
+            "type": "string",
+            "description": "User identifier; populated on status transition to enacted. Requires user authority."
+          },
+          "enacted_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."
+          }
         }
       }
     }
   },
   "x-lifecycle": {
     "field": "status",
-    "states": ["open", "enacted", "superseded"],
+    "states": [
+      "open",
+      "enacted",
+      "superseded"
+    ],
     "transitions": [
-      { "from": "open", "to": "enacted", "required_authority": "user", "note": "Enactment updates forward-looking constraint blocks and lands code change; entry is NOT removed on enactment." },
-      { "from": "enacted", "to": "open", "required_authority": "user", "note": "Reopening for revision; creates a new open state on the existing entry rather than a new entry. Alternative pattern: create a new decision entry with a decision_supersedes_decision edge referencing this one." },
-      { "from": "open", "to": "superseded", "required_authority": "user", "note": "Withdrawal of an entry that was filed under proliferation pressure or on incorrect framing. Reasoning lives in consequences. Used when the entry is acknowledged as not-a-real-decision rather than enacted." }
+      {
+        "from": "open",
+        "to": "enacted",
+        "required_authority": "user",
+        "note": "Enactment updates forward-looking constraint blocks and lands code change; entry is NOT removed on enactment."
+      },
+      {
+        "from": "enacted",
+        "to": "open",
+        "required_authority": "user",
+        "note": "Reopening for revision; creates a new open state on the existing entry rather than a new entry. Alternative pattern: create a new decision entry with a decision_supersedes_decision edge referencing this one."
+      },
+      {
+        "from": "open",
+        "to": "superseded",
+        "required_authority": "user",
+        "note": "Withdrawal of an entry that was filed under proliferation pressure or on incorrect framing. Reasoning lives in consequences. Used when the entry is acknowledged as not-a-real-decision rather than enacted."
+      }
     ],
-    "note": "Three-state lifecycle. AJV draft-07 cannot enforce transition validity or required_authority; this block is metadata for future framework-level state-machine validation (FGAP-005) and authorship attestation (FGAP-004)."
+    "note": "Three-state lifecycle. AJV draft-07 cannot enforce transition validity or required_authority; this block is metadata reserved for future framework-level state-machine validation and authorship attestation."
   }
 }