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

pcp/orphaned_work.py

@@ -0,0 +1,262 @@
+"""Criteria whose work landed in the repo but whose status still says `pending`.
+
+Three independent occurrences on Project O inside a week, via two
+different code paths:
+
+- **The wave-gate reopen path.** `core-data-model` A022/A030/A033/A038 — $30.04
+  spent, all four branches merged into `main`, all four set back to `pending`
+  because a wave gate blocked on findings about a module outside the wave. Fixed
+  2026-07-30 (`_finding_blames_outside_wave`).
+- **The run-stopped path, still unfixed.** `query-eval-harness`, 2026-07-30 —
+  $31.65 spent, A001 and A008 merged into `main` with source and tests present
+  (`32be3fa`, `bbb134c`), MOD_A002 committed (`4276c70`), and **all 18 criteria
+  reading `pending`**. No wave-block record exists; the run simply stopped after
+  its last commit and nothing wrote status back.
+
+Whatever the cause, the consequence is the same and it is the worst kind PCP can
+have: the project's own record of what is built becomes false in the direction
+that makes people rebuild finished work. `pcp scan` regenerates `current_state.md`
+from acceptance status, so a wrong status propagates into every downstream view —
+the dashboard, `diff.md`, `validate-strategy`'s coverage, the next build's pending
+list.
+
+This module does not fix status. It **reports the contradiction**, deterministically
+(rung 1, no LLM), because `acceptance.yaml` is human-approved and PCP must not
+silently mark work complete on its own — that would trade a false "not built" for
+a false "built", which is strictly worse.
+
+The signal is a landed COMMIT written by PCP's own conventions -- `Merge
+feat/<module>-<criterion_id>` from the merge path, or `<module>/<criterion_id>:`
+from the auto-commit path. Branch-merged state is deliberately NOT used: worktree
+reuse resets branches to the current base, so a branch that never carried a commit
+still reports as merged. See `_landed_commit_subjects`. No heuristics about file
+contents, no guessing.
+"""
+
+import subprocess
+from pathlib import Path
+
+import yaml as _yaml
+
+from pcp.schema.validator import load_yaml
+
+
+def dump_yaml(data: dict) -> str:
+    return _yaml.dump(data, default_flow_style=False, sort_keys=False)
+
+
+def _landed_commit_subjects(project_root: Path) -> list[str]:
+    """Commit subjects reachable from HEAD. Empty on any git failure.
+
+    `git branch --merged` is NOT a usable signal here and using it was the first
+    version of this module. `pcp build` reuses worktrees and resets their branch
+    to the current base (`_sync_worktree_to_base`), so a branch that never carried
+    a single commit still reports as "merged" — it is an ancestor of HEAD by
+    construction. Checked against Project O, that produced 18 findings of
+    which most were false: `feat/query-eval-harness-MOD_A001` and
+    `feat/core-data-model-A041` have no merge commit and never advanced.
+
+    The trustworthy signal is PCP's own commit conventions, which only exist when
+    work actually landed:
+      - `_merge_module_branch` commits `Merge feat/<module>-<criterion_id>`
+      - `_auto_commit_criterion` commits `<module>/<criterion_id>: <description>`
+    """
+    try:
+        proc = subprocess.run(
+            ["git", "log", "--format=%s", "HEAD"],
+            cwd=project_root, capture_output=True, text=True, timeout=60,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return []
+    if proc.returncode != 0:
+        return []
+    return proc.stdout.splitlines()
+
+
+def find_orphaned_work(pcp_dir: Path, project_root: Path | None = None) -> list[dict]:
+    """Pending criteria that have a landed commit written for them.
+
+    Deliberately conservative: requires a commit subject matching PCP's own
+    conventions exactly. A criterion whose work never produced such a commit is
+    treated as genuinely unfinished and is not reported — the first version used
+    branch-merged state instead and was wrong on 6 of 18 findings.
+    """
+    project_root = project_root or Path(pcp_dir).parent
+    subjects = _landed_commit_subjects(project_root)
+    if not subjects:
+        return []
+
+    found = []
+    modules_dir = Path(pcp_dir) / "strategy" / "modules"
+    if not modules_dir.exists():
+        return []
+    for acc_path in sorted(modules_dir.glob("*/acceptance.yaml")):
+        module = acc_path.parent.name
+        try:
+            data = load_yaml(acc_path) or {}
+        except Exception:
+            continue
+        for c in data.get("criteria", []) or []:
+            if not isinstance(c, dict):
+                continue
+            status = c.get("status", "pending")
+            if status == "complete":
+                continue
+            cid = c.get("id")
+            branch = f"feat/{module}-{cid}"
+            merge_subject = f"Merge {branch}"
+            work_prefix = f"{module}/{cid}:"
+            evidence = next(
+                (s for s in subjects
+                 if s.strip() == merge_subject or s.startswith(work_prefix)),
+                None,
+            )
+            if evidence:
+                found.append({
+                    "module": module,
+                    "criterion_id": cid,
+                    "branch": branch,
+                    "status": status,
+                    "evidence": evidence[:120],
+                    "description": (c.get("description") or "")[:120],
+                })
+    return found
+
+
+def _unverified_now(modules_dir: Path) -> list[dict]:
+    found = []
+    for acc_path in sorted(modules_dir.glob("*/acceptance.yaml")):
+        module = acc_path.parent.name
+        try:
+            data = load_yaml(acc_path) or {}
+        except Exception:
+            continue
+        for c in data.get("criteria", []) or []:
+            if not isinstance(c, dict):
+                continue
+            if c.get("status") == "complete" and not c.get("verified_by"):
+                found.append({
+                    "module": module,
+                    "criterion_id": c.get("id"),
+                    "description": (c.get("description") or "")[:120],
+                })
+    return found
+
+
+def _baseline_path(pcp_dir: Path) -> Path:
+    return Path(pcp_dir) / "unverified_complete_baseline.yaml"
+
+
+def find_unverified_complete(pcp_dir: Path) -> list[dict]:
+    """Criteria marked `complete` with no `verified_by` -- the mirror image of
+    `find_orphaned_work` -- EXCLUDING a one-time grandfathered baseline.
+
+    `verified_by` is stamped ONLY by `_mark_criterion_complete` inside `pcp
+    build`'s real gated loop (or now `pcp verify`). Its absence on a `complete`
+    criterion means the status was hand-edited into acceptance.yaml directly --
+    no gate ever ran, no evidence exists, and PCP is reporting work as done that
+    it has no basis for.
+
+    First found live on Project O 2026-07-30: 12 criteria hand-flipped
+    after the orphaned-work fix landed, because no sanctioned "mark done" path
+    existed yet -- fixed by `pcp verify` in this same change.
+
+    **The baseline exists because the naive version was shipped and run against
+    the real project before the tests caught the problem it caused.** `verified_by`
+    is 6 days old (added 2026-07-24); Project O has 432 criteria going back
+    to early July. Un-baselined, this returns **282 of 333 complete criteria** --
+    85% of all completed work, flagged as suspect for the sole reason that it
+    predates a field that did not exist when it was built. That is not a signal,
+    it is the field's own introduction date read back as an accusation. It is
+    also exactly the shape already named once this session: a check with no
+    sanctioned way to comply produces noise users learn to ignore (CTRL-018's 110
+    phantom blocks, 42.5% of that project's recorded blocks).
+
+    The baseline is a one-time snapshot, written to
+    `.pcp/unverified_complete_baseline.yaml` on the first call ever made in a
+    project (empty findings that call, honestly -- there is no "new" yet to
+    report). Every criterion in it is accepted debt from before this check
+    existed, and stays grandfathered PERMANENTLY by (module, criterion_id)
+    identity -- not by status. A baselined criterion never reappears just from
+    cycling pending -> complete again, deliberately: acceptance.yaml is already
+    gated behind `pcp pm`/`pcp verify`/human approval, so resurrecting it on a
+    status bounce would add a new failure mode (an innocent status edit making
+    old debt look like a new violation) without closing any real hole. The way
+    out of the baseline is `pcp verify`, which stamps `verified_by` and removes
+    the criterion from the unverified set entirely -- not silence, an actual fix.
+    Anything unverified-complete that was never in the baseline is new since
+    this check started watching, and is reported every time.
+
+    This is the more dangerous direction of the two orphaned-work checks. A false
+    `pending` costs a wasted rebuild. A false `complete` means the work is never
+    checked again -- silently absent from every future gate, audit, and coverage
+    figure. Advisory only, never blocking, for the same reason CTRL-018 is warn
+    by default: refusing to build over inherited debt would be the wrong failure
+    mode."""
+    modules_dir = Path(pcp_dir) / "strategy" / "modules"
+    if not modules_dir.exists():
+        return []
+    current = _unverified_now(modules_dir)
+
+    baseline_path = _baseline_path(pcp_dir)
+    if not baseline_path.exists():
+        keys = sorted(f"{f['module']}/{f['criterion_id']}" for f in current)
+        try:
+            baseline_path.parent.mkdir(parents=True, exist_ok=True)
+            baseline_path.write_text(dump_yaml({
+                "note": ("One-time grandfather snapshot, written automatically by the first "
+                         "`pcp scan`/`pcp build` after this check shipped. Everything listed here "
+                         "predates verified_by tracking and is accepted debt, not a new problem -- "
+                         "see find_unverified_complete's docstring. Never hand-edit; a criterion "
+                         "drops out of this list on its own once it goes through `pcp verify` or "
+                         "`pcp build`."),
+                "criteria": keys,
+            }))
+        except OSError:
+            pass  # best-effort -- an unwritable .pcp/ must not break scan/build
+        return []
+
+    try:
+        baseline = set((load_yaml(baseline_path) or {}).get("criteria") or [])
+    except Exception:
+        baseline = set()
+    return [f for f in current if f"{f['module']}/{f['criterion_id']}" not in baseline]
+
+
+def format_unverified_findings(found: list[dict]) -> list[str]:
+    """Human-readable lines for find_unverified_complete. Empty when nothing to say."""
+    if not found:
+        return []
+    lines = [
+        f"{len(found)} criterion(s) marked 'complete' with no verified_by — no gate ever "
+        f"confirmed this, the status was set by hand:"
+    ]
+    for f in found[:12]:
+        lines.append(f"   {f['module']}/{f['criterion_id']}  <- fix: pcp verify {f['module']} {f['criterion_id']}")
+    if len(found) > 12:
+        lines.append(f"   ... and {len(found) - 12} more")
+    lines.append(
+        "If genuinely done, record it properly with the command above. Leaving it as-is means "
+        "no gate, audit, or coverage figure will ever check this again."
+    )
+    return lines
+
+
+def format_findings(found: list[dict]) -> list[str]:
+    """Human-readable lines. Empty list when there is nothing to say."""
+    if not found:
+        return []
+    lines = [
+        f"{len(found)} criterion(s) marked '{found[0]['status']}' or pending whose work is "
+        f"already merged into this branch — the status is stale, not the code:"
+    ]
+    for f in found[:12]:
+        lines.append(f"   {f['module']}/{f['criterion_id']}  <- commit: {f['evidence']}")
+    if len(found) > 12:
+        lines.append(f"   ... and {len(found) - 12} more")
+    lines.append(
+        "Verify, then mark them complete via `pcp pm` — acceptance.yaml is human-approved, "
+        "so PCP will not flip status on its own. Leaving it stale makes the next build "
+        "redo finished work."
+    )
+    return lines

pcp/pcp_dir.py

@@ -0,0 +1,35 @@
+"""Locate and navigate the .pcp/ directory for a project."""
+
+from pathlib import Path
+
+
+class NoPCPDir(Exception):
+    pass
+
+
+def find_pcp_dir(start: Path | None = None) -> Path:
+    """Walk up from start (default cwd) to find .pcp/. Raises NoPCPDir if not found."""
+    current = (start or Path.cwd()).resolve()
+    for parent in [current, *current.parents]:
+        candidate = parent / ".pcp"
+        if candidate.is_dir():
+            return candidate
+    raise NoPCPDir(
+        "No .pcp/ directory found. Run `pcp init` to initialise this project."
+    )
+
+
+def get_modules_dir(pcp_dir: Path) -> Path:
+    return pcp_dir / "strategy" / "modules"
+
+
+def get_objective(pcp_dir: Path) -> Path:
+    return pcp_dir / "objective.md"
+
+
+def get_decomposition(pcp_dir: Path) -> Path:
+    return pcp_dir / "strategy" / "decomposition.md"
+
+
+def get_ontology_state(pcp_dir: Path) -> Path:
+    return pcp_dir / "ontology_state.yaml"

pcp/pcp_status.py

@@ -0,0 +1,313 @@
+"""Shared pcp.md governance snapshot writer.
+
+Called by `pcp scan` (auto) and `pcp status` (on-demand).
+pcp.md lives at project root — never inside .pcp/.
+"""
+
+from pathlib import Path
+import re
+import yaml
+
+
+def _read_optional(path: Path, max_chars: int = 600) -> str:
+    if not path.exists():
+        return ""
+    text = path.read_text().strip()
+    return text[:max_chars] + ("\n…" if len(text) > max_chars else "")
+
+
+def _evaluate_exit_criterion(c: dict, project_root: Path) -> bool:
+    check = c.get("check", "manual")
+    if check == "file_exists":
+        return (project_root / c.get("target", "")).exists()
+    if check == "ast_pattern":
+        target = project_root / c.get("target", "")
+        pattern = c.get("pattern", "")
+        if not target.exists() or not pattern:
+            return c.get("status") == "complete"
+        import re
+        return bool(re.search(pattern, target.read_text(errors="replace"), re.MULTILINE))
+    return c.get("status") == "complete"
+
+
+def _extract_phase(pcp_dir: Path) -> tuple[str, list[dict]]:
+    sdlc_path = pcp_dir / "SDLC_phase.yaml"
+    if not sdlc_path.exists():
+        return "unknown", []
+    data = yaml.safe_load(sdlc_path.read_text()) or {}
+    current = data.get("current_phase", "unknown")
+    phases = data.get("phases", [])
+    current_phase_data = next((p for p in phases if p["name"] == current), {})
+    project_root = pcp_dir.parent
+    criteria = current_phase_data.get("exit_criteria", [])
+    # Evaluate deterministic checks live
+    evaluated = []
+    for c in criteria:
+        done = _evaluate_exit_criterion(c, project_root)
+        evaluated.append({**c, "_done": done})
+    return current, evaluated
+
+
+def _extract_bypass_count(pcp_dir: Path) -> int:
+    log_path = pcp_dir / "bypass_log.yaml"
+    if not log_path.exists():
+        return 0
+    data = yaml.safe_load(log_path.read_text()) or {}
+    return len(data.get("bypasses", []))
+
+
+def _extract_audit_summary(pcp_dir: Path) -> str | None:
+    audit_path = pcp_dir / "audit.md"
+    if not audit_path.exists():
+        return None
+    generated, findings = "", None
+    for line in audit_path.read_text().splitlines():
+        if line.startswith("Generated:"):
+            generated = line.split(":", 1)[1].strip()
+        elif line.startswith("Findings:"):
+            findings = line.split(":", 1)[1].strip()
+    if findings is None:
+        return f"_Last run {generated} — no audit tool detected._" if generated else None
+    return f"{findings} dead-code finding(s) — last run {generated}"
+
+
+def _extract_token_summary(pcp_dir: Path) -> str | None:
+    ledger_path = pcp_dir / "token_ledger.yaml"
+    if not ledger_path.exists():
+        return None
+    data = yaml.safe_load(ledger_path.read_text()) or {}
+    calls = data.get("calls", [])
+    if not calls:
+        return None
+    total_input = sum(c.get("input_tokens", 0) + c.get("cache_creation_tokens", 0) for c in calls)
+    total_cache_read = sum(c.get("cache_read_tokens", 0) for c in calls)
+    total_output = sum(c.get("output_tokens", 0) for c in calls)
+    total_cost = sum(c.get("cost_usd") or 0 for c in calls)
+    by_model = {}
+    for c in calls:
+        m = c.get("model", "default")
+        by_model[m] = by_model.get(m, 0) + 1
+    model_breakdown = ", ".join(f"{m}:{n}" for m, n in sorted(by_model.items()))
+    return (
+        f"{len(calls)} LLM call(s) — {total_input:,} input / {total_cache_read:,} cache-read / "
+        f"{total_output:,} output tokens — ~${total_cost:.2f} — by model: {model_breakdown}"
+    )
+
+
+def _extract_test_coverage(pcp_dir: Path) -> str | None:
+    cs = pcp_dir / "current_state.md"
+    if not cs.exists():
+        return None
+    text = cs.read_text()
+    m = re.search(r"## Test Coverage\n([\d.]+)% \(([^)]+)\)", text)
+    return f"{m.group(1)}% ({m.group(2)})" if m else None
+
+
+def _extract_telemetry_summary(pcp_dir: Path) -> str | None:
+    from pcp import telemetry
+    records = telemetry.load(pcp_dir)
+    if not records:
+        return None
+    agg = telemetry.aggregate(records)
+    by_module = agg["by_module"]
+    if not by_module:
+        return None
+    total_qa = sum(v["qa_total"] for v in by_module.values())
+    total_blocks = sum(v["qa_blocks"] for v in by_module.values())
+    total_attempts = len(agg["build_records"])
+    total_criteria = len({(m, c) for m, v in by_module.items() for c in v["criteria"]})
+    avg_attempts = total_attempts / total_criteria if total_criteria else 0.0
+    qa_rate = f"{total_blocks}/{total_qa}" if total_qa else "—"
+    worst_module = max(
+        by_module.items(),
+        key=lambda kv: (kv[1]["attempts"] / (len(kv[1]["criteria"]) or 1)),
+        default=None,
+    )
+    worst_note = ""
+    if worst_module and len(by_module) > 1:
+        wname, wv = worst_module
+        wavg = wv["attempts"] / (len(wv["criteria"]) or 1)
+        if wavg > avg_attempts:
+            worst_note = f" — highest retry rate: `{wname}` ({wavg:.1f} attempts/criterion)"
+    return (
+        f"{total_criteria} criteria built, {avg_attempts:.1f} avg attempts/criterion, "
+        f"QA blocks {qa_rate}{worst_note}. Run `pcp telemetry` for the per-module breakdown."
+    )
+
+
+def _extract_brd_summary(pcp_dir: Path) -> str | None:
+    brd_path = pcp_dir / "brd.md"
+    if not brd_path.exists():
+        return None
+    items_path = pcp_dir / "brd_items.yaml"
+    items = (yaml.safe_load(items_path.read_text()) or {}).get("items", []) if items_path.exists() else []
+    active = [i for i in items if i.get("status") == "active"]
+    drift = [i for i in active if i.get("drift_flag")]
+    if not active:
+        return None
+    note = f", {len(drift)} drift flag(s) vs objective.md" if drift else ""
+    return f"{len(active)} active requirement(s){note}. See `brd.md`."
+
+
+def _extract_decision_log_summary(pcp_dir: Path) -> str | None:
+    from pcp import decision_log
+    records = decision_log.load(pcp_dir)
+    if not records:
+        return None
+    agg = decision_log.aggregate(records)
+    by_category = agg["by_category"]
+    breakdown = ", ".join(f"{cat}:{len(items)}" for cat, items in sorted(by_category.items()))
+    return f"{len(records)} technical decision(s) captured — {breakdown}. Run `pcp telemetry` or see `.pcp/decision_log.jsonl`."
+
+
+def _extract_pending_gaps(pcp_dir: Path) -> list[str]:
+    cs = pcp_dir / "current_state.md"
+    if not cs.exists():
+        return []
+    gaps = []
+    for line in cs.read_text().splitlines():
+        if re.match(r"\s*- \[ \]", line):
+            gaps.append(line.strip()[6:])
+    return gaps
+
+
+def _module_table(modules_results: list[dict]) -> list[str]:
+    lines = [
+        "| Module | Criteria | Complete | Pending |",
+        "|---|---|---|---|",
+    ]
+    for m in modules_results:
+        total = len(m["criteria"])
+        complete = sum(1 for c in m["criteria"] if c["status"] == "complete")
+        pending = total - complete
+        status = "✓" if pending == 0 else f"{pending} pending"
+        lines.append(f"| `{m['module']}` | {total} | {complete} | {status} |")
+    return lines
+
+
+def _phase_exit_table(exit_criteria: list[dict]) -> list[str]:
+    lines = []
+    for c in exit_criteria:
+        done = c.get("_done", c.get("status") == "complete")
+        mark = "x" if done else " "
+        lines.append(f"- [{mark}] **{c['id']}**: {c['description']}")
+    return lines or ["_No exit criteria defined._"]
+
+
+def extract_objective_text(pcp_dir: Path) -> str:
+    """First non-heading body text from objective.md. Real bug, found
+    2026-07-08: a heading immediately followed by its body text on the very
+    next line (no blank line between them -- completely normal markdown,
+    e.g. "## Why This Exists\nBecause...") used to make the WHOLE block get
+    rejected outright (the paragraph, heading+body glued together, "starts
+    with #"), silently discarding real objective text and falling through
+    to "No objective.md found" even though the file existed and had real
+    content. Strips leading heading line(s) off each paragraph block first,
+    and only rejects a block if nothing but headings remain. Factored out
+    of write_pcp_md so dashboard.py can reuse the same extraction instead
+    of duplicating this parsing."""
+    obj_path = pcp_dir / "objective.md"
+    if not obj_path.exists():
+        return ""
+    raw = obj_path.read_text()
+    for block in re.split(r"\n{2,}", raw):
+        lines = block.strip().split("\n")
+        while lines and lines[0].strip().startswith("#"):
+            lines.pop(0)
+        body = "\n".join(lines).strip()
+        if body:
+            return body[:500]
+    return ""
+
+
+def write_pcp_md(
+    pcp_dir: Path,
+    modules_results: list[dict],
+    timestamp: str,
+    total: int,
+    complete: int,
+) -> Path:
+    """Write pcp.md to project root. Returns path."""
+    project_root = pcp_dir.parent
+    project_name = project_root.name
+    score = complete / total if total else 0.0
+    score_pct = f"{score:.0%}"
+
+    phase_name, exit_criteria = _extract_phase(pcp_dir)
+    bypass_count = _extract_bypass_count(pcp_dir)
+    pending_gaps = _extract_pending_gaps(pcp_dir)
+    audit_summary = _extract_audit_summary(pcp_dir)
+    token_summary = _extract_token_summary(pcp_dir)
+    telemetry_summary = _extract_telemetry_summary(pcp_dir)
+    test_coverage = _extract_test_coverage(pcp_dir)
+    brd_summary = _extract_brd_summary(pcp_dir)
+    decision_log_summary = _extract_decision_log_summary(pcp_dir)
+    obj_text = extract_objective_text(pcp_dir)
+
+    lines = [
+        f"# PCP Governance — {project_name}",
+        f"_Updated: {timestamp} | Phase: `{phase_name}` | Coverage: {score_pct} | Bypasses: {bypass_count}_",
+        "",
+        "> Auto-generated by `pcp scan`. Do not edit manually.",
+        "",
+        "## Objective",
+        "",
+        obj_text or "_No objective.md found. Run `pcp init`._",
+        "",
+        f"## SDLC Phase: `{phase_name}`",
+        "",
+        *_phase_exit_table(exit_criteria),
+        "",
+        "## Module Status",
+        "",
+        *_module_table(modules_results),
+        "",
+    ]
+
+    if pending_gaps:
+        lines += [
+            "## Pending Gaps",
+            "",
+            *[f"- [ ] {g}" for g in pending_gaps],
+            "",
+        ]
+    else:
+        lines += [
+            "## Pending Gaps",
+            "",
+            "_All acceptance criteria met._",
+            "",
+        ]
+
+    if test_coverage:
+        lines += ["## Test Coverage", "", test_coverage, ""]
+
+    if audit_summary:
+        lines += ["## Dead Code / Bloat", "", audit_summary, ""]
+
+    if token_summary:
+        lines += ["## Token Spend", "", token_summary, ""]
+
+    if telemetry_summary:
+        lines += ["## Build Efficiency", "", telemetry_summary, ""]
+
+    if brd_summary:
+        lines += ["## Business Requirements (Living)", "", brd_summary, ""]
+
+    if decision_log_summary:
+        lines += ["## Technical Decisions", "", decision_log_summary, ""]
+
+    if bypass_count > 0:
+        log_path = pcp_dir / "bypass_log.yaml"
+        data = yaml.safe_load(log_path.read_text()) or {}
+        bypasses = data.get("bypasses", [])
+        lines += ["## Bypass Log", ""]
+        for b in bypasses[-5:]:  # last 5 only
+            lines.append(f"- `{b.get('timestamp', '')}` — {b.get('reason', '')} (rules: {', '.join(b.get('rules_bypassed', []))})")
+        lines.append("")
+    else:
+        lines += ["## Bypass Log", "", "_No bypasses._", ""]
+
+    out = project_root / "pcp.md"
+    out.write_text("\n".join(lines))
+    return out