@matt82198/aesop 0.2.0 → 0.3.1

package/tools/wave_preflight.py

@@ -38,9 +38,13 @@ import os
 import re
 import subprocess
 import sys
-import time
 from pathlib import Path
 
+# Ensure both tools and state_store are importable (sys.path fix for bootstrapping)
+repo_root = Path(__file__).parent.parent
+if str(repo_root) not in sys.path:
+    sys.path.insert(0, str(repo_root))
+
 try:
     from common import get_state_dir, check_heartbeat_staleness
 except ImportError:
@@ -51,6 +55,9 @@ try:
 except ImportError:
     from tools import halt
 
+# Import ReadAPI unconditionally - import failure is a loud error
+from state_store.read_api import ReadAPI
+
 
 def load_config(root_dir=None):
     """Load aesop.config.json from root, return dict (or {} if absent/bad)."""
@@ -134,8 +141,10 @@ def parse_orchestrator_status_phase(status_json_path):
 def check_orchestrator_status_freshness(status_json_path, threshold_s):
     """Check if orchestrator-status.json is fresh based on updated_at timestamp.
 
+    Uses ReadAPI (state_store.read_api) for all checks - single source of truth.
+
     Args:
-        status_json_path: Path to orchestrator-status.json
+        status_json_path: Path to orchestrator-status.json (or state dir)
         threshold_s: Staleness threshold in seconds
 
     Returns:
@@ -144,30 +153,38 @@ def check_orchestrator_status_freshness(status_json_path, threshold_s):
           age_s (int): Age in seconds (0 if file missing/unreadable)
           info (str or None): Descriptive message if stale/missing, None if fresh
     """
-    if not status_json_path.exists():
-        return True, 0, "orchestrator-status.json file missing"
-
     try:
-        data = json.loads(status_json_path.read_text(encoding="utf-8"))
-        updated_at = data.get("updated_at")
+        # Determine state_dir: if status_json_path is the status file, use its parent
+        status_path = Path(status_json_path)
+        if status_path.name == "orchestrator-status.json":
+            state_dir = status_path.parent
+        else:
+            state_dir = status_path
+
+        api = ReadAPI(str(state_dir))
+        status = api.read_orchestrator_status()
+        if status is None:
+            return True, 0, "orchestrator-status.json file missing or unreadable"
+
+        # Check freshness
+        updated_at = status.get("updated_at")
         if not updated_at:
             return True, 0, "orchestrator-status.json missing updated_at field"
 
-        # Parse ISO 8601 timestamp (handle both "Z" and "+00:00" timezone formats)
-        import datetime
-        # Normalize Z suffix to +00:00 for fromisoformat compatibility
+        # Parse ISO 8601 timestamp
+        from datetime import datetime, timezone
         normalized_ts = updated_at.replace("Z", "+00:00")
-        updated_dt = datetime.datetime.fromisoformat(normalized_ts)
+        updated_dt = datetime.fromisoformat(normalized_ts)
         timestamp = updated_dt.timestamp()
 
+        import time
         age_seconds = int(time.time()) - int(timestamp)
 
         # Check for far-future timestamp (clock skew beyond tolerance)
-        # More than 120s in the future is treated as stale, not clamped-to-fresh
         if age_seconds < -120:
             return True, 0, "orchestrator-status timestamp in future (clock skew)"
 
-        # Clamp small negative ages to 0 (normal clock skew recovery)
+        # Clamp small negative ages to 0
         age_seconds = max(0, age_seconds)
 
         if age_seconds >= threshold_s:
@@ -259,6 +276,201 @@ def can_import_secret_scan():
         return False, str(e)
 
 
