hashloom: Instructions file for Claude Code

Working rules for hashloom

Hashloom 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 — 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. (The shared-cache backend python -m hashloom.cache_server is a deliberate operational process, not a 6th CLI command — the client surface stays 5/5.)

Hashloom develops on hashloom

The repo is itself a hashloom project: contracts/ holds contracts for the stable seams (the five api.py functions, the contract.py hashing trio, impl_hash, verification_key, HashloomError, the Store Protocol, the LanguageAdapter seam behind the per-extension adapters, and the cache_protocol wire spec — spec-only, no impl to verify). The workflow from docs/getting-started.md applies here:

• The hashloom MCP server is project-configured in .mcp.json (uv run hashloom serve). When its tools are present, prefer get_contract packets and get_dependents over reading a contracted seam's source file — the ~300-token packet is the token-frugal path this project exists to prove; fall back to file reads only for uncontracted code.
• Before changing a contracted seam, check the blast radius (the get_dependents MCP tool when connected — it is not a CLI command); after touching one, uv run hashloom verify --radius <name> must return ok: true — that is the inner-loop gate.
• A new stable seam gets a contract before its implementation. If you (the agent) derived the contract rather than the user specifying it, mark it status: inferred; the user flips it to confirmed on review. hashloom status lists the review queue.
• Do not contract churning interiors. The cache server's wire protocol is contracted (cache_protocol — it became a compatibility surface when the v0.5 hosted-store theme shipped), but the module interiors behind it — remote.py, cache_server.py, shared.py — stay uncontracted: their store-facing obligations are Store's, the wire's are cache_protocol's. Helpers (tokens.py, project.py) are weft. Pinning interiors is the failure mode the README warns about.
• The hashloom gate layers on the DoD — it never replaces it. Full uv run pytest and the benchmark below remain the definition of done; hashloom's cached verify must not be the only thing vouching for hashloom.