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

package/docs/HOW-THE-LOOP-WORKS.md

@@ -0,0 +1,175 @@
+# How the Wave Loop Works (The Fast, Cheap Way)
+
+**TL;DR**: Aesop's `/buildsystem` runs one cycle per wave: rank backlog → fan out parallel Haiku agents → watchdog catches hangs → verify + merge → close with audits. The result: **lower cost (Haiku is ~1/3 the cost of Sonnet) and faster wall-clock from running agents in parallel** through parallelism and cheap subagents, while the orchestrator stays busy planning next work.
+
+---
+
+## The Wave Cycle at a Glance
+
+A **wave** is one complete delivery loop:
+
+```
+1. Rank Backlog (~10 min)
+   ↓
+2. Fan Out (spawn 5–8 parallel Haiku agents, ~80 min)
+   ↓
+3. Watchdog (catch stalls, respawn as needed)
+   ↓
+4. Verify + Merge (orchestrator reviews outputs, merges PRs, ~30 min)
+   ↓
+5. Close: Audit + Ideation + Fleet Ops (~20 min)
+   ↓
+6. NEXT WAVE: feed the backlog with findings
+```
+
+**Wallclock time per wave**: 2–3 hours. **Token spend**: ~$0.03. **What ships**: 5–8 small, tested features/fixes.
+
+---
+
+## 1. Rank Backlog (10 min)
+
+Before spawning agents, you decide what to build. Use these lenses:
+
+- **Priority**: P1 blockers first, P2 quality/UX, P3 tech debt
+- **Sizing**: fit each item to a Haiku agent (scoped <5 min reasoning)
+- **Ownership**: assign one agent type per item (backend-dev for APIs, frontend-dev for UI, test-bot for test fixes)
+
+**Example backlog after ranking**:
+```
+P1: Fix auth timeout (backend-dev)
+P1: Add verify-dash UTF-8 check (frontend-dev)
+P2: Refactor config loader (backend-dev)
+P3: Simplify hook test suite (test-bot)
+P3: Document wave cycle (docs-agent)
+```
+
+**Productivity win**: Ranked backlog prevents "what should I build next?" tax. Agents don't guess — they execute known work.
+
+---
+
+## 2. Fan Out (80 min, all in parallel)
+
+The orchestrator spawns 5–8 Haiku agents **in one command**, one per backlog item. Each agent:
+
+- Gets a **scoped brief** (what to build, acceptance criteria)
+- **Works in its own worktree** (no conflicts, safe parallelism)
+- **Commits + pushes** when done
+- **Opens a PR** with a summary
+
+Example spawn:
+```
+→ Haiku-1 (auth): "fix timeout, add tests, commit & PR"
+→ Haiku-2 (UI): "add UTF-8 check to /submit, update test"
+→ Haiku-3 (refactor): "simplify config, preserve API"
+→ Haiku-4 (tests): "prune old hooks, keep coverage >90%"
+→ Haiku-5 (docs): "write HOW-THE-LOOP-WORKS.md"
+```
+
+**Productivity win**: the agents run concurrently instead of one at a time, and each Haiku costs 1/3 of Sonnet (1/5 of Opus) — so the fleet is both faster in wall-clock and far cheaper than one expensive agent working serially.
+
+---
+
+## 3. Watchdog (Continuous, 80 min)
+
+While agents work, a background watchdog:
+
+- **Polls every 10s**: checks agent heartbeats and PR status
+- **Respawns hung agents**: if >200s idle, TaskStop + relaunch (max 3 auto-retries)
+- **Escalates hangs**: after 3 retries, mark BLOCKED and surface to you
+
+**No human waiting**. The watchdog runs autonomously.
+
+---
+
+## 4. Verify + Merge (30 min)
+
+Once all 5 agents finish (or hit 3-retry cap), the orchestrator:
+
+1. **Reviews each PR** (code review, test coverage, no known-broken state)
+2. **Approves + merges** (or routes back to agent for fixes)
+3. **Runs integration tests** (do the merged features work together?)
+4. **Updates main** (all work lands together, not one-at-a-time)
+
+**Example merge sequence**:
+```
+✓ Haiku-1 PR #95: auth timeout fix (APPROVED)
+✓ Haiku-2 PR #96: UTF-8 check (APPROVED)
+✓ Haiku-3 PR #97: config refactor (APPROVED)
+✓ Haiku-4 PR #98: test prune (APPROVED)
+✓ Haiku-5 PR #99: docs (APPROVED)
+→ Merge all 5 → run integration tests → green ✓
+```
+
+**Productivity win**: Batch PR reviews (all at once) + single merge transaction = faster feedback loops, fewer context-switches.
+
+---
+
+## 5. Close (20 min): Audit + Ideation + Fleet Ops
+
+Before the next wave, close this one:
+
+- **Audit**: Did all 5 agents follow rules? (branch discipline, secret-scan gate, test coverage)
+- **Ideation**: What went well? What bottlenecked? Any tech-debt findings to backlog?
+- **Fleet ops**: Rotate logs (BUILDLOG.md archives), update MEMORY.md with learnings, clean up worktrees
+
+**Example findings**:
+```
+✓ 5/5 agents followed rules
+✓ All PRs had tests
+→ Config refactor revealed opportunity: auto-gen schemas (P3, backlog for wave 12)
+→ UTF-8 check is cheap; suggest expanding to other endpoints (P2)
+→ One agent took 95 min (slightly over 80); consider smaller tasks next wave
+```
+
+**Productivity win**: Intentional retrospective prevents repeating mistakes. Backlog feeds into the next wave's ranking, so you build on learnings, not starting fresh each time.
+
+---
+
+## Why It's Fast & Cheap
+
+| Metric | Aesop Wave | All-Opus Equivalent |
+|--------|-----------|-------------------|
+| **Agents** | 5 Haiku + 1 Opus orchestrator | 6 Opus |
+| **Time** | ~2–3 hours (parallel) | ~12+ hours (serial) |
+| **Cost** | ~$0.03 | ~$0.18 |
+| **Test coverage** | Required per agent | Often skipped in time-crunch |
+| **Outputs** | All PRs merged, all tests green | Might be 1–2 half-finished features |
+
+**Key levers**:
+1. **Parallelism**: agents work concurrently instead of one-at-a-time (measured example: wave-10's 5-agent fleet finished in ~293s of wall-clock vs ~897s if run serially — about 3x)
+2. **Cheap subagents**: Haiku is 1/3 the cost of Sonnet and 1/5 the cost of Opus (exact on both input and output); running many in parallel keeps spend low
+3. **Orchestrator stays lean**: reads only STATE.md + BUILDLOG.md + git one-liners (no re-reading entire codebase)
+4. **No idle time**: while agents work, orchestrator plans next phase (never blocking on agents)
+
+---
+
+## When the Loop Stalls (Retry Cap & Escalation)
+
+If an agent hangs 3 times on the same task:
+
+1. **Auto-retry 1–3**: Watchdog relaunches agent (same prompt, no changes)
+2. **On 4th hang**: Mark BLOCKED in BUILDLOG.md, surface to you
+3. **You decide**: Break the task smaller, escalate to Sonnet, or park it and move on
+
+**Why a cap?** Infinite retries waste tokens and hide real problems (task too big, external dependency broken, etc.). 3 retries = 6 min of agent time; if still stuck, it's a human decision.
+
+---
+
+## About /buildsystem and /power Skills
+
+**Important**: The `/buildsystem` and `/power` skills are **orchestrator-brain skills** installed to `~/.claude/skills/`, not files inside the aesop template. They are invoked via Claude Code as slash commands.
+
+- **Location**: `~/.claude/skills/buildsystem/` and `~/.claude/skills/power/` on your workstation.
+- **Template copy**: The aesop repo contains skill definitions in `skills/` for reference and setup (copy these to `~/.claude/skills/` on first use).
+- **Invocation**: In Claude Code, type `/power` to prime your orchestrator brain, or `/buildsystem` to start a wave cycle.
+
+See [skills/power/SKILL.md](../skills/power/SKILL.md) for detailed setup instructions.
+
+## Next Steps
+
+1. Run `/buildsystem` to start a wave (orchestrator handles the flow)
+2. Monitor via the TUI dashboard (`bash dash/watchdog-gui.sh`)
+3. After merge, review findings to feed the next backlog
+4. Rinse, repeat
+
+For deep dives on cost/dispatch patterns, see [DISPATCH-MODEL.md](DISPATCH-MODEL.md). For reliability guarantees, see [RELIABILITY.md](RELIABILITY.md).

package/docs/MEMORY-TEMPLATE.md

@@ -0,0 +1,61 @@
+# Memory Index Template
+
+This is the canonical index of team facts. Each fact is **one file, one truth**.
+
+## Format
+
+### Index line
+```
+- [Title](file.md) — [1-line hook]
+```
+
+### Fact frontmatter
+Every memory file opens with:
+```
+---
+name: [Fact name]
+description: [One sentence]
+type: [user|feedback|project|reference]
+---
+```
+
+**Types**: `user` (who you are), `feedback` (decisions/learnings), `project` (repo-specific), `reference` (how-tos/patterns).
+
+## Examples
+
+### Memory file: `~/.claude/memory/dispatch-principles.md`
+
+```
+---
+name: Dispatch cost lever
+description: Why Haiku subagents are the single most important cost optimization.
+type: reference
+---
+
+Subagents are ALWAYS Haiku (1/3 Sonnet cost). This is the cost lever.
+Six to eight Haiku agents in parallel cost ~25% of all-Opus fleet...
+[Full context here]
+```
+
+### Memory file: `~/.claude/memory/team-goals.md`
+
+```
+---
+name: 2026 Q2 goals
+description: Ship [feature] by end of June, maintain <200ms latency on [metric].
+type: feedback
+---
+
+Primary goal: [...]
+Secondary goal: [...]
+Constraints: [...]
+```
+
+### Index entry (in MEMORY.md)
+
+```
+- [Dispatch principles](memory/dispatch-principles.md) — Haiku is 1/3 cost, default subagent tier
+- [Team goals](memory/team-goals.md) — Q2 2026 roadmap and constraints
+```
+
+Create new facts by adding a file and an index line. The orchestrator reads the index at session start.

package/docs/README.md

@@ -0,0 +1,44 @@
+# Aesop Documentation Index
+
+Aesop is a fable-fleet orchestration harness for Claude Code. It runs fast, cheap delivery waves: parallel Haiku agents, lower cost via Haiku-first dispatch and faster wall-clock via parallel agents.
+
+**New to Aesop?** Start here: [HOW-THE-LOOP-WORKS.md](HOW-THE-LOOP-WORKS.md) — a walkthrough of one wave cycle and why it's productive.
+
+For deeper governance + operational rules, see the reference docs below.
+
+---
+
+## Quick Start
+
+- [HOW-THE-LOOP-WORKS.md](HOW-THE-LOOP-WORKS.md) — Concrete walkthrough of one `/buildsystem` wave (rank → fan out → verify → merge → close)
+
+## Core Governance & Rules (Reference)
+
+- [CARDINAL-RULES.md](CARDINAL-RULES.md) — Foundational operational principles (dispatch model, cost, subagent discipline, retry caps)
+- [RELIABILITY.md](RELIABILITY.md) — Reliability core: never wait, inputs always produce outputs, pride bar for completion
+- [CHECKPOINTING.md](CHECKPOINTING.md) — Durable STATE.md/BUILDLOG.md lifecycle, recovery on resume, log rotation patterns
+- [SCRIPTS-POLICY.md](SCRIPTS-POLICY.md) — Local-only execution, shared script library, task-local vs. reusable heuristics
+- [DISPATCH-MODEL.md](DISPATCH-MODEL.md) — Fable/Haiku orchestration patterns and cost calculations
+- [GOVERNANCE.md](GOVERNANCE.md) — Single-instance loops, single-writer files, heartbeat protocol, security gates
+
+## The Five Pillars
+
+### 1. Onboarding Templates
+- [MEMORY-TEMPLATE.md](MEMORY-TEMPLATE.md) — Canonical index format and structure for team memory & facts
+
+### 2. Policy Hooks
+- [HOOK-INSTALL.md](HOOK-INSTALL.md) — Install and customize `hooks/pre-push-policy.sh` (branch/secret enforcement at push time)
+
+### 3. Behavioral PRs
+- [BEHAVIORAL-PR-REVIEW.md](BEHAVIORAL-PR-REVIEW.md) — Checklist for reviewing PRs that modify rules, policies, or orchestration behavior
+
+### 4. Forensics (Git-Bisectable Agent Debugging)
+- [FORENSICS.md](FORENSICS.md) — Reconstruct agent failures using `tools/agent-forensics.sh`; make agent behavior git-debuggable
+
+### 5. Restore (Cross-Machine Reconstitution)
+- [RESTORE.md](RESTORE.md) — Reconstitute Aesop & fleet on a new machine from git + watchdog backups after a wipe
+
+## Operational Guides
+
+- [PUBLISHING.md](PUBLISHING.md) — Release Aesop to npm using GitHub Actions with OIDC trusted publishing
+- [av-resilience.md](av-resilience.md) — Antivirus & behavioral-engine resilience patterns for reliable agent execution

package/docs/RELEASING.md

@@ -0,0 +1,159 @@
+# Releasing Aesop
+
+This document covers the release process for Aesop: version bumping, git tagging, GitHub release creation, and npm publishing with beta dist-tag support.
+
+## Release Types
+
+Aesop follows semantic versioning: `MAJOR.MINOR.PATCH[-PRERELEASE]`
+
+- **Stable (0.1.0)**: Core orchestration engine stable; backward-compatible API
+- **Beta (0.1.0-beta.N)**: Pre-release builds; may have breaking changes; uses `@beta` npm dist-tag
+- **Patch (0.1.0-beta.N+M)**: Fixes within a beta series; increments local version only
+
+## Full Release Workflow
+
+### 1. Version Bump (`npm version`)
+
+```bash
+# From repo root, on a `release/*` or `docs/*` branch (never main)
+npm version minor       # for 0.1.0 → 0.2.0 (stable)
+npm version prerelease  # for 0.1.0 → 0.1.1-rc.0 (next beta)
+npm version patch       # for 0.1.0-beta.4 → 0.1.0-beta.5 (current beta)
+```
+
+This command:
+- Updates `package.json` version field
+- Creates a git commit `"v<version>"` (only if git is clean)
+- Creates an annotated git tag `v<version>`
+- Does NOT push (safe for local preview)
+
+**Pre-check**: Ensure:
+- `package.json` files in repo (root + `ui/web/`) are in sync
+- No uncommitted changes (git status clean)
+- `dist/` is up-to-date (npm run build if needed)
+
+### 2. Verify the Tag Locally
+
+```bash
+# Check the tag was created and points to the right commit
+git tag -l | tail -5
+git show v0.1.0-beta.5
+```
+
+### 3. Push to Git Remote
+
+```bash
+# Push the branch and the new tag
+git push origin docs/wave15-currency
+git push origin v0.1.0-beta.5
+```
+
+This makes the tag available for GitHub release creation.
+
+### 4. Create GitHub Release
+
+GitHub Actions CI automatically creates a release from the tag when pushed. Or manually via GitHub web UI:
+
+1. Go to [Releases](https://github.com/matt82198/aesop/releases)
+2. Click "Create a new release"
+3. Select `v0.1.0-beta.5` from the tag dropdown
+4. Title: `Aesop 0.1.0-beta.5`
+5. Body (auto-generated or manual):
+   ```markdown
+   ## What's New
+   - State-sourced SQLite backing store (Wave-15)
+   - Self-building stats via tools/self_stats.py
+   - MCP fleet server integration
+   - Alert webhook bridge
+   - Onboarding wizard (interactive scaffolder)
+   - Healthcheck skill for liveness probes
+   
+   ## Install
+   ```bash
+   npm install @matt82198/aesop@beta
+   ```
+   
+   See [CHANGELOG.md](CHANGELOG.md) for the full list.
+   ```
+6. **For beta releases**: Check "This is a pre-release"
+7. Click "Publish release"
+
+### 5. Publish to npm
+
+```bash
+# Login (if not already authenticated)
+npm login
+
+# For stable releases (0.1.0)
+npm publish --access public
+
+# For beta releases (0.1.0-beta.5)
+npm publish --access public --tag beta
+
+# Verify the tag was set
+npm view @matt82198/aesop@0.1.0-beta.5 | grep dist-tags
+# Should output:
+#   'dist-tags': { latest: '0.1.0', beta: '0.1.0-beta.5' }
+```
+
+**Pre-check before publish**:
+- `npm run test:all` passes (all test suites green)
+- `npm run build` succeeds in ui/web/
+- `dist/` is committed and up-to-date
+- Changelog is current (CHANGELOG.md updated)
+- No local uncommitted changes
+
+## Verification Checklist
+
+After publishing, verify the release is live:
+
+```bash
+# Check npm registry
+npm view @matt82198/aesop@latest     # Should show latest stable
+npm view @matt82198/aesop@beta       # Should show latest beta
+
+# Install in a test dir and verify
+mkdir /tmp/aesop-test && cd /tmp/aesop-test
+npm install @matt82198/aesop@beta
+node -e "console.log(require('./package.json').dependencies)"
+```
+
+## Rollback (if needed)
+
+If a release has a critical bug:
+
+1. **npm**: Deprecate the bad version
+   ```bash
+   npm deprecate @matt82198/aesop@0.1.0-beta.5 "Critical bug; use @beta instead"
+   ```
+
+2. **GitHub**: Delete the release from the web UI (Releases → click release → Delete)
+
+3. **Git**: Delete the tag locally and remotely
+   ```bash
+   git tag -d v0.1.0-beta.5
+   git push origin :refs/tags/v0.1.0-beta.5
+   ```
+
+4. **Branch**: Reset the version bump commit (if desired)
+   ```bash
+   git reset --soft HEAD~1
+   # Edit package.json back to previous version
+   git add package.json
+   git commit -m "Revert: v0.1.0-beta.5 (critical bug)"
+   git push origin <branch>
+   ```
+
+## Notes
+
+- **The `@latest` dist-tag** is reserved for stable releases (no prerelease suffix). Beta releases stay under `@beta`.
+- **Semver gaps**: If beta.4 was skipped, beta.5 jumps directly. No backfilling needed.
+- **Prereleases don't block stable**: Users on `npm install @matt82198/aesop` get the latest stable, not the latest beta.
+- **Local version suffix**: If you need to publish a local build for testing, use `0.1.0-beta.5+local.1` (won't be published to npm, only for local installs).
+
+## References
+
+- [npm version](https://docs.npmjs.com/cli/v8/commands/npm-version)
+- [npm publish](https://docs.npmjs.com/cli/v8/commands/npm-publish)
+- [npm dist-tags](https://docs.npmjs.com/cli/v8/commands/npm-dist-tag)
+- [Semantic Versioning](https://semver.org/)

package/docs/RELIABILITY.md

@@ -0,0 +1,61 @@
+# Reliability & Core Obligations
+
+**TL;DR**: Three rules for shipping production work: (1) orchestrator never idles (spawn next task while agents run), (2) every action produces observable output (silence = failure), (3) pride bar — verify end-to-end before marking done. Together: reliable, visible, trustworthy automation.
+
+---
+
+## NEVER WAIT: Keep the orchestrator busy
+
+The orchestrator must never go idle while background work is in flight. Every moment waiting on agents or builds is spent producing forward progress:
+
+- Dispatch the next unblocked work unit
+- Extend planning documentation (roadmaps, next phases)
+- Stage ideas and observations to memory
+- Queue important facts via the inbox pattern
+- Always offer the user an actionable idea for what to do next
+
+**Key principle**: "Waiting on X" is never a complete status — it must come with "meanwhile, doing/proposing Y." Never burn cycles re-reading state that scoped agents will report anyway.
+
+## Inputs ALWAYS produce outputs
+
+Every dispatched agent, loop cycle, tool run, and workflow MUST emit an observable output:
+- A brief summary
+- A log line
+- A heartbeat signal
+- Or an explicit `FAILED` or `EMPTY` marker
+
+**Silence is never acceptable.** No output = failure, and the watchdog treats it as a hang. Never swallow a result; never let a task end without reporting something.
+
+## The pride bar: never ship until you would be proud to deliver it
+
+"An agent returned a brief" and "tests pass" are checkpoints, not completion.
+
+**Done means:**
+- Verified end-to-end (not just isolated tests)
+- Briefs cross-checked against reality
+- Test artifacts cleaned up
+- Loose ends closed or explicitly logged as pending decisions
+- Nothing known-broken shipped silently
+
+If you would hesitate to hand it over under your own name, it is not done — keep going. Shipping something you're not proud of erodes team trust and creates technical debt that costs more to fix later.
+
+## Why these matter
+
+**Cache persistence.** Consistent outputs and reliable checkpoints mean the prompt cache stays warm and effective. Broken shortcuts kill cache hit rates and waste tokens.
+
+**Team trust.** Silence erodes confidence in agent-driven work. Observable outputs, explicit failures, and the pride bar rebuild and maintain trust.
+
+**Cost containment.** Retries, debug loops, and rollbacks all cost tokens. Getting it right the first time (through upfront verification and deliberate finishing) is cheaper than fixing broken work later.
+
+## Implementation checklist
+
+- Daemons emit heartbeats every cycle (even on error)
+- Logs are append-only; every action logged with timestamp
+- If a subagent stalls >200s, watchdog respawns it
+- Orchestrator briefs the user with findings while delegating to subagents (never idle)
+- Before marking work done, verify end-to-end and cross-check briefs against reality
+- On task completion, ask: "Would I be proud to deliver this under my name?"
+
+---
+
+These three principles together form the **reliability core**: keep working (never wait), always report (inputs → outputs), and never compromise on quality (pride bar). They enable scaling from 1 orchestrator to dozens of parallel subagents without losing control, visibility, or production readiness.