@matt82198/aesop 0.1.0-beta.4 → 0.1.0-rc.1

package/docs/README.md

@@ -1,44 +1,193 @@
-# Aesop Documentation Index
+# Aesop Documentation
 
-Aesop is a fable-fleet orchestration harness for Claude Code. It runs fast, cheap delivery waves: parallel Haiku agents, lower cost via Haiku-first dispatch and faster wall-clock via parallel agents.
+Aesop is a fable-fleet orchestration harness for Claude Code. It runs fast, cheap delivery waves: parallel Haiku agents, durable state, observable machinery, security gates.
 
-**New to Aesop?** Start here: [HOW-THE-LOOP-WORKS.md](HOW-THE-LOOP-WORKS.md) — a walkthrough of one wave cycle and why it's productive.
+---
+
+## Adopter Journey (Start Here)
+
+If you're new to Aesop, follow this 4-stage path:
+
+### Stage 1: Install
+**[INSTALL.md](INSTALL.md)** — Prerequisites, `npx` scaffold, what gets created
+
+- System requirements (Claude Code CLI, Git, Bash, Node.js, Python)
+- Quick-start: `npx @matt82198/aesop@beta my-fleet`
+- Manual setup for development (git clone)
+- Pre-push hook installation
+
+### Stage 2: Configure
+**[CONFIGURE.md](CONFIGURE.md)** — aesop.config.json, repos, ports, brain root
+
+- Field reference (`aesopRoot`, `braindRoot`, `repos`, `dashboardPort`, `dashboardOrigin`)
+- Example configurations (single repo, microservices, Windows paths)
+- Security notes (git-ignore config, no secrets in config)
+- Environment variables
 
-For deeper governance + operational rules, see the reference docs below.
+### Stage 3: First Wave
+**[FIRST-WAVE.md](FIRST-WAVE.md)** — Run `/power` then `/buildsystem` end-to-end
+
+- What to expect from each phase (rank → dispatch → verify → close)
+- Monitoring (dashboard, TUI, logs)
+- When agents hang (watchdog protocol, retry cap)
+- Common Q&A (wave duration, cost, cancellation, failure handling)
+
+### Stage 4: Concepts
+**[CONCEPTS.md](CONCEPTS.md)** — Dispatch model, cost, state, security, governance
+
+- The wave cycle at a glance
+- Dispatch model (Haiku-first subagents, cost model, patterns)
+- State & checkpointing (STATE.md, BUILDLOG.md, durable recovery)
+- Security gates (secret-scan, branch discipline)
+- Governance (single-writer files, heartbeat protocol)
+- Reliability core (inputs always produce outputs, pride bar)
+- Links to all deep-dive reference docs
 
 ---
 
-## Quick Start
+## System Architecture
 
-- [HOW-THE-LOOP-WORKS.md](HOW-THE-LOOP-WORKS.md) — Concrete walkthrough of one `/buildsystem` wave (rank → fan out → verify → merge → close)
+**[ARCHITECTURE.md](ARCHITECTURE.md)** — Visual flow diagram + component overview
+
+- Mermaid diagram: orchestrator → parallel fleet → merge train → checkpoint → audit → next backlog
+- Component breakdown (watchdog, monitor, dashboard, durable state)
+- Cost model and scaling characteristics
+- Security model (pre-push hook + GitHub branch protection)
+
+---
 
-## Core Governance & Rules (Reference)
+## Deep-Dive Reference Docs
 
-- [CARDINAL-RULES.md](CARDINAL-RULES.md) — Foundational operational principles (dispatch model, cost, subagent discipline, retry caps)
-- [RELIABILITY.md](RELIABILITY.md) — Reliability core: never wait, inputs always produce outputs, pride bar for completion
-- [CHECKPOINTING.md](CHECKPOINTING.md) — Durable STATE.md/BUILDLOG.md lifecycle, recovery on resume, log rotation patterns
-- [SCRIPTS-POLICY.md](SCRIPTS-POLICY.md) — Local-only execution, shared script library, task-local vs. reusable heuristics
-- [DISPATCH-MODEL.md](DISPATCH-MODEL.md) — Fable/Haiku orchestration patterns and cost calculations
-- [GOVERNANCE.md](GOVERNANCE.md) — Single-instance loops, single-writer files, heartbeat protocol, security gates
+Once you've completed the adopter journey, use these for operational reference:
 
