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

pcp/commands/pressure_test_cmd.py

@@ -0,0 +1,72 @@
+"""pcp pressure-test -- MAC-Bench-style adversarial-pressure compliance
+check (see pcp.pressure_test's module docstring + docs/research-
+rigidity-vs-reliability-2026-07.md). Explicit, human-triggered only --
+spawns TWO real coding-agent sessions, real time and cost. Never called
+from `pcp build`'s own loop.
+"""
+
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from pcp.pcp_dir import find_pcp_dir, NoPCPDir
+from pcp.schema.validator import load_yaml
+from pcp import pressure_test
+
+console = Console()
+
+
+@click.command(name="pressure-test")
+@click.argument("module_name")
+@click.argument("criterion_id")
+@click.option("--path", "project_path", type=click.Path(), default=None,
+              help="Project root (default: cwd, walks up to find .pcp/).")
+@click.option("--model", "build_model", default=None, help="Override the coding-agent model for both runs.")
+def pressure_test_cmd(module_name: str, criterion_id: str, project_path: str | None, build_model: str | None):
+    """Run a criterion twice (baseline vs. urgency/authority-pressure framing),
+    each in its own throwaway worktree, and compare advisory-check violation
+    counts. A widening gap under pressure is a real compliance-under-pressure
+    signal -- see pcp.pressure_test's docstring."""
+    try:
+        pcp_dir = find_pcp_dir(Path(project_path) if project_path else None)
+    except NoPCPDir as e:
+        console.print(f"[red]Error:[/red] {e}")
+        sys.exit(2)
+
+    project_root = pcp_dir.parent
+    spec_path = pcp_dir / "strategy" / "modules" / module_name / "spec.yaml"
+    acc_path = pcp_dir / "strategy" / "modules" / module_name / "acceptance.yaml"
+    if not spec_path.exists() or not acc_path.exists():
+        console.print(f"[red]Error:[/red] module '{module_name}' not found under .pcp/strategy/modules/")
+        sys.exit(2)
+
+    spec = load_yaml(spec_path)
+    acc = load_yaml(acc_path)
+    criterion = next((c for c in acc.get("criteria", []) if c["id"] == criterion_id), None)
+    if criterion is None:
+        console.print(f"[red]Error:[/red] criterion '{criterion_id}' not found in module '{module_name}'")
+        sys.exit(2)
+
+    mod = {"name": module_name, "spec_path": spec_path, "acc_path": acc_path, "spec": spec}
+
+    console.print(
+        f"[bold]Pressure-testing[/bold] {module_name}/{criterion_id} -- "
+        "spawning 2 real coding-agent sessions (baseline + pressure framing), each in its own worktree..."
+    )
+    report = pressure_test.run_pressure_test(pcp_dir, project_root, mod, criterion, build_model=build_model)
+
+    console.print(f"\n[bold]Baseline advisory findings:[/bold] {report['baseline']['total_advisory']} {report['baseline']['advisory_counts']}")
+    console.print(f"[bold]Pressure advisory findings:[/bold]  {report['pressure']['total_advisory']} {report['pressure']['advisory_counts']}")
+    if report["widened"]:
+        console.print(
+            f"[red bold]⚠ Compliance gap widened under pressure[/red bold] "
+            f"(+{report['delta']} advisory findings) -- this criterion showed MORE corner-cutting "
+            "when told to move fast. Worth a human look at what got skipped."
+        )
+    elif report["delta"] < 0:
+        console.print(f"[dim]Pressure run showed FEWER advisory findings ({report['delta']}) -- no widening gap this run.[/dim]")
+    else:
+        console.print("[green]No compliance gap under pressure this run.[/green]")
+    console.print(f"[dim]Logged to .pcp/pressure_test_log.jsonl[/dim]")

pcp/commands/provenance.py

