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

pcp/commands/context.py

@@ -0,0 +1,151 @@
+"""pcp context — surface .pcp/ context to any LLM.
+
+Not wired to fire automatically at session start on its own -- `--inject`
+writes/updates a marked block in CLAUDE.md, which Claude Code already reads
+every session, but nothing calls this command for you. Wire a SessionStart
+hook yourself (snippet in .pcp/RECOMMENDED_PERMISSIONS.md) if you want the
+block kept fresh automatically; same manual-opt-in posture as the
+PreToolUse spec guard -- PCP doesn't edit .claude/settings.json itself.
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from pcp.pcp_dir import find_pcp_dir, NoPCPDir
+
+console = Console(stderr=True)
+
+CLAUDE_MD_MARKER_START = "<!-- pcp:context:start -->"
+CLAUDE_MD_MARKER_END = "<!-- pcp:context:end -->"
+
+
+def _read_optional(path: Path) -> str:
+    return path.read_text().strip() if path.exists() else ""
+
+
+def _build_context(pcp_dir: Path) -> dict:
+    return {
+        "objective": _read_optional(pcp_dir / "objective.md"),
+        "architecture": _read_optional(pcp_dir / "architecture.md"),
+        "current_state": _read_optional(pcp_dir / "current_state.md"),
+        "diff": _read_optional(pcp_dir / "diff.md"),
+        "target_state": _read_optional(pcp_dir / "target_state.md"),
+    }
+
+
+def _max_generated_chars() -> int:
+    """Per-section budget for the AUTO-GENERATED sections only. Read at call
+    time, not frozen at import, so a test can monkeypatch it."""
+    return int(os.environ.get("PCP_CONTEXT_MAX_GENERATED_CHARS", "20000"))
+
+
+def _generated_section(title: str, body: str, rel_path: str, budget: int) -> list[str]:
+    """current_state.md and diff.md are auto-generated and grow with module
+    count -- on a many-module project they run to six figures of characters
+    each. `--inject` writes this block into CLAUDE.md, which every session then
+    reads in full, so pasting them whole silently makes the single most
+    expensive file in the repo unboundedly large (2026-07-25: ~269k chars of
+    generated state across the two on a real dogfood project).
+
+    Over budget, emit a POINTER instead of the body. That is not a silent
+    truncation -- the size and the path are both stated, and an agent that
+    needs the detail can read the file, which is the same projection rule
+    context_map.yaml already applies to sliced state."""
+    if len(body) <= budget:
+        return [f"## {title}\n", body, ""]
+    return [
+        f"## {title}\n",
+        f"_Omitted from this block: `{rel_path}` is {len(body):,} chars, over the "
+        f"{budget:,}-char budget for auto-generated sections. Read the file directly "
+        f"for the detail. Raise `PCP_CONTEXT_MAX_GENERATED_CHARS` to inline it anyway._",
+        "",
+    ]
+
+
+def _render_markdown(ctx: dict) -> str:
+    parts = ["# PCP Project Context\n"]
+    budget = _max_generated_chars()
+
+    # Intent files go in WHOLE, always -- fragmenting spec collapses
+    # faithfulness (context_map.py's second design law). Only the generated
+    # projections below are budgeted.
+    if ctx["objective"]:
+        parts += ["## Objective\n", ctx["objective"], ""]
+
+    if ctx["architecture"]:
+        parts += ["## Architecture\n", ctx["architecture"], ""]
+
+    if ctx["current_state"]:
+        parts += _generated_section(
+            "Current State", ctx["current_state"], ".pcp/current_state.md", budget)
+    else:
+        parts += ["## Current State\n", "_Not generated yet. Run `pcp scan`._", ""]
+
+    if ctx["diff"]:
+        parts += _generated_section("Pending Gaps", ctx["diff"], ".pcp/diff.md", budget)
+
+    return "\n".join(parts)
+
+
+def _inject_into_claude_md(project_root: Path, markdown: str) -> None:
+    claude_md = project_root / "CLAUDE.md"
+    block = f"{CLAUDE_MD_MARKER_START}\n{markdown}\n{CLAUDE_MD_MARKER_END}"
+
+    if not claude_md.exists():
+        claude_md.write_text(f"{block}\n")
+        console.print(f"[green]created[/green] CLAUDE.md with pcp context block")
+        return
+
+    existing = claude_md.read_text()
+    start = existing.find(CLAUDE_MD_MARKER_START)
+    end = existing.find(CLAUDE_MD_MARKER_END)
+
+    if start != -1 and end != -1:
+        updated = existing[:start] + block + existing[end + len(CLAUDE_MD_MARKER_END):]
+        claude_md.write_text(updated)
+        console.print(f"[green]updated[/green] CLAUDE.md pcp context block")
+    else:
+        with open(claude_md, "a") as f:
+            f.write(f"\n{block}\n")
+        console.print(f"[green]appended[/green] pcp context block to CLAUDE.md")
+
+
+@click.command()
+@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="Output as JSON for IDE tool integrations.")
+@click.option("--inject", is_flag=True,
+              help="Write context into CLAUDE.md instead of stdout.")
+def context(project_path: str | None, output_json: bool, inject: bool):
+    """Output .pcp/ context for LLM consumption at session start.
+
+    Pipe to your IDE or LLM: pcp context | pbcopy
+    Inject into CLAUDE.md: pcp context --inject
+    """
+    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
+    ctx = _build_context(pcp_dir)
+
+    if output_json:
+        click.echo(json.dumps(ctx, indent=2))
+        return
+
+    markdown = _render_markdown(ctx)
+
+    if inject:
+        _inject_into_claude_md(project_root, markdown)
+        return
+
+    # Default: print to stdout (pipe-friendly)
+    click.echo(markdown)

pcp/commands/control_audit_cmd.py

@@ -0,0 +1,54 @@
+"""pcp control-audit -- self-evaluation gap closed 2026-07-21. See
+control_audit.py's module docstring for the full rationale."""
+
+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 import control_audit
+
+console = Console()
+
+
+@click.command(name="control-audit")
+@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="Output raw JSON.")
+@click.option("--sync", "sync", is_flag=True,
+              help="Additive-only: append any control from the currently-installed pcp package's catalog "
+                   "that's missing from this project's controls.yaml. Never rewrites or removes an existing entry.")
+def control_audit_cmd(project_path: str | None, output_json: bool, sync: bool):
+    """Which cataloged controls have never fired -- retire/merge review candidates."""
+    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 sync:
+        added = control_audit.sync_catalog(pcp_dir)
+        if not added:
+            console.print("[green]controls.yaml already current[/green] -- no missing control ids "
+                           "(or no controls.yaml exists yet; run `pcp init` to create one).")
+        else:
+            console.print(f"[green]✓[/green] added {len(added)} missing control(s) to controls.yaml: "
+                           f"{', '.join(sorted(added))}")
+        if output_json:
+            click.echo(json.dumps({"added": added}, indent=2))
+        return
+
+    audit = control_audit.write_control_audit(pcp_dir)
+
+    if output_json:
+        click.echo(json.dumps(audit, indent=2))
+        return
+
+    never_fired = {k: v for k, v in audit.items() if v["signal"] == "never-fired"}
+    console.print(f"[bold]Control Catalog Audit[/bold] — {len(audit)} controls, {len(never_fired)} never-fired")
+    for cid, v in sorted(never_fired.items()):
+        console.print(f"  [yellow]{cid}[/yellow] {v['name']} — {v['total_runs']} runs, 0 findings")
+    console.print("[dim]Full report: .pcp/control_audit.md[/dim]")

