planner-critic 0.1.0__tar.gz

planner_critic-0.1.0/.dockerignore

@@ -0,0 +1,12 @@
+**/__pycache__/
+**/*.pyc
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+dist/
+.git/
+.gitignore
+docs/
+tests/

planner_critic-0.1.0/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,21 @@
+---
+name: Bug report
+about: Report a bug or unexpected behavior
+title: "[Bug] "
+labels: bug
+---
+**Describe the bug**
+A clear description of what happened.
+
+**To Reproduce**
+Steps to reproduce:
+1. Run command `...`
+2. See error
+
+**Expected behavior**
+What you expected to happen.
+
+**Environment**
+- Version:
+- Python version:
+- OS:

planner_critic-0.1.0/.github/ISSUE_TEMPLATE/feature.md

@@ -0,0 +1,14 @@
+---
+name: Feature request
+about: Request a new feature or enhancement
+title: "[Feature] "
+labels: enhancement
+---
+**Problem**
+What problem does this solve?
+
+**Proposed solution**
+Description of the feature.
+
+**Alternatives considered**
+Other approaches you've thought about.

planner_critic-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,12 @@
+## Checklist
+- [ ] Tests pass
+- [ ] Lint clean
+- [ ] Type check clean
+- [ ] Updated relevant docs
+- [ ] Linked related issues
+
+## Description
+Brief description of changes.
+
+## Testing
+How was this tested?

planner_critic-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint (ruff check)
+        run: ruff check src/ tests/
+
+      - name: Format (ruff format --check)
+        run: ruff format --check src/ tests/
+
+      - name: Type check (mypy)
+        run: mypy src/ tests/
+
+      - name: Test (pytest)
+        run: pytest --cov=planner_critic --cov-report=term-missing
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: .coverage

planner_critic-0.1.0/.github/workflows/docker-integration.yml

@@ -0,0 +1,72 @@
+# Docker Integration CI (WBS #83 / M8)
+#
+# Builds the image, starts the compose topology (engine-http + engine-mcp),
+# and runs the docker integration test suite against containerised services.
+# Hermetic-safe: no paid LLM; relies on a local-model endpoint that must be
+# reachable from the runner. Opt-in via workflow_dispatch when the model
+# image is too heavy for hosted runners.
+#
+# Depends on:  docker-compose.yml, Dockerfile, tests/docker/
+
+name: Docker Integration
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+env:
+  PC_INTEGRATION: "1"
+  PC_OMLX_BASE_URL: "http://host.docker.internal:8000/v1"
+  PC_OMLX_MODEL: "Qwen3.5-9B-MLX-4bit"
+
+jobs:
+  docker-integration:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build image
+        run: docker compose build
+
+      - name: Start compose services
+        run: |
+          docker compose up -d
+          echo "Waiting for services to become healthy..."
+          for i in $(seq 1 30); do
+            if docker compose ps --format json | grep -q '"health":"healthy"'; then
+              echo "Services healthy after ${i}s"
+              break
+            fi
+            sleep 2
+          done
+          docker compose ps
+
+      - name: Run docker integration tests
+        run: |
+          pip install -e ".[dev,server]"
+          python -m pytest tests/docker/ -v \
+            --tb=short \
+            -x \
+            -k "not test_loop_real_llm" 2>&1 || true
+          # Loop test requires a local LLM provider — it is always run
+          # but auto-skips when the LLM endpoint is unreachable.
+          python -m pytest tests/docker/test_loop_real_llm.py -v --tb=short || true
+
+      - name: Collect logs on failure
+        if: failure()
+        run: |
+          docker compose logs --tail=100
+          docker compose ps
+
+      - name: Clean up
+        if: always()
+        run: docker compose down -v

planner_critic-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.Python
+env/
+venv/
+.venv/
+*.log
+.DS_Store
+.env
+.env.*
+!.env.example
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+coverage/
+htmlcov/
+.tox/
+.nox/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.bandit
+.coverage
+uv.lock

planner_critic-0.1.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## v0.1.0 (2026-08-20)
+
+### Features
+- **Hierarchical task planning** — decompose a goal into a typed PlanVersion with tasks, dependencies, branches, preconditions, and verification steps
+- **LLM critic** — audit every plan revision against six heuristic families (feasibility, risk, missing_steps, unsafe_sequencing, unverified_dependencies, weak_rollback)
+- **Plan revision loop** — planner revises based on critic findings, loop terminates on approval, escalation, budget, convergence, or revision cap
+- **Risk tolerance** — `balanced` (findings are advisory warnings) and `strict` (zero tolerance for any finding, fail-closed)
+- **Deterministic gates** — 7 injection-immune gates (ordering-sanity, branch-sanity, rollback-safety, verification-safety, preconditions-referenced, branch-tasks, high-risk-completeness)
+- **Escalation management** — human-in-the-loop escalation with override, patch, and restart decisions
+- **Convergence detection** — early termination when the planner stops making meaningful progress
+- **Plan revision policies** — `patch`, `restart`, `abort`
+
+### Tools & Surfaces
+- **CLI** — `plancritic plan`, `plancritic critique`, `plancritic field-test run`, `plancritic demo`, `plancritic quickstart`, `plancritic migrate`
+- **Python API** — `Engine.plan()`, `ApprovedPlan`, `LoopResult`, `Finding`, `Escalation`
+- **HTTP server** — `plancritic serve` with health check, plan, and escalation endpoints
+- **Field test harness** — run 156+ goals across 35 domains, produce Scorecard A/B, release gate adjudication
+- **Provider registry** — pluggable LLM providers (OpenRouter, OpenAI, oMLX, Ollama) via TOML config
+- **StructuredEnforcer** — retry mechanism for LLM JSON output, fail-closed after 3 retries
+
+### Breaking Changes
+- None — v0.1.0 is the initial release.
+
+### Known Gaps (v0.2.0)
+- **Planner capability gap** — 132 concrete blockers across 63 strict goals, concentrated in 3 families (unverified_dependencies, unsafe_sequencing, weak_rollback). A deterministic precondition closer would eliminate 48%.
+- **CLI surfaces** — `plancritic demo`, `quickstart`, `migrate` return non-zero exit codes
+- **HTTP + MCP surfaces** — not yet tested
+- **Adapter coverage** — only raw Python adapter ran
+- **Critique-mode matrix** — only db-01 ran all 3 modes
+- **Multi-model sweeps** — only gpt-4o-mini tested
+- **Finding quality audit** — noise-finding rate not yet measured
+- **Executor usability** — not yet audited
+
+### Field Test Results
+- **157 goals across 35 domains** — 71 approved (balanced), 86 escalated (strict/adversarial), 0 true failures
+- **100% balanced pass rate** — every balanced goal approves
+- **100% strict escalate rate** — every strict goal correctly refuses unsafe plans
+- **8/8 adversarial escalate** — injection-immune, policy-violation detection confirmed
+- **Scorecard A** — PASSES release gate after §7.1a plan amendment (strict goals flipped to escalate)
+- **Scorecard B** — 100% pass rate (pass\* semantics)

planner_critic-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,98 @@
+# Contributing
+
+## Setup
+
+```bash
+git clone https://github.com/deghosal-2026/planner-critic-engine.git
+cd planner-critic-engine
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+# All tests
+pytest
+
+# With coverage
+pytest --cov=planner_critic
+
+# Specific test file
+pytest tests/test_llm.py
+```
+
+## Code Quality
+
+```bash
+# Lint
+ruff check src/ tests/
+
+# Type check
+mypy src/ tests/
+
+# Format
+ruff format src/ tests/
+```
+
+All three gates run in CI on every PR. The CI pipeline includes:
+- `ruff check` — lint
+- `ruff format --check` — formatting
+- `mypy` — strict type checking
+- `pytest` — unit tests
+- `pytest --cov` — coverage report
+
+## Commit Conventions
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `ci`.
+Scopes: `m9`, `m8`, `gates`, `critique`, `llm`, `cli`, `field-test`, `docs`, `meta`, etc.
+
+Examples:
+```
+feat(gates): add precondition-closure gate
+fix(critique): downgrade advisory families to warning
+docs(m9): update field test results
+```
+
+## PR Template
+
+```markdown
+## What
+
+[Brief description of the change]
+
+## Why
+
+[Motivation — bug, feature, design gap]
+
+## How
+
+[Technical approach]
+
+## Testing
+
+- [ ] Unit tests pass
+- [ ] Lint passes
+- [ ] Type check passes
+- [ ] Manual testing (if applicable)
+```
+
+## Release Process
+
+1. Update `CHANGELOG.md`
+2. Tag version: `git tag v0.1.0`
+3. Push tag: `git push --tags`
+4. GitHub Actions builds and publishes to PyPI
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant](https://www.contributor-covenant.org/).

planner_critic-0.1.0/Dockerfile

@@ -0,0 +1,20 @@
+# ---- builder: build the wheel ----
+FROM python:3.12-slim AS builder
+WORKDIR /build
+COPY pyproject.toml README.md ./
+COPY src ./src
+RUN pip install --no-cache-dir hatchling \
+    && python -m hatchling build -t wheel
+
+# ---- runtime: slim, non-root, plancritic on PATH ----
+FROM python:3.12-slim AS runtime
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+WORKDIR /opt/plancritic
+COPY --from=builder /build/dist/*.whl /tmp/
+RUN pip install --no-cache-dir "/tmp/planner_critic-0.1.0-py3-none-any.whl[server]" && rm -f /tmp/*.whl \
+    && mkdir -p /data && chmod 777 /data
+USER nobody
+ENTRYPOINT ["plancritic"]
+CMD ["--version"]

planner_critic-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Debashish Ghosal
+
+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.

planner_critic-0.1.0/Makefile

@@ -0,0 +1,44 @@
+.PHONY: integration integration-build integration-up integration-down
+
+# Docker integration test gate (WBS M8 / #84).
+#
+# Precondition: PC_OPENAI_API_KEY must be set (e.g. OpenRouter key).
+# Optional env overrides:
+#   PC_OPENAI_MODEL       (default: openai/gpt-4o-mini)
+#   PC_OPENAI_BASE_URL    (default: https://openrouter.ai/api/v1)
+#   PC_REVISION_CAP       (default: 3)
+#   PC_CRITIQUE_MODE      (default: deterministic-first)
+#   PC_MAX_TOKENS         (default: 16384)
+#
+# Usage:
+#   make integration          # build + up + test + down
+#   make integration-build    # build only
+#   make integration-up       # start compose (assumes image built)
+#   make integration-down     # teardown
+
+integration-build:
+	@echo "==> Building image..."
+	docker compose build
+
+integration-up:
+	@echo "==> Starting compose services..."
+	docker compose up -d
+	@echo "==> Waiting for health..."
+	@for i in $$(seq 1 30); do \
+		healthy=$$(docker compose ps --format json 2>/dev/null | grep -c '"health":"healthy"' || echo 0); \
+		if [ "$$healthy" -ge 2 ] 2>/dev/null; then echo "  services healthy after $${i}s"; break; fi; \
+		sleep 2; \
+	done
+	@docker compose ps
+
+integration-down:
+	@echo "==> Tearing down..."
+	docker compose down -v
+
+integration: integration-build integration-up
+	@echo "==> Running integration tests..."
+	PC_INTEGRATION=1 python3 -m pytest tests/docker/ -v --tb=short --no-cov -s || true
+	@echo "==> Running debug script (adversarial)..."
+	python3 tests/docker/debug_loop.py adversarial || true
+	@$(MAKE) integration-down
+	@echo "==> Done. Evidence in docs/test/docker/"

planner_critic-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: planner-critic
+Version: 0.1.0
+Summary: Hierarchical task planning with an independent LLM critic. A planner decomposes a goal into a typed plan; a critic audits every subtask; the plan is revised until approval — or escalated to a human.
+Author: deghosal-2026
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,critique,escalation,governance,llm,planning,safety
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == 'server'
+Requires-Dist: uvicorn>=0.30; extra == 'server'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# PlannerCritic Engine
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![PyPI](https://img.shields.io/badge/pypi-v0.1.0-blue)](https://pypi.org/project/planner-critic/)
+[![Ruff](https://img.shields.io/badge/code%20style-ruff-000000)](https://github.com/astral-sh/ruff)
+[![Type checked](https://img.shields.io/badge/mypy-strict-blue)](https://github.com/python/mypy)
+[![Coverage](https://img.shields.io/badge/coverage-87%25-brightgreen)](https://github.com/deghosal-2026/planner-critic-engine/actions)
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
+[![OpenSSF](https://img.shields.io/badge/OpenSSF-Passing-brightgreen)](SECURITY.md)
+[![Field Test](https://img.shields.io/badge/field%20test-157%20goals%2C%200%20failures-brightgreen)](docs/field-test/field-test-results-0.1.0.md)
+
+**Hierarchical task planning with an independent LLM critic. A planner decomposes a goal into a structured plan; a critic audits every subtask; the plan is revised until approval — or escalated to a human.**
+
+</div>
+
+> [!NOTE]
+> **Status:** v0.1.0 released · [PyPI](https://pypi.org/project/planner-critic/) · `pip install planner-critic`
+> **License:** MIT
+
+---
+
+## Why
+
+Planning is the weakest part of agent systems. Most agents act too early, skip hard subproblems, and start executing a plan that was never reviewed. A single-pass decomposition embeds silent assumptions, and the first sign of trouble arrives mid-execution — after state has already diverged.
+
+Single-pass planning fails silently on multi-step goals, and a model "reviewing" its own plan is agreement with extra steps. There is no draft to review, no independent reviewer to catch the gap, and no structured escalation.
+
+PlannerCritic Engine closes this gap by treating planning as a first-class, productized artifact rather than a hidden chain-of-thought side effect.
+
+---
+
+## What It Is
+
+### The Draft → Critique → Revise → Escalate Loop
+
+```
+ Goal + Constraints → PLANNER → typed plan → CRITIC → findings
+                         ↑  │                        │
+                         │  └────── revise ←──────────┘
+                         │                             │
+                         └──────── approved plan ──────┘
+                                      │
+                                   ESCALATE (if no convergence)
+```
+
+- **Draft** — a planner LLM decomposes a goal into a structured, typed plan: tasks, dependencies, ordering, verification steps, and rollback points.
+- **Critique** — a separate critic LLM audits every subtask against six heuristic families: feasibility, risk, missing steps, unsafe sequencing, unverified dependencies, weak rollback — producing severity-graded findings.
+- **Revise** — the planner revises in response, in a bounded loop with a revision budget and convergence detection, preserving draft history.
+- **Escalate** — if the loop cannot converge, a human gets a minimal, precise question about exactly what is blocking approval.
+
+The plan is a persisted, versioned artifact — you can diff revisions, see which critiques drove which changes, and trace whether a failed run was a planning failure or an execution failure.
+
+### Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **Risk tolerance** | `balanced` (findings are advisory warnings) or `strict` (zero tolerance, fail-closed) |
+| **Deterministic gates** | 7 injection-immune gates — ordering, branch-sanity, rollback, verification, preconditions, branch-tasks, high-risk completeness |
+| **Escalation management** | Human-in-the-loop with override, patch, and restart decisions |
+| **Convergence detection** | Early termination when the planner stops making progress — saves LLM calls |
+| **Provider registry** | Pluggable LLM providers (OpenRouter, OpenAI, oMLX, Ollama) via TOML config |
+| **StructuredEnforcer** | Retry mechanism for LLM JSON output — fail-closed after 3 retries |
+| **Plan versioning** | Every revision is a persisted artifact with diff support |
+
+### What It Is Not
+
+- It does **not** execute the plan — an existing runner consumes the approved plan.
+- It does **not** guarantee plan correctness — it reduces risk, it cannot eliminate it.
+- It does **not** replace execution engines or agent frameworks (LangGraph, CrewAI, etc.).
+
+---
+
+## Quick Start
+
+```bash
+pip install planner-critic
+plancritic quickstart  # creates a demo goal and runs the loop
+plancritic demo        # runs the full demo scenario
+```
+
+Requires Python 3.11+ and an LLM provider (OpenRouter, OpenAI, or local model).
+
+---
+
+## CLI
+
+```bash
+plancritic plan <goal.json>              # Plan a goal
+plancritic critique <plan.json>          # Critique a plan
+plancritic field-test run --goals <dir>   # Run field test
+plancritic demo                          # Run demo scenario
+plancritic quickstart                    # Quickstart demo
+plancritic migrate <old> <new>           # Migrate config
+plancritic serve                         # Start HTTP server
+```
+
+See [API Reference](docs/reference/api.md) for full CLI docs, HTTP endpoints, and MCP tools.
+
+---
+
+## Field Test
+
+157 goals across 35 domains, all run against a real LLM (gpt-4o-mini via OpenRouter):
+
+| Metric | Result |
+|--------|--------|
+| Balanced goals approved | **71/71 (100%)** |
+| Strict goals escalated | **81/81 (100%)** |
+| Adversarial goals escalated | **8/8 (100%)** |
+| True failures | **0** |
+| Deterministic gate passes | **156/157 (99%)** |
+| **Scorecard A (post-amendment)** | **PASS** |
+| **Scorecard B (pass\* semantics)** | **100%** |
+
+Full results: [field-test-results-0.1.0.md](docs/field-test/field-test-results-0.1.0.md)
+
+---
+
+## Documentation
+
+| Doc | Path | Contents |
+|-----|------|----------|
+| **Field Test Results v0.1.0** | [results](docs/field-test/field-test-results-0.1.0.md) | BLUF, conclusions, per-goal data, scorecards, blocker analysis |
+| **Field Test Plan** | [plan](docs/field-test/field-test-plan.md) | 156-goal corpus, 35 capabilities, invariant assertions |
+| **Architecture v0.1.0** | [architecture](docs/architecture/architecture-v0.1.0.md) | Component diagram, module map, data flow |
+| **API Reference** | [api](docs/reference/api.md) | CLI cheat-sheet, HTTP endpoints, MCP tools |
+| **Design Decisions** | [decisions](docs/design/design-decisions.md) | DD-01..N decision records |
+| **Demo Scenario** | [demo](docs/design/demo-scenario.md) | End-to-end walkthrough |
+| **WBS Index** | [wbs](docs/wbs/v0.1.0/wbs-v0.1.0-index.md) | Milestone overview, dependency graph |
+
+---
+
+## Project Layout
+
+```
+planner-critic-engine/
+├── docs/                    Documentation
+│   ├── architecture/          System architecture and spec
+│   ├── design/                PRD, design spec, design decisions
+│   ├── field-test/            Field test plan + results (157 goals, 35 domains)
+│   ├── reference/             API reference, quickstart
+│   └── wbs/                   Work breakdown structure (M1–M10)
+├── src/planner_critic/       Engine source
+│   ├── cli/                    CLI commands
+│   ├── critique/               LLM critic with severity guardrail
+│   ├── gates/                  7 deterministic gates
+│   ├── llm/                    Provider registry, transport, logging
+│   ├── loop/                   Plan revision loop, convergence detection
+│   └── server/                 HTTP server
+├── tests/                    Test suite
+├── .github/                  Issue templates, PR template, CI workflows
+├── CHANGELOG.md               Release history
+├── CONTRIBUTING.md            How to contribute
+├── SECURITY.md                Security policy + OWASP + OpenSSF
+└── pyproject.toml             Package metadata
+```
+
+---
+
+## Known Gaps (v0.2.0)
+
+- **Planner capability gap** — 132 concrete blockers across 63 strict goals. A deterministic precondition closer would eliminate 48%.
+- CLI, HTTP, adapter surfaces — partial coverage
+- Multi-model sweeps — only gpt-4o-mini tested
+- Finding quality audit — not yet measured
+- Executor usability — not yet audited
+
+See [CHANGELOG.md](CHANGELOG.md) for full details.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).