@davidorex/pi-context 0.30.0 → 0.32.0

package/samples/conception.json

@@ -121,6 +121,14 @@
       "array_key": "stories",
       "data_path": "story.json"
     },
+    {
+      "canonical_id": "milestone",
+      "display_name": "Milestones",
+      "prefix": "MILE-",
+      "schema_path": "schemas/milestone.schema.json",
+      "array_key": "milestones",
+      "data_path": "milestone.json"
+    },
     {
       "canonical_id": "work-orders",
       "display_name": "Work Orders",
@@ -128,6 +136,14 @@
       "schema_path": "schemas/work-orders.schema.json",
       "array_key": "work_orders",
       "data_path": "work-orders.json"
+    },
+    {
+      "canonical_id": "session-notes",
+      "display_name": "Session Notes",
+      "prefix": "SESSION-",
+      "schema_path": "schemas/session-notes.schema.json",
+      "array_key": "sessions",
+      "data_path": "session-notes.json"
     }
   ],
   "relation_types": [
@@ -136,7 +152,8 @@
       "display_name": "supersedes",
       "category": "ordering",
       "source_kinds": ["decisions"],
-      "target_kinds": ["decisions"]
+      "target_kinds": ["decisions"],
+      "role_direction": "as_parent"
     },
     {
       "canonical_id": "decision_relates_to_decision",
@@ -187,19 +204,35 @@
       "source_kinds": ["framework-gaps"],
       "target_kinds": ["issues"]
     },
+    {
+      "canonical_id": "task_addresses_issue",
+      "display_name": "addresses issue",
+      "category": "data_flow",
+      "source_kinds": ["tasks"],
+      "target_kinds": ["issues"]
+    },
+    {
+      "canonical_id": "issue_relates_to_issue",
+      "display_name": "relates to issue",
+      "category": "data_flow",
+      "source_kinds": ["issues"],
+      "target_kinds": ["issues"]
+    },
     {
       "canonical_id": "feature_depends_on_item",
       "display_name": "depends on item",
       "category": "ordering",
       "source_kinds": ["features"],
-      "target_kinds": ["*"]
+      "target_kinds": ["*"],
+      "role_direction": "as_parent"
     },
     {
       "canonical_id": "feature_gated_by_item",
       "display_name": "gated by",
       "category": "ordering",
       "source_kinds": ["features"],
-      "target_kinds": ["*"]
+      "target_kinds": ["*"],
+      "role_direction": "as_child"
     },
     {
       "canonical_id": "feature_resolves_issue",
@@ -220,35 +253,40 @@
       "display_name": "story depends on story",
       "category": "ordering",
       "source_kinds": ["story"],
-      "target_kinds": ["story"]
+      "target_kinds": ["story"],
+      "role_direction": "as_parent"
     },
     {
       "canonical_id": "story_gated_by_item",
       "display_name": "story gated by",
       "category": "ordering",
       "source_kinds": ["story"],
-      "target_kinds": ["*"]
+      "target_kinds": ["*"],
+      "role_direction": "as_child"
     },
     {
       "canonical_id": "task_depends_on_task",
       "display_name": "depends on task",
       "category": "ordering",
       "source_kinds": ["tasks"],
-      "target_kinds": ["tasks"]
+      "target_kinds": ["tasks"],
+      "role_direction": "as_parent"
     },
     {
       "canonical_id": "requirement_depends_on_requirement",
       "display_name": "depends on requirement",
       "category": "ordering",
       "source_kinds": ["requirements"],
-      "target_kinds": ["requirements"]
+      "target_kinds": ["requirements"],
+      "role_direction": "as_parent"
     },
     {
       "canonical_id": "research_supersedes_research",
       "display_name": "research supersedes research",
       "category": "ordering",
       "source_kinds": ["research"],
-      "target_kinds": ["research"]
+      "target_kinds": ["research"],
+      "role_direction": "as_parent"
     },
     {
       "canonical_id": "research_informs_item",
@@ -283,21 +321,40 @@
       "display_name": "positioned in phase",
       "category": "membership",
       "source_kinds": ["tasks"],
-      "target_kinds": ["phase"]
+      "target_kinds": ["phase"],
+      "role_direction": "as_child"
+    },
+    {
+      "canonical_id": "phase_positioned_in_milestone",
+      "display_name": "positioned in milestone",
+      "category": "membership",
+      "source_kinds": ["phase"],
+      "target_kinds": ["milestone"],
+      "role_direction": "as_child"
+    },
+    {
+      "canonical_id": "milestone_precedes_milestone",
+      "display_name": "precedes",
+      "category": "ordering",
+      "source_kinds": ["milestone"],
+      "target_kinds": ["milestone"],
+      "role_direction": "as_parent"
     },
     {
       "canonical_id": "feature_contains_story",
       "display_name": "contains story",
       "category": "membership",
       "source_kinds": ["features"],
-      "target_kinds": ["story"]
+      "target_kinds": ["story"],
+      "role_direction": "as_parent"
     },
     {
-      "canonical_id": "story_contains_task",
-      "display_name": "contains task",
+      "canonical_id": "story_includes_item",
+      "display_name": "includes item",
       "category": "membership",
       "source_kinds": ["story"],
-      "target_kinds": ["tasks"]
+      "target_kinds": ["*"],
+      "role_direction": "as_parent"
     },
     {
       "canonical_id": "rationale_supports_decision",
@@ -327,12 +384,93 @@
       "source_kinds": ["tasks"],
       "target_kinds": ["decisions"]
     },
