@davidorex/pi-context 0.26.0

package/samples/conception.json

@@ -0,0 +1,467 @@
+{
+  "schema_version": "1.0.0",
+  "block_kinds": [
+    {
+      "canonical_id": "decisions",
+      "display_name": "Decisions",
+      "prefix": "DEC-",
+      "schema_path": "schemas/decisions.schema.json",
+      "array_key": "decisions",
+      "data_path": "decisions.json"
+    },
+    {
+      "canonical_id": "framework-gaps",
+      "display_name": "Framework Gaps",
+      "prefix": "FGAP-",
+      "schema_path": "schemas/framework-gaps.schema.json",
+      "array_key": "gaps",
+      "data_path": "framework-gaps.json"
+    },
+    {
+      "canonical_id": "tasks",
+      "display_name": "Tasks",
+      "prefix": "TASK-",
+      "schema_path": "schemas/tasks.schema.json",
+      "array_key": "tasks",
+      "data_path": "tasks.json"
+    },
+    {
+      "canonical_id": "verification",
+      "display_name": "Verification",
+      "prefix": "VER-",
+      "schema_path": "schemas/verification.schema.json",
+      "array_key": "verifications",
+      "data_path": "verification.json"
+    },
+    {
+      "canonical_id": "issues",
+      "display_name": "Issues",
+      "prefix": "issue-",
+      "schema_path": "schemas/issues.schema.json",
+      "array_key": "issues",
+      "data_path": "issues.json"
+    },
+    {
+      "canonical_id": "features",
+      "display_name": "Features",
+      "prefix": "FEAT-",
+      "schema_path": "schemas/features.schema.json",
+      "array_key": "features",
+      "data_path": "features.json"
+    },
+    {
+      "canonical_id": "research",
+      "display_name": "Research",
+      "prefix": "R-",
+      "schema_path": "schemas/research.schema.json",
+      "array_key": "research",
+      "data_path": "research.json"
+    },
+    {
+      "canonical_id": "rationale",
+      "display_name": "Design Rationale",
+      "prefix": "RAT-",
+      "schema_path": "schemas/rationale.schema.json",
+      "array_key": "rationales",
+      "data_path": "rationale.json"
+    },
+    {
+      "canonical_id": "spec-reviews",
+      "display_name": "Spec Reviews",
+      "prefix": "REVIEW-",
+      "schema_path": "schemas/spec-reviews.schema.json",
+      "array_key": "reviews",
+      "data_path": "spec-reviews.json"
+    },
+    {
+      "canonical_id": "layer-plans",
+      "display_name": "Layer Restructure Plans",
+      "prefix": "PLAN-",
+      "schema_path": "schemas/layer-plans.schema.json",
+      "array_key": "plans",
+      "data_path": "layer-plans.json"
+    },
+    {
+      "canonical_id": "requirements",
+      "display_name": "Requirements",
+      "prefix": "REQ-",
+      "schema_path": "schemas/requirements.schema.json",
+      "array_key": "requirements",
+      "data_path": "requirements.json"
+    },
+    {
+      "canonical_id": "conventions",
+      "display_name": "Conventions",
+      "prefix": "",
+      "schema_path": "schemas/conventions.schema.json",
+      "array_key": "rules",
+      "data_path": "conventions.json"
+    },
+    {
+      "canonical_id": "context-contracts",
+      "display_name": "Context Contracts",
+      "prefix": "CTX-",
+      "schema_path": "schemas/context-contracts.schema.json",
+      "array_key": "contracts",
+      "data_path": "context-contracts.json"
+    },
+    {
+      "canonical_id": "phase",
+      "display_name": "Phases",
+      "prefix": "PHASE-",
+      "schema_path": "schemas/phase.schema.json",
+      "array_key": "phases",
+      "data_path": "phase.json"
+    },
+    {
+      "canonical_id": "story",
+      "display_name": "Stories",
+      "prefix": "STORY-",
+      "schema_path": "schemas/story.schema.json",
+      "array_key": "stories",
+      "data_path": "story.json"
+    }
+  ],
+  "relation_types": [
+    {
+      "canonical_id": "decision_supersedes_decision",
+      "display_name": "supersedes",
+      "category": "ordering",
+      "source_kinds": ["decisions"],
+      "target_kinds": ["decisions"]
+    },
+    {
+      "canonical_id": "decision_relates_to_decision",
+      "display_name": "relates to decision",
+      "category": "data_flow",
+      "source_kinds": ["decisions"],
+      "target_kinds": ["decisions"]
+    },
+    {
+      "canonical_id": "decision_addresses_issue",
+      "display_name": "addresses issue",
+      "category": "data_flow",
+      "source_kinds": ["decisions"],
+      "target_kinds": ["issues"]
+    },
+    {
+      "canonical_id": "decision_addresses_feature",
+      "display_name": "addresses feature",
+      "category": "data_flow",
+      "source_kinds": ["decisions"],
+      "target_kinds": ["features"]
+    },
+    {
+      "canonical_id": "decision_addresses_gap",
+      "display_name": "addresses gap",
+      "category": "data_flow",
+      "source_kinds": ["decisions"],
+      "target_kinds": ["framework-gaps"]
+    },
+    {
+      "canonical_id": "gap_addressed_by_decision",
+      "display_name": "addressed by decision",
+      "category": "data_flow",
+      "source_kinds": ["framework-gaps"],
+      "target_kinds": ["decisions"]
+    },
+    {
+      "canonical_id": "gap_addressed_by_feature",
+      "display_name": "addressed by feature",
+      "category": "data_flow",
+      "source_kinds": ["framework-gaps"],
+      "target_kinds": ["features"]
+    },
+    {
+      "canonical_id": "gap_relates_to_issue",
+      "display_name": "relates to issue",
+      "category": "data_flow",
+      "source_kinds": ["framework-gaps"],
+      "target_kinds": ["issues"]
+    },
+    {
+      "canonical_id": "feature_depends_on_item",
+      "display_name": "depends on item",
+      "category": "ordering",
+      "source_kinds": ["features"],
+      "target_kinds": ["*"]
+    },
+    {
+      "canonical_id": "feature_gated_by_item",
+      "display_name": "gated by",
+      "category": "ordering",
+      "source_kinds": ["features"],
+      "target_kinds": ["*"]
+    },
+    {
+      "canonical_id": "feature_resolves_issue",
+      "display_name": "resolves issue",
+      "category": "data_flow",
+      "source_kinds": ["features"],
+      "target_kinds": ["issues"]
+    },
+    {
+      "canonical_id": "feature_governed_by_decision",
+      "display_name": "governed by decision",
+      "category": "data_flow",
+      "source_kinds": ["features"],
+      "target_kinds": ["decisions"]
+    },
+    {
+      "canonical_id": "story_depends_on_story",
+      "display_name": "story depends on story",
+      "category": "ordering",
+      "source_kinds": ["story"],
+      "target_kinds": ["story"]
+    },
+    {
+      "canonical_id": "story_gated_by_item",
+      "display_name": "story gated by",
+      "category": "ordering",
+      "source_kinds": ["story"],
+      "target_kinds": ["*"]
+    },
+    {
+      "canonical_id": "task_depends_on_task",
+      "display_name": "depends on task",
+      "category": "ordering",
+      "source_kinds": ["tasks"],
+      "target_kinds": ["tasks"]
+    },
+    {
+      "canonical_id": "requirement_depends_on_requirement",
+      "display_name": "depends on requirement",
+      "category": "ordering",
+      "source_kinds": ["requirements"],
+      "target_kinds": ["requirements"]
+    },
+    {
+      "canonical_id": "research_supersedes_research",
+      "display_name": "research supersedes research",
+      "category": "ordering",
+      "source_kinds": ["research"],
+      "target_kinds": ["research"]
+    },
+    {
+      "canonical_id": "research_informs_item",
+      "display_name": "informs item",
+      "category": "data_flow",
+      "source_kinds": ["research"],
+      "target_kinds": ["*"]
+    },
+    {
+      "canonical_id": "research_relates_to_research",
+      "display_name": "relates to research",
+      "category": "data_flow",
+      "source_kinds": ["research"],
+      "target_kinds": ["research"]
+    },
+    {
+      "canonical_id": "review_targets_item",
+      "display_name": "review targets",
+      "category": "membership",
+      "source_kinds": ["spec-reviews"],
+      "target_kinds": ["*"]
+    },
+    {
+      "canonical_id": "verification_verifies_item",
+      "display_name": "verifies",
+      "category": "data_flow",
+      "source_kinds": ["verification"],
+      "target_kinds": ["*"]
+    },
+    {
+      "canonical_id": "task_positioned_in_phase",
+      "display_name": "positioned in phase",
+      "category": "membership",
+      "source_kinds": ["tasks"],
+      "target_kinds": ["phase"]
+    },
+    {
+      "canonical_id": "feature_contains_story",
+      "display_name": "contains story",
+      "category": "membership",
+      "source_kinds": ["features"],
+      "target_kinds": ["story"]
+    },
+    {
+      "canonical_id": "story_contains_task",
+      "display_name": "contains task",
+      "category": "membership",
+      "source_kinds": ["story"],
+      "target_kinds": ["tasks"]
+    },
+    {
+      "canonical_id": "rationale_supports_decision",
+      "display_name": "supports decision",
+      "category": "data_flow",
+      "source_kinds": ["rationale"],
+      "target_kinds": ["decisions"]
+    },
+    {
+      "canonical_id": "task_addresses_gap",
+      "display_name": "addresses gap",
+      "category": "data_flow",
+      "source_kinds": ["tasks"],
+      "target_kinds": ["framework-gaps"]
+    },
+    {
+      "canonical_id": "task_addresses_feature",
+      "display_name": "addresses feature",
+      "category": "data_flow",
+      "source_kinds": ["tasks"],
+      "target_kinds": ["features"]
+    },
+    {
+      "canonical_id": "task_governed_by_decision",
+      "display_name": "governed by decision",
+      "category": "data_flow",
+      "source_kinds": ["tasks"],
+      "target_kinds": ["decisions"]
+    }
+  ],
+  "lenses": [
+    {
+      "id": "tasks-by-status",
+      "kind": "target",
+      "target": "tasks",
+      "derived_from_field": "status",
+      "bins": [
+        "planned",
+        "in-progress",
+        "completed",
+        "blocked",
+        "cancelled"
+      ]
+    },
+    {
+      "id": "gaps-by-status",
+      "kind": "target",
+      "target": "framework-gaps",
+      "derived_from_field": "status",
+      "bins": [
+        "identified",
+        "accepted",
+        "in-progress",
+        "closed",
+        "wontfix"
+      ]
+    }
+  ],
+  "layers": [],
+  "status_buckets": {},
+  "installed_schemas": [
+    "decisions",
+    "framework-gaps",
+    "tasks",
+    "verification",
+    "issues",
+    "features",
+    "research",
+    "rationale",
+    "spec-reviews",
+    "layer-plans",
+    "requirements",
+    "conventions",
+    "context-contracts",
+    "phase",
+    "story"
+  ],
+  "installed_blocks": [
+    "decisions",
+    "framework-gaps",
+    "tasks",
+    "verification",
+    "issues",
+    "features",
+    "research",
+    "rationale",
+    "spec-reviews",
+    "layer-plans",
+    "requirements",
+    "conventions",
+    "context-contracts",
+    "phase",
+    "story"
+  ],
+  "invariants": [
+    {
+      "id": "completed-task-has-verification",
+      "class": "requires-edge",
+      "block": "tasks",
+      "where": {
+        "status": "completed"
+      },
+      "relation_types": [
+        "verification_verifies_item"
+      ],
+      "direction": "as_child",
+      "severity": "error",
+      "message": "Completed task '{id}' has no verification edge (verification_verifies_item)"
+    },
+    {
+      "id": "decision-cites-forcing-artifact",
+      "class": "requires-edge",
+      "block": "decisions",
+      "relation_types": [
+        "decision_addresses_issue",
+        "decision_addresses_feature",
+        "decision_addresses_gap"
+      ],
+      "direction": "as_parent",
+      "severity": "error",
+      "message": "Decision '{id}' cites no forcing artifact (decision_addresses_issue|feature|gap edge)"
+    },
+    {
+      "id": "task-completed-gap-closed",
+      "class": "status-consistency",
+      "block": "tasks",
+      "relation_types": [
+        "task_addresses_gap"
+      ],
+      "direction": "as_parent",
+      "when_bucket": "complete",
+      "require_target_bucket": "complete",
+      "severity": "warning",
+      "message": "Completed task '{id}' addresses a gap that is not closed"
+    },
+    {
+      "id": "task-completed-feature-complete",
+      "class": "status-consistency",
+      "block": "tasks",
+      "relation_types": [
+        "task_addresses_feature"
+      ],
+      "direction": "as_parent",
+      "when_bucket": "complete",
+      "require_target_bucket": "complete",
+      "severity": "warning",
+      "message": "Completed task '{id}' addresses a feature that is not complete"
+    },
+    {
+      "id": "verification-passed-task-complete",
+      "class": "status-consistency",
+      "block": "verification",
+      "relation_types": [
+        "verification_verifies_item"
+      ],
+      "direction": "as_parent",
+      "when_bucket": "complete",
+      "require_target_bucket": "complete",
+      "severity": "error",
+      "message": "Passed verification '{id}' verifies a task that is not completed"
+    },
+    {
+      "id": "task-not-on-superseded-decision",
+      "class": "status-consistency",
+      "block": "tasks",
+      "relation_types": [
+        "task_governed_by_decision"
+      ],
+      "direction": "as_parent",
+      "forbid_target_bucket": "unknown",
+      "severity": "warning",
+      "message": "Task '{id}' is governed by a superseded or cancelled decision"
+    }
+  ]
+}

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

