@matt82198/aesop 0.1.0 → 0.3.1

package/docs/DEMO.md

@@ -0,0 +1,334 @@
+# Init-Prime-Demo: Your First Complete Aesop Flow
+
+**TL;DR**: This 10-minute walkthrough takes you from nothing to a working orchestration harness, primed and ready for your first wave.
+
+Covered in this demo:
+1. Create a toy project (just a git repo)
+2. Scaffold Aesop into a fleet harness
+3. Run `/power` to prime the orchestrator
+4. Understand what happens next
+
+---
+
+## What You'll Need
+
+Before starting, ensure you have:
+
+- **Node.js** v18+ (for scaffolder and CLI)
+- **Git** v2.40+ (for repo setup)
+- **Bash** v4+ (for daemons; Windows: Git Bash)
+- **Claude Code CLI** v0.1+ (for `/power` and `/buildsystem` skills)
+
+Check versions:
+```bash
+node --version
+git --version
+bash --version
+claude --version
+```
+
+---
+
+## Step 1: Create a Toy Project (2 min)
+
+This simulates a real project that Aesop will manage.
+
+```bash
+# Create a new directory and initialize git
+mkdir ~/my-demo-project
+cd ~/my-demo-project
+git init
+
+# Configure git (required for commits)
+git config user.email "demo@aesop.test"
+git config user.name "Demo User"
+
+# Create a sample file and make an initial commit
+echo "# My Demo Project" > README.md
+git add README.md
+git commit -m "Initial commit"
+```
+
+Your toy project is now ready. It's a clean git repo with one commit.
+
+---
+
+## Step 2: Scaffold Aesop (2 min)
+
+Create a fleet harness in a separate directory. The harness orchestrates your project(s).
+
+```bash
+# Go to a working directory (e.g., your home or ~/projects)
+cd ~
+
+# Scaffold Aesop (creates ~/demo-fleet/)
+npx @matt82198/aesop demo-fleet \
+  --name "demo-fleet" \
+  --repos "~/my-demo-project" \
+  --yes
+
+# Move into the harness
+cd ~/demo-fleet
+```
+
+What this does:
+- Creates `daemons/`, `skills/`, `monitor/`, `tools/`, `ui/`, `docs/` subdirectories
+- Generates `aesop.config.json` with your project path
+- Creates `CLAUDE.md` (orchestrator brain template)
+- Installs a git pre-push hook for secret scanning
+- Initializes a git repo in the harness
+
+Expected output:
+```
+✓ Creating ~/demo-fleet...
+✓ Copying scaffold files...
+✓ Generating CLAUDE.md...
+✓ Generating aesop.config.json...
+✓ Installing pre-push hook...
+✓ Initializing git repo...
+
+Next steps:
+  1. cd ~/demo-fleet
+  2. npx @matt82198/aesop doctor  # Verify preflight checks
+  3. /power                        # Prime orchestrator brain
+  4. /buildsystem                  # Run your first wave
+```
+
+---
+
+## Step 3: Verify Installation (1 min)
+
+Run preflight checks to ensure everything is ready.
+
+```bash
+npx @matt82198/aesop doctor
+```
+
+Expected output:
+```
+[doctor] Checking prerequisites...
+  ✓ Node.js v18.14.0 found
+  ✓ Git v2.42.0 found
+  ✓ Bash v5.1.16 found
+  ✓ Python v3.11.0 found (optional)
+  ✓ aesop.config.json is readable
+  ✓ Pre-push hook is installed and executable
+  ✓ Port 8770 is available (for dashboard)
+
+All checks passed. Ready to start.
+```
+
+If you see warnings about missing optional tools (Python, jq), that's OK for this demo. You can install them later.
+
+---
+
+## Step 4: Prime the Orchestrator (/power) (3 min)
+
+Now open Claude Code and invoke the `/power` skill. This reads your configuration and verifies the orchestrator is healthy.
+
+```
+/power
+```
+
+What `/power` does:
+1. Reads `~/.claude/CLAUDE.md` (your global orchestrator rules)
+2. Reads `aesop.config.json` (your fleet configuration)
+3. Checks `state/STATE.md` (current phase and next steps)
+4. Validates that daemons are healthy (checks heartbeat files)
+5. Reports a health brief
+
+Expected output:
+```
+Orchestrator Brain Loaded
+
+✓ Global rules (CLAUDE.md) loaded
+✓ Fleet config (aesop.config.json) loaded
+  - 1 repo configured: my-demo-project
+  - Brain root: ~/.claude
+  - State root: ~/demo-fleet/state
+✓ Fleet daemons: healthy (watchdog heartbeat ~30s old)
+✓ STATE.md initialized: Phase 1, ready for backlog
+
+NEXT STEPS:
+(1) Create a backlog (P1/P2 tasks)
+(2) Run /buildsystem to execute a complete wave cycle
+```
+
+If you see errors about missing CLAUDE.md or heartbeat files, don't worry—they'll be created on first startup. Re-run `/power` after a few seconds.
+
+---
+
+## Step 5: Understand the Backlog (Optional, 2 min)
+
+Before running your first wave, you need a backlog of work. The orchestrator dispatches agents to complete these tasks.
+
+Example backlog:
+```markdown
+## Wave 1 Backlog
+
+- **P1: Add setup documentation** (backend-dev) — Document the initial setup process
+- **P2: Fix README formatting** (docs-agent) — Improve readability of README.md
+- **P3: Add a test scaffold** (test-bot) — Create tests/ directory with example test
+```
+
+Each task should:
+- Fit in 5–15 minutes for a Haiku agent
+- Be scoped (not "refactor everything")
+- Have a priority (P1=blocker, P2=quality, P3=tech debt)
+- Be assigned to an agent type
+
+For this demo, you can skip this step and just observe what `/buildsystem` would do. Or create 2–3 simple tasks.
+
+---
+
+## Step 6: Run Your First Wave (Optional, 10+ min)
+
+Once you have a backlog, invoke `/buildsystem` in Claude Code:
+
+```
+/buildsystem
+```
+
+What `/buildsystem` does:
+1. **Rank & Assign** — Reads your backlog, assigns agents to tasks
+2. **Dispatch Fleet** — Spawns 3–8 Haiku agents in parallel worktrees
+3. **Execute** — Each agent works on its task independently
+4. **Verify** — Runs tests, checks compilation, validates changes
+5. **Merge Train** — Commits and pushes completed tasks
+6. **Checkpoint** — Saves state (STATE.md, BUILDLOG.md)
+
+You'll see live updates as agents work. Each task runs in isolation (no conflicts).
+
+Expected output:
+```
+Wave 1 / Rank & Assign
+  ✓ Task 1: Add setup documentation (backend-dev)
+  ✓ Task 2: Fix README formatting (docs-agent)
+  ✓ Task 3: Add test scaffold (test-bot)
+→ Dispatching 3 Haiku agents (est. 45–60 min)...
+
+[Agent 1: backend-dev] Working on Task 1...
+[Agent 2: docs-agent] Working on Task 2...
+[Agent 3: test-bot] Working on Task 3...
+
+Wave 1 / Merge Train
+  ✓ All agents completed
+  ✓ 3 PRs created
+  ✓ All tests passed
+  ✓ Merging to main...
+
+Wave 1 Complete
+  Duration: 47 minutes
+  Cost: 3,200 tokens
+  Files changed: 12
+  NEXT STEPS: Review BUILDLOG.md, run Wave 2 if needed
+```
+
+---
+
+## What Happened?
+
+You just ran a complete Aesop wave cycle:
+
+1. **Orchestrator** (you) → defined the backlog
+2. **Dispatch** (Aesop) → analyzed tasks, assigned agents
+3. **Execution** → 3+ Haiku agents worked in parallel (each in their own worktree)
+4. **Verification** → tests passed, code reviewed, merged
+5. **Checkpoint** → progress saved to `state/STATE.md` and `state/BUILDLOG.md`
+
+Each wave is independent. You can run wave 2 with a new backlog, or pause and review results.
+
+---
+
+## Exploring the Harness
+
+Now that you've seen it work, explore:
+
+### 1. Check the state files
+```bash
+cat state/STATE.md          # Current phase and next steps
+cat state/BUILDLOG.md       # Append-only progress log
+```
+
+### 2. View the dashboard (optional)
+```bash
+npx @matt82198/aesop dash  # Launches http://localhost:8770
+```
+
+Monitor waves in real-time: see active agents, heartbeats, logs, and costs.
+
+### 3. Check the daemons
+```bash
+ls -la daemons/
+bash daemons/run-watchdog.sh --once  # Run watchdog once (no daemon)
+```
+
+The watchdog handles backup, secret scanning, and fleet health checks.
+
+### 4. Review the configuration
+```bash
+cat aesop.config.json       # Your fleet configuration
+cat CLAUDE.md               # Orchestrator brain (domain map, rules)
+```
+
+---
+
+## Scaling to Real Projects
+
+Once you're comfortable with the demo flow, you can:
+
+1. **Add more repos** — Edit `aesop.config.json` and list your real projects
+2. **Customize domains** — Edit `CLAUDE.md` to define your team structure
+3. **Tune the backlog** — Work with your team to prioritize tasks
+4. **Run continuous waves** — Schedule `/buildsystem` to run on a cadence
+5. **Set cost ceilings** — Add spending limits to prevent runaway bills
+
+See [CONFIGURE.md](CONFIGURE.md) and [INSTALL.md](INSTALL.md) for full details.
+
+---
+
+## Troubleshooting
+
+**Q: `/power` says "CLAUDE.md not found"**
+- A: Copy the skills to your Claude Code home:
+  ```bash
+  cp -r skills/power ~/.claude/skills/
+  cp -r skills/buildsystem ~/.claude/skills/
+  ```
+
+**Q: `aesop doctor` reports missing Python**
+- A: Python is optional for the demo. If you want secret scanning or log rotation, install it:
+  ```bash
+  python3 --version  # Check if installed
+  pip install pyyaml  # If needed
+  ```
+
+**Q: Watchdog fails with "not inside a git repository"**
+- A: Make sure you've run the scaffold from a location with git installed and initialized. Re-run scaffold:
+  ```bash
+  npx @matt82198/aesop demo-fleet --yes
+  ```
+
+**Q: Dashboard won't open (port 8770 in use)**
+- A: The scaffold will use the next available port (8771, 8772, etc). Check `aesop.config.json` for the actual port.
+
+See [INSTALL.md](INSTALL.md) for more troubleshooting and [CONCEPTS.md](CONCEPTS.md) for deeper understanding.
+
+---
+
+## Next Steps
+
+1. **Run the full test suite** — Verify everything works:
+   ```bash
+   npm run test:all
+   ```
+
+2. **Read [FIRST-WAVE.md](FIRST-WAVE.md)** — Deep dive into the wave cycle
+
+3. **Explore [CONCEPTS.md](CONCEPTS.md)** — Understand the dispatch model and state architecture
+
+4. **Add your real repos** — Scale from demo to production
+
+5. **Set up continuous integration** — Schedule waves to run automatically
+
+Enjoy! 🚀

