@matt82198/aesop 0.1.0-beta.5 → 0.1.0

package/CHANGELOG.md

@@ -7,11 +7,164 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Added (Wave-16/17 in-flight)
-- CLAUDE.md minimization and domain map refinements (PR #151).
-- Isolation detector and machinery/scripts port (PR #150).
-- MCP server and scan/ directory shipping in npm package.
-- README stats refresh and agent-catalog reference.
+## [0.1.0] - 2026-07-17
+
+First stable release. This is the graduation of `0.1.0-rc.1` to a stable version with the
+same feature set — no code changes beyond the version/documentation promotion. It publishes to
+npm under the `latest` dist-tag. Highlights carried from rc.1: verified Opus audit (0
+hallucinated findings), kill-switch wired into the live dispatch path, cost-ceiling guardrail,
+a measured held-out benchmark (39 judgment tasks, Haiku on par with Opus at ~1/3 the cost),
+the state-reconcile primitive, browser-proven dashboard views (Wave PR Board + Agent
+Inspector), a source-available license, and a slim, reproducible ~409 kB npm package. See the
+[0.1.0-rc.1] entry below for the full itemized list, and RELEASE-NOTES.md for the honest-limits
+account (small-N benchmark, cost-ceiling not yet tied to live token spend, local-first).
+
+## [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
 

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" 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**, that loop has carried the project to an installable, tested, audited, and benchmarked stable release—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's first stable release is `0.1.0`, published to npm under the `latest` tag — a plain `npx @matt82198/aesop` or `npm install @matt82198/aesop` pulls it. Earlier prereleases remain available under the `@rc` and `@beta` tags.
 
 ### Quickest path: npx scaffold
 
 ```bash
-npx @matt82198/aesop@beta my-fleet \
+npx @matt82198/aesop my-fleet \
   --name "my-api" \
   --repos "/path/to/repo1,/path/to/repo2"
 cd my-fleet
@@ -70,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
   ↓
@@ -79,7 +122,7 @@ STATE.md + BUILDLOG.md          Git-committed, survives machine wipes
 
 See [docs/DISPATCH-MODEL.md](./docs/DISPATCH-MODEL.md) for cost analysis and parallel patterns.
 
-<!-- SELF-STATS:START -->
+<!-- STATS:START -->
 
 ## Aesop builds itself
 
@@ -87,30 +130,32 @@ Aesop is built entirely by its own `/buildsystem` wave cycle—running parallel
 
 | Metric | Value |
 | --- | --- |
-| Merged PRs | 141 <!-- metrics-verified: self_stats.py (git log) --> |
-| Total Commits | 377 <!-- metrics-verified: self_stats.py (git log) --> |
-| Project Age | 3 days <!-- metrics-verified: self_stats.py (git log) --> |
-| Waves | 15 <!-- metrics-verified: self_stats.py (git log) --> |
-| Insertions + Deletions | 70,439 <!-- metrics-verified: self_stats.py (git log) --> |
-| Files Tracked | 257 <!-- metrics-verified: self_stats.py (git log) --> |
-| Distinct Co-authors | 7 <!-- metrics-verified: self_stats.py (git log) --> |
+| 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 -->
 
-<!-- SELF-STATS:END -->
 
 ## Recommended Agents
 
-Aesop pairs well with the open-source [Claude specialized-agent catalog](https://github.com/anthropics/claude-code/tree/main/agents) — a library of ~130 domain-specific agents (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.
+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
 
@@ -150,7 +195,7 @@ 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)
 
@@ -200,28 +245,47 @@ The dev server proxies `/data`, `/api`, `/events`, `/agent`, `/submit` to the Py
 | 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
-- `case-study-portfolio.md` — How Aesop built its own portfolio site; full audit trail and cost breakdown
-
-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

@@ -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": [
@@ -45,6 +46,11 @@
   "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,

package/bin/CLAUDE.md

@@ -9,10 +9,19 @@
 - **Help**: `npx @matt82198/aesop --help` or `-h`
 - **Interactive wizard**: `npx @matt82198/aesop wizard` (on a TTY, prompts; with `--yes`, uses defaults)
 
+## Runtime subcommands
+
+cli.js dispatches runtime management subcommands to `tools/{subcommand}.js`:
+
+- **`aesop doctor`** (or `node bin/cli.js doctor`) — Preflight readiness check; validates Node.js, Python, git, config, directories, hooks, and dashboard port availability.
+- **`aesop watch`** (or `node bin/cli.js watch`) — Launch the watchdog daemon; spawns `daemons/run-watchdog.sh` for continuous fleet monitoring.
+- **`aesop dash`** (or `node bin/cli.js dash`) — Launch the web dashboard; spawns `python ui/serve.py` to serve realtime fleet status at localhost:8770 (default).
+- **`aesop status`** (or `node bin/cli.js status`) — One-shot fleet status snapshot; displays heartbeats, dashboard port, and git branch status.
+
 ## What gets copied
 
-Files in `filesToCopy` array (cli.js line 57–69):
-- **Directories**: `daemons/`, `dash/`, `monitor/`, `tools/`, `ui/`, `docs/`
+Files in `filesToCopy` array (cli.js lines 239–256):
+- **Directories**: `daemons/`, `dash/`, `monitor/`, `tools/`, `ui/`, `docs/`, `state_store/`, `skills/`, `mcp/`, `scan/`, `hooks/`
 - **Files**: `aesop.config.example.json`, `README.md`, `LICENSE`, `CHANGELOG.md`, `CLAUDE-TEMPLATE.md`
 - **Brain templates** (in docs/): `MEMORY-TEMPLATE.md` (via docs/ directory copy)
 
@@ -61,7 +70,7 @@ The wizard mode provides an interactive onboarding flow for new adopters, guidin
 ## Invariants & gotchas
 
 - **Idempotent on empty targets**: Fails if `targetDir` exists and is non-empty (non-destructive). Safe to retry.
-- **Adding shipped files**: Any new file/dir added to `filesToCopy` array must also be added to `package.json` `files` array (lines 9–21 in package.json) so npm publish includes it.
+- **Adding shipped files**: Any new file/dir added to `filesToCopy` array must also be added to `package.json` `files` array (lines 9–27 in package.json) so npm publish includes it.
 - **No machine-specific paths**: Use relative paths only; `__dirname` and `path.join()` handle cross-platform resolution.
 - **Wizard prompts are async**: Main execution is wrapped in async IIFE to support readline prompts
 - **Help text accuracy**: If invocation steps or output paths change, update help text