@matt82198/aesop 0.3.2 → 0.4.1

package/CHANGELOG.md

@@ -7,6 +7,53 @@ 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
+- **Two-seat unified config** (HS-1): New `seats` configuration block allows swapping both worker AND orchestrator models from a single config block — eliminates split configuration and enables model experimentation without code changes. No-op default: existing installations remain unchanged (install-time safety).
+- **Live orchestrator-seat swap** (HS-2): Added `final_catch` gate in the wave loop with block/quarantine + crash-only degradation — orchestrator model can be swapped mid-flight without restarting the entire fleet. Failure path quarantines the wave and logs the incident.
+- **Microkernel architecture guide** (HS-3): New `docs/MICROKERNEL.md` explains the proof-of-concept model-swap seam, multi-model verification bounds, and a 60-second "swap a seat's model" quickstart for adopters.
+- **Scaffold completeness** (`npx aesop init`): driver/ directory now scaffolds on first run (was omitted, breaking adopter first-run experience). Added --force idempotent re-scaffold and child process timeout protection.
+
+### Security / Hardening
+- **IPv6 SSRF + DNS-resolution validation**: Requests to orchestrator's `base_url` now validate against IPv6 loopback and route-local semantics; DNS resolution blocked for external hostnames; `is_local` pinned to loopback only.
+- **API key environment variable allowlist** (primary enforcement): `api_key_env` rejects obvious secret patterns (AWS_SECRET, AZURE_KEY, etc.) and logs a loud NOTICE for non-standard names; fail-closed on read errors.
+- **Worker model field validation**: `worker.model` config field no longer silently ignored if orchestrator uses a non-Claude driver; now validated at load time.
+- **Wave execution timeouts**: Added `run_command` timeouts to prevent indefinite wave hangs on subprocess failures; child processes now respect explicit timeout boundaries (no more wave-level hard stops).
+- **CI merge-wait fail-closed**: `ci_merge_wait` gate now exits with explicit failure codes (not silent pass) on timeout or missing CI status, preventing accidental merges of untested code.
+- **Windows CI shard concurrency cap**: Reduced `max-parallel` for Windows runner to cut container contention flakes; Windows shard now stable on standard GitHub Actions.
+- **Path redaction completeness** (bench tooling): Bench results and logs redact full paths before reporting; `is_local` validation prevents accidental leakage of internal network topology.
+- **JSON-boundary fail-open holes patched**: Orchestrator/driver seam now validates JSON boundaries at worker<->orchestrator message crossings; malformed messages fail-closed (not skipped).
+
+### Fixed
+- **`npx aesop init` driver scaffolding**: Adopters running init on a fresh repo now get a complete driver/ directory tree; was silently omitting driver/, causing "module not found" on first wave.
+- **Scaffold idempotency + child timeouts**: Re-running init --force no longer corrupts existing templates; child scaffold processes timeout cleanly instead of hanging.
+- **Gate incumbent-validation**: Pre-gate validation of model incumbent (before swap attempt) catches incompatibilities early and logs them for forensics.
+
 ## [0.3.2] - 2026-07-23
 
 ### Fixed

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <em>Autonomous Developer for Any Repository</em>
+  <em>Crash-only multi-agent orchestration for any repository</em>
 </p>
 
 <p align="center">
@@ -14,7 +14,15 @@
 
 ## What It Does
 
-**Aesop** is a source-available orchestration harness that runs multi-agent workflows on any repository. It ranks backlog, dispatches parallel Haiku workers (scoped to disjoint file ownership), verifies merges with adversarial safety, and feeds learnings into the next wave. Durable state (SQLite + git-rendered checkpoints) survives machine wipes and enables team coordination. This repo's own 223 PRs across 880 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). The stack is portable: swappable backends (Claude Code reference, OpenAI-compatible Ollama/OpenRouter, Codex bridge), with auto-tuned verification safety calibrated per backend.
+**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 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: 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
 
@@ -86,16 +94,20 @@ Aesop is built entirely by its own `/buildsystem` wave cycle—running parallel
 
 | Metric | Value |
 | --- | --- |
-| Merged PRs | 244 <!-- metrics-verified: self_stats.py (git log) --> |
-| Total Commits | 1065 <!-- 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 | 185,174 <!-- metrics-verified: self_stats.py (git log) --> |
-| Files Tracked | 541 <!-- 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.*
 
 
@@ -108,17 +120,18 @@ 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
 
 - **[docs/INSTALL.md](./docs/INSTALL.md)** — Setup and first wave  
