@davidorex/pi-context 0.26.0 → 0.28.0

package/samples/schemas/research.schema.json

@@ -1,55 +1,106 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "pi-context://schemas/research",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "title": "Research",
   "description": "Factual and analytical substrate under decisions — each entry captures what was investigated, how, what was found, what grounds the findings, and what stale conditions invalidate them.",
   "type": "object",
-  "required": ["research"],
+  "required": [
+    "research"
+  ],
   "properties": {
     "research": {
       "type": "array",
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["id", "title", "status", "layer", "type", "question", "method", "findings_summary", "created_by", "created_at"],
+        "required": [
+          "id",
+          "title",
+          "status",
+          "layer",
+          "type",
+          "question",
+          "method",
+          "findings_summary",
+          "created_by",
+          "created_at"
+        ],
         "properties": {
-          "id": { "type": "string", "pattern": "^R-\\d{4}$" },
-          "title": { "type": "string" },
+          "id": {
+            "type": "string",
+            "pattern": "^R-\\d{4}$"
+          },
+          "title": {
+            "type": "string"
+          },
           "status": {
             "type": "string",
-            "enum": ["planned", "in-progress", "complete", "stale", "superseded", "revised"],
+            "enum": [
+              "planned",
+              "in-progress",
+              "complete",
+              "stale",
+              "superseded",
+              "revised"
+            ],
             "description": "planned = question framed, method chosen, no work started. in-progress = investigation underway. complete = findings_summary and citations finalized. stale = a stale_condition fired; findings may still be correct but grounding is no longer authoritative. superseded = a newer research entry replaces this one. revised = transient state during re-investigation against updated grounding."
           },
           "layer": {
             "type": "string",
-            "enum": ["L1", "L2", "L3", "L4", "L5"],
+            "enum": [
+              "L1",
+              "L2",
+              "L3",
+              "L4",
+              "L5"
+            ],
             "description": "Which Muni layer the research informs. L1 identity/domain; L2 specification; L3 work; L4 execution; L5 memory."
           },
           "type": {
             "type": "string",
-            "enum": ["investigative", "comparative", "empirical", "historical", "audit", "landscape", "feasibility", "curation"],
+            "enum": [
+              "investigative",
+              "comparative",
+              "empirical",
+              "historical",
+              "audit",
+              "landscape",
+              "feasibility",
+              "curation"
+            ],
             "description": "Kind of research, per the research:* skill taxonomy. Affects reliability characteristics and staleness behavior."
           },
           "question": {
             "type": "string",
             "description": "The question being investigated.",
-            "x-prompt-budget": { "tokens": 1000, "words": 800 }
+            "x-prompt-budget": {
+              "tokens": 1000,
+              "words": 800
+            }
           },
           "method": {
             "type": "string",
             "description": "How the investigation was conducted — e.g. 'code-inspection', 'empirical-test', 'web-fetch', 'curation of external document', or a combination.",
-            "x-prompt-budget": { "tokens": 1000, "words": 800 }
+            "x-prompt-budget": {
+              "tokens": 1000,
+              "words": 800
+            }
           },
           "scope": {
             "type": "array",
-            "items": { "type": "string" },
+            "items": {
+              "type": "string"
+            },
             "description": "What was in scope — versions, branches, revisions, URLs, documents examined."
           },
           "findings_summary": {
             "type": "string",
             "description": "Self-contained, prompt-injectable summary of what was found. Target ~300-800 words. Must stand alone without the full findings_document.",
-            "x-prompt-budget": { "tokens": 1000, "words": 800 }
+            "x-prompt-budget": {
+              "tokens": 1000,
+              "words": 800
+            }
           },
           "findings_document": {
             "type": "string",
@@ -61,17 +112,23 @@
             "properties": {
               "dependencies": {
                 "type": "array",
-                "items": { "type": "string" },
+                "items": {
+                  "type": "string"
+                },
                 "description": "Version-pinned dependency strings (e.g. '@mariozechner/pi-ai@0.63.1') whose behavior is load-bearing for the findings."
               },
               "revisions": {
                 "type": "array",
-                "items": { "type": "string" },
+                "items": {
+                  "type": "string"
+                },
                 "description": "Git SHAs, branch snapshots, or repo-at-date references."
               },
               "external_refs": {
                 "type": "array",
-                "items": { "type": "string" },
+                "items": {
+                  "type": "string"
+                },
                 "description": "Dated external references — URLs with retrieval timestamps, academic papers, external spec documents."
               }
             }
@@ -82,8 +139,10 @@
           },
           "stale_conditions": {
             "type": "array",
-            "items": { "type": "string" },
-            "description": "Explicit list of conditions under which the research is no longer authoritative. The future staleness engine (FGAP-007) will read this to transition status from complete to stale automatically."
+            "items": {
+              "type": "string"
+            },
+            "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."
           },
           "citations": {
             "type": "array",
@@ -91,13 +150,25 @@
             "items": {
               "type": "object",
               "additionalProperties": false,
-              "required": ["label"],
+              "required": [
+                "label"
+              ],
               "properties": {
-                "label": { "type": "string" },
-                "path": { "type": "string" },
-                "lines": { "type": "string" },
-                "url": { "type": "string" },
-                "retrieved_at": { "type": "string" }
+                "label": {
+                  "type": "string"
+                },
+                "path": {
+                  "type": "string"
+                },
+                "lines": {
+                  "type": "string"
+                },
+                "url": {
+                  "type": "string"
+                },
+                "retrieved_at": {
+                  "type": "string"
+                }
               }
             }
           },
@@ -109,26 +180,88 @@
             "type": "string",
             "description": "Alias for created_at."
           },
-          "created_by": { "type": "string" },
-          "created_at": { "type": "string" },
-          "modified_by": { "type": "string" },
-          "modified_at": { "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."
+          }
         }
       }
     }
   },
   "x-lifecycle": {
     "field": "status",
-    "states": ["planned", "in-progress", "complete", "stale", "superseded", "revised"],
+    "states": [
+      "planned",
+      "in-progress",
+      "complete",
+      "stale",
+      "superseded",
+      "revised"
+    ],
     "transitions": [
-      { "from": "planned", "to": "in-progress", "required_authority": "any" },
-      { "from": "in-progress", "to": "complete", "required_authority": "any", "note": "Agent may mark own research complete when findings_summary and citations are finalized." },
-      { "from": "complete", "to": "stale", "required_authority": "any", "note": "Any party marks stale when a stale_condition fires. Future staleness engine (FGAP-007) fires this automatically." },
-      { "from": "stale", "to": "in-progress", "required_authority": "user", "note": "Reopening for revision; requires user authority if the research is currently cited by an enacted decision because revising may invalidate the decision's grounding." },
-      { "from": "complete", "to": "superseded", "required_authority": "any", "precondition": "superseding entry exists and points to this one via a research_supersedes_research edge" },
-      { "from": "in-progress", "to": "revised", "required_authority": "any" },
-      { "from": "revised", "to": "complete", "required_authority": "any" }
+      {
+        "from": "planned",
+        "to": "in-progress",
+        "required_authority": "any"
+      },
+      {
+        "from": "in-progress",
+        "to": "complete",
+        "required_authority": "any",
+        "note": "Agent may mark own research complete when findings_summary and citations are finalized."
+      },
+      {
+        "from": "complete",
+        "to": "stale",
+        "required_authority": "any",
+        "note": "Any party marks stale when a stale_condition fires. A future staleness engine fires this automatically."
+      },
+      {
+        "from": "stale",
+        "to": "in-progress",
+        "required_authority": "user",
+        "note": "Reopening for revision; requires user authority if the research is currently cited by an enacted decision because revising may invalidate the decision's grounding."
+      },
+      {
+        "from": "complete",
+        "to": "superseded",
+        "required_authority": "any",
+        "precondition": "superseding entry exists and points to this one via a research_supersedes_research edge"
+      },
+      {
+        "from": "in-progress",
+        "to": "revised",
+        "required_authority": "any"
+      },
+      {
+        "from": "revised",
+        "to": "complete",
+        "required_authority": "any"
+      }
     ],
-    "note": "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). The staleness engine (FGAP-007) reads stale_conditions and fires the complete→stale transition automatically when conditions are met."
+    "note": "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. A future staleness engine reads stale_conditions and fires the complete→stale transition automatically when conditions are met."
   }
 }

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