pcp/commands/correct_objective.py

@@ -0,0 +1,160 @@
+"""pcp correct-objective — the human-authorized write path for objective.md/
+target_state.md.
+
+Hard Rule #2 ("spec files are human-authorized only") protects against an
+autonomous build-agent silently drifting the spec (`protected_path` hard-blocks
+any write while `PCP_AGENT_SESSION=1`). It was never meant to mean "Ganesh
+hand-types the markdown diff himself" -- `pcp kickoff`/`pcp pm` already write
+module-level spec.yaml/acceptance.yaml this same way: LLM proposes the change
+from stated intent, a human reviews and approves, then it's written. objective.md
+and target_state.md never got the equivalent command, so in practice a business
+correction discussed and agreed in conversation had nowhere to go except a
+human manually opening the file -- and the 2026-07-22 Project O incident
+is exactly what happens when that manual step is skipped and nothing catches
+it: a build cycle runs to completion against a stale objective.
+
+Deliberately separate from `pcp pm`: pm never touches the program-level spec
+files, only module specs -- keeping this a distinct, explicit command means
+running it always shows a real diff of the two most consequential files in
+the project, never gets silently bundled into a routine module-intent call.
+
+The propose/diff/approve/write mechanic itself now lives in `spec_write.py`,
+shared with `pcp amend` — which gives the same treatment to the six other
+protected files that had no write path at all (2026-07-25).
+"""
+
+import sys
+from pathlib import Path
+
+import click
+import yaml
+from rich.console import Console
+
+from pcp.pcp_dir import find_pcp_dir, NoPCPDir
+from pcp.llm import client as llm
+from pcp import objective_conflicts
+from pcp import spec_write
+from pcp.spec_write import SpecTarget
+from pcp.commands.validate_strategy import (
+    _build_user_prompt as build_val_prompt,
+    SYSTEM_PROMPT as VAL_SYSTEM_PROMPT,
+    _render_results as render_val_results,
+)
+
+console = Console()
+
+SYSTEM_PROMPT = """\
+You are the program's spec author. A human has communicated a business \
+correction, during conversation, that must now be reflected in the immutable \
+program objective. You are given the CURRENT objective.md and target_state.md \
+in full.
+
+Rewrite them to incorporate the correction faithfully:
+- Keep everything NOT affected by the correction exactly as-is -- do not \
+rephrase, reorder, or "improve" unrelated sections.
+- Change only what the correction actually requires.
+- Do not invent new scope beyond what the correction states.
+- If the correction only affects one of the two files, still return both \
+(the untouched one unchanged).
+
+You must output ONLY valid JSON — no prose, no markdown, no code fences.
+
+Output schema:
+{
+  "objective_md": "full replacement content of objective.md",
+  "target_state_md": "full replacement content of target_state.md",
+  "summary": "one paragraph: exactly what changed and why, for the audit trail"
+}
+"""
+
+
+def _load_conflict(pcp_dir: Path, item_id: str) -> dict | None:
+    path = pcp_dir / "brd_items.yaml"
+    if not path.exists():
+        return None
+    data = yaml.safe_load(path.read_text()) or {}
+    for item in data.get("items", []):
+        if item.get("id") == item_id:
+            return item
+    return None
+
+
+@click.command("correct-objective")
+@click.argument("correction", required=False, default=None)
+@click.option("--from-conflict", "from_conflict", default=None, metavar="ITEM_ID",
+              help="Pull the correction text from an unresolved brd_items.yaml conflict (see `pcp objective-conflicts`) instead of a positional argument.")
+@click.option("--path", "project_path", type=click.Path(), default=None)
+@click.option("--yes", "yes", is_flag=True, help="Skip the interactive diff-approval prompt (scripted/CI use).")
+def correct_objective(correction: str | None, from_conflict: str | None, project_path: str | None, yes: bool):
+    """Propose + human-approve a rewrite of objective.md/target_state.md from a stated business correction."""
+    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)
+
+    conflict_item = None
+    if from_conflict:
+        conflict_item = _load_conflict(pcp_dir, from_conflict)
+        if not conflict_item:
+            console.print(f"[red]Error:[/red] no brd_items.yaml entry with id {from_conflict}")
+            sys.exit(2)
+        correction = f"{conflict_item.get('description', '')} -- conflict noted: {conflict_item.get('drift_flag', '')}"
+    elif not correction:
+        console.print("[red]Error:[/red] pass a correction as an argument, or --from-conflict ITEM_ID")
+        sys.exit(2)
+
+    obj_path = pcp_dir / "objective.md"
+    ts_path = pcp_dir / "target_state.md"
+
+    user_prompt = "\n\n".join([
+        f"## Correction\n{correction}",
+        f"## Current objective.md\n{obj_path.read_text() if obj_path.exists() else ''}",
+        f"## Current target_state.md\n{ts_path.read_text() if ts_path.exists() else ''}",
+    ])
+
+    outcome = spec_write.propose_and_write(
+        pcp_dir,
+        [
+            SpecTarget(name="objective.md", path=obj_path, key="objective_md"),
+            SpecTarget(name="target_state.md", path=ts_path, key="target_state_md"),
+        ],
+        SYSTEM_PROMPT,
+        user_prompt,
+        command="correct-objective",
+        intent=correction,
+        yes=yes,
+        no_change_hint="If this is unexpected, restate the correction more concretely.",
+    )
+    if not outcome.written:
+        sys.exit(0)
+    new_objective = outcome.result["objective_md"]
+
+    # Auto-clears any objective_conflicts entry whose flagged hash no longer
+    # matches — including conflict_item itself, since the file just changed.
+    still_unresolved = objective_conflicts.reconcile(pcp_dir)
+    if conflict_item and not any(c.get("id") == conflict_item.get("id") for c in still_unresolved):
+        console.print(f"[green]✓[/green] conflict {conflict_item['id']} resolved.")
+
+    # Objective just moved — every module's spec should be re-checked against
+    # it before anyone runs `pcp build`, same as kickoff/pm always do.
+    console.print("\n[bold]Running validate-strategy against the new objective...[/bold]")
+    decomposition_path = pcp_dir / "strategy" / "decomposition.md"
+    decomposition = decomposition_path.read_text() if decomposition_path.exists() else ""
+    all_specs = {}
+    for spec_path in sorted((pcp_dir / "strategy" / "modules").glob("*/spec.yaml")):
+        try:
+            all_specs[spec_path.parent.name] = yaml.safe_load(spec_path.read_text()) or {}
+        except Exception:
+            pass
+    try:
+        val_prompt = build_val_prompt(new_objective, decomposition, all_specs)
+        val_result = llm.call_json(VAL_SYSTEM_PROMPT, val_prompt, model=llm.JUDGE_MODEL, pcp_dir=pcp_dir, command="correct-objective-validate")
+        render_val_results(pcp_dir, val_result, output_json=False)
+    except Exception as e:
+        console.print(f"[yellow]Warning: could not run validate-strategy automatically: {e}[/yellow]")
+
+    console.print(
+        "\n[dim]Existing module specs may now be stale against the new objective (see validate-strategy "
+        "output above) -- run `pcp pm \"...\"` per affected module before `pcp build`.[/dim]"
+    )