-## The Five Pillars
+### Wave Cycle & Orchestration
+- **[HOW-THE-LOOP-WORKS.md](HOW-THE-LOOP-WORKS.md)** — Concrete walkthrough of one complete `/buildsystem` wave cycle (rank → fan-out → verify → merge → close)
+
+### Dispatch & Cost
+- **[DISPATCH-MODEL.md](DISPATCH-MODEL.md)** — Haiku-first subagent dispatch, cost analysis, patterns (fan-out, sequential, hierarchical)
+
+### State Management & Recovery
+- **[CHECKPOINTING.md](CHECKPOINTING.md)** — STATE.md and BUILDLOG.md lifecycle, recovery on resume, log rotation patterns
+
+### Foundational Principles
+- **[CARDINAL-RULES.md](CARDINAL-RULES.md)** — 10 foundational principles (dispatch model, cost, subagent discipline, TDD, reliability, orchestrator isolation, orchestrator focus, durable handoff, control files, security & version control)
+
+### Operational Governance
+- **[GOVERNANCE.md](GOVERNANCE.md)** — Single-instance loops, single-writer files, heartbeat protocol, inbox pattern, AUTO/PROPOSE action tiers
+
+### Reliability Guarantees
+- **[RELIABILITY.md](RELIABILITY.md)** — Reliability core (inputs always produce outputs, no silent waits, pride bar for completion), failure scenarios, recovery patterns
+
+### Security & Hooks
+- **[HOOK-INSTALL.md](HOOK-INSTALL.md)** — Install and customize `hooks/pre-push-policy.sh` (branch discipline, secret-scan enforcement at push time)
+
+### Team Onboarding
+- **[MEMORY-TEMPLATE.md](MEMORY-TEMPLATE.md)** — Canonical format for team memory and facts (to be stored in `~/.claude/MEMORY.md`)
+
+### Behavioral Review Checklist
+- **[BEHAVIORAL-PR-REVIEW.md](BEHAVIORAL-PR-REVIEW.md)** — Checklist for reviewing PRs that modify rules, policies, or orchestration behavior
+
+### Operational Guides
+- **[FORENSICS.md](FORENSICS.md)** — Reconstruct agent failures using `tools/agent-forensics.sh`; make agent behavior git-debuggable
+- **[RESTORE.md](RESTORE.md)** — Reconstitute Aesop & fleet on a new machine from git + watchdog backups
+- **[PUBLISHING.md](PUBLISHING.md)** — Release Aesop to npm using GitHub Actions with OIDC trusted publishing
+- **[av-resilience.md](av-resilience.md)** — Antivirus and behavioral-engine resilience patterns for reliable agent execution
+
+### Lessons & Case Studies
+- **[autonomous-swe.md](autonomous-swe.md)** — The 0.1.0-rc.1 milestone told honestly: what "autonomous SWE" means here (a fleet running the wave loop under a human who owns the outward gates), the committed evidence behind each claim (held-out benchmark, verified audit, proven kill-switch, reproducible package), and the limits the project owns
+- **[case-study-portfolio.md](case-study-portfolio.md)** — How Aesop built its own portfolio site; full audit trail and cost breakdown
+- **[SCRIPTS-POLICY.md](SCRIPTS-POLICY.md)** — Local-only execution, shared script library (`~/scripts`), task-local vs. reusable heuristics
+
+---
 
-### 1. Onboarding Templates
-- [MEMORY-TEMPLATE.md](MEMORY-TEMPLATE.md) — Canonical index format and structure for team memory & facts
+## Quick Index by Use Case
 
