@matt82198/aesop 0.1.0-beta.4 → 0.1.0-beta.5

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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]
+
+### 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-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 +50,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/README.md

@@ -46,6 +46,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
@@ -77,6 +79,28 @@ 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 -->
+
+## 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 | 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) --> |
+
+<!-- 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.
+
 ## 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:
@@ -128,13 +152,44 @@ Settings > Branches > main
 
 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
 
 **Custom signal collectors**: Edit `monitor/collect-signals.mjs` to add domain-specific health checks.
 
 **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
 
@@ -150,6 +205,7 @@ For deeper docs, see `docs/`:
 - `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.
 

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",
@@ -44,5 +44,12 @@
   },
   "cardinal_rules": {
     "subagent_model": "haiku"
+  },
+  "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
   }
 }

package/bin/CLAUDE.md

@@ -1,12 +1,13 @@
 # bin/ — CLI scaffolder
 
-**Purpose**: Node.js CLI entry point that clones the aesop orchestration template into a target directory with idempotent validation.
+**Purpose**: Node.js CLI entry point that clones the aesop orchestration template into a target directory with idempotent validation, plus an interactive onboarding wizard for new adopters.
 
 ## Invocation
 
 - **npm registry**: `npx @matt82198/aesop [target-dir]` (default: `aesop-fleet`)
 - **Local dev**: `node bin/cli.js [target-dir]`
 - **Help**: `npx @matt82198/aesop --help` or `-h`
+- **Interactive wizard**: `npx @matt82198/aesop wizard` (on a TTY, prompts; with `--yes`, uses defaults)
 
 ## What gets copied
 
@@ -31,9 +32,36 @@ Scaffolder prints steps for users:
 5. Test daemon: `bash daemons/run-watchdog.sh --once`
 6. Launch dashboard: `python ui/serve.py`
 
+## Interactive wizard (`aesop wizard`)
+
+The wizard mode provides an interactive onboarding flow for new adopters, guiding them through fleet setup in ~60 seconds:
+
+1. **Trigger**: `npx @matt82198/aesop wizard` on a TTY (interactive terminal)
+2. **Questions** (all have sensible defaults, press Enter-Enter-Enter to skip):
+   - Project name (default: "my-fleet")
+   - Repos to watch (auto-discovers git repos under `~`, offers choices)
+   - Dashboard port (default: 8770, validates 1–65535)
+   - Brain root directory (default: `~/.claude`)
+3. **Output**:
+   - Scaffolds template files
+   - Generates CLAUDE.md (substituted with project name)
+   - Generates aesop.config.json (with discovered repos)
+   - Prints "next 3 commands" epilogue
+   - Offers to run `watchdog --once` smoke test immediately
+4. **Non-interactive mode** (`--yes` flag or non-TTY stdin): Uses defaults, zero prompts (CI-safe)
+
+### Wizard implementation details
+
+- **Repo discovery** (`discoverRepos`): Scans `~` for `.git` directories at first level (non-recursive)
+- **Port validation** (`validatePort`): Rejects invalid ports, accepts 1–65535
+- **Portable paths**: All config paths use `~` form (`~/.claude`, `~/scripts`, etc.) for cross-platform compatibility
+- **Defaults**: Every prompt has a default so users can skip it (press Enter)
+- **Non-destructive**: Never overwrites existing `aesop.config.json` without user confirmation
+
 ## 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.
 - **No machine-specific paths**: Use relative paths only; `__dirname` and `path.join()` handle cross-platform resolution.
-- **Help text accuracy**: If invocation steps or output paths change, update help text (lines 27–31).
+- **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