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

pcp/commands/build_plan.py

@@ -0,0 +1,153 @@
+"""pcp build-plan — deterministic execution plan, no agents spawned.
+
+Root of tonight's redesign (2026-07-30): `pcp build`'s Python execution engine
+(worktree-per-criterion, ThreadPoolExecutor, merge/retry-on-conflict) is one of
+TWO independent orchestration implementations in this codebase -- the `/pcp`
+skill's own SKILL.md already documents a second one, built on the Workflow
+tool's `pipeline()`/`parallel()`, and CLAUDE.md describes both as if they were
+the same mechanism. They aren't. The Python engine reinvents coordination the
+harness already provides natively, and pays for it: measured on Project O,
+5 of 5 completed `query-eval-harness` criteria hit a merge conflict in one run,
+99% of that run's cost sat on the conflicted criteria, and two criteria were
+still stuck mid-retry two hours in.
+
+The concrete root cause, read directly out of the colliding file: every
+criterion in a module has to add its own method to one shared facade class in
+`__init__.py` and remove its own entry from a shared `_PENDING` dict -- small,
+non-overlapping in meaning, but landing in the same file at the same insertion
+anchor, so git's diff sees a conflict where nothing semantically conflicts.
+
+This command is the new split: Python stays the planner (deterministic, rung 1,
+reuses the exact wave-computation this project already had -- nothing here is
+new logic, it's `gather_modules_to_build`/`compute_waves`/
+`_compute_criterion_waves` from build.py, called and serialized rather than
+immediately acted on). Python stops being the executor. Emits a plan; spawns
+nothing. Execution -- actually running agents against that plan -- happens
+through the Workflow tool from an orchestrating session (the `/pcp` skill),
+using real harness primitives: `parallel()` for criteria that provably touch
+disjoint files, `pipeline()`/a single-writer step for the ones that don't.
+
+**Shared-surface files are the reason a per-criterion `target` isn't enough to
+schedule safely.** A criterion's own new file (`metrics/plan_correctness.py`)
+is genuinely disjoint from another criterion's new file -- true parallelism is
+safe there. But BOTH criteria still touch the module's `__init__.py` to
+register, and no criterion ever declares that as its `target` (it's an
+implicit side effect of the registration convention every `pcp init --module`
+scaffold uses, not something anyone writes down). So `shared_surface_files`
+here is not inferred from declared targets at all -- it's the module's own
+known facade files: `src/modules/<module>/__init__.py` and any file a
+MOD_A00x criterion in that module declares as `target` (MOD_A002's app-registry
+target, MOD_A004's interface-file target). Every criterion in the module is
+marked as touching these implicitly, conservatively, whether or not its own
+declared target says so -- the same asymmetry `_partition_wave_by_file_scope`
+already reasons from: reopening/serializing too much costs parallelism,
+missing a real collision costs a broken merge, and the second is worse.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from pcp.pcp_dir import find_pcp_dir, NoPCPDir
+from pcp.commands.build import gather_modules_to_build, compute_waves, _compute_criterion_waves
+
+console = Console()
+
+
+def _module_shared_surface(pcp_dir: Path, module_name: str) -> list[str]:
+    """The facade files every criterion in this module implicitly touches to
+    register, regardless of what each criterion's own `target` says.
+
+    `src/modules/<module>/__init__.py` is the scaffold's own convention
+    (see init.py's MODULE_ACCEPTANCE_TEMPLATE / MOD_A002-A004) -- it exists
+    whether or not it's on disk yet, because the first criterion to land
+    creates it. MOD_A002 (registers through the application interface) and
+    MOD_A004 (interface file) declare their OWN targets explicitly; those are
+    pulled in here too, since registering ANY new criterion touches both the
+    facade and, if the module has one, the interface file.
+    """
+    mod_slug = module_name.replace("-", "_")
+    surface = {f"src/modules/{mod_slug}/__init__.py"}
+    acc_path = pcp_dir / "strategy" / "modules" / module_name / "acceptance.yaml"
+    if acc_path.exists():
+        from pcp.schema.validator import load_yaml
+        try:
+            data = load_yaml(acc_path) or {}
+        except Exception:
+            data = {}
+        for c in data.get("criteria", []) or []:
+            cid = str(c.get("id") or "")
+            if cid.startswith("MOD_") and c.get("target"):
+                surface.add(c["target"])
+    return sorted(surface)
+
+
+def build_plan(pcp_dir: Path, module_name: str | None = None) -> dict:
+    """{modules: [{name, wave, shared_surface_files, dependencies,
+    criterion_waves: [[{id, description, check, target, depends_on,
+    touches_shared_surface}, ...], ...]}], total_criteria: int}.
+
+    Pure aggregation over data build.py already computes -- no new scheduling
+    logic, no LLM, nothing spawned. `criterion_waves` is a list of lists: each
+    inner list is one dependency wave (from `_compute_criterion_waves`), so
+    the consumer knows both "these can run together" and "in what order
+    relative to each other" without recomputing anything.
+    """
+    modules = gather_modules_to_build(pcp_dir, module_name)
+    module_waves = compute_waves(modules)
+
+    out_modules = []
+    for mod in modules:
+        surface = _module_shared_surface(pcp_dir, mod["name"])
+        crit_wave_of = _compute_criterion_waves(mod)
+        max_wave = max(crit_wave_of.values()) if crit_wave_of else 0
+
+        criterion_waves = []
+        for w in range(max_wave + 1):
+            wave_criteria = [c for c in mod["pending_criteria"] if crit_wave_of.get(c["id"], 0) == w]
+            criterion_waves.append([
+                {
+                    "id": c["id"],
+                    "description": c.get("description", ""),
+                    "check": c.get("check", "manual"),
+                    "target": c.get("target"),
+                    "depends_on": c.get("depends_on") or [],
+                    "touches_shared_surface": True,  # see _module_shared_surface docstring
+                }
+                for c in wave_criteria
+            ])
+
+        out_modules.append({
+            "name": mod["name"],
+            "wave": module_waves.get(mod["name"], 0),
+            "dependencies": mod["spec"].get("dependencies") or [],
+            "shared_surface_files": surface,
+            "criterion_waves": criterion_waves,
+        })
+
+    out_modules.sort(key=lambda m: (m["wave"], m["name"]))
+    total = sum(len(w) for m in out_modules for w in m["criterion_waves"])
+    return {"modules": out_modules, "total_criteria": total}
+
+
+@click.command(name="build-plan")
+@click.option("--module", "module_name", default=None, help="Limit the plan to one module.")
+@click.option("--path", "project_path", type=click.Path(), default=None,
+              help="Project root override.")
+def build_plan_cmd(module_name: str | None, project_path: str | None):
+    """Emit the deterministic build plan as JSON. Spawns nothing.
+
+    Consumed by the `/pcp` skill's Workflow-tool execution -- see this
+    module's own docstring for why Python stopped being the executor.
+    """
+    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)
+
+    plan = build_plan(pcp_dir, module_name)
+    click.echo(json.dumps(plan, indent=2))

pcp/commands/build_status.py

@@ -0,0 +1,83 @@
+"""pcp build-status — live view of an in-progress `pcp build` run.
+
+Reads `.pcp/build_progress.yaml`, written by build.py's `_write_progress()`
+at each criterion-attempt checkpoint (coding / evaluating gates / done /
+failed). Real gap this closes (2026-07-24, Project O incident):
+`pcp build` gives no way to tell what it's currently doing short of reading
+raw agent output -- backgrounded (`nohup pcp build ... &`) it's fully
+opaque, which is what triggered "i want to see whats happening" and a build
+getting killed over what looked like a stall.
+"""
+
+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, NoPCPDir
+
+console = Console()
+
+STALE_AFTER_SEC = 600  # a step with no update in 10 min is worth flagging
+
+
+def load_progress(pcp_dir: Path) -> dict | None:
+    path = pcp_dir / "build_progress.yaml"
+    if not path.exists():
+        return None
+    try:
+        return yaml.safe_load(path.read_text()) or None
+    except yaml.YAMLError:
+        return None
+
+
+def format_status(data: dict | None, now: datetime | None = None) -> str:
+    """Pure formatting -- testable without a clock or filesystem."""
+    if not data:
+        return "No build in progress (no .pcp/build_progress.yaml yet)."
+
+    now = now or datetime.now(timezone.utc)
+    line = (
+        f"{data.get('module', '?')}/{data.get('criterion_id', '?')} "
+        f"attempt {data.get('attempt', '?')} — {data.get('step', '?')}"
+    )
+    updated_at = data.get("updated_at")
+    if updated_at:
+        try:
+            ts = datetime.strptime(updated_at, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+            age_sec = (now - ts).total_seconds()
+            line += f"  (updated {int(age_sec)}s ago)"
+            if age_sec > STALE_AFTER_SEC and data.get("step") not in ("done", "failed"):
+                line += "  ⚠ no update in a while — may be stuck"
+        except ValueError:
+            pass
+    return line
+
+
+@click.command(name="build-status")
+@click.option("--path", "project_path", type=click.Path(), default=None,
+              help="Project root (default: cwd, walks up to find .pcp/).")
+@click.option("--watch", is_flag=True, help="Poll and redraw every --interval seconds until Ctrl-C.")
+@click.option("--interval", type=int, default=5, help="Poll interval in seconds for --watch (default 5).")
+def build_status(project_path: str | None, watch: bool, interval: int):
+    """Show what an in-progress `pcp build` run is currently doing."""
+    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 not watch:
+        console.print(format_status(load_progress(pcp_dir)))
+        sys.exit(0)
+
+    try:
+        while True:
+            console.print(format_status(load_progress(pcp_dir)))
+            time.sleep(interval)
+    except KeyboardInterrupt:
+        sys.exit(0)

pcp/commands/capture.py

@@ -0,0 +1,72 @@
+"""pcp capture — classify a session transcript into business-logic drift
+(-> .pcp/brd.md) and technical input (-> .pcp/decision_log.jsonl).
+
+Advisory, never blocks. Designed to be wired to a Claude Code SessionEnd hook
+(reads the hook's JSON payload from stdin) for human/PM/UAT sessions; `pcp
+build` calls the same underlying pcp.capture.run_capture() directly for its
+own per-criterion agent sessions.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from pcp.pcp_dir import find_pcp_dir, NoPCPDir
+from pcp.capture import run_capture
+
+console = Console()
+
+
+@click.command()
+@click.option("--path", "project_path", type=click.Path(), default=None,
+              help="Project root (default: cwd, walks up to find .pcp/).")
+@click.option("--transcript-file", type=click.Path(exists=True), default=None,
+              help="Transcript JSONL to classify (manual/testing use). "
+                   "Default: read a Claude Code SessionEnd hook payload from stdin.")
+def capture(project_path: str | None, transcript_file: str | None):
+    """Classify a session transcript into business/technical drift. Advisory, never blocks."""
+    try:
+        pcp_dir = find_pcp_dir(Path(project_path) if project_path else None)
+    except NoPCPDir:
+        # Silent — this may run via a hook in any project, not just PCP-managed ones.
+        sys.exit(0)
+
+    transcript_path = None
+    session_id = None
+
+    if transcript_file:
+        transcript_path = Path(transcript_file)
+        # Claude Code transcripts are always named <session-id>.jsonl (same
+        # convention pcp.capture.find_transcript_for_session relies on) — derive
+        # it from the filename so manual/testing runs still get real traceability
+        # instead of session_id=None / source="session:unknown".
+        session_id = transcript_path.stem
+    else:
+        raw = sys.stdin.read() if not sys.stdin.isatty() else ""
+        if raw.strip():
+            try:
+                payload = json.loads(raw)
+                session_id = payload.get("session_id")
+                tp = payload.get("transcript_path")
+                if tp:
+                    transcript_path = Path(tp)
+            except json.JSONDecodeError:
+                pass
+
+    if not transcript_path or not transcript_path.exists():
+        console.print("[dim]pcp capture: no transcript available, skipping.[/dim]")
+        sys.exit(0)
+
+    result = run_capture(pcp_dir, transcript_path, source=f"session:{session_id or 'unknown'}", session_id=session_id)
+
+    if result.get("skipped"):
+        console.print(f"[dim]pcp capture: {result['skipped']}[/dim]")
+    else:
+        console.print(
+            f"[green]pcp capture:[/green] {result['business_count']} business item(s) -> .pcp/brd.md, "
+            f"{result['technical_count']} technical item(s) -> .pcp/decision_log.jsonl"
+        )
+    sys.exit(0)