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

pcp/commands/deploy.py

@@ -0,0 +1,199 @@
+"""pcp deploy — production deploy automation.
+
+Per docs/greenfield.md Phase 6: checklist, trigger, smoke test, auto-rollback.
+Deploy is the one place in the PCP lifecycle where an irreversible production
+action happens — human approval is mandatory by default (`--yes` opts out for
+CI use, deliberately not the default). Extra scrutiny if migration/PII/payment
+-flavoured criteria are detected in this release.
+"""
+
+import os
+import subprocess
+import sys
+import time
+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, get_modules_dir, NoPCPDir
+from pcp.schema.validator import load_yaml
+from pcp.commands.doctor import load_integrations, check_environment
+from pcp.commands.watch import check_deploy_health, notify
+
+console = Console()
+
+RISK_KEYWORDS = ["migration", "migrate", "pii", "personal data", "payment", "credit card", "compliance"]
+
+
+def run_deploy_check(project_root: Path) -> bool:
+    """Shells out to `pcp deploy-check` (Layer 3) rather than importing it —
+    deploy_check.py's logic is a single click command body, not factored into
+    a reusable function, and shelling out exercises the exact same path a
+    human running it manually would."""
+    result = subprocess.run(
+        [sys.executable, "-m", "pcp.cli", "deploy-check", "--path", str(project_root)],
+        cwd=project_root,
+    )
+    return result.returncode == 0
+
+
+def collect_risk_flags(modules_dir: Path) -> list[str]:
+    flags = []
+    if not modules_dir.exists():
+        return flags
+    for acc_path in sorted(modules_dir.glob("*/acceptance.yaml")):
+        data = load_yaml(acc_path)
+        for c in data.get("criteria", []):
+            desc = (c.get("description") or "").lower()
+            for kw in RISK_KEYWORDS:
+                if kw in desc:
+                    flags.append(f"{acc_path.parent.name}/{c['id']}: \"{c['description']}\" (matched '{kw}')")
+                    break
+    return flags
+
+
+def log_deploy(pcp_dir: Path, entry: dict) -> None:
+    log_path = pcp_dir / "deploy_log.yaml"
+    existing = []
+    if log_path.exists():
+        data = yaml.safe_load(log_path.read_text()) or {}
+        existing = data.get("deploys", [])
+    existing.append(entry)
+    log_path.write_text(yaml.dump({"deploys": existing}, default_flow_style=False))
+
+
+@click.command()
+@click.option("--path", "project_path", type=click.Path(), default=None)
+@click.option("--yes", is_flag=True, help="Skip the interactive approval prompt (CI/non-interactive use — opt-in, not default).")
+@click.option("--rollout", default="100", help="Rollout percentage, logged for audit (e.g. 5, 25, 100).")
+def deploy(project_path: str | None, yes: bool, rollout: str):
+    """Production deploy — checklist, trigger, smoke test, auto-rollback."""
+    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
+    check_environment(pcp_dir, fatal_on_missing_required=False)
+    integrations = load_integrations(pcp_dir)
+    deploy_cfg = integrations.get("deploy") or {}
+    deploy_command = deploy_cfg.get("command")
+    health_url = deploy_cfg.get("health_check_url")
+    rollback_command = deploy_cfg.get("rollback_command")
+
+    console.print("[bold]Deploy checklist[/bold]")
+    console.print("[dim]Checking Layer 3 SDLC phase exit criteria (pcp deploy-check)...[/dim]")
+    if not run_deploy_check(project_root):
+        console.print("[red bold]BLOCKED — deploy-check failed. Resolve exit criteria before deploying.[/red bold]")
+        sys.exit(1)
+    console.print("[green]✓[/green] deploy-check passed")
+
+    try:
+        from pcp.commands.provenance import write_provenance
+        write_provenance(pcp_dir)
+        console.print("[dim]Audit evidence refreshed -> .pcp/provenance.md (review before approving)[/dim]")
+    except Exception as e:
+        console.print(f"[dim]Provenance refresh skipped: {e}[/dim]")
+
+    modules_dir = get_modules_dir(pcp_dir)
+    risk_flags = collect_risk_flags(modules_dir)
+
+    # Deploy-time OPA policy (deploy_policy.rego — freeze windows, rollback
+    # requirements). Advisory infrastructure but its deny rules DO block:
+    # a policy a human wrote saying "don't deploy Fridays" means exactly that.
+    # Missing opa / missing policy file degrades silently, same as the other
+    # rego consumers.
+    from pcp import policy
+    decision = policy.evaluate(pcp_dir, "data.pcp.deploy.deny", {
+        "utc_weekday": datetime.now(timezone.utc).weekday(),
+        "risk_flag_count": len(risk_flags),
+        "rollback_configured": bool(rollback_command),
+    })
+    if decision.get("available") and not decision.get("undefined"):
+        denies = decision.get("value") or []
+        if denies:
+            for d in denies:
+                console.print(f"[red bold]Deploy policy DENY:[/red bold] {d}")
+            console.print("[dim]Edit .pcp/policies/deploy_policy.rego to change deploy-time policy.[/dim]")
+            sys.exit(1)
+
+    if risk_flags:
+        console.print("\n[yellow bold]Risk flags detected — review before approving:[/yellow bold]")
+        for f in risk_flags:
+            console.print(f"  ⚠ {f}")
+    else:
+        console.print("[dim]No migration/PII/payment-flavoured criteria detected in this release.[/dim]")
+
+    console.print(f"\nRollout: {rollout}%")
+    console.print(f"Deploy command: {deploy_command or '(none configured — run `pcp doctor`)'}")
+    console.print(f"Health check: {health_url or '(none configured)'}")
+    console.print(f"Rollback command: {rollback_command or '(none configured)'}")
+
+    if not deploy_command:
+        console.print("[red]No deploy command configured. Run `pcp doctor` to set one.[/red]")
+        sys.exit(2)
+
+    if not yes:
+        prompt = "Approve this deploy?"
+        if risk_flags:
+            prompt = f"⚠ {len(risk_flags)} risk flag(s) above — approve this deploy anyway?"
+        if not click.confirm(prompt, default=False):
+            console.print("[yellow]Deploy aborted by user.[/yellow]")
+            sys.exit(0)
+
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    console.print(f"\n[bold]Triggering deploy:[/bold] {deploy_command}")
+    trigger_result = subprocess.run(deploy_command, shell=True, cwd=project_root)
+    deploy_ok = trigger_result.returncode == 0
+
+    smoke_result = None
+    rolled_back = False
+    if deploy_ok and health_url:
+        console.print("[dim]Waiting 10s before smoke test...[/dim]")
+        time.sleep(10)
+        # Multi-sample smoke (build plan 3.6 — the Argo/Flagger/LaunchDarkly
+        # baseline gates on error RATE over a window, not one boolean probe;
+        # a single check catches only total outage, not a flapping deploy).
+        # N samples over an interval; more than max_failures failed samples
+        # fails the smoke test. Defaults keep the old behavior cheap-ish:
+        # 3 samples, 5s apart, zero failures tolerated.
+        samples = int(os.environ.get("PCP_DEPLOY_SMOKE_SAMPLES", "3"))
+        interval_s = float(os.environ.get("PCP_DEPLOY_SMOKE_INTERVAL_SEC", "5"))
+        max_failures = int(os.environ.get("PCP_DEPLOY_SMOKE_MAX_FAILURES", "0"))
+        failures = 0
+        for i in range(max(samples, 1)):
+            if i:
+                time.sleep(interval_s)
+            if check_deploy_health(health_url) is not True:
+                failures += 1
+        smoke_result = failures <= max_failures
+        console.print(f"[dim]Smoke: {samples - failures}/{samples} samples healthy (tolerance {max_failures}).[/dim]")
+        if smoke_result:
+            console.print("[green]✓ Smoke test passed.[/green]")
+        else:
+            console.print("[red]✗ Smoke test FAILED.[/red]")
+            if rollback_command:
+                console.print(f"[bold]Auto-rollback:[/bold] {rollback_command}")
+                rb = subprocess.run(rollback_command, shell=True, cwd=project_root)
+                rolled_back = rb.returncode == 0
+                notify(f"pcp deploy: smoke test failed, auto-rollback {'succeeded' if rolled_back else 'FAILED — needs human attention'}")
+            else:
+                notify("pcp deploy: smoke test failed, no rollback command configured — needs human attention")
+
+    log_deploy(pcp_dir, {
+        "timestamp": timestamp, "rollout_pct": rollout, "risk_flags": risk_flags,
+        "deploy_command": deploy_command, "trigger_succeeded": deploy_ok,
+        "smoke_test_passed": smoke_result, "rolled_back": rolled_back,
+    })
+
+    if not deploy_ok:
+        console.print("[red bold]Deploy trigger command failed.[/red bold]")
+        sys.exit(1)
+
+    console.print("\n[bold]Post-deploy:[/bold] watch P95 latency, error rate, memory for the next 15 minutes.")
+    if smoke_result is False and not rolled_back:
+        sys.exit(1)

