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

pcp/__init__.py

@@ -0,0 +1,3 @@
+"""PCP — Program Context Protocol."""
+
+__version__ = "0.1.0"

pcp/assertions.py

@@ -0,0 +1,152 @@
+"""Deterministic objective-coverage scoring — replaces the LLM-judged
+coverage_score with keyword-overlap graph reachability when possible,
+mirroring how coupling.py already replaced the LLM-judged coupling_score
+with networkx graph math (same pioneer-claim, same Logic-Tier Selection
+philosophy: cheapest rung that correctly makes the decision).
+
+coverage_score is the one LLM-judged number CLAUDE.md's own coverage_audit.py
+section flags as a real Goodhart risk — a spec can be word-smithed to score
+well without real coverage, and coverage_audit.py only ever detects the
+resulting inconsistency/drift after the fact, it can't prevent it. This is a
+genuinely different mitigation: score numbered assertions parsed straight
+from objective.md's own text against each module's declared
+objective_coverage via keyword overlap — zero LLM calls, zero flakiness,
+immune to word-smithing the way a semantic judgment call isn't.
+
+Deliberately not a replacement for the LLM's judgment across the board:
+contradictions/overlaps/missing_modules stay genuinely semantic and keep
+going through validate_strategy.py's LLM call unchanged — only
+coverage_score/coverage_gaps get the deterministic treatment here, the same
+narrow scope coupling.py's own history establishes (see CLAUDE.md's
+"Updated 2026-06-30" coupling entry).
+
+Honest limitation, stated rather than hidden: "does this module's free-text
+objective_coverage actually, semantically cover this assertion" is still a
+real judgment call that keyword overlap can get wrong in both directions —
+false positive (shared vocabulary, no real coverage) and false negative
+(real coverage, different words). Same class of approximation
+docs.py's _brd_keywords() already accepts for BRD-item matching — a rung-1
+heuristic, not ground truth, and it says so rather than pretending
+precision it doesn't have.
+"""
+
+import re
+
+_ASSERTION_PATTERN = re.compile(r"^[ \t]*(\d+)\.[ \t]+(.+)$", re.MULTILINE)
+_KEYWORD_PATTERN = re.compile(r"[a-zA-Z]{5,}")
+_OVERLAP_THRESHOLD = 0.25  # fraction of an assertion's own keywords that must appear in a module's coverage text
+
+
+def parse_assertions(objective_text: str) -> list[dict]:
+    """Numbered list items anywhere in objective.md — e.g. the numbered
+    outcomes under a '## What Success Looks Like' heading, the exact shape
+    `pcp kickoff`'s own SYSTEM_PROMPT already generates for every new
+    project. Returns [] if the document has no numbered list at all (every
+    pre-existing objective.md written before this convention existed) —
+    callers MUST treat an empty list as "cannot score deterministically
+    yet", not as "zero assertions found", and fall back to the LLM-judged
+    score. Never hard-breaks on an old-format file."""
+    assertions = []
+    for i, m in enumerate(_ASSERTION_PATTERN.finditer(objective_text), 1):
+        text = m.group(2).strip()
+        if text:
+            assertions.append({"id": f"A{i}", "text": text})
+    return assertions
+
+
+def _keywords(text: str) -> set[str]:
+    return {w.lower() for w in _KEYWORD_PATTERN.findall(text)}
+
+
+def _covers(assertion_text: str, coverage_text: str) -> bool:
+    a_kw = _keywords(assertion_text)
+    if not a_kw:
+        return False
+    c_kw = _keywords(coverage_text)
+    return len(a_kw & c_kw) / len(a_kw) >= _OVERLAP_THRESHOLD
+
+
+def compute_coverage(assertions: list[dict], modules: dict[str, dict]) -> dict:
+    """Deterministic reachability: an assertion counts as covered if at
+    least one module's objective_coverage list has keyword overlap with its
+    text above _OVERLAP_THRESHOLD. Returns the same coverage_score/
+    coverage_gaps shape the LLM-judged path already returns, so callers
+    don't need to branch on which path produced the result — only the
+    scoring_method field distinguishes them."""
+    gaps = []
+    covered_by: dict[str, list[str]] = {}
+    for a in assertions:
+        covering_modules = sorted(
+            name for name, spec in modules.items()
+            if any(_covers(a["text"], cov) for cov in (spec.get("objective_coverage") or []))
+        )
+        if covering_modules:
+            covered_by[a["id"]] = covering_modules
+        else:
+            gaps.append({"area": a["text"], "quote": a["text"]})
+
+    score = round(len(covered_by) / len(assertions), 2) if assertions else 0.0
+    return {
+        "coverage_score": score,
+        "coverage_gaps": gaps,
+        "assertions_total": len(assertions),
+        "assertions_covered": len(covered_by),
+        "assertion_coverage_map": covered_by,
+    }
+
+
+# Confidence floor above which the LLM's own coverage judgment is trusted
+# enough that a much lower deterministic score reads as scorer disagreement
+# rather than as real missing coverage.
+LLM_CONFIDENCE_FLOOR = 0.85
+
+# Below this, the deterministic scorer failed to match a MAJORITY of the
+# objective's assertions, which indicates the keyword heuristic does not work
+# against this objective's phrasing at all — not that coverage is genuinely
+# absent. At or above it, individual misses are credible and still block.
+SCORER_CREDIBILITY_FLOOR = 0.5
+
+
+def scorers_disagree(result: dict, floor: float = LLM_CONFIDENCE_FLOOR,
+                     credibility_floor: float = SCORER_CREDIBILITY_FLOOR) -> bool:
+    """True when the deterministic score contradicts a confident LLM score.
+
+    Keyword overlap is explicitly "not ground truth" (see this module's own
+    docstring): it has systematic false negatives whenever an objective's
+    numbered list is phrased in different vocabulary from the modules'
+    `objective_coverage`. Measured 2026-07-27 across four real projects, the
+    deterministic score ranged 0%-100% on healthy decompositions — Project P
+    scored 0/5 with 11 real modules because its assertions are terse feature
+    names, and Project S scored 1/4 because two of its assertions are
+    non-functional outcomes ("the sender never has to explain it") that no
+    module coverage text will ever share words with.
+
+    Two scorers disagreeing is an uncertainty signal, not a verdict. This
+    lives here, callable, because the rule previously existed ONLY inside
+    build.py's wave gate: `pcp build` correctly treated the disagreement as
+    advisory while standalone `pcp validate-strategy` exited 1 on the very
+    same data. One rule, one definition, both callers.
+    """
+    llm_score = result.get("llm_coverage_score")
+    det_score = result.get("coverage_score", 0)
+    return (
+        result.get("scoring_method") == "deterministic"
+        and llm_score is not None
+        and llm_score >= floor
+        and det_score < llm_score
+        # ...and the deterministic scorer must look BROKEN on this objective,
+        # not merely stricter. Vocabulary mismatch is systematic: it fails to
+        # match assertions uniformly and drives the score toward zero (Project P
+        # 0/5, Project S 1/4). A genuine missing module is localised — most
+        # assertions still match and one does not (9/10, or the 1/2 case in
+        # test_deterministic_gap_shown_in_cli_output, a real uncovered
+        # module the LLM claimed was fine).
+        #
+        # Without this clause the rule would have disarmed the very Goodhart
+        # mitigation the deterministic scorer exists to provide: any gap the
+        # LLM word-smithed past would have been waved through as
+        # "disagreement". Below-majority means the scorer is not working here
+        # and cannot be trusted to BLOCK; at or above majority its misses are
+        # credible and still fail the check.
+        and det_score < credibility_floor
+    )

