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

package/CHANGELOG.md

@@ -7,108 +7,92 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Added
+### 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)
+- UI correctness hardening: a11y improvements, contrast fixes, dead marquee removal, monitor-status class.
+- Dashboard UX: accessibility fixes, keyboard navigation improvements.
+- npm packaging fixes: dependency alignment, build optimization.
+- Docs currency: dead-link sweep, reference updates, HOW-THE-LOOP-WORKS clarifications.
+- Test/CI wiring: doc-drift and domain-map test verification.
+- Machinery gates: secret-scan enforcement, pre-push hook gating.
+
+### 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.
+
+### 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 (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.
+
+## [Wave-10] - 2026-07-10
 
-#### Dashboard Integrations
-- **`dash/dash-extra.mjs`**: Fleet agent detector scans transcripts for running agents, enables web dashboard agent panel. Detects agents in last 12 minutes, color-codes by alert severity, outputs JSON for REST endpoint or TUI text for terminal.
-- **`tools/secret_scan.py`**: Pre-push secret/credential detection gate with comprehensive pattern library (PEM keys, AWS/GitHub/Slack/OpenAI tokens, .env patterns, credential filenames). Supports `--staged`, `--history`, and direct path scanning. Pragma escape hatch for allow-pattern-docs. Exit 1 blocks push on findings.
+### Added
+- **UI API Package** (`ui/api/`): Extracted mutation-gate helpers (`validate_mutation()`, `append_to_inbox()`, tracker CRUD handlers) from monolithic handler.py for direct unit testing.
+- **Work-item Tracker**: 4-lane kanban (proposed | ranked | in-progress | done) with full CRUD API and SSE updates, priority chips (P0-P3), expandable item details.
+- **Orchestrator Status Panel**: Real-time activity, phase, age display with stale detection (>30m).
+- **Dashboard ASCII Banner**: Animated audit-phase indicator (tortoise + magnifying glass).
+- **UI Module Refactoring**: Split monolithic `serve.py` → focused modules (`config.py`, `csrf.py`, `render.py`, `handler.py`, `collectors.py`, `agents.py`, `sse.py`).
 
 ### Improved
-- Web dashboard now properly detects and displays running subagents via `dash-extra.mjs`
-- Secret-scan gate now active in watchdog cycle; blocks any push with unscanned credentials
+- **Security**: CSRF on /api/tracker create; XSS whitelist for pr_link (http/https only, blocks javascript:); fail-closed lock with PID liveness.
+- **Stability**: SSE exception handling; timezone-aware datetime; stale lock timestamp spoofing prevention.
+
+## [Wave-9] - 2026-06-30
 
-## [1.0.0] - 2026-07-11
+### Added
+- **UI Module Split**: Monolithic `serve.py` refactored into composable modules for maintainability and direct testing (config, csrf, render, handler, collectors, agents, sse).
+- **Real Handler Tests**: Seam tests exercising render, collectors, agents without full HTTP coupling (wave-10 P0 foundation).
+
+## [0.1.0-beta.3] - 2026-07-12
 
 ### Added
+- Hardened rule documentation (CARDINAL-RULES, DISPATCH-MODEL, GOVERNANCE.md).
+- Real orchestration monitor with 10 standing health checks (replaced stub).
 