+    {
+      "canonical_id": "item_governed_by_convention",
+      "display_name": "governed by convention",
+      "category": "data_flow",
+      "source_kinds": ["decisions", "features", "tasks"],
+      "target_kinds": ["conventions"]
+    },
+    {
+      "canonical_id": "item_acknowledges_missing_convention",
+      "display_name": "acknowledges missing convention",
+      "category": "data_flow",
+      "source_kinds": ["decisions", "features", "tasks"],
+      "target_kinds": ["framework-gaps"]
+    },
     {
       "canonical_id": "item_derived_from_item",
       "display_name": "derived from",
       "category": "data_flow",
       "source_kinds": ["*"],
+      "target_kinds": ["*"],
+      "role_direction": "as_child"
+    },
+    {
+      "canonical_id": "decision_raises_gap",
+      "display_name": "raises gap",
+      "category": "data_flow",
+      "source_kinds": ["decisions"],
+      "target_kinds": ["framework-gaps"]
+    },
+    {
+      "canonical_id": "decision_gated_by_item",
+      "display_name": "gated by",
+      "category": "ordering",
+      "source_kinds": ["decisions"],
+      "target_kinds": ["*"],
+      "role_direction": "as_child"
+    },
+    {
+      "canonical_id": "gap_relates_to_gap",
+      "display_name": "relates to gap",
+      "category": "data_flow",
+      "source_kinds": ["framework-gaps"],
+      "target_kinds": ["framework-gaps"]
+    },
+    {
+      "canonical_id": "task_gated_by_item",
+      "display_name": "gated by",
+      "category": "ordering",
+      "source_kinds": ["tasks"],
+      "target_kinds": ["*"],
+      "role_direction": "as_child"
+    },
+    {
+      "canonical_id": "session_touches_item",
+      "display_name": "touches item",
+      "category": "membership",
+      "source_kinds": ["session-notes"],
       "target_kinds": ["*"]
+    },
+    {
+      "canonical_id": "decision_derived_from_item",
+      "display_name": "derived from",
+      "category": "data_flow",
+      "source_kinds": ["decisions"],
+      "target_kinds": ["*"],
+      "role_direction": "as_child"
+    },
+    {
+      "canonical_id": "decision_escalates_underdetermined",
+      "display_name": "escalates underdetermined choice",
+      "category": "data_flow",
+      "source_kinds": ["decisions"],
+      "target_kinds": ["framework-gaps"]
+    },
+    {
+      "canonical_id": "task_advances_story",
+      "display_name": "advances story",
+      "category": "data_flow",
+      "source_kinds": ["tasks"],
+      "target_kinds": ["story"]
+    },
+    {
+      "canonical_id": "feature_advances_story",
+      "display_name": "advances story",
+      "category": "data_flow",
+      "source_kinds": ["features"],
+      "target_kinds": ["story"]
     }
   ],
   "lenses": [
@@ -361,10 +499,137 @@
         "closed",
         "wontfix"
       ]
