pact-agents 0.1.0__tar.gz

pact_agents-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pact_agents-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project runtime state (generated per-project, not checked in)
+.pact/
+
+# Secrets
+.env
+*.key
+*.pem

pact_agents-0.1.0/CLAUDE.md

@@ -0,0 +1,240 @@
+# CLAUDE.md -- Pact
+
+Contract-first multi-agent software engineering. Decomposition produces contracts and tests, not code. Black-box implementations verified by functional tests at boundaries. Recursive composition.
+
+## Quick Reference
+
+```bash
+cd ~/WanderRepos/pact
+python3 -m pytest tests/ -v        # Run all tests
+pact init <project-dir>            # Initialize project
+pact status <project-dir>          # Show state
+pact components <project-dir>      # List components
+pact build <project-dir> <id>      # Build specific component
+pact run <project-dir>             # Execute pipeline
+pact tasks <project-dir>           # Generate/display task list
+pact analyze <project-dir>         # Cross-artifact analysis
+pact checklist <project-dir>       # Requirements quality checklist
+pact export-tasks <project-dir>    # Export TASKS.md
+pact directive <project-dir> <json> # Send structured directive to daemon
+```
+
+**Entry point**: `pact = "pact.cli:main"` (pyproject.toml)
+
+**Python**: >=3.12 | **Dependencies**: pydantic>=2.0, pyyaml>=6.0 | **Optional**: anthropic>=0.40
+
+## Architecture Overview
+
+### Research-First Agent Protocol
+
+Every agent follows 3 phases: Research -> Plan+Evaluate -> Execute. Research and plan outputs are persisted alongside work products.
+
+### Core Workflow
+
+1. **Interview** -- System reads task+SOPs, identifies risks/ambiguities, asks user clarifying questions
+2. **Shape** -- (Optional) Produce a Shape Up pitch: appetite, breadboard, rabbit holes, no-gos
+3. **Decompose** -- Task -> DecompositionNode tree (2-7 components), guided by shaping context
+3. **Contract** -- For each component (leaves first), generate ComponentContract
+4. **Test** -- For each contract, generate ContractTestSuite with executable tests
+5. **Validate** -- Mechanical gate: all refs resolve, no cycles, test code parses
+6. **Implement** -- Each component independently by code_author agent, verified by contract tests
+7. **Integrate** -- Parent components: glue code wiring children, parent-level tests
+8. **Diagnose** -- On failure: I/O tracing, systematic error recovery
+
+### Execution Modes
+
+Two independent levers:
+- `parallel_components: true` -- Independent leaves implement concurrently (semaphore-limited)
+- `competitive_implementations: true` -- N agents implement same component, best wins
+- `plan_only: true` -- Stop after contracts, use `pact build` to target specific nodes
+- `max_concurrent_agents: 4` -- Concurrency limit for parallel modes
+
+### Build Modes
+
+Three build modes control decomposition behavior:
+
+```yaml
+# pact.yaml
+build_mode: auto    # unary | auto | hierarchy
+```
+
+- **unary**: Single agent session. Skips LLM decomposition, creates one component with the full task. Still produces contract+tests for verification.
+- **auto** (default): LLM decides whether to decompose or implement directly. Improved prompts genuinely encourage `is_trivial=true` for straightforward tasks.
+- **hierarchy**: Always decompose into multiple components (previous default behavior).
+
+Project config overrides global config. Set at runtime via directive:
+```bash
+pact directive ./my-proj '{"type": "set_mode", "mode": "unary"}'
+```
+
+### Global Standards
+
+After decomposition, pact automatically collects shared conventions from contracts:
+- Shared types (appearing in 2+ contracts)
+- Common validator patterns
+- Package requirements
+- Coding conventions from SOPs
+
+Standards are injected into every agent's handoff brief and persisted at `.pact/standards.json`.
+
+### Production Monitoring & Auto-Remediation
+
+Opt-in (`monitoring_enabled: true`). Pact-generated code embeds `PACT:<project_hash>:<component_id>` log keys. The Sentinel watches log files, processes, and webhooks for errors, attributes them to components via log keys (or LLM triage), and spawns knowledge-flashed fixer agents that add a reproducer test and rebuild the black box. Multi-window budget caps (per-incident/hourly/daily/weekly/monthly) prevent runaway spend.
+
+**Narrative retry**: On retry attempts, the remediator carries forward prior failures, test results, research reports, and plan evaluations — matching the `implementer.py` pattern. A heroic narrative reframe ("senior engineer brought in because the previous approach failed") prevents the model from falling into the same reasoning rut. `build_narrative_debrief()` is a pure, testable function.
+
+**Budget hypervisor**: `estimate_tokens()` provides content-aware token estimation (symbol ratio → chars/token: 3.5 for code, 4.5 for prose). `record_tokens_validated()` cross-validates reported vs estimated counts using `max()` for conservative accounting. The `claude_code` backend no longer falls back to `len(text) // 4`. The `claude_code_team` backend now tracks spend via estimation.
+
+### Casual-Pace Scheduling
+
+Poll-based, not event-loop. Agents invoked for focused bursts, state fully persisted between bursts.
+
+## Source Layout
+
+```
+src/pact/
+  schemas.py           # All Pydantic models
+  schemas_shaping.py   # Shaping phase models (ShapingPitch, Breadboard, etc.)
+  pitch_utils.py       # Pitch summary, formatting, handoff context
+  contracts.py         # Contract validation (mechanical gates)
+  test_harness.py      # Functional test execution
+  design_doc.py        # Living design document
+  decomposer.py        # Task -> Contracts workflow
+  implementer.py       # Contract -> Code workflow (parallel + competitive)
+  integrator.py        # Composition + I/O tracing (parallel depth groups)
+  resolution.py        # Competitive resolution (score, pick winner)
+  diagnoser.py         # Error recovery
+  scheduler.py         # Casual-pace polling + component targeting
+  project.py           # Project directory lifecycle + attempt storage
+  config.py            # GlobalConfig + ProjectConfig + ParallelConfig
+  budget.py            # Per-project spend tracking + content-aware token estimation
+  lifecycle.py         # Run state machine
+  daemon.py            # Event-driven FIFO-based coordinator
+  interface_stub.py    # Interface stub generation + log key preamble
+  standards.py         # Global standards collection + rendering
+  cli.py               # CLI entry points
+
+  # Spec-kit capabilities (task list, analysis, checklist)
+  schemas_tasks.py     # Task list, analysis, checklist Pydantic models
+  task_list.py         # Task list generation + rendering (mechanical, no LLM)
+  analyzer.py          # Cross-artifact consistency analysis (mechanical)
+  checklist_gen.py     # Requirements quality checklist generation (mechanical)
+
+  # Monitoring subsystem
+  schemas_monitoring.py # Monitoring models (Signal, Incident, MonitoringBudget, etc.)
+  signals.py           # Signal ingestion (LogTailer, ProcessWatcher, WebhookReceiver)
+  incidents.py         # Incident lifecycle + multi-window budget enforcement
+  remediator.py        # Knowledge-flashed fixer (reproducer test + rebuild + narrative retry)
+  sentinel.py          # Long-running monitor coordinator
+
+  agents/
+    base.py            # AgentBase (reuses Backend protocol)
+    research.py        # Best-practices research + plan evaluation
+    contract_author.py # Generates interface contracts
+    test_author.py     # Generates functional tests from contracts
+    code_author.py     # Implements black boxes (embeds PACT log keys)
+    shaper.py          # Shape Up pitch generation agent
+    trace_analyst.py   # I/O tracing for diagnosis
+    triage.py          # Error-to-component mapping + diagnostic reports
+
+  backends/
+    __init__.py        # Backend protocol + factory
+    anthropic.py       # Direct API backend
+    claude_code.py     # Claude Code CLI backend (validated token tracking)
+    claude_code_team.py # Tmux-based full Claude Code agent sessions (budget-aware)
+
+  human/
+    __init__.py        # Human integration facade
+    linear.py          # Linear issue tracking
+    slack.py           # Slack notifications
+    git.py             # Git/PR management
+```
+
+## Per-Project Directory
+
+```
+<project>/
+  task.md              # Task description
+  sops.md              # Operating procedures
+  pact.yaml            # Per-project config
+  design.md            # Living design document
+  .pact/
+    state.json         # Run lifecycle state
+    audit.jsonl        # All actions + decisions
+    decomposition/     # Tree + decisions
+    contracts/         # Per-component contracts + tests
+    implementations/   # Per-component code + attempts/
+    standards.json     # Global standards (auto-generated after decomposition)
+    tasks.json         # Phased task list (auto-generated after decomposition)
+    analysis.json      # Cross-artifact analysis report
+    checklist.json     # Requirements quality checklist
+    compositions/      # Integration glue
+    learnings/         # Accumulated learnings
+    monitoring/        # Incidents, budget state, diagnostic reports
+      incidents.json   # All incidents with lifecycle state
+      budget.json      # Running budget totals per window
+      reports/         # Per-incident diagnostic reports (markdown)
+```
+
+## Key Schemas
+
+| Schema | Purpose |
+|--------|---------|
+| `DecompositionTree` | Tree of components with traversal (leaves, parallel groups, subtree) |
+| `ComponentContract` | Typed interface: functions, types, invariants, dependencies |
+| `ContractTestSuite` | Executable tests generated from contract |
+| `TestResults` | Aggregated pass/fail with failure details |
+| `ScoredAttempt` | Competitive attempt with pass rate + duration scoring |
+| `RunState` | Mutable lifecycle: phase, status, component tasks, spend |
+| `Incident` | Tracked production error with lifecycle (detected→triaging→remediating→resolved/escalated) |
+| `MonitoringBudget` | Multi-window spend caps (per-incident, hourly, daily, weekly, monthly) |
+| `Signal` | Raw error signal from log file, process, webhook, or manual report |
+| `GlobalStandards` | Shared packages, types, conventions distributed to all agents |
+| `BuildMode` | StrEnum: unary, auto, hierarchy |
+| `Directive` | Structured FIFO command with type + payload |
+| `TaskList` | Phased task list with dependency-aware ready_tasks() |
+| `AnalysisReport` | Cross-artifact consistency findings (errors, warnings, info) |
+| `RequirementsChecklist` | Quality validation questions with tri-state answers |
+
+## Task List & Analysis Commands
+
+```bash
+pact tasks <project-dir>                   # Generate/display phased task list
+pact tasks <project-dir> --regenerate      # Force regeneration
+pact tasks <project-dir> --phase setup     # Filter by phase
+pact tasks <project-dir> --component auth  # Filter by component
+pact tasks <project-dir> --complete T001   # Mark task as completed
+pact tasks <project-dir> --json            # Output as JSON
+pact analyze <project-dir>                 # Run cross-artifact analysis
+pact analyze <project-dir> --json          # Output as JSON
+pact checklist <project-dir>               # Generate requirements checklist
+pact checklist <project-dir> --json        # Output as JSON
+pact export-tasks <project-dir>            # Export TASKS.md
+```
+
+The task list is auto-generated after decomposition and auto-updated after each implementation/integration phase.
+
+## Directive Commands
+
+```bash
+pact directive <project-dir> resume                                        # Backward-compatible simple string
+pact directive <project-dir> '{"type": "set_mode", "mode": "unary"}'       # Change build mode at runtime
+pact directive <project-dir> '{"type": "set_config", "key": "value"}'      # Update config keys
+pact directive <project-dir> '{"type": "inject_context", "context": "..."}'# Inject context for next agent
+```
+
+## Monitoring Commands
+
+```bash
+pact watch <project-dir>...           # Start Sentinel monitor (Ctrl+C to stop)
+pact report <project-dir> <error>     # Manually report a production error
+pact incidents <project-dir>          # List active/recent incidents
+pact incident <project-dir> <id>      # Show incident details + diagnostic report
+```
+
+## Testing
+
+```bash
+make test          # 1260 tests, ~5s
+make test-quick    # Stop on first failure
+```