+- **[docs/MICROKERNEL.md](./docs/MICROKERNEL.md)** — The two swappable seats (worker + orchestrator), the invariant Report/state boundary, and a 60-second quickstart for swapping either seat's model  
 - **[docs/PORTING.md](./docs/PORTING.md)** — Adopter's guide: port Aesop to your repo (prerequisites, scaffold, 10 failure modes)  
 - **[docs/HOW-THE-LOOP-WORKS.md](./docs/HOW-THE-LOOP-WORKS.md)** — Concrete walkthrough of a wave cycle  
 - **[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
 
@@ -133,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/aesop.config.example.json

@@ -46,6 +46,22 @@
   "cardinal_rules": {
     "subagent_model": "haiku"
   },
+  "seats": {
+    "_comment": "Unified two-seat model selection (0.4.0). ONE block swaps BOTH seats: 'worker' = the coding agents (AgentDriver), 'orchestrator' = the decision seat (OrchestratorBackend). The values below ARE the defaults -- Claude Code worker + live-harness orchestrator -- so this block as shipped changes nothing; deleting it changes nothing either. To swap a seat, replace its block with one of the _worker_examples/_orchestrator_examples. Keys are read from env vars named by api_key_env at CALL time, never stored in this file. 'is_local': true = LOOPBACK endpoint only (localhost/127.0.0.1/::1 -- rejected otherwise): no API key needed, honest verification tier 3. Separate surface: cardinal_rules.subagent_model (above) pins the model for LIVE-HARNESS Claude Code subagents; seats.worker swaps the AgentDriver worker seam itself.",
+    "worker": { "backend": "claude" },
+    "orchestrator": { "backend": "harness" },
+    "_worker_examples": {
+      "_note": "Asymmetry: worker openai-compatible seats REQUIRE base_url; the orchestrator seat may omit base_url (defaults to the hosted OpenAI endpoint).",
+      "codex_hosted_openai": { "backend": "codex", "model": "gpt-4o-mini" },
+      "openai_compatible_openrouter": { "backend": "openai-compatible", "base_url": "https://openrouter.ai/api/v1", "model": "openai/gpt-4-turbo", "api_key_env": "OPENROUTER_API_KEY" },
+      "openai_compatible_local_ollama": { "backend": "openai-compatible", "base_url": "http://localhost:11434/v1", "model": "mistral", "is_local": true }
+    },
+    "_orchestrator_examples": {
+      "harness_default": { "backend": "harness" },
+      "openai_hosted": { "backend": "openai-compatible", "model": "gpt-4o-mini", "api_key_env": "OPENAI_API_KEY" },
+      "local_ollama": { "backend": "openai-compatible", "base_url": "http://localhost:11434/v1", "model": "mistral", "is_local": true }
+    }
+  },
   "limits": {
     "_comment": "Cost ceiling / kill switch (tools/cost_ceiling.py, tools/halt.py). null disables a given ceiling (feature opt-in). When spend meets or exceeds a configured ceiling, cost_ceiling.py trips tools/halt.py's .HALT sentinel, which daemons/run-watchdog.sh checks at the top of every cycle and refuses to do work (no backup, no push, no scan) until cleared via 'python tools/halt.py --clear'.",
     "max_wave_tokens": null,

package/bin/cli.js

@@ -259,7 +259,7 @@ const repoUrlsStr = getFlag('--repo-urls');
 if (fs.existsSync(targetDir)) {
   const contents = fs.readdirSync(targetDir);
   // Allow .git and aesop scaffolded files to already exist (for idempotency)
-  const aesopDirs = ['daemons', 'dash', 'monitor', 'tools', 'ui', 'docs', 'state_store', 'skills', 'mcp', 'scan', 'hooks', '.git', 'state'];
+  const aesopDirs = ['daemons', 'dash', 'monitor', 'tools', 'ui', 'docs', 'state_store', 'skills', 'mcp', 'scan', 'hooks', 'driver', '.git', 'state'];
   const aesopFiles = [
     'aesop.config.example.json',
     'aesop.config.json',
@@ -317,6 +317,7 @@ const filesToCopy = [
   'mcp',
   'scan',
   'hooks',
+  'driver',
   'aesop.config.example.json',
   'README.md',
   'LICENSE',
@@ -421,8 +422,10 @@ function generateConfigJson(targetDir, templateRoot, projectName, reposStr, repo
         port: 8770
       },
       cardinal_rules: {
+        // NOTE: orchestrator_model was RETIRED in 0.4.0 (HS-1): it was written
+        // here but read by nothing. The orchestrator seat's model now lives in
+        // seats.orchestrator.model (see aesop.config.example.json).
         subagent_model: 'haiku',
-        orchestrator_model: 'opus',
         tdd_first: true,
         never_push_main: true,
         secret_scan_gates_push: true
@@ -431,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';
@@ -464,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) => {
@@ -924,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"