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

pcp/commands/amend.py

@@ -0,0 +1,283 @@
+"""pcp amend — the human-authorized write path for every protected `.pcp/`
+file that previously had none.
+
+Before this, of the 10 paths in ci_rules.yaml's `protected_path` scope only 4
+had a propose/approve/write command: objective.md + target_state.md via
+`pcp correct-objective`, and modules/*/spec.yaml + acceptance.yaml via
+`pcp kickoff`/`pcp pm`. The other six -- architecture.md, decomposition.md,
+dependency_map.md, ci_rules.yaml, controls.yaml, SDLC_phase.yaml -- were
+written once at kickoff (or, for dependency_map.md, only by `pcp import`) and
+had no path afterwards. Combined with doctrine wording that told agents never
+to edit a protected file, the practical outcome was that a detailed feature
+discussion ending in "now update the specs" updated nothing at all.
+
+`amend` closes that. Same mechanic as `correct-objective` (see spec_write.py):
+LLM proposes from stated intent, human reviews a real unified diff, approves,
+then it's written. The three governance files additionally get schema
+validation and a deterministic weakening check before the human is even asked.
+"""
+
+import sys
+from pathlib import Path
+
+import click
+import yaml
+from rich.console import Console
+
+from pcp import spec_write
+from pcp.llm import client as llm
+from pcp.pcp_dir import find_pcp_dir, NoPCPDir
+from pcp.spec_write import SpecTarget
+
+console = Console()
+
+# Files whose amendment changes what modules exist / what they cover, and so
+# must be re-checked against the objective immediately afterwards.
+_REVALIDATES = {"decomposition", "dependency_map"}
+
+
+def _targets(pcp_dir: Path) -> dict[str, SpecTarget]:
+    return {
+        "architecture": SpecTarget(
+            name="architecture.md",
+            path=pcp_dir / "architecture.md",
+            key="content",
+            description="program-level tech decisions and constraints",
+        ),
+        "decomposition": SpecTarget(
+            name="strategy/decomposition.md",
+            path=pcp_dir / "strategy" / "decomposition.md",
+            key="content",
+            description="how the objective breaks into modules, and why",
+        ),
+        "dependency_map": SpecTarget(
+            name="strategy/dependency_map.md",
+            path=pcp_dir / "strategy" / "dependency_map.md",
+            key="content",
+            description="module build order and inter-module contracts",
+        ),
+        "ci_rules": SpecTarget(
+            name="ci_rules.yaml",
+            path=pcp_dir / "ci_rules.yaml",
+            key="content",
+            schema="ci_rules",
+            guarded=True,
+            description="the program's enforced laws (Layer 1 gates)",
+        ),
+        "controls": SpecTarget(
+            name="controls.yaml",
+            path=pcp_dir / "controls.yaml",
+            key="content",
+            schema="controls",
+            guarded=True,
+            description="the control catalog, cross-referenced to SSDF practices",
+        ),
+        "sdlc_phase": SpecTarget(
+            name="SDLC_phase.yaml",
+            path=pcp_dir / "SDLC_phase.yaml",
+            key="content",
+            schema="sdlc_phase",
+            guarded=True,
+            description="current SDLC phase and its machine-enforced exit criteria",
+        ),
+    }
+
+# Accepted aliases, so `pcp amend architecture.md` and `pcp amend
+# strategy/decomposition.md` work as well as the short keys.
+_ALIASES = {
+    "architecture.md": "architecture",
+    "decomposition.md": "decomposition",
+    "strategy/decomposition.md": "decomposition",
+    "dependency-map": "dependency_map",
+    "dependency_map.md": "dependency_map",
+    "strategy/dependency_map.md": "dependency_map",
+    "ci-rules": "ci_rules",
+    "ci_rules.yaml": "ci_rules",
+    "controls.yaml": "controls",
+    "sdlc": "sdlc_phase",
+    "sdlc-phase": "sdlc_phase",
+    "sdlc_phase.yaml": "sdlc_phase",
+    "SDLC_phase.yaml": "sdlc_phase",
+}
+
+
+def resolve_target_key(raw: str) -> str | None:
+    """Map a user-typed file argument onto a registry key. Deterministic
+    lookup, never fuzzy — an LLM guessing which protected file the human meant
+    is exactly the drift this command exists to prevent."""
+    if raw in _ALIASES:
+        return _ALIASES[raw]
+    # Order matters: strip "./" before ".pcp/", and never lstrip(chars) here --
+    # lstrip("./") eats the leading dot of ".pcp/" itself.
+    normalised = raw.strip().removeprefix("./").removeprefix(".pcp/").removeprefix("/")
+    if normalised in _ALIASES:
+        return _ALIASES[normalised]
+    key = normalised.replace("-", "_")
+    return key if key in {
+        "architecture", "decomposition", "dependency_map",
+        "ci_rules", "controls", "sdlc_phase",
+    } else None
+
+
+_MARKDOWN_RULES = """\
+- Keep everything NOT affected by the change exactly as-is -- do not rephrase, \
+reorder, or "improve" unrelated sections.
+- Change only what the stated change actually requires.
+- Do not invent scope beyond what the change states.
+- Preserve the file's existing structure and heading style."""
+
+_YAML_RULES = """\
+- Keep everything NOT affected by the change exactly as-is, including comments, \
+key order, and formatting.
+- Change only what the stated change actually requires.
+- NEVER remove an existing rule/control/exit-criterion, and never downgrade a \
+hard_block severity, unless the stated change explicitly and unambiguously asks \
+for that removal or downgrade.
+- Preserve every existing id verbatim -- ids are written into telemetry.jsonl by \
+gate call sites and renaming one silently breaks the audit trail."""
+
+
+def build_system_prompt(target: SpecTarget) -> str:
+    is_yaml = target.name.endswith(".yaml")
+    rules = _YAML_RULES if is_yaml else _MARKDOWN_RULES
+    return (
+        f"You are the program's spec author. A human has decided, during "
+        f"conversation, on a change that must now be reflected in "
+        f"`.pcp/{target.name}` ({target.description}). You are given the "
+        f"current file in full, plus read-only context.\n\n"
+        f"Rewrite the file to incorporate the change faithfully:\n{rules}\n\n"
+        f"You must output ONLY valid JSON — no prose, no markdown, no code "
+        f"fences.\n\nOutput schema:\n{spec_write.build_output_schema([target])}\n"
+    )
+
+
+def build_user_prompt(pcp_dir: Path, target: SpecTarget, change: str) -> str:
+    sections = [f"## Requested change\n{change}"]
+
+    current = target.path.read_text() if target.path.exists() else "(file does not exist yet)"
+    sections.append(f"## Current {target.name}\n{current}")
+
+    # Read-only context — never rewritten by this command, only used so the
+    # proposal stays consistent with what the program already says.
+    objective = pcp_dir / "objective.md"
+    if objective.exists():
+        sections.append(f"## Read-only context: objective.md\n{objective.read_text()}")
+
+    decomposition = pcp_dir / "strategy" / "decomposition.md"
+    if target.name != "strategy/decomposition.md" and decomposition.exists():
+        sections.append(f"## Read-only context: decomposition.md\n{decomposition.read_text()}")
+
+    modules_dir = pcp_dir / "strategy" / "modules"
+    if modules_dir.exists():
+        summaries = []
+        for spec_path in sorted(modules_dir.glob("*/spec.yaml")):
+            try:
+                spec = yaml.safe_load(spec_path.read_text()) or {}
+            except yaml.YAMLError:
+                continue
+            name = spec.get("module") or spec_path.parent.name
+            purpose = str(spec.get("purpose", "")).strip().splitlines()[:1]
+            depends = spec.get("depends_on") or spec.get("dependencies") or []
+            summaries.append(
+                f"- {name}: {purpose[0] if purpose else ''} (depends_on: {depends or 'none'})"
+            )
+        if summaries:
+            sections.append("## Read-only context: existing modules\n" + "\n".join(summaries))
+
+    return "\n\n".join(sections)
+
+
+def _revalidate(pcp_dir: Path) -> None:
+    """Re-run validate-strategy after a change to what modules exist/cover —
+    same posture as correct-objective's. Advisory: a failure here never undoes
+    the write the human already approved."""
+    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.print("\n[bold]Running validate-strategy against the amended strategy...[/bold]")
+    obj_path = pcp_dir / "objective.md"
+    objective = obj_path.read_text() if obj_path.exists() else ""
+    dec_path = pcp_dir / "strategy" / "decomposition.md"
+    decomposition = dec_path.read_text() if dec_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(objective, decomposition, all_specs)
+        val_result = llm.call_json(
+            VAL_SYSTEM_PROMPT, val_prompt, model=llm.JUDGE_MODEL,
+            pcp_dir=pcp_dir, command="amend-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]")
+
+
+@click.command("amend")
+@click.argument("target_file")
+@click.argument("change")
+@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).")
+@click.option("--allow-weakening", "allow_weakening", is_flag=True,
+              help="Permit a governance-file rewrite that removes a rule/control/exit-criterion or downgrades a hard_block. Recorded in decision_log.jsonl.")
+def amend(target_file: str, change: str, project_path: str | None, yes: bool, allow_weakening: bool):
+    """Propose + human-approve a rewrite of a human-authorized .pcp/ file.
+
+    TARGET_FILE is one of: architecture, decomposition, dependency_map,
+    ci_rules, controls, sdlc_phase (file names like `architecture.md` also work).
+
+    For objective.md/target_state.md use `pcp correct-objective`; for module
+    spec.yaml/acceptance.yaml use `pcp pm`.
+    """
+    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)
+
+    key = resolve_target_key(target_file)
+    if key is None:
+        if target_file.strip().removeprefix("./").removeprefix(".pcp/") in (
+            "objective.md", "target_state.md", "objective", "target_state"
+        ):
+            console.print("[red]Error:[/red] use `pcp correct-objective \"<correction>\"` for objective.md/target_state.md.")
+            sys.exit(2)
+        if "spec.yaml" in target_file or "acceptance.yaml" in target_file:
+            console.print("[red]Error:[/red] use `pcp pm \"<intent>\"` for module spec.yaml/acceptance.yaml.")
+            sys.exit(2)
+        console.print(
+            f"[red]Error:[/red] {target_file} is not an amendable file. Choose one of: "
+            "architecture, decomposition, dependency_map, ci_rules, controls, sdlc_phase."
+        )
+        sys.exit(2)
+
+    target = _targets(pcp_dir)[key]
+    if not change.strip():
+        console.print("[red]Error:[/red] pass the change to make as the second argument.")
+        sys.exit(2)
+
+    outcome = spec_write.propose_and_write(
+        pcp_dir,
+        [target],
+        build_system_prompt(target),
+        build_user_prompt(pcp_dir, target, change),
+        command="amend",
+        intent=change,
+        yes=yes,
+        allow_weakening=allow_weakening,
+        no_change_hint="If this is unexpected, restate the change more concretely.",
+    )
+    if not outcome.written:
+        sys.exit(0)
+
+    if key in _REVALIDATES:
+        _revalidate(pcp_dir)
+    elif target.guarded:
+        console.print("\n[dim]Gate definitions changed — run `pcp check` before your next commit "
+                      "so Layer 1 runs against the amended rules.[/dim]")