pcp/commands/deploy_check.py

@@ -0,0 +1,134 @@
+"""pcp deploy-check — Layer 3 deploy gate (deterministic SDLC phase exit)."""
+
+import re
+import sys
+from datetime import datetime, timezone
+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 validate_file, load_yaml
+
+console = Console()
+
+MAX_CURRENT_STATE_AGE_HOURS = 24
+
+
+def _check_criterion(criterion: dict, project_root: Path) -> tuple[bool, str]:
+    check = criterion.get("check", "manual")
+    target = criterion.get("target", "")
+
+    if check == "file_exists":
+        path = project_root / target
+        return path.exists(), f"{'exists' if path.exists() else 'missing'}: {target}"
+
+    elif check == "ast_pattern":
+        pattern = criterion.get("pattern", "")
+        if not pattern or not target:
+            return criterion.get("status") == "complete", "manual (no pattern)"
+        path = project_root / target
+        if not path.exists():
+            return False, f"file not found: {target}"
+        content = path.read_text(errors="replace")
+        matched = bool(re.search(pattern, content, re.MULTILINE))
+        return matched, f"pattern {'found' if matched else 'not found'} in {target}"
+
+    else:  # manual
+        return criterion.get("status") == "complete", "manual"
+
+
+def _check_current_state_freshness(pcp_dir: Path) -> tuple[bool, str]:
+    cs = pcp_dir / "current_state.md"
+    if not cs.exists():
+        return False, "current_state.md not found — run `pcp scan`"
+    content = cs.read_text()
+    m = re.search(r"Generated: (\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z)", content)
+    if not m:
+        return False, "current_state.md has no timestamp"
+    generated = datetime.strptime(m.group(1), "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+    now = datetime.now(timezone.utc)
+    age_hours = (now - generated).total_seconds() / 3600
+    ok = age_hours <= MAX_CURRENT_STATE_AGE_HOURS
+    return ok, f"current_state.md is {age_hours:.1f}h old (max {MAX_CURRENT_STATE_AGE_HOURS}h)"
+
+
+@click.command()
+@click.option("--phase", default=None, help="Phase name to check (default: current_phase in SDLC_phase.yaml).")
+@click.option("--path", "project_path", type=click.Path(), default=None)
+@click.option("--skip-freshness", is_flag=True, help="Skip current_state.md age check.")
+def deploy_check(phase: str | None, project_path: str | None, skip_freshness: bool):
+    """Layer 3 deploy gate — enforce SDLC phase exit criteria."""
+    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
+    sdlc_path = pcp_dir / "SDLC_phase.yaml"
+
+    if not sdlc_path.exists():
+        console.print("[dim]No SDLC_phase.yaml found — skipping deploy-check.[/dim]")
+        sys.exit(0)
+
+    schema_errors = validate_file(sdlc_path, "sdlc_phase")
+    if schema_errors:
+        console.print("[red]SDLC_phase.yaml schema errors:[/red]")
+        for e in schema_errors:
+            console.print(f"  {e}")
+        sys.exit(1)
+
+    data = load_yaml(sdlc_path)
+    current_phase_name = phase or data.get("current_phase")
+    phases = {p["name"]: p for p in data.get("phases", [])}
+
+    if current_phase_name not in phases:
+        console.print(f"[red]Phase '{current_phase_name}' not found in SDLC_phase.yaml.[/red]")
+        sys.exit(2)
+
+    phase_data = phases[current_phase_name]
+    criteria = phase_data.get("exit_criteria", [])
+
+    console.print(f"[bold]Checking phase:[/bold] {current_phase_name}")
+
+    failures = []
+    passed = []
+
+    if not skip_freshness:
+        ok, detail = _check_current_state_freshness(pcp_dir)
+        if ok:
+            passed.append(f"current_state.md freshness: {detail}")
+        else:
+            failures.append(f"current_state.md stale: {detail}")
+
+    for c in criteria:
+        if c.get("status") == "complete":
+            # Already manually marked complete — trust it
+            passed.append(f"[{c['id']}] {c['description']}")
+            continue
+        ok, detail = _check_criterion(c, project_root)
+        if ok:
+            passed.append(f"[{c['id']}] {c['description']}")
+        else:
+            failures.append(f"[{c['id']}] {c['description']} → {detail}")
+
+    for p in passed:
+        console.print(f"  [green]✓[/green]  {p}")
+
+    from pcp import telemetry
+    telemetry.record(
+        pcp_dir, cycle="qa", cycle_number=None, check="deploy-phase-exit",
+        control_id="CTRL-009", module=None, submodule=None, criterion_id=None,
+        files=[], result="block" if failures else "pass", errors=failures, error_count=len(failures),
+    )
+
+    if failures:
+        console.print(f"\n[red bold]BLOCKED — {len(failures)} exit criteria not met:[/red bold]")
+        for f in failures:
+            console.print(f"  [red]✗[/red]  {f}")
+        sys.exit(1)
+
+    console.print(f"\n[green bold]✓  Phase '{current_phase_name}' exit criteria met.[/green bold]")
+    sys.exit(0)

pcp/commands/design_audit.py

@@ -0,0 +1,323 @@
+"""pcp design-audit — PCP Design lifecycle, stage 5 (Audit/rollup).
+
+Feature Exposure Ladder: for every UI-facing acceptance criterion in a
+project, classifies how discoverable it actually is to an end user, based
+on the design_justification stage 2 (Decide) already recorded (or not) on
+that criterion. Pure aggregation over what's already on disk -- no LLM,
+never hand-edited, same posture as architecture_justification.py, but a
+different audience: this is for product/PM ("can a user find and use this"),
+architecture_justification.md is for engineering ("was this the right
+technical call").
+
+Maps directly onto Google's HEART framework's Adoption pillar, computed
+statically from declared intent rather than live usage telemetry (Happiness/
+Engagement/Retention need real instrumentation -- a separate, deferred
+build-vs-buy decision, not something inferable from a build-time audit).
+"""
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+import click
+import yaml
+from rich.console import Console
+
+from pcp import nav_graph
+from pcp.pcp_dir import find_pcp_dir, get_modules_dir, NoPCPDir
+from pcp.commands.build import _is_ui_facing_criterion
+
+console = Console()
+
+RUNG_LABEL = {
+    1: "Built, Hidden",
+    2: "Exposed, Undiscoverable",
+    3: "Exposed, Discoverable",
+    4: "Exposed, Enriched",
+}
+
+# Crude, deterministic JTBD-shape check: a real "when X, do Y" conditional
+# framing vs. a bare feature-name restatement. Good enough as a rung-3→4
+# gate; false negatives just mean a genuinely good framing sits one rung
+# lower than it deserves, which is a safe direction to err in.
+_JTBD_MARKERS = ("when ", "if ", "whenever ")
+
+
+def _load_yaml(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    return yaml.safe_load(path.read_text()) or {}
+
+
+def _classify_rung(criterion: dict, nav: dict | None = None,
+                   depth_threshold: int = 3) -> int | None:
+    """Rung from the MEASURED artifact where possible, `None` when unknown.
+
+    This used to read one field: no `design_justification` -> rung 1. Measured
+    2026-07-27 on Project O that gave 101 at rung 1, 24 at rung 4, and
+    **zero** at rungs 2 and 3 -- a binary condition wearing a four-rung costume,
+    because nothing ever writes a partial justification. "101 Built, Hidden"
+    described 101 missing fields, not 101 hidden features.
+
+    Rungs 1-3 now come from `nav_graph`: is the criterion's screen reachable
+    from the app's entry page, and how deep. Only rung 4 still consults the
+    declaration, because "is this framed as a real job-to-be-done" is genuinely
+    a property of the writing, not of the artifact.
+
+    `None` means not determinable -- no front end, or a criterion that cannot be
+    tied to a screen. That is reported separately and is NOT rung 1. Reporting
+    an absent measurement as a bad measurement is the whole defect being fixed.
+    """
+    target = criterion.get("target") or ""
+    screen = nav_graph.screen_for_target(target, nav) if nav else None
+    if screen is None:
+        return None
+
+    depths = (nav or {}).get("depths", {})
+    if screen not in depths:
+        return 1                      # measured: genuinely unreachable from entry
+    if depths[screen] > depth_threshold:
+        return 2                      # reachable, but buried
+
+    dj = criterion.get("design_justification") or {}
+    checklist = dj.get("checklist_passed") or []
+    jtbd = (dj.get("jtbd_framing") or "").strip()
+    if jtbd and any(m in jtbd.lower() for m in _JTBD_MARKERS) and checklist:
+        return 4
+    return 3
+
+
+def _nav_depth_threshold() -> int:
+    import os
+    return int(os.environ.get("PCP_NAV_DEPTH_THRESHOLD", "3"))
+
+
+def build_design_audit(pcp_dir: Path) -> dict:
+    """Pure aggregation, no LLM -- safe to call at any point."""
+    modules_dir = get_modules_dir(pcp_dir)
+    modules = []
+    rung_counts = {r: 0 for r in RUNG_LABEL}
+    # Criteria whose screen cannot be identified are counted here, NOT dumped
+    # into rung 1. "We could not measure this" and "this is hidden" are
+    # different facts and must not share a bucket.
+    undetermined = 0
+    nav = nav_graph.analyse(pcp_dir.parent)
+    total_ui_criteria = 0
+    nav_depths: list[int] = []
+    nav_depth_missing = 0
+    customizable_count = 0
+
+    if modules_dir.exists():
+        for mod_path in sorted(p for p in modules_dir.iterdir() if p.is_dir()):
+            acceptance = _load_yaml(mod_path / "acceptance.yaml")
+            ui_criteria = []
+            for c in acceptance.get("criteria", []):
+                if not _is_ui_facing_criterion(c):
+                    continue
+                rung = _classify_rung(c, nav, _nav_depth_threshold())
+                if rung is None:
+                    undetermined += 1
+                else:
+                    rung_counts[rung] += 1
+                total_ui_criteria += 1
+                dj = c.get("design_justification") or {}
+                nav_depth = c.get("nav_depth")
+                if nav_depth is None:
+                    nav_depth_missing += 1
+                else:
+                    nav_depths.append(nav_depth)
+                customizable = bool(dj.get("customizable"))
+                if customizable:
+                    customizable_count += 1
+                ui_criteria.append({
+                    "id": c.get("id"),
+                    "description": c.get("description"),
+                    "rung": rung,
+                    "jtbd_framing": dj.get("jtbd_framing", ""),
+                    "deviations_from_system": dj.get("deviations_from_system", ""),
+                    "nav_depth": nav_depth,
+                    "customizable": customizable,
+                    "customization_notes": dj.get("customization_notes", ""),
+                })
+            if ui_criteria:
+                modules.append({"module": mod_path.name, "criteria": ui_criteria})
+
+    threshold = _nav_depth_threshold()
+    within_threshold = sum(1 for d in nav_depths if d <= threshold)
+    nav_depth_summary = {
+        "declared": len(nav_depths),
+        "missing": nav_depth_missing,
+        "max": max(nav_depths) if nav_depths else None,
+        "avg": round(sum(nav_depths) / len(nav_depths), 1) if nav_depths else None,
+        "within_threshold_pct": round(within_threshold / len(nav_depths), 2) if nav_depths else None,
+        "threshold": threshold,
+    }
+    customization_summary = {
+        "customizable_count": customizable_count,
+        "total_ui_criteria": total_ui_criteria,
+        "customizable_pct": round(customizable_count / total_ui_criteria, 2) if total_ui_criteria else None,
+    }
+
+    ui_archetype = None
+    conventions_path = pcp_dir / "design_conventions.yaml"
+    if conventions_path.exists():
+        ui_archetype = (_load_yaml(conventions_path) or {}).get("ui_archetype")
+
+    return {
+        "modules": modules,
+        "rung_counts": rung_counts,
+        "undetermined": undetermined,
+        "nav_analysis": nav,
+        "total_ui_criteria": total_ui_criteria,
+        "nav_depth": nav_depth_summary,
+        "customization": customization_summary,
+        "ui_archetype": ui_archetype,
+    }
+
+
+def _render_markdown(data: dict, timestamp: str) -> str:
+    lines = [
+        "# Design Audit — Feature Exposure Ladder",
+        "",
+        f"_Auto-generated by `pcp design-audit` at {timestamp}. Never hand-edit — "
+        "the rationale lives in each criterion's design_justification; this is a "
+        "rollup view, not a second place to author it._",
+        "",
+        "PCP Design lifecycle, stage 5 (Audit/rollup). Maps to Google HEART's Adoption "
+        "pillar. Rungs 1-3 are MEASURED from the built UI — pages discovered from the "
+        "front end's own entry config, edges from its links, depth by shortest path from "
+        "the entry page. Only rung 4 consults a declaration, because whether a screen is "
+        "framed as a real job-to-be-done is a property of the writing, not the artifact.",
+        "",
+        "## Rung Distribution",
+        "",
+        "| Rung | Label | Criteria |",
+        "|---|---|---|",
+    ]
+    for rung, label in RUNG_LABEL.items():
+        lines.append(f"| {rung} | {label} | {data['rung_counts'].get(rung, 0)} |")
+    lines.append("")
+
+    # "Could not measure" is its own row and never folded into rung 1. The
+    # previous version classified a missing `design_justification` as
+    # "Built, Hidden" and reported 101 of them on Project O -- a
+    # statement about absent paperwork dressed as a discoverability crisis.
+    nav = data.get("nav_analysis") or {}
+    undet = data.get("undetermined", 0)
+    if undet:
+        lines += [
+            f"**{undet} UI-facing criteria could not be placed on the ladder.** This is "
+            "NOT a finding about the product — it means the criterion could not be tied "
+            "to a screen, so its discoverability was never measured.",
+            "",
+        ]
+        if nav.get("available"):
+            lines += [
+                f"The app itself WAS measured: `{nav.get('ui_root')}` — "
+                f"{len(nav.get('pages', []))} page(s), entry `{nav.get('entry')}`, "
+                f"{len(nav.get('unreachable', []))} unreachable. What is missing is the "
+                "link from criterion to screen: declare `target` on a UI-facing criterion "
+                "and it becomes measurable.",
+                "",
+            ]
+        else:
+            lines += [
+                f"No front end could be measured either ({nav.get('reason', 'unknown')}), "
+                "so nothing here is a claim about discoverability.",
+                "",
+            ]
+    if nav.get("available") and nav.get("unreachable"):
+        lines += [
+            "**Unreachable pages** (exist in the build, no path from the entry page): "
+            + ", ".join(f"`{p}`" for p in nav["unreachable"]),
+            "",
+        ]
+
+    nd = data["nav_depth"]
+    lines += ["## Navigation Depth (clicks from entry point)", ""]
+    if nd["declared"]:
+        lines.append(
+            f"Declared on {nd['declared']} UI-facing criteria ({nd['missing']} missing) — "
+            f"max {nd['max']}, avg {nd['avg']}, {nd['within_threshold_pct']:.0%} within the "
+            f"{nd['threshold']}-click threshold. Self-declared, not computed from a real routing "
+            "graph — see CTRL-025."
+        )
+    else:
+        lines.append(f"_No criteria declare nav_depth yet ({nd['missing']} missing)._")
+    lines.append("")
+
+    cz = data["customization"]
+    lines += ["## Feature Customization", ""]
+    if cz["total_ui_criteria"]:
+        lines.append(
+            f"{cz['customizable_count']}/{cz['total_ui_criteria']} UI-facing criteria "
+            f"({cz['customizable_pct']:.0%}) declare `customizable: true` — see CTRL-026 for the "
+            "structural check on those declarations."
+        )
+    else:
+        lines.append("_No UI-facing criteria yet._")
+    lines.append("")
+
+    lines += ["## Top Menu Bar Convention", ""]
+    if data["ui_archetype"] == "desktop_app":
+        lines.append("`ui_archetype: desktop_app` — CTRL-027 checks for File/Edit/View/Help-style "
+                      "menus; see provenance.md / telemetry for the latest result.")
+    else:
+        lines.append(f"`ui_archetype: {data['ui_archetype'] or 'web_app (default)'}` — "
+                      "menu-bar convention check inert (desktop_app only).")
+    lines.append("")
+
+    if not data["modules"]:
+        lines.append("_No UI-facing criteria found yet._")
+        return "\n".join(lines)
+
+    for m in data["modules"]:
+        lines.append(f"## Module: `{m['module']}`")
+        lines.append("")
+        lines.append("| Criterion | Rung | JTBD Framing | Nav Depth | Customizable |")
+        lines.append("|---|---|---|---|---|")
+        for c in m["criteria"]:
+            # rung None = the criterion's screen could not be identified, so
+            # discoverability was never measured. It gets its own cell rather
+            # than borrowing rung 1's "Built, Hidden" label and its ⚠.
+            rung = c["rung"]
+            flag = " ⚠" if rung == 1 else ""
+            rung_cell = f"{rung} ({RUNG_LABEL[rung]})" if rung is not None else "— (not measured)"
+            nav_depth_cell = c["nav_depth"] if c["nav_depth"] is not None else "—"
+            customizable_cell = "✓" if c["customizable"] else "—"
+            lines.append(
+                f"| {c['id']}: {c['description']}{flag} | {rung_cell} | "
+                f"{c['jtbd_framing'] or '—'} | {nav_depth_cell} | {customizable_cell} |"
+            )
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def write_design_audit(pcp_dir: Path) -> Path:
+    data = build_design_audit(pcp_dir)
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    md = _render_markdown(data, timestamp)
+    out = pcp_dir / "design_audit.md"
+    out.write_text(md)
+    return out
+
+
+@click.command(name="design-audit")
+@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 design_audit.md.")
+def design_audit(project_path: str | None, output_json: bool):
+    """Feature Exposure Ladder — roll up how discoverable UI-facing criteria actually are."""
+    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 output_json:
+        click.echo(json.dumps(build_design_audit(pcp_dir), indent=2, default=str))
+        return
+
+    out_path = write_design_audit(pcp_dir)
+    console.print(f"[green]Design audit written[/green] -> {out_path.relative_to(pcp_dir.parent)}")