@jaguilar87/gaia 5.0.0-rc1

package/hooks/modules/evidence/loader.py

@@ -0,0 +1,126 @@
+"""
+Brief frontmatter loader.
+
+Contract:
+    load_acs(brief_path: Path) -> list[Evidence]
+
+Evidence fields:
+    id: str              # "AC-1", "AC-2", ...
+    description: str
+    type: str            # command | url | playwright | artifact | metric
+    shape: dict          # type-specific
+    artifact: str        # relative artifact path
+
+Exceptions:
+    InvalidBriefFrontmatter -- YAML parse error or missing '---' markers.
+    UnknownEvidenceType     -- evidence.type outside the allowed set.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+_ALLOWED_EVIDENCE_TYPES = frozenset({
+    "command",
+    "url",
+    "playwright",
+    "artifact",
+    "metric",
+})
+
+
+class InvalidBriefFrontmatter(Exception):
+    """Raised when the brief has no frontmatter or the YAML block is malformed."""
+
+
+class UnknownEvidenceType(Exception):
+    """Raised when evidence.type is not in the allowed set."""
+
+
+@dataclass
+class Evidence:
+    """One acceptance criterion with its evidence spec."""
+
+    id: str
+    description: str
+    type: str
+    shape: dict
+    artifact: str
+
+
+def _extract_frontmatter(text: str) -> dict:
+    """Parse the YAML block between two '---' markers at the top of `text`.
+
+    Raises InvalidBriefFrontmatter when markers are absent or YAML is malformed.
+    """
+    lines = text.splitlines(keepends=True)
+    if not lines or lines[0].rstrip() != "---":
+        raise InvalidBriefFrontmatter("Brief is missing opening '---' marker")
+
+    # Find the closing '---' on its own line.
+    closing_index = None
+    for i in range(1, len(lines)):
+        if lines[i].rstrip() == "---":
+            closing_index = i
+            break
+    if closing_index is None:
+        raise InvalidBriefFrontmatter("Brief is missing closing '---' marker")
+
+    yaml_block = "".join(lines[1:closing_index])
+    try:
+        parsed = yaml.safe_load(yaml_block)
+    except yaml.YAMLError as exc:
+        raise InvalidBriefFrontmatter(f"Invalid YAML in frontmatter: {exc}") from exc
+
+    if parsed is None:
+        return {}
+    if not isinstance(parsed, dict):
+        raise InvalidBriefFrontmatter(
+            f"Frontmatter must be a mapping, got {type(parsed).__name__}"
+        )
+    return parsed
+
+
+def load_acs(brief_path: Path) -> list[Evidence]:
+    """Parse `brief_path` and return its acceptance_criteria as Evidence objects."""
+    text = Path(brief_path).read_text(encoding="utf-8")
+    frontmatter = _extract_frontmatter(text)
+
+    raw_acs: Any = frontmatter.get("acceptance_criteria")
+    if raw_acs is None:
+        return []
+    if not isinstance(raw_acs, list):
+        raise InvalidBriefFrontmatter(
+            "acceptance_criteria must be a list"
+        )
+
+    evidences: list[Evidence] = []
+    for entry in raw_acs:
+        if not isinstance(entry, dict):
+            raise InvalidBriefFrontmatter(
+                "Each acceptance_criteria entry must be a mapping"
+            )
+
+        ev_spec = entry.get("evidence") or {}
+        ev_type = ev_spec.get("type", "")
+        if ev_type not in _ALLOWED_EVIDENCE_TYPES:
+            raise UnknownEvidenceType(
+                f"Unknown evidence type: {ev_type!r} "
+                f"(allowed: {sorted(_ALLOWED_EVIDENCE_TYPES)})"
+            )
+
+        shape = ev_spec.get("shape") or {}
+        evidences.append(
+            Evidence(
+                id=str(entry.get("id", "")),
+                description=str(entry.get("description", "")),
+                type=ev_type,
+                shape=dict(shape) if isinstance(shape, dict) else {},
+                artifact=str(entry.get("artifact", "")),
+            )
+        )
+    return evidences

package/hooks/modules/evidence/runner.py

@@ -0,0 +1,241 @@
+"""
+Command + artifact evidence runners.
+
+Contract:
+    run_command(shape, artifact_path) -> EvidenceResult
+    run_artifact(shape, artifact_path) -> EvidenceResult
+
+EvidenceResult:
+    passed: bool
+    output: str           # stdout + stderr
+    artifact_path: Path   # file written -- stdout + stderr + exit for commands,
+                          # raw target bytes for artifacts
+    error: Optional[str]  # "timeout" | "spawn_error" | "yaml: ..." | "json: ..." | None
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+
+from .assertions import evaluate
+
+
+_DEFAULT_TIMEOUT = 60
+_DEFAULT_EXPECT = "exit 0"
+
+
+@dataclass
+class EvidenceResult:
+    """Outcome of a single evidence run."""
+
+    passed: bool
+    output: str
+    artifact_path: Path
+    error: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# command
+# ---------------------------------------------------------------------------
+
+def _write_command_artifact(
+    artifact_path: Path,
+    stdout: str,
+    stderr: str,
+    exit_code: int,
+    error: Optional[str],
+) -> None:
+    """Persist stdout + stderr + exit code to the artifact file."""
+    artifact_path.parent.mkdir(parents=True, exist_ok=True)
+    parts = [
+        "=== stdout ===",
+        stdout.rstrip("\n"),
+        "=== stderr ===",
+        stderr.rstrip("\n"),
+        f"exit_code: {exit_code}",
+    ]
+    if error:
+        parts.append(f"error: {error}")
+    artifact_path.write_text("\n".join(parts) + "\n", encoding="utf-8")
+
+
+def _check_expect(expect: str, stdout: str, stderr: str, exit_code: int) -> bool:
+    """Evaluate the expect clause against the run output."""
+    if expect == "exit 0":
+        return exit_code == 0
+    if expect.startswith("substring "):
+        needle = expect[len("substring "):]
+        return needle in stdout or needle in stderr
+    # Unknown expect pattern -- fail closed.
+    return False
+
+
+def run_command(shape: dict, artifact_path: Path) -> EvidenceResult:
+    """Execute `shape.run` through bash and evaluate against `shape.expect`."""
+    run_cmd = shape.get("run", "")
+    expect = shape.get("expect", _DEFAULT_EXPECT)
+    timeout = int(shape.get("timeout", _DEFAULT_TIMEOUT))
+
+    try:
+        completed = subprocess.run(
+            ["bash", "-c", run_cmd],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        stdout = exc.stdout.decode("utf-8", errors="replace") if isinstance(
+            exc.stdout, (bytes, bytearray)
+        ) else (exc.stdout or "")
+        stderr = exc.stderr.decode("utf-8", errors="replace") if isinstance(
+            exc.stderr, (bytes, bytearray)
+        ) else (exc.stderr or "")
+        combined = stdout + stderr
+        _write_command_artifact(artifact_path, stdout, stderr, -1, "timeout")
+        return EvidenceResult(
+            passed=False,
+            output=combined,
+            artifact_path=artifact_path,
+            error="timeout",
+        )
+    except (FileNotFoundError, OSError) as exc:
+        msg = f"spawn_error: {exc}"
+        _write_command_artifact(artifact_path, "", msg, -1, "spawn_error")
+        return EvidenceResult(
+            passed=False,
+            output=msg,
+            artifact_path=artifact_path,
+            error="spawn_error",
+        )
+
+    stdout = completed.stdout or ""
+    stderr = completed.stderr or ""
+    combined = stdout + stderr
+    passed = _check_expect(expect, stdout, stderr, completed.returncode)
+
+    _write_command_artifact(
+        artifact_path, stdout, stderr, completed.returncode, None
+    )
+    return EvidenceResult(
+        passed=passed,
+        output=combined,
+        artifact_path=artifact_path,
+        error=None,
+    )
+
+
+# ---------------------------------------------------------------------------
+# artifact
+# ---------------------------------------------------------------------------
+
+def _select_target(path_str: str, select: Optional[str]) -> Path:
+    """Resolve the file to parse. If path is a directory and select=latest,
+    pick the newest file in it (by mtime). Otherwise return path as-is."""
+    p = Path(path_str)
+    if p.is_dir() and select == "latest":
+        candidates = [c for c in p.iterdir() if c.is_file()]
+        if not candidates:
+            return p  # Will fail downstream with a clear error.
+        candidates.sort(key=lambda c: c.stat().st_mtime, reverse=True)
+        return candidates[0]
+    return p
+
+
+def _parse_target(target: Path, kind: str) -> Any:
+    """Parse the target file according to `kind`. Returns the raw Python object."""
+    text = target.read_text(encoding="utf-8")
+    if kind == "yaml":
+        return yaml.safe_load(text)
+    if kind == "json":
+        return json.loads(text)
+    raise ValueError(f"Unknown artifact kind: {kind!r}")
+
+
+def _write_artifact_snapshot(
+    artifact_path: Path,
+    target: Path,
+    passed: bool,
+    error: Optional[str],
+) -> None:
+    """Persist a summary of the artifact check to the artifact file."""
+    artifact_path.parent.mkdir(parents=True, exist_ok=True)
+    parts = [
+        f"target: {target}",
+        f"passed: {passed}",
+    ]
+    if error:
+        parts.append(f"error: {error}")
+    try:
+        snippet = target.read_text(encoding="utf-8")
+        parts.append("=== content ===")
+        parts.append(snippet)
+    except OSError as exc:
+        parts.append(f"(unable to read target: {exc})")
+    artifact_path.write_text("\n".join(parts) + "\n", encoding="utf-8")
+
+
+def run_artifact(shape: dict, artifact_path: Path) -> EvidenceResult:
+    """Load a file, optionally pick latest from a directory, assert on its parsed
+    contents via the assertions DSL."""
+    path_str = shape.get("path", "")
+    kind = shape.get("kind", "")
+    select = shape.get("select")
+    assert_spec = shape.get("assert") or {}
+
+    target = _select_target(path_str, select)
+
+    try:
+        data = _parse_target(target, kind)
+    except yaml.YAMLError as exc:
+        err = f"yaml parse error: {exc}"
+        _write_artifact_snapshot(artifact_path, target, False, err)
+        return EvidenceResult(
+            passed=False,
+            output=err,
+            artifact_path=artifact_path,
+            error=err,
+        )
+    except json.JSONDecodeError as exc:
+        err = f"json parse error: {exc}"
+        _write_artifact_snapshot(artifact_path, target, False, err)
+        return EvidenceResult(
+            passed=False,
+            output=err,
+            artifact_path=artifact_path,
+            error=err,
+        )
+    except (OSError, ValueError) as exc:
+        err = f"artifact error: {exc}"
+        _write_artifact_snapshot(artifact_path, target, False, err)
+        return EvidenceResult(
+            passed=False,
+            output=err,
+            artifact_path=artifact_path,
+            error=err,
+        )
+
+    try:
+        passed = evaluate(assert_spec, data)
+    except ValueError as exc:
+        err = f"assert error: {exc}"
+        _write_artifact_snapshot(artifact_path, target, False, err)
+        return EvidenceResult(
+            passed=False,
+            output=err,
+            artifact_path=artifact_path,
+            error=err,
+        )
+
+    _write_artifact_snapshot(artifact_path, target, passed, None)
+    return EvidenceResult(
+        passed=passed,
+        output=f"target={target} passed={passed}",
+        artifact_path=artifact_path,
+        error=None,
+    )

package/hooks/modules/memory/__init__.py

@@ -0,0 +1,8 @@
+"""
+Memory module - Episodic memory capture for workflow episodes.
+
+Provides:
+- episode_writer: Workflow episode storage + session events (replaces episode_capture + session_state)
+"""
+
+__all__ = []

package/hooks/modules/memory/episode_writer.py

@@ -0,0 +1,216 @@
+"""
+Episodic memory capture for workflow episodes.
+
+Renamed from episode_capture.py. Absorbs get_session_events() from
+session_state.py directly into this module.
+
+Provides:
+    - write(): Store workflow as episodic memory
+    - get_session_events(): Read context.json, categorize events
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# Session events (absorbed from session_state.py)
+# ============================================================================
+
+def get_session_events() -> Dict[str, Any]:
+    """
+    Get critical events from active session context.
+
+    Returns:
+        Dict with categorized session events (commits, pushes, file_mods)
+    """
+    context_path = Path(".claude/session/active/context.json")
+
+    if not context_path.exists():
+        logger.debug("No session context found")
+        return {}
+
+    try:
+        with open(context_path, "r") as f:
+            context = json.load(f)
+
+        critical_events = context.get("critical_events", [])
+
+        if not critical_events:
+            return {}
+
+        commits = [
+            {
+                "hash": e.get("commit_hash", ""),
+                "message": e.get("commit_message", ""),
+                "timestamp": e.get("timestamp", "")
+            }
+            for e in critical_events
+            if e.get("event_type") == "git_commit" and e.get("commit_hash")
+        ]
+
+        pushes = [
+            {
+                "branch": e.get("branch", ""),
+                "timestamp": e.get("timestamp", "")
+            }
+            for e in critical_events
+            if e.get("event_type") == "git_push" and e.get("branch")
+        ]
+
+        file_mods = [
+            {
+                "count": e.get("modification_count", 0),
+                "timestamp": e.get("timestamp", "")
+            }
+            for e in critical_events
+            if e.get("event_type") == "file_modifications"
+        ]
+
+        result = {}
+        if commits:
+            result["git_commits"] = commits
+        if pushes:
+            result["git_pushes"] = pushes
+        if file_mods:
+            result["file_modifications"] = file_mods
+
+        if result:
+            logger.info(f"Found {len(critical_events)} session events")
+
+        return result
+
+    except Exception as e:
+        logger.warning(f"Failed to read session events: {e}")
+        return {}
+
+
+# ============================================================================
+# Episodic memory capture
+# ============================================================================
+
+def write(
+    metrics: Dict[str, Any],
+    anomalies: Optional[List[Dict[str, str]]] = None,
+    commands_executed: Optional[List[str]] = None,
+) -> Optional[str]:
+    """
+    Capture workflow as episodic memory.
+
+    Args:
+        metrics: Subagent metrics from workflow (includes plan_status, tier, task description)
+        anomalies: Detected anomalies from audit(), stored in episode context
+        commands_executed: List of commands extracted from EVIDENCE_REPORT
+
+    Returns:
+        Episode ID if stored, None otherwise
+    """
+    try:
+        import importlib.util
+
+        candidates = [
+            Path(__file__).parent.parent.parent.parent / "tools" / "memory" / "episodic.py",
+            Path(".claude/tools/memory/episodic.py"),
+        ]
+
+        episodic_module = None
+        for path in candidates:
+            if path.exists():
+                try:
+                    spec = importlib.util.spec_from_file_location("episodic", path)
+                    if spec and spec.loader:
+                        episodic_module = importlib.util.module_from_spec(spec)
+                        spec.loader.exec_module(episodic_module)
+                        logger.debug(f"Loaded episodic module from {path}")
+                        break
+                except Exception as e:
+                    logger.debug(f"Could not load episodic from {path}: {e}")
+                    continue
+
+        if not episodic_module:
+            logger.debug("Episodic memory module not found - skipping episode capture")
+            return None
+
+        memory = episodic_module.EpisodicMemory()
+
+        # Use the real task description captured from the transcript.
+        # metrics["prompt"] now holds the first user message (task description)
+        # rather than the generic "SubagentStop for <agent>".
+        prompt = metrics.get("prompt", "")
+        if not prompt:
+            prompt = f"Task for {metrics.get('agent', 'unknown')}"
+
+        subagent_type = metrics.get("agent", "unknown")
+        duration_seconds = metrics.get("duration_ms", 0) / 1000.0 if metrics.get("duration_ms") else None
+
+        # Determine outcome: prefer plan_status string, fall back to exit_code
+        plan_status = metrics.get("plan_status", "")
+        exit_code = metrics.get("exit_code", 0)
+        if plan_status:
+            if "COMPLETE" in plan_status:
+                outcome = "success"
+                success = True
+            elif "BLOCKED" in plan_status or "ERROR" in plan_status:
+                outcome = "failed"
+                success = False
+            else:
+                # IN_PROGRESS, REVIEW, NEEDS_INPUT -> partial
+                outcome = "partial"
+                success = None
+        elif exit_code == 0:
+            outcome = "success"
+            success = True
+        else:
+            outcome = "failed"
+            success = False
+
+        # Tags from metrics -- filter empty strings defensively
+        tags = [t for t in metrics.get("tags", []) if t]
+        if not tags and subagent_type and subagent_type != "unknown":
+            tags = [subagent_type]
+
+        # Enrich with session events and anomalies
+        session_events = get_session_events()
+        context = {"metrics": metrics}
+        if session_events:
+            context["session_events"] = session_events
+            logger.info(f"Enriched episode with session events: {list(session_events.keys())}")
+        if anomalies:
+            context["anomalies"] = anomalies
+            logger.info(f"Episode has {len(anomalies)} anomaly/anomalies")
+
+        # Include context anchor hit tracking if available
+        anchor_hits = metrics.get("context_anchor_hits")
+        if anchor_hits:
+            context["context_anchor_hits"] = anchor_hits
+            logger.info(
+                "Episode anchor hits: %d/%d (%.0f%%)",
+                anchor_hits.get("hits", 0),
+                anchor_hits.get("total_checked", 0),
+                anchor_hits.get("hit_rate", 0) * 100,
+            )
+
+        # P3 CLI compatibility fields
+        episode_id = memory.store_episode(
+            prompt=prompt,
+            clarifications={},
+            enriched_prompt=prompt,
+            context=context,
+            tags=tags,
+            outcome=outcome,
+            success=success,
+            duration_seconds=duration_seconds,
+            commands_executed=commands_executed or [],
+            workflow_metrics=metrics,
+        )
+
+        logger.info(f"Captured episode: {episode_id} (outcome: {outcome}, plan_status: {plan_status})")
+        return episode_id
+
+    except Exception as e:
+        logger.debug(f"Failed to capture episodic memory: {e}")
+        return None

package/hooks/modules/orchestrator/__init__.py

@@ -0,0 +1 @@
+# Orchestrator enforcement modules.