@matt82198/aesop 0.1.0 → 0.2.0

package/tools/defect_escape.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""
+Defect escape telemetry — Haiku code quality measurement.
+
+Turns 'is Haiku producing good code' from assertion into a measured number.
+
+Given --repo <path> --since <ISO date>, computes:
+  (a) fix-forward rate: count commits matching /fix-forward|hotfix|fix(ci)|repair/i
+      vs total feature commits in the window
+  (b) first-try-estimate: per-merge, whether a 'fix-forward' commit followed
+      the feature commit before the merge (proxy for not-first-try-green)
+
+Output: JSON with {window, feature_commits, fixforward_commits, fixforward_rate, first_try_estimate}
+
+Deterministic, stdlib+subprocess(git) only, no network, Windows-safe.
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+
+def run_git(args, repo_path, check=True):
+    """
+    Run git command in repo, return stdout.
+
+    Args:
+        args: list of git command args (e.g., ["log", "--oneline"])
+        repo_path: path to git repo
+        check: raise on non-zero exit if True
+
+    Returns:
+        stdout as string
+    """
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(repo_path)] + args,
+            capture_output=True,
+            text=True, encoding="utf-8", errors="replace",
+            check=check,
+        )
+        return result.stdout
+    except subprocess.CalledProcessError as e:
+        if check:
+            raise RuntimeError(
+                f"git command failed: {' '.join(args)}\n"
+                f"stderr: {e.stderr}"
+            )
+        return ""
+
+
+def get_commits_since(repo_path, since_date):
+    """
+    Get all commits since a date using git log.
+
+    Args:
+        repo_path: path to git repo
+        since_date: ISO format date string (e.g., "2026-07-01")
+
+    Returns:
+        list of commit hashes
+    """
+    output = run_git(
+        [
+            "log",
+            "--all",
+            f"--since={since_date}",
+            "--format=%H",
+        ],
+        repo_path,
+    )
+    commits = [c.strip() for c in output.strip().split("\n") if c.strip()]
+    return commits
+
+
+def get_commit_subject(repo_path, commit_hash):
+    """Get commit subject line."""
+    output = run_git(
+        ["log", "-1", "--format=%s", commit_hash],
+        repo_path,
+    )
+    return output.strip()
+
+
+def is_fixforward_commit(subject):
+    """
+    Check if commit subject matches fix-forward pattern.
+
+    Matches: fix-forward, hotfix, fix(ci), repair (case-insensitive)
+    """
+    import re
+
+    patterns = [
+        r"fix-forward",
+        r"hotfix",
+        r"fix\s*\(\s*ci\s*\)",
+        r"repair",
+    ]
+    combined = "|".join(f"({p})" for p in patterns)
+    return bool(re.search(combined, subject, re.IGNORECASE))
+
+
+def get_commit_parents(repo_path, commit_hash):
+    """Get parent commit hashes for a commit."""
+    output = run_git(
+        ["log", "-1", "--format=%P", commit_hash],
+        repo_path,
+    )
+    parents = output.strip().split() if output.strip() else []
+    return parents
+
+
+def compute_first_try_estimate(repo_path, commits_window):
+    """
+    Compute first-try-estimate: fraction of fix-forward commits that
+    followed a feature commit before the merge (proxy for not-first-try-green).
+
+    Simplified approach: for commits in the window, check if a fix-forward
+    commit appears after its preceding feature commit (naive linear scan).
+
+    Args:
+        repo_path: path to git repo
+        commits_window: list of commit hashes in window (reverse chronological)
+
+    Returns:
+        float 0.0-1.0 or None if no opportunities in window
+    """
+    if not commits_window or len(commits_window) < 2:
+        return None
+
+    # Build subject map for all commits in window
+    commit_subjects = {}
+    for commit in commits_window:
+        try:
+            subject = get_commit_subject(repo_path, commit)
+            commit_subjects[commit] = subject
+        except Exception:
+            pass
+
+    # Linear scan: count instances where a fix-forward follows a feature
+    # (commits come in reverse chronological, so "follows" means appears later in list)
+    feature_commits = [c for c in commits_window if c in commit_subjects
+                       and not is_fixforward_commit(commit_subjects[c])]
+
+    if not feature_commits:
+        return None
+
+    followed_count = 0
+    for i, feature_commit in enumerate(feature_commits):
+        # Check if any fix-forward appears in next few commits
+        # (simple heuristic: next 3 commits after this feature)
+        feature_idx = commits_window.index(feature_commit)
+        for j in range(feature_idx + 1, min(feature_idx + 4, len(commits_window))):
+            next_commit = commits_window[j]
+            if next_commit in commit_subjects:
+                if is_fixforward_commit(commit_subjects[next_commit]):
+                    followed_count += 1
+                    break
+
+    return followed_count / len(feature_commits) if feature_commits else None
+
+
+def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="Defect escape telemetry — Haiku code quality measurement"
+    )
+    parser.add_argument("--repo", required=True, help="Path to git repository")
+    parser.add_argument(
+        "--since", required=True, help="ISO format date (e.g., 2026-07-01)"
+    )
+    parser.add_argument(
+        "--json", action="store_true", help="Output JSON (default: human-readable)"
+    )
+
+    args = parser.parse_args()
+
+    repo_path = Path(args.repo)
+    if not repo_path.exists():
+        print(f"Error: repo not found: {repo_path}", file=sys.stderr)
+        sys.exit(1)
+
+    # Validate date format
+    try:
+        datetime.fromisoformat(args.since)
+    except ValueError:
+        print(f"Error: invalid date format (use ISO): {args.since}", file=sys.stderr)
+        sys.exit(1)
+
+    # Get all commits in window
+    try:
+        all_commits = get_commits_since(repo_path, args.since)
+    except RuntimeError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Count feature vs fix-forward
+    feature_commits = []
+    fixforward_commits = []
+
+    for commit in all_commits:
+        subject = get_commit_subject(repo_path, commit)
+        if is_fixforward_commit(subject):
+            fixforward_commits.append(commit)
+        else:
+            feature_commits.append(commit)
+
+    # Compute rates
+    total_feature = len(feature_commits)
+    total_fixforward = len(fixforward_commits)
+    fixforward_rate = (
+        total_fixforward / total_feature if total_feature > 0 else 0.0
+    )
+
+    # Compute first-try estimate
+    first_try_estimate = compute_first_try_estimate(repo_path, all_commits)
+
+    result = {
+        "window": {
+            "since": args.since,
+            "total_commits": len(all_commits),
+        },
+        "feature_commits": total_feature,
+        "fixforward_commits": total_fixforward,
+        "fixforward_rate": round(fixforward_rate, 4),
+        "first_try_estimate": (
+            round(first_try_estimate, 4) if first_try_estimate is not None else None
+        ),
+    }
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"Defect Escape Telemetry Report")
+        print(f"  Window: since {args.since}")
+        print(f"  Total commits: {len(all_commits)}")
+        print(f"  Feature commits: {total_feature}")
+        print(f"  Fix-forward commits: {total_fixforward}")
+        print(f"  Fix-forward rate: {fixforward_rate:.2%}")
+        if first_try_estimate is not None:
+            print(f"  First-try estimate: {first_try_estimate:.2%}")
+        else:
+            print(f"  First-try estimate: N/A (no merges in window)")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/doctor.js