pact_agents-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 J. Andrew McEntire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pact_agents-0.1.0/Makefile

@@ -0,0 +1,38 @@
+.PHONY: all install dev test clean help
+
+VENV := .venv
+PYTHON := $(VENV)/bin/python
+PIP := $(VENV)/bin/pip
+
+all: install  ## Default: create venv and install pact
+
+$(VENV)/bin/activate:
+	python3 -m venv $(VENV)
+
+install: $(VENV)/bin/activate  ## Install pact in editable mode
+	$(PIP) install -e ".[dev]"
+	@echo ""
+	@echo "  Pact installed. Activate with:"
+	@echo "    source $(VENV)/bin/activate"
+	@echo ""
+	@echo "  Then try:"
+	@echo "    pact init my-project"
+	@echo "    pact --help"
+
+dev: $(VENV)/bin/activate  ## Install with LLM backend support
+	$(PIP) install -e ".[dev,llm]"
+	@echo ""
+	@echo "  Pact installed with LLM support."
+
+test: $(VENV)/bin/activate  ## Run all tests
+	$(VENV)/bin/python -m pytest tests/ -v
+
+test-quick: $(VENV)/bin/activate  ## Run tests (stop on first failure)
+	$(VENV)/bin/python -m pytest tests/ -x -q
+
+clean:  ## Remove venv, caches, build artifacts
+	rm -rf $(VENV) dist build *.egg-info .pytest_cache
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+
+help:  ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'

