Bootstrap hotpath from engineering spec v0.1

Commit the spec and scaffold the system it describes:

- SPEC.md: the full v0.1 engineering spec
- crates/: trust-layer Rust workspace, unit-tested
  - bench-runner: interleaved ABAB scheduling with discarded warm-ups,
    deterministic bootstrap CIs over the ratio of medians,
    CI-lower-bound accept rule, env fingerprinting, and a CLI with
    compare + A/A self-test modes (A/A verified passing end-to-end)
  - diff-test: gate outcome model, sha256 corpus pin verifier that
    refuses on mismatch, per-target equivalence policy parser
    (byte-identical default, explicit fp-tolerance opt-in)
  - ledger: append-only SQLite attempt schema with UPDATE/DELETE
    refused by triggers, anti-double-attempt query
  - report: cores-saved and dollars/yr ROI math over speedup CIs,
    pricing.toml inputs
- playbook/: classes 1-7 with preconditions, procedure, verification
  notes, and known failure modes per class
- agent/: Python package skeleton — six-tool contract and prompting
  spine, harness IPC deferred to Phase 1
- config/: accept.toml (2% threshold, 30 runs/side), pricing.toml
- targets/, corpora/, results/calibration/: layout and policy docs

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EcKPWQ3MQD4NdEHwar96u2

agent/hotpath_agent/__init__.py

@@ -0,0 +1,10 @@
+"""hotpath agent (SPEC §3.5).
+
+The agent is the *untrusted* half of the system. It reads profiles, the
+ledger, and the playbook; it proposes patches and requests verdicts. It
+never holds a shell on the host, never writes outside targets/<name>/,
+and never touches crates/, config/, or corpora/ — enforced by the
+harness and filesystem permissions, not by this code or any prompt.
+"""
+
+__version__ = "0.1.0"

agent/hotpath_agent/prompts.py

@@ -0,0 +1,31 @@
+"""Prompting spine (SPEC §3.5). The system prompt is versioned code, not
+a config knob: changes here change what the ledger's attempts mean."""
+
+SYSTEM_PROMPT = """\
+You are hotpath, a performance-optimization agent. You operate in a loop:
+profile -> rank hotspots -> select playbook class -> hypothesize -> patch
+-> gates -> bench -> verdict -> ledger.
+
+Rules, in priority order:
+
+1. State your hypothesis BEFORE proposing a patch: which hotspot, which
+   playbook class, what mechanism, and what speedup you expect. The
+   hypothesis is recorded verbatim in the ledger.
+
+2. Prefer the cheapest untried playbook class for the current hotspot.
+   Check the ledger first; never re-attempt a (hotspot, class,
+   hypothesis) combination that already has a verdict.
+
+3. At most two iterations per rejected hypothesis. After the second
+   rejection, move to the next class or the next hotspot.
+
+4. A rejection with a clean ledger row is a successful outcome. You are
+   measured on the integrity of the ledger, not on acceptance rate.
+   Never restructure a patch to influence measurement rather than to
+   express the hypothesis.
+
+5. Equivalence is not yours to relax. Floating-point flag changes,
+   concurrency-primitive changes, and new unsafe code are routed to
+   human review automatically; do not attempt to phrase a patch to
+   avoid that routing.
+"""

agent/hotpath_agent/tools.py

@@ -0,0 +1,59 @@
+"""Tool surface exposed to the model (SPEC §3.5).
+
+Exactly six tools, all mediated by the trust-layer harness over IPC —
+the agent process has no direct filesystem or shell capability beyond
+what these return. Deliberately NOT exposed: shell on the host, writes
+outside targets/<name>/, any access to crates/, config/, corpora/.
+
+Phase 2 wiring: each function below becomes a Claude Agent SDK tool
+definition whose implementation calls the harness. The signatures and
+docstrings are the contract; the bodies are placeholders until the
+harness IPC exists (Phase 1 exit criteria).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+class HarnessUnavailable(RuntimeError):
+    """Raised until the Phase 1 trust-layer harness IPC is wired up."""
+
+
+def read_profile(target: str) -> dict[str, Any]:
+    """Latest profile for a target: ranked hotspots (symbol, exclusive %,
+    source mapping) plus perf stat counters. Read-only."""
+    raise HarnessUnavailable("profiler adapter not wired (Phase 1)")
+
+
+def read_ledger(target: str) -> list[dict[str, Any]]:
+    """All prior attempts against this target — the anti-double-attempt
+    memory. The agent must not re-grind a (hotspot, playbook_class,
+    hypothesis) combination that already has a verdict."""
+    raise HarnessUnavailable("ledger IPC not wired (Phase 1)")
+
+
+def read_playbook(class_number: int) -> str:
+    """Playbook class markdown (1-7): preconditions, procedure,
+    verification notes, known failure modes."""
+    raise HarnessUnavailable("playbook IPC not wired (Phase 1)")
+
+
+def read_target_source(target: str, path: str) -> str:
+    """Read-only view of the target's source tree at the pinned commit."""
+    raise HarnessUnavailable("source IPC not wired (Phase 1)")
+
+
+def propose_patch(target: str, diff: str, hypothesis: str) -> str:
+    """Submit a unified diff plus the hypothesis it tests. The harness
+    applies it via `git apply` after a path-allowlist check (SPEC §10);
+    a diff touching anything outside targets/<target>/ is auto-rejected
+    before any gate runs. Returns a patch id."""
+    raise HarnessUnavailable("patch IPC not wired (Phase 1)")
+
+
+def run_verdict(patch_id: str) -> dict[str, Any]:
+    """Run the full gate + bench sequence on a proposed patch and return
+    the ledger row (gates, bench CIs, verdict). This is the only way the
+    agent ever learns whether a change 'worked' — there is no other
+    number to optimize."""
+    raise HarnessUnavailable("verdict IPC not wired (Phase 1)")

agent/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "hotpath-agent"
+version = "0.1.0"
+description = "hotpath optimization agent: the untrusted proposer in the profile→patch→verdict loop"
+requires-python = ">=3.11"
+dependencies = [
+    "claude-agent-sdk>=0.1",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["hotpath_agent"]