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

package/daemons/run-watchdog.sh

@@ -4,15 +4,69 @@
 # Usage: run-watchdog.sh [--once]
 #
 # Configuration: export AESOP_ROOT=/path/to/aesop before running, or edit default below.
+# Testing: export AESOP_WATCHDOG_CYCLE_CMD to override backup-fleet.sh invocation
 
 AESOP_ROOT="${AESOP_ROOT:-.}"
 MODE="${1:-daemon}"
+LOCK_DIR="$AESOP_ROOT/state/.watchdog-lock"
+LOCK_STALE_THRESHOLD=300
 
-# 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."
+# Atomic lock acquire: mkdir is atomic (POSIX guarantees)
+# Returns 0 if lock acquired, 1 if held by another process, 2 if stale lock reclaimed
+acquire_lock() {
+  local lock_dir="$1"
+  local stale_threshold="$2"
+
+  # Ensure parent directory exists
+  mkdir -p "$(dirname "$lock_dir")" 2>/dev/null || true
+
+  # Try to create lock directory atomically (this is atomic on all POSIX systems)
+  if mkdir "$lock_dir" 2>/dev/null; then
+    # We created it; write timestamp and PID
+    date +%s > "$lock_dir/timestamp" 2>/dev/null
+    echo $$ > "$lock_dir/pid" 2>/dev/null
+    return 0
+  fi
+
+  # Lock directory already exists; check if it's stale
+  if [ -d "$lock_dir" ] && [ -f "$lock_dir/timestamp" ]; then
+    local lock_mtime=$(cat "$lock_dir/timestamp" 2>/dev/null || echo 0)
+    local now=$(date +%s)
+    local lock_age=$((now - lock_mtime))
+
+    if [ "$lock_age" -gt "$stale_threshold" ]; then
+      # Lock is stale; try to reclaim it
+      rm -rf "$lock_dir" 2>/dev/null || true
+      if mkdir "$lock_dir" 2>/dev/null; then
+        date +%s > "$lock_dir/timestamp" 2>/dev/null
+        echo $$ > "$lock_dir/pid" 2>/dev/null
+        echo "watchdog lock was stale (${lock_age}s) — reclaimed." >&2
+        return 2
+      fi
+    fi
+  fi
+
+  # Lock is held by another process
+  return 1
+}
+
+# Release lock: verify ownership before removing (P0 fix)
+release_lock() {
+  local lock_dir="$1"
+  if [ -f "$lock_dir/pid" ]; then
+    local lock_pid=$(cat "$lock_dir/pid" 2>/dev/null || echo "")
+    if [ "$lock_pid" = "$$" ]; then
+      rm -rf "$lock_dir" 2>/dev/null
+    fi
+  fi
+}
+
+# Try to acquire lock (applies to both --once and daemon modes)
+acquire_lock "$LOCK_DIR" "$LOCK_STALE_THRESHOLD"
+lock_result=$?
+
+if [ $lock_result -eq 1 ]; then
+  echo "watchdog already running — not starting a duplicate."
   exit 0
 fi
 
@@ -21,17 +75,43 @@ 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
+trap "release_lock \"$LOCK_DIR\"; echo \"[$(date '+%F %T')] === watchdog daemon (shell) STOPPED ===\" >> \"$AESOP_ROOT/state/FLEET-BACKUP.log\"; echo \"stopped.\"; exit 0" INT TERM
+
+# Allow override of backup cycle command (for testing)
+# Use array to safely handle paths with spaces (P1 fix)
+if [ -n "$AESOP_WATCHDOG_CYCLE_CMD" ]; then
+  # Override: run as-is through bash -c
+  CYCLE_CMD_ARRAY=("bash" "-c" "$AESOP_WATCHDOG_CYCLE_CMD")
+else
+  # Default: array form for proper quoting
+  CYCLE_CMD_ARRAY=("bash" "$AESOP_ROOT/daemons/backup-fleet.sh")
+fi
 
 if [ "$MODE" = "--once" ]; then
