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

package/CHANGELOG.md

@@ -5,6 +5,182 @@ All notable changes to Aesop are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.1.0-rc.1] - 2026-07-17
+
+First release candidate. The dispatch-model claims are now backed by measurement, the
+kill-switch and cost-ceiling are wired into the live dispatch path and proven, and the npm
+package ships slim and reproducible from a clean clone.
+
+### Added
+- **Verified Opus audit** (wave.26): Full release audit run with adversarial verification — 0 hallucinated findings, closing out the all-Haiku severity-inflation risk (wave-24: 4 reported P0s, 0 real).
+- **Kill-switch wired into dispatch** (wave.27): Fleet-wide halt control is now wired into the dispatch path and proven end-to-end — an operator can stop all agents from a single signal.
+- **Cost-ceiling guardrail** (wave.27): Per-wave spend ceiling halts dispatch when the configured budget is exceeded.
+- **Held-out benchmark measured** (wave.28): Real offline benchmark scorer (`tools/bench_runner.py`) over a held-out ground-truth set of 39 judgment tasks — Haiku scores on par with Opus at roughly 1/3 the cost, replacing the previously illustrative numbers.
+- **State-reconcile primitive** (wave.29): A reconcile primitive compares tracker state against shipped work so already-done items are not re-dispatched at wave open.
+- **Reproduce-from-clean-clone CI** (wave.30): CI job builds and validates the package from a fresh clone, proving the tarball is reproducible and self-contained.
+- **Wave PR Board** (wave.31): Dashboard view aggregating per-wave PR status for at-a-glance merge-train visibility (browser-proven).
+- **Agent Inspector** (wave.31): Drill-down dashboard view exposing individual agent transcripts, cost, and lifecycle (browser-proven).
+
+### Changed
+- **npm package slimmed** (wave.30): Package trimmed to ~400 kB by excluding UI source and node_modules; only built artifacts (`ui/web/dist/`), Python, tools, and docs ship.
+- **Adversarially-verified audits** (wave.25): Full audits now verify Haiku-reported findings before scheduling fixes.
+- **Tracker reconciliation at wave open** (wave.29): Wave startup reconciles the tracker against shipped work so already-done items are not re-dispatched.
+
+### Fixed
+- **CI docs-only deadlock** (wave.30): Broke a docs-gate deadlock that could mask HEAD failures in the CI pipeline.
+- **Waveguard worktree marker resolution** (#165): Fixed pre-commit hook to resolve marker to current worktree instead of hardcoded primary tree path (wave-24 fleet-block incident).
+
+### Tests
+- **Waveguard regression test** (#165): Added Test 7 to prove worktree commits pass while primary tree writes remain blocked by waveguard (wave-24 regression).
+
+## [0.1.0-wave.23] - 2026-07-15
+
+### Added
+- **Adopter-focused documentation restructure** (#164): Reorganized docs into adopter journey with architecture diagram (Mermaid) to improve onboarding clarity.
+- **Runtime CLI subcommands** (#164): Added `aesop watch`, `aesop dash`, and `aesop status` to CLI for real-time fleet monitoring.
+- **Pre-commit waveguard hook** (#164): New write-guard hook prevents stray primary-tree writes during active wave builds; blocks commits outside worktrees.
+
+### Fixed
+- **Tracker projection snapshotting** (#164): Fixed O(n²) replay latency in tracker-snapshotting by caching projection state (wave-19 P2).
+- **Log rotation race condition** (#164): Made `rotate_logs` atomic to prevent concurrent write race when logs exceed size limits.
+- **Dashboard transcript cache** (#164): Optimized `dash-extra.mjs` by caching transcript metadata (path, size, mtime) to reduce redundant reads.
+- **Monitor signal deduplication** (#164): Eliminated double-read of SECURITY-ALERTS.log in monitor signal collector to reduce noise.
+
+### Documentation
+- **Architecture diagram** (#164): Added Mermaid diagram showing fleet machinery layers (orchestrator → monitor → daemons → state).
+- **Adopter journey** (#164): Restructured README and docs to guide new adopters through setup → operations → troubleshooting workflows.
+
+## [0.1.0-wave.22] - 2026-07-15
+
+### Added
+- **GitHub docs overhaul** (#163): Complete README rewrite with "Why Aesop?" problem statement and architectural overview for discoverability.
+- **Aesop doctor preflight** (#163): New `aesop doctor` subcommand validates configuration, hooks, and state-store health before running waves.
+- **Self-building stats automation** (#163): Extended `self_stats.py` to regenerate `stats.json` and detect README stats drift; auto-regenerate in CI.
+- **TypeScript type safety** (#163): Added `tsc --noEmit` CI gate to catch UI type errors before merge.
+
+### Changed
+- **Stats drift enforcement** (#163): README stats block now auto-reconciled by CI; stale stats block push gate enforces freshness.
+
+### Fixed
+- **TypeScript compiler warnings** (#163): Resolved unused variable and type mismatch warnings in UI layer.
+
+### Documentation
+- **README landing rewrite** (#163): Replaced generic boilerplate with concrete "Why Aesop exists" section explaining multi-agent durability and cost optimization.
+- **CHANGELOG reconciliation** (#163): Added missing wave 16-20 dated entries and reorganized unreleased backlog to reflect actual shipped state.
+
+## [0.1.0-wave.21] - 2026-07-15
+
+### Added
+- **CI performance optimization** (#161): Implemented path-based build filters to skip CI on docs-only changes; added Python test parallelization for faster feedback.
+- **Fleet ledger instrumentation** (#161): Added phase and wave tagging to cost ledger for better fleet operations analytics and wave closure reporting.
+
+### Changed
+- **CI trigger-level filtering** (#161): Removed `paths-ignore` from trigger layer (was silently blocking required checks) and moved filtering to job level for correctness.
+
+### Fixed
+- **Python test parallelization** (#161): Parallel test runner now properly isolates test fixtures and state to prevent race conditions.
+
+### Documentation
+- **CI filtering best practices** (#161): Documented correct pattern for docs-only CI bypass (job-level, not trigger-level, to preserve required-check semantics).
+
+## [0.1.0-wave.20] - 2026-07-15
+
+### Added
+- **Fail-closed push gate** (#160): Secret-scan gate now blocks pushes on timeout, preventing silent failures that allow commits to bypass scanning.
+- **UI liveness improvements** (#160): Enhanced SSE cost collection and HealthHeader status display with better timeout handling.
+- **CI state classification** (#160): Improved `ci_merge_wait` handling to distinguish real CI status (success/failure) from temporary waits.
+- **Daemon portability fixes** (#160): Fixed `backup-fleet` and `run-watchdog` for Linux CI environments (path handling, process detection).
+- **Host normalization** (#160): Added consistent URL normalization in UI handler and monitor collectors to reduce false positives.
+- **Monitor cursor improvements** (#160): Enhanced monitor signal collection with better state tracking and recovery.
+
+### Documentation
+- **Currency updates** (#160): README and docs refresh for wave 20 machinery improvements.
+
+### Fixed
+- **UI handler robustness** (#160): Improved error handling in SSE cost collection and API state rendering.
+- **Test harness** (#160): Additional coverage for CI merge state handling and daemon portability.
+
+## [0.1.0-wave.19] - 2026-07-15
+
+### Added
+- **Secret-scan range push gate** (#165): Enhanced push hook with per-range verification to block partial/corrupted scans and prevent silent gate bypasses.
+- **Host-header guard** (#163): HTTP host validation in UI handler to prevent header injection attacks.
+- **CI merge classification** (#162): `ci_merge_wait` now distinguishes real CI status (success/failure) vs temporary waits, improving integration reliability.
+- **Scaffolder manifest completeness** (#161): All 10 template directories (state_store, skills, mcp, scan) verified in npm package; consistent onboarding experience.
+- **UI collector efficiency** (#164): Optimized agent and cost data collection for better freshness and reduced polling overhead; improved SSE contract.
+- **Stall-check test rewrite** (#160): Migrated bare test functions to unittest.TestCase for CI compatibility and better failure reporting.
+- **npm publish OIDC diagnostics** (#158): Self-diagnosing workflow for OIDC token generation and npm publish reliability.
+
+## [0.1.0-wave.18] - 2026-07-15
+
+### Added
+- **Comprehensive audit fixes**: 8-lens security, correctness, a11y, density, shippability, docs, and tools audit with 13 targeted fixes.
+- **Watchdog robustness** (#155): Improved `backup-fleet` and `run-watchdog` daemon stability with better error handling and signal detection.
+- **Pre-push policy hardening** (#155): Enhanced branch protection and secret-scan enforcement in hook execution.
+- **Config management** (#155): Improved aesop.config.json parsing and CLI handling for reliability.
+- **State store hardening** (#155): Fixed concurrency edge cases, improved error recovery, and validated persistence.
+
+### Fixed
+- **Security gates** (#155): Fixed secret-scan coverage gaps (node_modules, dynamic content); improved push hook reliability.
+- **a11y and UI hardening** (#155): Fixed contrast, keyboard navigation, and state-update timing issues.
+- **Test infrastructure** (#155): Added comprehensive test coverage for daemons, state store, SSE reliability, UI hardening, and tools.
+
+## [0.1.0-wave.17] - 2026-07-15
+
+### Added
+- **Fleet-ops templates** (#153): Example documents for fleet analysis, recommendations, and proposal tracking to guide operations workflows.
+- **Tools suite expansion** (#153): New Python and Node tools for fleet operations:
+  - `transcript_replay.py`: Replay agent transcripts with event timing
+  - `transcript_timeline.py`: Extract and visualize agent activity timelines
+  - `fleet_prompt_extractor.py`: Extract and categorize fleet prompts for analysis
+  - `svg_to_png.mjs`: Convert SVG charts to PNG for documentation
+  - `session_usage_summary.py`: Aggregate session token usage across fleet
+- **CI merge wait improvements** (#153): Enhanced `ci_merge_wait` detection with better status classification.
+- **Machinery port** (#153): Completed isolation violation detector, health checks, and signal collection for orchestration monitor.
+- **Shippability fixes** (#153): Fixed daemon portability and improved bootstrap process.
+
+### Documentation
+- **Fleet-ops guidance** (#153): Added templates and examples for monitoring, analysis, and recommendations workflows.
+
+## [0.1.0-wave.16] - 2026-07-15
+
+### Added
+- **Isolation-violation detector** (#152): Monitor now detects and reports when worktrees modify shared state (repository contamination checker).
+- **Monitor signal collection** (#152): Enhanced `collect-signals.mjs` with isolation detection and improved signal accuracy.
+
+### Documentation
+- **CLAUDE.md minimization** (#151): Streamlined domain-specific documentation; archived cancelled tiered-cognition spike; improved maintainability.
+- **Domain map refinement** (#151): Clarified tool, test, and UI layer responsibilities and ownership.
+
+## [0.1.0-beta.5] - 2026-07-15
+
+### Added (Wave-15)
+- **State-Sourced State Layer** (#134, #135): Event-sourced SQLite WAL backing store with projections; tracker.json re-rendered as export for git integration; dual-path mutations via StateAPI.
+- **Self-Building Stats** (#130): `tools/self_stats.py` computes verified repository metrics (merged PRs, commits, waves, files, coauthors) live from git; README stats block auto-populated via CI drift gate.
+- **MCP Fleet Server** (#121): Read-only MCP server exposing fleet status, agents, tracker, costs for external Claude integrations.
+- **Alert Webhook Bridge** (#120): Incoming HTTP webhook relay to monitor alerts; configurable signing + filtering.
+- **Onboarding Wizard** (#127): Interactive CLI scaffolder with guided config, hook setup, repo discovery.
+- **Healthcheck Skill** (#126): Liveness probe skill for orchestrator health; integrated into monitor signal collection.
+- **Symlink/Junction Coverage** (#125): Test coverage for path-traversal guards; validates symlink/junction rejection in backup and UI handlers.
+
+### Changed (Wave-15)
+- **Agent Detail Rendering** (#128): Transcript lookup fixed for parallel agent teams; handles multi-file agent logs.
+- **CI Cascade** (#122, #131, #132, #133): Tools-index alert bridge integration; SSE transcript fixture isolation; favicon verification; node_modules secret-scan gate.
+
+### Fixed (Wave-15)
+- **Socket Race** (#129): stderr noise from concurrent SSE keepalive; added locking around socket writes.
+- **State Store Concurrency Seams** (#138): Inbox-drain deduplication, render-failure recovery, migration guard.
+- **CSRF HTTPS Origins** (#137): Accept https loopback origins in CSRF validation.
+- **CI/Daemon Machinery** (#136): Dist-freshness gate enforcement; watchdog script-relative path fix.
+- **Dashboard UX Hardening** (#141): Stale-data timestamps, empty states, lane badges, a11y improvements.
+
+### Documentation (Wave-15)
+- **RELEASING.md** (#140): Release process documentation; npm publish and CI merge procedures.
+- **Currency Sweep** (#140): CHANGELOG #113–#135 documentation; README state_store and stats updates; CLAUDE.md drift correction; beta.5 preparation.
+- **Portfolio Case Study** (#139): Matt Culliton personal portfolio documentation; agent-fleet-built showcase.
+
 ## [0.1.0-beta.4] - 2026-07-14
 
 ### Added (Wave-13)
@@ -15,13 +191,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Test/CI wiring: doc-drift and domain-map test verification.
 - Machinery gates: secret-scan enforcement, pre-push hook gating.
 
-## [Unreleased]
+### Added (Wave-14)
+- **Dashboard Rewrite**: Complete React 18 + Vite + TypeScript redesign with 4 hash-routed views (Overview, Work, Activity, Cost), sticky health header, live SSE updates, light/dark theming with WCAG AA contrast, keyboard navigation, and `aria-live` regions.
+- **Frontend Architecture**: Zero runtime dependencies beyond React/React-dom; Vite dev server with API proxy; committed `dist/` serves as authoritative build with content-hashed assets and immutable cache headers.
+- **Backend Additions**: `/api/state` consolidated first-paint snapshot (one round trip), `/api/session` for Vite dev server CSRF fallback, `/api/cost` cost/scorecard collector from `OUTCOMES-LEDGER.md` with optional pricing map and per-model/per-day aggregates.
+- **Cost Analytics**: Per-model token totals, per-day bar chart (pure SVG), verdict scorecard (success/failure/hung rates), configurable pricing estimates from `aesop.config.json`.
+- **Testing Infrastructure**: Vitest + Testing Library component tests, rewritten `tools/verify_dash.py` (Playwright) with data-testid-based assertions, CI drift gate for committed dist, a11y/theme verification in CI.
 
-### Added
-- **Stall Detection** (wave-12): `tools/stall_check.py` silent-hang detection for the agent watchdog.
-- **CI-Gated Merge Helper** (wave-12): `tools/ci_merge_wait.py` awaits CI success before merge.
+### Changed (Wave-14)
+- **Dashboard Cutover**: `ui/templates/dashboard.html` deleted; `ui/handler.py` serve_html now returns hard 500 if dist missing (no fallback).
+- **Render Module**: `render.py` requires `template_path` parameter (no legacy default); raises TypeError if called without it.
+- **API Contract**: SSE emits 6 sections (added `cost`); `/api/state` returns consolidated snapshot for optimal first paint.
 
-### Fixed
+### Fixed (Wave-14)
 - **Wave-12 Stability**: Swallowed failures now loud; `sse.reset_state()` locked for concurrent test isolation; tracker writes in tempdir; symlink/path-injection guards in rotate-logs.
 - **Wave-11 Security**: Dangling symlink inbox rejection; real handler exercise over HTTP; staged merge tier + model policy hook.
 

package/LICENSE

@@ -1,21 +1,66 @@
-MIT License
-
-Copyright (c) 2026 Matt Culliton
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Copyright 2026 Matt Culliton
+
+Licensed under the PolyForm Strict License 1.0.0.
+The full license text follows.
+
+---
+
+# PolyForm Strict License 1.0.0
+
+<https://polyformproject.org/licenses/strict/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose, other than distributing the software or making changes or new works based on the software.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -7,15 +7,56 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@matt82198/aesop"><img src="https://img.shields.io/npm/v/@matt82198/aesop/beta" alt="npm"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/npm/l/@matt82198/aesop" alt="license"></a>
   <a href="https://github.com/matt82198/aesop/actions/workflows/ci.yml"><img src="https://github.com/matt82198/aesop/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@matt82198/aesop"><img src="https://img.shields.io/npm/v/@matt82198/aesop/rc" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-PolyForm%20Strict%201.0.0-orange.svg" alt="License: PolyForm Strict 1.0.0 (source-available)"></a>
 </p>
 
-**Aesop** is an open-source orchestration harness for Claude Code that builds itself. It runs a `/buildsystem` wave cycle—ranking a backlog, fanning out parallel Haiku agents (1/3 the cost of Opus), watchdogging them, verifying merges, then feeding the next wave via audit + ideation + fleet-ops monitoring. **This repo's own PRs are built by Aesop's own loop.** Dogfooding, not doctrine.
+**Aesop** is a source-available orchestration harness for Claude Code that builds itself. It runs a `/buildsystem` wave cycle—ranking a backlog, fanning out parallel Haiku agents (1/3 the cost of Sonnet, 1/5 the cost of Opus), watchdogging them, verifying merges, then feeding the next wave via audit + ideation + fleet-ops monitoring. **This repo's own PRs are built by Aesop's own loop.** Dogfooding, not doctrine.
+
+As of **0.1.0-rc.1**, that loop has carried the project to an installable, tested, audited, and benchmarked release candidate—the fleet running the wave loop on its own, under a human who sets goals and owns the outward gates. The claims below are backed by committed artifacts you can check, not adjectives. See [Milestone: it shipped itself](#milestone-it-shipped-itself-010-rc1).
 
 What you get: **cost-optimized multi-agent dispatch** (Haiku-first subagents, lean orchestrator), **durable state** (git-committed checkpoints survive wipes), **observable machinery** (every agent run logged, every cost tracked), **live dashboard** (real-time fleet health at http://localhost:8770), and **security gates** (secret-scan blocks pushes, CI validates each merge).
 
+## Milestone: it shipped itself (0.1.0-rc.1)
+
+Aesop reached its first release candidate by running its own wave loop—**audit → parallel build → verify → merge-train**—across the backlog that produced it. This is the version where the load-bearing claims stopped being illustrations and became measurements. The word "autonomous" has a precise, deliberately narrow meaning here.
+
+**What "autonomous" means here (and what it doesn't).** The *fleet* autonomously runs the wave loop: it ranks work, dispatches parallel Haiku workers on file-disjoint domains, verifies merges, and feeds the next wave from a closing audit. A *human* sets the goals and owns every outward gate—npm publish, tagged releases, and history rewrites all stay human-approved. It is a supervised loop, not an unsupervised agent, and not AGI. The true model-dispatch core runs inside the Claude Code harness, which lives outside this repo; what ships here is the harness around it—orchestration, guardrails, dashboard, and tooling.
+
+The differentiator is not "an AI wrote code." It's that the credibility and safety claims come with receipts:
+
+| Claim | Evidence (committed, checkable) | Honest caveat |
+| --- | --- | --- |
+| **Haiku is good enough for fleet judgment** | Across 39 held-out judgment tasks, Haiku scored **39/39** vs Opus **38/39** at ~1/3 the per-token cost — measured by a plain-Python scorer with no model in the grading loop. See [`bench/results/`](./bench/results/). | Curated set, **not** sampled from real fleet transcripts (N=39). The benchmark found *no* task where Opus beats Haiku — so it proves sufficiency for these shapes, not parity at the reasoning frontier. |
+| **Audits don't hallucinate findings** | A full release audit was run with adversarial verification of every finding: **0 hallucinated issues**, closing the prior all-Haiku severity-inflation risk. | An internal audit, not a third-party one. |
+| **Kill-switch actually stops the fleet** | The fleet-wide halt is wired into the live dispatch path and proven end-to-end — one signal **aborted a real wave with zero workers spawned**. See [`tools/halt.py`](./tools/halt.py). | Operator-triggered; it is a manual brake, not an autonomous safety monitor. |
+| **A cost ceiling brakes runaway spend** | Dispatch halts when a per-wave budget is exceeded. See [`tools/cost_ceiling.py`](./tools/cost_ceiling.py). | A brake on a *configured* ceiling, **not yet tied to live token spend**. |
+| **The package installs and reproduces** | A **~409 kB** npm tarball (measured via `npm pack`) builds and validates from a fresh clone in CI. See [docs/reproduce.md](./docs/reproduce.md). | UI browser-proofs (Playwright) and real-model runs need local setup / API keys; they don't run in the offline reproduce job. |
+
+**Nobody outside this project has reproduced these results yet.** The evidence is committed so a skeptical reader can check it — that transparency is the point, not a substitute for independent replication. For the full, unhedged account of what is and isn't proven, read [docs/autonomous-swe.md](./docs/autonomous-swe.md) and the ["Honest limits" section of the release notes](./RELEASE-NOTES.md#honest-limits).
+
+## Why Aesop?
+
+Multi-agent AI fleets hit a wall: all-Opus orchestrators cost $10k+ per wave, and machine crashes lose state—losing work and context on restart. Aesop solves both: **Haiku-first** dispatch cuts costs to 1/3 of Opus, and **git-committed state** (STATE.md, BUILDLOG.md) survives machine wipes with zero data loss. See the wave cycle below: ranked backlog → parallel worktree-isolated fleet → merge train → checkpoint → audit feeds next wave.
+
+```
+ranked backlog
+     ↓
+parallel haiku fleet (worktree-isolated)
+  [test] [build] [docs] [ui] [review] ...
+     ↓
+integration-branch merge train
+     ↓
+checkpoint (STATE.md + BUILDLOG.md)
+     ↓
+audit + fleet-ops monitoring
+     ↓
+(feeds next wave's backlog)
+```
+
+(See [assets/wave-cycle-diagram.txt](./assets/wave-cycle-diagram.txt) for the cycle reference.)
+
 ## What You Get
 
 - **Parallel Haiku fleets** — Cheap, scoped subagents dispatch in parallel; orchestrator stays lean on main thread.
@@ -24,15 +65,17 @@ What you get: **cost-optimized multi-agent dispatch** (Haiku-first subagents, le
 - **Self-healing watchdog** — Runs every 150s: backs up work, scans for secrets, detects drift, restores on reboot.
 - **Live web dashboard** — Real-time fleet health, security alerts, work-item kanban at `http://localhost:8770`.
 - **Secret-scan gates** — Pre-push hook blocks leaks; audit trail logged. Pair with GitHub branch protection for enforcement.
+- **Read-only MCP Fleet Server** — Expose fleet status, active agents, work items, and cost metrics to Claude Code (fleet_status, fleet_agents, fleet_tracker, fleet_cost tools). See [mcp/CLAUDE.md](./mcp/CLAUDE.md) for setup.
+- **Self-diagnosing npm publish** — OIDC token generation and publish reliability verified on each release; workflow surfaces diagnostics inline.
 
 ## Get Started (3 steps, 5 min)
 
-**Note:** Aesop is in beta. Install the `@beta` tag for the latest prerelease (0.1.0-beta.1+).
+**Note:** Aesop is at its first release candidate. Install the `@rc` tag for the latest prerelease (v0.1.0-rc.1); the `@beta` tag remains available for earlier prereleases.
 
 ### Quickest path: npx scaffold
 
 ```bash
-npx @matt82198/aesop@beta my-fleet \
+npx @matt82198/aesop@rc my-fleet \
   --name "my-api" \
   --repos "/path/to/repo1,/path/to/repo2"
 cd my-fleet
@@ -46,6 +89,8 @@ python ui/serve.py
 
 Pre-push hook auto-installed. See [docs/HOOK-INSTALL.md](./docs/HOOK-INSTALL.md) for branch protection pairing.
 
+**State Store**: Aesop uses an event-sourced SQLite WAL backing store (`state_store/`) for durable state persistence. The `tracker.json` file is automatically re-rendered as an export for git-friendly checkpointing. Mutations follow a dual-path model: append new events via the StateAPI, then rendered exports for external consumption.
+
 ### Or: git clone for hacking
 
 ```bash
@@ -68,7 +113,7 @@ orchestrator (via Claude Code)  Reads backlog, dispatches Haiku subagents in par
   ↓
 parallel Haiku fleet            Tiny, scoped domains (tests, build, review, docs, etc.)
   ↓
-watchdog verifies & merges      GREEN → push to main
+watchdog backs up & gates        Heartbeat, secret-scan, push to backup branch; merging is orchestrator/human-driven
   ↓
 monitor/collect-signals.mjs     Audits orchestration health, feeds next wave's backlog
   ↓
@@ -77,16 +122,40 @@ STATE.md + BUILDLOG.md          Git-committed, survives machine wipes
 
 See [docs/DISPATCH-MODEL.md](./docs/DISPATCH-MODEL.md) for cost analysis and parallel patterns.
 
+<!-- STATS:START -->
+
+## Aesop builds itself
+
+Aesop is built entirely by its own `/buildsystem` wave cycle—running parallel Haiku fleets across ranked backlog items, verifying merges, auditing orchestration health. These stats are the receipts: all numbers computed LIVE from git, verified by anyone who clones.
+
+| Metric | Value |
+| --- | --- |
+| Merged PRs | 170 <!-- metrics-verified: self_stats.py (git log) --> |
+| Total Commits | 556 <!-- metrics-verified: self_stats.py (git log) --> |
+| Project Age | 5 days <!-- metrics-verified: self_stats.py (git log) --> |
+| Waves | 30 <!-- metrics-verified: self_stats.py (git log) --> |
+| Insertions + Deletions | 96,065 <!-- metrics-verified: self_stats.py (git log) --> |
+| Files Tracked | 336 <!-- metrics-verified: self_stats.py (git log) --> |
+| Distinct Co-authors | 9 <!-- metrics-verified: self_stats.py (git log) --> |
+
+<!-- STATS:END -->
+
+
+## Recommended Agents
+
+Aesop pairs well with the open-source catalog of ~130 community-authored specialized agent definitions (TDD orchestrators, security reviewers, performance engineers, etc.). For optimal results, install agents from the upstream source and pair them with Aesop's cost-optimized Haiku dispatch. This is optional; Aesop works standalone with general-purpose Claude Code agents.
+
 ## Use with Claude Code
 
 If you're using **Claude Code**, invoke `/power` at the start of each session. It loads your orchestrator brain (cardinal rules, domain map, team memory, system state) and outputs a health brief. Setup once:
 
 ```bash
-# Copy the /power skill
+# Copy the /power skill and optional /healthcheck skill
 cp -r skills/power/ ~/.claude/skills/power/
+cp -r skills/healthcheck/ ~/.claude/skills/healthcheck/
 ```
 
-Then in Claude Code, type `/power` or `/buildsystem` to start a wave cycle. See [skills/power/SKILL.md](./skills/power/SKILL.md) for details.
+Then in Claude Code, type `/power` or `/buildsystem` to start a wave cycle. Use `/healthcheck` to audit fleet machinery health before running waves. See [skills/power/SKILL.md](./skills/power/SKILL.md) and [skills/healthcheck/SKILL.md](./skills/healthcheck/SKILL.md) for details.
 
 ## Core Principles
 
@@ -126,7 +195,38 @@ Settings > Branches > main
   ✓ Restrict pushes to (Admins only)
 ```
 
-Private brain (`~/.claude`) is never committed to this repo. Keep `aesop.config.json` git-ignored. Implement `tools/secret_scan.py` with your security rules. See [docs/HOOK-INSTALL.md](./docs/HOOK-INSTALL.md) for setup.
+**Host-header validation** in the dashboard UI handler prevents HTTP header injection attacks; all requests are validated against the configured origin. Private brain (`~/.claude`) is never committed to this repo. Keep `aesop.config.json` git-ignored. Implement `tools/secret_scan.py` with your security rules. See [docs/HOOK-INSTALL.md](./docs/HOOK-INSTALL.md) for setup.
+
+## Dashboard (Wave-14 Rewrite)
+
+The dashboard is a **React 18 + Vite + TypeScript** single-page app with four hash-routed views:
+
+### Viewing the Dashboard
+```bash
+python ui/serve.py
+```
+Opens `http://localhost:8770` — live fleet health, security alerts, work-item kanban, cost analytics.
+
+### Architecture
+- **Backend**: Python stdlib HTTP server (`ui/handler.py`) serves the built React app + JSON/SSE APIs (`/api/state`, `/api/cost`, `/events`).
+- **Frontend**: `ui/web/` (React app) is built to `dist/` (committed to git) and served as static files by the Python server.
+- **CSRF protection**: Token injected into `dist/index.html` via sentinel substitution; mutations gated by `/submit` and `/api/tracker` endpoints.
+
+### Development
+```bash
+cd ui/web
+npm install
+npm run dev        # Vite dev server with API proxy to http://localhost:8770
+npm run build      # Build to dist/ (commit the dist/)
+```
+
+The dev server proxies `/data`, `/api`, `/events`, `/agent`, `/submit` to the Python backend on :8770, so the frontend can develop against live APIs.
+
+### Views
+- **Overview**: Fleet agents, security alerts, recent events.
+- **Work** (`#/work`): Tracker kanban (4 lanes: proposed/ranked/in-progress/done), audit backlog progress.
+- **Activity** (`#/activity`): Agent timeline, main-thread message tail (live reasoning).
+- **Cost** (`#/cost`): Per-model spend/tokens, per-day bar chart, verdict scorecard (success/failure rates).
 
 ## Extending Aesop
 
@@ -134,7 +234,7 @@ Private brain (`~/.claude`) is never committed to this repo. Keep `aesop.config.
 
 **Custom watchdog hooks**: Edit `daemons/backup-fleet.sh` to run linters, integrate with your CI, or customize secret-scan logic.
 
-**Dashboard panels**: Edit `ui/serve.py` or `dash/watchdog-gui.sh` to surface your metrics.
+**Dashboard components**: Add React components in `ui/web/src/components/` or new views in `ui/web/src/views/`. Rebuild and commit `dist/`.
 
 ## Troubleshooting
 
@@ -145,27 +245,47 @@ Private brain (`~/.claude`) is never committed to this repo. Keep `aesop.config.
 | Secret-scan blocks push | Add suppression to `tools/secret_scan.py`; no auto-bypass (by design) |
 | Monitor doesn't start | Verify Node.js on PATH; check `monitor/BRIEF.md` for logs |
 
-For deeper docs, see `docs/`:
-- `CARDINAL-RULES.md` — full 10 principles
-- `DISPATCH-MODEL.md` — cost analysis and patterns
-- `CHECKPOINTING.md` — how STATE.md + BUILDLOG.md survive wipes
-- `GOVERNANCE.md` — AUTO/PROPOSE tiers
-
-See [CHANGELOG.md](./CHANGELOG.md) for release notes.
+## Documentation
+
+**Adopter journey** (start here):
+- [docs/INSTALL.md](./docs/INSTALL.md) — Install Aesop and verify setup
+- [docs/CONFIGURE.md](./docs/CONFIGURE.md) — Configure repos, ports, and brain root
+- [docs/FIRST-WAVE.md](./docs/FIRST-WAVE.md) — Run your first `/power` → `/buildsystem` cycle
+- [docs/CONCEPTS.md](./docs/CONCEPTS.md) — Key concepts (dispatch, state, security, governance) with links to deep dives
+- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) — System architecture diagram and components
+
+**Operational reference**:
+- [docs/HOW-THE-LOOP-WORKS.md](./docs/HOW-THE-LOOP-WORKS.md) — Concrete walkthrough of one wave cycle
+- [docs/DISPATCH-MODEL.md](./docs/DISPATCH-MODEL.md) — Cost analysis, dispatch patterns, scaling
+- [docs/CHECKPOINTING.md](./docs/CHECKPOINTING.md) — STATE.md + BUILDLOG.md lifecycle, recovery on wipe
+- [docs/CARDINAL-RULES.md](./docs/CARDINAL-RULES.md) — 10 foundational principles
+- [docs/GOVERNANCE.md](./docs/GOVERNANCE.md) — Single-writer files, heartbeat protocol, AUTO/PROPOSE tiers
+- [docs/RELIABILITY.md](./docs/RELIABILITY.md) — Reliability guarantees, pride bar, inputs-always-outputs
+- [docs/HOOK-INSTALL.md](./docs/HOOK-INSTALL.md) — Secret-scan and branch protection setup
+
+**For specific tasks**:
+- [docs/FORENSICS.md](./docs/FORENSICS.md) — Debug agent failures (git-bisectable)
+- [docs/RESTORE.md](./docs/RESTORE.md) — Reconstitute Aesop on a new machine
+- [docs/PUBLISHING.md](./docs/PUBLISHING.md) — Release Aesop to npm
+- [docs/autonomous-swe.md](./docs/autonomous-swe.md) — The 0.1.0-rc.1 milestone told honestly: what "autonomous SWE" means here, the evidence behind each claim, and the limits the project owns
+- [docs/case-study-portfolio.md](./docs/case-study-portfolio.md) — How Aesop built its own portfolio site; full audit trail and cost breakdown
+
+See [CHANGELOG.md](./CHANGELOG.md) and [RELEASE-NOTES.md](./RELEASE-NOTES.md) for release notes.
 
 ## Contributing
 
-Aesop welcomes improvements. The repo uses its own `/buildsystem` loop for development—PRs from `feature/*` branches are built, tested, and merged by Aesop itself. To contribute:
+Aesop is **source-available** under the PolyForm Strict License 1.0.0, which does not permit modification or redistribution — so outside code patches can't be accepted as merged contributions. That said, **feedback is genuinely welcome**:
 
-1. Fork and create a `feature/*` branch.
-2. Write failing tests first (TDD).
-3. Open a PR; Aesop's wave cycle will verify and merge.
+- **Issues and bug reports** — tell us what's broken or confusing.
+- **Discussion and ideas** — feature requests, design critiques, use-case questions.
 
-Maintain the core principles: **Haiku-first** subagents, **lean** orchestrator, **durable** state, **observable** machinery.
+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.
 
 ## License
 
-MIT. See `LICENSE`.
+**Source-available** under the [PolyForm Strict License 1.0.0](./LICENSE). You may read, run, and use the software for any permitted purpose, but **modification and redistribution are not permitted**. See [`LICENSE`](./LICENSE) for the full terms and the definition of permitted (noncommercial and personal) purposes.
+
+Copyright 2026 Matt Culliton.
 
 ## References
 

package/aesop.config.example.json

@@ -6,7 +6,7 @@
     "scripts_root": "Override via SCRIPTS_ROOT env var or config; default: {aesop_root}/../scripts",
     "temp_root": "Override via TEMP_ROOT env var or config; default: system temp + /claude",
     "state_root": "Override via AESOP_STATE_ROOT env var or config; default: {aesop_root}/state",
-    "fleet_root": "Override via AESOP_FLEET_ROOT env var or config; default: $HOME (security: validate clone targets remain under this root)",
+    "fleet_root": "Override via AESOP_FLEET_ROOT env var or config; default: $HOME. SECURITY: all repository clone targets must remain under fleet_root to prevent credential harvesting across account boundaries. The monitor validates clone targets on each cycle and surfaces violations as HIGH alerts.",
     "transcripts_root": "Override via AESOP_TRANSCRIPTS_ROOT env var or config; default: ~/.claude/projects"
   },
   "brain_root": "~/.claude",
@@ -14,6 +14,7 @@
   "temp_root": "~/.aesop-temp",
   "_temp_root_notes": "Portable path for temporary aesop files. ~ expands to home directory on both Windows and POSIX. Alternatively, on Windows set to %TEMP%/aesop, on POSIX set to /tmp/aesop. Config loaders expand ~ at runtime.",
   "state_root": "./state",
+  "_fleet_root_note": "SECURITY BOUNDARY: all repository clone targets must remain under fleet_root to prevent credential harvesting across account boundaries. The monitor validates clone targets on each cycle. Defaults to home directory if not specified.",
   "fleet_root": "/path/to/fleet",
   "transcripts_root": "~/.claude/projects",
   "repos": [
@@ -44,5 +45,17 @@
   },
   "cardinal_rules": {
     "subagent_model": "haiku"
+  },
+  "limits": {
+    "_comment": "Cost ceiling / kill switch (tools/cost_ceiling.py, tools/halt.py). null disables a given ceiling (feature opt-in). When spend meets or exceeds a configured ceiling, cost_ceiling.py trips tools/halt.py's .HALT sentinel, which daemons/run-watchdog.sh checks at the top of every cycle and refuses to do work (no backup, no push, no scan) until cleared via 'python tools/halt.py --clear'.",
+    "max_wave_tokens": null,
+    "max_daily_tokens": null
+  },
+  "alerts": {
+    "_comment": "Slack/Discord webhook integration for fleet alerts. webhook_url: null (default) disables alerts (feature opt-in). SETUP: (1) Slack: Create an app at https://api.slack.com/apps, enable 'Incoming Webhooks', add a new webhook to your channel, copy the Webhook URL. (2) Discord: In your Discord server, go to Server Settings > Integrations > Webhooks, create a webhook, copy its URL. SECURITY: NEVER commit a real webhook URL to version control — retrieve at runtime via environment variable AESOP_ALERTS_WEBHOOK_URL or load from a .env.local file. Provider: 'slack' (block-kit format) or 'discord' (embed format). min_severity: filter by HIGH/CRITICAL/etc. heartbeat_stall_s: alert if watchdog heartbeat older than N seconds (null = skip).",
+    "webhook_url": null,
+    "provider": "slack",
+    "min_severity": "HIGH",
+    "heartbeat_stall_s": 600
   }
 }