+def scan_backlog_items(tracker_path, work_dir, ledger_path=None):
+    """Scan backlog items for risky conditions.
+
+    Analyzes todo items in tracker.json for:
+      (a) missing/empty owns_files (file ownership info)
+      (b) stale items (references to non-existent files)
+      (c) overlaps (two items owning same file)
+      (d) history signal (retry rate from ledger)
+
+    Args:
+        tracker_path: Path to state/tracker.json
+        work_dir: Working directory for resolving relative file paths
+        ledger_path: Optional path to ledger for history stats
+
+    Returns:
+        dict with structure:
+        {
+            "success": bool,
+            "items": [
+                {
+                    "id": str,
+                    "title": str,
+                    "flags": [{"type": str, "detail": str}, ...]
+                },
+                ...
+            ],
+            "ledger_stats": dict or None,
+            "summary": str
+        }
+    """
+    tracker_path = Path(tracker_path)
+    work_dir = Path(work_dir)
+    result = {
+        "success": True,
+        "items": [],
+        "ledger_stats": None,
+        "summary": ""
+    }
+
+    # Load tracker.json
+    try:
+        if not tracker_path.exists():
+            result["success"] = False
+            result["summary"] = f"tracker file not found: {tracker_path}"
+            return result
+
+        tracker_data = json.loads(tracker_path.read_text(encoding="utf-8"))
+        if not isinstance(tracker_data, dict) or "items" not in tracker_data:
+            result["success"] = False
+            result["summary"] = "tracker.json invalid: missing 'items' key"
+            return result
+
+        items = tracker_data.get("items", [])
+    except (json.JSONDecodeError, IOError) as e:
+        result["success"] = False
+        result["summary"] = f"tracker.json unreadable: {e}"
+        return result
+
+    # Filter to todo items only
+    todo_items = [
+        item for item in items
+        if isinstance(item, dict) and item.get("status") == "todo"
+    ]
+
+    # Build ownership map for overlap detection
+    ownership_map = {}  # file_path -> set of item_ids
+
+    # Process each todo item
+    for item in todo_items:
+        item_id = item.get("id", "unknown")
+        title = item.get("title", "")
+        flags = []
+
+        # Flag (a): Check for missing/empty owns_files
+        owns_files = item.get("owns_files", [])
+        if not owns_files or (isinstance(owns_files, list) and len(owns_files) == 0):
+            flags.append({
+                "type": "missing_ownership",
+                "detail": "Item has no owns_files; cannot dispatch safely"
+            })
+
+        # Flag (b): Check for stale items (files not found)
+        if owns_files and isinstance(owns_files, list):
+            for file_ref in owns_files:
+                file_path = work_dir / file_ref if not Path(file_ref).is_absolute() else Path(file_ref)
+                if not file_path.exists():
+                    flags.append({
+                        "type": "stale_reference",
+                        "detail": f"Referenced file not found: {file_ref}"
+                    })
+
+                # Track for overlap detection
+                file_key = str(file_path.resolve())
+                if file_key not in ownership_map:
+                    ownership_map[file_key] = set()
+                ownership_map[file_key].add(item_id)
+
+        if flags or owns_files:  # Only include items with flags or ownership info
+            result["items"].append({
+                "id": item_id,
+                "title": title,
+                "flags": flags
+            })
+
+    # Flag (c): Detect overlaps
+    for file_path, item_ids in ownership_map.items():
+        if len(item_ids) > 1:
+            for item_id in item_ids:
+                # Find the item and add overlap flag
+                for item_result in result["items"]:
+                    if item_result["id"] == item_id:
+                        overlapping_ids = sorted(item_ids - {item_id})
+                        item_result["flags"].append({
+                            "type": "ownership_overlap",
+                            "detail": f"File shared with items: {', '.join(overlapping_ids)}"
+                        })
+                        break
+
+    # Flag (d): Load ledger stats if provided
+    if ledger_path:
+        ledger_path = Path(ledger_path)
+        if ledger_path.exists():
+            try:
+                ledger_stats = _analyze_ledger(ledger_path)
+                result["ledger_stats"] = ledger_stats
+            except Exception as e:
+                result["ledger_stats"] = {"error": str(e), "data": "DATA-UNAVAILABLE"}
+        else:
+            result["ledger_stats"] = {"data": "DATA-UNAVAILABLE", "note": "ledger not found"}
+    else:
+        result["ledger_stats"] = {"data": "DATA-UNAVAILABLE", "note": "no ledger provided"}
+
+    # Summary
+    flagged_count = sum(1 for item in result["items"] if item["flags"])
+    result["summary"] = f"Scanned {len(todo_items)} todo items; {flagged_count} have risk flags"
+
+    return result
+
+
+def _analyze_ledger(ledger_path):
+    """Extract repair/retry statistics from ledger.
+
+    Returns:
+        dict with overall repair rate and stats
+    """
+    ledger_path = Path(ledger_path)
+    try:
+        content = ledger_path.read_text(encoding="utf-8")
+    except IOError:
+        return {"data": "DATA-UNAVAILABLE", "error": "unreadable"}
+
+    lines = content.split("\n")
+    entries = []
+
+    for line in lines:
+        # Skip header and separator lines
+        if not line.strip() or "---|" in line or not line.startswith("|"):
+            continue
+
+        # Parse markdown table row
+        cells = [c.strip() for c in line.split("|")[1:-1]]
+        if len(cells) < 7:
+            continue
+
+        # Skip header row (first cell is "ISO ts" or similar header name)
+        if cells[0] in ("ISO ts", "iso_ts") or cells[0].startswith("ISO"):
+            continue
+
+        try:
+            # Columns: ISO ts, agent_type, model, duration_sec, tokens_in, tokens_out, verdict, phase, wave
+            verdict = cells[6] if len(cells) > 6 else "OK"
+            phase = cells[7].strip() if len(cells) > 7 else None
+            entries.append({"verdict": verdict, "phase": phase})
+        except (ValueError, IndexError):
+            continue
+
+    if not entries:
+        return {"data": "DATA-UNAVAILABLE", "reason": "no ledger entries"}
+
+    # Calculate retry rate: entries with FAILED verdict / total
+    failed_count = sum(1 for e in entries if e.get("verdict") == "FAILED")
+    total_count = len(entries)
+    repair_count = sum(1 for e in entries if e.get("phase") == "repair")
+
+    retry_rate = failed_count / total_count if total_count > 0 else 0
+
+    return {
+        "total_entries": total_count,
+        "failed_count": failed_count,
+        "repair_count": repair_count,
+        "retry_rate": round(retry_rate, 3),
+        "data": "AVAILABLE"
+    }
+
+
 def run_checks(root_dir=None, state_dir=None, config=None):
     """Run all preflight checks.
 
@@ -447,6 +659,8 @@ def main(argv=None):
 
     root_dir = None
     state_dir = None
+    tracker_path = None
+    ledger_path = None
     output_format = "text"
 
     # Parse arguments
@@ -469,6 +683,22 @@ def main(argv=None):
         elif arg.startswith("--state-root="):
             state_dir = arg[len("--state-root="):]
             i += 1
+        elif arg == "--tracker":
+            i += 1
+            if i < len(argv):
+                tracker_path = argv[i]
+            i += 1
+        elif arg.startswith("--tracker="):
+            tracker_path = arg[len("--tracker="):]
+            i += 1
+        elif arg == "--ledger":
+            i += 1
+            if i < len(argv):
+                ledger_path = argv[i]
+            i += 1
+        elif arg.startswith("--ledger="):
+            ledger_path = arg[len("--ledger="):]
+            i += 1
         elif arg == "--json":
             output_format = "json"
             i += 1
@@ -487,25 +717,62 @@ def main(argv=None):
     else:
         state_dir = Path(state_dir)
 
-    result = run_checks(root_dir, state_dir, config)
+    # If --tracker provided, run backlog analysis instead of repo readiness checks
+    if tracker_path:
+        work_dir = root_dir  # Use root_dir as the working directory for file resolution
+        result = scan_backlog_items(tracker_path, work_dir, ledger_path)
 
-    if output_format == "json":
-        print(json.dumps(result, indent=2))
-    else:
-        # Text format: numbered list
-        print("Wave preflight checks:")
-        for i, check in enumerate(result["checks"], 1):
-            status = "PASS" if check["ok"] else "FAIL"
-            print(f"{i}. {check['name']}: {status}")
-            if check["detail"]:
-                print(f"   {check['detail']}")
-
-        if result["ready"]:
-            print("\nPASS: Ready for wave")
+        if output_format == "json":
+            print(json.dumps(result, indent=2))
         else:
-            print("\nFAIL: Not ready for wave (see failures above)")
+            # Text format: summary + items with flags
+            print(f"Backlog Preflight: {result['summary']}")
+            print()
+
+            if result["ledger_stats"]:
+                stats = result["ledger_stats"]
+                if stats.get("data") == "AVAILABLE":
+                    print(f"Ledger History: {stats['total_entries']} entries, "
+                          f"{stats['failed_count']} failed, "
+                          f"{stats['repair_count']} repairs, "
+                          f"retry rate: {stats['retry_rate']}")
+                else:
+                    print(f"Ledger History: DATA-UNAVAILABLE")
+                print()
+
+            if result["items"]:
+                print("Flagged Items:")
+                for item in result["items"]:
+                    if item["flags"]:
+                        print(f"  [{item['id']}] {item['title']}")
+                        for flag in item["flags"]:
+                            print(f"    - {flag['type']}: {flag['detail']}")
+            else:
+                print("No risky items detected.")
+
+        # Exit 0 always (advisory tool, never blocks)
+        return 0
+    else:
+        # Standard repo readiness checks
+        result = run_checks(root_dir, state_dir, config)
 
-    return 0 if result["ready"] else 1
+        if output_format == "json":
+            print(json.dumps(result, indent=2))
+        else:
+            # Text format: numbered list
+            print("Wave preflight checks:")
+            for i, check in enumerate(result["checks"], 1):
+                status = "PASS" if check["ok"] else "FAIL"
+                print(f"{i}. {check['name']}: {status}")
+                if check["detail"]:
+                    print(f"   {check['detail']}")
+
+            if result["ready"]:
+                print("\nPASS: Ready for wave")
+            else:
+                print("\nFAIL: Not ready for wave (see failures above)")
+
+        return 0 if result["ready"] else 1
 
 
 if __name__ == "__main__":

package/tools/wave_templates.py

@@ -29,7 +29,7 @@ import argparse
 import json
 import sys
 from pathlib import Path
-from typing import Dict, Any, List, Optional
+from typing import Dict, Any, List, Optional, Tuple
 
 # Presets directory (relative to this file's location).
 TOOLS_DIR = Path(__file__).resolve().parent
@@ -101,20 +101,29 @@ def instantiate_template(
     return manifest
 
 
-def validate_manifest(manifest: Dict[str, Any]) -> None:
+def validate_manifest(
+    manifest: Dict[str, Any],
+    allow_placeholders: bool = True,
+    require_testcmd: bool = True
+) -> None:
     """Validate manifest schema and invariants.
 
     Checks:
       - items array exists and is non-empty