@@ -0,0 +1,313 @@
+"""pcp provenance — audit-evidence document: every file, every gate PCP has
+approved, any skipped/bypassed step made visible.
+
+Pure aggregation over already-persisted logs (.pcp/controls.yaml,
+.pcp/telemetry.jsonl, .pcp/bypass_log.yaml) — no LLM call, no rebuild.
+Callable at any point in a project's lifecycle, cheap, always a live
+snapshot. This is the SLSA/in-toto-informed "quality card" half of the
+CMMC/SSDF-style build-evidence document — controls.py's control catalog is
+the other half.
+"""
+
+import json
+import subprocess
+import sys
+from collections import defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+import click
+import yaml
+from rich.console import Console
+
+from pcp.pcp_dir import find_pcp_dir, NoPCPDir
+from pcp import telemetry as telemetry_mod
+from pcp import decision_log as decision_log_mod
+from pcp.evidence_chain import verify_chain
+
+console = Console()
+
+RESULT_SYMBOL = {
+    "pass": "OK", "block": "BLOCK", "skipped": "skip", "error": "ERROR", "bypassed": "bypass",
+    # "advisory" (2026-07-27): the check ran, found something, and deliberately
+    # did not block. Distinct from "pass" (found nothing) and "skipped" (never
+    # ran) — see _wave_record in build.py for why conflating it with "pass" was
+    # falsifying this very document.
+    "advisory": "ADVISORY",
+}
+
+# Fallback for telemetry records written before control_id existed (2026-07-01).
+CHECK_TO_CONTROL = {
+    "test-suite": "CTRL-001",
+    "wave-test-suite": "CTRL-001",
+    "lint": "CTRL-002",
+    "sast": "CTRL-003",
+    "layer1": "CTRL-004",
+    "layer1-bypass": "CTRL-004",
+    "architect-review": "CTRL-005",
+    "wave-architect-review": "CTRL-005",
+    "gate": "CTRL-006",
+    "wave-contract": "CTRL-007",
+    "wave-validate-strategy": "CTRL-008",
+    "deploy-phase-exit": "CTRL-009",
+    "build-scope": "CTRL-018",
+    "tier-presence": "CTRL-019",
+    "rung-necessity": "CTRL-020",
+}
+
+
+def _load_controls(pcp_dir: Path) -> dict:
+    path = pcp_dir / "controls.yaml"
+    if not path.exists():
+        return {}
+    data = yaml.safe_load(path.read_text()) or {}
+    return {c["id"]: c for c in data.get("controls", [])}
+
+
+def _load_bypasses(pcp_dir: Path) -> list[dict]:
+    path = pcp_dir / "bypass_log.yaml"
+    if not path.exists():
+        return []
+    data = yaml.safe_load(path.read_text()) or {}
+    return data.get("bypasses", [])
+
+
+def _git_head(project_root: Path) -> str:
+    result = subprocess.run(
+        ["git", "rev-parse", "--short", "HEAD"], capture_output=True, text=True, cwd=project_root,
+    )
+    return result.stdout.strip() if result.returncode == 0 else "unknown"
+
+
+def _control_id_for(record: dict) -> str | None:
+    return record.get("control_id") or CHECK_TO_CONTROL.get(record.get("check"))
+
+
+def _check_chain_integrity(pcp_dir: Path) -> dict:
+    """Verifies the hash chain on every append-only evidence log. Any non-empty
+    break list here means a record was edited, reordered, or deleted after
+    the fact — this is the one check in this whole document that isn't just
+    reporting what ran, it's reporting whether the report itself can be
+    trusted."""
+    telemetry_breaks = verify_chain(telemetry_mod.load(pcp_dir))
+    decision_breaks = verify_chain(decision_log_mod.load(pcp_dir))
+    bypass_breaks = verify_chain(_load_bypasses(pcp_dir))
+    return {
+        "telemetry.jsonl": telemetry_breaks,
+        "decision_log.jsonl": decision_breaks,
+        "bypass_log.yaml": bypass_breaks,
+    }
+
+
+def build_provenance(pcp_dir: Path) -> dict:
+    """Pure aggregation — safe to call at any point, no side effects besides read."""
+    controls = _load_controls(pcp_dir)
+    # Not just cycle=="qa" -- cross-cutting controls (e.g. CTRL-011 transcript
+    # archival, recorded under cycle="capture") carry a control_id too and
+    # belong in the same per-file/per-control coverage view.
+    qa_records = [r for r in telemetry_mod.load(pcp_dir) if _control_id_for(r)]
+    bypasses = _load_bypasses(pcp_dir)
+    chain_integrity = _check_chain_integrity(pcp_dir)
+
+    per_file: dict[str, dict[str, dict]] = defaultdict(dict)
+    per_control: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
+
+    for r in qa_records:
+        cid = _control_id_for(r)
+        if not cid:
+            continue
+        result = r.get("result", "pass")
+        per_control[cid]["total"] += 1
+        per_control[cid][result] += 1
+        for f in (r.get("files") or []):
+            existing = per_file[f].get(cid)
+            if not existing or r.get("timestamp", "") >= existing.get("timestamp", ""):
+                per_file[f][cid] = r
+
+    # A control whose every recorded outcome is "skipped" never actually ran
+    # anywhere in this project — a project-wide blind spot, not per-file noise.
+    standing_gap_cids = {
+        cid for cid, totals in per_control.items()
+        if totals["total"] > 0 and totals.get("skipped", 0) == totals["total"]
+    }
+    never_exercised_cids = {
+        cid for cid in controls if cid not in per_control and cid != "CTRL-010"
+    }
+
+    return {
+        "controls": controls,
+        "per_file": {f: dict(v) for f, v in per_file.items()},
+        "per_control": {cid: dict(v) for cid, v in per_control.items()},
+        "standing_gap_cids": sorted(standing_gap_cids),
+        "never_exercised_cids": sorted(never_exercised_cids),
+        "bypasses": bypasses,
+        "chain_integrity": chain_integrity,
+    }
+
+
+def _render_markdown(project_root: Path, data: dict, timestamp: str) -> str:
+    controls = data["controls"]
+    per_file = data["per_file"]
+    per_control = data["per_control"]
+
+    lines = [
+        "# PCP Audit Evidence",
+        f"Generated: {timestamp} | Git: `{_git_head(project_root)}`",
+        "",
+        "> Auto-generated by `pcp provenance`. Aggregates `.pcp/controls.yaml` + "
+        "`.pcp/telemetry.jsonl` + `.pcp/bypass_log.yaml`. Do not edit manually. "
+        "SSDF mapping is informed, not a certified assessment.",
+        "",
+        "## Per-File Gate Coverage",
+        "",
+    ]
+
+    if not per_file:
+        lines += ["_No telemetry recorded yet — run `pcp build` first._", ""]
+    else:
+        control_ids = sorted(controls.keys()) or sorted({cid for f in per_file.values() for cid in f})
+        lines.append("| File | " + " | ".join(control_ids) + " |")
+        lines.append("|---|" + "---|" * len(control_ids))
+        for f in sorted(per_file.keys()):
+            row = [f"`{f}`"]
+            for cid in control_ids:
+                rec = per_file[f].get(cid)
+                row.append("-" if not rec else RESULT_SYMBOL.get(rec.get("result"), rec.get("result", "?")))
+            lines.append("| " + " | ".join(row) + " |")
+        lines.append("")
+        legend = ", ".join(f"`{cid}`={controls.get(cid, {}).get('name', cid)}" for cid in control_ids)
+        lines += [f"Legend: {legend}", ""]
+
+    lines += ["## Standing Gaps (control never actually ran project-wide)", ""]
+    gap_lines = []
+    for cid in data["standing_gap_cids"]:
+        name = controls.get(cid, {}).get("name", cid)
+        total = per_control.get(cid, {}).get("total", 0)
+        gap_lines.append(f"- {cid} ({name}): {total}/{total} checks skipped — tool never detected project-wide.")
+    for cid in data["never_exercised_cids"]:
+        name = controls.get(cid, {}).get("name", cid)
+        gap_lines.append(f"- {cid} ({name}): never invoked in this project yet.")
+    lines += gap_lines if gap_lines else ["_None — every cataloged control has run with a real tool at least once._"]
+    lines.append("")
+
+    lines += ["## Bypass Ledger", ""]
+    if data["bypasses"]:
+        for b in data["bypasses"]:
+            rules = ", ".join(b.get("rules_bypassed", []))
+            lines.append(f"- `{b.get('timestamp', '')}` — {b.get('reason', '')} (rules: {rules})")
+    else:
+        lines.append("_No bypasses._")
+    lines.append("")
+
+    # Escalation responsiveness — proves the escalation ledger is watched,
+    # not just written (PagerDuty Escalation Policy Insights pattern).
+    from pcp import escalations as _esc
+    _esc_dir = project_root / ".pcp"
+    mtta = _esc.mtta_hours(_esc_dir)
+    esc_entries = _esc.load(_esc_dir)
+    lines += ["## Escalation Responsiveness", ""]
+    if esc_entries:
+        acked = sum(1 for e in esc_entries if e.get("acknowledged_at"))
+        lines.append(f"- Escalations recorded: {len(esc_entries)}; acknowledged: {acked}")
+        lines.append(f"- MTTA (median time-to-acknowledge): {mtta}h" if mtta is not None
+                     else "- MTTA: no escalation has ever been acknowledged — ledger may be unwatched")
+    else:
+        lines.append("_No escalations recorded._")
+    lines.append("")
+
+    # Auditability Card (adapted from "Auditable Agents", arXiv:2604.05485 —
+    # its 5-dimension framework maps 1:1 onto PCP's mechanisms). Deterministic
+    # self-score from artifacts that exist, not aspiration.
+    _pcp = project_root / ".pcp"
+    card = [
+        ("Action recoverability", (_pcp / "telemetry.jsonl").exists() and (_pcp / "evidence").exists(),
+         "per-attempt telemetry + raw untruncated QA evidence"),
+        ("Lifecycle coverage", (_pcp / "controls.yaml").exists() and (_pcp / "deploy_log.yaml").exists(),
+         "controls span commit->PR->wave->deploy; deploy log present"),
+        ("Policy checkability", (_pcp / "ci_rules.yaml").exists() and (_pcp / "policies").exists(),
+         "machine-checkable rules (ci_rules.yaml) + human-editable OPA policies"),
+        ("Responsibility attribution", (_pcp / "bypass_log.yaml").exists() or (_pcp / "escalations.yaml").exists(),
+         "attributed bypasses and/or escalation ledger with ack states"),
+        ("Evidence integrity", bool(data.get("chain_integrity")),
+         "hash-chained logs, verified each provenance run (unsigned — see roadmap)"),
+    ]
+    lines += ["## Auditability Card", "",
+              "Five dimensions from the 'Auditable Agents' framework (arXiv:2604.05485), "
+              "scored from artifacts actually present in this project:", "",
+              "| Dimension | Present | Basis |", "|---|---|---|"]
+    for name, ok, basis in card:
+        lines.append(f"| {name} | {'✓' if ok else '✗'} | {basis} |")
+    lines.append("")
+
+    lines += ["## Chain Integrity", "", "Each evidence log is hash-chained — an entry's hash covers its own "
+              "content plus the previous entry's hash, so an edit/reorder/deletion after the fact is "
+              "detectable even though the files themselves are plain, editable JSON/YAML.", ""]
+    any_break = False
+    for log_name, breaks in data["chain_integrity"].items():
+        if not breaks:
+            lines.append(f"- `{log_name}`: intact.")
+        else:
+            any_break = True
+            lines.append(f"- `{log_name}`: **{len(breaks)} break(s) detected**")
+            for b in breaks:
+                lines.append(f"  - index {b['index']}: {b['issue']}")
+    if any_break:
+        lines.append("")
+        lines.append("**A break here means this evidence document cannot be trusted as-is — "
+                      "investigate before relying on anything above.**")
+    lines.append("")
+
+    lines += ["## SSDF Crosswalk", "", "| Control | SSDF Practice | Enforcement | Status |", "|---|---|---|---|"]
+    for cid, c in sorted(controls.items()):
+        totals = per_control.get(cid, {})
+        if cid == "CTRL-010":
+            status = f"{len(data['bypasses'])} bypass(es) logged" if data["bypasses"] else "0 bypasses"
+        elif cid in data["never_exercised_cids"]:
+            status = "GAP — never invoked"
+        elif cid in data["standing_gap_cids"]:
+            status = "GAP — tool never detected"
+        else:
+            status = f"{totals.get('pass', 0)}/{totals.get('total', 0)} pass"
+        practices = ", ".join(c.get("ssdf_practice", []))
+        lines.append(f"| {cid} {c.get('name', '')} | {practices} | {c.get('enforcement', '')} | {status} |")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def write_provenance(pcp_dir: Path) -> Path:
+    data = build_provenance(pcp_dir)
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    md = _render_markdown(pcp_dir.parent, data, timestamp)
+    out = pcp_dir / "provenance.md"
+    out.write_text(md)
+    return out
+
+
+@click.command()
+@click.option("--path", "project_path", type=click.Path(), default=None)
+@click.option("--json", "output_json", is_flag=True, help="Print raw JSON instead of writing provenance.md.")
+@click.option("--attest", "attest_flag", is_flag=True,
+              help="Also export in-toto Statement v1 / DSSE envelopes to .pcp/attestations.jsonl "
+                   "(unsigned unless --sign and cosign present).")
+@click.option("--sign", "sign_flag", is_flag=True,
+              help="Sign the attestation export via cosign sign-blob (requires cosign; interactive OIDC).")
+def provenance(project_path: str | None, output_json: bool, attest_flag: bool, sign_flag: bool):
+    """Audit-evidence document — every file, every gate, any skip/bypass made visible."""
+    try:
+        pcp_dir = find_pcp_dir(Path(project_path) if project_path else None)
+    except NoPCPDir as e:
+        console.print(f"[red]Error:[/red] {e}")
+        sys.exit(2)
+
+    if attest_flag or sign_flag:
+        from pcp.attest import export_attestations
+        out, count, signing_note = export_attestations(pcp_dir, sign=sign_flag)
+        console.print(f"[green]✓[/green] {count} in-toto attestation(s) -> {out.name}  [{signing_note}]")
+
+    if output_json:
+        click.echo(json.dumps(build_provenance(pcp_dir), indent=2, default=str))
+        return
+
+    out_path = write_provenance(pcp_dir)
+    console.print(f"[green]Provenance written[/green] -> {out_path.relative_to(pcp_dir.parent)}")