-### 2. Policy Hooks
-- [HOOK-INSTALL.md](HOOK-INSTALL.md) — Install and customize `hooks/pre-push-policy.sh` (branch/secret enforcement at push time)
+**I'm setting up Aesop for the first time**
+→ [INSTALL.md](INSTALL.md) → [CONFIGURE.md](CONFIGURE.md) → [FIRST-WAVE.md](FIRST-WAVE.md)
 
-### 3. Behavioral PRs
-- [BEHAVIORAL-PR-REVIEW.md](BEHAVIORAL-PR-REVIEW.md) — Checklist for reviewing PRs that modify rules, policies, or orchestration behavior
+**I want to understand the cost model**
+→ [DISPATCH-MODEL.md](DISPATCH-MODEL.md) or [HOW-THE-LOOP-WORKS.md](HOW-THE-LOOP-WORKS.md#why-its-fast--cheap)
 
-### 4. Forensics (Git-Bisectable Agent Debugging)
-- [FORENSICS.md](FORENSICS.md) — Reconstruct agent failures using `tools/agent-forensics.sh`; make agent behavior git-debuggable
+**I want to know what's actually proven vs. claimed (the rc.1 milestone)**
+→ [autonomous-swe.md](autonomous-swe.md)
 
-### 5. Restore (Cross-Machine Reconstitution)
-- [RESTORE.md](RESTORE.md) — Reconstitute Aesop & fleet on a new machine from git + watchdog backups after a wipe
+**I need to understand how state survives a crash**
+→ [CHECKPOINTING.md](CHECKPOINTING.md)
+
+**I'm reviewing a PR that changes orchestration behavior**
+→ [BEHAVIORAL-PR-REVIEW.md](BEHAVIORAL-PR-REVIEW.md)
+
+**An agent failed and I need to debug it**
+→ [FORENSICS.md](FORENSICS.md)
+
+**I need to set up Aesop on a new machine after a wipe**
+→ [RESTORE.md](RESTORE.md)
+
+**I want to release a new version of Aesop**
+→ [PUBLISHING.md](PUBLISHING.md)
+
+**I'm experiencing reliability issues**
+→ [RELIABILITY.md](RELIABILITY.md) or [GOVERNANCE.md](GOVERNANCE.md)
+
+---
+
+## Architecture Diagram (Quick Reference)
+
+```
+Ranked Backlog
+     ↓
+Orchestrator (main thread)
+     ↓
+Parallel Haiku Fleet (worktrees)
+  [test] [build] [docs] [ui] ...
+     ↓
+Watchdog (heartbeat + respawn)
+     ↓
+Integration Merge Train
+     ↓
+Checkpoint (STATE.md + BUILDLOG.md)
+     ↓
+Closing Audit (findings)
+     ↓
+Monitor + Dashboard (signals)
+     ↓
+Next Backlog (feedback loop)
+```
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full diagram and component breakdown.
+
+---
+
+## Quick Answers
+
+**Q: How do I start a wave?**
+A: Type `/power` to prime your orchestrator brain, then `/buildsystem` to start a wave cycle. See [FIRST-WAVE.md](FIRST-WAVE.md).
+
+**Q: How much does a wave cost?**
+A: ~$0.03–$0.05 USD (1 Opus orchestrator + 5–8 Haiku agents). See [DISPATCH-MODEL.md](DISPATCH-MODEL.md).
+
+**Q: What if an agent hangs?**
+A: The watchdog detects it (>200s idle), respawns automatically (up to 3 retries), then surfaces to you if still stuck. See [CARDINAL-RULES.md](CARDINAL-RULES.md).
+
+**Q: How do I add my repos?**
+A: Edit `aesop.config.json` and add paths to `repos` array. See [CONFIGURE.md](CONFIGURE.md).
+
+**Q: Do agents work in the primary tree?**
+A: No. Each agent works in its own sibling worktree (via `git worktree add`). See [ARCHITECTURE.md](ARCHITECTURE.md).
+
+**Q: How do I set up secret-scan?**
+A: The pre-push hook is auto-installed. Customize `tools/secret_scan.py` with your rules. See [HOOK-INSTALL.md](HOOK-INSTALL.md).
+
+---
+
+## Contributing
+
+Aesop is **source-available** under the PolyForm Strict License 1.0.0, which doesn't permit modification or redistribution — so outside code patches can't be merged as contributions. **Issues, bug reports, and discussion are warmly welcome**, and are the best way to help. The repo develops itself via its own `/buildsystem` loop; code changes are made by the maintainer at their discretion, or by prior arrangement.
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for details and [CARDINAL-RULES.md](CARDINAL-RULES.md) for core principles.
+
+---
 
-## Operational Guides
+## License
 
-- [PUBLISHING.md](PUBLISHING.md) — Release Aesop to npm using GitHub Actions with OIDC trusted publishing
-- [av-resilience.md](av-resilience.md) — Antivirus & behavioral-engine resilience patterns for reliable agent execution
+**Source-available** under the [PolyForm Strict License 1.0.0](../LICENSE). Use is permitted for a permitted purpose; **modification and redistribution are not**. See [`LICENSE`](../LICENSE) for full terms.

package/docs/RELEASING.md

@@ -0,0 +1,159 @@
+# Releasing Aesop
+
+This document covers the release process for Aesop: version bumping, git tagging, GitHub release creation, and npm publishing with beta dist-tag support.
+
+## Release Types
+
+Aesop follows semantic versioning: `MAJOR.MINOR.PATCH[-PRERELEASE]`
+
+- **Stable (0.1.0)**: Core orchestration engine stable; backward-compatible API
+- **Beta (0.1.0-beta.N)**: Pre-release builds; may have breaking changes; uses `@beta` npm dist-tag
+- **Patch (0.1.0-beta.N+M)**: Fixes within a beta series; increments local version only
+
+## Full Release Workflow
+
+### 1. Version Bump (`npm version`)
+
+```bash
+# From repo root, on a `release/*` or `docs/*` branch (never main)
+npm version minor       # for 0.1.0 → 0.2.0 (stable)
+npm version prerelease  # for 0.1.0 → 0.1.1-rc.0 (next beta)
+npm version patch       # for 0.1.0-beta.4 → 0.1.0-beta.5 (current beta)
+```
+
+This command:
+- Updates `package.json` version field
+- Creates a git commit `"v<version>"` (only if git is clean)
+- Creates an annotated git tag `v<version>`
+- Does NOT push (safe for local preview)
+
+**Pre-check**: Ensure:
+- `package.json` files in repo (root + `ui/web/`) are in sync
+- No uncommitted changes (git status clean)
+- `dist/` is up-to-date (npm run build if needed)
+
+### 2. Verify the Tag Locally
+
+```bash
+# Check the tag was created and points to the right commit
+git tag -l | tail -5
+git show v0.1.0-beta.5
+```
+
+### 3. Push to Git Remote
+
+```bash
+# Push the branch and the new tag
+git push origin docs/wave15-currency
+git push origin v0.1.0-beta.5
+```
+
+This makes the tag available for GitHub release creation.
+
+### 4. Create GitHub Release
+
+GitHub Actions CI automatically creates a release from the tag when pushed. Or manually via GitHub web UI:
+
+1. Go to [Releases](https://github.com/matt82198/aesop/releases)
+2. Click "Create a new release"
+3. Select `v0.1.0-beta.5` from the tag dropdown
+4. Title: `Aesop 0.1.0-beta.5`
+5. Body (auto-generated or manual):
+   ```markdown
+   ## What's New
+   - State-sourced SQLite backing store (Wave-15)
+   - Self-building stats via tools/self_stats.py
+   - MCP fleet server integration
+   - Alert webhook bridge
+   - Onboarding wizard (interactive scaffolder)
+   - Healthcheck skill for liveness probes
+   
+   ## Install
+   ```bash
+   npm install @matt82198/aesop@beta
+   ```
+   
+   See [CHANGELOG.md](CHANGELOG.md) for the full list.
+   ```
+6. **For beta releases**: Check "This is a pre-release"
+7. Click "Publish release"
+
+### 5. Publish to npm
+
+```bash
+# Login (if not already authenticated)
+npm login
+
+# For stable releases (0.1.0)
+npm publish --access public
+
+# For beta releases (0.1.0-beta.5)
+npm publish --access public --tag beta
+
+# Verify the tag was set
+npm view @matt82198/aesop@0.1.0-beta.5 | grep dist-tags
+# Should output:
+#   'dist-tags': { latest: '0.1.0', beta: '0.1.0-beta.5' }
+```
+
+**Pre-check before publish**:
+- `npm run test:all` passes (all test suites green)
+- `npm run build` succeeds in ui/web/
+- `dist/` is committed and up-to-date
+- Changelog is current (CHANGELOG.md updated)
+- No local uncommitted changes
+
+## Verification Checklist
+
+After publishing, verify the release is live:
+
+```bash
+# Check npm registry
+npm view @matt82198/aesop@latest     # Should show latest stable
+npm view @matt82198/aesop@beta       # Should show latest beta
+
+# Install in a test dir and verify
+mkdir /tmp/aesop-test && cd /tmp/aesop-test
+npm install @matt82198/aesop@beta
+node -e "console.log(require('./package.json').dependencies)"
+```
+
+## Rollback (if needed)
+
+If a release has a critical bug:
+
+1. **npm**: Deprecate the bad version
+   ```bash
+   npm deprecate @matt82198/aesop@0.1.0-beta.5 "Critical bug; use @beta instead"
+   ```
+
+2. **GitHub**: Delete the release from the web UI (Releases → click release → Delete)
+
+3. **Git**: Delete the tag locally and remotely
+   ```bash
+   git tag -d v0.1.0-beta.5
+   git push origin :refs/tags/v0.1.0-beta.5
+   ```
+
+4. **Branch**: Reset the version bump commit (if desired)
+   ```bash
+   git reset --soft HEAD~1
+   # Edit package.json back to previous version
+   git add package.json
+   git commit -m "Revert: v0.1.0-beta.5 (critical bug)"
+   git push origin <branch>
+   ```
+
+## Notes
+
+- **The `@latest` dist-tag** is reserved for stable releases (no prerelease suffix). Beta releases stay under `@beta`.
+- **Semver gaps**: If beta.4 was skipped, beta.5 jumps directly. No backfilling needed.
+- **Prereleases don't block stable**: Users on `npm install @matt82198/aesop` get the latest stable, not the latest beta.
+- **Local version suffix**: If you need to publish a local build for testing, use `0.1.0-beta.5+local.1` (won't be published to npm, only for local installs).
+
+## References
+
+- [npm version](https://docs.npmjs.com/cli/v8/commands/npm-version)
+- [npm publish](https://docs.npmjs.com/cli/v8/commands/npm-publish)
+- [npm dist-tags](https://docs.npmjs.com/cli/v8/commands/npm-dist-tag)
+- [Semantic Versioning](https://semver.org/)

package/docs/archive/README.md

@@ -0,0 +1,3 @@
+# Archived Spike Investigations
+
+Spike investigations that were cancelled or superseded; kept for reference and historical context.

package/docs/{spikes → archive/spikes}/tiered-cognition/README.md

@@ -1,8 +1,6 @@
 # Tiered Cognition/Execution — spike + staged wave-12 artifact
 
-> **STATUS: STAGED, NOT ACTIVATED.** Nothing in this directory is wired into
-> `~/.claude/settings.json` or `~/.claude/hooks/`. The live model-policy hook
-> (`force-haiku-subagents.mjs`) is untouched and still governs the fleet.
+> **STATUS: CANCELLED 2026-07-14** after A/B testing measured 4.6x weighted cost for identical quality (see MEMORY.md wave-11 entry). Kept for reference; do not activate. Nothing in this directory is wired into `~/.claude/settings.json` or `~/.claude/hooks/`. The live model-policy hook (`force-haiku-subagents.mjs`) is untouched and still governs the fleet.
 
 ## Contents
 

package/docs/autonomous-swe.md

@@ -0,0 +1,149 @@
+# It shipped itself: the 0.1.0-rc.1 milestone, told honestly
+
+Aesop reached its first release candidate — `0.1.0-rc.1` — by running its own
+`/buildsystem` wave loop across the backlog that produced it: rank work, fan out
+parallel Haiku workers on file-disjoint domains, watchdog them, verify merges,
+close with an audit that seeds the next wave. This document is the honest account
+of what that milestone is and is not. Aesop's entire premise is candor, so the
+caveats here are load-bearing, not fine print.
+
+## What "autonomous SWE" means here
+
+It means something specific and narrow:
+
+> The **fleet** autonomously runs the wave loop — audit → parallel build → verify →
+> merge-train — under a **human** who sets the goals and owns the outward gates.
+
+Concretely:
+
+- **The fleet drives the loop.** Ranking, dispatch, worktree isolation, verification,
+  and the merge train run without a human hand-writing the code in each domain.
+- **A human owns the outward gates.** npm publishes, tagged releases, and git history
+  rewrites are all human-approved. The fleet proposes; a person disposes at the
+  repo boundary.
+- **The dispatch core is out-of-repo.** The actual model calls happen inside the
+  Claude Code harness, which is *not* part of this repository. What Aesop ships is
+  the machinery *around* that core — orchestration rules, guardrails, durable state,
+  the dashboard, and tooling.
+
+What it is **not**: it is not an unsupervised agent, not a hosted control plane, and
+not AGI. Calling it "autonomous SWE" is accurate only with those boundaries stated.
+Drop them and the phrase becomes hype.
+
+## The evidence, and the honest limit on each
+
+The milestone's real differentiator is not that an AI wrote code — plenty of tools do
+that. It is that the credibility and safety claims ship with **committed artifacts a
+skeptical reader can check**, each paired with the limit the project already owns.
+
+### 1. Haiku is good enough for the judgment work a fleet does
+
+The harness's whole cost model depends on cheap Haiku workers being adequate for
+subagent judgment, not just extraction. That was long asserted from the fleet grading
+its own output — agents vouching for agents, recorded in a private memory file. Not
+evidence an outsider can check.
+
+`bench/` plus `tools/bench_runner.py` replace that with a **held-out benchmark scored
+by plain Python string/regex matching — no model, no agent in the grading loop**.
+Across a combined **39 judgment tasks** (spanning bug-in-diff, finding-inflation,
+acceptance-criteria coverage, severity calibration, root-cause-from-trace,
+refactor-equivalence, and security-spotting):
+
+| Model  | Score | Cost (per-token) |
+| ------ | ----- | ---------------- |
+| Haiku  | **39/39 (100%)** | ~1/3 of Opus |
+| Sonnet | 39/39 (100%) | — |
+| Opus   | 38/39 (97%)  | baseline |
+
+On the single task any model missed — a severity call — it was *Opus* that erred, not
+Haiku. Full dated runs: [`bench/results/`](../bench/results/).
+
+**Honest limits (the project's own words):**
+
+- **Curated, not sampled.** The tasks were constructed by reasoning about fleet work,
+  not drawn from real fleet transcripts. Selection bias remains.
+- **N=39 is bigger, not statistically large.** Treat this as directional evidence for
+  this workload, not a universal law.
+- **It measures a floor, not the frontier.** The benchmark found *no* task where Opus
+  beats Haiku. So the defensible claim is bounded: *Haiku is sufficient for the
+  judgment shapes measured here*, **not** *Haiku equals Opus at the reasoning
+  frontier*. If tasks exist where Opus's depth is worth 3×, this set hasn't captured
+  them.
+- **Cost is the token-price ratio**, not measured wall-clock latency.
+
+### 2. Audits stop hallucinating findings
+
+An earlier wave (wave-24) exposed a real failure mode: an all-Haiku audit reported
+four P0 issues, **zero of which were real**. The release audit for this RC was run
+with **adversarial verification of every finding** and closed with **0 hallucinated
+issues**.
+
+**Honest limit:** it is an internal audit. No third party has re-run it.
+
+### 3. The kill-switch actually aborts a wave
+
+A halt control is only worth the claim if it's proven. The fleet-wide kill-switch
+([`tools/halt.py`](../tools/halt.py)) is wired into the **live dispatch path** and was
+exercised end-to-end: a single signal **aborted a real wave with zero workers
+spawned**.
+
+**Honest limit:** it is operator-triggered — a manual brake a human pulls, not an
+autonomous safety monitor that trips on its own.
+
+### 4. A cost ceiling brakes runaway spend
+
+A per-wave spend ceiling ([`tools/cost_ceiling.py`](../tools/cost_ceiling.py)) halts
+dispatch when the configured budget is exceeded.
+
+**Honest limit:** it brakes against a **configured** ceiling; it is **not yet tied to
+live token spend**. It's a guardrail you set, not a live meter.
+
+### 5. The package installs and reproduces from a clean clone
+
+The npm tarball is a **~409 kB** package (measured via `npm pack`) that **builds and
+validates from a fresh clone in CI** — the `reproduce` workflow proves the tarball is
+self-contained. The dashboard views shipped this RC (Wave PR Board, Agent Inspector)
+were **browser-proven** with Playwright. Steps to reproduce offline:
+[docs/reproduce.md](./reproduce.md).
+
+**Honest limit:** the offline reproduce job runs the test suites and the benchmark
+*scorer*; it does **not** run real-model benchmark calls or the Playwright browser
+proofs, which need local setup and (for the models) API keys.
+
+## The limits the project owns, in one place
+
+None of these are hidden, because hiding them would betray the one thing the project is
+actually selling — candor:
+
+1. **The benchmark is curated (N=39), not transcript-sampled.** Directional, not
+   definitive; it maps a floor, not the frontier.
+2. **The real dispatch core is out-of-repo.** It runs in the Claude Code harness. This
+   package is the harness around it, not a turnkey autonomous runtime.
+3. **No third party has reproduced any of it yet.** The artifacts are committed so a
+   skeptic can — that is transparency, not a substitute for independent replication.
+4. **The cost ceiling is a brake, not a live meter.** It enforces a configured budget,
+   not measured spend.
+5. **It is local-first.** State lives in git and local files; there is no hosted
+   control plane. Team scale beyond one machine is on the roadmap, not shipped.
+6. **It is a release candidate.** APIs, config, and dashboard contracts may still shift
+   before 0.1.0. Pin the exact version if you need stability.
+
+## Where to check the receipts
+
+- [`bench/results/`](../bench/results/) — dated benchmark runs (v1 extraction, v2 & v3
+  judgment), each with its own honest interpretation and limits.
+- [`bench/README.md`](../bench/README.md) — why the benchmark exists and how the scoring
+  removes agents from the grading loop.
+- [`tools/halt.py`](../tools/halt.py), [`tools/cost_ceiling.py`](../tools/cost_ceiling.py)
+  — the kill-switch and cost-ceiling implementations.
+- [docs/reproduce.md](./reproduce.md) — reproduce the tests and benchmark scorer from a
+  clean clone.
+- [RELEASE-NOTES.md](../RELEASE-NOTES.md#honest-limits) — release-level "Honest limits".
+- [CHANGELOG.md](../CHANGELOG.md) — the full `0.1.0-rc.1` entry.
+
+---
+
+The one-line version: **the fleet built, tested, audited, and benchmarked its way to a
+shippable release candidate, and every claim about that comes with a committed artifact
+and a stated limit.** That combination — self-built *and* honest about the seams — is
+the milestone.

package/docs/case-study-portfolio.md

@@ -0,0 +1,61 @@
+# Case Study: Portfolio Site Build with Aesop
+
+## What Happened (Timeline)
+
+| Time | Event | Duration |
+|------|-------|----------|
+| 17:09 | User prompt: "build me a portfolio site" | — |
+| 17:09–17:20 | 6 discovery scouts (GitHub API, Medium, LinkedIn, Reddit ×2, Playwright fallback, repo deep-dive) run in parallel; 4 ranked decision points surfaced | 11 min |
+| 17:20–17:24 | User answers 4 prioritization questions | 4 min |
+| 17:24–17:36 | 10 Haiku agents (scaffold + 8 section builders on file-disjoint Astro components + integrator) execute | 12 min |
+| 17:36–17:37 | 9th section added from late Reddit data; Astro build green in 914ms | 1 min |
+| 17:37–17:40 | Playwright screenshot proof round 1: CSS 404 detected (styles linked as `/src/` instead of `/dist/`) | 3 min |
+| 17:40–17:42 | Repair agent fixes CSS paths; proof round 2 validates fix | 2 min |
+| 17:42–17:48 | GitHub agent: secret-scan (10,066 files clean), create public repo, merge PR #1 | 6 min |
+| 18:04 | GitHub Pages deployed and live at https://matt82198.github.io/ (verified 200 status) | **55 min total** |
+
+## The Architecture
+
+**Parallel discovery with verified facts only**: Six independent scouts (HTTP fallback to Playwright for bot-blocked sites) collected portfolio inspiration, ranked by relevance; each returned structured data on a single contract. No hallucination—every section claim traces to a source.
+
+**File-disjoint fan-out**: 8 section agents each owned one `.astro` component with zero file overlap; no merge conflicts, no serialization bottleneck. Integrator assembled in 12 minutes.
+
+**Proof-driven QA**: Screenshot verification caught a real ship-blocker—styles in dist/ referenced `/src/` paths that vanished at build time. No visual inspection could have found this; Playwright proved it was broken, repair proved it was fixed.
+
+**Gated ship**: Secret-scan gate (10,066 files) ran before public repo creation; zero credentials leaked. PR merged, Pages deploy triggered, liveness confirmed.
+
+**Orchestrator final-catch**: Fable verified theme coherence across 9 sections after assembly; caught one color inconsistency and one missing accent variant before ship.
+
+## What Failed (and Was Caught)
+
+The site rendered unstyled in production. Astro build succeeded locally (914ms), but the distributed `.astro` component agents—writing styles inline—used `import` statements pointing to source paths. After minification and bundling into `/dist/`, those paths no longer existed. The site shipped with no CSS.
+
+Playwright screenshot automation caught this in production-like conditions (rendering against the compiled bundle). A repair agent updated path resolution, regenerated the build, and Playwright proved the fix before merge. This is not a testing infrastructure story—this is proof automation as a first-class gate.
+
+## Numbers
+
+- **Wall-clock time**: 55 minutes (first prompt to live site)
+- **Total agents used**: ~30 (6 scouts, 10 builders, 1 repair, 1 GitHub ops, 3 proof/integration, 9 audits)
+- **Build fleet**: 10 Haiku agents (scaffold + 8 section builders + integrator)
+- **Build time**: 12 minutes (including inter-agent coordination)
+- **Sections delivered**: 9
+- **Proof rounds**: 2 (CSS 404 caught in round 1; fix validated in round 2)
+- **Ship-blockers caught**: 1 (CSS 404)
+- **Files secret-scanned**: 10,066 (0 issues)
+- **Subagent tokens**: ~328K
+- **PR**: #1, merged
+- **Deploy**: GitHub Pages, live 200 status
+
+## How to Reproduce
+
+1. Fork this repo or set up Aesop in your environment.
+2. Run the [buildsystem skill](/skills/CLAUDE.md) for a portfolio project.
+3. Provide 4–6 source URLs or inspiration topics; Aesop will dispatch 6 discovery scouts.
+4. Approve the ranked backlog (user decision round).
+5. Aesop dispatches the 10-agent build workflow in parallel on Astro or your framework.
+6. Screenshot proof runs automatically; Aesop fixes any visual defects and re-proves.
+7. Secret-scan gate runs; if clean, Aesop creates the public repo and merges the PR.
+8. Pages (or your host) deploys automatically.
+
+The 55-minute bound is achievable when discovery sources are web-accessible (not gated PDFs) and the component schema is well-defined (Astro's `.astro` files are ideal; monolithic templates require serialization).
+