@@ -1,47 +1,95 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "pi-context://schemas/spec-reviews",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "title": "Spec Reviews",
   "description": "Design reviews of specification documents. Each review targets one spec, runs a pre-implementation review pass (ideally via independent fresh-context reviewer), and carries scope/method/status. A spec-review blocks implementation-spec drafting until 'clean'.",
   "type": "object",
-  "required": ["reviews"],
+  "required": [
+    "reviews"
+  ],
   "properties": {
     "reviews": {
       "type": "array",
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["id", "target", "status", "created_by", "created_at"],
+        "required": [
+          "id",
+          "target",
+          "status",
+          "created_by",
+          "created_at"
+        ],
         "properties": {
-          "id": { "type": "string", "pattern": "^REVIEW-\\d{3}$" },
+          "id": {
+            "type": "string",
+            "pattern": "^REVIEW-\\d{3}$"
+          },
           "target": {
             "type": "string",
             "description": "Path to the spec doc being reviewed"
           },
-          "target_revision": { "type": "string", "description": "Git SHA or version at which the review was conducted" },
-          "reviewer": { "type": "string", "description": "Agent name or role performing the review" },
+          "target_revision": {
+            "type": "string",
+            "description": "Git SHA or version at which the review was conducted"
+          },
+          "reviewer": {
+            "type": "string",
+            "description": "Agent name or role performing the review"
+          },
           "status": {
             "type": "string",
-            "enum": ["not-started", "in-progress", "complete", "abandoned"]
+            "enum": [
+              "not-started",
+              "in-progress",
+              "complete",
+              "abandoned"
+            ]
           },
           "scope": {
             "type": "array",
-            "items": { "type": "string" },
+            "items": {
+              "type": "string"
+            },
             "description": "Sections or concerns of the target in scope for this review"
           },
           "method": {
             "type": "string",
             "description": "How the review is conducted — e.g. 'fresh-context independent reviewer', 'adversarial pre-mortem', 'self-review'",
-            "x-prompt-budget": { "tokens": 1000, "words": 800 }
+            "x-prompt-budget": {
+              "tokens": 1000,
+              "words": 800
+            }
           },
           "clean": {
             "type": "boolean",
             "description": "True when every finding has a terminal state (resolved/wontfix/duplicate)"
           },
-          "created_by": { "type": "string" },
-          "created_at": { "type": "string" },
-          "completed_at": { "type": "string" }
+          "created_by": {
+            "type": "string"
+          },
+          "created_at": {
+            "type": "string"
+          },
+          "completed_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."
+          }
         }
       }
     }