-      - each item has required fields (slug, prompt, ownsFiles)
-      - no file ownership overlap
-      - no placeholder strings remain
+      - each item has required fields (slug, prompt, ownsFiles, and optionally testCmd)
+      - no file ownership overlap (per-manifest)
+      - optionally: no placeholder strings remain (for instantiated manifests)
 
     Args:
         manifest: the manifest dict to validate
+        allow_placeholders: if False, reject unsubstituted placeholders (default: True,
+                           for backward compatibility with presets). Set to False for
+                           instantiated manifests.
+        require_testcmd: if True, require testCmd field (default: True, since the wave
+                        engine needs it). Set to False to validate presets only.
 
     Raises:
-        ValueError: if validation fails
+        ValueError: if validation fails with detailed error per item
     """
     if "items" not in manifest:
         raise ValueError("Manifest missing 'items' array")
@@ -123,65 +132,160 @@ def validate_manifest(manifest: Dict[str, Any]) -> None:
     if not isinstance(items, list) or len(items) == 0:
         raise ValueError("'items' must be a non-empty list")
 
-    # Check required fields and validate structure.
-    required_fields = {"slug", "prompt", "ownsFiles"}
+    # Core required fields (always required).
+    required_core_fields = {"slug", "prompt", "ownsFiles"}
+    # Optional fields for instantiated manifests.
+    optional_fields = {"testCmd", "workDir"} if require_testcmd else set()
+    required_fields = required_core_fields | ({"testCmd"} if require_testcmd else set())
+
     owner_map = {}
     conflicts = []
+    errors = []
 
-    for item in items:
+    for item_idx, item in enumerate(items):
         if not isinstance(item, dict):
-            raise ValueError(f"Item must be a dict, got {type(item)}")
+            errors.append(f"Item {item_idx}: must be a dict, got {type(item)}")
+            continue
 
-        # Check required fields.
-        for field in required_fields:
+        # Check required core fields.
+        for field in required_core_fields:
             if field not in item:
-                raise ValueError(f"Item {item.get('slug', 'unknown')} missing '{field}'")
+                errors.append(f"Item {item_idx} ({item.get('slug', 'unknown')}): missing required field '{field}'")
+
+        # Check required testCmd if flag is set.
+        if require_testcmd and "testCmd" not in item:
+            errors.append(f"Item {item_idx} ({item.get('slug', 'unknown')}): missing required field 'testCmd'")
 
-        slug = item["slug"]
-        if not isinstance(slug, str) or not slug:
-            raise ValueError(f"Item slug must be non-empty string, got {slug}")
+        slug = item.get("slug")
+        if slug is not None:
+            if not isinstance(slug, str) or not slug:
+                errors.append(f"Item {item_idx}: slug must be non-empty string, got {slug}")
 
         # Check ownsFiles.
         owned_files = item.get("ownsFiles", [])
-        if not isinstance(owned_files, list) or not owned_files:
-            raise ValueError(f"Item {slug} must have non-empty ownsFiles list")
-
-        # Track file ownership.
+        if not isinstance(owned_files, list):
+            errors.append(f"Item {item_idx} ({slug}): ownsFiles must be a list")
+            continue
+        if len(owned_files) == 0:
+            errors.append(f"Item {item_idx} ({slug}): ownsFiles must be non-empty")
+            continue
+
+        # Track file ownership (within this manifest only).
         for f in owned_files:
             if f in owner_map:
                 conflicts.append((f, owner_map[f], slug))
             else:
                 owner_map[f] = slug
 
+    # Report all collected errors first.
+    if errors:
+        error_msg = "Manifest validation failed:\n  " + "\n  ".join(errors)
+        raise ValueError(error_msg)
+
     if conflicts:
-        raise ValueError(f"File ownership overlap: {conflicts}")
+        conflict_msg = "File ownership overlap (within manifest):\n  " + "\n  ".join(
+            [f"{f!r}: owned by both {o1!r} and {o2!r}" for f, o1, o2 in conflicts]
+        )
+        raise ValueError(conflict_msg)
+
+    # Check no placeholders remain (if instantiated manifest).
+    if not allow_placeholders:
+        manifest_str = json.dumps(manifest)
+        if "{project_name}" in manifest_str or "{base_dir}" in manifest_str:
+            raise ValueError("Manifest contains unsubstituted placeholders (not fully instantiated)")
+
 
-    # Check no placeholders remain.
-    manifest_str = json.dumps(manifest)
-    if "{project_name}" in manifest_str or "{base_dir}" in manifest_str:
-        raise ValueError("Manifest contains unsubstituted placeholders")
+def validate_presets(preset_names: List[str], output_json: bool = False) -> Tuple[bool, List[str]]:
+    """Validate one or more presets.
+
+    Args:
+        preset_names: list of preset names to validate (e.g., ["saas", "data", "library"])
+
+    Returns:
+        tuple (success: bool, errors: List[str])
+          - success is True if all presets validate clean
+          - errors is a list of formatted error messages per preset/item
+    """
+    errors = []
+    all_valid = True
+    results = {}
+
+    for preset_name in preset_names:
+        try:
+            preset = load_preset(preset_name)
+            # Validate the preset: allow placeholders (presets have them), require testCmd (wave engine needs it)
+            validate_manifest(preset, allow_placeholders=True, require_testcmd=True)
+            results[preset_name] = {"valid": True, "errors": []}
+            print(f"✓ {preset_name}: valid", file=sys.stderr)
+        except FileNotFoundError as e:
+            errors.append(f"✗ {preset_name}: {e}")
+            all_valid = False
+            results[preset_name] = {"valid": False, "errors": [str(e)]}
+        except ValueError as e:
+            errors.append(f"✗ {preset_name}: {e}")
+            all_valid = False
+            results[preset_name] = {"valid": False, "errors": [str(e)]}
+        except Exception as e:
+            errors.append(f"✗ {preset_name}: unexpected error: {e}")
+            all_valid = False
+            results[preset_name] = {"valid": False, "errors": [str(e)]}
+
+    if output_json:
+        print(json.dumps({"ok": all_valid, "templates": results}))
+    else:
+        # Print errors if any
+        for error in errors:
+            print(error, file=sys.stderr)
+
+    return all_valid, errors
 
 
 def main():
-    """CLI entry point: load preset and output resolved manifest."""
+    """CLI entry point: load preset, instantiate, validate, or validate presets."""
     parser = argparse.ArgumentParser(
-        description="Load and instantiate a wave manifest preset"
+        description="Wave manifest preset manager: load, instantiate, and validate presets"
+    )
+
+    # Create subparsers for different commands
+    subparsers = parser.add_subparsers(dest="command", help="command to run")
+
+    # Subcommand: validate
+    validate_parser = subparsers.add_parser(
+        "validate",
+        help="validate preset template(s) for completeness"
+    )
+    validate_parser.add_argument(
+        "--template",
+        choices=["saas", "data", "library", "all"],
+        default="all",
+        help="which preset(s) to validate (default: all)"
+    )
+    validate_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="output results in JSON format"
+    )
+
+    # Subcommand: instantiate
+    inst_parser = subparsers.add_parser(
+        "instantiate",
+        help="load and instantiate a preset manifest"
     )
-    parser.add_argument(
+    inst_parser.add_argument(
         "preset",
         help="preset name: saas, data, or library"
     )
-    parser.add_argument(
+    inst_parser.add_argument(
         "--project-name",
         required=True,
         help="project/app name (e.g., 'payment-api')"
     )
-    parser.add_argument(
+    inst_parser.add_argument(
         "--base-dir",
         required=True,
         help="base working directory (e.g., '/workspace/my-app')"
     )
-    parser.add_argument(
+    inst_parser.add_argument(
         "--output",
         default=None,
         help="output file (default: stdout)"
@@ -190,21 +294,42 @@ def main():
     args = parser.parse_args()
 
     try:
-        # Load and instantiate.
-        preset = load_preset(args.preset)
-        manifest = instantiate_template(preset, args.project_name, args.base_dir)
-
-        # Validate.
-        validate_manifest(manifest)
-
-        # Output.
-        output_json = json.dumps(manifest, indent=2)
-        if args.output:
-            output_path = Path(args.output)
-            output_path.write_text(output_json, encoding="utf-8")
-            print(f"Manifest written to {output_path}", file=sys.stderr)
+        if args.command == "validate":
+            # Validate preset(s)
+            if args.template == "all":
+                presets = ["saas", "data", "library"]
+            else:
+                presets = [args.template]
+
+            success, errors = validate_presets(presets, output_json=args.json)
+
+            if not success:
+                sys.exit(1)
+            else:
+                print(f"\nAll {len(presets)} preset(s) validated successfully.", file=sys.stderr)
+                sys.exit(0)
+
+        elif args.command == "instantiate":
+            # Instantiate preset
+            preset = load_preset(args.preset)
+            manifest = instantiate_template(preset, args.project_name, args.base_dir)
+
+            # Validate the instantiated manifest (disallow placeholders, require testCmd)
+            validate_manifest(manifest, allow_placeholders=False, require_testcmd=True)
+
+            # Output.
+            output_json = json.dumps(manifest, indent=2)
+            if args.output:
+                output_path = Path(args.output)
+                output_path.write_text(output_json, encoding="utf-8")
+                print(f"Manifest written to {output_path}", file=sys.stderr)
+            else:
+                print(output_json)
+
         else:
-            print(output_json)
+            # No command specified - print help
+            parser.print_help()
+            sys.exit(0)
 
     except Exception as e:
         print(f"Error: {e}", file=sys.stderr)