pcp/attest.py

@@ -0,0 +1,111 @@
+"""in-toto attestation export for PCP evidence.
+
+2026-07-17 (build plan 2.1): PCP's per-check evidence records are semantically
+in-toto attestations (subject = file/criterion, predicate = QA outcome) but
+lived in a bespoke JSONL schema. This module exports them as in-toto
+Statement v1 objects wrapped in DSSE envelopes so GUAC/Archivista/cosign-
+verify tooling can consume them — "PCP evidence is in-toto-compatible" is a
+stronger claim than "PCP has its own audit format".
+
+HONEST BOUNDARY: envelopes are exported UNSIGNED (signatures: []) unless
+cosign is installed and --sign is passed. Unsigned DSSE is structurally
+valid and machine-readable but provides no non-repudiation — the hash-chain
+(evidence_chain.py) remains the tamper-evidence layer until Sigstore signing
+(build-plan 2.2) is completed. Stated here and in the export itself.
+"""
+
+import base64
+import hashlib
+import json
+import shutil
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+from pcp import telemetry
+
+STATEMENT_TYPE = "https://in-toto.io/Statement/v1"
+PREDICATE_TYPE = "https://pcp-protocol.com/attestation/qa-evidence/v1"
+DSSE_PAYLOAD_TYPE = "application/vnd.in-toto+json"
+
+
+def _sha256_file(path: Path) -> str | None:
+    try:
+        return hashlib.sha256(path.read_bytes()).hexdigest()
+    except OSError:
+        return None
+
+
+def build_statements(pcp_dir: Path) -> list[dict]:
+    """One in-toto Statement per qa-cycle telemetry record that has a
+    resolvable control and at least one subject file still on disk."""
+    project_root = pcp_dir.parent
+    statements = []
+    for rec in telemetry.load(pcp_dir):
+        if rec.get("cycle") != "qa" or not rec.get("control_id"):
+            continue
+        subjects = []
+        for f in rec.get("files") or []:
+            digest = _sha256_file(project_root / f)
+            if digest:
+                subjects.append({"name": f, "digest": {"sha256": digest}})
+        if not subjects:
+            continue
+        statements.append({
+            "_type": STATEMENT_TYPE,
+            "subject": subjects,
+            "predicateType": PREDICATE_TYPE,
+            "predicate": {
+                "control_id": rec.get("control_id"),
+                "check": rec.get("check"),
+                "result": rec.get("result"),
+                "module": rec.get("module"),
+                "criterion_id": rec.get("criterion_id"),
+                "attempt": rec.get("cycle_number"),
+                "timestamp": rec.get("timestamp"),
+                "evidence_path": rec.get("evidence_path"),
+                "entry_hash": rec.get("entry_hash"),
+                "note": "subject digests are CURRENT file state at export time, "
+                        "not at check time — PCP telemetry does not yet snapshot "
+                        "per-check content digests (honest limitation)",
+            },
+        })
+    return statements
+
+
+def _dsse_envelope(statement: dict) -> dict:
+    payload = base64.b64encode(json.dumps(statement, sort_keys=True).encode()).decode()
+    return {"payloadType": DSSE_PAYLOAD_TYPE, "payload": payload, "signatures": []}
+
+
+def export_attestations(pcp_dir: Path, sign: bool = False) -> tuple[Path, int, str]:
+    """Write .pcp/attestations.jsonl (one DSSE envelope per line).
+    Returns (path, count, signing_note)."""
+    statements = build_statements(pcp_dir)
+    out = pcp_dir / "attestations.jsonl"
+    with open(out, "w") as f:
+        for s in statements:
+            f.write(json.dumps(_dsse_envelope(s)) + "\n")
+
+    signing_note = "UNSIGNED (no non-repudiation; hash-chain remains the tamper-evidence layer)"
+    if sign:
+        if shutil.which("cosign"):
+            bundle = pcp_dir / "attestations.jsonl.sig"
+            result = subprocess.run(
+                ["cosign", "sign-blob", "--yes", str(out),
+                 "--output-signature", str(bundle)],
+                capture_output=True, text=True, timeout=300,
+            )
+            signing_note = (
+                f"signed via cosign -> {bundle.name}" if result.returncode == 0
+                else f"cosign signing FAILED: {(result.stderr or '').strip()[:200]}"
+            )
+        else:
+            signing_note = "--sign requested but cosign not installed — exported unsigned"
+
+    meta = {
+        "exported_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "count": len(statements), "signing": signing_note,
+    }
+    (pcp_dir / "attestations.meta.json").write_text(json.dumps(meta, indent=2))
+    return out, len(statements), signing_note