-  bash "$AESOP_ROOT/daemons/backup-fleet.sh" 2>&1
-  exit 0
+  full_out=$("${CYCLE_CMD_ARRAY[@]}" 2>&1)
+  cmd_exit=$?
+  echo "$full_out"
+  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
+  fi
+  release_lock "$LOCK_DIR"
+  exit $cmd_exit
 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"
+  full_out=$("${CYCLE_CMD_ARRAY[@]}" 2>&1)
+  cmd_exit=$?
+  if [ $cmd_exit -eq 0 ]; then
+    out=$(echo "$full_out" | tail -2)
+    printf '%s  cycle #%d\n%s\n' "$(date '+%H:%M:%S')" "$n" "$out"
+  else
+    echo "[$(date '+%F %T')] ERROR: cycle #$n failed with exit code $cmd_exit" >> "$AESOP_ROOT/state/FLEET-BACKUP.log"
+    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
   sleep 150
 done

package/dash/CLAUDE.md

@@ -0,0 +1,32 @@
+# dash/ — Dashboard TUI
+
+**Purpose**: Real-time TUI fleet monitoring — watchdog daemon + agent activity display.
+
+## Files
+
+- **watchdog-gui.sh** — Read-only terminal UI (4s refresh, double-buffered, no flicker). Displays daemon status, backed-up repos, heartbeats, recent events. Launch in own window; never inside tool shell. CRLF-safe (no line continuations).
+- **dash-extra.mjs** — Node.js agent activity detector. Scans AESOP_TRANSCRIPTS_ROOT for agent-*.jsonl files (last 12 min). TUI output by default; --json for web endpoints. Requires node on PATH (unavailable fallback if missing).
+
+## State contracts
+
+**watchdog-gui.sh reads** (heartbeat staleness thresholds applied):
+- `state/.watchdog-heartbeat` (epoch, threshold: 300s for watchdog)
+- `state/FLEET-BACKUP.log` (append-only, tail 3 lines)
+- `state/SECURITY-ALERTS.log` (counts HIGH/MED, grep filtering RESOLVED-FP)
+- `state/.watchdog-repos.json` (jq-parsed, status per repo)
+- `state/.heartbeats/*` (epoch, per-agent thresholds: 3600s monitor, 300s watchdog, 1800s default)
+
+**dash-extra.mjs reads**:
+- `~/.claude/projects/**/ agent-*.jsonl` (modified time, <12min filter, top 8 recent)
+- `state/SECURITY-ALERTS.log` (severity classification: HIGH/MED/DRIFT)
+
+**Refresh cadence**:
+- watchdog-gui.sh: 4s loop (infinite, Ctrl-C to exit)
+- dash-extra.mjs: called on-demand (no built-in loop)
+
+## Invariants & TUI conventions
+
+- **Never modify fleet state** — both tools are read-only dashboards.
+- **Infinite loop design** — watchdog-gui.sh runs forever; launch in dedicated terminal window, never inside tool shells.
+- **CRLF-safe** — no bash line continuations; portable POSIX.
+- **Node optional** — dash-extra.mjs gracefully prints "unavailable" if node missing; doesn't fail watchdog-gui.sh.

package/dash/dash-extra.mjs

@@ -1,18 +1,62 @@
 // 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)
+//   --json: output JSON array of agents with rich metadata (for web dashboard)
 //   (default): render TUI text output (for terminal dashboard)
+//
+// Enhanced JSONL parsing: extracts dispatch prompt, token counts, runtime, task label
+// Robust: tolerates malformed lines, caps read size on large files
 
 import fs from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
