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

pcp/commands/status.py

@@ -0,0 +1,180 @@
+"""pcp status — generate or refresh pcp.md governance snapshot."""
+
+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, get_modules_dir, NoPCPDir
+from pcp.schema.validator import validate_file, load_yaml
+from pcp.pcp_status import write_pcp_md
+
+console = Console()
+
+
+def _load_modules_results(modules_dir: Path, project_root: Path) -> list[dict]:
+    """Reconstruct module results from existing current_state.md or live scan."""
+    results = []
+    for af in sorted(modules_dir.glob("*/acceptance.yaml")):
+        module_name = af.parent.name
+        data = load_yaml(af)
+        criteria_results = []
+        for c in data.get("criteria", []):
+            criteria_results.append({
+                "id": c["id"],
+                "description": c["description"],
+                "check": c.get("check", "manual"),
+                "status": c.get("status", "pending"),
+                "detail": "",
+            })
+        results.append({"module": module_name, "criteria": criteria_results})
+    return results
+
+
+def _parse_from_current_state(current_state_path: Path) -> dict[str, str]:
+    """Parse status from current_state.md — avoids re-running all checks."""
+    if not current_state_path.exists():
+        return {}
+    statuses = {}
+    for line in current_state_path.read_text().splitlines():
+        m = re.match(r"- \[([ x])\] ([A-Z0-9_-]+/[A-Z][0-9]+):", line.strip())
+        if m:
+            statuses[m.group(2)] = "complete" if m.group(1) == "x" else "pending"
+    return statuses
+
+
+PM_STATUS_SYSTEM_PROMPT = """\
+You are an expert AI product manager.
+Your task is to generate a plain-English project status report for a non-technical PM based on the provided project context and git history.
+
+The status report must be user-friendly, high-level, and avoid code snippets, technical jargon, or raw config file content.
+It must include:
+1. Current SDLC Phase and Completion % (calculated from criteria complete/total).
+2. This Week's Progress (derived from recent git commits and completed criteria).
+3. Current Blockers / PM Actions Needed (e.g. pending manual criteria, inputs/decisions needed).
+4. What's Next (what features/modules will be developed next).
+
+Keep it concise, clear, and action-oriented. Use formatting like bold text and bullet points.
+"""
+
+
+def _get_recent_commits(repo_path: Path) -> str:
+    import subprocess
+    result = subprocess.run(
+        ["git", "log", "--since=7.days.ago", "--oneline"],
+        capture_output=True,
+        text=True,
+        cwd=repo_path,
+    )
+    if result.returncode != 0:
+        return "No recent commits."
+    return result.stdout
+
+
+@click.command()
+@click.option("--path", "project_path", type=click.Path(), default=None)
+@click.option("--rescan", is_flag=True,
+              help="Re-run full scan before writing pcp.md (slower but accurate).")
+@click.option("--print", "print_only", is_flag=True,
+              help="Print pcp.md to stdout instead of writing file.")
+@click.option("--pm", "pm_mode", is_flag=True,
+              help="Generate a plain-English status report for the PM.")
+def status(project_path: str | None, rescan: bool, print_only: bool, pm_mode: bool):
+    """Generate or refresh pcp.md governance snapshot at project root.
+
+    By default reads from existing current_state.md (fast).
+    Use --rescan to re-evaluate all acceptance criteria first.
+    """
+    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
+    modules_dir = get_modules_dir(pcp_dir)
+
+    if rescan:
+        # Invoke scan command logic inline
+        from pcp.commands.scan import _scan_module, _write_current_state, _load_prior_manual_status
+        current_state_path = pcp_dir / "current_state.md"
+        prior_manual = _load_prior_manual_status(current_state_path)
+        modules_results = []
+        for af in sorted(modules_dir.glob("*/acceptance.yaml")):
+            module_name = af.parent.name
+            result = _scan_module(module_name, af, project_root, prior_manual)
+            modules_results.append(result)
+        timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        _write_current_state(pcp_dir, modules_results, timestamp)
+    else:
+        # Fast path: read from current_state.md
+        statuses = _parse_from_current_state(pcp_dir / "current_state.md")
+        modules_results = _load_modules_results(modules_dir, project_root)
+        # Apply parsed statuses
+        for m in modules_results:
+            for c in m["criteria"]:
+                key = f"{m['module'].upper()}/{c['id']}"
+                if key in statuses:
+                    c["status"] = statuses[key]
+        timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    total = sum(len(m["criteria"]) for m in modules_results)
+    complete = sum(1 for m in modules_results for c in m["criteria"] if c["status"] == "complete")
+
+    pcp_md_path = write_pcp_md(pcp_dir, modules_results, timestamp, total, complete)
+
+    if pm_mode:
+        from pcp.llm import client as llm
+        obj_text = (pcp_dir / "objective.md").read_text() if (pcp_dir / "objective.md").exists() else ""
+        current_state_text = (pcp_dir / "current_state.md").read_text() if (pcp_dir / "current_state.md").exists() else ""
+        sdlc_text = (pcp_dir / "SDLC_phase.yaml").read_text() if (pcp_dir / "SDLC_phase.yaml").exists() else ""
+        commits = _get_recent_commits(project_root)
+
+        score_pct = f"{complete}/{total} ({complete/total:.0%})" if total else "0/0 (0%)"
+
+        user_prompt = (
+            f"Objective:\n{obj_text}\n\n"
+            f"Current State & Completion:\nCompletion Score: {score_pct}\n{current_state_text}\n\n"
+            f"SDLC Phase Config:\n{sdlc_text}\n\n"
+            f"Recent Commits (last 7 days):\n{commits}\n"
+        )
+
+        console.print("[dim]Generating plain-English PM status report...[/dim]\n")
+        try:
+            report_text = llm.call(
+                PM_STATUS_SYSTEM_PROMPT, user_prompt,
+                model=llm.JUDGE_MODEL, pcp_dir=pcp_dir, command="status-pm",
+            )
+            click.echo(report_text)
+        except Exception as e:
+            console.print(f"[red]Error generating PM report:[/red] {e}")
+            sys.exit(2)
+        return
+
+    if print_only:
+        click.echo(pcp_md_path.read_text())
+        return
+
+    score = complete / total if total else 0.0
+    color = "green" if score >= 0.8 else "yellow" if score >= 0.5 else "red"
+    console.print(f"[{color}]{complete}/{total} ({score:.0%})[/{color}]  →  pcp.md")
+
+    # Escalation-acknowledgment watchdog — an escalation recorded but never
+    # acted on must stay loudly visible, not buried in escalations.yaml.
+    from pcp import escalations
+    for e in escalations.find_stale(pcp_dir):
+        console.print(
+            f"[red bold]STALE ESCALATION [{e.get('state', 'unacked')}]:[/red bold] "
+            f"{e.get('module')}/{e.get('criterion_id')} ({e.get('category', 'uncategorized')}) "
+            f"waiting {e.get('age_hours')}h — ack: pcp escalations --ack {e.get('module')}/{e.get('criterion_id')}"
+        )
+
+    # Notification dead-man's-switch — attempts without successes means the
+    # pipeline is broken and nobody is being reached.
+    from pcp.commands.watch import check_notify_heartbeat
+    hb = check_notify_heartbeat(pcp_dir)
+    if hb:
+        console.print(f"[red bold]{hb}[/red bold]")