+    },
+    {
+      "id": "issues-by-status",
+      "kind": "target",
+      "target": "issues",
+      "derived_from_field": "status",
+      "bins": [
+        "open",
+        "resolved",
+        "deferred"
+      ]
+    },
+    {
+      "id": "issues-by-priority",
+      "kind": "target",
+      "target": "issues",
+      "derived_from_field": "priority",
+      "bins": [
+        "critical",
+        "high",
+        "medium",
+        "low"
+      ]
+    },
+    {
+      "id": "gaps-by-priority",
+      "kind": "target",
+      "target": "framework-gaps",
+      "derived_from_field": "priority",
+      "bins": [
+        "P0",
+        "P1",
+        "P2",
+        "P3"
+      ]
+    },
+    {
+      "id": "features-by-status",
+      "kind": "target",
+      "target": "features",
+      "derived_from_field": "status",
+      "bins": [
+        "proposed",
+        "approved",
+        "in-progress",
+        "in-review",
+        "complete",
+        "blocked",
+        "cancelled"
+      ]
+    },
+    {
+      "id": "story-advancers",
+      "kind": "target",
+      "target": "story",
+      "relation_type": "task_advances_story",
+      "derived_from_field": null,
+      "bins": []
+    },
+    {
+      "id": "story-advancers-features",
+      "kind": "target",
+      "target": "story",
+      "relation_type": "feature_advances_story",
+      "derived_from_field": null,
+      "bins": []
     }
   ],
   "layers": [],
   "status_buckets": {},
+  "state_derivation": {
+    "in_flight": {
+      "kinds": [
+        "tasks"
+      ],
+      "bucket": "in_progress"
+    },
+    "focus_fallback": {
+      "kind": "phase",
+      "bucket": "in_progress"
+    },
+    "next_ranked": [
+      {
+        "kind": "tasks",
+        "label": "task",
+        "bucket": "todo",
+        "reason_template": "unblocked planned task"
+      },
+      {
+        "kind": "issues",
+        "label": "issue",
+        "bucket": "todo",
+        "rank_field": "priority",
+        "rank_order": [
+          "critical",
+          "high",
+          "medium",
+          "low"
+        ],
+        "reason_template": "open issue (priority {rank_value})"
+      },
+      {
+        "kind": "framework-gaps",
+        "label": "framework-gap",
+        "bucket": "todo",
+        "rank_field": "priority",
+        "rank_order": [
+          "P0",
+          "P1",
+          "P2",
+          "P3"
+        ],
+        "reason_template": "open gap (priority {rank_value})"
+      }
+    ],
+    "blocked_by": {
+      "relation_types": [
+        "task_depends_on_task",
+        "task_gated_by_item"
+      ]
+    },
+    "rollups": [
+      {
+        "kind": "milestone",
+        "membership_relation": "phase_positioned_in_milestone",
+        "complete_status": "reached",
+        "incomplete_status": "planned"
+      }
+    ],
+    "head_size": 15
+  },
   "installed_schemas": [
     "decisions",
     "framework-gaps",
@@ -381,7 +646,9 @@
     "context-contracts",
     "phase",
     "story",
-    "work-orders"
+    "milestone",
+    "work-orders",
+    "session-notes"
   ],
   "installed_blocks": [
     "decisions",
@@ -399,7 +666,9 @@
     "context-contracts",
     "phase",
     "story",
-    "work-orders"
+    "milestone",
+    "work-orders",
+    "session-notes"
   ],
   "invariants": [
     {
@@ -442,6 +711,19 @@
       "severity": "warning",
       "message": "Completed task '{id}' addresses a gap that is not closed"
     },
+    {
+      "id": "task-completed-issue-resolved",
+      "class": "status-consistency",
+      "block": "tasks",
+      "relation_types": [
+        "task_addresses_issue"
+      ],
+      "direction": "as_parent",
+      "when_bucket": "complete",
+      "require_target_bucket": "complete",
+      "severity": "warning",
+      "message": "Completed task '{id}' addresses an issue that is not resolved"
+    },
     {
       "id": "task-completed-feature-complete",
       "class": "status-consistency",
@@ -479,6 +761,67 @@
       "forbid_target_bucket": "unknown",
       "severity": "warning",
       "message": "Task '{id}' is governed by a superseded or cancelled decision"
+    },
+    {
+      "id": "decision-articulates-convention",
+      "class": "requires-edge",
+      "block": "decisions",
+      "relation_types": [
+        "item_governed_by_convention",
+        "item_acknowledges_missing_convention"
+      ],
+      "direction": "as_parent",
+      "severity": "warning",
+      "message": "Decision '{id}' articulates no governing convention — add an item_governed_by_convention edge to a convention, or an item_acknowledges_missing_convention edge to a missing-convention gap"
+    },
+    {
+      "id": "feature-articulates-convention",
+      "class": "requires-edge",
+      "block": "features",
+      "relation_types": [
+        "item_governed_by_convention",
+        "item_acknowledges_missing_convention"
+      ],
+      "direction": "as_parent",
+      "severity": "warning",
+      "message": "Feature '{id}' articulates no governing convention — add an item_governed_by_convention edge to a convention, or an item_acknowledges_missing_convention edge to a missing-convention gap"
+    },
+    {
+      "id": "task-articulates-convention",
+      "class": "requires-edge",
+      "block": "tasks",
+      "relation_types": [
+        "item_governed_by_convention",
+        "item_acknowledges_missing_convention"
+      ],
+      "direction": "as_parent",
+      "severity": "warning",
+      "message": "Task '{id}' articulates no governing convention — add an item_governed_by_convention edge to a convention, or an item_acknowledges_missing_convention edge to a missing-convention gap"
+    },
+    {
+      "id": "reached-milestone-phases-complete",
+      "class": "status-consistency",
+      "block": "milestone",
+      "relation_types": [
+        "phase_positioned_in_milestone"
+      ],
+      "direction": "as_child",
+      "when_bucket": "complete",
+      "require_target_bucket": "complete",
+      "severity": "error",
+      "message": "Reached milestone '{id}' has a positioned phase that is not complete — milestone.reached is a pure phase-rollup; a reached milestone requires the parent phase of every phase_positioned_in_milestone edge to be complete"
+    },
+    {
+      "id": "decision-shows-derivation",
+      "class": "requires-edge",
+      "block": "decisions",
+      "relation_types": [
+        "decision_derived_from_item",
+        "decision_escalates_underdetermined"
+      ],
+      "direction": "as_parent",
+      "severity": "warning",
+      "message": "Decision '{id}' shows no derivation basis — add a decision_derived_from_item edge to the fact its resolution derives from, or a decision_escalates_underdetermined edge to the framework-gap capturing a genuinely-underdetermined escalated choice (derive-decisions-from-facts)"
     }
   ],
   "tool_operations": [],

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