-#### Web Dashboard (Primary Interface)
-- Modern, responsive HTML dashboard replacing terminal UI
-- Real-time fleet monitoring with 3-second refresh cycles
-- Heartbeat liveness detection for daemon health
-- Security alerts panel with unreviewed event tracking
-- Inbox integration for direct orchestrator communication
-- Agent tracking with status and runtime hints
-- **Agent detail expansion**: Click agent rows to view full dispatch prompts, dispatcher, model, and message counts
-- **GET /agent endpoint**: RESTful query for agent metadata and full dispatch details
-- Repository synchronization status display
-- Recent events log with the latest 8 backup operations
-- Transcript integration showing main-thread conversation history
-- Configurable port (default 8770) via environment variables
-- Zero external dependencies (Python 3.10+ stdlib only)
-
-#### Orchestration Engine
-- Fable-fleet dispatch model (orchestrator + Haiku subagents)
-- Cost-optimized multi-agent coordination
-- Durable git-committed state (STATE.md, BUILDLOG.md)
-- Autonomous watchdog daemon with 150-second cycle
-- Secret-scan gate on every push (configurable via `tools/secret_scan.py`)
-- Heartbeat-based liveness detection (300s watchdog, 3600s monitor)
-- Append-only BUILDLOG for recovery and audit trails
-
-#### Refinement Monitor
-- Standing orchestration health monitor (Haiku loop)
-- Dual-action tier system (AUTO for immediate, PROPOSE for staged)
-- Signal collection and drift detection
-- Automated health checks and rule-friction analysis
-- Extensible signal collectors via `monitor/collect-signals.mjs`
-
-#### State Machine & Durability
-- Filesystem-first checkpoint design
-- Git-committed STATE.md and BUILDLOG.md
-- Recovery from machine wipes and interruptions
-- Single-writer control file discipline
-- Idempotent restart semantics
-
-#### Security & Observability
-- Configurable secret-scan gate (blocks pushes on policy violation)
-- Observable machinery (every agent run logged, every cost tracked)
-- Security alert collection and triaging
-- AV-resilience patterns for Windows environments
-- Support for dot-directory backup discovery
-
-#### Documentation
-- Cardinal Rules guide (10 principles for cost-optimized orchestration)
-- Dispatch Model documentation (cost analysis, parallel patterns)
-- State Machine guide (durability and recovery)
-- AV-Resilience guide (Windows security software compatibility)
-- Quickstart walkthrough and setup guide
-- Architecture deep-dives for extend points
-
-#### TUI Dashboard (Legacy Alternative)
-- Terminal-based dashboard via `dash/watchdog-gui.sh`
-- Real-time fleet status display
-- Agent activity tracking
-- Alert visualization
-- Optional jq dependency for JSON parsing
-
-### Configuration
-
-#### aesop.config.json Schema
-```json
-{
-  "aesop_root": "/path/to/aesop",
-  "state_root": "/path/to/state",
-  "scan_root": "/path/to/scan",
-  "transcripts_root": "/path/to/transcripts",
-  "repos": [
-    {
-      "path": "/path/to/repo",
-      "name": "repo-name"
-    }
-  ],
-  "watchdog_cycle_secs": 150,
-  "monitor_cycle_secs": 300,
-  "heartbeat_stale_threshold_secs": 300
-}
-```
-
-### Development & Extension
-
-- Plugin architecture for custom signal collectors
-- Hook points for watchdog customization
-- Dashboard extensibility via JavaScript injection
-- Secret-scan policy implementation examples
-- Support for Haiku-per-domain decomposition
+### Improved
+- Production observability infrastructure.
 
 ---
 

package/CLAUDE-TEMPLATE.md