pcp/commands/prune.py

@@ -0,0 +1,179 @@
+"""pcp prune — retention/pruning for .pcp/evidence/ and .pcp/transcripts/.
+
+Both grow unboundedly (CLAUDE.md names this explicitly: full raw QA proof
+on every check, gzip-archived session transcripts on every pcp capture
+call, no retention policy). Deliberately scoped to these two directories
+only, NOT telemetry.jsonl/decision_log.jsonl/bypass_log.yaml -- those are
+hash-chained (evidence_chain.py) and pruning entries out of the front of a
+hash chain breaks verify_chain() at the new first record unless the
+pruning routine re-anchors the chain with an explicit checkpoint, a bigger
+change than this pass takes on. evidence/transcripts are plain files with
+no chain to preserve, so they're the safe, high-value target: the actual
+disk-bloat culprits (full test-suite output, full judge responses, full
+session transcripts) rather than telemetry.jsonl's small per-record JSON
+lines.
+
+Deletion, not archival -- an irreversible action, so it gets the same
+posture pcp deploy already established as this project's one other
+genuinely irreversible action: mandatory interactive confirmation by
+default, --yes opts out.
+
+A deleted evidence file leaves a dangling evidence_path reference in
+telemetry.jsonl -- dashboard.py already just renders that as a link
+without checking existence, a known pre-existing gap this doesn't
+introduce or fix, just doesn't make worse.
+"""
+
+import shutil
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+import click
+import yaml
+from rich.console import Console
+
+from pcp.pcp_dir import find_pcp_dir, NoPCPDir
+from pcp.schema.validator import load_yaml
+
+console = Console()
+
+PRUNE_LOG = "prune_log.yaml"
+
+
+def _retention_config(pcp_dir: Path) -> dict:
+    ci_rules_path = pcp_dir / "ci_rules.yaml"
+    if not ci_rules_path.exists():
+        return {}
+    return (load_yaml(ci_rules_path) or {}).get("retention") or {}
+
+
+def _age_days(path: Path, now: datetime) -> float:
+    mtime = datetime.fromtimestamp(path.stat().st_mtime, tz=timezone.utc)
+    return (now - mtime).total_seconds() / 86400
+
+
+def _find_stale_evidence(pcp_dir: Path, evidence_days: int, now: datetime) -> list[Path]:
+    evidence_dir = pcp_dir / "evidence"
+    if not evidence_dir.exists():
+        return []
+    return [
+        p for p in evidence_dir.rglob("*.txt")
+        if p.is_file() and _age_days(p, now) > evidence_days
+    ]
+
+
+def _find_stale_transcripts(pcp_dir: Path, transcript_days: int, now: datetime) -> list[Path]:
+    transcripts_dir = pcp_dir / "transcripts"
+    if not transcripts_dir.exists():
+        return []
+    return [
+        p for p in transcripts_dir.glob("*.jsonl.gz")
+        if p.is_file() and _age_days(p, now) > transcript_days
+    ]
+
+
+def _log_prune_run(pcp_dir: Path, evidence_days: int | None, transcript_days: int | None,
+                    files_removed: int, bytes_reclaimed: int) -> None:
+    """Plain append list, not hash-chained -- this is an operational
+    maintenance record (what a config-driven cleanup pass did), not a
+    security/audit control checkpoint the way telemetry.jsonl/bypass_log.yaml
+    are. Scope kept narrow deliberately, same "phase 1, not the finished
+    thing" posture as pcp docs's drift score."""
+    log_path = pcp_dir / PRUNE_LOG
+    existing = []
+    if log_path.exists():
+        existing = (yaml.safe_load(log_path.read_text()) or {}).get("runs", [])
+    existing.append({
+        "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "evidence_days": evidence_days,
+        "transcript_days": transcript_days,
+        "files_removed": files_removed,
+        "bytes_reclaimed": bytes_reclaimed,
+    })
+    log_path.write_text(yaml.dump({"runs": existing}, default_flow_style=False))
+
+
+def run_prune(pcp_dir: Path, evidence_days: int | None, transcript_days: int | None,
+              now: datetime | None = None) -> dict:
+    """Pure discovery + deletion, no prompting -- the CLI command owns the
+    confirmation step. Returns a summary dict; always safe to call with
+    both days=None (finds nothing, deletes nothing)."""
+    now = now or datetime.now(timezone.utc)
+    stale_evidence = _find_stale_evidence(pcp_dir, evidence_days, now) if evidence_days else []
+    stale_transcripts = _find_stale_transcripts(pcp_dir, transcript_days, now) if transcript_days else []
+    all_stale = stale_evidence + stale_transcripts
+    total_bytes = sum(p.stat().st_size for p in all_stale)
+
+    return {
+        "evidence_files": stale_evidence,
+        "transcript_files": stale_transcripts,
+        "total_files": len(all_stale),
+        "total_bytes": total_bytes,
+    }
+
+
+def _delete_files(paths: list[Path]) -> None:
+    for p in paths:
+        p.unlink(missing_ok=True)
+
+
+@click.command()
+@click.option("--path", "project_path", type=click.Path(), default=None,
+              help="Project root (default: cwd, walks up to find .pcp/).")
+@click.option("--evidence-days", type=int, default=None,
+              help="Delete .pcp/evidence/*.txt older than N days (overrides ci_rules.yaml's retention.evidence_days).")
+@click.option("--transcript-days", type=int, default=None,
+              help="Delete .pcp/transcripts/*.jsonl.gz older than N days (overrides ci_rules.yaml's retention.transcript_days).")
+@click.option("--dry-run", is_flag=True, help="Show what would be deleted, delete nothing.")
+@click.option("--yes", is_flag=True, help="Skip the interactive confirmation prompt (CI/non-interactive use).")
+def prune(project_path: str | None, evidence_days: int | None, transcript_days: int | None,
+          dry_run: bool, yes: bool):
+    """Delete stale raw QA evidence / session transcripts past a retention window.
+
+    No retention happens unless configured -- via --evidence-days/
+    --transcript-days here, or a `retention:` block in ci_rules.yaml. A bare
+    `pcp prune` with nothing configured does nothing and says so."""
+    try:
+        pcp_dir = find_pcp_dir(Path(project_path) if project_path else None)
+    except NoPCPDir as e:
+        console.print(f"[red]Error:[/red] {e}")
+        sys.exit(2)
+
+    config = _retention_config(pcp_dir)
+    evidence_days = evidence_days if evidence_days is not None else config.get("evidence_days")
+    transcript_days = transcript_days if transcript_days is not None else config.get("transcript_days")
+
+    if not evidence_days and not transcript_days:
+        console.print(
+            "[dim]No retention configured -- nothing to do. Pass --evidence-days/--transcript-days, "
+            "or add a `retention:` block to .pcp/ci_rules.yaml.[/dim]"
+        )
+        sys.exit(0)
+
+    result = run_prune(pcp_dir, evidence_days, transcript_days)
+    if result["total_files"] == 0:
+        console.print("[green]Nothing past the retention window.[/green]")
+        sys.exit(0)
+
+    mb = result["total_bytes"] / (1024 * 1024)
+    console.print(
+        f"[bold]{result['total_files']} file(s)[/bold] past retention "
+        f"({len(result['evidence_files'])} evidence, {len(result['transcript_files'])} transcripts), "
+        f"~{mb:.1f} MB."
+    )
+
+    if dry_run:
+        console.print("[dim]--dry-run: nothing deleted.[/dim]")
+        sys.exit(0)
+
+    if not yes:
+        prompt = f"Permanently delete these {result['total_files']} file(s)?"
+        if not click.confirm(prompt, default=False):
+            console.print("[yellow]Prune aborted.[/yellow]")
+            sys.exit(0)
+
+    _delete_files(result["evidence_files"])
+    _delete_files(result["transcript_files"])
+    _log_prune_run(pcp_dir, evidence_days, transcript_days, result["total_files"], result["total_bytes"])
+    console.print(f"[green]✓[/green] Deleted {result['total_files']} file(s), reclaimed ~{mb:.1f} MB.")

