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

package/CHANGELOG.md

@@ -5,110 +5,53 @@ 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).
 
+## [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.
+
 ## [Unreleased]
 
 ### 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.
+
+### Fixed
+- **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.
 
-#### 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.
+## [Wave-10] - 2026-07-10
+
+### 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.
 
-## [1.0.0] - 2026-07-11
+## [Wave-9] - 2026-06-30
 
 ### 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).
 
-#### 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
+## [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).
+
+### 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.