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

package/tools/metrics_gate.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""
+NO-UNVERIFIED-METRICS gate: scan git diff for hard numeric claims in *.md files
+that lack source verification.
+
+A hard numeric claim is:
+  - Percentages (e.g., "42%")
+  - Multipliers (e.g., "3x", "3×")
+  - Dollar amounts (e.g., "$15000")
+
+Exclusions (don't require verification):
+  - Version numbers (e.g., "v1.2.3", "2.0")
+  - Dates (e.g., "2024", "2025")
+  - Line numbers (e.g., "line 42", "line:123")
+  - Numbers in code/JSON contexts
+
+A claim passes verification if:
+  - The same line or an adjacent line has: <!-- metrics-verified: <source> -->
+  - OR the claim itself looks like a version (e.g., "v1.2.3")
+  - OR the claim is a year/date (2000-2999)
+  - OR the claim is a line reference (line X, :X, @X patterns)
+
+Usage:
+  metrics_gate.py [origin/main...HEAD]
+    Scans ADDED lines in diff from origin/main...HEAD (default).
+    Exits 0 if all metrics are verified or excluded.
+    Exits 1 if unverified hard claims found (lists them).
+
+Used in CI as a PR gate:
+  metrics_gate.py origin/main...HEAD
+"""
+
+import sys
+import subprocess
+import re
+from pathlib import Path
+from typing import List, Tuple, Optional
+
+
+class MetricsGate:
+    """Scan git diffs for unverified hard numeric claims."""
+
+    # Regex patterns for hard numeric claims
+    PERCENTAGE_PATTERN = re.compile(r'\d+\s*%')
+    MULTIPLIER_PATTERN = re.compile(r'\d+\s*[x×]\s*(?:faster|slower|more|less|bigger|smaller|better|worse|improvement|increase|decrease|growth)')
+    DOLLAR_PATTERN = re.compile(r'\$\s*\d+')
+
+    # Exclusion patterns
+    VERSION_PATTERN = re.compile(r'\bv?\d+\.\d+(?:\.\d+)?(?:[.-](?:alpha|beta|rc|a|b)\d*)?\b')
+    DATE_PATTERN = re.compile(r'\b(19|20)\d{2}\b')
+    LINE_REFERENCE_PATTERN = re.compile(r'(?:line\s*|:|@)\s*\d+')
+
+    # Verification marker pattern
+    VERIFICATION_PATTERN = re.compile(r'<!--\s*metrics-verified:\s*[^-]+\s*-->')
+
+    def __init__(self, diff_range: str = "origin/main...HEAD"):
+        """Initialize with a git diff range."""
+        self.diff_range = diff_range
+        self.repo_root = Path(__file__).resolve().parent.parent
+
+    def get_diff_lines(self) -> List[Tuple[str, str]]:
+        """Get lines added in diff. Returns list of (file, line_content)."""
+        try:
+            # Use git diff to get added lines
+            result = subprocess.run(
+                ["git", "diff", self.diff_range, "--unified=0"],
+                cwd=self.repo_root,
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if result.returncode not in (0, 128):  # 128 = invalid range
+                # Fall back to empty if range is invalid
+                return []
+
+            diff_output = result.stdout
+            added_lines = []
+            current_file = None
+
+            for line in diff_output.split('\n'):
+                # Track current file
+                if line.startswith('+++'):
+                    current_file = line[6:]  # Strip "+++ b/"
+                    if current_file.startswith('b/'):
+                        current_file = current_file[2:]
+                # Capture added lines (start with '+' but not '+++')
+                elif line.startswith('+') and not line.startswith('+++'):
+                    content = line[1:]  # Strip leading '+'
+                    if current_file and current_file.endswith('.md'):
+                        added_lines.append((current_file, content))
+
+            return added_lines
+        except Exception:
+            return []
+
+    def is_version_number(self, text: str) -> bool:
+        """Check if text looks like a version number."""
+        return bool(self.VERSION_PATTERN.search(text))
+
+    def is_date(self, text: str) -> bool:
+        """Check if text looks like a date (year)."""
+        return bool(self.DATE_PATTERN.search(text))
+
+    def is_line_reference(self, text: str) -> bool:
+        """Check if text looks like a line reference."""
+        return bool(self.LINE_REFERENCE_PATTERN.search(text))
+
+    def is_excluded(self, text: str) -> bool:
+        """Check if a claim is excluded from verification."""
+        return (
+            self.is_version_number(text)
+            or self.is_date(text)
+            or self.is_line_reference(text)
+        )
+
+    def find_hard_claims(self, text: str) -> List[str]:
+        """Find hard numeric claims in text."""
+        claims = []
+        # Find percentages
+        claims.extend(self.PERCENTAGE_PATTERN.findall(text))
+        # Find multipliers
+        claims.extend(self.MULTIPLIER_PATTERN.findall(text))
+        # Find dollar amounts
+        claims.extend(self.DOLLAR_PATTERN.findall(text))
+        return claims
+
+    def is_verified(self, lines: List[Tuple[str, int, str]]) -> bool:
+        """Check if a claim line has verification marker nearby.
+
+        lines: list of (file, line_num, content) for this and adjacent lines
+        """
+        for _, _, content in lines:
+            if self.VERIFICATION_PATTERN.search(content):
+                return True
+        return False
+
+    def check(self) -> Tuple[int, List[str]]:
+        """Check for unverified metrics. Returns (exit_code, list of failures)."""
+        diff_lines = self.get_diff_lines()
+        failures = []
+
+        # Group lines by file for context
+        lines_by_file = {}
+        for file, content in diff_lines:
+            if file not in lines_by_file:
+                lines_by_file[file] = []
+            lines_by_file[file].append(content)
+
+        # Check each added line
+        for file, contents in lines_by_file.items():
+            for i, content in enumerate(contents):
+                claims = self.find_hard_claims(content)
+                for claim in claims:
+                    # Skip if it's excluded (version, date, line ref)
+                    if self.is_excluded(claim):
+                        continue
+
+                    # Check if verified (current line or adjacent)
+                    context = []
+                    if i > 0:
+                        context.append((file, i - 1, contents[i - 1]))
+                    context.append((file, i, content))
+                    if i + 1 < len(contents):
+                        context.append((file, i + 1, contents[i + 1]))
+
+                    if not self.is_verified(context):
+                        failures.append(
+                            f"{file}: unverified metric '{claim}' — add "
+                            f"<!-- metrics-verified: <source> --> on same or adjacent line"
+                        )
+
+        exit_code = 1 if failures else 0
+        return exit_code, failures
+
+
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "diff_range",
+        nargs="?",
+        default="origin/main...HEAD",
+        help="Git diff range to scan (default: origin/main...HEAD)",
+    )
+    args = parser.parse_args()
+
+    gate = MetricsGate(args.diff_range)
+    exit_code, failures = gate.check()
+
+    if failures:
+        print("NO-UNVERIFIED-METRICS GATE FAILED:", file=sys.stderr)
+        for failure in failures:
+            print(f"  - {failure}", file=sys.stderr)
+        sys.exit(exit_code)
+    else:
+        print("NO-UNVERIFIED-METRICS: OK")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/tools/orchestrator_status.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Orchestrator status CLI tool - atomic status updates for the orchestration layer.
+
+Usage:
+  python orchestrator_status.py set --activity "dispatching wave-8" --phase audit [--id main --role orchestrator]
+  python orchestrator_status.py clear
+
+Writes state/orchestrator-status.json atomically (temp+replace) for wave-8/wave-9+ compatibility.
+No external dependencies.
+"""
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def get_state_dir():
+    """Get state directory from env or fallback to AESOP_ROOT/state."""
+    state_root = os.getenv("AESOP_STATE_ROOT")
+    if state_root:
+        return Path(state_root)
+    
+    aesop_root = os.getenv("AESOP_ROOT", str(Path.home() / "aesop"))
+    return Path(aesop_root) / "state"
+
+
+def set_status(activity, phase, id=None, role=None):
+    """Atomically write orchestrator status."""
+    state_dir = get_state_dir()
+    state_dir.mkdir(parents=True, exist_ok=True)
+    
+    status_data = {
+        "id": id or "main",
+        "role": role or "orchestrator",
+        "parent_id": None,
+        "activity": activity,
+        "phase": phase,
+        "updated_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    }
+    
+    status_file = state_dir / "orchestrator-status.json"
+    temp_file = status_file.with_suffix(".json.tmp")
+    
+    try:
+        with open(temp_file, "w", encoding="utf-8") as f:
+            json.dump(status_data, f, indent=2)
+        os.replace(str(temp_file), str(status_file))
+        print(f"[OK] Status updated: activity={activity}, phase={phase}")
+    except Exception as e:
+        print(f"[ERROR] Failed to write status: {e}", file=sys.stderr)
+        try:
+            temp_file.unlink()
+        except:
+            pass
+        sys.exit(1)
+
+
+def clear_status():
+    """Atomically remove orchestrator status file."""
+    state_dir = get_state_dir()
+    status_file = state_dir / "orchestrator-status.json"
+    
+    try:
+        if status_file.exists():
+            status_file.unlink()
+        print("[OK] Status cleared")
+    except Exception as e:
+        print(f"[ERROR] Failed to clear status: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Atomic orchestrator status updates"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    
+    # set command
+    set_parser = subparsers.add_parser("set", help="Set orchestrator status")
+    set_parser.add_argument("--activity", required=True, help="Activity description")
+    set_parser.add_argument("--phase", required=True, help="Phase (plan, dispatch, audit, etc)")
+    set_parser.add_argument("--id", default="main", help="Orchestrator ID (default: main)")
+    set_parser.add_argument("--role", default="orchestrator", help="Orchestrator role (default: orchestrator)")
+    
+    # clear command
+    subparsers.add_parser("clear", help="Clear orchestrator status")
+    
+    args = parser.parse_args()
+    
+    if args.command == "set":
+        set_status(args.activity, args.phase, args.id, args.role)
+    elif args.command == "clear":
+        clear_status()
+
+
+if __name__ == "__main__":
+    main()

package/tools/power_selftest.py

@@ -0,0 +1,386 @@
+#!/usr/bin/env python3
+"""
+power_selftest.py — Health check harness for /power bootstrap.
+Validates hooks, brain state, heartbeats, decisions, and scanner regression.
+Exit 0 if OK/DEGRADED, 1 if FAIL. Prints one summary line + bullets for non-OK items.
+
+EXPECTED OUTPUT — HEALTHY SYSTEM:
+  POWER-SELFTEST: OK — hooks:ok brain:ok beats:ok decisions:0 pending,0 inbox scanner:n/a
+
+EXPECTED OUTPUT — UNHEALTHY SYSTEM:
+  POWER-SELFTEST: DEGRADED — hooks:ok brain:ok beats:stale decisions:2 pending scanner:8/9
+  - beats: watchdog:stale
+  - scanner: 8/9 tests passed
+
+Exit codes: 0=OK/DEGRADED, 1=FAIL (FAIL is any hook/brain/scanner non-OK; stale beats=WARN not FAIL)
+
+Configuration:
+  - Reads aesop.config.json for brain_root, state_root, scripts_root overrides.
+  - Env vars override config file: BRAIN_ROOT, AESOP_STATE_ROOT, SCRIPTS_ROOT.
+  - Falls back to defaults: brain_root=~/.claude, state_root=<aesop-root>/state.
+  - Gracefully degrades when targets don't exist (reports n/a instead of crashing).
+"""
+
+import json
+import subprocess
+import sys
+import io
+from pathlib import Path
+from datetime import datetime
+from collections import namedtuple
+
+# Force UTF-8 encoding on stdout to prevent UnicodeEncodeError on Windows
+if sys.stdout.encoding != 'utf-8':
+    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+
+# Named tuples for result tracking
+Check = namedtuple('Check', ['name', 'status', 'details', 'is_fail'])
+
+
+def load_config():
+    """Load aesop.config.json if present; return dict."""
+    try:
+        config_path = Path.cwd() / 'aesop.config.json'
+        if config_path.exists():
+            with open(config_path) as f:
+                return json.load(f)
+    except Exception:
+        pass
+    return {}
+
+
+def resolve_paths(config):
+    """Resolve paths with precedence: env var > config > default."""
+    aesop_root = Path.cwd()
+
+    # brain_root: env BRAIN_ROOT > config brain_root > default ~/.claude
+    brain_root = Path(
+        os.environ.get('BRAIN_ROOT', config.get('brain_root', ''))
+        or str(Path.home() / '.claude')
+    ).expanduser()
+
+    # state_root: env AESOP_STATE_ROOT > config state_root > default <aesop-root>/state
+    state_root = Path(
+        os.environ.get('AESOP_STATE_ROOT', config.get('state_root', ''))
+        or str(aesop_root / 'state')
+    ).expanduser()
+
+    # scripts_root: env SCRIPTS_ROOT > config scripts_root > default <aesop-root>/tools
+    scripts_root = Path(
+        os.environ.get('SCRIPTS_ROOT', config.get('scripts_root', ''))
+        or str(aesop_root / 'tools')
+    ).expanduser()
+
+    return {
+        'aesop_root': aesop_root,
+        'brain_root': brain_root,
+        'state_root': state_root,
+        'scripts_root': scripts_root,
+    }
+
+
+import os
+config = load_config()
+paths = resolve_paths(config)
+
+
+def check_hooks():
+    """Check hooks configuration. Returns Check."""
+    try:
+        settings_path = paths['brain_root'] / 'settings.json'
+        if not settings_path.exists():
+            return Check('hooks', 'OK', '(n/a)', False)
+
+        with open(settings_path) as f:
+            settings = json.load(f)
+
+        hooks = settings.get('hooks', {})
+        pre_tool_entries = hooks.get('PreToolUse', [])
+        post_tool_entries = hooks.get('PostToolUse', [])
+
+        # Check for required matchers in PreToolUse and PostToolUse arrays
+        pre_matchers = set()
+        post_matchers = set()
+        all_commands = []
+
+        for entry in pre_tool_entries if isinstance(pre_tool_entries, list) else []:
+            if isinstance(entry, dict):
+                matcher = entry.get('matcher', '')
+                if matcher:
+                    pre_matchers.update(matcher.split('|'))
+                hook_list = entry.get('hooks', [])
+                for hook in hook_list:
+                    if isinstance(hook, dict):
+                        cmd = hook.get('command', '')
+                        if cmd:
+                            all_commands.append(cmd)
+
+        for entry in post_tool_entries if isinstance(post_tool_entries, list) else []:
+            if isinstance(entry, dict):
+                matcher = entry.get('matcher', '')
+                if matcher:
+                    post_matchers.update(matcher.split('|'))
+                hook_list = entry.get('hooks', [])
+                for hook in hook_list:
+                    if isinstance(hook, dict):
+                        cmd = hook.get('command', '')
+                        if cmd:
+                            all_commands.append(cmd)
+
+        # Check required matchers
+        required_pre = {'Agent', 'Task'}
+        required_post = {'Write', 'Edit', 'NotebookEdit'}
+
+        pre_ok = required_pre.issubset(pre_matchers)
+        post_ok = required_post.issubset(post_matchers)
+
+        missing_files = []
+        for cmd in all_commands:
+            parts = cmd.split()
+            if parts:
+                for part in parts:
+                    if part.endswith(('.mjs', '.js', '.py', '.sh')):
+                        if not Path(part).exists():
+                            missing_files.append(part)
+                        break
+
+        if not (pre_ok and post_ok):
+            missing = []
+            if not pre_ok:
+                missing.append(f"PreToolUse: {required_pre - pre_matchers}")
+            if not post_ok:
+                missing.append(f"PostToolUse: {required_post - post_matchers}")
+            return Check('hooks', 'FAIL', f'missing matchers: {"; ".join(missing)}', True)
+        elif missing_files:
+            return Check('hooks', 'FAIL', f'missing files: {missing_files}', True)
+        else:
+            return Check('hooks', 'OK', None, False)
+    except Exception as e:
+        return Check('hooks', 'OK', '(error reading)', False)
+
+
+def check_brain():
+    """Check brain (git) status. Returns Check."""
+    try:
+        brain_path = paths['brain_root']
+        if not (brain_path / '.git').exists():
+            return Check('brain', 'OK', '(no git repo)', False)
+
+        # Get status
+        status_output = subprocess.run(
+            ['git', '-C', str(brain_path), 'status', '--porcelain'],
+            capture_output=True, text=True, timeout=5
+        ).stdout.strip()
+
+        status_lines = [l for l in status_output.split('\n') if l]
+
+        # Check ahead of current branch's upstream
+        try:
+            current_branch = subprocess.run(
+                ['git', '-C', str(brain_path), 'rev-parse', '--abbrev-ref', 'HEAD'],
+                capture_output=True, text=True, timeout=5
+            ).stdout.strip()
+        except:
+            current_branch = 'HEAD'
+
+        ahead_output = subprocess.run(
+            ['git', '-C', str(brain_path), 'rev-list', '--left-only', '--count', f'{current_branch}@{{u}}...{current_branch}'],
+            capture_output=True, text=True, timeout=5
+        ).stdout.strip()
+
+        try:
+            ahead_count = int(ahead_output) if ahead_output else 0
+        except:
+            ahead_count = 0
+
+        if ahead_count > 0:
+            return Check('brain', 'FAIL', f'ahead:{ahead_count}', True)
+        elif status_lines:
+            return Check('brain', 'WARN', f'{len(status_lines)} uncommitted', False)
+        else:
+            return Check('brain', 'OK', None, False)
+    except Exception as e:
+        return Check('brain', 'OK', '(error checking)', False)
+
+
+def check_beats():
+    """Check heartbeats. Returns Check."""
+    try:
+        heartbeat_results = []
+
+        # Watchdog heartbeat
+        try:
+            watchdog_beat = paths['state_root'] / '.watchdog-heartbeat'
+            if watchdog_beat.exists():
+                epoch_time = float(watchdog_beat.read_text().strip())
+                age = datetime.now().timestamp() - epoch_time
+                if age > 300:
+                    heartbeat_results.append(('watchdog', 'stale', int(age)))
+                else:
+                    heartbeat_results.append(('watchdog', 'ok', int(age)))
+            else:
+                heartbeat_results.append(('watchdog', 'missing', None))
+        except Exception as e:
+            heartbeat_results.append(('watchdog', 'n/a', None))
+
+        # Orchestration monitor heartbeat
+        try:
+            monitor_beat = paths['state_root'] / '.monitor-heartbeat'
+            if monitor_beat.exists():
+                epoch_time = float(monitor_beat.read_text().strip())
+                age = datetime.now().timestamp() - epoch_time
+                if age > 3600:
+                    heartbeat_results.append(('monitor', 'stale', int(age)))
+                else:
+                    heartbeat_results.append(('monitor', 'ok', int(age)))
+            else:
+                heartbeat_results.append(('monitor', 'missing', None))
+        except Exception as e:
+            heartbeat_results.append(('monitor', 'n/a', None))
+
+        # Determine beats status
+        beats_ok = all(status not in ('error', 'stale') for _, status, _ in heartbeat_results)
+        beats_stale = any(status == 'stale' for _, status, _ in heartbeat_results)
+        beats_all_na = all(status == 'n/a' for _, status, _ in heartbeat_results)
+
+        if beats_all_na:
+            return Check('beats', 'OK', '(n/a)', False)
+        elif not beats_ok:
+            details = '; '.join(f'{name}:{status}' for name, status, _ in heartbeat_results)
+            return Check('beats', 'FAIL', details, True)
+        elif beats_stale:
+            details = '; '.join(f'{name}:{status}' for name, status, _ in heartbeat_results)
+            return Check('beats', 'WARN', details, False)
+        else:
+            return Check('beats', 'OK', None, False)
+    except Exception as e:
+        return Check('beats', 'OK', '(n/a)', False)
+
+
+def check_decisions():
+    """Check decisions/inbox counts. Returns Check."""
+    try:
+        pending_count = 0
+        inbox_count = 0
+
+        try:
+            pending_path = paths['brain_root'] / 'plans' / 'PENDING-DECISIONS.md'
+            if pending_path.exists():
+                content = pending_path.read_text()
+                for line in content.split('\n'):
+                    line = line.strip()
+                    if line.startswith('- [ ]') or (line.startswith('-') and '[' not in line and line):
+                        pending_count += 1
+        except Exception:
+            pass
+
+        try:
+            inbox_path = paths['state_root'] / 'ui-inbox.md'
+            if inbox_path.exists():
+                content = inbox_path.read_text()
+                for line in content.split('\n'):
+                    if '- [' in line and ']' in line:
+                        inbox_count += 1
+        except Exception:
+            pass
+
+        details = f'{pending_count} pending'
+        if inbox_count > 0:
+            details += f',{inbox_count} inbox'
+
+        return Check('decisions', 'OK', details, False)
+    except Exception as e:
+        return Check('decisions', 'OK', '0 pending', False)
+
+
+def check_scanner():
+    """Check secret scanner. Returns Check."""
+    try:
+        scanner_path = paths['scripts_root'] / 'secret_scan.py'
+        if not scanner_path.exists():
+            return Check('scanner', 'OK', 'n/a', False)
+
+        result = subprocess.run(
+            [sys.executable, str(scanner_path), '--staged'],
+            capture_output=True, text=True, timeout=30,
+            cwd=str(paths['aesop_root'])
+        )
+
+        # Scanner exit 0 = clean, 1 = findings, 2 = usage error
+        if result.returncode == 0:
+            return Check('scanner', 'OK', None, False)
+        elif result.returncode == 1:
+            # Findings detected
+            return Check('scanner', 'FAIL', 'findings detected', True)
+        else:
+            return Check('scanner', 'OK', 'n/a', False)
+    except Exception as e:
+        return Check('scanner', 'OK', 'n/a', False)
+
+
+def run_checks():
+    """Run all health checks and return results."""
+    results = []
+
+    for check_fn in [check_hooks, check_brain, check_beats, check_decisions, check_scanner]:
+        result = check_fn()
+        if result:
+            results.append(result)
+
+    return results
+
+
+def format_output(results):
+    """Format results into the summary line and optional bullets."""
+    # Build status
+    has_fail = any(r.is_fail for r in results)
+    has_warn = any(r.status == 'WARN' for r in results)
+
+    if has_fail:
+        overall = 'FAIL'
+        exit_code = 1
+    elif has_warn:
+        overall = 'DEGRADED'
+        exit_code = 0
+    else:
+        overall = 'OK'
+        exit_code = 0
+
+    # Build detail strings for each check
+    check_details = []
+    for result in results:
+        if result.status in ('OK', 'WARN'):
+            if result.name in ('decisions', 'scanner'):
+                check_details.append(f'{result.name}:{result.details}')
+            else:
+                check_details.append(f'{result.name}:ok')
+        elif result.status in ('FAIL', 'ERROR'):
+            if result.details:
+                check_details.append(f'{result.name}:{result.details}')
+            else:
+                check_details.append(f'{result.name}:fail')
+
+    summary_line = f'POWER-SELFTEST: {overall} — {" ".join(check_details)}'
+
+    # Build bullet points for non-OK items
+    bullets = []
+    for result in results:
+        if result.status not in ('OK',):
+            msg = f'- {result.name}: {result.details}' if result.details else f'- {result.name}'
+            bullets.append(msg)
+
+    output_lines = [summary_line]
+    output_lines.extend(bullets)
+
+    return '\n'.join(output_lines), exit_code
+
+
+def main():
+    results = run_checks()
+    output, exit_code = format_output(results)
+    print(output)
+    sys.exit(exit_code)
+
+
+if __name__ == '__main__':
+    main()