aofire-python-agent 0.1.0__py3-none-any.whl

aofire_python_agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,405 @@
+Metadata-Version: 2.4
+Name: aofire-python-agent
+Version: 0.1.0
+Summary: Claude-powered Python coding and planning agents with enforced quality standards
+Author-email: Ed Hodapp <ed@hodapp.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/edhodapp/python-agent
+Project-URL: Repository, https://github.com/edhodapp/python-agent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: claude-agent-sdk
+Requires-Dist: pydantic>=2.12
+Provides-Extra: dev
+Requires-Dist: flake8-pyproject; extra == "dev"
+Requires-Dist: hypothesis; extra == "dev"
+Requires-Dist: mutmut<3; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pydantic>=2.12; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Dynamic: license-file
+
+# aofire-python-agent
+
+[![Lint](https://github.com/edhodapp/python-agent/actions/workflows/lint.yml/badge.svg)](https://github.com/edhodapp/python-agent/actions/workflows/lint.yml)
+[![Type Check](https://github.com/edhodapp/python-agent/actions/workflows/typecheck.yml/badge.svg)](https://github.com/edhodapp/python-agent/actions/workflows/typecheck.yml)
+[![Tests (570)](https://github.com/edhodapp/python-agent/actions/workflows/test.yml/badge.svg)](https://github.com/edhodapp/python-agent/actions/workflows/test.yml)
+[![Taint Analysis](https://github.com/edhodapp/python-agent/actions/workflows/taint.yml/badge.svg)](https://github.com/edhodapp/python-agent/actions/workflows/taint.yml)
+[![Fuzz](https://github.com/edhodapp/python-agent/actions/workflows/fuzz.yml/badge.svg)](https://github.com/edhodapp/python-agent/actions/workflows/fuzz.yml)
+[![Mutation](https://github.com/edhodapp/python-agent/actions/workflows/mutation.yml/badge.svg)](https://github.com/edhodapp/python-agent/actions/workflows/mutation.yml)
+
+Claude-powered Python agents with ontology-driven project planning,
+autonomous code generation, and defense-in-depth security hardening.
+
+The pipeline takes a project from idea to production code through
+structured ontology exploration, branching solution candidates, and
+an autonomous coding agent that enforces 10 quality gates before
+every commit.
+
+**BSD 3-Clause.** Python 3.11+. Requires the
+[Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python).
+
+## What This Is
+
+A monorepo containing six CLI tools and a shared ontology framework:
+
+| Tool | Mode | Purpose |
+|------|------|---------|
+| `aofire-discovery-agent` | Interactive | Build a domain ontology through conversation |
+| `aofire-divergence-agent` | Autonomous | Generate N candidate solution architectures |
+| `aofire-convergence-agent` | Interactive | Compare, select, and refine candidates |
+| `aofire-coding-agent` | Autonomous | Write production-quality code with Sonnet/Opus escalation |
+| `aofire-planning-agent` | Interactive | Freeform project design (no ontology) |
+| `aofire-call-graph` | Analysis | Source-to-sink taint analysis with CWE tagging |
+
+Plus shared infrastructure:
+
+| Module | Purpose |
+|--------|---------|
+| `ontology.py` | 16 Pydantic models: entities, relationships, modules, DAG |
+| `types.py` | `Annotated` + `Literal` shared type definitions |
+| `dag_utils.py` | DAG persistence with HMAC integrity signing |
+| `dag_integrity.py` | HMAC verification + injection pattern scanning |
+| `tool_guard.py` | `can_use_tool` callback: Bash blocklist + path confinement |
+| `rules.py` | System prompts with `frame_data()` content framing |
+
+## Install
+
+```bash
+pip install aofire-python-agent
+```
+
+For development (includes test/analysis tools):
+
+```bash
+git clone https://github.com/edhodapp/python-agent.git
+cd python-agent
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+```
+
+## The Ontology Pipeline
+
+```
+aofire-discovery-agent  -->  aofire-divergence-agent  -->  aofire-convergence-agent  -->  aofire-coding-agent
+  (interactive)        (autonomous)          (interactive)           (autonomous)
+  Build domain         Generate N            Compare, select,        Write code to
+  ontology             solution candidates   accept, refine          production standards
+```
+
+All state is saved to an **ontology DAG** (a JSON file). Each node is a
+complete ontology snapshot. Each edge records a design decision. You can
+backtrack to any prior state and explore a different path.
+
+### Step 1: Discovery
+
+Build a domain ontology interactively. The agent asks questions about
+your domain and constructs entities, relationships, and constraints.
+
+```bash
+aofire-discovery-agent "A URL shortener service" --dag-file shortener.json
+```
+
+Example session:
+
+```
+Planner: I'll help you design a URL shortener. Who are the users?
+
+> Anyone can follow a link. Registered users create short URLs.
+
+  [Agent proposes entities: User, ShortURL, relationship: User owns ShortURL]
+
+> show
+  Entities (2):
+    user: User [username, api_key]
+    short_url: ShortURL [slug, target_url, click_count]
+  Relationships (1):
+    user --owns--> short_url (one_to_many)
+  Open Questions (2):
+    [open] q1: Storage backend?
+    [open] q2: Slug format?
+
+> save initial domain model
+  Saved snapshot: 20260401T120000...
+
+> quit
+```
+
+Commands: `show`, `save [label]`, `back`, `quit`/`exit`/`done`
+
+Options:
+- `--dag-file PATH` -- DAG JSON file (default: `ontology.json`)
+- `-m MODEL` -- model (default: `claude-opus-4-6`)
+
+### Step 2: Divergence
+
+Autonomously generate multiple solution candidates. The agent identifies
+key architectural decision points, then generates one complete solution
+per strategy.
+
+```bash
+aofire-divergence-agent --dag-file shortener.json -n 3
+```
+
+```
+Identifying 3 strategies...
+Generating candidate: monolith-sqlite...
+  Created: monolith-sqlite
+Generating candidate: microservices-postgres...
+  Created: microservices-postgres
+Generating candidate: serverless-dynamo...
+  Created: serverless-dynamo
+
+Done. 3 candidates. Cost: $0.1234
+```
+
+Each candidate fills in the solution domain: modules, classes, functions,
+data models, external dependencies, and test strategies. The DAG now has
+three branching children.
+
+Options:
+- `--dag-file PATH` -- DAG JSON file (required)
+- `-n N` -- number of candidates (default: 3)
+- `-m MODEL` -- model (default: `claude-sonnet-4-6`)
+- `--max-budget USD` -- spending cap (default: 5.0)
+
+### Step 3: Convergence
+
+Compare candidates, select one, and refine it interactively. The LLM
+has context of all candidates and assists with comparisons.
+
+```bash
+aofire-convergence-agent --dag-file shortener.json
+```
+
+```
+> list
+  1. monolith-sqlite: Entities (2), Modules (4)...
+  2. microservices-postgres: Entities (2), Modules (6)...
+  3. serverless-dynamo: Entities (2), Modules (5)...
+
+> compare monolith-sqlite and microservices-postgres on complexity
+  [LLM explains trade-offs between the two approaches]
+
+> select 1
+  Selected: monolith-sqlite
+
+> show
+  [Full ontology: entities, relationships, modules with classes/functions]
+
+> accept
+  Accepted: monolith-sqlite. You can now refine.
+
+> Add rate limiting to the API module
+  [LLM proposes ontology update with new RateLimiter class]
+
+> save final design
+> quit
+```
+
+Commands: `list`, `select <n>`, `back`, `show`, `accept`, `save [label]`.
+Any other text goes to the LLM (e.g., "compare", "explain", "refine").
+
+Options:
+- `--dag-file PATH` -- DAG JSON file (required)
+- `-m MODEL` -- model (default: `claude-opus-4-6`)
+
+### Step 4: Coding
+
+The coding agent writes code, runs all quality checks, and iterates until
+everything passes. Starts with Sonnet for cost efficiency; automatically
+escalates to Opus if it gets stuck.
+
+```bash
+aofire-coding-agent "Implement the URL shortener from the accepted design" -d ./shortener --dag-file shortener.json
+```
+
+Pass `--dag-file` to give the coding agent the ontology as structured design
+context. The agent sees entities, module specs, function signatures, and test
+strategies from the accepted design.
+
+The agent's workflow (11 steps):
+1. Read existing code
+2. Write/modify code
+3. flake8 (complexity <= 5)
+4. mypy --strict
+5. pytest (100% branch coverage)
+6. Iterate on failures
+7. mutmut (100% kill rate)
+8. Fuzz tests for external-input functions
+9. aofire-call-graph taint analysis
+10. Functional test gap analysis
+11. Commit
+
+If the agent can't fix an issue (e.g., needs a `# type: ignore`), it
+presents grouped findings for user approval rather than silently
+suppressing.
+
+Options:
+- `-d DIR` -- project directory (default: `.`)
+- `-m MODEL` -- initial model (default: `claude-sonnet-4-6`)
+- `--max-turns N` -- step limit (default: 30)
+- `--max-budget USD` -- spending cap (default: 5.0)
+- `--dag-file PATH` -- ontology DAG JSON file for design context (optional)
+
+### Backtracking
+
+Re-run convergence on the same DAG to navigate back and try a different
+branch. All intermediate states are preserved:
+
+```bash
+aofire-convergence-agent --dag-file shortener.json
+> back
+> select 2
+> accept
+```
+
+## Standalone Planning Agent
+
+For freeform project design without the ontology pipeline:
+
+```bash
+aofire-planning-agent "A CLI tool that converts CSV to JSON with schema validation"
+```
+
+Uses Opus by default. Produces a structured markdown plan. Type `quit` to end.
+
+## Static Analysis: aofire-call-graph
+
+Source-to-sink taint analysis using Python's `ast` module. Traces data
+flow from external inputs through the call graph to dangerous sinks.
+Each finding tagged with a CWE code.
+
+```bash
+aofire-call-graph src/python_agent/                    # text report
+aofire-call-graph src/python_agent/ --sarif            # SARIF JSON for CI
+aofire-call-graph src/python_agent/ --include-sanitized  # show all paths
+```
+
+Sources detected: `input()`, `json.loads`, `open()`, `.model_validate()`,
+`.parse_args()`, `.query()` (SDK responses).
+
+Sinks detected: `eval`/`exec`, `subprocess`/`os.system`, `.write()`,
+`.query()` (prompt injection), `print()` (info exposure).
+
+Suppress acknowledged findings with mandatory comments:
+```python
+# taint: ignore[CWE-200] -- Interactive agent displays LLM output to user
+async def run(description: str, model: str) -> None:
+```
+
+## Security Hardening
+
+Defense-in-depth across all agents:
+
+| Layer | Defense | Protects Against |
+|-------|---------|-----------------|
+| 1 | `frame_data()` content framing | Prompt injection via embedded data |
+| 2 | HMAC-SHA256 DAG integrity | File tampering between sessions |
+| 3 | Pydantic `BaseModel` validation | Malformed data at construction |
+| 4 | `can_use_tool` callback (tool guard) | Dangerous Bash commands + path escape |
+| 5 | Injection pattern scanner | Common injection phrases in text fields |
+| 6 | Framing escape detection | `</ontology-data>` breakout attempts |
+| 7 | Call graph taint analysis | Unguarded source-to-sink data flows |
+| 8 | Taint suppressions with mandatory comments | Acknowledged risks with audit trail |
+| 9 | User approval workflow | Silent suppression by autonomous agent |
+
+The coding agent's tool guard blocks: `curl`, `wget`, `ssh`, `sudo`,
+`rm -rf /`, `dd`, `mkfs`, `chmod 777`, `chown`, `pkill`, writes to
+`/etc`, `~/.ssh`, `~/.bashrc`. File operations confined to project
+directory.
+
+## The Ontology Format
+
+16 Pydantic models capturing both problem and solution domains:
+
+**Problem domain:** Entity, Property, PropertyType, Relationship,
+DomainConstraint
+
+**Solution domain:** ModuleSpec, ClassSpec, FunctionSpec, DataModel,
+ExternalDependency
+
+**Planning state:** OpenQuestion (unresolved decisions)
+
+**DAG:** DAGNode (ontology snapshots), DAGEdge (design decisions),
+OntologyDAG (the full versioned graph)
+
+Type constraints enforced via `Annotated` types: `SafeId` (alphanumeric,
+max 100 chars), `ShortName` (max 100 chars), `Description` (max 2000
+chars). Enum fields use `Literal` types: `PropertyKind`, `Cardinality`,
+`ModuleStatus`, `Priority`.
+
+## Quality Standards
+
+All code produced by these agents (and the agents themselves) meets:
+
+1. **flake8 clean** with `--max-complexity=5`
+2. **mypy --strict** with zero errors
+3. **100% branch coverage** via pytest (570 tests)
+4. **100% mutant kill rate** via mutmut v2
+5. **Fuzz testing** via hypothesis on all external-input functions
+6. **Call graph taint analysis** with CWE tagging
+7. **Functional test gap analysis** as final verification step
+8. **Prompt injection hardening** across all agents
+
+See `CLAUDE.md` for the complete coding standards.
+
+## Project Status
+
+**Version:** 0.1.0
+
+**What works:**
+- Full ontology pipeline: discovery, divergence, convergence
+- Autonomous coding agent with Sonnet/Opus escalation
+- All security hardening layers active
+- 570 tests, 14 source files, all quality gates pass
+- aofire-call-graph reports clean (no unguarded taint paths)
+
+**What's next:**
+- Wire coding agent to consume ontology nodes as implementation specs
+- End-to-end pipeline test (idea to running code)
+- CI setup (GitHub Actions)
+- Performance requirements as soft ontology constraints (advisory, not blocking)
+- Tier 2 hardening: coding agent command audit log by default
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+
+# Full quality gate
+.venv/bin/flake8 --max-complexity=5 src/ tests/
+.venv/bin/mypy --strict src/
+.venv/bin/pytest --cov --cov-branch --cov-report=term-missing
+.venv/bin/mutmut run
+.venv/bin/pytest tests/test_fuzz.py --hypothesis-profile=ci
+.venv/bin/aofire-call-graph src/python_agent/
+```
+
+## Local PyPI with devpi
+
+```bash
+# Setup (first time)
+pip install devpi-server devpi-client
+devpi-server --init && devpi-server --start --port 3141
+devpi use http://localhost:3141
+devpi user -c myuser password=
+devpi login myuser
+devpi index -c dev bases=root/pypi
+devpi use myuser/dev
+
+# Publish
+devpi upload
+
+# Install from local index
+pip install aofire-python-agent -i http://localhost:3141/myuser/dev/+simple/
+```
+
+## License
+
+BSD 3-Clause. See [LICENSE](LICENSE).

aofire_python_agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+aofire_python_agent-0.1.0.dist-info/licenses/LICENSE,sha256=fOlGyPlQVBNVcSNHKxnZMgHRdWd2yOP430P3qJa-Nh8,1496
+python_agent/CLAUDE.md,sha256=Ysi_gKNMWsQoLwSy2OUBtLwrkXOnznkCFBkRHF3KqYI,7386
+python_agent/__init__.py,sha256=nyQD_E7D_F5fDIBMOMrmLgqXCQInZwf-sl-iq3m2zeo,79
+python_agent/agent_utils.py,sha256=32N8Lq_7DTC7VOBZ48L230TocL0gj7m-FPNWhYLgYNM,1530
+python_agent/call_graph.py,sha256=FxiZ1PKUFfratne_nC7b3nCm1cKAc2pelP6LyLlKLdk,19660
+python_agent/coding_agent.py,sha256=quDblkKDPO9U-MedcUSKtnUxIU43NX7t7gCwgLwmPuM,5310
+python_agent/convergence_agent.py,sha256=d9h4qqAGnU9ttrMK9aw5IgDc0sVyW-JQe6A_SaS6ihE,9675
+python_agent/dag_integrity.py,sha256=LiGaigeH9cvy4jvUehZfWHxFUktY4fTvUg1VvqeicCI,5681
+python_agent/dag_utils.py,sha256=u_qoqii4GYbnOHMSFBOVNN28elOsRgkffH0pFQxxCO8,4596
+python_agent/discovery_agent.py,sha256=K5FE22meadAOVmpu3_K14Cn3PiCFHJYH42qmcvJIvaQ,9495
+python_agent/divergence_agent.py,sha256=O_r4Qwaa_CtmTgHqqvwXQhNNxmkOwy8cgx5PfmSidMo,8067
+python_agent/ontology.py,sha256=1ltUnkdvO9MJBV19KPMwqNOTUcDmgKPo8EjlgVpFnLY,6012
+python_agent/planning_agent.py,sha256=d4ns9e7cSWE0Kmou-9kLNQPE6ugx9OtNA85m6xlnJH8,2275
+python_agent/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+python_agent/rules.py,sha256=BEFXdVtjVTvpvnKR-B1WwAYKHrApkfynmv967Mrm3IM,13003
+python_agent/tool_guard.py,sha256=75s_IJ6VAZVRX4GqZ45amAqyss7SbkKTrSeVCsdFzyM,3967
+python_agent/types.py,sha256=0znWiWxZPAmXvVL3vrBLsmmzpyq3JnMR8ff3dYMaxkg,775
+python_agent/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aofire_python_agent-0.1.0.dist-info/METADATA,sha256=Ka6Ay_o_vQsksD8yGMRHmPs4_18xvnAHNpZTx09Gt64,13887
+aofire_python_agent-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+aofire_python_agent-0.1.0.dist-info/entry_points.txt,sha256=m3NnzPLKLTxQemjfBP5MgH6buLmhC6ZL4wl8jB7tWnc,360
+aofire_python_agent-0.1.0.dist-info/top_level.txt,sha256=Vevsacnx_Xm_bXJtxyGqCbQU69PbzXHe0F1t0ynfgDc,13
+aofire_python_agent-0.1.0.dist-info/RECORD,,

aofire_python_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aofire_python_agent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,7 @@
+[console_scripts]
+aofire-call-graph = python_agent.call_graph:main
+aofire-coding-agent = python_agent.coding_agent:main
+aofire-convergence-agent = python_agent.convergence_agent:main
+aofire-discovery-agent = python_agent.discovery_agent:main
+aofire-divergence-agent = python_agent.divergence_agent:main
+aofire-planning-agent = python_agent.planning_agent:main

aofire_python_agent-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Ed Hodapp
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

aofire_python_agent-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+python_agent

python_agent/CLAUDE.md

@@ -0,0 +1,105 @@
+# Python Agent — Project Instructions
+
+## Python Standards
+
+All Python code must meet these standards before commit:
+
+1. **flake8 clean** — zero warnings, default rules
+2. **McCabe Cyclomatic Complexity <= 5** — `flake8 --max-complexity=5`
+3. **100% branch coverage** — `pytest --cov --cov-branch --cov-report=term-missing`
+4. **pytest** for all tests, **pytest-mock** for mocking
+5. **pyflakes clean** (included in flake8)
+6. **Mutation testing with mutmut** — 100% kill rate required
+   - Use mutmut v2 (`pip install 'mutmut<3'`). v3's test mapping doesn't work with non-standard layouts.
+   - Configure in `pyproject.toml`: `paths_to_mutate`, `runner` (must use `.venv/bin/python`).
+   - The only acceptable survivors are the `if __name__` guard. Everything else must be killed — no exceptions for "cosmetic" code like help strings or log messages.
+   - Surviving mutants = test gaps. Write targeted tests to kill them.
+   - **mutmut wraps mutated strings in `XX...XX`.** To kill string mutants, assert `"XX" not in output` rather than only checking for substrings (which still match inside the wrapped version).
+7. **Fuzz testing with hypothesis** — all functions that accept external inputs
+   - External inputs: user CLI args, SDK messages/results, keyboard input, filesystem paths.
+   - Every such function must have a `@given(...)` test verifying:
+     a. **No unhandled exceptions** — any valid-typed input must not crash.
+     b. **Return type contract** — return type matches the function's contract.
+     c. **Invariants** — domain-specific rules (e.g., `remaining_budget <= max_budget`).
+   - Hypothesis profiles in `tests/conftest.py`: `ci` = 200 examples, `dev` = 50.
+   - Fuzz tests go in `tests/test_fuzz.py`, separate from example-based tests.
+   - Use `io.StringIO` for stdout capture in fuzz tests (hypothesis doesn't support pytest's `capsys` fixture).
+   - Run: `.venv/bin/pytest tests/test_fuzz.py` or with profile: `--hypothesis-profile=ci`.
+8. **mypy --strict** — zero errors
+   - Run: `.venv/bin/mypy --strict src/`
+   - All function signatures must have type annotations (parameters and return types).
+   - Use `Annotated` types from `python_agent.types` for constrained strings.
+   - Use `Literal` types for enum-like fields (not plain `str`).
+   - Use Pydantic `BaseModel` for data structures (not dataclasses).
+   - Add `# type: ignore[<code>]` with specific error codes only for third-party libraries without stubs.
+9. **Call graph taint analysis** — no unguarded source-to-sink paths
+   - Run: `.venv/bin/aofire-call-graph src/`
+   - Traces data flow from external inputs (CLI args, keyboard, file reads, JSON parsing, SDK responses) through the call graph to dangerous sinks (eval, subprocess, file writes, prompt injection).
+   - Each finding tagged with a CWE code. Use `--sarif` for CI integration.
+   - Fix findings by adding sanitizers: `frame_data()` for prompts, Pydantic validation for data, `tool_guard` for commands.
+10. **Functional test gap analysis** — final step after all other checks pass
+   - Read every source function and every test. For each function, enumerate all code paths and identify which are not exercised by any test.
+   - Focus on: integration between components, error propagation, boundary conditions, multi-step flows, and real usage edge cases.
+   - Write tests to close the gaps found. Iterate until no meaningful gaps remain.
+   - This step catches what coverage and mutation testing miss: tests that exist but don't verify the right thing, interactions between functions, and untested error paths.
+
+### Venv
+
+Always use the project venv. Execute Python through `.venv/bin/python3`,
+`.venv/bin/pytest`, `.venv/bin/flake8`, etc. Never use the system Python.
+
+### Before Committing
+
+```bash
+.venv/bin/flake8 --max-complexity=5
+.venv/bin/mypy --strict src/
+.venv/bin/pytest --cov --cov-branch --cov-report=term-missing
+```
+
+The only acceptable uncovered line is the `if __name__` guard (`sys.exit`).
+
+## Correctness
+
+These are foundational. They apply to all code in all languages.
+
+- **No one writes correct code — not humans, not AI.** Confidence without evidence is the most dangerous state. The cost of catching a bug grows exponentially the later it's found. Verify now, not later.
+- **A programmer's critical job is proving their code is correct.** Trust nothing without verification.
+- **Failure handling code that is never tested is a liability.** It can generate new errors when it finally runs. When writing functions with failure paths, discuss whether those paths are reachable under test. If not, discuss the cost of making them testable (e.g., dependency injection so tests can supply fakes).
+- **Prefer parameters over hardcoded values.** Enables dependency injection and testability.
+- **An accidental fix is not a fix — it's a clue.** Ask WHY a change affects behavior before shipping it.
+- **Trace symptoms to code paths, not external theories.** When debugging, grep for what produces the output, trace the loop, ask "what are we not exiting and why?" Step UP in abstraction, don't drill down into speculation.
+
+## Testing Philosophy
+
+These are non-negotiable. They come from hard experience across multiple projects.
+
+- **Tests are part of the implementation, not a follow-up.** Code without tests is not done.
+- **Both sides of every conditional.** Not "the important ones" — ALL of them.
+- **Every test MUST have a meaningful assertion.** Never write a test that calls a function and unconditionally passes. Never write `assert len(x) > 0` when you can assert on the actual value.
+- **Test from multiple angles.** Unit test + functional test on the same path catches different bugs.
+- **Reproduce runtime bugs in tests first.** Write a test that triggers the failure (red), fix the code (green), commit both together.
+- **If unsure what to assert, discuss it first.** "What should this test verify?" is always the right question.
+- **The branch coverage analysis itself finds bugs.** Enumerating every conditional and verifying both sides are exercised catches things tests alone miss.
+- **Mutation testing is the proof.** If a mutant survives, the test is broken.
+
+## Production vs Prototype
+
+Two modes, hard boundary between them:
+
+- **Production code:** Full standards, thoroughly tested, no shortcuts.
+- **Prototype code:** Only when the path forward is unclear. Define the questions it answers upfront. When answered, reimplement from scratch to production standards. Never evolve a prototype into production code.
+
+## Working Style
+
+- Trunk-based development: commit directly to `main`, push after each group of changes.
+- Don't suggest breaks or stopping.
+- When you catch a mistake or unintended change — stop. Understand what changed and why before moving on. Don't rationalize differences away.
+- Never check files into the wrong repo by drifting directories. Stay in this project dir; use absolute paths for anything outside it.
+- Always check if a target file exists before `mv`/`cp`/`Write`. Lost uncommitted work is gone forever.
+- Never hide unexpected messages or errors — fix the source, not the reporter.
+- Revert failed experiments immediately. Only keep changes you have high confidence are correct.
+
+## Git
+
+- Commit after every group of code changes. Don't wait to be asked.
+- Use the git user.name and user.email configured on the system.

python_agent/__init__.py

@@ -0,0 +1,3 @@
+"""Claude-powered Python coding and planning agents."""
+
+__version__ = "0.1.0"

python_agent/agent_utils.py

@@ -0,0 +1,61 @@
+"""Shared helper functions used by multiple agents."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from claude_agent_sdk import TextBlock
+
+_ONTOLOGY_BLOCK_RE = re.compile(
+    r"```ontology\s*\n(.*?)\n```",
+    re.DOTALL,
+)
+
+
+def print_text_blocks(message: Any) -> None:
+    """Print TextBlock content from an AssistantMessage."""
+    for block in message.content:
+        if isinstance(block, TextBlock):
+            print(block.text)
+
+
+def collect_response_text(message: Any) -> str:
+    """Extract concatenated text from an AssistantMessage."""
+    parts: list[str] = []
+    for block in message.content:
+        if isinstance(block, TextBlock):
+            parts.append(block.text)
+    return "\n".join(parts)
+
+
+def read_user_input() -> str | None:
+    """Read a line from the user. Return None to quit."""
+    try:
+        user_input = input("\n> ")
+    except (EOFError, KeyboardInterrupt):
+        print("\nDone.")
+        return None
+    if user_input.strip().lower() in (
+        "quit", "exit", "done",
+    ):
+        return None
+    return user_input
+
+
+def extract_ontology_json(
+    text: str,
+) -> dict[str, Any] | None:
+    """Extract the first ontology JSON block from text.
+
+    Returns the parsed dict, or None if no valid block found.
+    """
+    match = _ONTOLOGY_BLOCK_RE.search(text)
+    if match is None:
+        return None
+    try:
+        result: dict[str, Any] = json.loads(match.group(1))
+        return result
+    except json.JSONDecodeError:
+        return None