heddle-mcp 0.1.0__tar.gz

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

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+# cancel superseded runs on the same ref (e.g. rapid pushes)
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Sync deps
+        run: uv sync --frozen --python ${{ matrix.python-version }}
+      - name: Run tests
+        # hash-stability suites are load-bearing; e2e spawns the real stdio server
+        run: uv run --python ${{ matrix.python-version }} pytest -q
+
+  benchmark:
+    name: benchmark (>5x DoD guard)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Sync deps
+        run: uv sync --frozen
+      - name: Token-reduction benchmark
+        # exits nonzero below the 5x definition-of-done line
+        run: uv run python bench/benchmark.py

heddle_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: Release
+
+# Publish to PyPI via Trusted Publishing (OIDC) when a version tag is pushed.
+# No API token is stored: the publish job mints a short-lived OIDC token that
+# PyPI trusts because this repo + workflow + environment are registered there.
+#
+# The published version comes from src/heddle/__init__.py (hatchling reads it
+# as the dynamic version); the tag is only the trigger, so keep the tag and
+# __version__ in sync, e.g. __version__ = "0.1.0" published by tag v0.1.0.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Store the distribution
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # `name` must match the environment in the PyPI pending-publisher form.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/heddle-mcp
+    permissions:
+      id-token: write  # required for Trusted Publishing; no stored secret
+    steps:
+      - name: Download the distribution
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

heddle_mcp-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.heddle/
+.pytest_cache/

heddle_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,75 @@
+# Working rules for heddle
+
+Heddle is a hash-keyed verification cache + content-addressed contract store,
+exposed over MCP. Contracts are warp (durable), code is weft (regenerable). These
+rules override default behavior — follow them.
+
+## Git is the user's
+
+**Commit and push only when the user explicitly asks** — never on your own, and
+write **no `Co-Authored-By` trailer** when you do. The user owns the PR/merge flow
+and brings local back to a clean, synced `main` before each new piece of work.
+
+**A fresh branch per change.** The first action on any new feature/change is
+`git switch -c <scoped-name>` off `main` — never commit to `main`, and never reuse
+a previous feature branch for new work. One piece = one branch = one PR.
+
+**Never git worktrees** — too much machinery for this project; the user dislikes
+them. Don't reach for worktree isolation.
+
+## Scope discipline
+
+Anything not on the current milestone is an entry in [ISSUES.md](ISSUES.md) — file
+it there, don't write the code. The named failure mode is "scope creep toward
+Loom." Keep the surface minimal: **5 MCP tools, 5 CLI commands.** The README
+documents "the entire surface"; if a change would add to it, stop and confirm.
+
+## Definition of done: >5x token reduction
+
+`bench/benchmark.py` is the DoD guard — it exits nonzero below 5x (currently
+5.5x). Run it for anything that could touch the context packets or hashing.
+**Never regress it.**
+
+## Hash stability is load-bearing
+
+`tests/test_contract_hash.py` and `tests/test_implhash.py` are the spec. Cosmetic
+input changes — whitespace, key order, comments, docstrings, file relocation —
+must never change a hash; meaning changes (signature, invariant/example order)
+must. If you touch `contract.py` or `implhash.py`, these tests are the contract.
+Run `uv run pytest` (full suite) before declaring anything done.
+
+## The store is derived
+
+`.heddle/store.db` is rebuildable from `contracts/` via `heddle index` — never
+hand-edit it. `contracts/*.yaml` is the source of truth.
+
+## Errors are structured
+
+Nothing leaks a stack trace over MCP. `_respond` in
+[server.py](src/heddle/server.py) wraps every tool; raise `HeddleError(code,
+message)` for anything an agent should see. Keep it that way.
+
+## The verify interpreter
+
+`verify` shells pytest out to a resolved interpreter (see
+[config.py](src/heddle/config.py)), in precedence order:
+
+1. `heddle serve --python PATH`
+2. `.heddle/config.json` → `{"python": "..."}`
+3. auto-detected project venv (`<root>/.venv/bin/python`, …)
+4. `sys.executable`
+
+So heddle can verify a target project against *its own* venv without being
+installed into it. `heddle status` reports the resolved interpreter.
+
+## How to run
+
+```bash
+uv run pytest                       # full suite — hash stability is load-bearing
+uv run python bench/benchmark.py    # the DoD number
+```
+
+CI (`.github/workflows/ci.yml`) runs both on every push and PR, so the DoD and
+hash-stability rules are enforced, not just documented. Keep it green.
+
+Python >=3.10. Deps: mcp, pyyaml, tiktoken, pytest.