pact_agents-0.1.0/PKG-INFO

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: pact-agents
+Version: 0.1.0
+Summary: Contract-first multi-agent software engineering. Contracts before code. Tests as law. Agents that can't cheat.
+Project-URL: Homepage, https://jmcentire.github.io/pact/
+Project-URL: Repository, https://github.com/jmcentire/pact
+Project-URL: Documentation, https://jmcentire.github.io/pact/
+Author-email: "J. Andrew McEntire" <j.andrew.mcentire@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,contracts,llm,multi-agent,software-engineering,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.12
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: all-backends
+Requires-Dist: anthropic>=0.40; extra == 'all-backends'
+Requires-Dist: google-genai>=1.0; extra == 'all-backends'
+Requires-Dist: openai>=1.0; extra == 'all-backends'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0; extra == 'gemini'
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40; extra == 'llm'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Pact
+
+**Contracts before code. Tests as law. Agents that can't cheat.**
+
+Pact is a multi-agent software engineering framework where the architecture is decided before a single line of implementation is written. Tasks are decomposed into components, each component gets a typed interface contract, and each contract gets executable tests. Only then do agents implement -- independently, in parallel, even competitively -- with no way to ship code that doesn't honor its contract.
+
+The insight: LLMs are unreliable reviewers but tests are perfectly reliable judges. So make the tests first, make them mechanical, and let agents iterate until they pass. No advisory coordination. No "looks good to me." Pass or fail.
+
+## When to Use Pact
+
+Pact is for projects where **getting the boundaries right matters more than getting the code written fast.** If a single Claude or Codex session can build your feature in one pass, just do that -- Pact's decomposition, contracts, and multi-agent coordination would be pure overhead.
+
+Use Pact when:
+- The task has **multiple interacting components** with non-obvious boundaries
+- You need **provable correctness at interfaces** -- not "it seems to work" but "it passes 200 contract tests"
+- The system will be **maintained by agents** who need contracts to understand what each piece does
+- You want **competitive or parallel implementation** where multiple agents race on the same component
+- The codebase is large enough that **no single context window can hold it all**
+
+Don't use Pact when:
+- A single agent can build the whole thing in one shot
+- The task is a bug fix, refactor, or small feature
+- You'd spend more time on contracts than on the code itself
+
+## Philosophy: Contracts Are the Product
+
+Pact treats **contracts as source of truth and implementations as disposable artifacts.** The code is cattle, not pets.
+
+When a module fails in production, the response isn't "debug the implementation." It's: add a test that reproduces the failure to the contract, flush the implementation, and let an agent rebuild it. The contract got stricter. The next implementation can't have that bug. Over time, contracts accumulate the scar tissue of every production incident -- they become the real engineering artifact.
+
+This inverts the traditional relationship between code and tests. Code is cheap (agents generate it in minutes). Contracts are expensive (they encode hard-won understanding of what the system actually needs to do). Pact makes that inversion explicit: you spend your time on contracts, agents spend their time on code.
+
+The practical upside: when someone asks "who's debugging this at 3am?" -- agents are. The Sentinel watches production logs, detects errors, attributes them to the right component via embedded PACT log keys, spawns a knowledge-flashed fixer agent loaded with the full contract/test context, adds a reproducer test, rebuilds the module, and verifies all tests pass. The contract ensures they can't introduce regressions. The human reviews the *contract change* in the morning, not the code.
+
+## Quick Start
+
+```bash
+git clone https://github.com/jmcentire/pact.git
+cd pact
+make
+source .venv/bin/activate
+```
+
+That's it. Now try:
+
+```bash
+pact init my-project
+# Edit my-project/task.md with your task
+# Edit my-project/sops.md with your standards
+pact --help
+```
+
+## How It Works
+
+```
+Task
+  |
+  v
+Interview -----> Shape (opt) -----> Decompose -----> Contract -----> Test
+                    |                   |                 |              |
+                    v                   v                 v              v
+              Pitch: appetite,    Component Tree    Interfaces     Executable Tests
+              breadboard, risks                                        |
+                                                                       v
+                                         Implement (parallel, competitive)
+                                                                       |
+                                                                       v
+                                         Integrate (glue + parent tests)
+                                                                       |
+                                                                       v
+                                                                 Diagnose (on failure)
+```
+
+**Nine phases, all mechanical gates:**
+
+1. **Interview** -- Identify risks, ambiguities, ask clarifying questions
+2. **Shape** -- (Optional) Produce a Shape Up pitch: appetite, breadboard, rabbit holes, no-gos
+3. **Decompose** -- Task into 2-7 component tree, guided by shaping context if present
+4. **Contract** -- Each component gets a typed interface contract
+5. **Test** -- Each contract gets executable tests (the enforcement)
+6. **Validate** -- Mechanical gate: refs resolve, no cycles, tests parse
+7. **Implement** -- Each component built independently by a code agent
+8. **Integrate** -- Parent components composed via glue code
+9. **Diagnose** -- On failure: I/O tracing, root cause, recovery
+
+## Two Execution Levers
+
+| Lever | Config Key | Effect |
+|-------|-----------|--------|
+| **Parallel Components** | `parallel_components: true` | Independent components implement concurrently |
+| **Competitive Implementations** | `competitive_implementations: true` | N agents implement the SAME component; best wins |
+
+Either, neither, or both. Defaults: both off (sequential, single-attempt).
+
+## Plan-Only Mode
+
+Set `plan_only: true` to stop after contracts and tests are generated. Then target specific components:
+
+```bash
+pact components my-project              # See what was decomposed
+pact build my-project sync_tracker      # Build one component
+pact build my-project sync_tracker --competitive --agents 3
+```
+
+## CLI Commands
+
+| Command | Purpose |
+|---------|---------|
+| `pact init <project>` | Scaffold a new project |
+| `pact run <project>` | Run the pipeline |
+| `pact daemon <project>` | Event-driven mode (recommended) |
+| `pact status <project> [component]` | Show project or component status |
+| `pact components <project>` | List components with status |
+| `pact build <project> <id>` | Build/rebuild a specific component |
+| `pact interview <project>` | Run interview phase only |
+| `pact answer <project>` | Answer interview questions |
+| `pact approve <project>` | Approve with defaults |
+| `pact validate <project>` | Re-run contract validation |
+| `pact design <project>` | Regenerate design.md |
+| `pact stop <project>` | Gracefully stop a running daemon |
+| `pact log <project>` | Show audit trail (`--tail N`, `--json`) |
+| `pact ping` | Test API connection and show pricing |
+| `pact signal <project>` | Resume a paused daemon |
+| `pact watch <project>...` | Start Sentinel production monitor (Ctrl+C to stop) |
+| `pact report <project> <error>` | Manually report a production error |
+| `pact incidents <project>` | List active/recent incidents |
+| `pact incident <project> <id>` | Show incident details + diagnostic report |
+
+## Configuration
+
+**Global** (`config.yaml` at repo root):
+
+```yaml
+model: claude-opus-4-6
+default_budget: 10.00
+parallel_components: false
+competitive_implementations: false
+competitive_agents: 2
+max_concurrent_agents: 4
+plan_only: false
+
+# Override token pricing (per million tokens: [input, output])
+model_pricing:
+  claude-opus-4-6: [15.00, 75.00]
+  claude-sonnet-4-5-20250929: [3.00, 15.00]
+  claude-haiku-4-5-20251001: [0.80, 4.00]
+
+# Production monitoring (opt-in)
+monitoring_enabled: false
+monitoring_auto_remediate: true
+monitoring_budget:
+  per_incident_cap: 5.00
+  hourly_cap: 10.00
+  daily_cap: 25.00
+  weekly_cap: 100.00
+  monthly_cap: 300.00
+```
+
+**Per-project** (`pact.yaml` in project directory):
+
+```yaml
+budget: 25.00
+parallel_components: true
+competitive_implementations: true
+competitive_agents: 3
+
+# Shaping (Shape Up methodology)
+shaping: true               # Enable shaping phase (default: false)
+shaping_depth: standard      # light | standard | thorough
+shaping_rigor: moderate      # relaxed | moderate | strict
+shaping_budget_pct: 0.15    # Max budget fraction for shaping
+
+# Production monitoring (per-project)
+monitoring_log_files:
+  - "/var/log/myapp/app.log"
+  - "/var/log/myapp/error.log"
+monitoring_process_patterns:
+  - "myapp-server"
+monitoring_webhook_port: 9876
+monitoring_error_patterns:
+  - "ERROR"
+  - "CRITICAL"
+  - "Traceback"
+```
+
+Project config overrides global. Both are optional.
+
+### Multi-Provider Configuration
+
+Route different roles to different providers for cost optimization:
+
+```yaml
+budget: 50.00
+
+role_models:
+  decomposer: claude-opus-4-6        # Strong reasoning for architecture
+  contract_author: claude-opus-4-6    # Precision for interfaces
+  test_author: claude-sonnet-4-5-20250929  # Fast test generation
+  code_author: gpt-4o                # Cost-effective implementation
+
+role_backends:
+  decomposer: anthropic
+  contract_author: anthropic
+  test_author: anthropic
+  code_author: openai                # Mix providers per role
+```
+
+Available backends: `anthropic`, `openai`, `gemini`, `claude_code`, `claude_code_team`.
+
+## Project Structure
+
+Each project is a self-contained directory:
+
+```
+my-project/
+  task.md              # What to build
+  sops.md              # How to build it (standards, stack, preferences)
+  pact.yaml            # Budget and execution config
+  design.md            # Auto-maintained design document
+  .pact/
+    state.json         # Run lifecycle
+    audit.jsonl        # Full audit trail
+    decomposition/     # Tree + decisions
+    contracts/         # Per-component interfaces + tests
+    implementations/   # Per-component code
+    compositions/      # Integration glue
+    learnings/         # Accumulated learnings
+    monitoring/        # Incidents, budget state, diagnostic reports
+```
+
+## Development
+
+```bash
+make dev          # Install with LLM backend support
+make test         # Run full test suite (950 tests)
+make test-quick   # Stop on first failure
+make clean        # Remove venv and caches
+```
+
+Requires Python 3.12+. Core has two dependencies: `pydantic` and `pyyaml`. LLM backends require `anthropic`.
+
+## Architecture
+
+See [CLAUDE.md](CLAUDE.md) for the full technical reference.
+
+## Background
+
+Pact is one of three systems (alongside Emergence and Apprentice) built to test
+the ideas in [Beyond Code: Context, Constraints, and the New Craft of Software](https://www.amazon.com/dp/B0GNLTXVC7).
+The book covers the coordination, verification, and specification problems that
+motivated Pact's design.
+
+## License
+
+MIT