@@ -126,7 +126,7 @@ function checkPort8770() {
       if (!resolved) {
         resolved = true;
         cleanup();
-        resolve({ passed: false, hint: 'Port 8770 is in use' });
+        resolve({ passed: false, hint: 'Port 8770 in use — is another fleet running? Update dashboard.port in aesop.config.json' });
       }
     });
 

package/tools/eod_sweep.py

@@ -11,21 +11,31 @@ Output contract:
   Line 1: EOD-SWEEP: SAFE or EOD-SWEEP: AT-RISK — <n> findings
   Lines 2+: One finding per line (if any)
   Exit code 0 only when SAFE.
+  Verdict also appended to BUILDLOG.md (if --buildlog provided or AESOP_STATE_ROOT set).
 
 Usage: eod_sweep.py [--repos PATHS] [--readonly-repos PATHS] [--fix-push]
+                    [--buildlog PATH] [--timestamp YYYY-MM-DD HH:MM]
 
   --repos: Colon-separated paths to scan (default: empty; use env var or flag to specify)
   --readonly-repos: Colon-separated paths that should NOT be auto-pushed
   --fix-push: Auto-push unpushed commits in repos where safe
+  --buildlog: Path to BUILDLOG.md (default: AESOP_STATE_ROOT/BUILDLOG.md or ./state/BUILDLOG.md)
+  --timestamp: Timestamp for BUILDLOG entry (format: YYYY-MM-DD HH:MM; omit to exclude timestamp)
 """
 
 import json
 import subprocess
 import sys
+import os
 from pathlib import Path
 from datetime import datetime
 import time
 
+try:
+    from common import get_state_dir
+except ImportError:
+    from tools.common import get_state_dir
+
 
 class Finding:
     """A single finding with repo + message."""
@@ -153,6 +163,32 @@ def run_secret_scan(repo_path):
         return False
 
 
+def append_to_buildlog(buildlog_path, verdict_line, timestamp_str=None):
+    """Append verdict to BUILDLOG.md (append-only).
+
+    Args:
+        buildlog_path: Path to BUILDLOG.md file.
+        verdict_line: The verdict line to append (e.g., "EOD-SWEEP: SAFE").
+        timestamp_str: Optional timestamp string (format: YYYY-MM-DD HH:MM).
+                      If None, timestamp is omitted from the entry.
+    """
+    buildlog_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Create header if file doesn't exist
+    if not buildlog_path.exists():
+        buildlog_path.write_text("# Build Log (append-only)\n")
+
+    # Build entry line with optional timestamp
+    if timestamp_str:
+        entry_line = f"### [{timestamp_str}] {verdict_line}"
+    else:
+        entry_line = f"### {verdict_line}"
+
+    # Append to BUILDLOG
+    with open(buildlog_path, "a", encoding="utf-8") as f:
+        f.write(entry_line + "\n")
+
+
 def main():
     import argparse
     parser = argparse.ArgumentParser(description=__doc__)
@@ -171,6 +207,16 @@ def main():
         action='store_true',
         help='Auto-push unpushed commits'
     )
+    parser.add_argument(
+        '--buildlog',
+        default=None,
+        help='Path to BUILDLOG.md (default: AESOP_STATE_ROOT/BUILDLOG.md or ./state/BUILDLOG.md)'
+    )
+    parser.add_argument(
+        '--timestamp',
+        default=None,
+        help='Timestamp for BUILDLOG entry (format: YYYY-MM-DD HH:MM; omit to exclude timestamp)'
+    )
     args = parser.parse_args()
 
     # Parse repos
@@ -232,6 +278,18 @@ def main():
     for finding in findings:
         print(f"  {finding}")
 
+    # Append to BUILDLOG if path is available
+    buildlog_path = None
+    if args.buildlog:
+        buildlog_path = Path(args.buildlog)
+    else:
+        # Try to derive from AESOP_STATE_ROOT or default to ./state
+        state_dir = get_state_dir()
+        buildlog_path = state_dir / "BUILDLOG.md"
+
+    if buildlog_path:
+        append_to_buildlog(buildlog_path, verdict_line, args.timestamp)
+
     sys.exit(exit_code)
 
 

package/tools/fleet.js

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+
+/**
+ * Aesop fleet — One-shot fleet snapshot
+ *
+ * Prints a comprehensive fleet status snapshot:
+ *  - Agents (from dash-extra.mjs --json passthrough)
+ *  - Heartbeat ages (watchdog + monitor, seconds, with STALE status if >threshold)
+ *  - Tracker lane counts (from state/tracker.json)
+ *  - Orchestrator status (from state/orchestrator-status.json)
+ *
+ * Graceful degradation: any missing state file produces explicit 'unavailable: <why>'
+ * rather than crashing or leaving blank output. Never crashes; always exits cleanly.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+
+const CURRENT_DIR = process.cwd();
+const WATCHDOG_STALE_THRESHOLD = 300; // seconds
+const MONITOR_STALE_THRESHOLD = 3600; // seconds
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+function readHeartbeat(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    const content = fs.readFileSync(filePath, 'utf8').trim();
+    const timestamp = parseInt(content, 10);
+    if (isNaN(timestamp)) {
+      return null;
+    }
+    return timestamp;
+  } catch (e) {
+    return null;
+  }
+}
+
+function getHeartbeatStatus(timestamp, threshold) {
+  if (timestamp === null) {
+    return { age: null, status: 'MISSING' };
+  }
+  const now = Math.floor(Date.now() / 1000);
+  const age = now - timestamp;
+  const isStale = age > threshold;
+  const status = isStale ? 'STALE' : 'OK';
+  return { age, status };
+}
+
+function loadJSON(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    const content = fs.readFileSync(filePath, 'utf8').trim();
+    if (!content) {
+      return null;
+    }
+    return JSON.parse(content);
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Invoke dash-extra.mjs --json to get active agents
+ * Returns { agents: [...] } or { unavailable: "reason" }
+ */
+function getFleetAgents(aesopRoot) {
+  return new Promise((resolve) => {
+    const dashExtraPath = path.join(aesopRoot, 'dash', 'dash-extra.mjs');
+
+    if (!fs.existsSync(dashExtraPath)) {
+      resolve({ unavailable: 'dash-extra.mjs not found' });
+      return;
+    }
+
+    try {
+      const proc = spawn('node', [dashExtraPath, '--json'], {
+        cwd: aesopRoot,
+        env: {
+          ...process.env,
+          AESOP_ROOT: aesopRoot
+        },
+        timeout: 5000,
+        stdio: ['ignore', 'pipe', 'pipe']
+      });
+
+      let stdout = '';
+      let stderr = '';
+      let resolved = false;
+
+      const cleanup = () => {
+        if (!resolved) {
+          resolved = true;
+          if (proc && !proc.killed) {
+            try {
+              proc.kill();
+            } catch (e) {
+              // ignore
+            }
+          }
+        }
+      };
+
+      const timeoutHandle = setTimeout(() => {
+        cleanup();
+        resolve({ unavailable: 'dash-extra.mjs timeout' });
+      }, 6000);
+
+      proc.stdout.on('data', (data) => {
+        stdout += data.toString();
+      });
+
+      proc.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+
+      proc.on('close', (code) => {
+        clearTimeout(timeoutHandle);
+        if (!resolved) {
+          resolved = true;
+          if (code === 0 && stdout.trim()) {
+            try {
+              const agents = JSON.parse(stdout);
+              resolve({
+                agents: Array.isArray(agents) ? agents : [],
+                count: Array.isArray(agents) ? agents.length : 0
+              });
+            } catch (e) {
+              resolve({ unavailable: 'failed to parse dash-extra output' });
+            }
+          } else {
+            resolve({ unavailable: 'dash-extra.mjs failed' });
+          }
+        }
+      });
+
+      proc.on('error', (err) => {
+        clearTimeout(timeoutHandle);
+        cleanup();
+        if (!resolved) {
+          resolved = true;
+          resolve({ unavailable: 'dash-extra.mjs spawn error' });
+        }
+      });
+    } catch (e) {
+      resolve({ unavailable: 'exception spawning dash-extra.mjs' });
+    }
+  });
+}
+
+function getTrackerLaneCounts(trackerPath) {
+  const tracker = loadJSON(trackerPath);
+  if (!tracker) {
+    return { unavailable: 'tracker.json not found or malformed' };
+  }
+
+  const items = tracker.items || [];
+  const byLane = {};
+
+  for (const item of items) {
+    const lane = item.lane || 'unknown';
+    byLane[lane] = (byLane[lane] || 0) + 1;
+  }
+
+  return {
+    total_items: items.length,
+    by_lane: byLane
+  };
+}
+
+function getOrchestratorStatus(orchStatusPath) {
+  const status = loadJSON(orchStatusPath);
+  if (!status) {
+    return { unavailable: 'orchestrator-status.json not found or malformed' };
+  }
+  return status;
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+(async function main() {
+  try {
+    // Determine AESOP_ROOT
+    const aesopRoot = process.env.AESOP_ROOT || CURRENT_DIR;
+
+    const stateDir = path.join(aesopRoot, 'state');
+    const watchdogHeartbeatPath = path.join(stateDir, '.watchdog-heartbeat');
+    const monitorHeartbeatPath = path.join(stateDir, '.monitor-heartbeat');
+    const trackerPath = path.join(stateDir, 'tracker.json');
+    const orchStatusPath = path.join(stateDir, 'orchestrator-status.json');
+
+    // Gather all data concurrently
+    const [watchdogTs, monitorTs, agentsData, trackerData, orchStatusData] = await Promise.all([
+      Promise.resolve(readHeartbeat(watchdogHeartbeatPath)),
+      Promise.resolve(readHeartbeat(monitorHeartbeatPath)),
+      getFleetAgents(aesopRoot),
+      Promise.resolve(getTrackerLaneCounts(trackerPath)),
+      Promise.resolve(getOrchestratorStatus(orchStatusPath))
+    ]);
+
+    // Build result object
+    const result = {
+      timestamp: new Date().toISOString(),
+      aesop_root: aesopRoot,
+      heartbeats: {
+        watchdog: null,
+        monitor: null
+      },
+      agents: agentsData,
+      tracker: trackerData,
+      orchestrator: orchStatusData
+    };
+
+    // Process watchdog heartbeat
+    const watchdogStatus = getHeartbeatStatus(watchdogTs, WATCHDOG_STALE_THRESHOLD);
+    if (watchdogStatus.age !== null) {
+      result.heartbeats.watchdog = {
+        age_seconds: watchdogStatus.age,
+        status: watchdogStatus.status,
+        threshold_seconds: WATCHDOG_STALE_THRESHOLD
+      };
+    } else {
+      result.heartbeats.watchdog = {
+        unavailable: watchdogStatus.status
+      };
+    }
+
+    // Process monitor heartbeat
+    const monitorStatus = getHeartbeatStatus(monitorTs, MONITOR_STALE_THRESHOLD);
+    if (monitorStatus.age !== null) {
+      result.heartbeats.monitor = {
+        age_seconds: monitorStatus.age,
+        status: monitorStatus.status,
+        threshold_seconds: MONITOR_STALE_THRESHOLD
+      };
+    } else {
+      result.heartbeats.monitor = {
+        unavailable: monitorStatus.status
+      };
+    }
+
+    // Output JSON
+    console.log(JSON.stringify(result, null, 2));
+
+    process.exitCode = 0;
+  } catch (err) {
+    console.error(`Error gathering fleet snapshot: ${err.message}`);
+    process.exitCode = 1;
+  }
+})();