@@ -49,14 +97,36 @@
   "x-lifecycle": {
     "review": {
       "field": "status",
-      "states": ["not-started", "in-progress", "complete", "abandoned"],
+      "states": [
+        "not-started",
+        "in-progress",
+        "complete",
+        "abandoned"
+      ],
       "transitions": [
-        { "from": "not-started", "to": "in-progress", "required_authority": "any" },
-        { "from": "in-progress", "to": "complete", "required_authority": "any" },
-        { "from": "in-progress", "to": "abandoned", "required_authority": "user" },
-        { "from": "complete", "to": "in-progress", "required_authority": "user", "note": "reopen for follow-up review" }
+        {
+          "from": "not-started",
+          "to": "in-progress",
+          "required_authority": "any"
+        },
+        {
+          "from": "in-progress",
+          "to": "complete",
+          "required_authority": "any"
+        },
+        {
+          "from": "in-progress",
+          "to": "abandoned",
+          "required_authority": "user"
+        },
+        {
+          "from": "complete",
+          "to": "in-progress",
+          "required_authority": "user",
+          "note": "reopen for follow-up review"
+        }
       ]
     },
-    "note": "AJV draft-07 cannot enforce transition validity; this block is metadata for future framework-level state-machine validation (FGAP-005)."
+    "note": "AJV draft-07 cannot enforce transition validity; this block is metadata reserved for future framework-level state-machine validation."
   }
 }