@@ -3,12 +3,16 @@
   "$id": "pi-context://schemas/framework-gaps",
   "version": "1.1.1",
   "title": "Framework Gaps",
-  "description": "Capability gaps in the pi-project-workflows framework — pieces that must exist natively for the target artifact-ownership model to be expressible as configuration rather than hand-enactment. Each gap carries evidence (file + line references), impact, canonical engineering vocabulary for the missing capability, proposed resolution, and lifecycle state. Framework gaps are distinct from feature-level defects: they describe what the framework cannot yet express at all, not bugs in expressible functionality.",
+  "description": "Capability gaps in the framework — pieces that must exist natively for the target artifact-ownership model to be expressible as configuration rather than hand-enactment. Each gap carries evidence (file + line references), impact, canonical engineering vocabulary for the missing capability, proposed resolution, and lifecycle state. Framework gaps are distinct from feature-level defects: they describe what the framework cannot yet express at all, not bugs in expressible functionality.",
   "type": "object",
   "required": [
     "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": {

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": {
@@ -43,7 +47,7 @@
           },
           "location": {
             "type": "string",
-            "description": "File path + line number, e.g. packages/pi-workflows/src/dag.ts:219"
+            "description": "File path + line number, e.g. src/module/file.ts:NNN"
           },
           "status": {
             "type": "string",
@@ -74,7 +78,7 @@
           },
           "package": {
             "type": "string",
-            "description": "Which monorepo package this issue touches (e.g. pi-workflows, pi-project, pi-behavior-monitors)"
+            "description": "Which package/module this issue touches (e.g. package-a, package-b)"
           },
           "source": {
             "type": "string",
@@ -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"
+      }
+    ]
   }
 }