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

package/docs/HOOK-INSTALL.md

@@ -0,0 +1,307 @@
+# Git Pre-Push Hook Installation Guide
+
+**Ship a hook, not a memo.** The pre-push policy hook is **auto-installed during scaffold** (see below). This guide explains customization, verification, and org-wide distribution.
+
+## Security Model: Local Convenience Defense Only
+
+**IMPORTANT**: The pre-push hook is a **local-machine convenience defense** — it is **NOT cryptographic protection**. Any developer can bypass it with `git push --no-verify` or by editing/deleting `.git/hooks/pre-push`. The audit log (`SECURITY-AUDIT.log`) is stored locally and can also be edited by a user with file system access.
+
+**Real enforcement requires server-side branch protection.** See GitHub Configuration below.
+
+## What the Hook Does
+
+`hooks/pre-push-policy.sh` enforces two checks at git push time:
+
+1. **Branch Policy**: Blocks direct pushes to `main` or `master` branches (feature branches only).
+2. **Secret Scan**: Runs `tools/secret_scan.py --staged` to detect credentials before they reach the remote.
+
+Both blocks append a JSON audit record to `state/SECURITY-AUDIT.log` with timestamp, repo, reason, and user — creating a reviewable trail of policy enforcement.
+
+## Auto-Installation During Scaffold
+
+**Default Behavior:** When you scaffold a new aesop fleet with `npx @matt82198/aesop [target-dir]`, the CLI automatically installs the pre-push hook into `.git/hooks/pre-push`.
+
+- **On Unix/macOS/Git Bash**: Creates a symlink so hook updates are automatic
+- **On Windows**: Copies the hook directly (symlinks don't work reliably on all NTFS setups)
+- **Idempotent**: Re-running scaffold doesn't clobber a user-customized hook
+- **Preserve Existing**: If you have a different pre-push hook, scaffold warns and preserves it
+- **Force Replace**: Use `npx @matt82198/aesop [target-dir] --force` to replace any existing hook
+
+**Example:**
+
+```bash
+# Initial scaffold (creates and installs hook automatically)
+npx @matt82198/aesop my-fleet
+
+# Later: re-scaffold the same directory (preserves customizations)
+npx @matt82198/aesop my-fleet
+
+# Force replace (even if hook was customized)
+npx @matt82198/aesop my-fleet --force
+```
+
+## Manual Installation
+
+If you're installing into an existing repo (not scaffolded), or you need to manually add the hook:
+
+### Option 1: Symlink (Linux / macOS / Git Bash on Windows)
+
+The cleanest method — hook stays in sync with repo updates:
+
+```bash
+ln -s ../../hooks/pre-push-policy.sh .git/hooks/pre-push
+chmod +x .git/hooks/pre-push
+```
+
+### Option 2: Copy (Windows, or to break sync)
+
+Copy the hook directly into `.git/hooks/`:
+
+```powershell
+Copy-Item hooks\pre-push-policy.sh .git\hooks\pre-push
+```
+
+On Windows PowerShell, mark it executable if your git respects file mode:
+
+```bash
+git config core.filemode false
+```
+
+## Testing
+
+Before committing to org-wide deployment, verify the hook works:
+
+```bash
+bash hooks/pre-push-policy.sh --test
+```
+
+Expected output: **PASS** for all three checks (branch policy, feature branch allowance, audit log format).
+
+## GitHub Configuration (Server-Side Enforcement)
+
+To pair this local hook with real enforcement, enable branch protection on GitHub:
+
+### Step 1: Create a Protected Branch
+
+1. Go to your GitHub repo **Settings** > **Branches**.
+2. Click **Add rule** under "Branch protection rules".
+3. Enter branch name pattern: `main` (or `master`, depending on your default branch).
+
+### Step 2: Enable Required Protections
+
+- **Require pull request reviews before merging**: ✓ (enforces PR review workflow)
+- **Require status checks to pass before merging**: ✓ (use this for CI)
+- **Require branches to be up to date before merging**: ✓
+- **Restrict who can push to matching branches**: ✓ (optional; allows only admins to push to main)
+
+### Step 3: Dismiss Stale Reviews (Recommended)
+
+- **Dismiss stale pull request approvals when new commits are pushed**: ✓
+
+### Example: Minimal Protected Branch Rule for `main`
+
+| Setting | Value |
+|---------|-------|
+| Branch name pattern | `main` |
+| Require pull request reviews | Yes (1 approval) |
+| Require status checks to pass | Yes (if you have CI) |
+| Require branches up to date | Yes |
+| Restrict pushes to | Admins only |
+
+Once this is configured, even if a developer bypasses the local hook with `--no-verify`, the remote will **refuse the push**.
+
+## Audit Log Format & Integrity
+
+Each block writes one JSON line to `${AESOP_ROOT:-$HOME/aesop}/state/SECURITY-AUDIT.log`:
+
+```json
+{"seq":1,"prev_hash":"GENESIS","ts":"2025-07-12T14:32:01Z","repo":"aesop","event":"push_blocked","reason":"secret_scan_failure","user":"alice"}
+{"seq":2,"prev_hash":"f4b92becb47baa447e839330cf3c0c6e8dea947acc9ec372bb99063ee416d036","ts":"2025-07-12T14:32:02Z","repo":"aesop","event":"push_blocked","reason":"secret_scan_failure","user":"bob"}
+```
+
+**Fields:**
+- `seq`: Monotonically increasing sequence number (starts at 1). Enables detection of truncation or missing entries.
+- `prev_hash`: SHA-256 hash of the previous line (without trailing newline). First entry uses `"GENESIS"`. Enables tampering detection.
+- `ts`: ISO-8601 UTC timestamp
+- `repo`: Repository basename
+- `event`: Always `push_blocked` (or `secret_scan_unavailable`)
+- `reason`: `push_to_protected_branch`, `secret_scan_failure`, or other block reason
+- `user`: Git user.name (fallback: "unknown"); all special characters and control chars are JSON-escaped
+
+**Write Safety & Concurrent Access:**
+All audit log writes are protected by a file-system atomic lock (`.audit-log-lock/` directory). This ensures that concurrent pushes from different repositories (or simultaneous local pushes) do not corrupt the hash chain. The lock has a 300-second stale-lock recovery mechanism to handle crashed holders.
+
+**Tail Hash Anchor:**
+Each write also updates `${AESOP_ROOT:-$HOME/aesop}/state/.audit-tail-hash` with the SHA-256 hash of the newly appended line. This sidecar file acts as an anchor against tail truncation.
+
+### Verifying Audit Log Integrity
+
+The hash chain and truncation anchor allow you to detect if someone edited, deleted, or truncated audit log entries:
+
+```bash
+bash hooks/pre-push-policy.sh --verify-audit-log
+```
+
+Output on intact log:
+```
+Audit log verification OK (42 entries)
+```
+
+Output if line tampering is detected:
+```
+Error: Hash chain broken at line 15
+  Expected prev_hash: f4b92becb47baa447e839330cf3c0c6e8dea947acc9ec372bb99063ee416d036
+  Actual prev_hash: abc123...
+```
+
+Output if tail truncation is detected:
+```
+TRUNCATION SUSPECTED: Tail hash mismatch (stored: f4b..., actual: 8e6...)
+```
+
+The truncation detection compares the stored tail hash (`state/.audit-tail-hash`) against the actual SHA-256 hash of the current log's last line. If someone deletes the last N lines, the hashes will not match.
+
+**Note**: Verification is a convenience check; it does not prevent tampering on a machine where the attacker has file system access. For real auditability, centralize audit logs to a secure remote (e.g., CloudWatch, Datadog, or a separate immutable log server).
+
+Parse the log with standard JSON tools:
+
+```bash
+cat state/SECURITY-AUDIT.log | jq '.reason' | sort | uniq -c
+```
+
+## Org Distribution & Customization
+
+### Standard Distribution
+
+1. Commit the hook to a shared repo or policy repository.
+2. Instruct teams to symlink or copy per option above.
+3. Communicate audit log location and parsing examples.
+
+### Customizing Checks
+
+To add org-specific rules (e.g., branch naming conventions, required CI status):
+
+1. Edit `hooks/pre-push-policy.sh` and add a new check function:
+   ```bash
+   check_my_org_policy() {
+     # your logic here
+     return 0 or 1
+   }
+   ```
+
+2. Call it from `main()` before exit, and log blocks:
+   ```bash
+   if ! check_my_org_policy; then
+     log_block "my_org_policy_violation"
+     exit 1
+   fi
+   ```
+
+3. Update `run_test_mode()` to include test cases for the new check.
+
+4. Commit and redistribute.
+
+### Disabling in CI/CD
+
+If CI systems need to bypass the hook (e.g., for automated releases), set:
+
+```bash
+export GIT_SKIP_HOOKS=pre-push
+git push
+```
+
+Or use `git push --no-verify` (explicitly allowing humans to opt out).
+
+## Audit Log Rotation
+
+The audit log is append-only. For long-running deployments, consider log rotation:
+
+```bash
+if [ -f state/SECURITY-AUDIT.log ] && [ $(stat -f%z state/SECURITY-AUDIT.log 2>/dev/null || stat -c%s state/SECURITY-AUDIT.log) -gt 1000000 ]; then
+  mv state/SECURITY-AUDIT.log "state/SECURITY-AUDIT.$(date +%Y%m%d-%H%M%S).log"
+fi
+```
+
+## Troubleshooting
+
+**Hook not running?**
+- Verify `.git/hooks/pre-push` exists and is executable: `ls -la .git/hooks/pre-push`
+- Check symlink target if using option 1: `readlink .git/hooks/pre-push`
+- Git version must be 1.8.2+; run `git --version`
+
+**"Push blocked" but no reason in audit log?**
+- Check `${AESOP_ROOT:-$HOME/aesop}/state/` directory exists and is writable.
+- Verify git config: `git config user.name` is not empty.
+
+**Secret scan warns but doesn't block?**
+- `secret_scan.py` must exist at `AESOP_ROOT/tools/secret_scan.py`.
+- If missing, the hook warns but allows push (fail-open default).
+- For fail-closed behavior, edit the hook and remove the early `return 0`.
+
+## References
+
+- Hook source: `hooks/pre-push-policy.sh`
+- Secret scanner: `tools/secret_scan.py`
+- Audit log location: `state/SECURITY-AUDIT.log` (git-ignored)
+- Cardinal rule: [CARDINAL-RULES.md](CARDINAL-RULES.md)
+
+## Claude Code hooks
+
+Beyond git hooks, aesop ships policy for the agent harness itself.
+`hooks/claude/force-model-policy.mjs` is a Claude Code **PreToolUse** hook that
+enforces the "subagents are always Haiku" cardinal rule in code: every `Agent`
+or `Task` dispatch whose `model` is absent or non-compliant is rewritten to the
+policy model before the subagent launches. Versioned in git, it is org policy
+you can review, diff, and test — not a memo agents can forget.
+
+### What it enforces
+
+- **Model policy**: subagent dispatches run on `haiku` by default. If
+  `aesop.config.json` defines `cardinal_rules.subagent_model` (looked up in
+  `$AESOP_ROOT`, then the working directory), that model is enforced instead.
+- **Rewrite, not block**: non-compliant dispatches are allowed through with
+  `model` rewritten via the hook output contract
+  (`hookSpecificOutput.updatedInput`), so work proceeds at the right cost tier.
+- **Fail-open reliability**: malformed input produces no output and exit 0.
+  The hook never crashes the harness and never logs payload contents.
+
+### Registration (settings.json)
+
+Add to `.claude/settings.json` in the project (or `~/.claude/settings.json`
+for user-wide enforcement):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Agent|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/hooks/claude/force-model-policy.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+If the hook lives outside the project (e.g., a shared policy checkout), use an
+absolute path to the `.mjs` file instead of `$CLAUDE_PROJECT_DIR`.
+
+### Escape hatch
+
+For dispatches that genuinely need a bigger model, include the literal marker
+`[[ALLOW-NON-HAIKU]]` anywhere in the subagent prompt. The hook passes the
+dispatch through untouched — and because the marker sits in the prompt, every
+opt-out is visible in the transcript and auditable after the fact.
+
+### Testing
+
+```bash
+node --test tests/force-model-policy.test.mjs
+```
+
+Covers the rewrite, escape-hatch, malformed-stdin, and config-override cases.

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/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.