heddle_mcp-0.1.0/ISSUES.md

@@ -0,0 +1,23 @@
+# Filed issues (v0.1 non-goals and follow-ups)
+
+Per the v0.1 spec: if a task isn't on a milestone, it's an issue. These move to
+the GitHub tracker once the repo has a remote.
+
+## Deferred by design (spec non-goals)
+
+1. **Multi-language support** — v0.1 is Python-only (AST hashing and pytest runner are Python-specific). Each language needs a normalised-AST hasher and a test-runner adapter.
+2. **Content-addressed implementation store** — implementations remain plain files on disk; only their hashes live in the store.
+3. **Hosted / team-shared store** — single-process, single sqlite file for now. A shared verification cache across a team is the obvious v0.2 candidate.
+4. **Semantic diff rendering** — `put_contract` reports *that* a contract changed and who is invalidated, not a pretty diff of *what* changed.
+5. **Tessl spec-format compatibility** — import/export adapter for Tessl-style spec files. Format is frozen for v0.1 as specced.
+6. **New syntax of any kind** — contracts stay plain YAML.
+
+## Known limitations / follow-ups
+
+7. **PyPI release** — `pip install heddle-mcp` in the README assumes publication; cut 0.1.0 to PyPI (the bare `heddle` name is held by a third-party placeholder, so the distribution name is `heddle-mcp`).
+8. **README gif** — record the Claude Code → heddle demo loop.
+9. **Pre-existing stale bytecode** — the verification runner passes `-B` / `PYTHONDONTWRITEBYTECODE` so its own runs never cache bytecode, but a stale user-written `__pycache__` (same size, same mtime second) could still be loaded. Consider a `--no-pycache-trust` mode that clears `__pycache__` in the dep closure before running.
+10. **Name finalization** — "heddle" is a working name; rename is a find-and-replace.
+11. **Demo gif** — record the Claude Code → heddle loop; storyboard + exact command sequence in [docs/demo.md](docs/demo.md).
+12. **Contract names are global** — no namespacing/packages; collisions across folders are unhandled (one `contracts/` dir per project for now).
+

heddle_mcp-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