package/samples/schemas/story.schema.json

@@ -1,9 +1,9 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "pi-context://schemas/story",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "title": "Stories",
-  "description": "Top-level user-story / story array-block (FGAP-064 elevation). Stories are a work-altitude between feature and task: a feature decomposes into stories, a story decomposes into tasks. Cross-altitude relationships (feature→story, story→task, story→story dependency, story→gating-item, story→milestone/phase/project-goal) live in relations.json closure-table edges per DEC-0013 — NOT as inline arrays on the story. Sub-shape is structural (id/title/status/description/acceptance_criteria); the Agile user-story form (role/want/benefit) is a future optional enrichment, not imposed (DEC-deferred per FGAP-064 — no role/want/benefit present in current data, none fabricated).",
+  "description": "Top-level user-story / story array-block. Stories are a work-altitude between feature and task: a feature decomposes into stories, a story decomposes into tasks. Cross-altitude relationships (feature→story, story→task, story→story dependency, story→gating-item, story→milestone/phase/project-goal) live in relations.json closure-table edges — NOT as inline arrays on the story. Sub-shape is structural (id/title/status/description/acceptance_criteria); the Agile user-story form (role/want/benefit) is a future optional enrichment, not imposed (no role/want/benefit present in current shape, none fabricated).",
   "type": "object",
   "required": [
     "stories"
@@ -39,7 +39,7 @@
               "complete",
               "blocked"
             ],
-            "description": "Story lifecycle. Intentionally divergent from pi-context://schemas/status; reconciliation tracked in FGAP-021."
+            "description": "Story lifecycle. Intentionally divergent from pi-context://schemas/status; reconciliation deferred to a future status-schema unification."
           },
           "description": {
             "type": "string",
@@ -65,6 +65,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/tasks.schema.json

@@ -1,32 +1,88 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "pi-context://schemas/tasks",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "title": "Tasks",
   "description": "Discrete units of work with status lifecycle (planned, in-progress, completed, blocked, cancelled). The operational layer between gaps/requirements and code changes.",
   "type": "object",
-  "required": ["tasks"],
+  "required": [
+    "tasks"
+  ],
   "properties": {
     "tasks": {
       "type": "array",
       "items": {
         "type": "object",
-        "required": ["id", "description", "status"],
+        "required": [
+          "id",
+          "description",
+          "status"
+        ],
         "properties": {
-          "id": { "type": "string", "pattern": "^TASK-\\d{3,}$" },
-          "description": { "type": "string", "x-prompt-budget": { "tokens": 1000, "words": 800 } },
-          "status": { "type": "string", "enum": ["planned", "in-progress", "completed", "blocked", "cancelled"] },
+          "id": {
+            "type": "string",
+            "pattern": "^TASK-\\d{3,}$"
+          },
+          "description": {
+            "type": "string",
+            "x-prompt-budget": {
+              "tokens": 1000,
+              "words": 800
+            }
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "planned",
+              "in-progress",
+              "completed",
+              "blocked",
+              "cancelled"
+            ]
+          },
           "files": {
             "type": "array",
-            "items": { "type": "string" },
+            "items": {
+              "type": "string"
+            },
             "description": "Files this task creates or modifies"
           },
           "acceptance_criteria": {
             "type": "array",
-            "items": { "type": "string", "x-prompt-budget": { "tokens": 1000, "words": 800 } }
+            "items": {
+              "type": "string",
+              "x-prompt-budget": {
+                "tokens": 1000,
+                "words": 800
+              }
+            }
+          },
+          "assigned_agent": {
+            "type": "string",
+            "description": "Agent name if assigned"
+          },
+          "notes": {
+            "type": "string",
+            "x-prompt-budget": {
+              "tokens": 1000,
+              "words": 800
+            }
+          },
+          "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."
           },
-          "assigned_agent": { "type": "string", "description": "Agent name if assigned" },
-          "notes": { "type": "string", "x-prompt-budget": { "tokens": 1000, "words": 800 } }
+          "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."
+          }
         }
       }
     }