package/docs/HOOK-INSTALL.md

@@ -1,82 +1,41 @@
-# Git Pre-Push Hook Installation Guide
+# Git Pre-Push Hook Setup
 
-**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.
+**TL;DR**: The hook is **auto-installed during scaffold**. Real enforcement requires server-side GitHub branch protection.
 
 ## What the Hook Does
 
-`hooks/pre-push-policy.sh` enforces two checks at git push time:
+`hooks/pre-push-policy.sh` enforces:
+1. **Branch Policy** — No direct pushes to `main`/`master` (feature branches only)
+2. **Secret Scan** — `tools/secret_scan.py --staged` blocks credentials
 
-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.
+## Security Model
 
-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.
+**IMPORTANT**: Local hook is a **convenience defense only**—NOT cryptographic protection. Bypass with `git push --no-verify`.
 
-## Auto-Installation During Scaffold
+**Real enforcement**: Pair with GitHub branch protection (server-side). See below.
 
-**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`.
+## Auto-Installation
 
-- **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:**
+Scaffold auto-installs the hook (symlink on Unix, copy on Windows):
 
 ```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:
-
+Manual install:
 ```bash
+# Option 1: Symlink (Unix/macOS/Git 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
+# Option 2: Copy (Windows)
+cp hooks/pre-push-policy.sh .git/hooks/pre-push
 ```
 