pcp/commands/takeover.py

@@ -0,0 +1,55 @@
+"""pcp takeover — one-shot: preflight -> kickoff -> autonomous build.
+
+The single entrypoint for "point pcp at a vision doc and let it run the
+project." Chains the existing doctor/kickoff/build commands rather than
+duplicating their logic.
+"""
+
+import sys
+from pathlib import Path
+
+import click
+import yaml
+from rich.console import Console
+
+from pcp.commands.build import build
+from pcp.commands.doctor import check_environment
+from pcp.commands.kickoff import kickoff
+
+console = Console()
+
+
+def _current_phase(pcp_dir: Path) -> str | None:
+    path = pcp_dir / "SDLC_phase.yaml"
+    if not path.exists():
+        return None
+    return (yaml.safe_load(path.read_text()) or {}).get("current_phase")
+
+
+@click.command()
+@click.argument("vision_file", type=click.Path(exists=True))
+@click.option("--path", "project_path", type=click.Path(), default=".",
+              help="Project root (default: current directory).")
+@click.option("--force", is_flag=True, help="Force overwrite existing .pcp/ directory.")
+def takeover(vision_file: str, project_path: str, force: bool):
+    """Take over a project end-to-end: preflight, kickoff from a vision doc, then build every pending criterion."""
+    root = Path(project_path).resolve()
+    pcp_dir = root / ".pcp"
+    ctx = click.get_current_context()
+
+    console.print("[bold]Step 1/3 — environment preflight[/bold]")
+    check_environment(pcp_dir, fatal_on_missing_required=True)
+
+    console.print("\n[bold]Step 2/3 — kickoff from vision[/bold]")
+    ctx.invoke(kickoff, vision_file=vision_file, project_path=project_path, force=force)
+
+    phase = _current_phase(pcp_dir)
+    if phase in (None, "planning"):
+        console.print(
+            "\n[yellow]Strategy not approved — stopping before build. "
+            "Re-run `pcp takeover` once you're ready.[/yellow]"
+        )
+        sys.exit(0)
+
+    console.print("\n[bold]Step 3/3 — autonomous build[/bold]")
+    ctx.invoke(build, module_name=None, project_path=project_path)

