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

pcp/commands/init.py

@@ -0,0 +1,1634 @@
+"""pcp init — scaffold .pcp/ directory in a project."""
+
+import re
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+console = Console()
+
+
+def _pascal_case(name: str) -> str:
+    return "".join(part.capitalize() for part in re.split(r"[_-]", name) if part)
+
+OBJECTIVE_TEMPLATE = """\
+# Program Objective
+
+## Why This Exists
+
+[Describe the problem this program solves.]
+
+## What Success Looks Like
+
+1. [Measurable outcome 1]
+2. [Measurable outcome 2]
+
+## Out of Scope
+
+- [What this program does NOT do]
+"""
+
+TARGET_STATE_TEMPLATE = """\
+# Target State
+
+[Describe what "done" looks like from a user/business perspective.
+This is the ideal end state of the entire program.]
+"""
+
+ARCHITECTURE_TEMPLATE = """\
+# Architecture
+
+## Tech Stack
+
+| Layer | Choice | Why |
+|---|---|---|
+| | | |
+
+## Key Constraints
+
+- [Constraint 1]
+
+## Design Decisions
+
+- [Decision and rationale]
+"""
+
+CI_RULES_TEMPLATE = """\
+version: "1.0"
+rules:
+  # ── Modularity rules (generated by pcp init — do not remove) ──────────────
+  # Philosophy: every module is a guest. It can leave without drama.
+  # It can arrive without surgery. Nothing else should know about it
+  # except the application registry.
+
+  - id: MOD_001
+    name: "No direct cross-module implementation imports"
+    check: ast_pattern
+    # matches: ../../other-module/src/  or  ../other-module/src/
+    pattern: "from \\\\.\\\\./(\\\\.\\\\./)?[^/]+/src/"
+    severity: hard_block
+    message: "Modules must communicate through interfaces/, not by importing each other's src/. Move shared types to interfaces/."
+    scope: ["*.py", "*.js", "*.jsx", "*.ts", "*.tsx", "*.go", "*.rb", "*.java", "*.php", "*.cs", "*.rs"]
+
+  - id: MOD_002
+    name: "No hardcoded module names as string literals in orchestrator"
+    check: ast_pattern
+    # catches brittle module-name strings that create implicit coupling
+    pattern: "require\\\\(['\\\"]\\\\.\\\\./"
+    severity: hard_block
+    message: "Use the module registry pattern — app.register(Module) not require('../module')."
+    scope: ["*.js", "*.jsx", "*.ts", "*.tsx"]
+
+  - id: MOD_003
+    name: "Every module must have a public interface file"
+    check: file_exists
+    target: "src/interfaces/I{module}.ts"
+    severity: hard_block
+    message: "Create src/interfaces/I{module}.ts defining what this module exposes. Other modules import only from here."
+
+  - id: MOD_004
+    name: "No shared global mutable state between modules"
+    check: ast_pattern
+    pattern: "global\\\\s+[A-Za-z_]\\\\w*\\\\s*="
+    severity: hard_block
+    message: "Global mutable state creates invisible coupling. Pass state through the registry or event bus."
+
+  - id: MOD_005
+    name: "Every module must have a feature flag"
+    check: file_exists
+    target: "src/modules/{module}/feature_flag.env"
+    severity: hard_block
+    message: "Create feature_flag.env with FEATURE_{MODULE}_ENABLED=false. All modules ship dark by default."
+
+  # ── Spec protection (generated by pcp init — do not remove) ───────────────
+  - id: SPEC_001
+    name: "Human-authorized spec files must not be written by an unattended agent"
+    check: protected_path
+    description: "These files are human-AUTHORIZED, not human-typed. Enforced only inside a pcp-build agent session (PCP_AGENT_SESSION=1), which is the unattended case. A human-present session updating a spec through its gated write path (`pcp correct-objective`, `pcp pm`, `pcp amend` — each shows a real diff and requires approval) is never blocked, and is the correct way to apply a spec change agreed in conversation."
+    severity: hard_block
+    scope:
+      - ".pcp/objective.md"
+      - ".pcp/target_state.md"
+      - ".pcp/architecture.md"
+      - ".pcp/ci_rules.yaml"
+      - ".pcp/controls.yaml"
+      - ".pcp/SDLC_phase.yaml"
+      - ".pcp/strategy/decomposition.md"
+      - ".pcp/strategy/dependency_map.md"
+      - ".pcp/strategy/modules/*/spec.yaml"
+      - ".pcp/strategy/modules/*/acceptance.yaml"
+
+  # ── Security rules (generated by pcp init — do not remove) ────────────────
+  - id: SEC_001
+    name: "No hardcoded secrets, API keys, or tokens"
+    check: ast_pattern
+    pattern: "(password|secret|api[_-]?key|access[_-]?key|token)\\\\s*[:=]\\\\s*['\\\"][^'\\\"]{8,}['\\\"]"
+    severity: hard_block
+    message: "Load secrets from environment variables or a secrets manager, never hardcode them."
+    scope: ["*.py", "*.js", "*.jsx", "*.ts", "*.tsx", "*.go", "*.rb", "*.java", "*.php", "*.cs", "*.rs"]
+
+  - id: SEC_002
+    name: "No dynamic code evaluation on untrusted input"
+    check: ast_pattern
+    pattern: "\\\\b(eval|exec)\\\\s*\\\\("
+    severity: hard_block
+    message: "Dynamic code evaluation on untrusted input is a code-injection vector. Use a safe parser or explicit dispatch instead."
+    scope: ["*.py", "*.js", "*.jsx", "*.ts", "*.tsx", "*.go", "*.rb", "*.java", "*.php", "*.cs", "*.rs"]
+
+  - id: SEC_003
+    name: "No disabled TLS/certificate verification"
+    check: ast_pattern
+    pattern: "(verify\\\\s*=\\\\s*False|rejectUnauthorized\\\\s*:\\\\s*false|NODE_TLS_REJECT_UNAUTHORIZED\\\\s*=\\\\s*['\\\"]?0|ssl_verify\\\\s*=\\\\s*False|check_hostname\\\\s*=\\\\s*False)"
+    severity: hard_block
+    message: "Disabling certificate verification allows MITM attacks. Fix the underlying cert/trust-store issue instead."
+    scope: ["*.py", "*.js", "*.jsx", "*.ts", "*.tsx", "*.go", "*.rb", "*.java", "*.php", "*.cs", "*.rs"]
+
+  - id: SEC_004
+    name: "No string-built SQL passed to execute()/query()"
+    check: ast_pattern
+    pattern: "\\\\.(execute|query)\\\\(\\\\s*(f['\\\"]|['\\\"][^'\\\"]*['\\\"]\\\\s*\\\\+)"
+    severity: hard_block
+    message: "Use parameterized queries (placeholders + a params argument), not f-strings or string concatenation."
+    scope: ["*.py", "*.js", "*.jsx", "*.ts", "*.tsx", "*.go", "*.rb", "*.java", "*.php", "*.cs", "*.rs"]
+
+  # ── Project rules (add yours below) ──────────────────────────────────────
+"""
+
+CONTROLS_TEMPLATE = """\
+version: "1.0"
+# Canonical catalog of gates PCP enforces on this project. This is the control
+# catalog a future audit-evidence document (`pcp provenance`) reads to build a
+# per-file/per-criterion compliance card. control ids here are written verbatim
+# into .pcp/telemetry.jsonl's `control_id` field by every gate call site — do
+# not rename an id without updating the code that emits it.
+#
+# ssdf_practice references NIST SP 800-218 (Secure Software Development
+# Framework) practice ids. This is an informed mapping to give the catalog a
+# recognizable compliance vocabulary — it is NOT a certified SSDF/CMMC
+# assessment. Treat it as a jumpstart, not a certificate.
+controls:
+  - id: CTRL-001
+    name: "Test suite must pass"
+    layer: build-loop
+    mechanism: "qa.run_test_suite"
+    tool: "pytest | npm test | go test (auto-detected)"
+    enforcement: hard_block
+    description: "Full regression suite runs after every criterion's agent attempt and again at each wave-merge boundary. Blocks on failure. Skips (never blocks) if no test runner is detected — that skip is recorded, not silently treated as a pass."
+    ssdf_practice: ["PW.7.2"]
+
+  - id: CTRL-002
+    name: "Lint clean on changed files"
+    layer: build-loop
+    mechanism: "qa.run_lint"
+    tool: "ruff | eslint (auto-detected)"
+    enforcement: hard_block
+    description: "Lint scoped to the files changed by this criterion's attempt."
+    ssdf_practice: ["PW.7.2"]
+
+  - id: CTRL-003
+    name: "SAST + secret scan clean"
+    layer: build-loop
+    mechanism: "qa.run_sast"
+    tool: "semgrep"
+    enforcement: hard_block
+    description: "Static analysis + secret scan scoped to changed files. Skips (never blocks) if semgrep is not installed."
+    ssdf_practice: ["PW.7.2", "PW.8.1"]
+
+  - id: CTRL-004
+    name: "Layer 1 structural/AST rules"
+    layer: layer1
+    mechanism: "check.py + ci_rules.yaml (ast_pattern, file_exists)"
+    tool: "pcp check (pre-commit)"
+    enforcement: hard_block
+    description: "Deterministic pre-commit gate — modularity (MOD_*) and security (SEC_*) rules. A human can override a specific commit with `[pcp-bypass: reason]`; every bypass is logged (see CTRL-010) and this control's status for that commit is recorded as bypassed, not passed."
+    ssdf_practice: ["PS.1.1", "PW.7.1"]
+
+  - id: CTRL-005
+    name: "Architect review (diff vs persona/architecture/KB)"
+    layer: build-loop
+    mechanism: "architect_review.py, called per-criterion and at wave boundaries"
+    tool: "LLM judge (JUDGE_MODEL)"
+    enforcement: hard_block
+    description: "BLOCK-severity findings stop the build; a failed/erroring judge call is recorded as an error, not silently counted as a pass or a block."
+    ssdf_practice: ["PW.1.3", "PW.4.1"]
+
+  - id: CTRL-006
+    name: "PR alignment vs objective/target_state"
+    layer: layer2
+    mechanism: "gate.py `pcp gate` (PR-time) and build.py's in-loop advisory check"
+    tool: "LLM judge (JUDGE_MODEL)"
+    enforcement: advisory
+    description: "Never hard-blocks merge — score + regressions are logged for review."
+    ssdf_practice: ["PW.2.1"]
+
+  - id: CTRL-007
+    name: "Wave contract validation"
+    layer: wave-merge
+    mechanism: "build.py:_run_wave_merge, dependency completeness check"
+    tool: "n/a (deterministic)"
+    enforcement: hard_block
+    description: "Every declared inter-module dependency must have 100% complete acceptance criteria before the next dependency wave starts."
+    ssdf_practice: ["PS.1.1"]
+
+  - id: CTRL-008
+    name: "Strategy coverage & coupling"
+    layer: wave-merge
+    mechanism: "validate_strategy.py, re-run at each wave boundary"
+    tool: "LLM judge (coverage) + networkx graph math (coupling)"
+    enforcement: hard_block
+    description: "Coverage gaps or severe coupling violations (circular deps, God modules, shared state) block the next wave."
+    ssdf_practice: ["PW.1.1"]
+
+  - id: CTRL-009
+    name: "Deploy phase exit criteria"
+    layer: layer3
+    mechanism: "deploy_check.py, SDLC_phase.yaml exit_criteria"
+    tool: "n/a (deterministic)"
+    enforcement: hard_block
+    description: "Deterministic phase-exit gate — the only gate positioned right before a deploy action."
+    ssdf_practice: ["PO.3.2", "PW.9.1"]
+
+  - id: CTRL-010
+    name: "Bypass accountability"
+    layer: cross-cutting
+    mechanism: "check.py bypass log"
+    tool: "n/a"
+    enforcement: override
+    description: "A human can override CTRL-004 per-commit with `[pcp-bypass: reason]`. Every bypass is appended to bypass_log.yaml (reason + rules bypassed) and to telemetry.jsonl (result: bypassed) — never silent, always auditable."
+    ssdf_practice: ["PO.5.1"]
+
+  - id: CTRL-011
+    name: "Session transcript archival"
+    layer: cross-cutting
+    mechanism: "capture.py archive_transcript()"
+    tool: "n/a"
+    enforcement: advisory
+    description: "Every session transcript pcp capture is invoked on is copied (gzip-compressed) into .pcp/transcripts/ before classification runs — the full raw action record, not just the classifier's distilled BRD/decision-log summary, becomes part of this project's own durable evidence instead of living only in Claude Code's own ~/.claude/projects/ retention."
+    ssdf_practice: ["PO.3.2"]
+
+  - id: CTRL-012
+    name: "Ticket automation (analyze/approve/reject/submit)"
+    layer: cross-cutting
+    mechanism: "program-context-protocol-team: tickets/analysis.py, tickets/actions.py"
+    tool: "LLM judge (JUDGE_MODEL) for analysis; Temporal for submission"
+    enforcement: advisory
+    description: "A ticket ingested via program-context-protocol-team's webhook is analyzed (root-cause hypothesis + fix options), and every human decision (approve one option / reject) is recorded here, with the LLM's full raw analysis response stored as evidence — same as any other QA judge call. A human always decides; nothing in this control auto-picks an option."
+    ssdf_practice: ["PW.4.1", "RV.1.1"]
+
+  - id: CTRL-013
+    name: "Design consistency check"
+    layer: build-loop
+    mechanism: "build.py _run_design_consistency_check()"
+    tool: "n/a — deterministic regex, no external tool"
+    enforcement: advisory
+    description: "PCP Design lifecycle, stage 4 (Verify). For a UI-facing criterion, once .pcp/design_system.md has real established color tokens, flags hardcoded hex color literals in that criterion's target file — a heuristic signal the screen may not be using the project's own design system, not proof either way. Never blocks; a legitimate reason to hardcode a specific value is common (e.g. a brand-mandated exact color)."
+    ssdf_practice: ["PW.7.1"]
+
+  - id: CTRL-014
+    name: "logic_tier drift at wave-merge"
+    layer: wave-merge
+    mechanism: "build.py:_run_wave_tier_drift_check(), 5th wave-merge sub-check"
+    tool: "n/a — deterministic regex, no external tool"
+    enforcement: hard_block
+    description: "A completed criterion declaring logic_tier 1-5 (deterministic through cached-reuse — no runtime LLM call expected by definition) whose own target file demonstrably imports an LLM SDK is a real signal the declared decision no longer matches what was actually built. Only rung 6 (deep-think LLM) is expected to import one. Does not re-examine build_vs_buy — no comparably cheap deterministic signal exists for that field yet."
+    ssdf_practice: ["PW.1.1"]
+
+  - id: CTRL-015
+    name: "design_justification substance check"
+    layer: build-loop
+    mechanism: "build.py _run_design_justification_check(), JUDGE_MODEL + adversarial verify"
+    tool: "LLM judge (JUDGE_MODEL)"
+    enforcement: hard_block
+    description: "Active structural-forcing for PCP Design lifecycle stage 4 — design_audit.py's Feature Exposure Ladder is a passive post-hoc rollup (pure keyword/presence logic, a checklist full of junk strings still classifies as rung 3/4). This check runs during the build itself: judges whether a UI-facing criterion's submitted checklist_passed/jtbd_framing/deviations_from_system reflects real design thinking or was lazily filled just to pass validation, re-verified adversarially before it can block the criterion the same way architect-review/gate findings do."
+    ssdf_practice: ["PW.7.1"]
+
+  - id: CTRL-016
+    name: "build_vs_buy drift at wave-merge"
+    layer: wave-merge
+    mechanism: "build.py:_run_wave_build_vs_buy_drift_check(), 6th wave-merge sub-check"
+    tool: "n/a — deterministic Python import analysis, no external tool"
+    enforcement: hard_block
+    description: "A completed criterion declaring build_vs_buy=reuse_whole or fork_adapt implies an external dependency should be visible in its target file — zero external imports despite that claim is a real signal the declared decision no longer matches what was built. Deliberately narrower than the logic_tier drift check (CTRL-014): build_fresh is NOT checked in the other direction (package names routinely differ from import names — pyyaml/yaml, beautifulsoup4/bs4 — too noisy to trust as a hard gate), and reuse_partial/reimplement_from_reference are skipped entirely (no distinguishing import signature either way)."
+    ssdf_practice: ["PW.1.1"]
+
+  - id: CTRL-017
+    name: "build_vs_buy rationale substance check"
+    layer: build-loop
+    mechanism: "build.py _run_build_vs_buy_justification_check(), deterministic placeholder/word-count check"
+    tool: "n/a — deterministic regex/word-count, no external tool"
+    enforcement: hard_block
+    description: "Structural-forcing for build_vs_buy, same enforcement posture design_justification (CTRL-015) already gets — build_vs_buy's rationale is schema-required to be present but was never checked for substance, so a placeholder string like the literal unfilled prompt template text passed validation as a real decision. Deterministic, not an LLM judge call: unlike design_justification (UI-facing criteria only), build_vs_buy is required on EVERY criterion, so an LLM call here on every attempt would violate Token Discipline for a field that mostly just needs a placeholder-text check, not genuine semantic judgment."
+    ssdf_practice: ["PW.1.1"]
+
+  - id: CTRL-018
+    name: "Build-agent scope guard (over-reach allowlist)"
+    layer: build-loop
+    mechanism: "build.py _run_scope_check() — git-diff changed files vs the module's declared surface (all criterion target files, .pcp/strategy/modules/<module>/, .pcp/design_system.md, test files)"
+    tool: "n/a — deterministic path matching over git diff, no external tool"
+    enforcement: advisory
+    description: "Over-reach guard: a criterion agent modifying files outside its own module's declared surface is the classic unattended-loop failure mode (loop touches unrelated code). PCP had a denylist (protected_path) but no allowlist until now. Warn-only by default — legitimate cross-cutting writes exist (module registries, shared interfaces), so the false-positive rate should be measured on real builds before enforcement; PCP_BUILD_SCOPE_MODE=block upgrades it to a hard per-attempt gate, =off disables (recorded as skipped, never silently)."
+    ssdf_practice: ["PS.1.1", "PW.7.1"]
+
+  - id: CTRL-019
+    name: "Logic-tier mechanism presence (positive check)"
+    layer: wave-merge
+    mechanism: "build.py _run_wave_tier_presence_check() — rungs 2-5 target files checked for their declared rung's mechanism signature (solver/ML/retrieval/cache imports; stdlib lru_cache counts for rung 5)"
+    tool: "n/a — deterministic import analysis, no external tool"
+    enforcement: advisory
+    description: "CTRL-014 checks the negative for rungs <=5 (no LLM SDK); this checks the positive: a rung-2 criterion with no solver import, rung-4 with no retrieval dependency, rung-5 with no cache layer is likely a tier declared but not implemented at that tier. Advisory — the mechanism may live in a shared helper the target imports; earns hard-block only after a measured false-positive rate."
+    ssdf_practice: ["PW.1.1"]
+
+  - id: CTRL-021
+    name: "Context-route staleness"
+    layer: wave-merge
+    mechanism: "context_map.validate() — every route in .pcp/context_map.yaml must resolve to at least one existing file (per known module for {module} templates, or via fallback)"
+    tool: "n/a — deterministic path resolution, no external tool"
+    enforcement: advisory
+    description: "The context routing table is itself a drift surface: files evolve, routes go stale, and a stale route silently starves agents of the context they need — worse and less visible than over-feeding, since a missing rule breaks a gate invisibly while an extra file only costs tokens. Checked at wave boundaries and by pcp doctor."
+    ssdf_practice: ["PW.1.1"]
+
+  - id: CTRL-020
+    name: "Rung-necessity challenge (over/under-declaration)"
+    layer: wave-merge
+    mechanism: "build.py _run_wave_rung_necessity_check() — deterministic judgment-keyword contradiction check for rung-1 declarations, plus ONE batched judge call per wave over completed rung-6 criteria (could a cheaper rung serve?)"
+    tool: "judge model (rung-6 half only; rung-1 half is keyword-deterministic)"
+    enforcement: advisory
+    description: "The Decision Integrity gap: nothing previously challenged a criterion lazily declared rung 6 that a truth table could serve, or rung 1 with judgment-shaped language in its own description. The rung-6 half is the ladder's one irreducibly semantic gate, so it gets the same posture as coverage_score — advisory, recorded, never trusted blindly, never blocking."
+    ssdf_practice: ["PW.1.1"]
+
+  - id: CTRL-022
+    name: "Accessibility (WCAG) scan"
+    layer: build-loop
+    mechanism: "build.py _run_a11y_check(), uat.check_axe() -- @axe-core/cli via npx"
+    tool: "axe-core"
+    enforcement: advisory
+    description: "PCP Design lifecycle, stage 4 addendum. Only fires on a UI-facing criterion that declares a url -- deterministic WCAG scan of the rendered page, no LLM involved. Advisory, same warn-first rollout posture as CTRL-013/018/019/020: a11y defects are real and common in AI-generated UI, but false-positive rate on real projects isn't measured yet."
+    ssdf_practice: ["PW.7.1"]
+
+  - id: CTRL-023
+    name: "Visual quality (checklist-anchored VLM judge)"
+    layer: build-loop
+    mechanism: "build.py _run_visual_quality_check(), uat.check_visual_quality() -- llm.call_json_with_images against a fresh screenshot"
+    tool: "judge model (JUDGE_MODEL)"
+    enforcement: advisory
+    description: "PCP Design lifecycle, stage 4 addendum, from a 2026-07-18 research pass on the intent-to-UI articulation gap: a checklist-anchored VLM judge measures ~94% human-correlation vs. ~21% for a bare freeform review, so this deliberately judges a fixed checklist rather than asking 'does this look good.' Only fires on a UI-facing criterion that declares a url; compares against the criterion's own reference_image when one is declared. Advisory only -- an LLM visual judgment should never hard-block a build until its own false-positive rate is measured on real projects, same posture every other judge-model gate in this catalog started at."
+    ssdf_practice: ["PW.7.1"]
+
+  - id: CTRL-024
+    name: "Module spec alignment (Two Validation Passes, Pass 1)"
+    layer: wave-merge
+    mechanism: "validate_module.py run_validate_module(), called per-module in build.py _run_wave_merge"
+    tool: "judge model (JUDGE_MODEL)"
+    enforcement: advisory
+    description: "Closes an orphan found 2026-07-20: `pcp validate-module` existed as a fully-built standalone command but was never actually called from anywhere in the enforcement lifecycle -- only `validate-strategy` (Pass 2: modules vs objective) was wired into the wave-merge gate; Pass 1 (does each module's own spec still align with the objective/decomposition) had no automatic trigger at all. Advisory, same warn-first rollout posture as every other judge-model gate in this catalog -- false-positive rate on real projects not measured yet."
+    ssdf_practice: ["PW.1.1"]
+
+  - id: CTRL-025
+    name: "Navigation depth (click-depth outliers)"
+    layer: wave-merge
+    mechanism: "build.py _run_nav_depth_check(), self-declared nav_depth field audited against PCP_NAV_DEPTH_THRESHOLD"
+    tool: "n/a (deterministic)"
+    enforcement: advisory
+    description: "How many clicks/taps from the app's primary entry point to reach a feature -- self-declared per criterion like logic_tier/build_vs_buy, not computed via real routing-graph analysis (a bigger, per-framework build this field doesn't earn on its own). Flags criteria missing the field entirely and criteria exceeding the 3-click threshold (default, PCP_NAV_DEPTH_THRESHOLD). Advisory -- a declared value is still a claim, not a measurement."
+    ssdf_practice: ["PW.7.1"]
+
+  - id: CTRL-026
+    name: "Feature customization structural check"
+    layer: build-loop
+    mechanism: "build.py _run_customization_check(), design_justification.customizable + customization_notes"
+    tool: "n/a (deterministic)"
+    enforcement: advisory
+    description: "A criterion declaring design_justification.customizable=true should show SOME settings-shaped signal in its own target file (setting/preference/config keyword) -- a bare true with no such signal reads the same way a lazily-filled design_justification does. Deterministic keyword scan, not a semantic judge call -- cheap, same Token Discipline posture as CTRL-017's build_vs_buy placeholder check."
+    ssdf_practice: ["PW.7.1"]
+
+  - id: CTRL-027
+    name: "Top menu bar convention (desktop_app archetype only)"
+    layer: wave-merge
+    mechanism: "build.py _run_menu_bar_check(), .pcp/design_conventions.yaml ui_archetype + top_menu_bar.required_menus"
+    tool: "n/a (deterministic)"
+    enforcement: advisory
+    description: "File/Edit/View/Help-style top menu bar is a desktop-app convention, not a universal one -- this check stays completely inert (never even runs) unless a human explicitly sets ui_archetype: desktop_app in .pcp/design_conventions.yaml (default web_app). When active, deterministic substring scan of UI-facing criteria target files for each required menu label; missing ones flagged advisory."
+    ssdf_practice: ["PW.7.1"]
+
+  - id: CTRL-028
+    name: "UI kit recipe completeness + import verification"
+    layer: wave-merge
+    mechanism: "build.py _run_wave_ui_kit_check(), .pcp/ui_kit_recipes.yaml organism->component mapping + screen_archetypes->required-organisms recipe"
+    tool: "n/a (deterministic)"
+    enforcement: advisory
+    description: "Build-vs-buy for PCP's UI building blocks: PCP does not build or maintain component code -- shadcn/ui (MIT, vendored per-project, official MCP server for search/retrieval) already solves that. PCP owns the thin layer on top: which organisms an archetype needs (recipe completeness -- a criterion declaring screen_archetypes=[dashboard] should show chart-panel/data-table/kpi-tile among its ui_organisms), and whether a declared organism shows real evidence of use (import-path substring match against the criterion's own target file, same mechanism CTRL-019 already uses for logic_tier). Advisory -- a real import can legitimately not match the hint (re-export, alias), so this is a review signal, not proof of non-use. Stays inert (no telemetry record) unless .pcp/ui_kit_recipes.yaml exists."
+    ssdf_practice: ["PW.7.1"]
+
+  - id: CTRL-029
+    name: "Generic lazy-marker scan"
+    layer: build-loop
+    mechanism: "build.py _run_lazy_marker_check() -- regex scan of ALL changed files for TODO/FIXME/XXX/HACK/placeholder/not-implemented markers and stub function bodies (pass/... only)"
+    tool: "n/a (deterministic regex)"
+    enforcement: advisory
+    description: "Lazy-agent mitigation backlog item 3 (2026-07-20): PCP previously only checked for placeholder text narrowly, inside build_vs_buy/design_justification's own free-text fields (CTRL-017/015). This is the general form -- any changed file, any lazy-shaped marker or stub body -- surfaced as a count/location for a human to judge, since a TODO or a stub can be legitimate. Advisory only, never blocks."
+    ssdf_practice: ["PW.7.1"]
+
+  - id: CTRL-030
+    name: "Integrity Auditor (retrospective statistical drift)"
+    layer: wave-merge
+    mechanism: "integrity_audit.py analyze() -- generalizes coverage_audit.py's drift-detection pattern across telemetry.jsonl: fast completions vs. declared logic_tier, per-module placeholder-flag concentration, recurring unresolved findings, uniform/templated evidence"
+    tool: "n/a (deterministic, statistical)"
+    enforcement: advisory
+    description: "Swarm-role backlog's Integrity Auditor (2026-07-20): retrospective-only -- reads already-complete criteria across the whole project, can't correct what's already built, only flags for human review. Deterministic-first, same posture as every other statistical-drift check in this catalog; the genuinely ambiguous tail (an LLM judging the flagged pattern) is not built in this pass. Runs at wave boundaries, not per-criterion -- the value is seeing patterns across many completed criteria no single-criterion CTRL check can see by design."
+    ssdf_practice: ["PW.1.1"]
+
+  - id: CTRL-031
+    name: "module_logic_breakdown built-code verification"
+    layer: wave-merge
+    mechanism: "build.py _run_wave_logic_breakdown_check() -- keyword-overlap between a module's declared spec.module_logic_breakdown and the combined description+target-file content of its OWN completed criteria"
+    tool: "n/a (deterministic keyword scan)"
+    enforcement: advisory
+    description: "Lazy-agent backlog item 9's verification half: kickoff/pm already keyword-check a declared breakdown item against a module's own criteria descriptions BEFORE build (check_module_logic_breakdown_coverage); this re-checks AFTER build, against completed criteria's actual target-file content -- does code exist that plausibly reflects each declared internal component, not just that a criterion was worded to mention it. Deterministic, not the CTRL-015-style LLM judge the backlog item originally sketched -- the semantic half (does the code genuinely FULFILL the component) stays deferred. Inert unless a module declares module_logic_breakdown."
+    ssdf_practice: ["PW.1.1"]
+
+  - id: CTRL-032
+    name: "Architect pre-flight (pre-implementation sanity check)"
+    layer: build-loop
+    mechanism: "build.py _run_architect_preflight() -- one judge-model call reviewing a HIGH-RISK criterion's declared logic_tier/build_vs_buy/module context BEFORE any code is written, injected as advisory context into attempt 1's own prompt"
+    tool: "judge model (JUDGE_MODEL)"
+    enforcement: advisory
+    description: "Swarm-role backlog's genuinely new lifecycle point: PCP's existing architect-review (CTRL-005) is post-hoc only -- it reviews the diff after code exists. This runs BEFORE, for high-risk criteria only (logic_tier >= 5, or build_vs_buy of reuse_whole/fork_adapt). Advisory prompt-injection in this pass, not the block_findings channel the backlog originally sketched -- PCP's attempt loop has no separate plan-then-code step, so routing this into block_findings would mean skipping a whole attempt with zero code written, a real behavior change to the 3-attempt contract. Upgrade path is the same L1-report-first rollout every other check in this catalog followed."
+    ssdf_practice: ["PW.1.1"]
+
+  - id: CTRL-033
+    name: "ci_rules.yaml contract completeness"
+    layer: wave-merge
+    mechanism: "build.py _run_wave_contract_completeness_check() -- every hard_block rule in ci_rules.yaml missing an ABC-style contract block (preconditions/invariants/recovery) is flagged"
+    tool: "n/a (deterministic)"
+    enforcement: advisory
+    description: "Agent Behavioral Contracts reference pattern (arXiv:2602.22302, 2026-07-20 research pass -- see docs/research-rigidity-vs-reliability-2026-07.md). ci_rules.yaml's rules gained an optional `contract` block (preconditions/invariants/recovery -- Governance is already the existing `severity` field, not duplicated). This is the presence check, same posture CTRL-019 already uses for logic_tier: a hard_block rule with no contract just relies on the flat severity gate, exactly as it always did -- advisory, never blocks, project-wide (one ci_rules.yaml, not per-module)."
+    ssdf_practice: ["PW.1.1"]
+
+  - id: CTRL-034
+    name: "Install-only fast path (direct priorart match)"
+    layer: build-loop
+    mechanism: "build.py _run_install_only() -- criterion/module declares install_only+install_command; human approval (or --yes), then run install_command, then Layer 1 + full test suite as a deterministic smoke test. No LLM calls, no TDD/architect-review cycle."
+    tool: "n/a (deterministic)"
+    enforcement: hard_block
+    description: "When priorart already confirms an existing package is a direct match for a criterion (or whole module), running the full TDD/architect-review/LLM-gate cycle just to write a thin wrapper around an install is pure waste. This fast path skips the coding-agent session entirely -- but never skips verification: a human must confirm the match (install_approvals.yaml, hash-chained like bypass_log.yaml), and the install still has to pass a real smoke test (Layer 1 + full regression suite) before the criterion is marked complete. A decline or a failed smoke test falls through to the normal full build path, never a silent skip."
+    ssdf_practice: ["PW.4.1", "PW.7.2"]
+
+  - id: CTRL-035
+    name: "Objective-conflict gate"
+    layer: build-loop
+    mechanism: "objective_conflicts.reconcile() -- build.py's first preflight step, before any module/agent work starts. An active brd_items.yaml entry with a live drift_flag (set by capture.py's classifier when a captured business item conflicts with objective.md's text) is stamped with a SHA-256 hash of objective.md+target_state.md's content at flag time. If current content still matches that hash, the conflict is unresolved and blocks. If the hash no longer matches, the file was actually edited since the flag was raised -- auto-clears deterministically."
+    tool: "n/a (deterministic hash check; flagging itself is Haiku-classified in capture.py)"
+    enforcement: hard_block
+    description: "2026-07-22 incident, Project O dogfood: a business objective correction was discussed and agreed, objective.md/target_state.md never got rewritten to match, and a 30+-agent build cycle two days later built exactly the rejected shape end-to-end -- every other gate passed, because every gate validates the build against objective.md as given, never against whether objective.md is still true. `pcp objective-conflicts` lists/dismisses flags; `pcp correct-objective` is the human-gated resolution path (LLM proposes an objective.md/target_state.md rewrite from the stated correction, human approves the real diff, then it's written -- same pattern pcp kickoff/pm already use for module specs). `pcp build` also self-captures its own live session (CLAUDE_CODE_SESSION_ID) before this gate even runs, so a correction discussed in the same still-open session that authorizes the build gets a chance to be caught."
+    ssdf_practice: ["PW.1.1", "PW.4.1"]
+
+  - id: CTRL-036
+    name: "Narrative lint (CLAUDE.md vs tracked state)"
+    layer: wave-merge
+    mechanism: "narrative_lint.py run() -- deterministic stale-dated-reference and missing-referenced-file scan of every CLAUDE.md-family file, plus ONE batched judge call comparing status-shaped narrative lines (Pending/Open Decision/Planned/etc.) against current_state.md+architecture.md for semantic contradiction"
+    tool: "judge model (JUDGE_MODEL, contradiction check only; the two file-scan sub-checks are deterministic)"
+    enforcement: advisory
+    description: "2026-07-24 fleet evidence: a context-hygiene pass across 4 projects (Project E, Project W, Project A, Project M) found narrative prose in CLAUDE.md -- stage descriptions, 'Open Decisions,' 'Pending' lists -- drifted from tracked state 3-for-3 in projects checked (largest: ~65 lines of dead launch-weekend content still live 7 weeks post-launch, undetected). Nothing in PCP's existing gate catalog checks free-text prose against current_state.md/architecture.md -- every other gate validates code against spec. Deterministic sub-checks port `~/.claude/scripts/session-hygiene-check.sh`'s mechanical checks into PCP's own enforcement lifecycle (telemetry, not just a SessionStart print); the semantic contradiction check is the one irreducibly judgment-shaped part, same rung-6 posture as CTRL-020's rung-necessity check -- one batched call, advisory, fails open. Standalone via `pcp narrative-lint`; also runs at every wave-merge boundary."
+    ssdf_practice: ["PW.1.1"]
+
+  - id: CTRL-037
+    name: "Build-loop bypass detector"
+    layer: cross-cutting
+    mechanism: "build_loop_bypass.py check() -- git log commit dates vs telemetry.jsonl's last entry timestamp, run by doctor.py's check_environment() (pcp build/watch/deploy's own automatic preflight) and the interactive `pcp doctor`"
+    tool: "n/a (deterministic)"
+    enforcement: advisory
+    description: "2026-07-24 incident (Project O, 3rd recurrence: 07-08, mid-July, 07-21-onward): pcp build's formal gated loop stopped being invoked, not by decision -- a real Postgres schema-bloat bug got killed and never relaunched -- while 31 commits landed via `pcp pm` + ad-hoc work over the next 3 days, telemetry.jsonl silent the whole time. Nothing previously surfaced that drift at the moment it started; it only became visible via manual transcript archaeology. Flags when commits continue past telemetry's last record by more than PCP_BUILD_LOOP_BYPASS_THRESHOLD_DAYS (default 3) -- inert until a project has at least one real telemetry record to compare against."
+    ssdf_practice: ["PW.1.1"]
+"""
+
+CONTEXT_MAP_TEMPLATE = """\
+version: "1.0"
+# Deterministic context routing: which files an agent reads per scenario.
+# Human-editable; consumed by pcp build's prompt builder. Rules that keep
+# routing safe (see logic_tier_guide.md's sibling doc rationale):
+# - scenarios are detected from schema fields, never by an LLM
+# - intent files (objective/spec) are routed WHOLE, never fragmented
+# - sliced state must be a GENERATED projection (docs/built.md), never a
+#   hand-maintained copy -- copies diverge, projections can't
+# `{module}` is substituted per-criterion. `fallback` used only when no
+# primary file exists. Routes resolving to zero files are flagged (CTRL-021).
+routes:
+  always:
+    files:
+      - .pcp/objective.md
+      - .pcp/architecture.md
+      - .pcp/architect_persona.md
+  module_state:
+    files:
+      - .pcp/strategy/modules/{module}/docs/built.md
+    fallback:
+      - .pcp/current_state.md
+  ui_facing:
+    files:
+      - .pcp/design_system.md
+  logic_tier_declared:
+    files:
+      - .pcp/logic_tier_guide.md
+"""
+
+LOGIC_TIER_GUIDE_TEMPLATE = """\
+# Logic-Tier Selection & Implementation Guide
+
+Read this when choosing a criterion's `logic_tier` or implementing a criterion
+whose tier is already declared. Scaffolded by `pcp init`; doctrine, not
+project-specific — edit only if your project genuinely disagrees with it.
+
+## Choosing a rung: classify the CORRECTNESS ORACLE, not the task
+
+Ask "how would I know an output is correct?", never "what kind of task is this":
+
+| Correctness means... | Rung |
+|---|---|
+| It satisfies rules I can write down completely | 1 |
+| It's the best feasible option under known constraints | 2 |
+| It matches what historically happened in similar cases | 3 |
+| It's faithful to what our documents/records actually say | 4 |
+| Same as last time for the same question (overlay on any rung) | 5 |
+| A reasonable human would accept it — and another human might accept a different answer | 6 |
+
+## The walk (cheapest first — stop at the first rung whose litmus passes)
+
+0. DECOMPOSE FIRST. A criterion is rarely one decision. "Categorize expenses
+   and flag anomalies with explanations" = categorization (rung 1 or 3) +
+   anomaly scoring (3) + explanation text (6). Classify each decision point
+   separately; declare the highest rung actually present; implement each
+   sub-decision at its own rung.
+1. Rung 1 litmus: could you write unit tests asserting EXACT outputs for every
+   input class right now (~<=20 rule branches, zero "it depends")?
+   Danger sign: judgment verbs in the description (recommend/interpret/assess).
+2. Rung 2 litmus: you cannot enumerate the answers but CAN enumerate the
+   constraints and a scoring function — "best/cheapest/shortest X subject to Y".
+   Danger sign: "optimization" with no writable objective = preference judgment.
+3. Rung 3 litmus: (input -> correct outcome) history exists or is cheap to
+   collect, hundreds of rows minimum. Countable before any code is written.
+4. Rung 4 litmus: the answer already exists as text in a bounded corpus you
+   control — the job is retrieval and assembly, not knowledge creation.
+5. Rung 5 is an OVERLAY, not a destination: repetitive question stream ->
+   cache in front of whichever rung serves it.
+6. Rung 6 only after 1-4 each failed FOR A STATED REASON — the reasons go in
+   build_vs_buy.rationale. Schema-cage the output, define the refusal path,
+   and accept: shape is reproducible, content is not.
+
+## Implementing each rung + where to search BEFORE building
+
+### Rung 1 — deterministic
+Process: rules as DATA (table/dict/config), never nested ifs; boundary +
+property tests; exhaustive tests where the domain is finite.
+Search first: domain rules are usually maintained packages — pycountry,
+dateutil, babel, holidays. Never hand-code tax tables, timezone rules, ISO enums.
+
+### Rung 2 — solver
+Process: formalize on paper (variables, domains, constraints, objective);
+brute-force a TINY instance first — that is your solver's ground truth; then
+OR-Tools CP-SAT by default, pulp/CBC for LP/MIP, z3 for logic/SMT, networkx
+for graph problems. Done = solver output matches brute force on small instances.
+Search first: OR-Tools examples gallery, MiniZinc model library (pattern
+catalog), OR Stack Exchange for the model shape.
+
+### Rung 3 — statistical/ML
+Process: data audit (row count, label quality, leakage) -> dumb baseline
+(majority class / logistic) -> sklearn pipeline -> holdout eval -> confidence
+threshold WITH a declared fallback path (below threshold -> rung 6 or human).
+Search first: prefer PRETRAINED over training — HuggingFace for text/vision;
+Kaggle and papers-with-code under the task's name; sklearn before anything exotic.
+
+### Rung 4 — RAG
+Process: corpus inventory (contents, freshness, owner) -> try grep/BM25
+(rank_bm25, free) BEFORE embeddings -> hybrid only if BM25 measurably fails ->
+retrieval-score threshold with an explicit "no answer" refusal (refusal beats
+hallucination) -> cite the source in the output -> decompose the synthesized
+answer into individual claims and check each against the retrieved context
+(entailed / contradicted / unsupported) before returning it -- retrieval-score
+threshold only proves retrieval worked, not that the synthesis stayed
+faithful to what was retrieved. Where the corpus is structured (exact field
+names, not free text), this is a cheap deterministic string/value match, not
+an LLM judge call; reserve an LLM claim-check for synthesis that actually
+combines/derives from multiple fields.
+Search first: semantic-router; a vector DB only when BM25 fails on real queries.
+
+### Rung 5 — cached reuse
+Process: define the cache key (normalized input; embedding similarity only for
+paraphrase tolerance) -> invalidation tied to the UNDERLYING DATA's change
+events, not just TTL -> spot-check recompute a sample % -> collision test.
+Search first: functools.lru_cache -> diskcache/redis -> GPTCache-class only
+when semantic matching is proven necessary.
+
+### Rung 6 — LLM (last resort)
+Process: output schema FIRST (Pydantic/JSON Schema) -> prompt = role + inputs
++ schema + refusal rule -> Instructor/Outlines validation -> low temperature ->
+verify pass when stakes are high -> every call logged with cost.
+Search guidance is INVERTED here: search for a way OFF rung 6 — recheck rungs
+1-5, then look for a bounded sub-decision split before accepting rung 6.
+
+## Always, at every rung
+Record the candidates you actually checked in build_vs_buy.candidates_considered
+— the search step and the audit trail are the same act. A criterion whose
+rationale names nothing checked is a criterion where nothing was checked.
+"""
+
+PRETOOLUSE_GUARD_TEMPLATE = """\
+#!/bin/sh
+# PCP tool-call-time guard (scaffolded by pcp init, 2026-07-17).
+#
+# Commit-time gates (pcp check) catch a protected-path edit only AFTER the
+# agent already made it. This PreToolUse hook denies the Edit/Write at the
+# moment the agent attempts it — the layer Endor Agent Governance and
+# Microsoft's agent-governance-toolkit operate at. DENY-only by design: a
+# hook that auto-ALLOWS anything is an approval bypass and gets hard-blocked
+# by Claude Code's own permission layer (see CLAUDE.md Hard Rules history).
+#
+# NOT wired automatically. To enable, add to .claude/settings.json yourself:
+#   "hooks": {"PreToolUse": [{"matcher": "Edit|Write",
+#     "hooks": [{"type": "command", "command": "sh .pcp/hooks/pretooluse_guard.sh"}]}]}
+#
+# Requires jq. Exits 0 (no opinion) when jq is missing or input is unparseable.
+command -v jq >/dev/null 2>&1 || exit 0
+INPUT=$(cat)
+FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+[ -z "$FILE" ] && exit 0
+if [ "$PCP_AGENT_SESSION" = "1" ]; then
+  case "$FILE" in
+    *.pcp/objective.md|*.pcp/target_state.md|*.pcp/architecture.md|*.pcp/ci_rules.yaml|*.pcp/controls.yaml|*.pcp/SDLC_phase.yaml|*.pcp/strategy/decomposition.md|*.pcp/strategy/dependency_map.md|*.pcp/strategy/modules/*/spec.yaml|*.pcp/strategy/modules/*/acceptance.yaml)
+      printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"PCP: unattended agent sessions may not edit human-authorized spec files. Route the change to the human, who applies it via pcp correct-objective / pcp pm / pcp amend (diff shown, approved, then written). See .pcp/ci_rules.yaml protected_path."}}\\n'
+      exit 0
+      ;;
+  esac
+fi
+exit 0
+"""
+
+BUILD_LOOP_WARNING_TEMPLATE = """\
+#!/usr/bin/env python3
+# PCP build-loop warning (scaffolded by pcp init, 2026-07-24).
+#
+# Real Project O finding: CTRL-037 (pcp doctor) catches build-loop
+# bypass only in retrospect -- after the fact, only if someone runs
+# pcp doctor. This is the real-time version: fires the moment an Edit/Write
+# happens outside pcp build's own gated agent loop (PCP_AGENT_SESSION != 1),
+# so the warning lands when it's actually useful -- before the work
+# happens, not days later. Purely informational: no permissionDecision is
+# ever set, so this can never block, ask, or grant a bypass -- it cannot
+# hit the same hard-block Claude Code's permission layer applies to a hook
+# that tries to auto-approve something (see verify-syntax-fix.sh's own
+# history). One warning per session, not per edit -- noise defeats the
+# point.
+#
+# NOT wired automatically. To enable, add to .claude/settings.json yourself:
+#   "hooks": {"PreToolUse": [{"matcher": "Edit|Write",
+#     "hooks": [{"type": "command", "command": "python3 .pcp/hooks/build_loop_warning.py"}]}]}
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def main() -> None:
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        sys.exit(0)
+
+    cwd = payload.get("cwd") or "."
+    project_root = Path(cwd).resolve()
+    pcp_dir = project_root / ".pcp"
+    if not pcp_dir.is_dir():
+        sys.exit(0)  # not a PCP-governed project
+
+    if os.environ.get("PCP_AGENT_SESSION") == "1":
+        sys.exit(0)  # inside pcp build's own gated loop already
+
+    session_id = payload.get("session_id") or os.environ.get("CLAUDE_CODE_SESSION_ID") or "unknown"
+    marker = pcp_dir / f".build_loop_warning_shown_{session_id}"
+    if marker.exists():
+        sys.exit(0)  # already warned this session
+    try:
+        marker.write_text("")
+    except OSError:
+        pass
+
+    msg = (
+        "PCP: this edit is happening outside pcp build's gated loop -- "
+        "no architect-review/QA/telemetry will be recorded for this change. "
+        "Run `pcp build` for a verified build, or continue if this is intentional "
+        "ad-hoc work (`pcp build-status` / .pcp/build_report.md show what pcp build "
+        "gives you that this path skips)."
+    )
+    print(json.dumps({
+        "systemMessage": msg,
+        "hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": msg},
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()
+"""
+
+SESSION_UPDATE_CHECK_TEMPLATE = """\
+#!/usr/bin/env python3
+# PCP update-available notice (scaffolded by pcp init, 2026-07-31).
+#
+# Announce-only, on purpose: `pcp self-update` (git pull --ff-only, human-
+# run) is the only thing that ever changes code. This hook just tells you
+# an update exists at session start -- it never fetches-and-pulls itself,
+# never runs in the background, and never touches the working tree. Same
+# reasoning as build_loop_warning.py: a hook that can silently change
+# behavior for a session already in progress is the risk this project
+# spent real effort removing elsewhere (the 2026-07-27 cron/curl launch
+# blocker) -- fixing it here only to reintroduce the shape at a different
+# trigger (session start instead of a timer) would be the same mistake.
+#
+# NOT wired automatically. To enable, add to .claude/settings.json yourself:
+#   "hooks": {"SessionStart": [{"hooks": [{"type": "command",
+#     "command": "python3 .pcp/hooks/session_update_check.py"}]}]}
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+def main() -> None:
+    try:
+        payload = json.load(sys.stdin)
+    except Exception:
+        payload = {}
+
+    cwd = payload.get("cwd") or "."
+    project_root = Path(cwd).resolve()
+    if not (project_root / ".pcp").is_dir():
+        sys.exit(0)  # not a PCP-governed project
+
+    try:
+        result = subprocess.run(
+            ["pcp", "self-update", "--check"],
+            capture_output=True, text=True, timeout=15,
+        )
+    except Exception:
+        sys.exit(0)  # offline, pcp not on PATH, etc. -- stay silent, never block boot
+
+    msg = (result.stdout or "").strip()
+    if not msg or "update available" not in msg.lower():
+        sys.exit(0)  # current, unknown, or unavailable -- nothing worth announcing
+
+    print(json.dumps({
+        "systemMessage": msg,
+        "hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": msg},
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()
+"""
+
+GITIGNORE_TEMPLATE = """\
+# Build artifacts — committing these breaks PCP's parallel-module worktree
+# merges (and pollutes diffs the gates judge). Scaffolded by `pcp init` only
+# when the project had no .gitignore at all; edit freely, it's yours now.
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.coverage
+htmlcov/
+node_modules/
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+.DS_Store
+.pcp/.build_loop_warning_shown_*
+
+# Agent-session-local config. Claude Code writes these per working directory,
+# and a worktree-scoped value (TMPDIR, granted permissions) differs in every
+# parallel build worktree. Committing them turns every wave merge into an
+# add/add conflict on a scratch config file — 2026-07-25 Project O,
+# where three criteria that had all passed their gates could not be merged.
+.claude/settings.json
+.claude/settings.local.json
+
+# PCP's own operational writes. These are auto-generated audit artifacts, and
+# PCP appends to them in the MAIN .pcp/ throughout a build by design. Tracking
+# them means a parallel-build merge hits "your local changes would be
+# overwritten by merge" and refuses — 2026-07-27 Project S dogfood, where a
+# criterion that had passed every gate could not be merged because the token
+# ledger had moved underneath it. Governance SPECS (objective, strategy/,
+# ci_rules, controls) stay tracked deliberately; only the run-time logs go.
+.pcp/token_ledger.yaml
+.pcp/telemetry.jsonl
+.pcp/decision_log.jsonl
+.pcp/coverage_audit.jsonl
+.pcp/build_progress.yaml
+.pcp/run_ledger.jsonl
+.pcp/hidden_coupling.json
+.pcp/notify_heartbeat.yaml
+.pcp/escalations.yaml
+.pcp/prune_log.yaml
+.pcp/brd.md
+.pcp/brd_items.yaml
+.pcp/evidence/
+.pcp/transcripts/
+
+# pytest-testmon's per-test dependency cache — a build artifact, per-worktree.
+.testmondata
+.testmondata-journal
+"""
+
+SDLC_PHASE_TEMPLATE = """\
+version: "1.0"
+current_phase: alpha
+phases:
+  - name: alpha
+    exit_criteria:
+      - id: E001
+        description: "Core functionality implemented"
+        check: manual
+        status: pending
+"""
+
+DECOMPOSITION_TEMPLATE = """\
+# Strategy Decomposition
+
+## How the Objective Breaks Down
+
+[Explain how the program objective decomposes into modules and why.]
+
+## Module Dependency Order
+
+1. [module-a] — [reason]
+2. [module-b] — depends on module-a
+
+## Inter-Module Contracts
+
+[Describe what each module provides to others.]
+"""
+
+MODULE_SPEC_TEMPLATE = """\
+version: "1.0"
+module: {name}
+description: "What this module does (10 words minimum)."
+objective_coverage:
+  - "Which part of objective.md this covers"
+dependencies: []
+constraints:
+  - "List constraints here"
+"""
+
+MODULE_ACCEPTANCE_TEMPLATE = """\
+version: "1.0"
+module: {name}
+criteria:
+  # ── Modularity criteria (generated by pcp init — do not remove) ──────────
+  - id: MOD_A001
+    description: "Module can be removed without breaking other modules (drop test)"
+    check: test_passes
+    test: "tests/modularity/test_drop_{name}.sh"
+    notes: "Temporarily disable module, run full test suite of other modules — must pass"
+    status: pending
+
+  - id: MOD_A002
+    description: "Module registers through application interface, not via direct import"
+    check: ast_pattern
+    target: "src/main"
+    pattern: "register\\\\({name}\\\\)|plugin\\\\({name}\\\\)|mount\\\\({name}\\\\)"
+    status: pending
+
+  - id: MOD_A003
+    description: "Module has a feature flag (FEATURE_{name_upper}_ENABLED), default false"
+    check: file_exists
+    target: "src/modules/{name}/feature_flag.env"
+    status: pending
+
+  - id: MOD_A004
+    description: "Module interface file exists and defines typed public surface"
+    check: file_exists
+    target: "src/interfaces/I{name_pascal}.ts"
+    status: pending
+
+  # ── Implementation criteria (add yours below) ─────────────────────────────
+  - id: A001
+    description: "Core implementation exists"
+    check: manual
+    status: pending
+"""
+
+ARCHITECT_PERSONA_TEMPLATE = """\
+# Architect Persona
+
+## Core Philosophy
+
+Every module is a guest in the codebase. It can leave without drama.
+It can arrive without surgery. Nothing else should know about it
+except the application registry.
+
+Vibe coders pivot. Architecture must absorb pivots without surgery.
+Modularity is not a preference — it is a hard constraint.
+
+## Modularity Invariants (always enforced, not project-specific)
+
+BLOCK:
+- Any direct import of another module's `src/` directory from outside that module
+- Any module that imports from another module except through the `interfaces/` contract
+- Any global mutable state shared between modules (singleton patterns, global stores)
+- Any module that directly instantiates another module (use dependency injection via registry)
+- Feature code shipped without a feature flag (`FEATURE_<MODULE>_ENABLED`)
+- A module whose tests require another module to be present (tests must be isolated)
+- Circular module dependencies (A depends on B depends on A)
+
+WARN:
+- A module with more than 3 entries in its `dependencies:` field (God module risk)
+- A module that owns more than 3 database tables (God module risk)
+- A module that directly modifies another module's database tables
+- A non-trivial module (auth, payment, queue, scheduler, parser, embeddings,
+  state-machine, ETL-class complexity, OR a mature UI subsystem — canvas/
+  diagram editor, rich text editor, spreadsheet grid, drag-drop builder)
+  scaffolded with no prior-art check logged in `.pcp/decision_log.jsonl` —
+  run `/priorart <description>` first and record reuse-as-dependency /
+  fork-adapt / reference-pattern-only / build-fresh + license rationale
+  before building
+
+## Project-Specific Principles
+
+BLOCK:
+- [Add project-specific hard constraints here]
+- Example: "No direct database calls outside repository layer"
+- Example: "All external API calls go through a dedicated client module"
+
+WARN:
+- [Add project-specific design smells]
+- Example: "Missing error boundary at integration points"
+- Example: "Synchronous calls to external APIs without timeout"
+
+## What I'm Lenient About
+
+- [Things explicitly out of scope for this phase]
+- Example: "Test coverage % in alpha phase"
+- Example: "Internal naming conventions within a module (each module owns its internals)"
+
+## Review Output
+Rate each finding: BLOCK | WARN | NOTE
+BLOCK = must fix before merge
+WARN  = fix before ship
+NOTE  = track, non-blocking
+"""
+
+DESIGN_SYSTEM_TEMPLATE = """\
+# Design System
+
+_Empty scaffold. Filled in by the `pcp-ui-design` skill the first time a UI-facing
+acceptance criterion is implemented -- not hand-written up front, since the right
+tokens depend on the product's actual domain, not a generic guess made before any
+real screen exists. See `~/.claude/skills/pcp-ui-design/SKILL.md`._
+
+_Real gap this exists to prevent: each UI-facing criterion built independently by a
+fresh agent session, with no shared design memory, produces a different vanilla-
+default look per screen. Once this file has real content, every later screen reads
+it and reuses the same system instead of deciding fresh._
+
+## Color
+
+(not yet established)
+
+## Type
+
+(not yet established)
+
+## Layout Conventions
+
+(not yet established)
+
+## Component Notes
+
+(grows over time -- a new reusable pattern gets recorded here whenever a screen establishes one)
+"""
+
+PCP_CLAUDE_BLOCK_START = "<!-- PCP:BEGIN — auto-managed by `pcp init`, do not hand-edit this block -->"
+PCP_CLAUDE_BLOCK_END = "<!-- PCP:END -->"
+
+PCP_CLAUDE_BLOCK_BODY = """\
+# PCP Governance (this project is PCP-managed)
+
+This project uses PCP (Program Context Protocol). Every session — new or
+resumed — is governed by `.pcp/`. Read the relevant files before acting;
+do not restate or duplicate their content here.
+
+## There is one track, not two
+
+There is no "just chatting" mode separate from "the PCP track" in this
+project. Whether the human is describing a bug, debating architecture,
+correcting scope, or typing `/pcp` explicitly — you are the PCP PM for this
+conversation, always, by default. A business-level statement made in casual
+conversation is exactly as real as one made inside a formal PM workflow; it
+does not become governed only once someone remembers to invoke a skill.
+
+Concretely, in any conversation on this project:
+- If something stated changes what should be built (scope, priority, a
+  correction to prior direction) — even said in passing — that is a PM-track
+  event. Reflect it into `.pcp/` in the same turn, don't defer it: run
+  `pcp capture` against the live session (or note the item directly) so it
+  lands in `brd_items.yaml`/`decision_log.jsonl`.
+- If it contradicts `.pcp/objective.md` or `target_state.md`'s actual text,
+  say so plainly and either run `pcp correct-objective "<correction>"` (human
+  approves the real diff) right then, or explicitly tell the human the spec
+  is now stale and must be corrected before you treat any later "go ahead"
+  as build authorization. Never let a stale objective sit undetected while
+  the conversation moves on to something else — see `pcp objective-conflicts`
+  (CTRL-035; also enforced as a hard block inside `pcp build` itself).
+- Do not wait for an explicit `/pcp` invocation to apply this — it is the
+  default posture for every conversation in a PCP-managed project, not an
+  opt-in mode.
+
+(2026-07-22 incident: a business correction was discussed and agreed, nothing
+in that conversation treated it as PM-track, `objective.md` was never
+rewritten, and a full build cycle two days later built exactly the rejected
+thing. This section exists because that gap was real, not hypothetical.)
+
+## Read first, every session
+
+- `.pcp/objective.md` — WHY this program exists. Immutable.
+- `.pcp/target_state.md` — WHAT done looks like.
+- `.pcp/architecture.md` — tech decisions + constraints.
+- `.pcp/architect_persona.md` — modularity + review rules.
+- `.pcp/current_state.md` — auto-generated reality snapshot.
+- `.pcp/diff.md` — auto-computed gap vs target.
+- `.pcp/strategy/decomposition.md` and `.pcp/strategy/modules/*/spec.yaml` — module specs.
+
+## Hard rules (non-negotiable, all sessions)
+
+1. **Spec files are human-APPROVED only** — `objective.md`, `target_state.md`,
+   `architecture.md`, `strategy/decomposition.md`, `strategy/dependency_map.md`,
+   `ci_rules.yaml`, `controls.yaml`, `SDLC_phase.yaml`, `modules/*/spec.yaml`,
+   `modules/*/acceptance.yaml`.
+   **Approved, not hand-typed.** A tool proposes the change, you review a real
+   diff, you approve, then it is written. An agent must never write one unattended, and
+   `pcp build`'s coding agent is hard-blocked from all of them. But when a human
+   is in the session and asks for a spec update, do it — via the gated command
+   for that file, which shows a real diff and requires approval before writing:
+
+   | File | Command |
+   |---|---|
+   | `objective.md`, `target_state.md` | `pcp correct-objective "<correction>"` |
+   | `modules/*/spec.yaml`, `acceptance.yaml` | `pcp pm "<intent>"` |
+   | everything else above | `pcp amend <file> "<change>"` |
+
+   Refusing to update a spec because it is "human-written" is a bug, not
+   compliance. The only wrong move is writing one without a diff and approval.
+2. **`current_state.md` is always auto-generated** by `pcp scan`. Never
+   hand-write it.
+3. **`diff.md` is always auto-computed** by `pcp diff`. Never edit it.
+4. **Modularity is a hard constraint** — every module is a guest; it can
+   leave without drama and arrive without surgery. No direct cross-module
+   `src/` imports, no shared global mutable state, no module without a
+   feature flag and an `interfaces/` contract. See `ci_rules.yaml` MOD_001-005.
+5. Before committing, run `pcp check` (Layer 1). Before a PR, `pcp gate`
+   (Layer 2, advisory). Before deploy, `pcp deploy-check` (Layer 3, hard).
+   Bypass only via `[pcp-bypass: reason]` in the commit message — it is
+   logged to `bypass_log.yaml`, never silent.
+6. If work here changes program strategy (drop/add a module, change
+   objective coverage), run `pcp validate-strategy` before proceeding.
+7. Before scaffolding a non-trivial module (auth, payment, queue, scheduler,
+   parser, embeddings, state-machine, ETL-class complexity — OR a mature UI
+   subsystem: canvas/diagram editor, rich text editor, spreadsheet grid,
+   drag-drop builder), run `/priorart <description>` first — check for
+   existing projects to reuse, fork, or reference before building from
+   scratch. Log the decision (reuse-as-dependency / fork-adapt /
+   reference-pattern-only / build-fresh + license) via `pcp capture` so it
+   lands in `.pcp/decision_log.jsonl`. Skip for trivial modules (helpers,
+   config parsers, glue code).
+
+## Session start checklist
+
+1. Read `.pcp/current_state.md` and `.pcp/diff.md` to know what's actually
+   built vs. what's left — don't assume from memory or git log alone.
+2. Read `.pcp/pcp.md` if present — it's the human-facing status rollup.
+3. If mid-build, check `.pcp/telemetry.jsonl` (or run `pcp telemetry`) for
+   prior attempt history on the current module before retrying.
+"""
+
+
+def render_pcp_claude_block() -> str:
+    return f"{PCP_CLAUDE_BLOCK_START}\n{PCP_CLAUDE_BLOCK_BODY}{PCP_CLAUDE_BLOCK_END}"
+
+
+def upsert_pcp_claude_block(claude_md_path: Path) -> bool:
+    """Insert or refresh the PCP governance block in a project's CLAUDE.md.
+
+    Preserves any human-authored content outside the marker pair. Returns
+    True if the file was created or changed.
+    """
+    block = render_pcp_claude_block()
+    if not claude_md_path.exists():
+        claude_md_path.parent.mkdir(parents=True, exist_ok=True)
+        claude_md_path.write_text(block + "\n")
+        return True
+
+    existing = claude_md_path.read_text()
+    if PCP_CLAUDE_BLOCK_START in existing and PCP_CLAUDE_BLOCK_END in existing:
+        pre = existing.split(PCP_CLAUDE_BLOCK_START)[0]
+        post = existing.split(PCP_CLAUDE_BLOCK_END)[1]
+        new_content = pre + block + post
+    else:
+        new_content = (existing.rstrip("\n") + "\n\n" + block + "\n") if existing.strip() else block + "\n"
+
+    if new_content == existing:
+        return False
+    claude_md_path.write_text(new_content)
+    return True
+
+
+ADR_EXAMPLE = """\
+# ADR-001: [Short Title]
+
+## Status
+Accepted | Superseded | Deprecated
+
+## Context
+[Why this decision was needed]
+
+## Decision
+[What was decided]
+
+## Rationale
+[Why this option over alternatives]
+
+## Consequences
+[What this enables. What it constrains.]
+"""
+
+POLICY_ESCALATION_TEMPLATE = """\
+package pcp.escalation
+
+# Confidence/stakes-gated routing: PCP's own asymmetric-failure-cost
+# principle (never silently treat "unsure" as "safe to automate") --
+# low confidence or an explicitly high-stakes action always escalates to
+# a human rather than resolving through the agent by default.
+
+default route := "agent"
+
+route := "human" if input.confidence_score < 0.65
+route := "human" if input.high_stakes == true
+"""
+
+POLICY_BYPASS_TEMPLATE = """\
+package pcp.bypass
+
+# Formalizes what ci_rules.yaml's [pcp-bypass: reason] mechanism treats as
+# ad-hoc otherwise -- rejects placeholder reasons before pcp check treats
+# a reason as adequate to log and accept a Layer 1 bypass.
+
+default approved := false
+
+approved if {
+	count(trim_space(input.reason)) > 0
+	not lower(trim_space(input.reason)) in {"reason", "todo", "test", "fixme"}
+}
+"""
+
+POLICY_DEPLOY_TEMPLATE = """\
+package pcp.deploy
+
+# Deploy-time policy (Harness policy-gate reference pattern, 2026-07-17).
+# Consulted by `pcp deploy` before the approval prompt. All rules
+# human-editable; a missing/failed OPA evaluation NEVER blocks a deploy
+# (advisory layer, same posture as escalation.rego).
+
+# Freeze windows: block deploys on listed UTC weekdays (0=Mon..6=Sun).
+# Default: no frozen days. Example: freeze_days := {4, 5, 6} freezes Fri-Sun.
+freeze_days := set()
+
+deny contains msg if {
+    input.utc_weekday in freeze_days
+    msg := sprintf("deploy freeze window: weekday %d is frozen", [input.utc_weekday])
+}
+
+# Require rollback configured for any deploy touching risk-flagged criteria.
+deny contains msg if {
+    input.risk_flag_count > 0
+    not input.rollback_configured
+    msg := "risk-flagged release with no rollback command configured — configure one via pcp doctor"
+}
+"""
+
+UI_KIT_RECIPES_TEMPLATE = """\
+version: "1.0"
+
+# PCP's UI building-blocks layer, added 2026-07-20. PCP does NOT build or
+# maintain UI component code -- that's a solved problem (shadcn/ui on Base
+# UI primitives: MIT, copy-paste-vendored per project via `npx shadcn add
+# <name>`, official MCP server for search/retrieval, already the dominant
+# stack among AI UI-generation tools). Verified current as of 2026-07-20 --
+# re-check ui.shadcn.com/docs/components before trusting these names if
+# this file is old; shadcn's own catalog evolves (toast -> sonner already
+# happened once).
+#
+# What PCP owns instead: which organisms an archetype needs (the recipe),
+# where to look for evidence they were actually used (import_path_hint,
+# consumed by build.py's CTRL-028), and how organisms combine into a screen
+# (the rules below). See CLAUDE.md's "UI Building Blocks" section for the
+# full rationale -- this is the build-vs-buy decision recorded there.
+kit: shadcn
+
+# organism -> where its evidence is expected to live. import_path_hint is a
+# SUBSTRING match against a criterion's target file, not an exact resolver
+# (no tsconfig-paths parsing) -- a real re-export/alias can legitimately
+# not match, so CTRL-028 treats a miss as advisory, not proof of non-use.
+# component: null means shadcn has no single installable primitive for
+# this organism -- it's a documented HAND-ASSEMBLED pattern (shadcn's own
+# docs say so explicitly for data-table and form), composed from the
+# primitives listed in the comment. import_path_hint still anchors on the
+# closest real primitive so the check has *something* concrete to look for.
+organisms:
+  primary-nav:
+    component: "sidebar"
+    import_path_hint: "components/ui/sidebar"
+    position: "top bar or left rail"
+  data-table:
+    component: null   # composed: `table` primitive + TanStack Table, per shadcn's own docs -- not a single install
+    import_path_hint: "components/ui/table"
+    position: "main content, below filters"
+  filter-bar:
+    component: null   # composed: input + select, no single shadcn primitive
+    import_path_hint: "components/ui/input"
+    position: "top of content, above the table"
+  modal:
+    component: "dialog"
+    import_path_hint: "components/ui/dialog"
+    position: "centered overlay"
+  toast:
+    component: "sonner"   # NOT "toast" -- shadcn deprecated its own toast component in favor of sonner
+    import_path_hint: "components/ui/sonner"
+    position: "top-right or bottom-center, transient"
+  status-badge:
+    component: "badge"
+    import_path_hint: "components/ui/badge"
+    position: "inline, next to the item it describes"
+  kpi-tile:
+    component: "card"
+    import_path_hint: "components/ui/card"
+    position: "top row of a dashboard"
+  chart-panel:
+    component: "chart"
+    import_path_hint: "components/ui/chart"
+    position: "main content area"
+  form-field-group:
+    component: null   # composed: field/label primitives + react-hook-form, per shadcn's own docs -- not a single install
+    import_path_hint: "components/ui/field"
+    position: "main content, vertical stack"
+  search-box:
+    component: "input"
+    import_path_hint: "components/ui/input"
+    position: "top-left or top-center of content"
+  empty-state:
+    component: "empty"
+    import_path_hint: "components/ui/empty"
+    position: "fills the content area it replaces"
+  comment-thread:
+    component: null   # composed: card + avatar + textarea, genuinely custom -- no anchor primitive close enough to check
+    import_path_hint: null
+    position: "right rail or bottom panel"
+
+# screen_archetype -> required ui_organisms (the recipe CTRL-028 checks
+# completeness against). canvas_editor deliberately has none -- it triggers
+# /priorart per the existing global Prior-Art Check rule instead of a
+# prescribed recipe (a diagram/canvas editor is its own mature-tool
+# decision, not a shadcn-organism composition).
+archetypes:
+  dashboard: ["kpi-tile", "chart-panel", "data-table"]
+  data_entry_form: ["form-field-group"]
+  list_table: ["data-table", "filter-bar", "empty-state"]
+  detail_view: ["kpi-tile"]
+  search_filter: ["search-box", "filter-bar", "empty-state"]
+  settings: ["form-field-group"]
+  chat: ["comment-thread"]
+  canvas_editor: []
+  wizard: ["form-field-group"]
+  auth: ["form-field-group"]
+
+# Composition rules -- documented here for the build agent to read; not yet
+# separately enforced by their own CTRL (recipe-completeness + import-
+# verification above are what CTRL-028 actually checks). Promote a rule to
+# its own deterministic check if/when one proves worth enforcing on its own.
+rules:
+  max_primary_actions_per_screen: 1
+  require_empty_state_for: ["data-table", "chat"]
+  require_confirmation_for_destructive_actions: true
+"""
+
+DESIGN_CONVENTIONS_TEMPLATE = """\
+version: "1.0"
+
+# UI archetype -- what KIND of product this is, for conventions that only
+# apply to some archetypes (a File/Edit/View menu bar is a desktop-app
+# convention; a SaaS dashboard or mobile-style portal has no reason to have
+# one). Default web_app: the menu-bar check below stays inert until a human
+# deliberately opts a project into a different archetype.
+#
+# One of: web_app | desktop_app | mobile | cli
+ui_archetype: web_app
+
+# Only enforced (deterministic substring scan, no LLM) when ui_archetype is
+# desktop_app -- CTRL-027 in build.py's wave-merge. Advisory, warn-first,
+# same rollout posture as every other check in this catalog.
+top_menu_bar:
+  required_menus: ["File", "Edit", "View", "Help"]
+"""
+
+POLICY_TIER_DISTRIBUTION_TEMPLATE = """\
+package pcp.tier_distribution
+
+# Logic-tier distribution bands (2026-07-18). How much of the product is
+# allowed to live at rung 6 (LLM, nondeterministic) before validate-strategy
+# colors the mix yellow/red? Advisory only -- this encodes a team's
+# predictability budget, human-editable here instead of buried in Python.
+# Defaults mirror validate_strategy.py's fallback bands.
+
+color := "green" if input.rung6_share <= 0.35
+else := "yellow" if input.rung6_share <= 0.6
+else := "red"
+"""
+
+POLICY_COUPLING_TEMPLATE = """\
+package pcp.coupling
+
+# Mirrors validate_strategy.py's display thresholds (green >= 0.8,
+# yellow >= 0.6, else red) -- human-editable here instead of buried in
+# Python.
+
+coupling_color := "green" if input.coupling_score >= 0.8
+else := "yellow" if input.coupling_score >= 0.6
+else := "red"
+"""
+
+DOMAIN_KB_TEMPLATE = """\
+# Domain Knowledge: [Technology/Area]
+
+## Known Failure Modes
+
+- [Pattern that causes bugs in this domain]
+
+## Invariants
+
+- [Things that must always be true]
+
+## Gotchas
+
+- [Non-obvious behaviours or edge cases]
+"""
+
+
+def _write(path: Path, content: str, force: bool) -> bool:
+    if path.exists() and not force:
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+    return True
+
+
+RECOMMENDED_PERMISSIONS_TEMPLATE = """\
+# Recommended Claude Code Permissions for PCP
+
+Found the hard way, once: an agent correcting a spec/target-path drift issue in
+`.pcp/` one file at a time (via the Edit tool) is exactly the kind of routine,
+low-risk PCP maintenance that still triggers a permission prompt on every
+single file under Claude Code's default settings. Pre-approving it narrows the
+friction to just this one path, not a blanket edit allowance.
+
+**This is advisory, not applied automatically** -- PCP does not (and will not)
+edit `.claude/settings.json` itself. Review the snippet below and merge it
+into your own `.claude/settings.json` or `.claude/settings.local.json` if you
+want it.
+
+## Recommended: allow edits under `.pcp/`
+
+```json
+{
+  "permissions": {
+    "allow": ["Edit(/.pcp/**)"]
+  }
+}
+```
+
+Narrower alternative, if you'd rather scope it to just spec/acceptance files
+instead of all of `.pcp/`:
+
+```json
+{
+  "permissions": {
+    "allow": ["Edit(/.pcp/strategy/modules/**/spec.yaml)", "Edit(/.pcp/strategy/modules/**/acceptance.yaml)"]
+  }
+}
+```
+
+## Optional: `acceptEdits` permission mode
+
+For a session dedicated to PCP spec maintenance specifically (not general
+coding), consider switching that session to `acceptEdits` mode instead of
+adding the rule above project-wide. Session-scoped, reverts when the session
+ends -- a good fit if this kind of correction is occasional rather than
+routine for your workflow.
+
+## If you use a `git branch -D` deny rule
+
+PCP's own worktree/branch-reset code (`pcp build`'s parallel module builds,
+and any PCP-provided demo/setup scripts) uses the non-destructive
+`git checkout -B <branch> <start-point>` form, never `git branch -D` --
+a standing deny rule on `-D` will not conflict with anything PCP itself does.
+
+## Optional: keep CLAUDE.md's PCP context block fresh via a SessionStart hook
+
+`pcp context --inject` writes a marked block into CLAUDE.md (objective,
+architecture, current state, pending gaps) -- Claude Code reads CLAUDE.md
+every session regardless, but nothing calls `pcp context --inject` for you.
+If you want that block to stay current automatically instead of running it
+by hand, add a `SessionStart` hook:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {"hooks": [{"type": "command", "command": "pcp context --inject --path \\"$CLAUDE_PROJECT_DIR\\""}]}
+    ]
+  }
+}
+```
+
+Same posture as everything else in this file: advisory, not applied by PCP itself.
+
+## Optional: real-time build-loop warning (2026-07-24)
+
+`.pcp/hooks/build_loop_warning.py` fires the moment an Edit/Write happens
+outside `pcp build`'s own gated agent loop -- a real-time companion to
+CTRL-037 (`pcp doctor`), which only catches this in retrospect. Purely
+informational: never sets a permission decision, so it can't block or force
+an "ask" prompt, one warning per session. To enable:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {"matcher": "Edit|Write", "hooks": [{"type": "command", "command": "python3 .pcp/hooks/build_loop_warning.py"}]}
+    ]
+  }
+}
+```
+
+## Optional: PCP update-available notice at session start (2026-07-31)
+
+`.pcp/hooks/session_update_check.py` runs `pcp self-update --check` (fetch +
+compare, read-only) at the start of a session and prints a one-line notice
+if a newer PCP is available. It never pulls anything itself -- updating
+always stays a separate, explicit `pcp self-update`. To enable:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {"hooks": [{"type": "command", "command": "python3 .pcp/hooks/session_update_check.py"}]}
+    ]
+  }
+}
+```
+"""
+
+
+def _write_permission_recommendations(root: Path, force: bool) -> Path | None:
+    """Advisory only -- writes a recommendation file, never touches
+    .claude/settings.json itself (that edit is permanently off-limits for an
+    agent to make on a human's behalf, confirmed the hard way: Claude Code's
+    own permission layer hard-blocks an agent wiring anything into its own
+    settings.json, even a narrow, clearly-scoped addition). Surfacing this at
+    `pcp init` time means a new PCP user sees it on day one, instead of
+    discovering it painfully after hitting the exact friction it describes --
+    which is how this file's own content was originally found."""
+    path = root / ".pcp" / "RECOMMENDED_PERMISSIONS.md"
+    if _write(path, RECOMMENDED_PERMISSIONS_TEMPLATE, force):
+        return path
+    return None
+
+
+@click.command()
+@click.option("--path", "project_path", type=click.Path(), default=".",
+              help="Project root (default: current directory).")
+@click.option("--module", "module_name", default=None,
+              help="Also scaffold a module under strategy/modules/<name>/.")
+@click.option("--force", is_flag=True, help="Overwrite existing files.")
+def init(project_path: str, module_name: str | None, force: bool):
+    """Scaffold .pcp/ directory in a project."""
+    root = Path(project_path).resolve()
+    pcp = root / ".pcp"
+
+    files = {
+        pcp / "objective.md": OBJECTIVE_TEMPLATE,
+        pcp / "target_state.md": TARGET_STATE_TEMPLATE,
+        pcp / "architecture.md": ARCHITECTURE_TEMPLATE,
+        pcp / "ci_rules.yaml": CI_RULES_TEMPLATE,
+        pcp / "controls.yaml": CONTROLS_TEMPLATE,
+        pcp / "SDLC_phase.yaml": SDLC_PHASE_TEMPLATE,
+        pcp / "strategy" / "decomposition.md": DECOMPOSITION_TEMPLATE,
+        pcp / "architect_persona.md": ARCHITECT_PERSONA_TEMPLATE,
+        pcp / "design_system.md": DESIGN_SYSTEM_TEMPLATE,
+        pcp / "kb" / "adr" / "ADR-001-example.md": ADR_EXAMPLE,
+        pcp / "kb" / "domain" / "general.md": DOMAIN_KB_TEMPLATE,
+        pcp / "policies" / "escalation.rego": POLICY_ESCALATION_TEMPLATE,
+        pcp / "policies" / "bypass_approval.rego": POLICY_BYPASS_TEMPLATE,
+        pcp / "policies" / "coupling_threshold.rego": POLICY_COUPLING_TEMPLATE,
+        pcp / "policies" / "deploy_policy.rego": POLICY_DEPLOY_TEMPLATE,
+        pcp / "hooks" / "pretooluse_guard.sh": PRETOOLUSE_GUARD_TEMPLATE,
+        pcp / "hooks" / "build_loop_warning.py": BUILD_LOOP_WARNING_TEMPLATE,
+        pcp / "hooks" / "session_update_check.py": SESSION_UPDATE_CHECK_TEMPLATE,
+        pcp / "policies" / "tier_distribution.rego": POLICY_TIER_DISTRIBUTION_TEMPLATE,
+        pcp / "logic_tier_guide.md": LOGIC_TIER_GUIDE_TEMPLATE,
+        pcp / "context_map.yaml": CONTEXT_MAP_TEMPLATE,
+        pcp / "design_conventions.yaml": DESIGN_CONVENTIONS_TEMPLATE,
+        pcp / "ui_kit_recipes.yaml": UI_KIT_RECIPES_TEMPLATE,
+    }
+
+    if module_name:
+        mod_dir = pcp / "strategy" / "modules" / module_name
+        files[mod_dir / "spec.yaml"] = MODULE_SPEC_TEMPLATE.format(name=module_name)
+        files[mod_dir / "acceptance.yaml"] = MODULE_ACCEPTANCE_TEMPLATE.format(
+            name=module_name, name_upper=module_name.upper(), name_pascal=_pascal_case(module_name),
+        )
+
+    created = []
+    skipped = []
+    for path, content in files.items():
+        if _write(path, content, force):
+            created.append(path.relative_to(root))
+        else:
+            skipped.append(path.relative_to(root))
+
+    for p in created:
+        console.print(f"  [green]created[/green]  {p}")
+    for p in skipped:
+        console.print(f"  [dim]skipped[/dim]  {p}  (exists, use --force to overwrite)")
+
+    claude_md = root / "CLAUDE.md"
+    if upsert_pcp_claude_block(claude_md):
+        console.print(f"  [green]updated[/green]  CLAUDE.md  (PCP governance block)")
+    else:
+        console.print(f"  [dim]unchanged[/dim]  CLAUDE.md  (PCP governance block already current)")
+
+    gitattributes = root / ".gitattributes"
+    ga_lines = [
+        ".pcp/current_state.md merge=ours",
+        ".pcp/diff.md merge=ours",
+        ".pcp/bypass_log.yaml merge=union",
+    ]
+    existing = gitattributes.read_text() if gitattributes.exists() else ""
+    additions = [l for l in ga_lines if l not in existing]
+    if additions:
+        with open(gitattributes, "a") as f:
+            f.write("\n" + "\n".join(additions) + "\n")
+        console.print(f"  [green]updated[/green]  .gitattributes")
+
+    # Layer 1 enforcement wired up automatically, not left as a manual step a
+    # human could forget -- "this project has .pcp/" and "this project is
+    # actually governed" used to be two separate facts. Cron side effects
+    # (global intervention aggregation, skill upgrade check) deliberately
+    # NOT included here -- see install_git_hook()'s own docstring.
+    from pcp.commands.install_hook import install_git_hook
+    hook_installed, hook_msg = install_git_hook(root)
+    if hook_installed:
+        console.print(f"  [green]installed[/green]  commit-msg hook  ({hook_msg})")
+    else:
+        console.print(f"  [dim]hook not installed[/dim]  ({hook_msg})")
+
+    perms_path = _write_permission_recommendations(root, force)
+    if perms_path:
+        console.print(f"  [green]written[/green]  {perms_path.relative_to(root)}  (advisory -- not applied automatically)")
+
+    # Build-artifact .gitignore, only when the project has none at all.
+    # Found dogfooding 2026-07-17 (round 4): a kickoff-scaffolded project with
+    # no .gitignore let build agents commit __pycache__/*.pyc alongside their
+    # work, and the parallel-module worktree merge then aborted on "local
+    # changes would be overwritten" — by bytecode files. Never appends to or
+    # modifies an existing .gitignore (that's the human's file).
+    gitignore_path = root / ".gitignore"
+    if not gitignore_path.exists():
+        gitignore_path.write_text(GITIGNORE_TEMPLATE)
+        console.print("  [green]written[/green]  .gitignore  (build-artifact patterns)")
+
+    console.print(f"\n[bold]PCP initialised at {pcp}[/bold]")
+    if perms_path:
+        console.print(
+            f"[dim]Recommended Claude Code permission rules written to {perms_path.relative_to(root)} -- "
+            "review and merge into your own .claude/settings.json if you want fewer per-edit prompts "
+            "when PCP corrects spec/target-path drift.[/dim]"
+        )
+    console.print("\nNext steps:")
+    console.print("  1. Edit [cyan].pcp/objective.md[/cyan] — describe WHY this program exists")
+    console.print("  2. Edit [cyan].pcp/strategy/decomposition.md[/cyan] — break objective into modules")
+    console.print("  3. Run [cyan]pcp init --module <name>[/cyan] for each module")
+    console.print("  4. Run [cyan]pcp validate-strategy[/cyan] to check coverage")
+    console.print("  5. Edit [cyan].pcp/architect_persona.md[/cyan] — define architecture principles")
+    console.print("  6. Add ADRs to [cyan].pcp/kb/adr/[/cyan] — document architecture decisions")
+    console.print("  7. Run [cyan]pcp architect-review[/cyan] — review changes against persona")