@matt82198/aesop 0.1.0-beta.1

package/daemons/backup-fleet.sh

@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+set -uo pipefail
+# Backup fleet repos: stash uncommitted work, push unpushed commits to backup branches.
+# Runs every 150s from run-watchdog.sh. Abort on secret-scan failures.
+# Improvements: dot-directory discovery, path dedup, tracked-files-only secret scanning.
+
+AESOP_ROOT="${AESOP_ROOT:-.}"
+HEARTBEAT="$AESOP_ROOT/state/.watchdog-heartbeat"
+LOG="$AESOP_ROOT/state/FLEET-BACKUP.log"
+REPOS_STATUS="$AESOP_ROOT/state/.watchdog-repos.json"
+
+date +%s > "$HEARTBEAT" 2>/dev/null
+ts() { date '+%Y-%m-%d %H:%M:%S'; }
+log() { echo "[$(ts)] $*" | tee -a "$LOG"; }
+
+is_touched() {
+  local repo="$1"
+  [ ! -d "$repo/.git" ] && return 1
+  (
+    cd "$repo" || return 1
+    [ -n "$(git status --porcelain 2>/dev/null)" ] && return 0
+    [ -n "$(git log @{u}.. --oneline 2>/dev/null)" ] && return 0
+    return 1
+  )
+}
+
+get_tracked_modifications() {
+  local repo="$1"
+  (
+    cd "$repo" || return 1
+    git diff --name-only HEAD 2>/dev/null
+    git ls-files -m 2>/dev/null
+  ) | sort -u
+}
+
+scan_tracked_files() {
+  local repo="$1"
+  local tracked_files
+  local file_paths=""
+  tracked_files=$(get_tracked_modifications "$repo")
+
+  if [ -z "$tracked_files" ]; then
+    return 0
+  fi
+
+  while IFS= read -r file; do
+    if [ -n "$file" ] && [ -f "$repo/$file" ]; then
+      file_paths="$file_paths $repo/$file"
+    fi
+  done <<EOF
+$tracked_files
+EOF
+
+  if [ -z "$file_paths" ]; then
+    return 0
+  fi
+
+  if [ -f "$AESOP_ROOT/tools/secret_scan.py" ]; then
+    python "$AESOP_ROOT/tools/secret_scan.py" $file_paths >/dev/null 2>&1
+  fi
+}
+
+get_default_branch() {
+  local repo="$1"
+  (cd "$repo" && git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's/refs\/remotes\/origin\///' || echo "master")
+}
+
+process_repo() {
+  local repo="$1"
+  local name=$(basename "$repo")
+  local default=$(get_default_branch "$repo")
+
+  (
+    cd "$repo" || exit 0
+    git fetch -q origin 2>/dev/null
+    local uncommitted=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+
+    if [ "$uncommitted" -gt 0 ]; then
+      TMPIDX=$(mktemp)
+      GIT_INDEX_FILE="$TMPIDX" git read-tree HEAD 2>/dev/null
+      GIT_INDEX_FILE="$TMPIDX" git add -A 2>/dev/null
+      TREE=$(GIT_INDEX_FILE="$TMPIDX" git write-tree 2>/dev/null)
+      rm -f "$TMPIDX"
+      LOCAL=$(git rev-parse HEAD 2>/dev/null)
+      HEADTREE=$(git rev-parse 'HEAD^{tree}' 2>/dev/null)
+      if [ -n "$TREE" ] && [ "$TREE" != "$HEADTREE" ]; then
+        COMMIT=$(git commit-tree "$TREE" -p "$LOCAL" -m "wip $(ts) — $uncommitted files" 2>/dev/null)
+        WIPREF="backup/wip-$(date +%Y%m%d)"
+        if scan_tracked_files "$repo"; then
+          if git push -qf origin "$COMMIT:refs/heads/$WIPREF" 2>/dev/null; then
+            printf 'SNAPSHOTTED|%s\n' "$name"
+            exit 0
+          fi
+        else
+          printf 'BLOCKED|%s\n' "$name"
+          exit 0
+        fi
+      fi
+    fi
+
+    local unpushed=$(git log @{u}.. --oneline 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$unpushed" -gt 0 ]; then
+      local branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+      [ "$branch" = "HEAD" ] && branch="$default"
+
+      if [ "$branch" = "$default" ]; then
+        WIPREF="backup/master-wip-$(date +%Y%m%d)"
+        if scan_tracked_files "$repo"; then
+          if git push -qf origin "HEAD:refs/heads/$WIPREF" 2>/dev/null; then
+            printf 'SNAPSHOTTED|%s\n' "$name"
+            exit 0
+          fi
+        else
+          printf 'BLOCKED|%s\n' "$name"
+          exit 0
+        fi
+      else
+        if scan_tracked_files "$repo"; then
+          if git push -q origin "$branch" 2>/dev/null; then
+            printf 'PUSHED|%s\n' "$name"
+            exit 0
+          fi
+        else
+          printf 'BLOCKED|%s\n' "$name"
+          exit 0
+        fi
+      fi
+    fi
+
+    printf 'CLEAN|%s\n' "$name"
+  )
+}
+
+log "=== cycle start ==="
+temp_json=$(mktemp)
+echo "[" > "$temp_json"
+first=1
+processed_paths=""
+
+# Discover all git repos: scan home dot-directories, root directories, dev/ subdirectory
+# This pattern includes ~/.* (dot-dirs like .claude), ~/* (home root), ~/dev/* (dev subtree)
+for dir in ~/.* ~/* ~/dev/*; do
+  base=$(basename "$dir")
+  [ "$base" = "." ] || [ "$base" = ".." ] && continue
+  [ ! -d "$dir/.git" ] && continue
+
+  # Normalize path to detect duplicates (e.g., .claude vs .claude/)
+  real_dir=$(cd "$dir" && pwd 2>/dev/null)
+  if [ -z "$real_dir" ]; then continue; fi
+  if echo "$processed_paths" | grep -Fq "$real_dir"; then
+    continue
+  fi
+  processed_paths="$processed_paths
+$real_dir"
+
+  if is_touched "$dir"; then
+    result=$(process_repo "$dir")
+    IFS="|" read -r state name <<< "$result"
+    [ -z "$state" ] && continue
+    if [ "$first" = 1 ]; then
+      first=0
+    else
+      echo "," >> "$temp_json"
+    fi
+    printf '{"repo":"%s","state":"%s","age":"%s"}' "$name" "$state" "$(date -Iseconds)" >> "$temp_json"
+    log "$state: $name"
+  fi
+done
+
+echo "" >> "$temp_json"
+echo "]" >> "$temp_json"
+mv "$temp_json" "$REPOS_STATUS"
+log "=== cycle end ==="

package/daemons/run-watchdog.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Durable fleet watchdog daemon (runs in a shell window). Ctrl-C to stop.
+# 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.
+
+AESOP_ROOT="${AESOP_ROOT:-.}"
+MODE="${1:-daemon}"
+
+# Heartbeat guard: skip if already running (within 200s)
+__hb=$(cat "$AESOP_ROOT/state/.watchdog-heartbeat" 2>/dev/null)
+__now=$(date +%s)
+if [ "$MODE" != "--once" ] && [ -n "$__hb" ] && [ $((__now - __hb)) -lt 200 ] 2>/dev/null; then
+  echo "watchdog already running (heartbeat $((__now - __hb))s ago) — not starting a duplicate."
+  exit 0
+fi
+
+echo "==================================================================="
+echo "  FLEET WATCHDOG DAEMON  ·  backup + ensure-push + scan / 150s"
+echo "  logs: $AESOP_ROOT/state/FLEET-BACKUP.log   ·   Ctrl-C to stop"
+echo "==================================================================="
+echo "[$(date '+%F %T')] === watchdog daemon (shell) STARTED ===" >> "$AESOP_ROOT/state/FLEET-BACKUP.log"
+trap 'echo "[$(date "+%F %T")] === watchdog daemon (shell) STOPPED ===" >> "$AESOP_ROOT/state/FLEET-BACKUP.log"; echo "stopped."; exit 0' INT TERM
+
+if [ "$MODE" = "--once" ]; then
+  bash "$AESOP_ROOT/daemons/backup-fleet.sh" 2>&1
+  exit 0
+fi
+
+n=0
+while true; do
+  n=$((n+1))
+  out=$(bash "$AESOP_ROOT/daemons/backup-fleet.sh" 2>&1 | tail -2)
+  printf '%s  cycle #%d\n%s\n' "$(date '+%H:%M:%S')" "$n" "$out"
+  sleep 150
+done

package/dash/dash-extra.mjs

@@ -0,0 +1,184 @@
+// Detect and render running Claude agents from transcripts.
+// Usage: node dash-extra.mjs [--json]
+//   --json: output JSON array of agents (for web dashboard /data endpoint)
+//   (default): render TUI text output (for terminal dashboard)
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Configuration from environment
+const AESOP_ROOT = process.env.AESOP_ROOT || path.join(process.env.HOME || '.', 'aesop');
+const TRANSCRIPTS_ROOT = path.resolve(
+  process.env.AESOP_TRANSCRIPTS_ROOT || path.join(process.env.HOME || '.', '.claude', 'projects')
+);
+const SCAN_DIR = path.join(AESOP_ROOT, 'scan');
+const ALERTS_LOG = path.join(SCAN_DIR, 'SECURITY-ALERTS.log');
+
+// ANSI colors for TUI output
+const c = {
+  R: '\x1b[31m',
+  G: '\x1b[32m',
+  Y: '\x1b[33m',
+  M: '\x1b[35m',
+  C: '\x1b[36m',
+  B: '\x1b[1m',
+  D: '\x1b[2m',
+  X: '\x1b[0m'
+};
+
+const now = Date.now();
+const out = [];
+
+// Read alerts log if present
+let slog = [];
+try {
+  if (fs.existsSync(ALERTS_LOG)) {
+    slog = fs.readFileSync(ALERTS_LOG, 'utf8').split('\n');
+  }
+} catch {}
+
+// Recursively walk directory tree to find agent-*.jsonl files
+function walk(dir, accumulator) {
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath, accumulator);
+      } else if (/^agent-.*\.jsonl$/.test(entry.name)) {
+        accumulator.push(fullPath);
+      }
+    }
+  } catch {}
+}
+
+// Find all agent transcript files
+let files = [];
+if (fs.existsSync(TRANSCRIPTS_ROOT)) {
+  walk(TRANSCRIPTS_ROOT, files);
+}
+
+// Filter: active agents in last 12 minutes, sorted by recency
+files = files
+  .map(f => {
+    let mtime = 0;
+    try {
+      mtime = fs.statSync(f).mtimeMs;
+    } catch {}
+    return { f, mtime };
+  })
+  .filter(x => now - x.mtime < 12 * 60 * 1000)
+  .sort((a, b) => b.mtime - a.mtime)
+  .slice(0, 8);
+
+// Extract description/hint from first ~60KB of agent transcript
+function label(filePath) {
+  try {
+    const fd = fs.openSync(filePath, 'r');
+    const buf = Buffer.alloc(60000);
+    const n = fs.readSync(fd, buf, 0, 60000, 0);
+    fs.closeSync(fd);
+    const content = buf.toString('utf8', 0, n);
+
+    // Try to find description or subagent_type in JSON
+    let match = content.match(/"description":"([^"]{2,60})"/);
+    if (!match) {
+      match = content.match(/"subagent_type":"([^"]{2,40})"/);
+    }
+    return match ? match[1] : '';
+  } catch {}
+  return '';
+}
+
+// TUI output: render heading
+out.push(`${c.B}  FLEET AGENTS${c.X} ${c.D}(green=running · severity-colored if flagged)${c.X}`);
+
+if (files.length === 0) {
+  out.push(`    ${c.D}(no active fleet agents in last 12 min)${c.X}`);
+}
+
+let runningCount = 0;
+
+// Render each agent
+for (const { f, mtime } of files) {
+  const basename = path.basename(f);
+  const ageSeconds = Math.round((now - mtime) / 1000);
+
+  // Check if agent is referenced in alerts log
+  const alertsForAgent = slog.filter(line => line.includes(basename));
+
+  let statusColor = ageSeconds < 120 ? c.G : c.D;
+  let statusText = ageSeconds < 120 ? 'running' : 'idle';
+
+  if (ageSeconds < 120) runningCount++;
+
+  // Recolor based on alert severity
+  if (alertsForAgent.some(l => l.includes('SUSPICIOUS'))) {
+    statusColor = c.R;
+    statusText = 'SUSPICIOUS';
+  } else if (alertsForAgent.some(l => / HIGH /.test(l))) {
+    statusColor = c.R;
+    statusText = 'HIGH';
+  } else if (alertsForAgent.some(l => / DRIFT /.test(l))) {
+    statusColor = c.M;
+    statusText = 'DRIFT';
+  } else if (alertsForAgent.some(l => / MED /.test(l))) {
+    statusColor = c.Y;
+    statusText = 'MED';
+  }
+
+  // Extract agent ID from filename (agent-<id>.jsonl)
+  const agentId = basename
+    .replace(/^agent-/, '')
+    .replace(/\.jsonl$/, '')
+    .slice(0, 13);
+
+  const hint = label(f).slice(0, 38);
+
+  out.push(
+    `    ${statusColor}●${c.X} ${agentId.padEnd(14)} ${c.D}${String(ageSeconds).padStart(4)}s${c.X}  ${statusColor}${statusText.padEnd(11)}${c.X}${c.D}${hint}${c.X}`
+  );
+}
+
+if (files.length > 0) {
+  out.push(`    ${c.D}${runningCount} running, ${files.length - runningCount} idle (last 12 min)${c.X}`);
+}
+
+// Output
+if (process.argv.includes('--json')) {
+  // JSON mode: emit agents array for web dashboard
+  const agents = [];
+  for (const { f, mtime } of files) {
+    const basename = path.basename(f);
+    const ageSeconds = Math.round((now - mtime) / 1000);
+    const alertsForAgent = slog.filter(line => line.includes(basename));
+
+    let status = ageSeconds < 120 ? 'running' : 'idle';
+
+    if (alertsForAgent.some(l => l.includes('SUSPICIOUS'))) {
+      status = 'SUSPICIOUS';
+    } else if (alertsForAgent.some(l => / HIGH /.test(l))) {
+      status = 'HIGH';
+    } else if (alertsForAgent.some(l => / DRIFT /.test(l))) {
+      status = 'DRIFT';
+    } else if (alertsForAgent.some(l => / MED /.test(l))) {
+      status = 'MED';
+    }
+
+    const agentId = basename
+      .replace(/^agent-/, '')
+      .replace(/\.jsonl$/, '')
+      .slice(0, 13);
+
+    agents.push({
+      id: agentId,
+      age_s: ageSeconds,
+      status: status,
+      hint: label(f).slice(0, 60)
+    });
+  }
+  process.stdout.write(JSON.stringify(agents) + '\n');
+} else {
+  // TUI mode: emit colored text
+  process.stdout.write(out.join('\n') + '\n');
+}

package/dash/watchdog-gui.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# Fleet watchdog TUI dashboard. Double-buffered no-flicker render. 4s refresh. CRLF-safe (no line continuations).
+# Launch in its own window: bash aesop/dash/watchdog-gui.sh
+# Set AESOP_ROOT=/path/to/aesop and TRACKED_REPOS before running.
+
+AESOP_ROOT="${AESOP_ROOT:-.}"
+
+# Color codes (ANSI)
+R=$'\e[31m'
+G=$'\e[32m'
+Y=$'\e[33m'
+M=$'\e[35m'
+C=$'\e[36m'
+B=$'\e[1m'
+D=$'\e[2m'
+X=$'\e[0m'
+
+# State files
+BLOG="$AESOP_ROOT/state/FLEET-BACKUP.log"
+SLOG="$AESOP_ROOT/state/SECURITY-ALERTS.log"
+HB="$AESOP_ROOT/state/.watchdog-heartbeat"
+REPOS_FILE="$AESOP_ROOT/state/.watchdog-repos.json"
+HB_DIR="$AESOP_ROOT/state/.heartbeats"
+
+SPINNER=0
+FIRST_FRAME=1
+
+# Trap Ctrl-C to restore cursor and exit cleanly
+trap 'printf "\033[?25h"; exit 0' INT TERM
+printf '\033[?25l'
+
+get_hb_threshold() {
+  local name="$1"
+  case "$name" in
+    *monitor*) echo 3600;;
+    *watchdog*) echo 300;;
+    *) echo 300;;
+  esac
+}
+
+render_frame() {
+  local FRAME=""
+  FRAME="${FRAME}${B}${C}== FLEET WATCHDOG${X}\n"
+  FRAME="${FRAME}  ${SPIN_CHAR} $(date '+%a %H:%M:%S')  Daemon: $WD  ${R}HIGH:$HI${X} ${Y}MED:$ME${X}${X}\n"
+  FRAME="${FRAME}\n"
+  FRAME="${FRAME}${B}  REPOS BACKED UP${X}\n"
+  if [ -f "$REPOS_FILE" ]; then
+    repos_data=$(cat "$REPOS_FILE" 2>/dev/null)
+    if [ "$repos_data" != "[]" ] 2>/dev/null; then
+      REPOS_LINES=$(echo "$repos_data" | jq -r '.[] | "    \(.repo) \(.state) \(.age)"' 2>/dev/null)
+      if [ -n "$REPOS_LINES" ]; then
+        FRAME="${FRAME}${REPOS_LINES}\n"
+      else
+        FRAME="${FRAME}    ${D}(repos unavailable)${X}\n"
+      fi
+    else
+      FRAME="${FRAME}    ${D}(no touched repos yet)${X}\n"
+    fi
+  else
+    FRAME="${FRAME}    ${D}(no status)${X}\n"
+  fi
+  FRAME="${FRAME}\n"
+  FRAME="${FRAME}${B}  HEARTBEATS${X}\n"
+  HB_FOUND=0
+  if [ -d "$HB_DIR" ] && [ -n "$(ls -A "$HB_DIR" 2>/dev/null)" ]; then
+    for hb_file in "$HB_DIR"/*; do
+      if [ -f "$hb_file" ]; then
+        name=$(basename "$hb_file")
+        epoch=$(head -1 "$hb_file" 2>/dev/null | grep -o '^[0-9]*')
+        if [ -n "$epoch" ] && [ "$epoch" -gt 0 ]; then
+          HB_FOUND=1
+          age=$(( now - epoch ))
+          threshold=$(get_hb_threshold "$name")
+          if [ "$age" -lt "$threshold" ]; then
+            status="${G}ALIVE${X} ${D}age:${age}s${X}"
+          else
+            status="${R}STALE${X} ${D}age:${age}s${X}"
+          fi
+          FRAME="${FRAME}    $name  $status\n"
+        fi
+      fi
+    done
+  fi
+  if [ "$HB_FOUND" -eq 0 ]; then
+    FRAME="${FRAME}    ${D}(none)${X}\n"
+  fi
+  FRAME="${FRAME}\n"
+  FRAME="${FRAME}${B}  RECENT EVENTS${X}\n"
+  if [ -s "$BLOG" ]; then
+    BACKUP_LINES=$(tail -3 "$BLOG" 2>/dev/null | sed 's/^/    /')
+    FRAME="${FRAME}${BACKUP_LINES}\n"
+  else
+    FRAME="${FRAME}    ${D}(none)${X}\n"
+  fi
+  FRAME="${FRAME}\n"
+  FRAME="${FRAME}${D}  Ctrl-C to exit  ·  4s refresh${X}\n"
+  echo -ne "$FRAME"
+}
+
+while true; do
+  SPINNER_CHARS='⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏'
+  SPINNER_IDX=$(( SPINNER % 10 ))
+  SPIN_CHAR="${SPINNER_CHARS:$SPINNER_IDX:1}"
+  ((SPINNER++))
+
+  now=$(date +%s)
+  hb=$(cat "$HB" 2>/dev/null)
+  case "$hb" in
+    ''|*[!0-9]*) hb=0 ;;
+  esac
+
+  if [ "$hb" -gt 0 ]; then
+    AGE=$(( now - hb ))
+  else
+    AGE=99999
+  fi
+
+  WD_THRESH=$(get_hb_threshold "watchdog")
+  if [ "$AGE" -lt "$WD_THRESH" ]; then
+    WD="${G}ALIVE${X} ${D}(${AGE}s)${X}"
+  else
+    WD="${R}STALE${X}"
+  fi
+
+  HI=$(grep -v '^RESOLVED-FP' "$SLOG" 2>/dev/null | grep -c ' HIGH '); HI=${HI:-0}
+  ME=$(grep -v '^RESOLVED-FP' "$SLOG" 2>/dev/null | grep -c ' MED '); ME=${ME:-0}
+
+  if [ "$FIRST_FRAME" -eq 1 ]; then
+    printf '\033[2J'
+    FIRST_FRAME=0
+  else
+    printf '\033[H'
+  fi
+
+  render_frame | while IFS= read -r line; do
+    printf '%b\033[K\n' "$line"
+  done
+  printf '\033[J'
+
+  sleep 4
+done

package/docs/CARDINAL-RULES.md

@@ -0,0 +1,146 @@
+# Cardinal Rules for Aesop Orchestration
+
+These are the foundational principles that guide all work in an Aesop-driven fleet. Violating these risks cost explosion, data loss, or orchestration breakdown.
+
+## 1. Dispatch model & cost
+
+**Rule**: Subagents are ALWAYS Haiku (1/3 Sonnet cost). Orchestrator (Opus) runs on main thread only.
+
+**Why**: Haiku at scale (6–8 agents in parallel) costs ~25% of all-Opus fleet while maintaining quality on tiny scoped tasks. Opus reserved for final validation, handoff, and orchestration.
+
+**Implementation**:
+- When spawning a new agent, default to Haiku.
+- If you need Opus-tier reasoning, consider decomposing into smaller Haiku tasks first.
+- Track token spend per subagent; alert if spend deviates >20% from baseline.
+
+## 2. TDD-first & parallel domains
+
+**Rule**: Test-driven development: failing tests before implementation. Decompose work into tiny scoped domains; one Haiku subagent per domain in parallel.
+
+**Why**: Small domains enable parallelism (cheaper, faster). TDD catches bugs early. Tests are living documentation.
+
+**Implementation**:
+- Write acceptance criteria first (in your story/ticket).
+- Red: verify tests fail.
+- Green: implement the minimum to pass tests.
+- Refactor: simplify, improve, extend reusable libraries.
+- When a task grows beyond one domain, split it and fan out to parallel Haiku agents.
+
+## 3. Reliability core: inputs always produce outputs
+
+**Rule**: Every input (request, event, cycle) must produce an output (brief/log/heartbeat/FAILED). Never wait silently; dispatch next work and offer ideas while waiting.
+
+**Why**: Hangs hide cost waste, data loss, and orchestration confusion. Observable failure is better than silent lag.
+
+**Implementation**:
+- Daemons emit heartbeats every cycle (even on error).
+- Logs are append-only; every action logged with timestamp.
+- If a subagent stalls >200s, watchdog respawns it.
+- Orchestrator briefs the user with findings while delegating to subagents (never idle).
+
+## 4. Orchestrator isolation: lean context
+
+**Rule**: Orchestrator reads ONLY: cardinal rules, STATE.md, BUILDLOG.md, MEMORY.md, and short git one-liners. Dispatch Haiku for research.
+
+**Why**: Large orchestrator context = token waste, slower decisions. Brief facts + git log tell the story.
+
+**Implementation**:
+- Orchestrator prompt stays <2000 tokens.
+- Long-form analysis → delegated to Haiku researcher agents.
+- Durable checkpoints (STATE.md, BUILDLOG.md) replace ephemeral context.
+- Prompt caching on cardinal rules + memory improves throughput.
+
+## 5. Durable handoff: STATE.md + BUILDLOG.md
+
+**Rule**: STATE.md tracks intent/decisions/phase/NEXT STEPS. BUILDLOG.md is append-only snapshots of agent work. On resume, re-sync from disk before acting.
+
+**Why**: Sessions end abruptly (wipes, crashes, restarts). Git-committed state survives. Re-syncing prevents duplicate work and data loss.
+
+**Implementation**:
+- Before acting, orchestrator reads STATE.md (5 min old max) and BUILDLOG.md (latest 10 entries).
+- After each major step, orchestrator updates STATE.md with new phase + next steps.
+- Subagents append work summaries to BUILDLOG.md (one line per completion).
+- Heartbeats mark liveness; stale heartbeats trigger re-sync.
+
+## 6. Branch discipline & continuous push
+
+**Rule**: Feature branches only (never main/master). Continuously push green work to origin. Never amend; create new commits.
+
+**Why**: Main branch stays deployable. Continuous push distributes backup risk. Amending hides history.
+
+**Implementation**:
+- Create feature/your-task at start.
+- Commit often (every 15–30 min of solid work).
+- Push after every commit (github mirrors your work).
+- Open PR when feature is ready for review.
+- Never force-push (unless explicitly approved for specific commit).
+
+## 7. Control files & single-writer discipline
+
+**Rule**: MEMORY.md (keeper writes), STATE.md (orchestrator writes), BUILDLOG.md (append-only, orchestrator appends).
+
+**Why**: Contention on shared state causes data loss and confusion. Single-writer enforcement prevents races.
+
+**Implementation**:
+- Designate one role per file.
+- Use heartbeats to detect live writers; skip if <200s.
+- On resume, read from disk; never trust in-memory state.
+- Append-only logs never overwrite; oldest entries rotate to archives.
+
+## 8. Secret-scan & version control
+
+**Rule**: `secret_scan.py` blocks every push (exit 1 = blocked). No credentials in repos. Sensitive data → private remote (e.g., claude-vault).
+
+**Why**: Credentials leak → account compromise. Scanning + gating prevents accidents.
+
+**Implementation**:
+- Install secret_scan.py in your aesop/tools/.
+- Run before every push (watchdog daemon does this).
+- If blocked, fix the issue and re-push (never --no-verify).
+- Log blocked attempts to SECURITY-ALERTS.log; triage later.
+
+## 9. Local execution only
+
+**Rule**: Python runs locally only (no cloud runners). Reusable scripts live in ~/scripts (indexed in CLAUDE.md); extend existing or add genuinely reusable.
+
+**Why**: Cloud execution = latency, cost, complexity, partial failure modes. Local = deterministic, fast, auditable.
+
+**Implementation**:
+- When you write a script, ask: "Will this be reused?" If yes, add to ~/scripts and index in CLAUDE.md. If no, keep in scratchpad.
+- Never schedule Python on a cloud agent or workflow.
+- Daemon scripts (watchdog, monitor, tooling) are canonical and live in aesop/tools/.
+
+## 10. Observability & audit trails
+
+**Rule**: Every agent run is logged. Every cost tracked. Every security event triaged.
+
+**Why**: Observability reveals cost leaks, drift, and breaches. Unreviewed alerts rot into ignored noise.
+
+**Implementation**:
+- FLEET-LEDGER.md: one row per agent outcome (timestamp, domain, token spend, result).
+- SECURITY-ALERTS.log: one row per security event (classified REAL/FP, triaged, archived).
+- COST-LOG.md: periodic summaries (spend rate, drivers, regressions, optimization levers).
+- Dashboard shows live status; triaged alerts move to RESOLVED-FP archives.
+
+---
+
+## Enforcement
+
+These rules are **guardrails-in-code**:
+- Watchdog daemon enforces secret-scan gate and branch discipline.
+- Monitor auto-detects violations and stages PROPOSALS.md or escalates.
+- Orchestrator reads STATE.md to verify cardinal rule compliance.
+- Violations caught late are logged and triaged; never silently ignored.
+
+## What to do if a rule seems wrong
+
+Rules are durable, but not dogmatic. If a rule creates friction:
+
+1. Propose a change (write it to PROPOSALS.md).
+2. Explain why it's necessary.
+3. Ask the user for approval.
+4. Never work around a rule; instead, propose improving it.
+
+---
+
+**Why these rules matter**: They ensure that your orchestration fleet operates **reliably** (inputs → outputs), **cheaply** (Haiku scale), **safely** (secrets gated), and **durably** (state survives wipes). Together, they enable you to scale from 1 Opus orchestrator to dozens of parallel Haiku subagents without losing control, visibility, or cost discipline.