@@ -0,0 +1,115 @@
+# {{PROJECT_NAME}} — Multi-Agent Orchestration Brain
+
+**What**: {{PROJECT_NAME}} is a {{DOMAIN_LIST}} system orchestrated through cost-optimized multi-agent dispatch.
+This is the team's durable brain: cardinal rules, domain map, and memory indexed here.
+
+## Cardinal Rules (how we work reliably at scale)
+
+These six rules keep our fleet fast, cheap, and unbreakable:
+
+1. **Subagents are always Haiku** (cost optimization at scale). Orchestrator (Opus/Sonnet) on main thread only.
+2. **Orchestrator is durable**: STATE.md + BUILDLOG.md committed to git; survive wipes and interruptions.
+3. **State gates everything**: No decision without git commit + push. Diff = behavior record.
+4. **Secret-scan gates every push**: `tools/secret_scan.py` blocks credentials. No override, no exceptions.
+5. **Idempotent + append-only**: Safe to restart mid-cycle. BUILDLOG.md never rewrites, only appends.
+6. **Observable machinery**: Every agent dispatch logged. Every cost tracked. Every security event audited.
+
+Read `docs/CARDINAL-RULES.md` for the full 10 rules and rationale. Single-writer discipline and heartbeat patterns are in `docs/GOVERNANCE.md`.
+
+## Domain Map (our system structure)
+
+Each domain maps to one Haiku subagent. Orchestrator dispatch = tiny, scoped, cheap.
+
+{{DOMAINS}}
+
+## Team Memory Structure
+
+Facts live in `~/.claude/MEMORY.md` (index) and individual files in `~/.claude/memory/`.
+
+**Fact format**:
+```
+---
+name: [Title]
+description: [1-line hook]
+type: [user|feedback|project|reference]
+---
+[Content]
+```
+
+**Types**:
+- `user` — who you are, team composition
+- `feedback` — decisions, learnings, constraints
+- `project` — repo-specific, {{PROJECT_NAME}} setup
+- `reference` — patterns, how-tos, runbooks
+
+See `docs/MEMORY-TEMPLATE.md` for full indexing format.
+
+## Initial Setup Checklist
+
+1. **Brain directory** (your private persistent memory):
+   ```bash
+   mkdir -p ~/.claude/memory
+   # Edit ~/.claude/CLAUDE.md with your domains and team info
+   # Edit ~/.claude/MEMORY.md with your facts
+   ```
+
+2. **Configuration**:
+   ```bash
+   cp aesop.config.example.json aesop.config.json
+   # Edit paths, repos, cycle times per your setup
+   ```
+
+3. **Directory structure**:
+   ```bash
+   mkdir -p ~/{{PROJECT_NAME}}/state
+   mkdir -p ~/.heartbeats
+   ```
+
+4. **Test the watchdog**:
+   ```bash
+   export AESOP_ROOT=$HOME/{{PROJECT_NAME}}
+   bash $AESOP_ROOT/daemons/run-watchdog.sh --once
+   ```
+
+5. **Launch the dashboard**:
+   ```bash
+   python $AESOP_ROOT/ui/serve.py
+   # Opens http://localhost:8770
+   ```
+
+6. **(Optional) Arm the monitor**:
+   ```bash
+   # In your Claude Code orchestrator loop, run:
+   export AESOP_ROOT=$HOME/{{PROJECT_NAME}}
+   node $AESOP_ROOT/monitor/collect-signals.mjs
+   ```
+
+## Repo Map
+
+Your tracked repositories (from aesop.config.json):
+
+{{REPO_LIST}}
+
+Each repo in the list will be discovered by the watchdog, backed up to `backup/wip-*` branches, and secret-scanned before push.
+
+## Key Files & Paths
+
+- **This file**: `~/.claude/CLAUDE.md` — your team brain
+- **Memory index**: `~/.claude/MEMORY.md` — indexed facts
+- **Memory directory**: `~/.claude/memory/` — individual fact files
+- **Orchestrator config**: `~/{{PROJECT_NAME}}/aesop.config.json` (git-ignored)
+- **Durable state**: `~/{{PROJECT_NAME}}/state/` — STATE.md, BUILDLOG.md (committed)
+- **Watchdog heartbeat**: `~/.heartbeats/.watchdog-heartbeat` (epoch timestamp)
+- **Monitor heartbeat**: `~/.heartbeats/.monitor-heartbeat` (epoch timestamp)
+
+## See Also
+
+- `docs/CARDINAL-RULES.md` — full 10 rules with rationale
+- `docs/DISPATCH-MODEL.md` — cost analysis + parallel patterns
+- `docs/GOVERNANCE.md` — single-writer discipline, inbox, loops
+- `docs/MEMORY-TEMPLATE.md` — memory structure and frontmatter
+- `README.md` — full walkthrough and troubleshooting
+
+---
+
+**Onboarding ready.** Your fleet is live when BUILDLOG.md shows the first dispatch.