-## Testing
-
-Before committing to org-wide deployment, verify the hook works:
-
+Test:
 ```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:

package/docs/INSTALL.md

@@ -33,7 +33,7 @@ The fastest way to get started is to use the Aesop template scaffolder. It creat
 ### Step 1: Scaffold the harness
 
 ```bash
-npx @matt82198/aesop@beta my-fleet \
+npx @matt82198/aesop my-fleet \
   --name "my-api" \
   --repos "/path/to/repo1,/path/to/repo2"
 ```
@@ -196,6 +196,75 @@ export DEBUG=1
 
 ---
 
+## Using Non-Claude Backends
+
+By default, Aesop uses Claude Code (the orchestration harness) as its backend. You can configure it to use other models via the **AgentDriver abstraction**—enabling Ollama, OpenAI-compatible endpoints, OpenRouter, and more.
+
+### Configure a backend in aesop.config.json
+
+Add or modify the `backend` section:
+
+```json
+{
+  "backend": "openai-compatible",
+  "model": "ollama-mistral",
+  "base_url": "http://localhost:11434/v1",
+  "api_key_env": "OLLAMA_API_KEY"
+}
+```
+
+Supported backends:
+- `"claude"` (default) — Claude Code CLI harness
+- `"openai-compatible"` — OpenAI Chat Completions API (Ollama, OpenRouter, etc.)
+- `"codex"` — CodeX OpenAI backend (legacy)
+
+### Example: Local Ollama
+
+To run Aesop against Mistral locally via Ollama:
+
+```bash
+# 1. Install Ollama (https://ollama.ai) and start the daemon
+ollama serve
+
+# 2. In another terminal, pull a model
+ollama pull mistral
+
+# 3. Configure Aesop to use it
+cat > aesop.config.json <<EOF
+{
+  "backend": "openai-compatible",
+  "model": "mistral",
+  "base_url": "http://localhost:11434/v1",
+  "api_key_env": "OLLAMA_API_KEY"
+}
+EOF
+
+# 4. Start Aesop (it will use Mistral for subagent dispatch)
+npx @matt82198/aesop my-fleet --name "my-api"
+```
+
+### Verification tiers: weaker backends get more checking
+
+The AgentDriver framework applies **honest verification tiers** — weaker backends (lower accuracy, no structured output) trigger stronger verification in the orchestrator:
+
+| Backend | Accuracy | Verification Tier | What it means |
+|---------|----------|-------------------|---------------|
+| Claude Code | ~0.99 | 1 (minimal) | Orchestrator trusts output; spot-check tests |
+| OpenAI (GPT-4) | ~0.95 | 2 | Validate all JSON, run full test suite |
+| Ollama (Mistral) | ~0.70 | 4 (maximum) | Validate all JSON, adversarial review, expensive repair cap |
+
+Lower tiers cost less but require more orchestrator work. See [driver/README.md](../driver/README.md) for full verification-policy details.
+
+### Troubleshooting
+
+**Backend won't connect**: Check `OLLAMA_API_KEY` (or your backend's API key env var) is set and the `base_url` is reachable.
+
+**Verification tier too strict**: If your backend is over-verified (tier 4 when it should be tier 2), update `probe_capabilities()` in the driver to report higher accuracy scores honestly.
+
+For more details, see [driver/README.md](../driver/README.md).
+
+---
+
 ## Pre-push Hook Installation
 
 The `npx` scaffold installs the pre-push hook automatically. If you cloned the repo manually, install it:
@@ -216,9 +285,10 @@ To bypass during testing: `git push --no-verify` (not recommended for production
 
 ## Next Steps
 
-1. **Read [CONFIGURE.md](CONFIGURE.md)** — Customize repos, ports, and brain root
-2. **Run [FIRST-WAVE.md](FIRST-WAVE.md)** — Test a full `/power` → `/buildsystem` cycle
-3. **Understand [CONCEPTS.md](CONCEPTS.md)** — Learn the dispatch model and state model
+1. **Read [PORTING.md](PORTING.md)** — Step-by-step guide for adopting Aesop on a foreign repo (10 common failure modes)
+2. **Read [CONFIGURE.md](CONFIGURE.md)** — Customize repos, ports, and brain root
+3. **Run [FIRST-WAVE.md](FIRST-WAVE.md)** — Test a full `/power` → `/buildsystem` cycle
+4. **Understand [CONCEPTS.md](CONCEPTS.md)** — Learn the dispatch model and state model
 4. **Explore the dashboard** — `python3 ui/serve.py` then open http://localhost:8770
 
 For troubleshooting, see the [Aesop README](../README.md#troubleshooting) or [GOVERNANCE.md](GOVERNANCE.md) for operational policies.

package/docs/PORTING.md

@@ -0,0 +1,166 @@
+# Porting Aesop to Your Repository
+
+Guide for adopters porting the orchestration harness to a foreign repo. Step-by-step with prerequisites, scaffold, config, and the 10 likeliest failure modes from real deployments.
+
+---
+
+## Prerequisites
+
+Ensure you have:
+- **Node.js** ≥18 (from `package.json`, `.nvmrc`: v18.20.5)
+- **Python** ≥3.10 (for daemons, health checks, secret-scan)
+- **Git** ≥2.40 (worktree + pre-push hooks)
+- **Bash** v4+ (or Git Bash on Windows)
+- **Optional**: Playwright (for UI verification testing); jq (for dashboard JSON)
+
+Check versions:
+```bash
+node --version && python3 --version && git --version && bash --version
+```
+
+### OS Notes
+- **Windows**: Use Git Bash for all shell commands; paths use `/c/Users/...` POSIX style
+- **Linux/macOS**: Standard Bash; ensure `/usr/bin/bash` or equivalent exists
+
+---
+
+## 1. Scaffold & Install
+
+### Step 1: Create your harness
+```bash
+npx @matt82198/aesop my-fleet \
+  --name "my-project" \
+  --repos "/path/to/repo1,/path/to/repo2"
+```
+
+Creates `my-fleet/` with daemons, skills, config, and UI.
+
+### Step 2: Copy skills to Claude Code home
+```bash
+cp -r my-fleet/skills/power ~/.claude/skills/power
+cp -r my-fleet/skills/buildsystem ~/.claude/skills/buildsystem
+```
+
+### Step 3: Configure & test
+Edit `my-fleet/aesop.config.json`:
+```json
+{
+  "backend": "claude",
+  "aesop_root": "/path/to/my-fleet",
+  "brain_root": "~/.claude",
+  "repos": [
+    { "path": "/path/to/repo1", "name": "my-project" }
+  ],
+  "dashboardPort": 8770
+}
+```
+
+Test dashboard backend (Ollama example):
+```json
+{
+  "backend": "openai-compatible",
+  "base_url": "http://localhost:11434/v1",
+  "model": "mistral",
+  "is_local": true
+}
+```
+
+### Step 4: Install pre-push hook
+```bash
+mkdir -p my-fleet/.git/hooks
+cp my-fleet/hooks/pre-push-policy.sh my-fleet/.git/hooks/pre-push
+chmod +x my-fleet/.git/hooks/pre-push
+```
+
+### Step 5: Verify with health check
+```bash
+cd my-fleet
+python tools/health_score.py
+```
+Expected output: All checks ✓; port 8770 available; git hooks installed.
+
+---
+
+## 2. First `/power`, First Wave
+
+Run the orchestrator once to prime the brain:
+```bash
+cd my-fleet
+/power
+```
+Expected output: State created (STATE.md, BUILDLOG.md, .watchdog-heartbeat).
+
+Run one complete wave:
+```bash
+/buildsystem --one-turn
+```
+Expected verdicts: All items "PASS" or "REVIEW"; zero code defects. Health score should report ≥85/100.
+
+---
+
+## 3. The 10 Likeliest Failure Modes
+
+Each: symptom → cause → fix.
+
+### 1. Secret-scan blocks legit push
+- **Symptom**: `git push` fails: "secret detected" but code has no real secret
+- **Cause**: Test fixtures with dummy secrets (credit card, API key patterns) are parsed as real
+- **Fix**: Assemble secrets at runtime: `"key" + "_" + "123"` not `"key_123"`; use `---` delimiters in comments. Secret-scan only scans staged files, not .git.
+
+### 2. Worktree isolation violated
+- **Symptom**: Editing feature branch X; changes also appear in primary tree
+- **Cause**: Agents not using isolated worktrees; sharing same `.git/index`
+- **Fix**: Each agent task must use `git worktree add ../wt-item-slug -b feature/item-slug origin/main`; verify with `git worktree list`
+
+### 3. Heartbeat stale/missing
+- **Symptom**: Watchdog won't start; error: "unreadable state dir" or "stale heartbeat"
+- **Cause**: `state/.watchdog-heartbeat` missing/corrupted or directory unreadable (permissions)
+- **Fix**: `rm -f state/.watchdog-heartbeat && bash daemons/run-watchdog.sh --once` (re-creates it)
+
+### 4. Port 8770 conflict
+- **Symptom**: `python ui/serve.py` fails: "Address already in use"
+- **Cause**: Old dashboard process still bound, or another service using port 8770
+- **Fix**: `lsof -i :8770 | grep -v PID | awk '{print $2}' | xargs kill -9` (Mac/Linux); Windows: `netstat -ano | grep 8770`, kill the PID. Or change `dashboardPort` in config.
+
+### 5. Git identity placeholder
+- **Symptom**: Pre-push hook fails: "user identity invalid"; commits fail
+- **Cause**: Git config has template defaults (e.g., "John Doe") instead of your name
+- **Fix**: `git config user.name "Your Name" && git config user.email "you@example.com"`
+
+### 6. CRLF line endings corrupt scripts
+- **Symptom**: Bash script fails: "command not found" at line 50 (but line 50 exists)
+- **Cause**: Editor/Windows converted LF to CRLF; bash reads `\r` as part of command
+- **Fix**: `git config core.autocrlf false` locally; convert file: `dos2unix daemons/run-watchdog.sh`
+
+### 7. Test count drift in CI
+- **Symptom**: Health-check fails: "expected 127 tests, got 128"
+- **Cause**: Added new test file but didn't update baseline in tools/health_score.py or CI config
+- **Fix**: Run `python tools/health_score.py --json` to get true count; update baseline in CI gate
+
+### 8. UTF-8 encoding on Windows
+- **Symptom**: Pre-publish gate fails with encoding error in secret_scan.py
+- **Cause**: Python opens files in system encoding (cp1252) instead of UTF-8
+- **Fix**: Aesop tools now force UTF-8 internally; ensure `PYTHONIOENCODING=utf-8` if running external Python scripts
+
+### 9. Cost ceiling never triggers
+- **Symptom**: Cost ceilings configured; spending uncapped; halt never fires
+- **Cause**: Claude Code driver returns `get_tokens_spent()=None`; coerces to 0; ledger fallback skipped
+- **Fix**: For Claude Code, cost tracking integrates live API; for non-Claude backends, ledger fallback logs at end of wave
+
+### 10. Hook TTY behavior blocks CI pushes
+- **Symptom**: `git push` fails in CI/cron: "cannot read stdin"; interactive prompt hangs
+- **Cause**: Hook tries to detect TTY when stdin is `/dev/null` (non-interactive context)
+- **Fix**: Hook now handles empty stdin (rc=2 for delete-only, skip scan + log); use `hooks/pre-push-policy.sh --test` in CI (no-op validation)
+
+---
+
+## Next Steps
+
+1. **Read [INSTALL.md](./INSTALL.md)** — Full setup and environment variables
+2. **Run [health_score.py](../tools/health_score.py)** — Continuous readiness checks
+3. **Explore the [README](../README.md)** — Demo walkthrough and proof numbers
+4. **For troubleshooting**, check [GOVERNANCE.md](./GOVERNANCE.md) or open an issue on GitHub
+
+---
+
+**License**: PolyForm Strict 1.0.0 (source-available, noncommercial). See [LICENSE](../LICENSE) for details.