+
+// Configuration: env var > config file > built-in default
+// Helper: load aesop.config.json if it exists
+function loadConfigFile(aesopRoot) {
+  try {
+    const configPath = path.join(aesopRoot, 'aesop.config.json');
+    if (fs.existsSync(configPath)) {
+      return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+  } catch {
+    // Parse error or file doesn't exist; ignore
+  }
+  return {};
+}
+
+// Helper: expand ~ and environment variables in paths for portability
+function expandPath(pathStr) {
+  if (!pathStr) return pathStr;
+  // Expand ~ to home directory
+  if (pathStr.startsWith('~')) {
+    return path.join(os.homedir(), pathStr.slice(1));
+  }
+  // Expand environment variables like $VAR or %VAR%
+  return pathStr.replace(/\$\{?([A-Z_]+)\}?/gi, (match, varName) => {
+    return process.env[varName] || match;
+  });
+}
 
-// Configuration from environment
 const AESOP_ROOT = process.env.AESOP_ROOT || path.join(process.env.HOME || '.', 'aesop');
+const config = loadConfigFile(AESOP_ROOT);
+
 const TRANSCRIPTS_ROOT = path.resolve(
-  process.env.AESOP_TRANSCRIPTS_ROOT || path.join(process.env.HOME || '.', '.claude', 'projects')
+  expandPath(
+    process.env.AESOP_TRANSCRIPTS_ROOT ||
+    config.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');
+
+// Resolve state_root: env var > config > default
+const STATE_ROOT = path.resolve(
+  expandPath(
+    process.env.AESOP_STATE_ROOT ||
+    config.state_root ||
+    path.join(AESOP_ROOT, 'state')
+  )
+);
+const ALERTS_LOG = path.join(STATE_ROOT, 'SECURITY-ALERTS.log');
 
 // ANSI colors for TUI output
 const c = {
@@ -29,6 +73,110 @@ const c = {
 const now = Date.now();
 const out = [];
 
+// Activity window: only include files modified within the last 12 minutes
+const ACTIVITY_WINDOW = 12 * 60 * 1000;
+
+// Depth limit to match monitor's equivalent (prevent unbounded recursion on growing tree)
+const MAX_DEPTH = 6;
+
+// Parse JSONL agent transcript and extract rich metadata
+function parseAgentJsonl(filePath) {
+  const metadata = {
+    promptFull: '',
+    taskLabel: '',
+    tokensUsed: 0,
+    startedAt: null,
+    lastActivity: null,
+    runtimeSeconds: 0,
+    project: ''
+  };
+
+  try {
+    // Derive project from path: transcripts_root/PROJECT/session/...
+    const relPath = path.relative(TRANSCRIPTS_ROOT, filePath);
+    const parts = relPath.split(path.sep);
+    if (parts.length > 0) {
+      metadata.project = parts[0];
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const lines = content.split('\n');
+
+    // Cap reading: first 50 + last 50 lines to avoid expensive parsing on huge files
+    const linesToRead = [];
+    if (lines.length <= 100) {
+      linesToRead.push(...lines);
+    } else {
+      linesToRead.push(...lines.slice(0, 50));
+      linesToRead.push(...lines.slice(-50));
+    }
+
+    let firstTimestamp = null;
+    let lastTimestamp = null;
+
+    for (const line of linesToRead) {
+      if (!line.trim()) continue;
+
+      try {
+        const obj = JSON.parse(line);
+
+        // Extract dispatch prompt from first user message
+        if (obj.type === 'user' && obj.message && !metadata.promptFull) {
+          const content = obj.message.content;
+          if (typeof content === 'string') {
+            metadata.promptFull = content;
+            // Extract task label: first line of prompt, capped at 80 chars
+            const firstLine = content.split('\n')[0];
+            metadata.taskLabel = firstLine.substring(0, 80);
+          }
+        }
+
+        // Track timestamps
+        if (obj.timestamp) {
+          const ts = new Date(obj.timestamp).getTime();
+          if (!firstTimestamp) {
+            firstTimestamp = ts;
+            metadata.startedAt = obj.timestamp;
+          }
+          lastTimestamp = ts;
+          metadata.lastActivity = obj.timestamp;
+        }
+
+        // (token accumulation is a separate FULL-file pass below — sampling
+        //  only 100 lines under-counts tokens badly on long transcripts)
+      } catch {
+        // Silently skip malformed JSON lines
+        continue;
+      }
+    }
+
+    // Token total: scan EVERY line (usage records are spread throughout the
+    // transcript, not just the sampled head/tail). Cheap substring pre-filter
+    // keeps this fast on huge files by JSON-parsing only candidate lines.
+    for (const line of lines) {
+      if (!line.includes('"usage"')) continue;
+      try {
+        const obj = JSON.parse(line);
+        if (obj.type === 'assistant' && obj.usage) {
+          const { input_tokens = 0, output_tokens = 0 } = obj.usage;
+          metadata.tokensUsed += input_tokens + output_tokens;
+        }
+      } catch {
+        continue;
+      }
+    }
+
+    // Calculate runtime in seconds
+    if (firstTimestamp && lastTimestamp) {
+      metadata.runtimeSeconds = Math.floor((lastTimestamp - firstTimestamp) / 1000);
+    }
+  } catch {
+    // If file read fails, return empty metadata
+  }
+
+  return metadata;
+}
+
 // Read alerts log if present
 let slog = [];
 try {
@@ -37,14 +185,22 @@ try {
   }
 } catch {}
 
-// Recursively walk directory tree to find agent-*.jsonl files
-function walk(dir, accumulator) {
+// Recursively walk directory tree to find agent-*.jsonl files.
+// Respects depth limit. Activity window filtering happens per-file, not per-directory,
+// to avoid hiding active agents in dirs whose mtime was frozen at creation.
+function walk(dir, accumulator, depth = 0) {
+  // Stop recursion if depth exceeds limit
+  if (depth > MAX_DEPTH) return;
+
   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);
+        // Always descend into subdirectories (respecting depth limit only)
+        // Do NOT prune based on directory mtime, as directories don't update
+        // when files inside are appended to.
+        walk(fullPath, accumulator, depth + 1);
       } else if (/^agent-.*\.jsonl$/.test(entry.name)) {
         accumulator.push(fullPath);
       }
@@ -68,8 +224,13 @@ files = files
     return { f, mtime };
   })
   .filter(x => now - x.mtime < 12 * 60 * 1000)
-  .sort((a, b) => b.mtime - a.mtime)
-  .slice(0, 8);
+  .sort((a, b) => b.mtime - a.mtime);
+
+// True active total. The 8 below is a TUI terminal-space limit ONLY — not the
+// real count. The web (--json) emits ALL active agents; the TUI shows 8 + "N more".
+const totalActive = files.length;
+const runningCount = files.filter(x => now - x.mtime < 120 * 1000).length;
+const TUI_ROW_CAP = 8;
 
 // Extract description/hint from first ~60KB of agent transcript
 function label(filePath) {
@@ -93,14 +254,13 @@ function label(filePath) {
 // 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) {
+if (totalActive === 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) {
+// Render each agent (TUI caps rows to TUI_ROW_CAP for terminal space; the counts
+// above are the true totals across all active agents)
+for (const { f, mtime } of files.slice(0, TUI_ROW_CAP)) {
   const basename = path.basename(f);
   const ageSeconds = Math.round((now - mtime) / 1000);
 
@@ -110,8 +270,6 @@ for (const { f, mtime } of files) {
   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;
@@ -140,8 +298,12 @@ for (const { f, mtime } of files) {
   );
 }
 
-if (files.length > 0) {
-  out.push(`    ${c.D}${runningCount} running, ${files.length - runningCount} idle (last 12 min)${c.X}`);
+if (totalActive > TUI_ROW_CAP) {
+  out.push(`    ${c.D}… +${totalActive - TUI_ROW_CAP} more active (showing ${TUI_ROW_CAP} of ${totalActive})${c.X}`);
+}
+
+if (totalActive > 0) {
+  out.push(`    ${c.D}${runningCount} running, ${totalActive - runningCount} idle (last 12 min)${c.X}`);
 }
 
 // Output
@@ -170,11 +332,22 @@ if (process.argv.includes('--json')) {
       .replace(/\.jsonl$/, '')
       .slice(0, 13);
 
+    // Parse JSONL for rich metadata
+    const metadata = parseAgentJsonl(f);
+
     agents.push({
       id: agentId,
-      age_s: ageSeconds,
+      project: metadata.project,
       status: status,
-      hint: label(f).slice(0, 60)
+      age_s: ageSeconds,
+      hint: label(f).slice(0, 60),
+      // New enriched fields
+      startedAt: metadata.startedAt,
+      lastActivity: metadata.lastActivity,
+      runtimeSeconds: metadata.runtimeSeconds,
+      tokensUsed: metadata.tokensUsed,
+      taskLabel: metadata.taskLabel,
+      promptFull: metadata.promptFull
     });
   }
   process.stdout.write(JSON.stringify(agents) + '\n');

package/dash/watchdog-gui.sh

@@ -21,6 +21,7 @@ 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"
+CONFIG_FILE="$AESOP_ROOT/aesop.config.json"
 
 SPINNER=0
 FIRST_FRAME=1
@@ -29,15 +30,31 @@ FIRST_FRAME=1
 trap 'printf "\033[?25h"; exit 0' INT TERM
 printf '\033[?25l'
 
+# Load heartbeat thresholds from config; fallback to built-in defaults
+load_hb_thresholds() {
+  if [ -f "$CONFIG_FILE" ] && command -v jq >/dev/null 2>&1; then
+    HB_THRESHOLD_MONITOR=$(jq -r '.monitor.heartbeat_thresholds.monitor // 3600' "$CONFIG_FILE" 2>/dev/null || echo 3600)
+    HB_THRESHOLD_WATCHDOG=$(jq -r '.monitor.heartbeat_thresholds.watchdog // 300' "$CONFIG_FILE" 2>/dev/null || echo 300)
+    HB_THRESHOLD_DEFAULT=$(jq -r '.monitor.heartbeat_thresholds.default // 1800' "$CONFIG_FILE" 2>/dev/null || echo 1800)
+  else
+    HB_THRESHOLD_MONITOR=3600
+    HB_THRESHOLD_WATCHDOG=300
+    HB_THRESHOLD_DEFAULT=1800
+  fi
+}
+
 get_hb_threshold() {
   local name="$1"
   case "$name" in
-    *monitor*) echo 3600;;
-    *watchdog*) echo 300;;
-    *) echo 300;;
+    *monitor*) echo "$HB_THRESHOLD_MONITOR";;
+    *watchdog*) echo "$HB_THRESHOLD_WATCHDOG";;
+    *) echo "$HB_THRESHOLD_DEFAULT";;
   esac
 }
 
+# Load thresholds at startup
+load_hb_thresholds
+
 render_frame() {
   local FRAME=""
   FRAME="${FRAME}${B}${C}== FLEET WATCHDOG${X}\n"
@@ -122,8 +139,8 @@ while true; do
     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}
+  set -- $(awk '/^RESOLVED-FP/ { next } / HIGH / { hi++ } / MED / { me++ } END { print hi+0 " " me+0 }' "$SLOG" 2>/dev/null || echo '0 0')
+  HI="$1"; ME="$2"
 
   if [ "$FIRST_FRAME" -eq 1 ]; then
     printf '\033[2J'
@@ -133,7 +150,7 @@ while true; do
   fi
 
   render_frame | while IFS= read -r line; do
-    printf '%b\033[K\n' "$line"
+    printf '%s\033[K\n' "$line"
   done
   printf '\033[J'
 

package/docs/BEHAVIORAL-PR-REVIEW.md

@@ -0,0 +1,86 @@
+# Behavioral PR Review Checklist
+
+For pull requests that modify operational rules, agent behavior, monitoring, or orchestration policy, follow this checklist **before merging**.
+
+## 1. Rule & Cardinal Alignment
+
+- [ ] Rule named explicitly (e.g., "Rule 3: Reliability core" or "Cardinal Rule 1: Dispatch model")
+- [ ] PR title and description clearly state which rule(s) are affected
+- [ ] Change aligns with (or explicitly updates) `docs/CARDINAL-RULES.md`
+- [ ] No contradictions with other cardinal rules or guardrails
+
+## 2. Blast Radius & Impact
+
+- [ ] Impact scope documented (e.g., "affects all new monitor cycles", "affects heartbeat thresholds only", "no impact on running agents")
+- [ ] Backward compatibility assessed (breaking changes require migration plan)
+- [ ] Dependent systems identified (e.g., if monitor behavior changes, does ACTIONS.log parsing break?)
+- [ ] Risk of silent failures assessed (e.g., does fallback-to-default mask issues?)
+
+## 3. Verification & Testing
+
+- [ ] Reproducible test steps provided (not "tested locally" — state what was tested)
+- [ ] Test output attached or described (e.g., "ran `node monitor/collect-signals.mjs` twice, no duplicate PROPOSALS.md entries")
+- [ ] Idempotency verified if applicable (safe to run multiple times in same cycle?)
+- [ ] Edge cases covered (what if config missing? what if file unreadable?)
+
+## 4. Rollback & Recovery
+
+- [ ] Rollback plan documented (e.g., "revert commit + clear `.signal-state.json` + restart monitor")
+- [ ] Rollback tested if possible (e.g., apply change, verify it works, revert, verify rollback works)
+- [ ] No irreversible side effects (don't delete files without append-only logging first)
+
+## 5. Single-Writer & Proposal Provenance
+
+- [ ] If PROPOSALS.md or ACTIONS.log touched: confirm monitor still writes atomically (append-only)
+- [ ] If new proposal emission logic added: confirm idempotency (no duplicate proposals from re-runs)
+- [ ] If proposal came from monitor-collected signal: CHARTER.md action tier justified (AUTO vs PROPOSE)
+- [ ] If proposal came from human: documented in PROPOSALS.md (what human, when, why)
+
+## 6. Documentation & Handoff
+
+- [ ] Related doc updated (CHARTER.md, CARDINAL-RULES.md, GOVERNANCE.md, etc.)
+- [ ] Code comments added for non-obvious rule enforcement logic
+- [ ] Affected stakeholders notified (e.g., if monitor behavior changes, note in CONTRIBUTING.md)
+
+---
+
+## Worked Example: Cost-cap-per-repo Change
+
+**PR Title:** `feat(dispatch): Enforce Haiku cost cap per-repo instead of global`
+
+**Rule affected:** Cardinal Rule 1 (dispatch model), Rule 6 (commit discipline)
+
+**Blast radius:** All new agent dispatches via claude-code-cli; existing running agents unaffected
+
+**Verification:**
+- Ran dispatch-test-harness.sh with 3 mock repos, 5 Haiku spawns per repo
+- Confirmed ledger recorded per-repo cost separately
+- Rolled back, confirmed ledger reverted to single global entry
+- No test script in package.json; test via integration harness
+
+**Rollback:** Revert commit, clear `~/.claude/projects/*/FLEET-LEDGER.md`, restart orchestrator
+
+**Documentation:** Updated DISPATCH-MODEL.md section "Cost tracking" with new per-repo tracking format
+
+**Result:** ✓ Merged after review
+
+---
+
+## When to Request Changes (🔴 Critical)
+
+- Missing verification or test steps
+- Rollback plan untested or implausible
+- Proposal came from monitor but action tier (AUTO/PROPOSE) unjustified
+- Change introduces hardcoded paths, secrets, or usernames
+- Backward-incompatible change with no migration documented
+- Cardinal rule contradiction or guardrail violation
+
+## When to Suggest (💡 Consider)
+
+- Minor documentation clarification
+- Additional edge case to test (not required, but good to consider)
+- Related code that could benefit from similar fix (out of scope for this PR, open separate issue)
+
+## Proposal lifecycle
+
+Use `node tools/proposals.mjs list` to review pending proposals in monitor/PROPOSALS.md. To approve a proposal, run `node tools/proposals.mjs accept <signal-key>` (moves block to PROPOSALS-LOG.md under `## ACCEPTED <timestamp>`); to decline, run `reject <signal-key>` instead. Both commands are idempotent: re-running on an already-moved proposal is a no-op.