heddle_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: heddle-mcp
+Version: 0.1.0
+Summary: Content-addressed contracts with a hash-keyed verification cache for spec-driven agent loops, over MCP.
+Project-URL: Homepage, https://github.com/davet47/heddle
+Project-URL: Repository, https://github.com/davet47/heddle
+Project-URL: Issues, https://github.com/davet47/heddle/issues
+Author: Dave T
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agents,caching,contracts,mcp,spec-driven
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0
+Requires-Dist: pytest>=8.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tiktoken>=0.7
+Description-Content-Type: text/markdown
+
+# heddle
+
+[![CI](https://github.com/davet47/heddle/actions/workflows/ci.yml/badge.svg)](https://github.com/davet47/heddle/actions/workflows/ci.yml)
+
+**Heddle treats software units as content-addressed contracts rather than files.** An MCP server that makes agent regeneration loops cheap.
+
+Because contracts are content-addressed and dependency-aware, agents reuse verification, compute blast radius precisely, and regenerate code from a few hundred tokens of context instead of re-reading whole files. Build systems ask which files changed. Heddle asks which software obligations changed.
+
+The heddle is the part of a loom that holds the warp threads, the fixed, durable strands, while the shuttle weaves disposable weft through them. **Contracts are warp. Code is weft.**
+
+## The problem
+
+Agents repeatedly pay to rediscover software structure. Spec-driven development tools made specs the durable artifact and code regenerable, but they run on plain files, so every regeneration loop re-derives what the project already knows:
+
+1. **Context acquisition is expensive.** Regenerating one unit means re-reading whole spec and source files: thousands of tokens to learn what a few hundred convey.
+2. **Verification is uncached.** Every regeneration re-runs (and re-reads the output of) the full relevant test surface, even for units whose contracts haven't changed.
+3. **Blast radius is by convention, not mechanism.** When a spec changes, nothing tells the agent precisely which dependents are invalidated.
+
+## The model
+
+Heddle treats each software unit as a content-addressed contract with explicit dependencies, not a file. A contract is a small YAML spec (signature, invariants, examples, dependency names); the implementation behind it is regenerable weft. Because every contract is hashed and its dependencies are named, the structure an agent keeps re-deriving from files becomes something heddle computes once and serves.
+
+## Outcomes
+
+The model buys three things, all mechanical:
+
+- **Verification caching.** A green test result is keyed on the contract, implementation, and dependency hashes, and served from cache until one of them changes. pytest runs only on a real miss.
+- **Mechanical blast radius.** A contract change reports the exact set of invalidated dependents, transitively and by hash, not by convention.
+- **Tiny context packets.** An agent regenerating a unit gets the contract, its dependencies' signatures, and its callers as one packet of a few hundred tokens, instead of the whole file closure.
+
+### The number
+
+Same three regeneration tasks on a 20-contract sample project, once with raw file reads, once through heddle (tiktoken cl100k, reproduce with `uv run python bench/benchmark.py`):
+
+| task                | raw files | heddle | reduction |
+|---------------------|----------:|-------:|----------:|
+| revenue_by_region   |     1,925 |    371 |      5.2x |
+| top_customers       |     2,137 |    334 |      6.4x |
+| revenue_by_category |     1,942 |    392 |      5.0x |
+| **total**           | **6,004** | **1,097** | **5.5x** |
+
+Raw mode counts what a file-based agent reads per task: the unit's spec file, every transitive dep's spec file, every source module in the dep closure, the unit's test file, and the output of running the suite. It is deliberately generous to the baseline: it assumes the agent already knows the exact dependency closure, which is precisely the thing heddle computes for you.
+
+## Quickstart
+
+```bash
+pip install heddle-mcp
+# or from source: pip install "git+https://github.com/davet47/heddle"
+
+cd your-project
+heddle init                 # creates .heddle/ and contracts/
+heddle index                # builds the store from contracts/
+```
+
+Point Claude Code at it:
+
+```bash
+claude mcp add heddle -- heddle serve
+```
+
+(Stdio transport; the server resolves the project by walking up from its working directory to the nearest `.heddle/`.)
+
+## Contracts
+
+One YAML file per unit in `contracts/`. Minimal, hand-writable, hashable:
+
+```yaml
+name: revenue_by_region
+signature: "(sales: list[Sale]) -> dict[Region, float]"
+deps: [Sale, Region]            # other contract names
+invariants:
+  - excludes sales where completed is false
+  - excludes sales with null amount
+examples:
+  - in:  "[Sale(region='QLD', amount=10, completed=True)]"
+    out: "{'QLD': 10.0}"
+tests: [tests/test_revenue.py::test_revenue_by_region]   # pytest node IDs
+impl: src/revenue.py::revenue_by_region                  # current woven weft
+```
+
+Subdirectories are namespaces: `contracts/billing/invoice.yaml` is the contract
+`billing/invoice`, so the same short name can live in different folders. A
+contract's `name` must match its path under `contracts/`.
+
+### When to write a contract
+
+A contract belongs on a stable seam: an interface other units depend on and that you expect to outlive its current implementation. The implementation behind it is disposable weft, regenerated freely. Dropping a contract where it does not earn that place is correct use, not a failure. The failure mode is the opposite, over-pinning interiors you would happily rewrite, which turns the durable layer into busywork.
+
+Contracts are reviewed artifacts. Authoring one is cheap and getting cheaper, so the real cost is reviewing it, not writing it. A wrong contract is worse than no contract, because the durable artifact now lies: agents will regenerate code to satisfy a spec that is itself incorrect. Review a contract the way you review an interface, not the way you skim generated code.
+
+### Hashing semantics
+
+- **Contract hash**: sha256 over a canonical form: keys sorted, whitespace normalised, comments stripped, invariant and example order preserved, dep order ignored. `impl` and `tests` are excluded, so **relocating files never invalidates.** Invariants are free text and live inside this hash, so rewording one without changing its meaning still moves the contract hash and re-verifies every dependent. Behaviour-equivalent prose edits are not free yet (see [Roadmap](https://github.com/davet47/heddle/blob/main/ROADMAP.md)).
+- **Impl hash**: sha256 over the normalised AST of the implementation, so reformatting and comment edits never bust the cache. Docstrings are stripped too.
+- **Verification key**: `(contract hash, impl hash, transitive dep contract hashes)`. Heddle caches verification results, not correctness: a cached green result is served iff the full key matches, and an edit to any contract in the closure forces a re-run. Failures are never served from cache. Two caveats are worth knowing. A cached pass assumes deterministic tests, so a green result that depended on wall-clock time, network, or randomness can outlive the condition that made it pass. And test source is not yet part of the key, so editing a test body without touching the contract or impl does not by itself force a re-run (see [Roadmap](ROADMAP.md)).
+
+## MCP tools (the entire surface)
+
+| tool | does |
+|---|---|
+| `get_contract` | the ~300-token context packet: contract + hash + one-line dep signatures + caller list |
+| `put_contract` | validate, write `contracts/<name>.yaml`, return new hash + every invalidated dependent |
+| `get_dependents` | blast-radius query, direct or transitive, names + hashes |
+| `verify` | per-unit `cached-pass` / `pass` / `fail`; runs pytest only on cache misses; failures come back as a ≤40-token assertion summary, never a traceback |
+| `status` | dirty contracts, stale verifications, cache hit-rate, resolved verify interpreter, cumulative token counters |
+
+Every tool returns structured errors — `{"error": {"code": "unknown_dep", "message": "'Regoin' not found — nearest: 'Region'"}}` — never a stack trace.
+
+### The verify interpreter
+
+`verify` runs your tests with the project's own python, resolved in order:
+`heddle serve --python PATH` → `.heddle/config.json` (`{"python": "..."}`) → an
+auto-detected `<project>/.venv` → the interpreter running heddle. So a
+globally-installed heddle can verify a project against its own virtualenv without
+being installed into it; `heddle status` shows which interpreter it resolved.
+
+`.heddle/config.json` also takes `verify_timeout` (seconds per pytest run,
+default 300) for suites that need longer than the default, and `pycache_trust`
+(default `true`); set `pycache_trust: false` — or pass `--no-pycache-trust` — to
+clear the project's `__pycache__` before each verify run, so a stale `.pyc` can
+never shadow the current source.
+
+## CLI
+
+`heddle init` · `heddle index` · `heddle serve` · `heddle status` · `heddle verify`. The sqlite store under `.heddle/` is derived state: delete it any time and `heddle index` rebuilds it from `contracts/`.
+
+`heddle verify <name>…` runs the same cached verification as the MCP tool from the command line and exits nonzero if any unit fails — drop it in CI or a pre-commit hook.
+
+## Try the sample project
+
+```bash
+cd examples/sales
+heddle init && heddle index && heddle serve   # then point your agent at it
+```
+
+20 contracts, 25 tests, three dependency layers deep.
+
+## Development
+
+```bash
+uv sync
+uv run pytest             # full suite; hash stability is the load-bearing suite
+uv run python bench/benchmark.py
+```
+
+Python-only and single-process by design for v0.1. Everything not in this README is an [issue](ISSUES.md).
+
+## License
+
+Apache 2.0