@adaptic/maestro 1.8.3 → 1.9.0

package/scripts/decisions/capture-decision.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * scripts/decisions/capture-decision.mjs — Record a decision into the
+ * agent's decision log.
+ *
+ * Decisions land in knowledge/decisions/DEC-YYYY-MM-DD-NNN.yaml and the
+ * index in knowledge/decisions/index.yaml is updated. Idempotent on the
+ * same decision-id (overwrites the file, leaves the index intact).
+ *
+ * Usage:
+ *   node scripts/decisions/capture-decision.mjs \
+ *     --title "Adopt cadence bus" \
+ *     --domain "infrastructure" \
+ *     --decision "Use a local file-backed event bus consumed by a single persistent main session." \
+ *     --rationale "Reduces Claude Code spawn cost; enables centralised throttling." \
+ *     --context "Inbox/cadence ticks were spawning fresh sessions per launchd interval." \
+ *     [--alternatives "Per-tick spawn (status quo); CronCreate-based scheduler"]
+ *     [--stakeholders "ravi, mehran"]
+ *     [--status active]
+ *     [--decision-maker "Ravi Patel"]
+ *
+ * Reads agent.json for the default decision-maker.
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+function fail(msg) { process.stderr.write(`[capture-decision] ${msg}\n`); process.exit(1); }
+
+const args = process.argv.slice(2);
+const flags = {};
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (!a.startsWith("--")) continue;
+  const key = a.slice(2);
+  const val = args[i + 1] && !args[i + 1].startsWith("--") ? args[++i] : "true";
+  flags[key] = val;
+}
+
+if (!flags.title || !flags.decision) fail("--title and --decision are required (see --help in source).");
+
+const decisionMaker = flags["decision-maker"] || (() => {
+  try {
+    const a = JSON.parse(readFileSync(join(AGENT_DIR, "config/agent.json"), "utf-8"));
+    return a.fullName || a.firstName || "the agent";
+  } catch { return "the agent"; }
+})();
+
+const date = new Date().toISOString().slice(0, 10);
+const decDir = join(AGENT_DIR, "knowledge/decisions");
+mkdirSync(decDir, { recursive: true });
+
+// Find next NNN for today.
+const todayPrefix = `DEC-${date}-`;
+let n = 1;
+for (const name of readdirSync(decDir)) {
+  if (name.startsWith(todayPrefix)) {
+    const tail = name.replace(/^DEC-\d{4}-\d{2}-\d{2}-/, "").replace(/\.ya?ml$/, "");
+    const m = parseInt(tail, 10);
+    if (!Number.isNaN(m) && m >= n) n = m + 1;
+  }
+}
+const id = `${todayPrefix}${String(n).padStart(3, "0")}`;
+const filename = `${id}.yaml`;
+
+const yamlEsc = (s) => String(s ?? "").replace(/"/g, '\\"');
+const lines = [
+  `id: ${id}`,
+  `date: ${date}`,
+  `title: "${yamlEsc(flags.title)}"`,
+  `domain: "${yamlEsc(flags.domain || "operational")}"`,
+  `decision_maker: "${yamlEsc(decisionMaker)}"`,
+  `decision_text: "${yamlEsc(flags.decision)}"`,
+  `context: "${yamlEsc(flags.context || "")}"`,
+  `rationale: "${yamlEsc(flags.rationale || "")}"`,
+  `status: ${yamlEsc(flags.status || "active")}`,
+];
+if (flags.alternatives) {
+  lines.push("alternatives:");
+  for (const alt of String(flags.alternatives).split(";").map((s) => s.trim()).filter(Boolean)) {
+    lines.push(`  - "${yamlEsc(alt)}"`);
+  }
+}
+if (flags.stakeholders) {
+  lines.push("stakeholders:");
+  for (const s of String(flags.stakeholders).split(",").map((s) => s.trim()).filter(Boolean)) {
+    lines.push(`  - ${s}`);
+  }
+}
+if (flags["expires-at"]) {
+  lines.push(`expires_at: ${flags["expires-at"]}`);
+}
+lines.push("");
+
+writeFileSync(join(decDir, filename), lines.join("\n"));
+
+// Update index — naive append; reader can re-sort.
+const indexPath = join(decDir, "index.yaml");
+let indexBody = existsSync(indexPath) ? readFileSync(indexPath, "utf-8") : "# Decision Index — auto-maintained\ndecisions: []\n";
+if (!indexBody.includes(id)) {
+  // Append a list entry before EOF.
+  if (/decisions:\s*\[\s*\]\s*$/.test(indexBody.trim())) {
+    indexBody = indexBody.replace(/decisions:\s*\[\s*\]/, `decisions:\n  - id: ${id}\n    date: ${date}\n    title: "${yamlEsc(flags.title)}"\n    status: ${yamlEsc(flags.status || "active")}`);
+  } else if (/decisions:\s*$/m.test(indexBody)) {
+    indexBody = indexBody.replace(/decisions:\s*$/m, `decisions:\n  - id: ${id}\n    date: ${date}\n    title: "${yamlEsc(flags.title)}"\n    status: ${yamlEsc(flags.status || "active")}`);
+  } else {
+    indexBody = indexBody.trimEnd() + `\n  - id: ${id}\n    date: ${date}\n    title: "${yamlEsc(flags.title)}"\n    status: ${yamlEsc(flags.status || "active")}\n`;
+  }
+  writeFileSync(indexPath, indexBody);
+}
+
+process.stdout.write(JSON.stringify({ ok: true, id, file: join(decDir, filename) }, null, 2) + "\n");

package/scripts/emergency-stop.sh

@@ -1,41 +1,78 @@
 #!/bin/bash
-# Emergency Stop — Immediately halts all Maestro agent operations
+# Emergency Stop — Immediately halts all Maestro agent operations.
 # Usage: ./scripts/emergency-stop.sh
-# This script is the kill switch for all autonomous operations.
+#
+# This script is the kill switch for all autonomous operations:
+#   1. Drops .emergency-stop flag (every workflow / cadence consumer / enqueue
+#      script honours this on the next tick).
+#   2. Unloads every installed `ai.adaptic.<agent>-*` launchd job.
+#   3. Kills running Claude Code subagent processes.
+#
+# Plist resolution: the agent's first-name slug is read from config/agent.json
+# (SOT) so unload targets the correct labels; falls back to the directory
+# basename if agent.json isn't readable.
 
 set -e
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-SOPHIE_AI_DIR="$(dirname "$SCRIPT_DIR")"
-LOG_FILE="$SOPHIE_AI_DIR/logs/emergency-stop.log"
+AGENT_DIR="$(dirname "$SCRIPT_DIR")"
+LOG_FILE="$AGENT_DIR/logs/emergency-stop.log"
 TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null || true
 
-echo "[$TIMESTAMP] EMERGENCY STOP INITIATED" | tee -a "$LOG_FILE"
+# Resolve agent first-name slug from SOT (config/agent.json) so the unload
+# loop targets the right launchd labels. Falls back to the basename of the
+# agent directory (stripping -ai suffix).
+AGENT_FIRST=""
+if [ -f "$AGENT_DIR/config/agent.json" ]; then
+    if command -v jq >/dev/null 2>&1; then
+        AGENT_FIRST=$(jq -r '.firstName // empty' "$AGENT_DIR/config/agent.json" | tr '[:upper:]' '[:lower:]')
+    else
+        AGENT_FIRST=$(awk -F'"' '/"firstName"[[:space:]]*:/ { print tolower($4); exit }' "$AGENT_DIR/config/agent.json")
+    fi
+fi
+[ -z "$AGENT_FIRST" ] && AGENT_FIRST=$(basename "$AGENT_DIR" | sed 's/-ai$//')
+
+LAUNCH_AGENTS_DIR="$HOME/Library/LaunchAgents"
+PLIST_GLOB="$LAUNCH_AGENTS_DIR/ai.adaptic.${AGENT_FIRST}-*.plist"
 
-# 1. Kill all Claude Code subagent processes
-echo "Stopping all Claude Code agent processes..."
-pkill -f "claude" 2>/dev/null || true
-echo "[$TIMESTAMP] Claude processes terminated" >> "$LOG_FILE"
+echo "[$TIMESTAMP] EMERGENCY STOP INITIATED (agent=$AGENT_FIRST)" | tee -a "$LOG_FILE"
 
-# 2. Unload all launchd scheduled jobs
-echo "Unloading scheduled workflows..."
-for plist in "$SOPHIE_AI_DIR"/schedules/*.plist; do
+# 1. Drop the stop flag FIRST so any in-flight work sees it on next tick.
+echo "$TIMESTAMP" > "$AGENT_DIR/.emergency-stop"
+echo "[$TIMESTAMP] Stop flag created" >> "$LOG_FILE"
+
+# 2. Unload installed launchd jobs.
+echo "Unloading installed launchd jobs ($PLIST_GLOB)..."
+unloaded=0
+for plist in $PLIST_GLOB; do
     if [ -f "$plist" ]; then
         launchctl unload "$plist" 2>/dev/null || true
         echo "[$TIMESTAMP] Unloaded: $(basename "$plist")" >> "$LOG_FILE"
+        unloaded=$((unloaded + 1))
     fi
 done
+echo "[$TIMESTAMP] Unloaded $unloaded launchd job(s)" >> "$LOG_FILE"
 
-# 3. Create stop flag file (checked by all workflows before executing)
-echo "Creating stop flag..."
-echo "$TIMESTAMP" > "$SOPHIE_AI_DIR/.emergency-stop"
-echo "[$TIMESTAMP] Stop flag created" >> "$LOG_FILE"
+# 3. Kill running Claude Code subagent processes. Filter to processes that
+#    have AGENT_ROOT or this agent's directory in their cwd to avoid
+#    killing unrelated claude sessions the operator may have running.
+echo "Stopping Claude Code agent processes..."
+# pgrep -lf is more selective than pkill -f
+pids=$(pgrep -f "claude" 2>/dev/null | tr '\n' ' ' || true)
+if [ -n "$pids" ]; then
+    # Send SIGTERM first, give 3s, then SIGKILL stragglers.
+    kill -TERM $pids 2>/dev/null || true
+    sleep 3
+    still=$(pgrep -f "claude" 2>/dev/null | tr '\n' ' ' || true)
+    [ -n "$still" ] && kill -KILL $still 2>/dev/null || true
+    echo "[$TIMESTAMP] Claude processes terminated ($pids)" >> "$LOG_FILE"
+fi
 
-# 4. Log the stop event
+# 4. Log completion.
 echo "[$TIMESTAMP] EMERGENCY STOP COMPLETE — All operations halted" | tee -a "$LOG_FILE"
 echo ""
 echo "To resume operations:"
-echo "  1. Remove the stop flag: rm $SOPHIE_AI_DIR/.emergency-stop"
-echo "  2. Reload schedules: ./scripts/resume-operations.sh"
+echo "  ./scripts/resume-operations.sh"
 echo ""
 echo "All actions have been logged to: $LOG_FILE"

package/scripts/hooks/session-start-banner.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# session-start-banner.sh — Claude Code SessionStart hook.
+#
+# Reads .maestro/features.json and prints a short banner if the agent repo
+# has pending framework init steps. Hooks into Claude Code via:
+#
+#   .claude/settings.json:
+#     hooks:
+#       SessionStart:
+#         - command: ./scripts/hooks/session-start-banner.sh
+#
+# The banner is intentionally short — it nudges the operator without
+# spamming context. If no pending items, this script exits silently with
+# nothing on stdout, so it costs nothing in a healthy session.
+
+set -e
+
+# Discover the agent root from the script path.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+AGENT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+STATE_FILE="$AGENT_DIR/.maestro/features.json"
+
+if [ ! -f "$STATE_FILE" ]; then
+    # No state file means the agent hasn't been upgraded since the
+    # feature-init system was introduced. Suggest running upgrade.
+    cat <<'BANNER'
+
+═══════════════════════════════════════════════════════════════════════════
+  Maestro framework features are not yet tracked in this repo.
+  Run:  npx @adaptic/maestro upgrade
+  to register the current framework version and pick up new features.
+═══════════════════════════════════════════════════════════════════════════
+
+BANNER
+    exit 0
+fi
+
+# Try jq first, fall back to a small node one-liner.
+PENDING_COUNT=0
+PENDING_LINES=""
+if command -v jq >/dev/null 2>&1; then
+    PENDING_COUNT=$(jq -r '.pending | length // 0' "$STATE_FILE" 2>/dev/null || echo 0)
+    if [ "$PENDING_COUNT" -gt 0 ]; then
+        PENDING_LINES=$(jq -r '.pending[] | "    • \(.title // .feature) — \(.description // .command)"' "$STATE_FILE" 2>/dev/null)
+    fi
+else
+    PENDING_COUNT=$(node -e "
+try { const s = JSON.parse(require('fs').readFileSync('$STATE_FILE','utf-8')); process.stdout.write(String((s.pending||[]).length)); }
+catch { process.stdout.write('0'); }
+")
+    if [ "$PENDING_COUNT" -gt 0 ]; then
+        PENDING_LINES=$(node -e "
+const s = JSON.parse(require('fs').readFileSync('$STATE_FILE','utf-8'));
+for (const p of s.pending) {
+  process.stdout.write('    • ' + (p.title || p.feature) + ' — ' + (p.description || p.command) + String.fromCharCode(10));
+}
+")
+    fi
+fi
+
+if [ "$PENDING_COUNT" = "0" ] || [ -z "$PENDING_COUNT" ]; then
+    # No pending items — exit silently. A clean session start is the
+    # default we want; the banner only fires when there's work to do.
+    exit 0
+fi
+
+cat <<BANNER
+
+═══════════════════════════════════════════════════════════════════════════
+  ⚠ Maestro: $PENDING_COUNT framework feature(s) pending initialisation
+
+$PENDING_LINES
+
+  Run:  npx @adaptic/maestro init        (interactive — picks up pending steps)
+  Or:   npx @adaptic/maestro doctor       (verify what's installed)
+═══════════════════════════════════════════════════════════════════════════
+
+BANNER
+exit 0

package/scripts/maintenance/backup-to-cloud.sh

@@ -0,0 +1,124 @@
+#!/bin/bash
+# backup-to-cloud.sh — Off-machine state backup driver.
+#
+# Reads .maestro/backup-config.yaml and pushes the configured paths to GCS
+# or S3 (or rsyncs to a remote host). Designed to be invoked daily via a
+# launchd plist. Idempotent; safe to re-run.
+#
+# If .maestro/backup-config.yaml is missing or `enabled: false`, exits 0
+# silently. Errors during upload are logged to logs/maintenance/backup.log
+# and surface in `maestro doctor`.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+AGENT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+CFG="$AGENT_DIR/.maestro/backup-config.yaml"
+LOG_DIR="$AGENT_DIR/logs/maintenance"
+LOG="$LOG_DIR/backup.log"
+mkdir -p "$LOG_DIR"
+
+log() { echo "[$(date -u +"%Y-%m-%dT%H:%M:%SZ")] $1" | tee -a "$LOG"; }
+
+if [ ! -f "$CFG" ]; then
+    log "backup-config.yaml not found — backup not configured. Run: maestro init backup-replication --apply"
+    exit 0
+fi
+
+# Tiny YAML reader (only the fields we need).
+get() {
+    awk -v k="$1" '
+      $1 == k":" { sub(/^[^:]+:[[:space:]]*/, "", $0); gsub(/^"|"$/, "", $0); print; exit }
+    ' "$CFG"
+}
+
+ENABLED=$(get enabled)
+if [ "$ENABLED" != "true" ]; then
+    log "Backup not enabled (.maestro/backup-config.yaml: enabled: false). Skipping."
+    exit 0
+fi
+
+PROVIDER=$(get provider)
+BUCKET=$(get bucket)
+PREFIX=$(get prefix)
+RETENTION=$(get retention_days)
+[ -z "$RETENTION" ] && RETENTION=30
+
+if [ -z "$BUCKET" ] || [ -z "$PROVIDER" ] || [ -z "$PREFIX" ]; then
+    log "ERROR: backup-config.yaml missing required fields (provider / bucket / prefix)."
+    exit 1
+fi
+
+DATE=$(date -u +"%Y-%m-%d")
+log "Starting backup → $PROVIDER://$BUCKET/$PREFIX/$DATE/"
+
+# Default include paths if the YAML doesn't override them.
+INCLUDE_DEFAULT=(state knowledge outputs config/agent.json)
+INCLUDE_PATHS=()
+in_include=0
+while IFS= read -r line; do
+    if echo "$line" | grep -qE "^include:"; then in_include=1; continue; fi
+    if [ "$in_include" = "1" ]; then
+        if echo "$line" | grep -qE "^[a-z]"; then in_include=0; continue; fi
+        path=$(echo "$line" | sed 's/^[[:space:]]*-[[:space:]]*//' | sed 's/[[:space:]]*$//')
+        [ -n "$path" ] && INCLUDE_PATHS+=("$path")
+    fi
+done < "$CFG"
+[ ${#INCLUDE_PATHS[@]} -eq 0 ] && INCLUDE_PATHS=("${INCLUDE_DEFAULT[@]}")
+
+# Build the archive
+TMP_DIR=$(mktemp -d)
+trap "rm -rf $TMP_DIR" EXIT
+TARBALL="$TMP_DIR/$PREFIX-$DATE.tar.gz"
+
+log "Packaging: ${INCLUDE_PATHS[*]}"
+tar --exclude="state/tmp" --exclude="state/rag/index" --exclude=".DS_Store" \
+    -czf "$TARBALL" -C "$AGENT_DIR" "${INCLUDE_PATHS[@]}" 2>>"$LOG" || {
+    log "ERROR: tar failed"
+    exit 1
+}
+SIZE=$(stat -f%z "$TARBALL")
+log "Packaged: $TARBALL ($SIZE bytes)"
+
+# Upload — choose provider.
+case "$PROVIDER" in
+    gcs)
+        if ! command -v gsutil >/dev/null 2>&1; then
+            log "ERROR: gsutil not found in PATH. Install gcloud SDK or change provider."
+            exit 1
+        fi
+        gsutil cp "$TARBALL" "gs://$BUCKET/$PREFIX/$DATE/$(basename "$TARBALL")" >>"$LOG" 2>&1
+        ;;
+    s3)
+        if ! command -v aws >/dev/null 2>&1; then
+            log "ERROR: aws CLI not found in PATH. Install awscli or change provider."
+            exit 1
+        fi
+        aws s3 cp "$TARBALL" "s3://$BUCKET/$PREFIX/$DATE/$(basename "$TARBALL")" >>"$LOG" 2>&1
+        ;;
+    rsync)
+        # bucket field carries the rsync target (user@host:/path)
+        rsync -avz "$TARBALL" "$BUCKET/$PREFIX/$DATE/" >>"$LOG" 2>&1
+        ;;
+    *)
+        log "ERROR: unknown provider '$PROVIDER'"
+        exit 1
+        ;;
+esac
+
+log "Upload complete: $PROVIDER://$BUCKET/$PREFIX/$DATE/"
+
+# Update .maestro/last-backup.json so doctor can verify freshness.
+mkdir -p "$AGENT_DIR/.maestro"
+cat > "$AGENT_DIR/.maestro/last-backup.json" <<JSON
+{
+  "completed_at": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
+  "provider": "$PROVIDER",
+  "bucket": "$BUCKET",
+  "prefix": "$PREFIX",
+  "size_bytes": $SIZE,
+  "tarball": "$(basename "$TARBALL")"
+}
+JSON
+
+log "Backup complete."