pcp/build_loop_bypass.py

@@ -0,0 +1,76 @@
+"""CTRL-037: build-loop bypass detector (2026-07-24).
+
+Real, recurring incident (Project O, 07-08 / mid-July / 07-21-onward,
+3 occurrences): `pcp build`'s formal gated loop (architect-review, QA,
+wave-merge, telemetry) silently stops being used -- not by decision, just by
+default -- while real commits keep landing via `pcp pm` + ad-hoc/manual
+work. `telemetry.jsonl` going stale IS the finding, not evidence the project
+went idle; nothing previously surfaced that at the moment it started
+happening. Deterministic: git log commit dates vs telemetry.jsonl's last
+entry timestamp, no LLM judgment.
+"""
+
+import os
+import subprocess
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from pcp import telemetry
+
+DEFAULT_THRESHOLD_DAYS = 3
+_TS_FMT = "%Y-%m-%dT%H:%M:%SZ"
+
+
+def _last_telemetry_ts(pcp_dir: Path) -> datetime | None:
+    records = telemetry.load(pcp_dir)
+    if not records:
+        return None
+    timestamps = [r["timestamp"] for r in records if r.get("timestamp")]
+    if not timestamps:
+        return None
+    latest = max(timestamps)
+    try:
+        return datetime.strptime(latest, _TS_FMT).replace(tzinfo=timezone.utc)
+    except ValueError:
+        return None
+
+
+def _commits_since(project_root: Path, since: datetime) -> int:
+    result = subprocess.run(
+        ["git", "log", f"--since={since.isoformat()}", "--format=%H"],
+        cwd=project_root, capture_output=True, text=True,
+    )
+    if result.returncode != 0:
+        return 0
+    return len([l for l in result.stdout.splitlines() if l.strip()])
+
+
+def check(pcp_dir: Path, project_root: Path, threshold_days: int | None = None) -> list[str]:
+    """Returns findings; [] if inert (no telemetry history yet, not a git
+    repo) or nothing to flag. Never raises -- advisory, same posture as
+    every other doctor-time check."""
+    threshold_days = threshold_days if threshold_days is not None else int(
+        os.environ.get("PCP_BUILD_LOOP_BYPASS_THRESHOLD_DAYS", DEFAULT_THRESHOLD_DAYS)
+    )
+    last_ts = _last_telemetry_ts(pcp_dir)
+    if last_ts is None:
+        return []  # never built via pcp build at all yet -- nothing to compare against
+    if not (project_root / ".git").exists():
+        return []
+
+    cutoff = last_ts + timedelta(days=threshold_days)
+    now = datetime.now(timezone.utc)
+    if cutoff >= now:
+        return []  # still inside the grace window
+
+    commit_count = _commits_since(project_root, cutoff)
+    if commit_count == 0:
+        return []
+
+    age_days = (now - last_ts).days
+    return [
+        f"{commit_count} commit(s) landed since {cutoff.strftime('%Y-%m-%d')} "
+        f"(>{threshold_days}d past telemetry.jsonl's last entry, {age_days}d ago) — "
+        "`pcp build`'s formal gated loop (architect-review/QA/wave-merge/telemetry) "
+        "may have been bypassed; work is happening outside it"
+    ]