pcp/commands/architect_review.py

@@ -0,0 +1,291 @@
+"""pcp architect-review — architecture principle review against persona + KB."""
+
+import json
+import subprocess
+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.llm import client as llm
+
+console = Console()
+
+SYSTEM_PROMPT = """\
+You are a senior software architect reviewing code changes.
+You have a project-specific persona, architecture constraints, and a curated knowledge base.
+Review the provided diff (or module spec) against the persona rules and KB.
+
+Output ONLY valid JSON — no prose, no markdown, no code fences.
+
+Output schema:
+{
+  "findings": [
+    {
+      "severity": "BLOCK | WARN | NOTE",
+      "location": "file:line or module name or 'general'",
+      "principle": "which architecture principle or persona rule was violated",
+      "finding": "what is wrong",
+      "fix": "concrete suggestion to fix it"
+    }
+  ],
+  "summary": "one sentence overall assessment",
+  "blocks": 0,
+  "warns": 0
+}
+
+severity:
+  BLOCK = must fix before merge (violates hard architecture constraint)
+  WARN  = fix before ship (design smell, weak boundary, missing invariant)
+  NOTE  = track, non-blocking (observation for future consideration)
+
+If no findings, return {"findings": [], "summary": "No architecture violations found.", "blocks": 0, "warns": 0}
+"""
+
+
+def _get_diff(base: str) -> str:
+    result = subprocess.run(
+        ["git", "diff", f"{base}...HEAD"],
+        capture_output=True, text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"git diff failed: {result.stderr.strip()}")
+    return result.stdout[:14000]
+
+
+def _get_staged_diff() -> str:
+    result = subprocess.run(
+        ["git", "diff", "--cached"],
+        capture_output=True, text=True,
+    )
+    return result.stdout[:14000]
+
+
+def _load_persona(pcp_dir: Path) -> str:
+    persona_path = pcp_dir / "architect_persona.md"
+    if not persona_path.exists():
+        return ""
+    return persona_path.read_text()
+
+
+def _load_kb(pcp_dir: Path, changed_files: list[str]) -> str:
+    """Load ADRs always. Load domain KB contextually based on changed files."""
+    kb_dir = pcp_dir / "kb"
+    if not kb_dir.exists():
+        return ""
+
+    parts = []
+
+    # ADRs — always load (small, high signal)
+    adr_dir = kb_dir / "adr"
+    if adr_dir.exists():
+        adr_files = sorted(adr_dir.glob("*.md"))
+        if adr_files:
+            parts.append("## Architecture Decision Records\n")
+            for f in adr_files:
+                parts.append(f"### {f.stem}\n{f.read_text()}\n")
+
+    # Domain KB — contextual
+    domain_dir = kb_dir / "domain"
+    if domain_dir.exists():
+        for domain_file in sorted(domain_dir.glob("*.md")):
+            tag = domain_file.stem.lower()
+            # Load if any changed file path contains the tag word
+            if any(tag in cf.lower() for cf in changed_files) or not changed_files:
+                parts.append(f"## Domain KB: {domain_file.stem}\n{domain_file.read_text()}\n")
+
+    return "\n".join(parts)
+
+
+def _changed_files_from_diff(diff: str) -> list[str]:
+    files = []
+    for line in diff.splitlines():
+        if line.startswith("+++ b/"):
+            files.append(line[6:])
+    return files
+
+
+def _load_module_spec(pcp_dir: Path, module_name: str) -> str:
+    mod_dir = pcp_dir / "strategy" / "modules" / module_name
+    parts = []
+    spec = mod_dir / "spec.yaml"
+    acceptance = mod_dir / "acceptance.yaml"
+    if spec.exists():
+        parts.append(f"## Module Spec ({module_name})\n```yaml\n{spec.read_text()}\n```")
+    if acceptance.exists():
+        parts.append(f"## Acceptance Criteria\n```yaml\n{acceptance.read_text()}\n```")
+    return "\n\n".join(parts)
+
+
+def _build_prompt(
+    persona: str,
+    architecture: str,
+    kb: str,
+    diff_or_spec: str,
+    mode: str,
+) -> str:
+    parts = []
+
+    if persona:
+        parts.append(f"## Architect Persona\n\n{persona}")
+
+    if architecture:
+        parts.append(f"## Project Architecture Constraints\n\n{architecture}")
+
+    if kb:
+        parts.append(f"## Knowledge Base\n\n{kb}")
+
+    if mode == "diff":
+        parts.append(f"## Code Diff to Review\n\n```diff\n{diff_or_spec}\n```")
+        parts.append("Review this diff against your persona rules, architecture constraints, and KB.")
+    else:
+        parts.append(f"## Module Spec to Review\n\n{diff_or_spec}")
+        parts.append("Review this module spec for architecture principle violations.")
+
+    return "\n\n".join(parts)
+
+
+def _render_table(result: dict) -> None:
+    findings = result.get("findings", [])
+    blocks = result.get("blocks", 0)
+    warns = result.get("warns", 0)
+
+    summary = result.get("summary", "")
+    color = "green" if blocks == 0 and warns == 0 else ("red" if blocks > 0 else "yellow")
+    console.print(f"\n[bold]Architecture Review[/bold]  [{color}]{blocks} BLOCK  {warns} WARN[/{color}]")
+    console.print(f"[dim]{summary}[/dim]\n")
+
+    if not findings:
+        console.print("  [green]✓[/green]  No architecture violations found.")
+        return
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Sev", width=6)
+    table.add_column("Location", width=28)
+    table.add_column("Principle", width=22)
+    table.add_column("Finding")
+
+    sev_colors = {"BLOCK": "red", "WARN": "yellow", "NOTE": "dim"}
+
+    for f in findings:
+        sev = f.get("severity", "NOTE")
+        color = sev_colors.get(sev, "dim")
+        table.add_row(
+            f"[{color}]{sev}[/{color}]",
+            f.get("location", ""),
+            f.get("principle", ""),
+            f"{f.get('finding', '')}  →  [italic]{f.get('fix', '')}[/italic]",
+        )
+
+    console.print(table)
+    console.print("\n[dim]BLOCK = fix before merge. WARN = fix before ship. NOTE = track.[/dim]")
+
+
+@click.command()
+@click.option("--base", default="main", show_default=True,
+              help="Base branch for diff (ignored if --staged or --module).")
+@click.option("--staged", is_flag=True,
+              help="Review staged changes (pre-commit mode).")
+@click.option("--module", "module_name", default=None,
+              help="Review a specific module spec instead of a diff.")
+@click.option("--json", "output_json", is_flag=True,
+              help="Output raw JSON.")
+@click.option("--path", "project_path", type=click.Path(), default=None,
+              help="Project root override.")
+@click.option("--fail-on-block", is_flag=True,
+              help="Exit 1 if any BLOCK findings. For CI use.")
+def architect_review(
+    base: str,
+    staged: bool,
+    module_name: str | None,
+    output_json: bool,
+    project_path: str | None,
+    fail_on_block: bool,
+):
+    """Architecture principle review against project persona + KB (advisory)."""
+    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)
+
+    persona = _load_persona(pcp_dir)
+    architecture = (pcp_dir / "architecture.md").read_text() if (pcp_dir / "architecture.md").exists() else ""
+
+    if module_name:
+        spec_text = _load_module_spec(pcp_dir, module_name)
+        if not spec_text:
+            console.print(f"[red]Error:[/red] No spec found for module '{module_name}'")
+            sys.exit(2)
+        kb = _load_kb(pcp_dir, [module_name])
+        mode = "module"
+        target = spec_text
+        label = f"module:{module_name}"
+    else:
+        if staged:
+            diff = _get_staged_diff()
+            label = "staged changes"
+        else:
+            diff = _get_diff(base)
+            label = f"diff vs {base}"
+
+        if not diff.strip():
+            console.print(f"[dim]No changes to review ({label}).[/dim]")
+            sys.exit(0)
+
+        changed_files = _changed_files_from_diff(diff)
+        kb = _load_kb(pcp_dir, changed_files)
+        mode = "diff"
+        target = diff
+
+    if not persona and not architecture:
+        console.print(
+            "[yellow]Warning:[/yellow] No architect_persona.md and no architecture.md found. "
+            "Review will be generic. Run [cyan]pcp init[/cyan] to scaffold persona."
+        )
+
+    if not output_json:
+        console.print(f"[dim]Reviewing {label}...[/dim]")
+
+    try:
+        result = llm.call_json(
+            SYSTEM_PROMPT,
+            _build_prompt(persona, architecture, kb, target, mode),
+            model=llm.JUDGE_MODEL, pcp_dir=pcp_dir, command="architect-review",
+        )
+    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)
+
+    # Same gap class as `pcp verify`: this command is called directly by a
+    # harness-driven agent (pcp build-plan + the Workflow tool's agent()), not
+    # only through build.py's own _run_architect_review wrapper -- which was
+    # the only place this gate's telemetry got recorded before. Not a removed
+    # hook, an omission: it was only ever wired for the older path.
+    from pcp import telemetry
+    telemetry.record(
+        pcp_dir, cycle="qa", cycle_number=None, check="architect-review", control_id=None,
+        module=module_name, submodule=None, criterion_id=None,
+        files=changed_files if mode == "diff" else [],
+        result="block" if result.get("blocks", 0) > 0 else "pass",
+        errors=[f.get("finding", "") for f in result.get("findings", []) if f.get("severity") == "BLOCK"],
+        error_count=result.get("blocks", 0),
+    )
+
+    if output_json:
+        click.echo(json.dumps(result, indent=2))
+        if fail_on_block and result.get("blocks", 0) > 0:
+            sys.exit(1)
+        sys.exit(0)
+
+    _render_table(result)
+
+    if fail_on_block and result.get("blocks", 0) > 0:
+        sys.exit(1)
+    sys.exit(0)