pcp/commands/report.py

@@ -0,0 +1,49 @@
+"""pcp report — DEPRECATED (2026-07-21).
+
+Confirmed a genuine duplicate, not a distinct capability: this command had
+its own separate implementation reading bypass_log.yaml/current_state.md
+directly, never calling into provenance.py's build_provenance(). Every
+data point it showed already exists elsewhere -- the bypass ledger is a
+full section of `pcp provenance`'s output; the coverage percentage is
+already in current_state.md itself (which this command only re-read) and
+surfaced again in pcp.md/dashboard.html. Zero unique data, duplicate code
+instead of reuse -- exactly the catalog-bloat pattern PCP's own
+self-evaluation named. Kept as a command (not removed outright) so a
+script or muscle-memory invocation gets a clear redirect instead of a
+"command not found" error.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from pcp.pcp_dir import find_pcp_dir, NoPCPDir
+
+console = Console()
+
+_DEPRECATION_MESSAGE = (
+    "`pcp report` is deprecated -- use `pcp provenance` (bypass ledger + SSDF crosswalk) "
+    "or `pcp dashboard` (Audit Trail tab) instead. Both already show everything this "
+    "command did, with more context."
+)
+
+
+@click.command()
+@click.option("--path", "project_path", type=click.Path(), default=None)
+@click.option("--json", "output_json", is_flag=True, help="Output raw JSON.")
+def report(project_path: str | None, output_json: bool):
+    """DEPRECATED -- use `pcp provenance` or `pcp dashboard` instead."""
+    try:
+        find_pcp_dir(Path(project_path) if project_path else None)
+    except NoPCPDir as e:
+        console.print(f"[red]Error:[/red] {e}")
+        sys.exit(2)
+
+    if output_json:
+        click.echo(json.dumps({"deprecated": True, "use_instead": ["pcp provenance", "pcp dashboard"]}, indent=2))
+        return
+
+    console.print(f"[yellow]{_DEPRECATION_MESSAGE}[/yellow]")