@matt82198/aesop 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 **Version scheme**: Stable releases are `0.x.y`; `0.x.0-beta.N` / `-rc.N` are pre-releases; `0.1.0-wave.N` were internal wave-milestone previews.
 
+## [0.4.1] - 2026-07-26
+
+### Onboarding overhaul
+- **Config home-directory expansion** (PR #413): User-set `aesop_root: "~/myfleet"` now expands correctly via `.expanduser()` instead of treating tilde as a literal path.
+- **Reproduce graceful degradation** (PR #413): Fresh scaffolds (`.git` present, no `package-lock.json`) detect scaffold mode and run installed-mode verification instead of failing on `npm ci`; clear one-line message on graceful degrade.
+- **Scaffolder absolute paths** (PR #413): All NEXT STEPS `cd` commands in CLI output now print absolute resolved paths matching config's stored resolved paths (no relative dirs).
+- **Scaffold and doctor fixes** (PR #407): Corrected path handling in scaffolder and doctor, improved validation logic, clearer guidance on remediation.
+- **Setup docs field-name sync** (PR #405): Fixed CONFIGURE block field names and added missing Claude Code install steps; docs now match actual config structure.
+- **Watchdog smoke-test verdict** (PR #406): New `watchdog --once` exits with explicit PASS/FAIL verdict for CI/doctor integration; clear signal for fleet health checks.
+
+### CI/test hardening
+- **PowerShell syntax gate** (PR #401): Pre-commit CI gate validates all `*.ps1` files for correct syntax; prevents shell-script drift on Windows daemon scripts.
+- **Workflow_dispatch on main-full** (PR #399): Main CI now accepts manual dispatch trigger for on-demand full-suite runs without waiting for a commit.
+- **Self-updating test suite count gate** (PR #403): New `tools/verify_test_suite_count.py` auto-reconciles test counts in `tests/CLAUDE.md`; `--check` mode for CI (fail-closed on drift), `--fix` mode for lanes. Eliminates merge blocks from concurrent test additions.
+- **Frontier-slice test depollution** (PR #400): Frontier-slice benchmark output now writes to gitignored temp location instead of polluting repo; clean CI artifacts.
+- **Git-identity isolation + runtime tripwire** (PR #412): Fixed root cause of Test User ghost commits — 6 test files used shell fallthrough causing silent git config writes to shared `.git/config`. Now using direct `spawn('git', …, {cwd})` with no shell; runtime tripwire in `test_test_hygiene.py` fails suite if repo identity mutates during test run.
+
+### Honesty / stats
+- **Stats truth-sync + verify tool** (PR #411): Fixed stale v0.1.0 stats in stats.json; new `scripts/verify-stats.sh` documents single-stats-source wrapper (`self_stats --check/--regenerate`); ancestor principles named (Temporal, Candea & Fox crash-only, Erlang/OTP, K8s reconciliation).
+- **Self_stats squash-merge fix** (PR #398): Merged PR count now authoritative from GitHub API (387, up from undercounted 268). Git fallback for offline use handles both merge-commit and squash-merge styles; deduplicates on PR number.
+
+### Bench
+- **gpt-4o-mini worker seat dogfood** (PR #404): Benchmark expands with gpt-4o-mini seated as worker model; includes real context-tip item-9 discrimination and co-model A/B measurement.
+
 ## [0.4.0] - 2026-07-25
 
 ### Added

package/README.md

@@ -16,12 +16,14 @@
 
 **Aesop** is a **crash-recoverable orchestration harness** for multi-agent workflows on any repository. One-line theme: *stateless agent execution over git-backed durable memory*.
 
-Core idea: **agent behavior is source code.** Every decision lives in durable, human-diffable files—git history, plain-text STATE.md, append-only BUILDLOG.md, Python guardrails. When a machine fails, you re-read from disk. No vector DBs, no distributed consensus, no magic. This repo's own 251 merged PRs across 1088 commits were delivered by Aesop's own `/buildsystem` wave loop—a supervised loop under a human operator who sets goals and owns outward gates (npm publish, releases, history rewrites).
+Core idea: **agent behavior is source code.** Every decision lives in durable, human-diffable files—git history, plain-text STATE.md, append-only BUILDLOG.md, Python guardrails. When a machine fails, you re-read from disk. No vector DBs, no distributed consensus, no magic. This repo's own 387 merged PRs across 1181 commits were delivered by Aesop's own `/buildsystem` wave loop—a supervised loop under a human operator who sets goals and owns outward gates (npm publish, releases, history rewrites).
 
-**Why it matters:** crash recovery is not a special path; it is how the system *always* starts. Stateless workers, persistent filesystem brain, Haiku-first dispatch (4.3× cheaper than hierarchical design, proven by real A/B), fail-closed guardrails (pre-push secret gate, kill-switch, cost ceiling), and observable heartbeats. The result: 251 PRs in 11 days; Haiku at 39/39 on a 39-task benchmark vs Opus 38/39, at ~1/3 the cost.
+**Why it matters:** crash recovery is not a special path; it is how the system *always* starts. Stateless workers, persistent filesystem brain, Haiku-first dispatch (4.3× cheaper than hierarchical design, proven by real A/B), fail-closed guardrails (pre-push secret gate, kill-switch, cost ceiling), and observable heartbeats. The result: 387 PRs across 1181 commits; Haiku at 39/39 on a 39-task benchmark vs Opus 38/39, at ~1/3 the cost.
 
 **Why it's built this way:** [The Aesop Hypothesis](./docs/THE-AESOP-HYPOTHESIS.md) — the design philosophy, the trade-offs, the cancelled architectures with published data.
 
+**New in 0.4.0:** Swap the **worker** and **orchestrator** model (Claude, Codex, or any OpenAI-compatible endpoint) from one `seats` config block without code changes. See [docs/MICROKERNEL.md](./docs/MICROKERNEL.md) for the two-seat architecture and a 60-second quickstart. Single-instance proven; multi-instance coordination is scheduled.
+
 ## Feature Demo
 
 **One-turn wave** — Run a complete build cycle (tests, build, docs, review, merge, audit) end-to-end:
@@ -92,17 +94,20 @@ Aesop is built entirely by its own `/buildsystem` wave cycle—running parallel
 
 | Metric | Value |
 | --- | --- |
-| Merged PRs | 251 <!-- metrics-verified: self_stats.py (git log) --> |
-| Total Commits | 1088 <!-- metrics-verified: self_stats.py (git log) --> |
-| Project Age | 11 days <!-- metrics-verified: self_stats.py (git log) --> |
+| Merged PRs | 387 <!-- metrics-verified: self_stats.py (git log) --> |
+| Total Commits | 1181 <!-- metrics-verified: self_stats.py (git log) --> |
+| Project Age | 14 days <!-- metrics-verified: self_stats.py (git log) --> |
 | Waves | 30 <!-- metrics-verified: self_stats.py (git log) --> |
-| Insertions + Deletions | 186,587 <!-- metrics-verified: self_stats.py (git log) --> |
-| Files Tracked | 546 <!-- metrics-verified: self_stats.py (git log) --> |
+| Insertions + Deletions | 222,290 <!-- metrics-verified: self_stats.py (git log) --> |
+| Files Tracked | 642 <!-- metrics-verified: self_stats.py (git log) --> |
 | Distinct Co-authors | 11 <!-- metrics-verified: self_stats.py (git log) --> |
 
 <!-- STATS:END -->
 
 
+
+
+
 *Wave: one complete build cycle (intake → dispatch → verify → ship) run by the orchestration engine.*
 
 
@@ -115,7 +120,7 @@ Aesop is built entirely by its own `/buildsystem` wave cycle—running parallel
 
 ## Why Haiku-First Works
 
-The benchmark proves it: across 39 judgment tasks (code review, severity calibration, root-cause analysis, refactor equivalence, security spots), Haiku scored **39/39** vs Opus **38/39** at ~1/3 the per-token cost. See [`bench/results/2026-07-17-judgment-v3-haiku-sonnet-opus.md`](./bench/results/2026-07-17-judgment-v3-haiku-sonnet-opus.md). **Curated set, N=39** — Haiku 39/39 vs Opus 38/39; proves sufficiency for this workload, not frontier parity.
+The benchmark proves sufficiency: across 39 judgment tasks (code review, severity calibration, root-cause analysis, refactor equivalence, security spots), Haiku scored **39/39** vs Opus **38/39** at ~1/3 the per-token cost. See [`bench/results/2026-07-17-judgment-v3-haiku-sonnet-opus.md`](./bench/results/2026-07-17-judgment-v3-haiku-sonnet-opus.md). The pre-declared ceiling rule (when ≥2 tiers score ≥92%, the instrument failed to discriminate) trips on this result — both Haiku and Sonnet achieved 39/39, meaning the benchmark maps a *sufficiency floor*, not tier equivalence. **Curated set, N=39; scoped to extraction and judgment tasks with context at the seam** — does NOT reach frontier reasoning, long-horizon planning, or open-ended synthesis. Full analysis: [`bench/results/2026-07-26-judgment-v3-ceiling-addendum.md`](./bench/results/2026-07-26-judgment-v3-ceiling-addendum.md) and [`bench/EQUIVALENCE-MARGIN.md`](./bench/EQUIVALENCE-MARGIN.md).
 
 ## Learn More
 
@@ -126,7 +131,7 @@ The benchmark proves it: across 39 judgment tasks (code review, severity calibra
 - **[docs/DISPATCH-MODEL.md](./docs/DISPATCH-MODEL.md)** — Cost analysis and scaling  
 - **[docs/CARDINAL-RULES.md](./docs/CARDINAL-RULES.md)** — 10 foundational principles  
 - **[docs/autonomous-swe.md](./docs/autonomous-swe.md)** — What "autonomous" means (and doesn't), evidence for all claims, honest limits  
-- **[RELEASE-NOTES.md](./RELEASE-NOTES.md)** — Version 0.3.1 (the 0.3.0 milestone): non-Claude core proof (Codex wave), refinement-loop convergence, Windows-green CI
+- **[RELEASE-NOTES.md](./RELEASE-NOTES.md)** — Version 0.4.0 (the two-seat micro-kernel): swappable worker + orchestrator models from one config, live orchestrator seat-swap gate, IPv6/DNS hardening, scaffolding completeness
 
 ## Contributing
 
@@ -141,6 +146,8 @@ The repo develops itself via its own `/buildsystem` loop; code changes are made
 
 **Source-available** under the [PolyForm Strict License 1.0.0](./LICENSE). You may read, run, and use the software for any permitted purpose, but **modification and redistribution are not permitted**. See [`LICENSE`](./LICENSE) for the full terms and the definition of permitted (noncommercial and personal) purposes.
 
+**License history:** Aesop was released under the MIT License until 2026-07-17, when it was relicensed to PolyForm Strict 1.0.0. Snapshots cloned or forked before that date retain their original MIT license grant; new work lives under PolyForm Strict 1.0.0.
+
 Copyright 2026 Matt Culliton.
 
 ## References

package/bin/cli.js

@@ -434,7 +434,7 @@ function generateConfigJson(targetDir, templateRoot, projectName, reposStr, repo
   }
 
   // Update with provided values
-  exampleConfig.aesop_root = targetDir;
+  exampleConfig.aesop_root = path.resolve(targetDir);
   exampleConfig.brain_root = '~/.claude';
   exampleConfig.scripts_root = '~/scripts';
   exampleConfig.temp_root = '~/.aesop-temp';
@@ -467,14 +467,31 @@ function generateConfigJson(targetDir, templateRoot, projectName, reposStr, repo
 
 // Print next steps and optionally run watchdog (returns a Promise)
 async function printNextStepsAndWatchdog(rl, targetDir, configPath, port) {
-  console.log('\n🎯 Next 2 commands to get started:\n');
-  console.log(`  1. cd ${targetDir}`);
-  console.log('  2. bash daemons/run-watchdog.sh --once  (one-time watchdog smoke test)');
-  console.log(`  3. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:${port})`);
-  console.log('\n📖 Optional: Set up your brain (Claude Code orchestration memory):\n');
+  const resolvedTargetDir = path.resolve(targetDir);
+  console.log('\n🎯 NEXT STEPS — Customize, validate, and launch:\n');
+  console.log('1. Customize CLAUDE.md domains and team info:');
+  console.log(`     cd ${resolvedTargetDir}`);
+  console.log('     Edit CLAUDE.md — update domains, team, and project details');
+  console.log('');
+  console.log('2. Set real repository URLs in aesop.config.json:');
+  console.log('     Edit aesop.config.json — replace placeholder URLs (https://github.com/user/...) with actual repo URLs');
+  console.log('');
+  console.log('3. Copy the skills (required for orchestration):');
+  console.log('     cp ~/.claude/skills/power/SKILL.md . (verify it exists first)');
+  console.log('     cp ~/.claude/skills/buildsystem/SKILL.md . (verify it exists first)');
+  console.log('');
+  console.log('4. Run preflight checks:');
+  console.log('     aesop doctor  (or: npx @matt82198/aesop doctor)');
+  console.log('');
+  console.log('5. Launch watchdog (one-time smoke test):');
+  console.log('     bash daemons/run-watchdog.sh --once');
+  console.log('');
+  console.log(`6. Launch dashboard (on localhost:${port}):`);
+  console.log('     python3 ui/serve.py  (or python as fallback)\n');
+  console.log('📖 Optional: Set up your brain (Claude Code orchestration memory):\n');
   console.log('  mkdir -p ~/.claude/memory');
-  console.log(`  cp ${targetDir}/CLAUDE.md ~/.claude/CLAUDE.md  (review and customize)`);
-  console.log(`  cp ${targetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)\n`);
+  console.log(`  cp ${resolvedTargetDir}/CLAUDE.md ~/.claude/CLAUDE.md  (review and customize)`);
+  console.log(`  cp ${resolvedTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)\n`);
 
   return new Promise((resolve) => {
     rl.question('Run watchdog --once now? (y/N): ', (answer) => {
@@ -927,38 +944,91 @@ if (!isRuntimeCommand) {
       process.exit(0);
     } else if (wizardMode) {
       // Wizard mode with --yes flag (non-interactive)
-      console.log('\n🎯 Next 3 commands to get started:\n');
-      console.log(`  1. cd ${finalTargetDir}`);
-      console.log('  2. bash daemons/run-watchdog.sh --once  (one-time watchdog smoke test)');
-      console.log(`  3. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:${dashboardPort})`);
-      console.log('\n📖 Optional: Set up your brain (Claude Code orchestration memory):\n');
+      const resolvedFinalTargetDir = path.resolve(finalTargetDir);
+      console.log('\n🎯 NEXT STEPS — Customize, validate, and launch:\n');
+      console.log('1. Customize CLAUDE.md domains and team info:');
+      console.log(`     cd ${resolvedFinalTargetDir}`);
+      console.log('     Edit CLAUDE.md — update domains, team, and project details');
+      console.log('');
+      console.log('2. Set real repository URLs in aesop.config.json:');
+      console.log('     Edit aesop.config.json — replace placeholder URLs (https://github.com/user/...) with actual repo URLs');
+      console.log('');
+      console.log('3. Copy the skills (required for orchestration):');
+      console.log('     cp ~/.claude/skills/power/SKILL.md . (verify it exists first)');
+      console.log('     cp ~/.claude/skills/buildsystem/SKILL.md . (verify it exists first)');
+      console.log('');
+      console.log('4. Run preflight checks:');
+      console.log('     aesop doctor  (or: npx @matt82198/aesop doctor)');
+      console.log('');
+      console.log('5. Launch watchdog (one-time smoke test):');
+      console.log('     bash daemons/run-watchdog.sh --once');
+      console.log('');
+      console.log(`6. Launch dashboard (on localhost:${dashboardPort}):`);
+      console.log('     python3 ui/serve.py  (or python as fallback)');
+      console.log('');
+      console.log('📖 Optional: Set up your brain (Claude Code orchestration memory):\n');
       console.log('  mkdir -p ~/.claude/memory');
-      console.log(`  cp ${finalTargetDir}/CLAUDE.md ~/.claude/CLAUDE.md  (review and customize)`);
-      console.log(`  cp ${finalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
+      console.log(`  cp ${resolvedFinalTargetDir}/CLAUDE.md ~/.claude/CLAUDE.md  (review and customize)`);
+      console.log(`  cp ${resolvedFinalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
       process.exit(0);
     } else if (finalProjectName) {
+      const resolvedFinalTargetDir = path.resolve(finalTargetDir);
       console.log('\n✅ Headless scaffolding complete!\n');
-      console.log('🎯 Next 3 commands to get started:\n');
-      console.log(`  1. cd ${finalTargetDir}`);
-      console.log('  2. bash daemons/run-watchdog.sh --once  (one-time watchdog smoke test)');
-      console.log(`  3. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:${dashboardPort})`);
-      console.log('\n📖 Optional: Set up your brain (Claude Code orchestration memory):\n');
+      console.log('🎯 NEXT STEPS — Customize, validate, and launch:\n');
+      console.log('1. Customize CLAUDE.md domains and team info:');
+      console.log(`     cd ${resolvedFinalTargetDir}`);
+      console.log('     Edit CLAUDE.md — update domains, team, and project details');
+      console.log('');
+      console.log('2. Set real repository URLs in aesop.config.json:');
+      console.log('     Edit aesop.config.json — replace placeholder URLs (https://github.com/user/...) with actual repo URLs');
+      console.log('');
+      console.log('3. Copy the skills (required for orchestration):');
+      console.log('     cp ~/.claude/skills/power/SKILL.md . (verify it exists first)');
+      console.log('     cp ~/.claude/skills/buildsystem/SKILL.md . (verify it exists first)');
+      console.log('');
+      console.log('4. Run preflight checks:');
+      console.log('     aesop doctor  (or: npx @matt82198/aesop doctor)');
+      console.log('');
+      console.log('5. Launch watchdog (one-time smoke test):');
+      console.log('     bash daemons/run-watchdog.sh --once');
+      console.log('');
+      console.log(`6. Launch dashboard (on localhost:${dashboardPort}):`);
+      console.log('     python3 ui/serve.py  (or python as fallback)');
+      console.log('');
+      console.log('📖 Optional: Set up your brain (Claude Code orchestration memory):\n');
       console.log('  mkdir -p ~/.claude/memory');
-      console.log(`  cp ${finalTargetDir}/CLAUDE.md ~/.claude/CLAUDE.md  (review and customize)`);
-      console.log(`  cp ${finalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
+      console.log(`  cp ${resolvedFinalTargetDir}/CLAUDE.md ~/.claude/CLAUDE.md  (review and customize)`);
+      console.log(`  cp ${resolvedFinalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
     } else {
+      const resolvedFinalTargetDir = path.resolve(finalTargetDir);
       console.log('\n✅ Scaffold complete!\n');
-      console.log('🎯 Next 3 commands to get started:\n');
-      console.log(`  1. cd ${finalTargetDir}`);
-      console.log('  2. bash daemons/run-watchdog.sh --once  (one-time watchdog smoke test)');
-      console.log(`  3. python3 ui/serve.py  (or python as fallback; launch dashboard on localhost:${dashboardPort})`);
-      console.log('\n📖 Configuration steps (optional):\n');
-      console.log('  cp aesop.config.example.json aesop.config.json  (if not generated)');
-      console.log('  Edit aesop.config.json with your configuration');
-      console.log('\n📖 Optional: Set up your brain (Claude Code orchestration memory):\n');
+      console.log('🎯 NEXT STEPS — Customize, validate, and launch:\n');
+      console.log('1. Create aesop.config.json from example:');
+      console.log('     cp aesop.config.example.json aesop.config.json');
+      console.log(`     cd ${resolvedFinalTargetDir}`);
+      console.log('     Edit aesop.config.json with your configuration and actual repository URLs');
+      console.log('');
+      console.log('2. Customize CLAUDE.md domains and team info:');
+      console.log('     Edit CLAUDE-TEMPLATE.md and save as CLAUDE.md');
+      console.log('     Update domains, team, and project details');
+      console.log('');
+      console.log('3. Copy the skills (required for orchestration):');
+      console.log('     cp ~/.claude/skills/power/SKILL.md . (verify it exists first)');
+      console.log('     cp ~/.claude/skills/buildsystem/SKILL.md . (verify it exists first)');
+      console.log('');
+      console.log('4. Run preflight checks:');
+      console.log('     aesop doctor  (or: npx @matt82198/aesop doctor)');
+      console.log('');
+      console.log('5. Launch watchdog (one-time smoke test):');
+      console.log('     bash daemons/run-watchdog.sh --once');
+      console.log('');
+      console.log(`6. Launch dashboard (on localhost:${dashboardPort}):`);
+      console.log('     python3 ui/serve.py  (or python as fallback)');
+      console.log('');
+      console.log('📖 Optional: Set up your brain (Claude Code orchestration memory):\n');
       console.log('  mkdir -p ~/.claude/memory');
-      console.log(`  cp ${finalTargetDir}/CLAUDE-TEMPLATE.md ~/.claude/CLAUDE.md  (then edit domains/team info)`);
-      console.log(`  cp ${finalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
+      console.log(`  cp ${resolvedFinalTargetDir}/CLAUDE-TEMPLATE.md ~/.claude/CLAUDE.md  (then edit domains/team info)`);
+      console.log(`  cp ${resolvedFinalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
     }
     console.log('\nFor full documentation, see the README.md in the scaffolded directory.');
     process.exit(0);

package/daemons/run-watchdog.sh

@@ -228,6 +228,7 @@ main() {
   if [ "$MODE" = "--once" ]; then
     if check_halt "$AESOP_ROOT/state/FLEET-BACKUP.log"; then
       release_lock "$LOCK_DIR"
+      printf 'WATCHDOG SMOKE: PASSED\n'
       exit 0
     fi
     full_out=$("${CYCLE_CMD_ARRAY[@]}" 2>&1)
@@ -236,13 +237,16 @@ main() {
     if [ $cmd_exit -ne 0 ]; then
       err_msg="[$(date '+%F %T')] ERROR: cycle #1 failed with exit code $cmd_exit"
       echo "$err_msg" >> "$AESOP_ROOT/state/FLEET-BACKUP.log"
-      echo "[ERROR: exit $cmd_exit]" >&2
+      printf 'WATCHDOG SMOKE: FAILED — [ERROR: exit %d]\n' "$cmd_exit" >&2
+      release_lock "$LOCK_DIR"
+      exit $cmd_exit
     fi
     if [ -n "$PYTHON_EXE" ]; then
       "$PYTHON_EXE" "$AESOP_ROOT/tools/alert_bridge.py" --scan || true
     fi
     release_lock "$LOCK_DIR"
-    exit $cmd_exit
+    printf 'WATCHDOG SMOKE: PASSED\n'
+    exit 0
   fi
 
   n=0

package/docs/CONFIGURE.md

@@ -10,8 +10,8 @@ After setup, you'll have an `aesop.config.json` in your harness root. This file
 
 ```json
 {
-  "aesopRoot": "/home/user/aesop",
-  "braindRoot": "/home/user/.claude",
+  "aesop_root": "/home/user/aesop",
+  "brain_root": "/home/user/.claude",
   "repos": [
     {
       "path": "/home/user/my-api",
@@ -22,14 +22,16 @@ After setup, you'll have an `aesop.config.json` in your harness root. This file
       "name": "web-frontend"
     }
   ],
-  "dashboardPort": 8770,
+  "dashboard": {
+    "port": 8770
+  },
   "dashboardOrigin": "http://localhost:8770"
 }
 ```
 
 ### Field Reference
 
-#### `aesopRoot` (string, required)
+#### `aesop_root` (string, required)
 
 Absolute path to this Aesop harness directory. Used by daemons to locate scripts and state files.
 
@@ -39,7 +41,7 @@ Absolute path to this Aesop harness directory. Used by daemons to locate scripts
 
 ---
 
-#### `braindRoot` (string, required)
+#### `brain_root` (string, required)
 
 Absolute path to your Claude Code home directory. This is where skills (`.claude/skills/`) and memory (`.claude/MEMORY.md`) live.
 
@@ -78,7 +80,7 @@ Each repo object has:
 
 ---
 
-#### `dashboardPort` (number, default: 8770)
+#### `dashboard.port` (number, default: 8770)
 
 HTTP port for the web dashboard. The dashboard runs a Python HTTP server on this port.
 
@@ -116,15 +118,17 @@ The origin (scheme + host + port) for the dashboard. Used for CORS validation an
 
 ```json
 {
-  "aesopRoot": "/home/user/aesop",
-  "braindRoot": "/home/user/.claude",
+  "aesop_root": "/home/user/aesop",
+  "brain_root": "/home/user/.claude",
   "repos": [
     {
       "path": "/home/user/my-app",
       "name": "my-app"
     }
   ],
-  "dashboardPort": 8770,
+  "dashboard": {
+    "port": 8770
+  },
   "dashboardOrigin": "http://localhost:8770"
 }
 ```
@@ -133,8 +137,8 @@ The origin (scheme + host + port) for the dashboard. Used for CORS validation an
 
 ```json
 {
-  "aesopRoot": "/home/user/aesop",
-  "braindRoot": "/home/user/.claude",
+  "aesop_root": "/home/user/aesop",
+  "brain_root": "/home/user/.claude",
   "repos": [
     {
       "path": "/home/user/services/auth",
@@ -153,7 +157,9 @@ The origin (scheme + host + port) for the dashboard. Used for CORS validation an
       "name": "infrastructure"
     }
   ],
-  "dashboardPort": 8770,
+  "dashboard": {
+    "port": 8770
+  },
   "dashboardOrigin": "http://localhost:8770"
 }
 ```
@@ -162,15 +168,17 @@ The origin (scheme + host + port) for the dashboard. Used for CORS validation an
 
 ```json
 {
-  "aesopRoot": "C:\\Users\\user\\aesop",
-  "braindRoot": "C:\\Users\\user\\.claude",
+  "aesop_root": "C:\\Users\\user\\aesop",
+  "brain_root": "C:\\Users\\user\\.claude",
   "repos": [
     {
       "path": "C:\\Users\\user\\projects\\my-api",
       "name": "api"
     }
   ],
-  "dashboardPort": 8770,
+  "dashboard": {
+    "port": 8770
+  },
   "dashboardOrigin": "http://localhost:8770"
 }
 ```
@@ -205,14 +213,17 @@ Aesop credentials (GitHub tokens, API keys) should never go in `aesop.config.jso
 You can override config values via environment variables (optional):
 
 ```bash
-# Override the Aesop root
+# Override the Aesop root (used by daemons)
 export AESOP_ROOT=/path/to/aesop
 
-# Override the Claude Code home
-export CLAUDE_CODE_HOME=/path/to/.claude
+# Override the Aesop state directory (default: ./state)
+export AESOP_STATE_ROOT=/path/to/state
+
+# Override the Claude Code home (used by /power skill and orchestrator)
+export BRAIN_ROOT=/path/to/.claude
 
-# Enable debug logging in daemons
-export DEBUG=1
+# Override the scripts directory
+export SCRIPTS_ROOT=/path/to/scripts
 ```
 
 If set, these override the values in `aesop.config.json`.

package/docs/FIRST-WAVE.md

@@ -47,19 +47,39 @@ This tells you the orchestrator is ready.
 
 Before running a wave, you need ranked work. The orchestrator needs to know what to build.
 
-### Create an initial backlog
+### Where your backlog lives
 
-In your orchestrator (Claude Code) or in a scratch file, write down 2–5 small tasks:
+Create a `state/BACKLOG.md` file (or update the backlog section in `state/STATE.md`). Use this markdown format:
 
-**Example backlog**:
-```
-P1: Add README docs for orchestration
-P2: Fix typo in dashboard title
-P2: Add unit test coverage for config loader
-P3: Document the watchdog daemon
+```markdown
+# Wave 15 Backlog
+
+## P1: Critical
+
+- [ ] Fix secret-scan gate hang (blocking CI) — backend-dev — 5min
+- [ ] Update MEMORY.md with wave-15 learnings — docs-agent — 3min
+
+## P2: Features
+
+- [ ] Add cost-ceiling dashboard widget — frontend-dev — 8min
+- [ ] Implement fleet-ops monitoring — backend-dev — 10min
+
+## P3: Tech Debt
+
+- [ ] Refactor monitor/collect-signals.mjs (duplicate checks) — backend-dev — 15min
+- [ ] Add type hints to Python tools — test-bot — 10min
 ```
 
-**Backlog principles**:
+**Backlog format**:
+- **Sections**: Group by priority (P1/P2/P3)
+- **Items**: Checkbox (`[ ]`) + title + agent type + time estimate
+- **Sizing guide**:
+  - **3–5 min**: Typo fix, simple config change, one-line refactor
+  - **5–10 min**: New function, small feature, unit test
+  - **10–15 min**: Module refactor, feature with 2–3 functions
+  - **15+ min**: Split into smaller items (waves work best in 30–90 min total)
+
+### Backlog principles
 
 - **Sized for Haiku**: Each task should take 1 Haiku agent 3–10 minutes (not 30 minutes)
 - **Scoped**: "Fix auth timeout" is better than "Refactor auth system"

package/docs/INSTALL.md

@@ -2,6 +2,9 @@
 
 **TL;DR**: Install Aesop in ~5 minutes using `npx`, set your repos, then verify with a single watchdog test run.
 
+**New repo?** Follow the scaffolding guide below.
+**Existing repo?** See [PORTING.md](PORTING.md) for adopting Aesop on a foreign codebase (with 10 common pitfalls covered).
+
 ---
 
 ## Prerequisites
@@ -15,7 +18,26 @@ Before you start, make sure you have:
 - **Python** (v3.10+) — for secret-scan and log rotation
 - **jq** (optional) — for TUI dashboard parsing
 
-Check your versions:
+### Install Claude Code CLI
+
+Claude Code is required to run `/power` and `/buildsystem` skills.
+
+**Download and install**:
+- Visit https://claude.com/claude-code to download and install Claude Code for your operating system
+
+**Verify installation**:
+```bash
+claude --version
+```
+
+Expected output: `Claude Code vX.Y.Z` (v0.1 or higher)
+
+**If not on PATH**: On macOS/Linux, add the install directory to your `$PATH`. On Windows, the installer registers Claude Code in your PATH automatically. If `claude` is not found:
+- Reinstall Claude Code and ensure the installer adds it to PATH
+- Or add the installation directory to PATH manually (usually `~/.claude/bin` or `C:\Program Files\Claude Code\bin`)
+
+### Check your versions
+
 ```bash
 claude --version
 git --version
@@ -61,6 +83,15 @@ cp -r skills/power/ ~/.claude/skills/power/
 cp -r skills/buildsystem/ ~/.claude/skills/buildsystem/
 ```
 
+**Verify the skills were copied**:
+```bash
+# Check both skills exist
+ls -la ~/.claude/skills/power/SKILL.md
+ls -la ~/.claude/skills/buildsystem/SKILL.md
+```
+
+Expected output: Two SKILL.md files should exist.
+
 ### Step 3: Verify the installation
 
 Run the watchdog once to test everything:
@@ -79,6 +110,8 @@ Expected output:
 
 If you see errors, check the logs in `state/FLEET-BACKUP.log`.
 
+**Note**: The `reproduce` command runs full test suites if you're working in the aesop repo itself. For scaffolded fleets, verification uses `aesop doctor` + `watchdog --once` to check preflight requirements and basic health.
+
 ---
 
 ## Manual Setup: Git Clone (For Development)
@@ -101,8 +134,8 @@ Open `aesop.config.json` and customize for your repos (see [CONFIGURE.md](CONFIG
 
 ```json
 {
-  "aesopRoot": "/home/user/my-aesop",
-  "braindRoot": "/home/user/.claude",
+  "aesop_root": "/home/user/my-aesop",
+  "brain_root": "/home/user/.claude",
   "repos": [
     {
       "path": "/home/user/my-repo1",
@@ -113,7 +146,9 @@ Open `aesop.config.json` and customize for your repos (see [CONFIGURE.md](CONFIG
       "name": "my-frontend"
     }
   ],
-  "dashboardPort": 8770,
+  "dashboard": {
+    "port": 8770
+  },
   "dashboardOrigin": "http://localhost:8770"
 }
 ```
@@ -169,10 +204,10 @@ After setup, you'll have:
 ### Configuration files
 
 - **aesop.config.json** — Main configuration (git-ignored, never commit credentials)
-  - `aesopRoot` — path to this harness directory
-  - `braindRoot` — path to Claude Code home (`~/.claude`)
+  - `aesop_root` — path to this harness directory
+  - `brain_root` — path to Claude Code home (`~/.claude`)
   - `repos` — list of monitored repositories
-  - `dashboardPort` — web dashboard port (default: 8770)
+  - `dashboard.port` — web dashboard port (default: 8770)
   - `dashboardOrigin` — CORS origin validation
 
 - **aesop.config.example.json** — Template with defaults (commit this, use as reference)
@@ -184,18 +219,48 @@ After setup, you'll have:
 Optional environment variables you can set in your shell:
 
 ```bash
-# Point to the Aesop harness root (used by daemons)
+# Point to the Aesop harness root (used by daemons and tools)
 export AESOP_ROOT=/home/user/my-aesop
 
-# Optional: custom location for Claude Code home
-export CLAUDE_CODE_HOME=/home/user/.claude
+# Optional: custom location for Aesop state directory (default: ./state)
+export AESOP_STATE_ROOT=/home/user/my-aesop/state
 
-# Optional: enable debug output in daemons
-export DEBUG=1
+# Optional: custom location for Claude Code home (used by /power skill)
+export BRAIN_ROOT=/home/user/.claude
+
+# Optional: custom location for reusable scripts directory
+export SCRIPTS_ROOT=/home/user/scripts
 ```
 
 ---
 
+## Already Have Aesop? Quick Setup
+
+If you've already scaffolded Aesop and just need to get running:
+
+1. **Verify your config**:
+   ```bash
+   node -e "console.log(JSON.parse(require('fs').readFileSync('aesop.config.json')))"
+   ```
+
+2. **Verify the setup**:
+   ```bash
+   bash daemons/run-watchdog.sh --once
+   ```
+
+3. **Copy skills** (if not done yet):
+   ```bash
+   cp -r skills/power/ ~/.claude/skills/power/
+   cp -r skills/buildsystem/ ~/.claude/skills/buildsystem/
+   ```
+
+4. **Run your first wave**:
+   - Open Claude Code
+   - Type `/power` to prime your brain
+   - Type `/buildsystem` to start a wave (see [FIRST-WAVE.md](FIRST-WAVE.md))
+
+---
+
 ## 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.

package/docs/PORTING.md

@@ -2,6 +2,10 @@
 
 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.
 
+**Quick decision**:
+- **New harness directory?** See [INSTALL.md](INSTALL.md) for the quick 5-minute scaffold.
+- **Existing codebase?** You're in the right place. This guide covers integrating Aesop into your project with common pitfalls.
+
 ---
 
 ## Prerequisites