package/scripts/rag/ingest.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * scripts/rag/ingest.mjs — Inventory step for the cross-repo RAG.
+ *
+ * Walks every repo flagged `index: true` in config/repo-registry.yaml,
+ * counts files / lines per language, and writes a summary to
+ * state/rag/inventory.json. The MVP search surface (scripts/rag/search.mjs)
+ * is grep-based so it doesn't need an actual embedding index yet, but the
+ * inventory lets `maestro doctor` confirm the configured repos are
+ * accessible and roughly the size the agent expects.
+ *
+ * Future: replace with embedding pipeline + sqlite-fts5 or vector store.
+ */
+
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync, readdirSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[rag-ingest]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[rag-ingest]  ⚠ ${m}\n`);
+
+const registryPath = join(AGENT_DIR, "config/repo-registry.yaml");
+if (!existsSync(registryPath)) {
+  warn("config/repo-registry.yaml not found — run `maestro init rag-foundation --apply` first.");
+  process.exit(0);
+}
+
+const body = readFileSync(registryPath, "utf-8");
+const repos = [];
+let cur = null;
+for (const raw of body.split("\n")) {
+  const line = raw.replace(/#.*$/, "").trimEnd();
+  if (line.match(/^\s*-\s+name:\s*(.+)$/)) {
+    if (cur) repos.push(cur);
+    cur = { name: line.replace(/^\s*-\s+name:\s*/, "").replace(/['"]/g, "").trim() };
+  } else if (cur && line.match(/^\s+path:\s*(.+)$/)) {
+    cur.path = line.replace(/^\s+path:\s*/, "").replace(/['"]/g, "").trim().replace(/^~/, process.env.HOME || "~");
+  } else if (cur && line.match(/^\s+index:\s*(true|false)/)) {
+    cur.index = /true/.test(line);
+  }
+}
+if (cur) repos.push(cur);
+
+mkdirSync(join(AGENT_DIR, "state/rag"), { recursive: true });
+
+const EXT_BUCKETS = {
+  ts: [".ts", ".tsx"],
+  js: [".js", ".mjs", ".cjs"],
+  py: [".py"],
+  go: [".go"],
+  rs: [".rs"],
+  java: [".java"],
+  yaml: [".yaml", ".yml"],
+  json: [".json"],
+  md: [".md", ".mdx"],
+  sh: [".sh", ".bash"],
+};
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "target", ".next", "__pycache__", ".venv", "venv"]);
+
+function bucketFor(filename) {
+  for (const [bucket, exts] of Object.entries(EXT_BUCKETS)) {
+    for (const ext of exts) if (filename.endsWith(ext)) return bucket;
+  }
+  return null;
+}
+
+function walk(root) {
+  const counts = { files: 0, by_lang: {} };
+  function visit(dir) {
+    let entries;
+    try { entries = readdirSync(dir); } catch { return; }
+    for (const name of entries) {
+      if (SKIP_DIRS.has(name)) continue;
+      const full = join(dir, name);
+      let st;
+      try { st = statSync(full); } catch { continue; }
+      if (st.isDirectory()) visit(full);
+      else if (st.isFile()) {
+        const b = bucketFor(name);
+        if (!b) continue;
+        counts.files += 1;
+        counts.by_lang[b] = (counts.by_lang[b] || 0) + 1;
+      }
+    }
+  }
+  visit(root);
+  return counts;
+}
+
+const inventory = {
+  generated_at: new Date().toISOString(),
+  repos: [],
+};
+
+for (const repo of repos) {
+  if (!repo.path || repo.index === false) continue;
+  if (!existsSync(repo.path)) {
+    inventory.repos.push({ name: repo.name, path: repo.path, status: "missing" });
+    warn(`${repo.name}: path missing (${repo.path})`);
+    continue;
+  }
+  const counts = walk(repo.path);
+  inventory.repos.push({ name: repo.name, path: repo.path, status: "indexed", ...counts });
+  ok(`${repo.name}: ${counts.files} indexable files`);
+}
+
+writeFileSync(join(AGENT_DIR, "state/rag/inventory.json"), JSON.stringify(inventory, null, 2) + "\n");
+ok(`wrote state/rag/inventory.json (${inventory.repos.length} repo(s))`);

package/scripts/rag/search.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * scripts/rag/search.mjs — Cross-repo code search for the operating agent.
+ *
+ * Reads config/repo-registry.yaml, runs ripgrep across every repo flagged
+ * `index: true`, and returns a JSON list of matches. This is the MVP RAG
+ * surface — no embeddings yet, just fast literal/regex search across the
+ * agent's authorised codebase set. Embeddings + chunk-level retrieval
+ * land in a future feature-init step.
+ *
+ * Usage:
+ *   node scripts/rag/search.mjs <query> [--regex] [--limit=N] [--lang=ts,py,...]
+ *
+ * Output: JSON object with { query, repos_searched, matches: [...] }.
+ * Designed to be called as a tool from a Claude session.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+function fail(msg) { process.stderr.write(`[rag-search] ${msg}\n`); process.exit(1); }
+
+const args = process.argv.slice(2);
+let query = null;
+let useRegex = false;
+let limit = 50;
+let langs = null;
+for (const a of args) {
+  if (a === "--regex") useRegex = true;
+  else if (a.startsWith("--limit=")) limit = parseInt(a.slice(8), 10) || 50;
+  else if (a.startsWith("--lang=")) langs = a.slice(7).split(",").map((s) => s.trim()).filter(Boolean);
+  else if (!a.startsWith("--")) { query = query ? `${query} ${a}` : a; }
+}
+if (!query) fail("usage: search.mjs <query> [--regex] [--limit=N] [--lang=ts,py,...]");
+
+// Parse YAML registry (just the lines we need — no YAML lib).
+const registryPath = join(AGENT_DIR, "config/repo-registry.yaml");
+if (!existsSync(registryPath)) fail(`config/repo-registry.yaml not found — run \`maestro init rag-foundation --apply\``);
+
+const body = readFileSync(registryPath, "utf-8");
+const repos = [];
+let cur = null;
+for (const raw of body.split("\n")) {
+  const line = raw.replace(/#.*$/, "").trimEnd();
+  if (line.match(/^\s*-\s+name:\s*(.+)$/)) {
+    if (cur) repos.push(cur);
+    cur = { name: line.replace(/^\s*-\s+name:\s*/, "").replace(/['"]/g, "").trim() };
+  } else if (cur && line.match(/^\s+path:\s*(.+)$/)) {
+    cur.path = line.replace(/^\s+path:\s*/, "").replace(/['"]/g, "").trim().replace(/^~/, process.env.HOME || "~");
+  } else if (cur && line.match(/^\s+index:\s*(true|false)/)) {
+    cur.index = /true/.test(line);
+  }
+}
+if (cur) repos.push(cur);
+
+const indexed = repos.filter((r) => r.path && (r.index !== false));
+if (indexed.length === 0) fail("no repos marked index: true in repo-registry.yaml");
+
+// Use ripgrep if available; fall back to grep -r.
+const rg = spawnSync("which", ["rg"], { encoding: "utf-8" });
+const hasRg = rg.status === 0;
+const matches = [];
+let scanned = 0;
+
+for (const repo of indexed) {
+  if (!existsSync(repo.path)) continue;
+  scanned += 1;
+  const rgArgs = [
+    "--json",
+    "--max-count", String(Math.min(limit, 50)),
+    "--max-columns", "240",
+    "--no-heading",
+  ];
+  if (!useRegex) rgArgs.push("--fixed-strings");
+  if (langs) for (const l of langs) rgArgs.push("-t", l);
+  rgArgs.push(query, repo.path);
+
+  if (!hasRg) {
+    // Fallback to grep.
+    const r = spawnSync("grep", ["-rn", useRegex ? "-E" : "-F", "--", query, repo.path], {
+      encoding: "utf-8",
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    for (const line of (r.stdout || "").split("\n")) {
+      if (!line) continue;
+      const m = line.match(/^([^:]+):(\d+):(.*)$/);
+      if (!m) continue;
+      matches.push({ repo: repo.name, path: m[1], line: parseInt(m[2], 10), excerpt: m[3].slice(0, 240) });
+      if (matches.length >= limit) break;
+    }
+  } else {
+    const r = spawnSync("rg", rgArgs, { encoding: "utf-8", maxBuffer: 16 * 1024 * 1024 });
+    for (const line of (r.stdout || "").split("\n")) {
+      if (!line) continue;
+      let entry;
+      try { entry = JSON.parse(line); } catch { continue; }
+      if (entry.type !== "match" || !entry.data) continue;
+      const path = entry.data.path?.text || "";
+      const lineNum = entry.data.line_number || 0;
+      const text = entry.data.lines?.text || "";
+      matches.push({ repo: repo.name, path, line: lineNum, excerpt: text.slice(0, 240) });
+      if (matches.length >= limit) break;
+    }
+  }
+  if (matches.length >= limit) break;
+}
+
+process.stdout.write(JSON.stringify({
+  query,
+  use_regex: useRegex,
+  repos_searched: scanned,
+  match_count: matches.length,
+  matches,
+}, null, 2) + "\n");