program-context-protocol 0.12.4__py3-none-any.whl

pcp/schema/ci_rules.schema.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://pcp-protocol.com/schema/ci_rules.schema.json",
+  "title": "PCP CI Rules",
+  "type": "object",
+  "required": ["version", "rules"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "string",
+      "enum": ["1.0"]
+    },
+    "retention": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional pruning config for `pcp prune` -- how many days of raw QA evidence (.pcp/evidence/*.txt) and session transcripts (.pcp/transcripts/*.jsonl.gz) to keep before they're eligible for deletion. Unset means pcp prune does nothing unless overridden by its own --evidence-days/--transcript-days CLI flags -- no retention happens by default, since a silent auto-delete of audit evidence would be a worse default than an unbounded-growth warning.",
+      "properties": {
+        "evidence_days": { "type": "integer", "minimum": 1 },
+        "transcript_days": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "ships_externally": {
+      "type": "boolean",
+      "description": "Does this project ship/distribute to anyone outside the org, or run as a network service others connect to? Copyleft (GPL/AGPL/SSPL) obligations trigger on distribution/network-service-access, not on internal-only use -- see CLAUDE.md's Prior-Art license guardrail. false = pure internal tool: GPL is fine to vendor, AGPL/SSPL still flagged for manual review regardless (network-access clause is ambiguous even for 'internal' tools reachable over a network). Unset (or true) = the existing strict MIT/Apache-style-only default applies, unchanged -- conservative by default. Human-set -- never inferred."
+    },
+    "rules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "name", "check", "severity"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[A-Z]+_?[0-9]+$" },
+          "name": { "type": "string" },
+          "check": {
+            "type": "string",
+            "enum": ["ast_pattern", "file_exists", "llm_semantic", "protected_path"]
+          },
+          "pattern": { "type": "string" },
+          "target": { "type": "string" },
+          "description": { "type": "string" },
+          "message": { "type": "string" },
+          "require_present": { "type": "boolean" },
+          "severity": {
+            "type": "string",
+            "enum": ["hard_block", "advisory"]
+          },
+          "scope": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "contract": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "Optional -- Agent Behavioral Contracts reference pattern (arXiv:2602.22302), borrowed 2026-07-20 (see docs/research-rigidity-vs-reliability-2026-07.md). ABC's (P,I,G,R) shape mapped onto this schema: Governance is already `severity` above, not duplicated here. `recovery` is the one field with real behavior -- see check.py/build.py's ci_rules consumers for how it's used.",
+            "properties": {
+              "preconditions": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Conditions that must hold for this rule to even apply -- documentation only in this version, not evaluated."
+              },
+              "invariants": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Properties that must hold throughout execution, not just at the point checked -- documentation only in this version, not evaluated."
+              },
+              "recovery": {
+                "type": "string",
+                "enum": ["retry", "escalate", "quarantine", "block"],
+                "description": "What should happen when this rule fires, beyond the flat severity gate. 'escalate' additionally logs an escalation entry immediately when the rule fires (build.py), rather than waiting for 3rd-attempt exhaustion. 'retry'/'quarantine'/'block' are declared for completeness and future use; only 'escalate' changes behavior in this version -- see build.py's _apply_rule_recovery for the honest current scope."
+              }
+            }
+          }
+        },
+        "allOf": [
+          {
+            "if": { "properties": { "check": { "const": "ast_pattern" } } },
+            "then": { "required": ["pattern"] }
+          },
+          {
+            "if": { "properties": { "check": { "const": "file_exists" } } },
+            "then": { "required": ["target"] }
+          },
+          {
+            "if": { "properties": { "check": { "const": "llm_semantic" } } },
+            "then": { "required": ["description"] }
+          },
+          {
+            "if": { "properties": { "check": { "const": "protected_path" } } },
+            "then": { "required": ["scope"] }
+          },
+          {
+            "if": {
+              "properties": {
+                "check": { "const": "ast_pattern" },
+                "require_present": { "const": true }
+              },
+              "required": ["require_present"]
+            },
+            "then": { "required": ["scope"] }
+          }
+        ]
+      }
+    }
+  }
+}

pcp/schema/controls.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://pcp-protocol.com/schema/controls.schema.json",
+  "title": "PCP Control Catalog",
+  "description": "Canonical list of gates PCP enforces, cross-referenced to NIST SP 800-218 (SSDF) practices. Human-readable jumpstart for a CMMC/SSDF-style audit document — not a certified mapping. Read by future `pcp provenance`/audit-evidence tooling; control ids here must match control_id values written to telemetry.jsonl.",
+  "type": "object",
+  "required": ["version", "controls"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "type": "string", "enum": ["1.0"] },
+    "controls": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "name", "layer", "enforcement", "description"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^CTRL-[0-9]+$" },
+          "name": { "type": "string" },
+          "layer": {
+            "type": "string",
+            "enum": ["layer1", "layer2", "layer3", "wave-merge", "build-loop", "cross-cutting"]
+          },
+          "mechanism": { "type": "string" },
+          "tool": { "type": "string" },
+          "enforcement": {
+            "type": "string",
+            "enum": ["hard_block", "advisory", "tracked", "override"]
+          },
+          "description": { "type": "string" },
+          "ssdf_practice": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

pcp/schema/module_acceptance.schema.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://pcp-protocol.com/schema/module_acceptance.schema.json",
+  "title": "PCP Module Acceptance Criteria",
+  "type": "object",
+  "required": ["module", "criteria"],
+  "additionalProperties": true,
+  "properties": {
+    "version": {
+      "type": "string"
+    },
+    "module": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_-]*$"
+    },
+    "criteria": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "description", "check", "status"],
+        "additionalProperties": true,
+        "properties": {
+          "id": { "type": "string" },
+          "description": { "type": "string" },
+          "check": {
+            "type": "string",
+            "enum": ["ast_pattern", "file_exists", "test_passes", "manual", "dom_contains", "url_responds", "visual"]
+          },
+          "target": { "type": "string" },
+          "pattern": { "type": "string" },
+          "depends_on": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Other criterion ids in this module this one requires to be built first. Presence of this key on ANY criterion in the module is the opt-in signal for criterion-level parallel builds (see build.py's _criteria_parallel_enabled) -- without it, criteria in a module stay strictly sequential, the pre-existing default. An empty list still counts as opt-in (deliberately declared as independent)."
+          },
+          "test": { "type": "string" },
+          "url": { "type": "string" },
+          "selector": { "type": "string" },
+          "notes": { "type": "string" },
+          "reference_image": {
+            "type": "string",
+            "description": "Path to a local screenshot/mockup/Figma export image file, relative to project root, that a PM can point a UI-facing criterion at instead of describing the screen in prose alone. Consumed by build.py's _run_visual_quality_check as a second image the VLM judge compares the rendered screenshot against (layout/structure similarity, not pixel-perfect match). A remote URL is not fetched -- must be a file already present in the repo. Optional -- absence just means that check runs without a reference."
+          },
+          "nav_depth": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Number of clicks/taps from the app's primary entry point (login/home) to reach this feature, self-declared like logic_tier/build_vs_buy -- not computed via real routing-graph analysis (that needs per-framework route parsing, a bigger build than this field earns on its own). Audited by pcp design-audit against PCP_NAV_DEPTH_THRESHOLD (default 3, the classic UX heuristic); missing on a UI-facing criterion is itself a finding, same posture as design_justification's absence."
+          },
+          "screen_archetypes": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": ["dashboard", "data_entry_form", "list_table", "detail_view", "search_filter",
+                       "settings", "chat", "canvas_editor", "wizard", "auth", "other"]
+            },
+            "description": "Which screen archetype(s) this criterion's UI belongs to -- a LIST, not a single value, because most real screens are composite (a detail page is often detail_view + list_table + chat all at once; see CLAUDE.md's UI Building Blocks section on why a single-enum forced the wrong shape). 'other' is the honest escape hatch for a genuine non-fit -- forcing a bad-fit archetype to satisfy a schema is worse than declaring it doesn't cleanly match one. Each archetype maps to a recipe (required ui_organisms) in .pcp/ui_kit_recipes.yaml."
+          },
+          "ui_organisms": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Which organism-level building blocks (data-table, primary-nav, modal, ...) this screen actually uses, self-declared by the build agent -- like logic_tier/build_vs_buy, not detected. Checked against .pcp/ui_kit_recipes.yaml's organism->component mapping by build.py's CTRL-028: a declared organism should show a matching import in the criterion's own target file, or the declaration is unverified. Also checked against the criterion's screen_archetypes recipe (are the archetype's required organisms present)."
+          },
+          "status": {
+            "type": "string",
+            "enum": ["pending", "complete", "deferred", "blocked-ci", "blocked-secret", "blocked-regression"]
+          },
+          "verified_by": {
+            "type": "string",
+            "enum": ["pcp_build", "pcp_build_install_only", "manual"],
+            "description": "Who/what flipped status to complete. Stamped automatically by build.py's _mark_criterion_complete -- the ONLY place this ever gets set by the real gated loop (full TDD/QA/architect-review cycle = pcp_build; install-only fast path, CTRL-034 = pcp_build_install_only). Absence on a complete criterion means it was hand-edited outside pcp build entirely -- never set that by hand, it would defeat the point."
+          },
+          "logic_tier": {
+            "type": "integer",
+            "enum": [1, 2, 3, 4, 5, 6],
+            "description": "6-rung decision ladder: 1=deterministic, 2=solver, 3=ML, 4=RAG, 5=cached reuse, 6=deep-think LLM. See CLAUDE.md's Logic-Tier Selection philosophy."
+          },
+          "build_vs_buy": {
+            "type": "object",
+            "required": ["decision", "rationale"],
+            "additionalProperties": false,
+            "properties": {
+              "decision": {
+                "type": "string",
+                "enum": ["reuse_whole", "reuse_partial", "reimplement_from_reference", "fork_adapt", "build_fresh"]
+              },
+              "rationale": { "type": "string" },
+              "candidates_considered": {
+                "type": "array",
+                "items": { "type": "string" }
+              }
+            }
+          },
+          "install_only": {
+            "type": "boolean",
+            "description": "Set when priorart found a direct match and a human confirmed it (not an automated confidence heuristic) -- see CLAUDE.md's install-only fast path. build.py's _build_one_criterion skips the full TDD/architect-review/LLM-gate cycle for this criterion: interactive human approval (or --yes), run install_command, then a deterministic smoke test only (full test suite + Layer 1 ci_rules -- CTRL-034). Requires install_command. Declining the approval prompt, or a failed smoke test, falls through to the normal full build path -- this is never a silent skip."
+          },
+          "install_command": {
+            "type": "string",
+            "description": "Shell command that installs the direct-match dependency (e.g. 'pip install acroforge'). Required when install_only is true; ignored otherwise."
+          },
+          "design_justification": {
+            "type": "object",
+            "description": "PCP Design lifecycle, stage 2 (Decide per-screen) -- only meaningful for UI-facing criteria. Not schema-required (whether a criterion is UI-facing isn't expressible as a JSON-schema condition on free-text description) -- absence on a real UI criterion is instead a finding surfaced by pcp design-audit, not a validation failure.",
+            "additionalProperties": false,
+            "properties": {
+              "checklist_passed": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "deviations_from_system": { "type": "string" },
+              "jtbd_framing": { "type": "string" },
+              "customizable": {
+                "type": "boolean",
+                "description": "Does this feature expose real user-configurable settings/preferences affecting its own behavior, or is it fixed? Structurally checked (not just presence) by build.py's CTRL-026 -- a customizable=true declaration with no settings-shaped signal anywhere in the target file is flagged advisory, same posture as design_justification's own substance check."
+              },
+              "customization_notes": {
+                "type": "string",
+                "description": "What's actually configurable, one sentence. Required in spirit (not schema) whenever customizable=true -- an empty/placeholder note there is exactly what CTRL-026 flags."
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "version": { "const": "2.0" } },
+        "required": ["version"]
+      },
+      "then": {
+        "properties": {
+          "criteria": {
+            "items": {
+              "required": ["id", "description", "check", "status", "logic_tier", "build_vs_buy"]
+            }
+          }
+        }
+      }
+    }
+  ]
+}

pcp/schema/module_spec.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://pcp-protocol.com/schema/module_spec.schema.json",
+  "title": "PCP Module Spec",
+  "type": "object",
+  "required": ["module", "description"],
+  "additionalProperties": true,
+  "properties": {
+    "version": {
+      "type": "string"
+    },
+    "module": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_-]*$"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 10
+    },
+    "objective_coverage": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1
+    },
+    "dependencies": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "constraints": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "module_logic_breakdown": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Decompose-first, one level deeper than objective_coverage (GUIDE, arXiv:2502.21068, already applied program-wide via capabilities_enumerated): this module's internal components/sub-flows/edge-cases, declared BEFORE its acceptance criteria are generated so criteria derive from a real breakdown rather than a high-level restatement of the description. Optional, living artifact -- allowed to evolve once real implementation constraints surface, same posture design_system.md already has."
+    },
+    "deprecated": {
+      "type": "boolean"
+    },
+    "build_vs_buy": {
+      "type": "object",
+      "required": ["decision", "rationale"],
+      "additionalProperties": false,
+      "description": "Module-level build-vs-buy for infrastructure-shaped modules (portal, auth, integrations, orchestration engine). 'not_applicable' for pure business-logic modules -- see per-criterion build_vs_buy in acceptance.yaml instead.",
+      "properties": {
+        "decision": {
+          "type": "string",
+          "enum": ["reuse_whole", "reuse_partial", "reimplement_from_reference", "fork_adapt", "build_fresh", "not_applicable"]
+        },
+        "rationale": { "type": "string" },
+        "candidates_considered": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "install_only": {
+      "type": "boolean",
+      "description": "Whole-module direct-match fast path -- the entire module's pending criteria are satisfied by installing one existing dependency, human-confirmed (not an automated heuristic). build.py's _build_module_worker skips the full per-criterion TDD/architect-review/LLM-gate loop entirely: one interactive approval (or --yes), run install_command once, then one deterministic smoke test (full test suite + Layer 1 -- CTRL-034) covering the whole module. All pending criteria are marked complete together on success. Requires install_command. Declining the approval, or a failed smoke test, falls through to the normal per-criterion build loop -- never a silent skip."
+    },
+    "install_command": {
+      "type": "string",
+      "description": "Shell command that installs the direct-match dependency for the whole module. Required when install_only is true; ignored otherwise."
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "version": { "const": "2.0" } },
+        "required": ["version"]
+      },
+      "then": {
+        "required": ["build_vs_buy"]
+      }
+    }
+  ]
+}

pcp/schema/sdlc_phase.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://pcp-protocol.com/schema/sdlc_phase.schema.json",
+  "title": "PCP SDLC Phase",
+  "type": "object",
+  "required": ["version", "current_phase", "phases"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "string",
+      "enum": ["1.0"]
+    },
+    "current_phase": { "type": "string" },
+    "phases": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["name", "exit_criteria"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string" },
+          "scope": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "exit_criteria": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["id", "description", "check", "status"],
+              "additionalProperties": false,
+              "properties": {
+                "id": { "type": "string" },
+                "description": { "type": "string" },
+                "check": {
+                  "type": "string",
+                  "enum": ["file_exists", "ast_pattern", "manual"]
+                },
+                "target": { "type": "string" },
+                "status": {
+                  "type": "string",
+                  "enum": ["pending", "complete"]
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

pcp/schema/validator.py

@@ -0,0 +1,77 @@
+"""YAML schema validation against PCP JSON schemas."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+import jsonschema
+import yaml
+
+SCHEMA_DIR = Path(__file__).parent
+# Real packaging bug, found 2026-07-08: this used to be
+# Path(__file__).parent.parent.parent.parent / "schema", assuming a repo-root
+# schema/ dir sits four levels above validator.py -- only true in this exact
+# dev-repo layout. A real installed package (site-packages/pcp/schema/
+# validator.py, editable or not) has no such sibling four levels up, so
+# every validate_file() call silently pointed at a nonexistent path for
+# anyone using PCP as an actually-installed dependency (confirmed against
+# Project O's own separate venv install). Schemas now live directly
+# alongside validator.py, inside the package itself, so the path resolves
+# correctly regardless of how or where the package is installed.
+
+
+def _load_schema(name: str) -> dict:
+    path = SCHEMA_DIR / f"{name}.schema.json"
+    with open(path) as f:
+        return json.load(f)
+
+
+def validate_file(yaml_path: Path, schema_name: str) -> list[str]:
+    """Validate a YAML file against a named schema. Returns list of error messages."""
+    try:
+        with open(yaml_path) as f:
+            data = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        return [f"YAML parse error: {e}"]
+
+    schema = _load_schema(schema_name)
+    validator = jsonschema.Draft7Validator(schema)
+    errors = sorted(validator.iter_errors(data), key=lambda e: list(e.path))
+
+    return [
+        f"{'.'.join(str(p) for p in err.path) or 'root'}: {err.message}"
+        for err in errors
+    ]
+
+
+class MalformedSpecError(Exception):
+    """A spec/acceptance file exists but is not parseable YAML."""
+
+
+def load_yaml(path: Path) -> Any:
+    """Parse a `.pcp/` YAML file, failing with an actionable error.
+
+    This used to let PyYAML's ScannerError escape raw. A build agent
+    hand-edited `signer-fill-sign-flow/acceptance.yaml` on 2026-07-27, writing
+    a multi-line description as a plain (unquoted) scalar containing ": ",
+    which is invalid YAML. The resulting traceback ended a 41-dollar run that
+    had already completed two modules -- with no message naming the file, the
+    line, or what to do about it, and no chance for the other modules to
+    survive.
+
+    A malformed spec is a normal, expected condition in a system where agents
+    write files: it must read as "this file is broken, here is where" and be
+    catchable per-module, not as an interpreter stack trace.
+    """
+    try:
+        with open(path) as f:
+            return yaml.safe_load(f)
+    except yaml.YAMLError as exc:
+        mark = getattr(exc, "problem_mark", None)
+        where = f" at line {mark.line + 1}, column {mark.column + 1}" if mark else ""
+        problem = getattr(exc, "problem", None) or str(exc).splitlines()[0]
+        raise MalformedSpecError(
+            f"{path} is not valid YAML{where}: {problem}. "
+            f"A common cause is a multi-line description written unquoted while "
+            f"containing ': ' -- quote the string or use a block scalar (|)."
+        ) from exc