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

package/bin/cli.js

@@ -3,10 +3,55 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const readline = require('readline');
+const { execSync } = require('child_process');
 
 const args = process.argv.slice(2);
 const helpFlag = args.includes('--help') || args.includes('-h');
 const forceFlag = args.includes('--force');
+const yesFlag = args.includes('--yes');
+
+// Detect if stdin is a TTY (interactive terminal)
+function isInteractive() {
+  return process.stdin.isTTY && process.stdout.isTTY;
+}
+
+// Discover git repositories under a base directory (non-recursive first level)
+function discoverRepos(baseDir) {
+  const repos = [];
+  try {
+    if (!fs.existsSync(baseDir)) return repos;
+    const entries = fs.readdirSync(baseDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && !entry.name.startsWith('.')) {
+        const fullPath = path.join(baseDir, entry.name);
+        const gitDir = path.join(fullPath, '.git');
+        if (fs.existsSync(gitDir)) {
+          repos.push({ name: entry.name, path: fullPath });
+        }
+      }
+    }
+  } catch (e) {
+    // Silently ignore discovery errors
+  }
+  return repos;
+}
+
+// Interactive prompt via readline (exported for testing)
+async function promptUser(rl, prompt, defaultValue) {
+  return new Promise((resolve) => {
+    const displayPrompt = defaultValue ? `${prompt} (${defaultValue}): ` : `${prompt}: `;
+    rl.question(displayPrompt, (answer) => {
+      resolve(answer.trim() || defaultValue || '');
+    });
+  });
+}
+
+// Validate port is a number
+function validatePort(port) {
+  const p = parseInt(port, 10);
+  return !isNaN(p) && p > 0 && p < 65536 ? p : null;
+}
 
 // Parse named flags
 function getFlag(flagName) {
@@ -23,6 +68,10 @@ aesop — Multi-agent orchestration template scaffolder
 
 Usage:
   npx @matt82198/aesop [target-dir] [options]
+  npx @matt82198/aesop wizard [options]
+
+Commands:
+  wizard                  Interactive onboarding (prompts for project name, repos, port)
 
 Arguments:
   target-dir    Directory to scaffold the template into (default: "aesop-fleet")
@@ -30,6 +79,7 @@ Arguments:
 Options:
   --help, -h              Show this help message
   --force                 Replace any existing .git/hooks/pre-push during scaffold
+  --yes                   Skip interactive prompts, use defaults (CI-safe)
   --name <name>           Project name (for headless scaffolding; generates CLAUDE.md + aesop.config.json)
   --domains <list>        Comma-separated domain list (e.g., "api,worker,monitoring")
   --repos <paths>         Comma-separated repo paths (e.g., "/path/to/repo1,/path/to/repo2")
@@ -37,6 +87,7 @@ Options:
 Examples:
   npx @matt82198/aesop                                      # Creates ./aesop-fleet/ with template
   npx @matt82198/aesop my-fleet                             # Creates ./my-fleet/ with template
+  npx @matt82198/aesop wizard                               # Interactive onboarding (60-second setup)
   npx @matt82198/aesop my-fleet --force                     # Re-scaffold and replace hooks
   npx @matt82198/aesop orchestrator --name "my-service"     # Headless: generates CLAUDE.md + config
 
@@ -46,7 +97,13 @@ Examples:
   Full headless with domains and repos (PowerShell):
     npx @matt82198/aesop orchestrator --name "api" --domains "server,worker" --repos "C:\path\to\api"
 
-After scaffolding with --name, cd into the directory and:
+Interactive wizard flow:
+  1. Run: npx @matt82198/aesop wizard
+  2. Answer prompts (press Enter for defaults): project name, repos to watch, port, brain root
+  3. Scaffolds template, writes aesop.config.json, prints next steps
+  4. Optionally runs watchdog smoke test
+
+After scaffolding, cd into the directory and:
   1. Review CLAUDE.md (pre-filled with your project info)
   2. Review aesop.config.json (pre-configured for your repos)
   3. Run: bash daemons/run-watchdog.sh --once
@@ -55,6 +112,27 @@ After scaffolding with --name, cd into the directory and:
   process.exit(0);
 }
 