pcp/build_report.py

@@ -0,0 +1,54 @@
+"""End-of-cycle build report (2026-07-24). `pcp build` already generates
+real evidence -- run_log.jsonl's proof-of-delivery bracket, raw QA output
+under .pcp/evidence/, per-attempt telemetry.jsonl records -- but until now
+none of it ever got handed to the human at the moment a run finished, just
+one dim summary line. This renders what actually happened THIS run, with
+evidence, so "pcp build completed" reads as something more than a plain
+commit does. Pure/testable: takes a since-timestamp, does no clock reads
+or side effects of its own.
+"""
+
+from pathlib import Path
+
+from pcp import run_log
+
+
+def render(pcp_dir: Path, since_ts: str) -> str:
+    """since_ts: ISO timestamp, run_log's own format (%Y-%m-%dT%H:%M:%SZ).
+    Only paired runs (criteria) whose POST record lands at or after this
+    count as "this run" -- string comparison is safe since the format is
+    fixed-width and zero-padded."""
+    pairs = [p for p in run_log.pair_runs(run_log.load(pcp_dir)) if p.get("timestamp", "") >= since_ts]
+
+    lines = ["# Build Cycle Report", ""]
+    if not pairs:
+        lines.append("_No criteria completed this run._")
+        return "\n".join(lines) + "\n"
+
+    succeeded = [p for p in pairs if p.get("result") == "success"]
+    lines.append(f"{len(succeeded)}/{len(pairs)} criteria succeeded this run.")
+    lines.append("")
+
+    for p in pairs:
+        module = p.get("module", "?")
+        feature = p.get("feature", "?")
+        proof = p.get("proof_of_delivery", {})
+        mark = "✓" if p.get("result") == "success" else "✗"
+        lines.append(f"## {mark} {module}: {feature}")
+        lines.append(f"- Deterministic gates passed: {', '.join(proof.get('real_gates_passed') or []) or 'none'}")
+        lines.append(f"- LLM-judged gates passed: {', '.join(proof.get('llm_judged_gates_passed') or []) or 'none'}")
+        commit_note = f" ({proof['post_commit_sha'][:8]})" if proof.get("post_commit_sha") else ""
+        lines.append(f"- Committed: {proof.get('committed')}  Pushed: {proof.get('pushed')}{commit_note}")
+        if p.get("anomaly_flags"):
+            lines.append(f"- ⚠ Anomalies: {'; '.join(p['anomaly_flags'])}")
+        lines.append(f"- Raw evidence: `.pcp/evidence/{module}/` (full test/lint/SAST/architect-review output)")
+        lines.append("")
+
+    lines.append("Full audit trail: `.pcp/provenance.md` · `pcp telemetry` for per-attempt token/cost breakdown.")
+    return "\n".join(lines) + "\n"
+
+
+def write(pcp_dir: Path, since_ts: str) -> Path:
+    out = Path(pcp_dir) / "build_report.md"
+    out.write_text(render(pcp_dir, since_ts))
+    return out