@@ -0,0 +1,89 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "pi-context://schemas/context-contracts",
+  "version": "1.0.0",
+  "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).",
+  "type": "object",
+  "required": [
+    "contracts"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "contracts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "unit_kind",
+          "bundle_relation_types",
+          "created_by",
+          "created_at"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^CTX-\\d{3,}$"
+          },
+          "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)."
+          },
+          "bundle_relation_types": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "relation_type",
+                "direction",
+                "max_depth"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "relation_type": {
+                  "type": "string"
+                },
+                "direction": {
+                  "type": "string",
+                  "enum": [
+                    "in",
+                    "out",
+                    "both"
+                  ]
+                },
+                "max_depth": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "applicability_predicate": {
+                  "type": "string",
+                  "description": "Optional FGAP-010 territory; reserved for relevance-scoping language."
+                }
+              }
+            }
+          },
+          "description": {
+            "type": "string"
+          },
+          "notes": {
+            "type": "string"
+          },
+          "created_by": {
+            "type": "string"
+          },
+          "created_at": {
+            "type": "string"
+          },
+          "modified_by": {
+            "type": "string"
+          },
+          "modified_at": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/samples/schemas/conventions.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "pi-context://schemas/conventions",
+  "version": "1.0.0",
+  "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"],
+  "properties": {
+    "rules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "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"] }
+        }
+      }
+    },
+    "test_conventions": {
+      "type": "object",
+      "required": ["runner_command", "file_pattern"],
+      "properties": {
+        "runner_command": { "type": "string" },
+        "file_pattern": { "type": "string" }
+      }
+    },
+    "lint_command": { "type": "string" },
+    "lint_scope": { "type": "string" }
+  }
+}

package/samples/schemas/decisions.schema.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "pi-context://schemas/decisions",
+  "version": "1.0.0",
+  "title": "Decisions",
+  "description": "Live decision log; each entry is open, enacted, or superseded, with supporting references and intra-item options.",
+  "type": "object",
+  "required": ["decisions"],
+  "properties": {
+    "decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "title", "status", "context", "decision", "consequences", "created_by", "created_at"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^DEC-\\d{4}$" },
+          "title": { "type": "string" },
+          "status": {
+            "type": "string",
+            "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 }
+          },
+          "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 }
+          },
+          "options_considered": {
+            "type": "array",
+            "description": "Populated only when multiple mandate-compliant candidates genuinely compete for user choice. Mandate-violating or structurally-wrong candidates are never listed.",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "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." }
+              }
+            }
+          },
+          "consequences": {
+            "type": "array",
+            "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": {
+            "type": "array",
+            "description": "Supporting references: code paths (file + lines), research documents, commit SHAs that enacted the decision, external specs. Each reference is a labeled pointer.",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["label"],
+              "properties": {
+                "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" }
+        }
+      }
+    }
+  },
+  "x-lifecycle": {
+    "field": "status",
+    "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." }
+    ],
+    "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)."
+  }
+}