+// Check if wizard mode is requested (either as first arg or after targetDir)
+// e.g., "aesop wizard" or "aesop my-dir wizard"
+let wizardModeRequested = false;
+let wizardArgIndex = -1;
+
+// Check if 'wizard' is in the args
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === 'wizard') {
+    wizardModeRequested = true;
+    wizardArgIndex = i;
+    break;
+  }
+}
+
+const wizardMode = wizardModeRequested || (args.length === 0 && isInteractive());
+
+// Handle wizard mode by removing 'wizard' from args
+if (wizardModeRequested && wizardArgIndex >= 0) {
+  args.splice(wizardArgIndex, 1);
+}
+
 // Extract targetDir (first non-flag argument, excluding flag values)
 // Build set of indices consumed as flag values (tokens after --name/--domains/--repos)
 const consumedIndices = new Set();
@@ -266,6 +344,38 @@ function generateConfigJson(targetDir, templateRoot, projectName, reposStr) {
   return exampleConfig;
 }
 
+// Print next steps and optionally run watchdog (returns a Promise)
+async function printNextStepsAndWatchdog(rl, targetDir, configPath, port) {
+  console.log('\n🎯 Next 3 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. python ui/serve.py  (launch dashboard on localhost:${port})`);
+  console.log('\n📖 After that, review:');
+  console.log('  • CLAUDE.md (pre-filled with your project info)');
+  console.log('  • aesop.config.json (pre-configured for your repos)');
+  console.log('  • docs/MEMORY-TEMPLATE.md (edit ~/.claude/MEMORY.md with your facts)\n');
+
+  return new Promise((resolve) => {
+    rl.question('Run watchdog --once now? (y/N): ', (answer) => {
+      if (answer.toLowerCase() === 'y') {
+        console.log('\nRunning watchdog smoke test...');
+        try {
+          const watchdogScript = path.join(targetDir, 'daemons', 'run-watchdog.sh');
+          if (fs.existsSync(watchdogScript)) {
+            // Use bash to run the script
+            execSync(`bash "${watchdogScript}" --once`, { stdio: 'inherit', cwd: targetDir });
+            console.log('\n✓ Watchdog smoke test completed');
+          }
+        } catch (e) {
+          console.error('\n⚠ Watchdog test failed (this is OK, continue manually)');
+        }
+      }
+      rl.close();
+      resolve();
+    });
+  });
+}
+
 function installPrePushHook(targetDir, templateRoot) {
   // Try to locate .git directory
   const gitDir = path.join(targetDir, '.git');
@@ -374,83 +484,186 @@ function installPrePushHook(targetDir, templateRoot) {
   }
 }
 
-try {
-  filesToCopy.forEach(item => {
-    const src = path.join(templateRoot, item);
-    const dest = path.join(targetDir, item);
-    if (fs.existsSync(src)) {
-      copyRecursive(src, dest);
-      console.log(`✓ Copied ${item}`);
+// Main execution function
+(async () => {
+  try {
+    let finalProjectName = projectName;
+    let finalReposStr = reposStr;
+    let finalDomainsStr = domainsStr;
+    let finalTargetDir = targetDir;
+    let configPath = path.join(targetDir, 'aesop.config.json');
+    let dashboardPort = 8770;
+
+    let wizardRl = null;
+
+    // Handle wizard mode
+    if (wizardMode && isInteractive() && !yesFlag) {
+      wizardRl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+      });
+
+      console.log('\n🪄 Aesop interactive onboarding wizard');
+      console.log('═'.repeat(50));
+      console.log('Answer these 4 questions to set up your fleet in 60 seconds.');
+      console.log('Press Enter to accept defaults (shown in parentheses).\n');
+
+      // Q1: Project name
+      finalProjectName = await promptUser(wizardRl, 'Project name', 'my-fleet');
+
+      // Q2: Repos to watch
+      console.log('\nDiscovering git repos in your home directory...');
+      const discoveredRepos = discoverRepos(os.homedir());
+      let selectedRepos = '';
+
+      if (discoveredRepos.length > 0) {
+        console.log(`Found ${discoveredRepos.length} git repo(s):\n`);
+        discoveredRepos.forEach((repo, i) => {
+          console.log(`  ${i + 1}. ${repo.name} (${repo.path})`);
+        });
+        console.log('\nEnter repo paths to watch (comma-separated), or press Enter to skip:');
+        selectedRepos = await promptUser(wizardRl, 'Repos', '');
+        if (!selectedRepos && discoveredRepos.length > 0) {
+          // Auto-select the first discovered repo if user presses Enter
+          selectedRepos = discoveredRepos[0].path;
+          console.log(`  → Using: ${selectedRepos}`);
+        }
+      } else {
+        selectedRepos = await promptUser(wizardRl, 'Repos to watch (paths, comma-separated)', '');
+      }
+      finalReposStr = selectedRepos;
+
+      // Q3: Dashboard port
+      let port = '';
+      while (!port) {
+        port = await promptUser(wizardRl, 'Dashboard port', '8770');
+        const validPort = validatePort(port);
+        if (!validPort) {
+          console.log('  ✗ Invalid port. Must be a number between 1 and 65535.');
+          port = '';
+        } else {
+          dashboardPort = validPort;
+        }
+      }
+
+      // Q4: Brain root
+      const brainRoot = await promptUser(wizardRl, 'Brain root directory', '~/.claude');
+
+      console.log('\n✨ Scaffolding your fleet...\n');
+
+      // Update config path for wizard-generated config
+      configPath = path.join(finalTargetDir, 'aesop.config.json');
+    } else if (yesFlag && wizardMode) {
+      // Non-interactive defaults for wizard mode with --yes
+      finalProjectName = 'my-fleet';
+      finalReposStr = '';
+      dashboardPort = 8770;
+      console.log('🪄 Running onboarding wizard with defaults (--yes)');
     }
-  });
 
-  // Create state/ directory
-  const stateDir = path.join(targetDir, 'state');
-  if (!fs.existsSync(stateDir)) {
-    fs.mkdirSync(stateDir, { recursive: true });
-    console.log('✓ Created state/ directory');
-  }
+    // Copy template files
+    filesToCopy.forEach(item => {
+      const src = path.join(templateRoot, item);
+      const dest = path.join(finalTargetDir, item);
+      if (fs.existsSync(src)) {
+        copyRecursive(src, dest);
+        console.log(`✓ Copied ${item}`);
+      }
+    });
 
-  // If --name provided, generate CLAUDE.md and aesop.config.json
-  if (projectName) {
-    // Generate CLAUDE.md from template
-    const templatePath = path.join(targetDir, 'CLAUDE-TEMPLATE.md');
-    const claudeMdPath = path.join(targetDir, 'CLAUDE.md');
-    if (fs.existsSync(templatePath)) {
-      const templateContent = fs.readFileSync(templatePath, 'utf8');
-      const claudeContent = substituteTemplate(templateContent, projectName, domainsStr, reposStr);
-      fs.writeFileSync(claudeMdPath, claudeContent);
-      console.log('✓ Generated CLAUDE.md (from template with substitutions)');
+    // Create state/ directory
+    const stateDir = path.join(finalTargetDir, 'state');
+    if (!fs.existsSync(stateDir)) {
+      fs.mkdirSync(stateDir, { recursive: true });
+      console.log('✓ Created state/ directory');
     }
 
-    // Generate aesop.config.json
-    const configPath = path.join(targetDir, 'aesop.config.json');
-    const config = generateConfigJson(targetDir, templateRoot, projectName, reposStr);
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
-    console.log('✓ Generated aesop.config.json (configured for your repos)');
-  }
+    // If --name or wizard provided, generate CLAUDE.md and aesop.config.json
+    if (finalProjectName) {
+      // Generate CLAUDE.md from template
+      const templatePath = path.join(finalTargetDir, 'CLAUDE-TEMPLATE.md');
+      const claudeMdPath = path.join(finalTargetDir, 'CLAUDE.md');
+      if (fs.existsSync(templatePath)) {
+        const templateContent = fs.readFileSync(templatePath, 'utf8');
+        const claudeContent = substituteTemplate(templateContent, finalProjectName, finalDomainsStr, finalReposStr);
+        fs.writeFileSync(claudeMdPath, claudeContent);
+        console.log('✓ Generated CLAUDE.md (from template with substitutions)');
+      }
 
-  // Copy MEMORY-TEMPLATE.md as MEMORY-SEED.md
-  const memoryTemplatePath = path.join(templateRoot, 'docs', 'MEMORY-TEMPLATE.md');
-  const memorySeedPath = path.join(targetDir, 'MEMORY-SEED.md');
-  if (fs.existsSync(memoryTemplatePath) && !fs.existsSync(memorySeedPath)) {
-    fs.copyFileSync(memoryTemplatePath, memorySeedPath);
-    console.log('✓ Copied MEMORY-SEED.md (template for your facts)');
-  }
+      // Check if aesop.config.json already exists (for wizard mode)
+      if (fs.existsSync(configPath) && wizardMode && isInteractive()) {
+        // This should not happen in wizard mode since we're creating a new targetDir
+        // But if it does, warn and skip
+        console.warn(`⚠ Warning: aesop.config.json already exists at ${configPath}`);
+      } else {
+        // Generate aesop.config.json
+        const config = generateConfigJson(finalTargetDir, templateRoot, finalProjectName, finalReposStr);
+        // Update dashboard port if specified in wizard mode
+        if (wizardMode && dashboardPort !== 8770) {
+          config.dashboard.refresh_seconds = 1;
+        }
+        fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+        console.log('✓ Generated aesop.config.json (configured for your repos)');
+      }
+    }
 
-  // Install the pre-push hook
-  installPrePushHook(targetDir, templateRoot);
-
-  console.log(`\n✅ Scaffolded aesop template into "${targetDir}" (${copiedCount} files)`);
-
-  if (projectName) {
-    console.log('\nHeadless scaffolding complete! Next steps:');
-    console.log(`  1. cd ${targetDir}`);
-    console.log('  2. Review CLAUDE.md (pre-filled with your project info)');
-    console.log('  3. Review aesop.config.json (pre-configured for your repos)');
-    console.log('\nInitialize your brain (Claude Code team memory):');
-    console.log('  4. mkdir -p ~/.claude/memory');
-    console.log(`  5. cp ${targetDir}/CLAUDE.md ~/.claude/CLAUDE.md  (or review existing ~/.claude/CLAUDE.md)`);
-    console.log(`  6. cp ${targetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
-    console.log('\nRun the daemon and dashboard:');
-    console.log('  7. bash daemons/run-watchdog.sh --once  (test run)');
-    console.log('  8. python ui/serve.py  (launch dashboard on localhost:8770)');
-  } else {
-    console.log('\nConfiguration steps:');
-    console.log(`  1. cd ${targetDir}`);
-    console.log('  2. cp aesop.config.example.json aesop.config.json');
-    console.log('  3. Edit aesop.config.json with your configuration');
-    console.log('\nInitialize your brain (Claude Code team memory):');
-    console.log('  4. mkdir -p ~/.claude/memory');
-    console.log(`  5. cp ${targetDir}/CLAUDE-TEMPLATE.md ~/.claude/CLAUDE.md  (then edit domains/team info)`);
-    console.log(`  6. cp ${targetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
-    console.log('\nRun the daemon and dashboard:');
-    console.log('  7. bash daemons/run-watchdog.sh --once  (test run)');
-    console.log('  8. python ui/serve.py  (launch dashboard on localhost:8770)');
+    // Copy MEMORY-TEMPLATE.md as MEMORY-SEED.md
+    const memoryTemplatePath = path.join(templateRoot, 'docs', 'MEMORY-TEMPLATE.md');
+    const memorySeedPath = path.join(finalTargetDir, 'MEMORY-SEED.md');
+    if (fs.existsSync(memoryTemplatePath) && !fs.existsSync(memorySeedPath)) {
+      fs.copyFileSync(memoryTemplatePath, memorySeedPath);
+      console.log('✓ Copied MEMORY-SEED.md (template for your facts)');
+    }
+
+    // Install the pre-push hook
+    installPrePushHook(finalTargetDir, templateRoot);
+
+    console.log(`\n✅ Scaffolded aesop template into "${finalTargetDir}" (${copiedCount} files)`);
+
+    if (wizardMode && wizardRl) {
+      // Wizard mode: print next steps and offer to run watchdog
+      await printNextStepsAndWatchdog(wizardRl, finalTargetDir, configPath, dashboardPort);
+      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. python ui/serve.py  (launch dashboard on localhost:${dashboardPort})`);
+      console.log('\n📖 After that, review:');
+      console.log('  • CLAUDE.md (pre-filled with your project info)');
+      console.log('  • aesop.config.json (pre-configured for your repos)');
+      console.log('  • docs/MEMORY-TEMPLATE.md (edit ~/.claude/MEMORY.md with your facts)');
+      process.exit(0);
+    } else if (finalProjectName) {
+      console.log('\nHeadless scaffolding complete! Next steps:');
+      console.log(`  1. cd ${finalTargetDir}`);
+      console.log('  2. Review CLAUDE.md (pre-filled with your project info)');
+      console.log('  3. Review aesop.config.json (pre-configured for your repos)');
+      console.log('\nInitialize your brain (Claude Code team memory):');
+      console.log('  4. mkdir -p ~/.claude/memory');
+      console.log(`  5. cp ${finalTargetDir}/CLAUDE.md ~/.claude/CLAUDE.md  (or review existing ~/.claude/CLAUDE.md)`);
+      console.log(`  6. cp ${finalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
+      console.log('\nRun the daemon and dashboard:');
+      console.log('  7. bash daemons/run-watchdog.sh --once  (test run)');
+      console.log('  8. python ui/serve.py  (launch dashboard on localhost:8770)');
+    } else {
+      console.log('\nConfiguration steps:');
+      console.log(`  1. cd ${finalTargetDir}`);
+      console.log('  2. cp aesop.config.example.json aesop.config.json');
+      console.log('  3. Edit aesop.config.json with your configuration');
+      console.log('\nInitialize your brain (Claude Code team memory):');
+      console.log('  4. mkdir -p ~/.claude/memory');
+      console.log(`  5. cp ${finalTargetDir}/CLAUDE-TEMPLATE.md ~/.claude/CLAUDE.md  (then edit domains/team info)`);
+      console.log(`  6. cp ${finalTargetDir}/MEMORY-SEED.md ~/.claude/MEMORY.md  (then add your facts)`);
+      console.log('\nRun the daemon and dashboard:');
+      console.log('  7. bash daemons/run-watchdog.sh --once  (test run)');
+      console.log('  8. python ui/serve.py  (launch dashboard on localhost:8770)');
+    }
+    console.log('\nFor full documentation, see the README.md in the scaffolded directory.');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Error scaffolding template: ${err.message}`);
+    process.exit(1);
   }
-  console.log('\nFor full documentation, see the README.md in the scaffolded directory.');
-  process.exit(0);
-} catch (err) {
-  console.error(`Error scaffolding template: ${err.message}`);
-  process.exit(1);
-}
+})();

package/daemons/CLAUDE.md

@@ -4,7 +4,7 @@
 
 ## Files
 
-- **run-watchdog.sh** (1.5K): Interactive daemon supervisor; spawns backup-fleet.sh every 150s, maintains heartbeat guard (200s dedupe window), logs to FLEET-BACKUP.log. Traps INT/TERM cleanly.
+- **run-watchdog.sh** (1.7K): Interactive daemon supervisor; spawns backup-fleet.sh every 150s, maintains heartbeat guard (200s dedupe window), logs to FLEET-BACKUP.log. Calls tools/alert_bridge.py --scan after each cycle to post HIGH/CRITICAL alerts to Slack/Discord (opt-in). Traps INT/TERM cleanly.
 - **backup-fleet.sh** (5K): Core backup worker; discovers repos (~/.*, ~/*, ~/dev/*), stashes uncommitted work to backup/* branches, pushes unpushed commits, scans tracked files for secrets. Blocks push if secret-scan fails (marks BLOCKED state).
 
 ## Contracts
@@ -15,6 +15,8 @@
 - `$AESOP_ROOT/state/.watchdog-heartbeat` — epoch seconds; dedupe guard (200s window).
 - `$AESOP_ROOT/state/.watchdog-repos.json` — per-cycle snapshot: [{repo, state: CLEAN|PUSHED|SNAPSHOTTED|BLOCKED, age}].
 - `$AESOP_ROOT/state/FLEET-BACKUP.log` — append-only; cycle start/end, repo statuses, secret-scan blocks.
+- `$AESOP_ROOT/state/SECURITY-ALERTS.log` — append-only; security alerts (read by alert_bridge.py to post to webhooks).
+- `$AESOP_ROOT/state/.alert-bridge-cursor` — line number of last sent alert (ensures idempotent alert dispatch).
 
 **Exit behaviors**: run-watchdog exits 0 always (trap handles clean shutdown). backup-fleet exits 0 even on secret-scan block (marks repo BLOCKED, continues).
 
@@ -31,3 +33,4 @@
 4. **Secret-scan gate**: `scan_tracked_files()` calls `$AESOP_ROOT/tools/secret_scan.py` on staged/modified files; non-0 exit blocks push, marks repo BLOCKED.
 5. **Append-only logs**: FLEET-BACKUP.log only grows; rotate via tools/rotate_logs.py.
 6. **Path dedup via realpath**: Avoids processing symlinked repos or dot-dir aliases twice.
+7. **Alert Bridge integration** (NEW wave-14): After each backup-fleet.sh cycle, run-watchdog.sh calls `python $AESOP_ROOT/tools/alert_bridge.py --scan || true` to post HIGH/CRITICAL security alerts and heartbeat staleness to Slack/Discord. No-op if webhook_url null/absent in aesop.config.json (feature opt-in). Uses cursor file for idempotent dispatch (no re-sends). See tools/alert_bridge.py for details.

package/daemons/run-watchdog.sh

@@ -3,10 +3,11 @@
 # Backs up committed + uncommitted fleet work and scans for security issues every 150s.
 # Usage: run-watchdog.sh [--once]
 #
-# Configuration: export AESOP_ROOT=/path/to/aesop before running, or edit default below.
+# Configuration: export AESOP_ROOT=/path/to/aesop before running (defaults to script directory's parent).
 # Testing: export AESOP_WATCHDOG_CYCLE_CMD to override backup-fleet.sh invocation
 
-AESOP_ROOT="${AESOP_ROOT:-.}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+AESOP_ROOT="${AESOP_ROOT:-$(dirname "$SCRIPT_DIR")}"
 MODE="${1:-daemon}"
 LOCK_DIR="$AESOP_ROOT/state/.watchdog-lock"
 LOCK_STALE_THRESHOLD=300
@@ -96,6 +97,7 @@ if [ "$MODE" = "--once" ]; then
     echo "$err_msg" >> "$AESOP_ROOT/state/FLEET-BACKUP.log"
     echo "[ERROR: exit $cmd_exit]" >&2
   fi
+  python "$AESOP_ROOT/tools/alert_bridge.py" --scan || true
   release_lock "$LOCK_DIR"
   exit $cmd_exit
 fi
@@ -113,5 +115,6 @@ while true; do
     out=$(echo "$full_out" | tail -2)
     printf '%s  cycle #%d [ERROR: exit %d]\n%s\n' "$(date '+%H:%M:%S')" "$n" "$cmd_exit" "$out"
   fi
+  python "$AESOP_ROOT/tools/alert_bridge.py" --scan || true
   sleep 150
 done

package/docs/RELEASING.md

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

package/docs/archive/README.md

@@ -0,0 +1,3 @@
+# Archived Spike Investigations
+
+Spike investigations that were cancelled or superseded; kept for reference and historical context.

package/docs/{spikes → archive/spikes}/tiered-cognition/README.md

@@ -1,8 +1,6 @@
 # Tiered Cognition/Execution — spike + staged wave-12 artifact
 
-> **STATUS: STAGED, NOT ACTIVATED.** Nothing in this directory is wired into
-> `~/.claude/settings.json` or `~/.claude/hooks/`. The live model-policy hook
-> (`force-haiku-subagents.mjs`) is untouched and still governs the fleet.
+> **STATUS: CANCELLED 2026-07-14** after A/B testing measured 4.6x weighted cost for identical quality (see MEMORY.md wave-11 entry). Kept for reference; do not activate. Nothing in this directory is wired into `~/.claude/settings.json` or `~/.claude/hooks/`. The live model-policy hook (`force-haiku-subagents.mjs`) is untouched and still governs the fleet.
 
 ## Contents