@jaguilar87/gaia 5.0.0-rc1

package/dist/gaia-ops/tools/agentic-loop/record-iteration.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""
+record-iteration.py
+
+Atomically update state.json and append to worklog.md after each iteration.
+The LLM never writes state.json directly — this script is the only writer.
+
+Usage:
+    python3 record-iteration.py \
+        --state-file state.json \
+        --worklog worklog.md \
+        --iteration 5 \
+        --metric-value 94.5 \
+        --status keep \
+        --description "Handle hyphenated verbs" \
+        --insight "delete-objects splits correctly" \
+        --next "Check camelCase+hyphen combined"
+
+    Optional flags:
+        --changed TEXT      What was modified (default: same as description)
+        --metric-name TEXT  Name of the metric recorded (default: "metric")
+
+Atomic write guarantee: state.json is written to a .tmp sibling, fsynced,
+then renamed over the original.  Either the full write lands or the original
+is untouched.
+"""
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+from datetime import datetime, timezone
+
+
+def load_state(path: str) -> dict:
+    """Load existing state.json or return an empty skeleton."""
+    if not os.path.exists(path):
+        return {
+            "iteration": 0,
+            "current_metric": None,
+            "best_metric": None,
+            "consecutive_discards": 0,
+            "pivot_count": 0,
+            "timestamp": None,
+            "status": None,
+        }
+    try:
+        with open(path, "r") as fh:
+            data = json.load(fh)
+        return data
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"error: cannot read state file '{path}': {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+def atomic_write_json(path: str, data: dict) -> None:
+    """Write *data* to *path* atomically using write-fsync-rename."""
+    dir_name = os.path.dirname(os.path.abspath(path))
+    # Use a temp file in the same directory so rename is on the same filesystem.
+    try:
+        fd, tmp_path = tempfile.mkstemp(dir=dir_name, suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w") as fh:
+                json.dump(data, fh, indent=2)
+                fh.write("\n")
+                fh.flush()
+                os.fsync(fh.fileno())
+            os.replace(tmp_path, path)
+        except Exception:
+            # Clean up orphaned temp file on failure.
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass
+            raise
+    except OSError as exc:
+        print(f"error: atomic write to '{path}' failed: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+def append_worklog(
+    path: str,
+    iteration: int,
+    description: str,
+    metric_name: str,
+    metric_value: float,
+    status: str,
+    changed: str,
+    insight: str,
+    next_step: str,
+    best_metric: float | None,
+) -> None:
+    """Append a structured run entry to worklog.md."""
+    status_upper = status.upper()
+
+    # Build result sentence
+    if best_metric is None:
+        result_text = f"{metric_name}={metric_value} (first run, no prior best)"
+    else:
+        comparison = (
+            f"improved from {best_metric}"
+            if metric_value > best_metric
+            else (
+                f"unchanged from {best_metric}"
+                if metric_value == best_metric
+                else f"regressed from {best_metric}"
+            )
+        )
+        result_text = f"{metric_name}={metric_value} ({comparison})"
+
+    entry = (
+        f"\n### Run {iteration}: {description} — {metric_name}={metric_value} ({status_upper})\n"
+        f"- **Changed:** {changed}\n"
+        f"- **Result:** {result_text}\n"
+        f"- **Insight:** {insight}\n"
+        f"- **Next:** {next_step}\n"
+    )
+
+    try:
+        with open(path, "a") as fh:
+            fh.write(entry)
+    except OSError as exc:
+        print(f"error: cannot append to worklog '{path}': {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Atomically record an agentic-loop iteration into state.json and worklog.md.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Status values:
+  keep     — metric improved; best is updated, consecutive_discards reset to 0
+  discard  — metric did not improve; consecutive_discards incremented
+  pivot    — forced strategy change (also increments pivot_count)
+  stop     — terminal state; loop should halt
+
+Exit codes:
+  0  success
+  1  error (message on stderr)
+        """,
+    )
+    parser.add_argument("--state-file", required=True, metavar="PATH", help="Path to state.json")
+    parser.add_argument("--worklog", required=True, metavar="PATH", help="Path to worklog.md (append-only)")
+    parser.add_argument("--iteration", required=True, type=int, help="Current iteration number (1-based)")
+    parser.add_argument("--metric-value", required=True, type=float, metavar="NUM", help="Numeric metric value this run")
+    parser.add_argument(
+        "--status",
+        required=True,
+        choices=["keep", "discard", "pivot", "stop"],
+        help="Outcome classification for this iteration",
+    )
+    parser.add_argument("--description", required=True, help="Short description of what changed this run")
+    parser.add_argument("--insight", required=True, help="What was learned from this run")
+    parser.add_argument("--next", required=True, dest="next_step", help="What to try in the next iteration")
+    parser.add_argument(
+        "--changed",
+        default=None,
+        metavar="TEXT",
+        help="What was specifically modified (defaults to --description)",
+    )
+    parser.add_argument(
+        "--metric-name",
+        default="metric",
+        metavar="NAME",
+        help="Name label for the metric (default: metric)",
+    )
+    args = parser.parse_args()
+
+    changed = args.changed if args.changed is not None else args.description
+
+    # --- Load current state ---
+    state = load_state(args.state_file)
+
+    prev_best: float | None = state.get("best_metric")
+
+    # --- Compute new state values ---
+    state["iteration"] = args.iteration
+    state["current_metric"] = args.metric_value
+    state["status"] = args.status
+    state["timestamp"] = datetime.now(tz=timezone.utc).isoformat()
+
+    if args.status == "keep":
+        # Keep: this run is better; promote to best.
+        state["best_metric"] = args.metric_value
+        state["consecutive_discards"] = 0
+    elif args.status == "discard":
+        # Do not update best; increment discard counter.
+        state["consecutive_discards"] = int(state.get("consecutive_discards") or 0) + 1
+    elif args.status == "pivot":
+        # Pivot: counts as a discard for streak purposes, but also advances pivot_count.
+        state["consecutive_discards"] = int(state.get("consecutive_discards") or 0) + 1
+        state["pivot_count"] = int(state.get("pivot_count") or 0) + 1
+    elif args.status == "stop":
+        # Terminal — no counter changes needed beyond recording.
+        pass
+
+    # --- Atomic write ---
+    atomic_write_json(args.state_file, state)
+
+    # --- Append worklog ---
+    append_worklog(
+        path=args.worklog,
+        iteration=args.iteration,
+        description=args.description,
+        metric_name=args.metric_name,
+        metric_value=args.metric_value,
+        status=args.status,
+        changed=changed,
+        insight=args.insight,
+        next_step=args.next_step,
+        best_metric=prev_best,
+    )
+
+    # Emit updated state summary for easy inspection.
+    print(json.dumps(state, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/dist/gaia-ops/tools/context/README.md

@@ -0,0 +1,132 @@
+# Context Module
+
+**Purpose:** Context provisioning and enrichment for agents
+
+## Overview
+
+This module manages the SSOT (Single Source of Truth) context that agents receive. It loads project configuration, filters by agent contract (defined in `config/context-contracts.json` + cloud extensions), and provides context to agents.
+It also classifies the task into generic Gaia surfaces, emits an `investigation_brief`, and injects `write_permissions` so agents receive deterministic cross-surface guidance and writable-section ownership, not just raw project data.
+
+## Core Functions
+
+### `load_project_context(path)`
+Loads the project-context.json file.
+
+```python
+from tools.context.context_provider import load_project_context
+context = load_project_context(Path(".claude/project-context/project-context.json"))
+```
+
+### `get_contract_context(project_context, agent_name, provider_contracts)`
+Gets the specific context needed for an agent based on its contract.
+
+```python
+from tools.context.context_provider import get_contract_context
+contract_context = get_contract_context(
+    project_context,
+    "terraform-architect",
+    provider_contracts
+)
+```
+
+### `get_context_update_contract(agent_name, provider_contracts)`
+Gets the readable/writable section contract that governs `CONTEXT_UPDATE`.
+
+```python
+from tools.context.context_provider import get_context_update_contract
+update_contract = get_context_update_contract("terraform-architect", provider_contracts)
+```
+
+### `load_provider_contracts(cloud_provider)`
+Loads cloud provider-specific agent contracts (GCP, AWS).
+
+```python
+from tools.context.context_provider import load_provider_contracts
+contracts = load_provider_contracts("gcp")
+```
+
+### `classify_surfaces(task, current_agent=...)`
+Classifies a task into one or more active Gaia surfaces using generic signals.
+
+```python
+from tools.context.surface_router import classify_surfaces
+routing = classify_surfaces("Investigate rollout failure after CI image change", current_agent="gitops-operator")
+```
+
+### `build_investigation_brief(task, agent_name, contract_context)`
+Builds the deterministic investigation brief injected into project context.
+
+```python
+from tools.context.surface_router import build_investigation_brief
+brief = build_investigation_brief("Review hook/skill drift", "gaia-system", contract_context={})
+```
+
+## Core Classes
+
+### `ContextSectionReader`
+Selective context loading for token optimization.
+
+```python
+from tools.context.context_section_reader import ContextSectionReader
+reader = ContextSectionReader(project_context)
+sections = reader.get_sections_for_agent("gitops-operator")
+```
+
+## Agent Contracts
+
+Each agent receives specific v2 context sections (defined in `config/context-contracts.json` v3):
+
+**terraform-architect:**
+- project_identity, stack, git, environment, infrastructure, orchestration
+- terraform_infrastructure, infrastructure_topology
+- operational_guidelines, cluster_details, application_services, architecture_overview
+
+**gitops-operator:**
+- project_identity, stack, git, environment, infrastructure, orchestration
+- gitops_configuration, cluster_details
+- operational_guidelines, application_services, architecture_overview
+
+**cloud-troubleshooter:**
+- project_identity, stack, git, environment, infrastructure, orchestration
+- cluster_details, infrastructure_topology, terraform_infrastructure
+- gitops_configuration, application_services, monitoring_observability, architecture_overview
+
+The same contracts are also exposed under `write_permissions`:
+- `readable_sections`
+- `writable_sections`
+
+Agents should use the injected `write_permissions`, not a hardcoded table in a skill,
+when deciding whether a `CONTEXT_UPDATE` is allowed.
+
+## Command Line Usage
+
+```bash
+python3 tools/context/context_provider.py terraform-architect "Create a VPC" \
+  --context-file .claude/project-context/project-context.json
+```
+
+## Files
+
+```
+context/
+├── __init__.py                # Public exports (re-exports from context_provider + surface_router)
+├── _paths.py                  # Shared config directory resolution (resolve_config_dir)
+├── context_provider.py        # Main context provisioning logic
+├── surface_router.py          # Surface classification + investigation brief
+├── context_section_reader.py  # Token-optimized context extraction
+├── context_selector.py        # Context selection logic
+├── context_compressor.py      # Context compression for token optimization
+├── context_lazy_loader.py     # Lazy loading for large contexts
+├── deep_merge.py              # Deep merge utility for contract merging
+├── pending_updates.py         # Pending context update management
+├── benchmark_context.py       # Performance benchmarking
+└── README.md
+```
+
+## See Also
+
+- `config/context-contracts.json` - Agent contracts (SSOT)
+- `config/cloud/gcp.json` - GCP-specific contract extensions
+- `config/cloud/aws.json` - AWS-specific contract extensions
+- `hooks/modules/context/context_writer.py` - Context write operations
+- `tests/tools/test_context_provider.py` - Test suite

package/dist/gaia-ops/tools/context/__init__.py

@@ -0,0 +1,42 @@
+"""
+Context Module: Context provisioning and enrichment
+
+This module provides context loading, filtering, and enrichment for agents.
+It manages the SSOT (Single Source of Truth) context contracts and ensures
+agents receive the necessary context for execution.
+
+Main functions:
+- load_project_context(): Load project context from JSON
+- get_contract_context(): Get context for an agent based on its contract
+- get_context_update_contract(): Get readable/writable write permissions
+- load_provider_contracts(): Load cloud provider-specific contracts
+"""
+
+from . import context_provider
+from .context_section_reader import ContextSectionReader
+
+# Re-export key functions for convenience
+from .context_provider import (
+    load_project_context,
+    get_contract_context,
+    get_context_update_contract,
+    load_provider_contracts,
+)
+from .surface_router import (
+    build_investigation_brief,
+    classify_surfaces,
+    load_surface_routing_config,
+)
+
+__all__ = [
+    "context_provider",  # module
+    "ContextSectionReader",
+    # Main functions
+    "load_project_context",
+    "get_contract_context",
+    "get_context_update_contract",
+    "load_provider_contracts",
+    "build_investigation_brief",
+    "classify_surfaces",
+    "load_surface_routing_config",
+]

package/dist/gaia-ops/tools/context/_paths.py

@@ -0,0 +1,20 @@
+"""Shared path resolution utilities for the context module."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def resolve_config_dir() -> Path:
+    """Resolve config directory from installed project or package checkout."""
+    installed_path = Path(".claude/config")
+    if installed_path.is_dir():
+        return installed_path
+
+    # context/ -> tools/ -> gaia-ops/
+    script_dir = Path(__file__).parent.parent.parent
+    package_path = script_dir / "config"
+    if package_path.is_dir():
+        return package_path
+
+    return Path(".claude/config")