pcp/commands/telemetry_cmd.py

@@ -0,0 +1,167 @@
+"""pcp telemetry — summarize .pcp/telemetry.jsonl for analysis.
+
+Closes the loop on "captured to analyse and learn": telemetry.jsonl has the raw
+per-attempt/per-qa-check records, this command rolls them up so the data is
+actually useful without hand-writing a notebook every time.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from pcp.pcp_dir import find_pcp_dir, NoPCPDir
+from pcp import telemetry as telemetry_lib
+
+console = Console()
+
+
+@click.command(name="telemetry")
+@click.option("--path", "project_path", type=click.Path(), default=None,
+              help="Project root (default: cwd, walks up to find .pcp/).")
+@click.option("--json", "output_json", is_flag=True, help="Print raw per-module aggregates as JSON.")
+def telemetry_cmd(project_path: str | None, output_json: bool):
+    """Summarize .pcp/telemetry.jsonl — per-module retries, QA error rate, languages, cost."""
+    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)
+
+    records = telemetry_lib.load(pcp_dir)
+    if not records:
+        console.print("[dim]No .pcp/telemetry.jsonl found — run `pcp build` first.[/dim]")
+        sys.exit(0)
+
+    agg = telemetry_lib.aggregate(records)
+    by_module = agg["by_module"]
+
+    if output_json:
+        click.echo(json.dumps({
+            k: {**v, "criteria": sorted(filter(None, v["criteria"])), "languages": sorted(v["languages"])}
+            for k, v in by_module.items()
+        }, indent=2))
+        return
+
+    table = Table(title="PCP Build Telemetry — per module")
+    table.add_column("Module")
+    table.add_column("Criteria")
+    table.add_column("Attempts")
+    table.add_column("Avg attempts/criterion")
+    table.add_column("QA error rate")
+    table.add_column("Tokens in/cache/out")
+    table.add_column("Cost")
+    table.add_column("Languages")
+
+    total_cost = 0.0
+    for m_name, v in sorted(by_module.items()):
+        n_crit = len(v["criteria"]) or 1
+        avg_attempts = v["attempts"] / n_crit
+        qa_rate = f"{v['qa_blocks']}/{v['qa_total']}" if v["qa_total"] else "—"
+        table.add_row(
+            m_name, str(len(v["criteria"])), str(v["attempts"]), f"{avg_attempts:.1f}",
+            qa_rate, f"{v['tokens_in']:,}/{v['tokens_cache_read']:,}/{v['tokens_out']:,}",
+            f"${v['cost']:.2f}", ", ".join(sorted(v["languages"])) or "—",
+        )
+        total_cost += v["cost"]
+
+    console.print(table)
+
+    # Worktree merge conflict rate — comparable against AgenticFlict's
+    # (arXiv:2604.03551) 27.67% agent-authored-PR conflict baseline.
+    merges = [r for r in records if r.get("check") == "worktree-merge"]
+    if merges:
+        conflicts = sum(1 for r in merges if r.get("result") == "block")
+        console.print(
+            f"[dim]Worktree merges: {len(merges)}, conflicts: {conflicts} "
+            f"({conflicts / len(merges):.0%}) — agentic-PR literature baseline 27.67% (AgenticFlict)[/dim]"
+        )
+
+    # Output per dollar over time. Nothing reported this, so a real ~6x
+    # degradation on Project O went unseen for a week while commits/day
+    # rose — the flattering metric was the only visible one.
+    weeks = telemetry_lib.productivity_by_week(records)
+    if len(weeks) > 1:
+        # Written vs landed, side by side. Telemetry alone reads healthy — on
+        # Project O it called 2026-W31 the most productive week of the run
+        # (+12,342 lines, $0.018/line) while git says non-test code grew by 599.
+        # The ratio between them is the signal; neither number is, alone.
+        repo = telemetry_lib.repo_net_lines_by_week(pcp_dir.parent)
+        landed = repo["by_week"]
+        wt = Table(title="Output per dollar — by week")
+        wt.add_column("Week")
+        wt.add_column("Attempts", justify="right")
+        wt.add_column("Spend", justify="right")
+        wt.add_column("Lines written", justify="right")
+        if landed:
+            wt.add_column("Landed (non-test)", justify="right")
+            wt.add_column("Survived", justify="right")
+            wt.add_column("$/landed line", justify="right")
+        else:
+            wt.add_column("$/written line", justify="right")
+
+        for w in weeks:
+            row = [w["week"], str(w["attempts"]), f"${w['cost_usd']:.2f}",
+                   f"{w['net_lines']:+,}"]
+            if landed:
+                net = landed.get(w["week"])
+                if net is None:
+                    row += ["—", "—", "—"]
+                else:
+                    row.append(f"{net:+,}")
+                    written = w["net_lines"]
+                    if net > written:
+                        # More landed than the build loop recorded writing, so code
+                        # arrived by some other path — an ad-hoc agent, a hand edit,
+                        # a bulk merge. That is CTRL-037's story showing up in the
+                        # numbers, and printing it as "5185% survived" would bury it.
+                        row.append("[yellow]outside loop[/yellow]")
+                    elif written > 0:
+                        row.append(f"{net / written:.0%}")
+                    else:
+                        row.append("—")
+                    # A week that spent money and landed nothing is the single most
+                    # important row to see — never render it as a tidy $0.00.
+                    row.append(f"${w['cost_usd'] / net:.2f}" if net > 0
+                               else "[red]nothing landed[/red]")
+            else:
+                per = w["usd_per_net_line"]
+                row.append(f"${per:.3f}" if per is not None
+                           else ("[red]no net output[/red]" if w["cost_usd"] > 0 else "—"))
+            wt.add_row(*row)
+        console.print(wt)
+
+        if landed:
+            console.print(
+                "[dim]`Lines written` is every attempt's diff, so it includes superseded "
+                "attempts, reverts and test code. `Landed` is net authored non-test source "
+                "that survived in git. `Survived` is the ratio — the number actually worth "
+                "watching, since a high written count with a low survival rate is churn, "
+                "not velocity. `outside loop` means more landed than the build loop recorded "
+                "writing, i.e. code arrived by some other path.[/dim]"
+            )
+            # No silent caps: say what was excluded and why.
+            skipped = repo["bulk_commits_skipped"]
+            if skipped:
+                detail = ", ".join(f"{w} ({n})" for w, n in sorted(skipped.items()))
+                console.print(
+                    f"[dim]Excluded {sum(skipped.values())} bulk commit(s) over "
+                    f"{repo['bulk_threshold']:,} changed source lines — {detail}. Those are "
+                    "vendor imports, bulk moves or generated dumps, not one criterion's "
+                    "work; counting them made survival read 107372% on a real project.[/dim]"
+                )
+        else:
+            console.print(
+                "[dim]git unavailable — showing written lines only. These count every "
+                "attempt's diff including superseded work, so treat $/written line as a "
+                "trend, not an accounting figure.[/dim]"
+            )
+
+    console.print(
+        f"\n[dim]{len(records)} total records — {len(agg['build_records'])} build, "
+        f"{len(agg['qa_records'])} qa — total cost ~${total_cost:.2f}[/dim]"
+    )
+    console.print("[dim]Raw data: .pcp/telemetry.jsonl (one JSON object per line — load into pandas/duckdb for deeper analysis)[/dim]")

pcp/commands/validate_module.py

@@ -0,0 +1,153 @@
+"""pcp validate-module <name> — per-module spec alignment check."""
+
+import json
+import sys
+from pathlib import Path
+
+import click
+import yaml
+from rich.console import Console
+
+from pcp.pcp_dir import find_pcp_dir, get_modules_dir, get_objective, get_decomposition, NoPCPDir
+from pcp.schema.validator import validate_file, load_yaml
+from pcp.llm import client as llm
+
+console = Console()
+
+SYSTEM_PROMPT = """\
+You are a program-context auditor. Check whether a single module specification \
+is aligned with the program objective and decomposition rationale.
+
+Output ONLY valid JSON — no prose, no markdown, no code fences.
+
+Output schema:
+{
+  "alignment_score": 0.0,
+  "aligned": true,
+  "gaps": ["string"],
+  "contradictions": ["string"],
+  "decomposition_conflicts": ["string"],
+  "suggestions": ["string"]
+}
+
+alignment_score: 0.0 (no alignment) to 1.0 (perfectly aligned).
+aligned: true if alignment_score >= 0.7 and no contradictions.
+"""
+
+
+def _build_prompt(objective: str, decomposition: str | None, module_name: str, spec: dict) -> str:
+    parts = [f"## Program Objective\n\n{objective}\n"]
+    if decomposition:
+        parts.append(f"## Decomposition Rationale\n\n{decomposition}\n")
+    parts.append(f"## Module to Validate: {module_name}\n")
+    parts.append(f"```yaml\n{yaml.dump(spec, default_flow_style=False)}```\n")
+    parts.append(
+        f"Does the '{module_name}' module spec align with the objective and decomposition? "
+        "Are its objective_coverage claims accurate? Does it conflict with the decomposition?"
+    )
+    return "\n".join(parts)
+
+
+def run_validate_module(pcp_dir: Path, module_name: str) -> dict | None:
+    """Core module-vs-decomposition alignment check, reusable outside the CLI
+    command (e.g. build.py's wave-merge gate). Returns the LLM judge's result
+    dict, or None if the module is missing/deprecated/objective.md absent --
+    callers decide what "no result" means for their own control flow, same
+    posture as run_validate_strategy."""
+    modules_dir = get_modules_dir(pcp_dir)
+    spec_path = modules_dir / module_name / "spec.yaml"
+    if not spec_path.exists():
+        return None
+
+    validate_file(spec_path, "module_spec")  # schema errors surfaced by the CLI wrapper, not fatal here
+
+    spec = load_yaml(spec_path)
+    if spec.get("deprecated"):
+        return None
+
+    objective_path = get_objective(pcp_dir)
+    if not objective_path.exists():
+        return None
+
+    objective = objective_path.read_text()
+    decomp_path = get_decomposition(pcp_dir)
+    decomposition = decomp_path.read_text() if decomp_path.exists() else None
+
+    return llm.call_json(
+        SYSTEM_PROMPT, _build_prompt(objective, decomposition, module_name, spec),
+        model=llm.JUDGE_MODEL, pcp_dir=pcp_dir, command="validate-module",
+    )
+
+
+@click.command()
+@click.argument("module_name")
+@click.option("--json", "output_json", is_flag=True, help="Output raw JSON.")
+@click.option("--path", "project_path", type=click.Path(), default=None)
+def validate_module(module_name: str, output_json: bool, project_path: str | None):
+    """Check whether a module spec aligns with the objective and decomposition."""
+    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)
+
+    modules_dir = get_modules_dir(pcp_dir)
+    spec_path = modules_dir / module_name / "spec.yaml"
+
+    if not spec_path.exists():
+        console.print(f"[red]Module '{module_name}' not found:[/red] {spec_path}")
+        console.print(f"Available: {', '.join(p.parent.name for p in modules_dir.glob('*/spec.yaml'))}")
+        sys.exit(2)
+
+    errors = validate_file(spec_path, "module_spec")
+    if errors:
+        console.print(f"[yellow]⚠  schema errors in {module_name}/spec.yaml:[/yellow]")
+        for e in errors:
+            console.print(f"   {e}")
+
+    spec = load_yaml(spec_path)
+    if spec.get("deprecated"):
+        console.print(f"[dim]{module_name} is deprecated — skipping.[/dim]")
+        sys.exit(0)
+
+    objective_path = get_objective(pcp_dir)
+    if not objective_path.exists():
+        console.print("[red]Error:[/red] .pcp/objective.md not found.")
+        sys.exit(2)
+
+    if not output_json:
+        console.print(f"[dim]Validating module '{module_name}'...[/dim]")
+
+    try:
+        result = run_validate_module(pcp_dir, module_name)
+    except RuntimeError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        sys.exit(2)
+    except ValueError as e:
+        console.print(f"[red]LLM returned invalid JSON:[/red] {e}")
+        sys.exit(2)
+
+    if output_json:
+        click.echo(json.dumps(result, indent=2))
+        sys.exit(0 if result.get("aligned") else 1)
+
+    score = result.get("alignment_score", 0.0)
+    aligned = result.get("aligned", False)
+    color = "green" if aligned else "red"
+
+    console.print(f"\n[bold]Module:[/bold] {module_name}")
+    console.print(f"[bold]Alignment:[/bold] [{color}]{score:.0%}[/{color}]  {'✓' if aligned else '✗'}\n")
+
+    for gap in result.get("gaps", []):
+        console.print(f"  [yellow]⚠  Gap:[/yellow] {gap}")
+    for c in result.get("contradictions", []):
+        console.print(f"  [red]✗  Contradiction:[/red] {c}")
+    for dc in result.get("decomposition_conflicts", []):
+        console.print(f"  [red]✗  Decomp conflict:[/red] {dc}")
+    for s in result.get("suggestions", []):
+        console.print(f"  [dim]→  {s}[/dim]")
+
+    if aligned and not result.get("gaps") and not result.get("contradictions"):
+        console.print("[green]✓  Module spec is aligned.[/green]")
+
+    sys.exit(0 if aligned else 1)