@jaguilar87/gaia 5.0.0-rc1

package/dist/gaia-ops/skills/skill-creation/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: skill-creation
+description: Use when creating a new skill, improving an existing skill, or deciding what a skill should contain and how it should be structured
+metadata:
+  user-invocable: false
+  type: technique
+---
+
+# Skill Creation
+
+## What is a skill?
+
+Injected procedural knowledge -- the "how" for agents. The agent brings identity and domain knowledge. The skill brings process and protocol. They never duplicate each other.
+
+## Step 1: Choose the type
+
+Type determines structure. Choose before writing anything.
+
+| Type | Purpose | When it applies |
+|------|---------|-----------------|
+| **Discipline** | Enforces rules the agent will rationalize around under pressure | command-execution, execution |
+| **Technique** | How to think about or approach a class of problem | investigation, approval |
+| **Reference** | Lookup tables, classifications, format specifications | security-tiers, fast-queries, git-conventions |
+| **Domain** | Project-specific patterns for a technical area | terraform-patterns, gitops-patterns |
+| **Protocol** | System operating contract -- state machines, mandatory formats | agent-protocol |
+
+## Step 2: Apply the type structure
+
+**Discipline:** Iron Law -> Mental Model -> Rules -> Traps -> Anti-patterns. Every trap you leave unnamed is a loophole.
+
+**Technique:** Overview (core principle + when to use) -> Process (numbered steps) -> Anti-patterns.
+
+**Reference:** Quick-scan table at top -> Examples -> Edge cases / special rules.
+
+**Domain:** Conventions (naming, structure) -> Examples/snippets -> Key rules -> links to reference files.
+
+**Protocol:** State machine / flow -> Mandatory format -> State transitions -> Error handling.
+
+## Step 3: Write for judgment, not compliance
+
+A rule without context ("ALWAYS do X") carries almost no weight in the LLM's reasoning -- the model has no reason to prioritize it over competing signals. An explanation with consequences carries enough weight to influence decisions even under pressure. Every line competes for attention; earn each one with reasoning the model can use.
+
+The test: for each rule, ask -- if the agent saw enough examples of this going wrong, would it reach the same conclusion? If yes, you are capturing genuine wisdom. If no, it needs more context.
+
+For detailed guidance on tone by type (discipline, technique, domain, reference, protocol) and connection to the gaia-patterns design philosophy, see `reference.md`.
+
+## Step 4: Write the description field
+
+The description determines when the agent reads the skill. It contains **triggering conditions only** -- describing the process causes the agent to follow the description and skip reading the content.
+
+```yaml
+# Bad -- summarizes process, agent skips content
+description: Defensive command execution - timeout protection, pipe avoidance, safe shell patterns
+
+# Good -- triggering conditions only
+description: Use when executing any bash command, cloud CLI, or shell operation
+```
+
+## Step 5: Respect the line budget
+
+| Injection method | Budget | Reason |
+|-----------------|--------|--------|
+| Frontmatter (always loaded) | < 100 lines | Loaded on every agent call |
+| On-demand (read from disk) | < 500 lines | Loaded only when explicitly needed |
+
+Heavy reference material -> `reference.md` (on-demand). Concrete examples -> `examples.md`. Executable tools -> `scripts/`.
+
+```
+skill-name/
+├── SKILL.md          <- main content (always loaded)
+├── reference.md      <- heavy docs (on-demand)
+├── examples.md       <- concrete examples (on-demand)
+└── scripts/          <- executable tools
+```
+
+## When to create vs update
+
+**Create new skill:** Distinct behavioral concern not covered by existing skills. Domain knowledge inline in an agent that applies to multiple agents.
+
+**Update existing skill:** Agent ignores a rule the skill already defines -> strengthen with traps. Skill is missing a type-appropriate section.
+
+**Put elsewhere:** Project-specific config -> CLAUDE.md or agent inline. Single-agent-only behavior -> keep inline. Knowledge the LLM covers well from training -> not needed.
+
+**When creating a new skill:** Also update `skills/README.md` to add the new skill to the index. Load Skill('readme-writing') to do this correctly.
+
+## Anti-Patterns
+
+- **Description summarizes process** -- agent follows the description and skips reading the skill body.
+- **Discipline without traps** -- agents rationalize around rules; every unnamed loophole gets used.
+- **Too generic** -- "be careful with commands" teaches nothing; skills need specific, concrete rules.
+- **Duplicates agent content** -- two sources of truth both become stale; pick one place.
+- **Single responsibility violated** -- if a skill covers two distinct behaviors, split it.

package/dist/gaia-ops/skills/skill-creation/reference.md

@@ -0,0 +1,29 @@
+# Skill Creation -- Reference
+
+Detailed guidance on writing style, tone by type, and design philosophy. Read on-demand when crafting or reviewing skill content.
+
+## Write for Judgment, Not Compliance
+
+A skill that says "ALWAYS do X" is a rule. Rules get skipped the moment the agent encounters a situation where X seems unnecessary. A skill that explains *what goes wrong when you skip X* forms judgment. Judgment holds even in situations the skill never anticipated.
+
+The test: for each rule or step you write, ask -- if the agent saw enough real examples of this going wrong, would it reach the same conclusion on its own? If yes, you're capturing genuine wisdom. If no, it's probably an arbitrary preference that needs more context before it can guide decisions.
+
+This is why the investigation skill doesn't say "INVESTIGATE FIRST. ALWAYS. NO EXCEPTIONS." It says: *"Every codebase is a record of accumulated decisions... The first 2-3 files you read define whether your solution fits or fights the project."* The agent understands the stakes. The behavior follows.
+
+Every line in a skill competes for weight in the LLM's reasoning. A rule without context carries almost no weight -- the model has no reason to prioritize it over competing signals. An explanation with consequences carries enough weight to influence decisions even under pressure. This is why conciseness matters: a verbose skill dilutes its own weight. Every line should earn its place by adding reasoning the model can use.
+
+## Tone by Type
+
+**Discipline** works best when the Iron Law is blunt and a reasoned paragraph follows explaining what breaks when you violate it. Command-execution's mental model ("When you reach for a pipe, you have not looked for the flag yet") does more work than a dozen capitalized warnings because it reframes the decision point itself.
+
+**Technique** should read like a mentor sharing experience. Not "do step 1, step 2, step 3" but "when you encounter X, the thing that matters most is Y, because Z." The agent needs to internalize the priority, not memorize the sequence.
+
+**Domain** skills guide discovery of the project's conventions, not dictate a generic structure. The codebase is the source of truth; the skill is a reference that helps the agent find and interpret what's already there.
+
+**Reference** is where tone matters least and accuracy matters most. Tables, classifications, format specs. Get the content right.
+
+**Protocol** needs precision in its state machines and formats, but transitions should explain why they exist. An agent that understands why REVIEW precedes IN_PROGRESS for T3 operations will handle edge cases the protocol didn't enumerate.
+
+## Connection to Design Philosophy
+
+The gaia-patterns Workflow Design Philosophy captures this directly: *"Be positive -- describe what to do, not what to avoid"* and *"Allow discovery -- agent reaches conclusions empirically."* These principles apply directly to skill writing. A skill full of prohibitions ("never do X", "do NOT do Y") trains avoidance, not understanding. A skill that describes the better path and explains why it's better trains judgment that generalizes.

package/dist/gaia-ops/skills/terraform-patterns/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: terraform-patterns
+description: Use when creating, modifying, or reviewing Terraform or Terragrunt configuration files
+metadata:
+  user-invocable: false
+  type: domain
+---
+
+# Terraform Patterns
+
+Project-specific conventions. Use values from your injected project-context — never hardcode project IDs, regions, or account identifiers.
+
+For HCL examples (remote state, component structure, labels, outputs), read `reference.md` in this directory.
+
+## Discover the Project's Organization
+
+Every project organizes Terraform differently. Before creating any
+file, discover how THIS project does it.
+
+1. **Find the modules directory.** Look for `tf_modules/`, `modules/`,
+   `terraform/`, or similar. The name varies — what matters is whether
+   reusable modules exist and where they live.
+2. **Read 2-3 existing terragrunt.hcl files.** Look at the `source =`
+   lines. Do they reference local modules? Registry modules? A mix?
+3. **Follow the majority pattern.** If 8 out of 10 components use
+   local module references, yours should too. Consistency with the
+   project matters more than what you'd choose on a greenfield.
+
+### Module vs Inline
+
+If the project has reusable modules for similar resource compositions
+(e.g., a cloud-sql module that composes instance + database + user +
+secrets), and your new resource follows a similar composition pattern,
+create a reusable module. If it's truly one-off glue with no reuse
+potential, inline is acceptable — but check first, because most
+projects lean one way.
+
+## Directory Structure (Reference)
+
+The structure below is a common starting point, not a prescription.
+If the codebase uses a different layout, follow the codebase.
+
+```
+terraform/
+└── [module-name]/
+    ├── main.tf        # Resource definitions
+    ├── variables.tf   # Input variables
+    ├── outputs.tf     # Output values (snake_case, with descriptions)
+    └── provider.tf    # Provider config (if module-level)
+
+features/infra/[env]/
+├── terragrunt.hcl           # Root: remote state config
+└── [component]/
+    └── terragrunt.hcl       # Component: inputs + dependency references
+```
+
+## Naming Convention
+
+| Resource | Pattern | Notes |
+|----------|---------|-------|
+| Network/VPC | `{app}-{env}-vpc` | From context: project + env |
+| Cluster | `{app}-{env}-cluster-{n}` | Match context cluster_name |
+| Database | `{app}-{env}-{engine}-instance` | Engine: postgres, mysql |
+| Secret | `{service}-secret` | Matches app service name |
+| Service Account | `{resource}-sa` | Scope: resource it serves |
+
+## Module Sourcing
+
+- **Local modules** (preferred for GCP): `../../../../../terraform//{module-name}`
+- **Registry modules** (preferred for AWS): `tfr:///terraform-aws-modules/{module}/aws?version=x.y.z`
+- **Always pin exact versions** — never `latest`, never unpinned
+
+## Key Rules
+
+1. **Prefer Terragrunt** — prefer `terragrunt` commands for all environment operations; raw `terraform` is acceptable for module development and testing only
+2. **Dependencies via blocks** — never hardcode IDs, always `dependency.x.outputs.y`
+3. **Version pinning** — exact versions for modules, `~>` for providers
+4. **Tags on everything** — all resources get the standard label block
+5. **snake_case outputs** — descriptive names with `description` field
+6. **mock_outputs on dependencies** — required for `validate` and `plan` to work offline
+
+## Reference Docs
+
+Use `WebFetch` when a resource or attribute is unknown or ambiguous. Do not use WebFetch to discover patterns — the codebase always wins over external docs.
+
+| Need | URL |
+|------|-----|
+| Google provider resources | `https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/{resource}` |
+| Terragrunt config blocks | `https://terragrunt.gruntwork.io/docs/reference/config-blocks-and-attributes` |

package/dist/gaia-ops/skills/terraform-patterns/reference.md

@@ -0,0 +1,93 @@
+# Terraform Patterns — HCL Reference
+
+Structural patterns for Terraform and Terragrunt. Cloud-agnostic — use values from project-context, never hardcode.
+
+For cloud-specific resource examples (VPCs, clusters, databases), discover patterns from the existing codebase using the `investigation` skill.
+
+---
+
+## Remote State (root terragrunt.hcl)
+
+```hcl
+remote_state {
+  backend = "gcs"                          # gcs | s3 | azurerm — from cloud_provider in context
+  config = {
+    bucket   = "{project_id}-terraform-state"
+    prefix   = "${path_relative_to_include()}/terraform.tfstate"
+    project  = "{project_id}"              # from project-context
+    location = "{primary_region}"          # from project-context
+  }
+}
+```
+
+## Component (terragrunt.hcl)
+
+```hcl
+include "root" { path = find_in_parent_folders() }
+terraform { source = "../../../../../terraform//{module-name}" }
+
+dependency "vpc" {
+  config_path = "../vpc"
+  mock_outputs = { network_id = "mock-network" }
+  mock_outputs_allowed_terraform_commands = ["validate", "plan"]
+}
+
+inputs = {
+  project_id = "{project_id}"              # from project-context
+  region     = "{primary_region}"          # from project-context
+  network_id = dependency.vpc.outputs.network_id
+}
+```
+
+## Required Labels
+
+Every resource must include:
+
+```hcl
+labels = {
+  environment = "{env}"                    # from project-context
+  managed_by  = "terraform"
+  project     = "{project_id}"            # from project-context
+}
+```
+
+## Outputs Pattern
+
+```hcl
+output "resource_id" {
+  description = "Description of what this output represents"
+  value       = resource_type.name.id
+}
+```
+
+Always: snake_case name, non-empty description, no sensitive values unless `sensitive = true`.
+
+## Module Sourcing
+
+```hcl
+# Local module (GCP preferred)
+terraform { source = "../../../../../terraform//{module-name}" }
+
+# Registry module (AWS preferred)
+terraform { source = "tfr:///terraform-aws-modules/{module}/aws?version=x.y.z" }
+```
+
+Always pin exact versions — never `latest`, never unpinned.
+
+## State Operations
+
+```bash
+terragrunt state list
+terragrunt state show {resource_type}.{name}
+terragrunt import {resource_type}.{name} {live_id}
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| State lock | Check state backend lock table, wait or force-unlock with caution |
+| Module not found | Run `terragrunt init` |
+| Dependency cycle | Review dependency `config_path` declarations |
+| Mock outputs mismatch | Update `mock_outputs` to match actual output types |
+| Plan shows unexpected destroy | Check for naming drift between code and live state |

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

@@ -0,0 +1,9 @@
+"""gaia-ops tools namespace package.
+
+Marking ``tools`` as a regular package ensures pytest's rootdir discovery
+resolves to the repo root for both ``tests/`` and ``tools/scan/tests/``
+during full-suite collection. Without this file, pytest walks up from
+``tools/scan/tests/__init__.py`` to ``tools/`` (no ``__init__.py``) and
+uses that as the package root, which makes ``from tools.scan...`` imports
+fail at collection time.
+"""

package/dist/gaia-ops/tools/agentic-loop/decide-status.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""
+decide-status.py
+
+Mechanically decide what to do based on numbers alone.  No LLM judgment.
+
+Usage:
+    python3 decide-status.py \
+        --current 94.5 \
+        --best 92.0 \
+        --threshold 98 \
+        --direction higher \
+        --consecutive-discards 2 \
+        --pivot-count 1
+
+Output JSON:
+    {
+      "decision": "keep",
+      "reason": "Metric improved from 92.0 to 94.5",
+      "improved": true,
+      "gap_remaining": 3.5
+    }
+
+Decision precedence (evaluated top-to-bottom, first match wins):
+  1. pivot_count >= 3                          → stop
+  2. consecutive_discards >= 5                 → pivot   (also a discard)
+  3. consecutive_discards >= 3                 → refine  (also a discard)
+  4. current meets or passes threshold         → threshold_reached
+  5. current improved vs best (per direction)  → keep
+  6. current same or worse                     → discard
+
+Exit codes:
+  0  success (decision emitted as JSON)
+  1  invalid input
+"""
+
+import argparse
+import json
+import sys
+
+
+Decision = str  # type alias for readability
+
+
+def _is_improved(current: float, best: float, direction: str) -> bool:
+    """Return True if *current* is strictly better than *best* per direction."""
+    if direction == "higher":
+        return current > best
+    return current < best  # lower is better
+
+
+def _threshold_reached(current: float, threshold: float, direction: str) -> bool:
+    """Return True if *current* has met or surpassed *threshold*."""
+    if direction == "higher":
+        return current >= threshold
+    return current <= threshold
+
+
+def _gap_remaining(current: float, threshold: float, direction: str) -> float:
+    """Absolute gap between current value and threshold."""
+    if direction == "higher":
+        return max(0.0, threshold - current)
+    return max(0.0, current - threshold)
+
+
+def decide(
+    current: float,
+    best: float,
+    threshold: float,
+    direction: str,
+    consecutive_discards: int,
+    pivot_count: int,
+) -> dict:
+    """Pure function: return decision dict from numeric inputs."""
+
+    gap = _gap_remaining(current, threshold, direction)
+    improved = _is_improved(current, best, direction)
+
+    # --- Precedence 1: hard stop on too many pivots ---
+    if pivot_count >= 3:
+        return {
+            "decision": "stop",
+            "reason": f"pivot_count={pivot_count} has reached the maximum of 3; halting loop",
+            "improved": improved,
+            "gap_remaining": gap,
+        }
+
+    # --- Precedence 2 & 3: discard streak escalations ---
+    # Evaluated before threshold/keep so an ongoing failing streak is flagged
+    # even if the current run happens to reach the threshold.
+    if consecutive_discards >= 5:
+        return {
+            "decision": "pivot",
+            "reason": (
+                f"consecutive_discards={consecutive_discards} >= 5; "
+                "strategy is not working, force a pivot"
+            ),
+            "improved": improved,
+            "gap_remaining": gap,
+        }
+
+    if consecutive_discards >= 3:
+        return {
+            "decision": "refine",
+            "reason": (
+                f"consecutive_discards={consecutive_discards} >= 3; "
+                "current approach needs refinement before continuing"
+            ),
+            "improved": improved,
+            "gap_remaining": gap,
+        }
+
+    # --- Precedence 4: threshold reached ---
+    if _threshold_reached(current, threshold, direction):
+        return {
+            "decision": "threshold_reached",
+            "reason": (
+                f"current={current} {'≥' if direction == 'higher' else '≤'} "
+                f"threshold={threshold}; goal achieved"
+            ),
+            "improved": improved,
+            "gap_remaining": 0.0,
+        }
+
+    # --- Precedence 5 & 6: standard keep/discard ---
+    if improved:
+        return {
+            "decision": "keep",
+            "reason": f"Metric improved from {best} to {current}",
+            "improved": True,
+            "gap_remaining": gap,
+        }
+
+    return {
+        "decision": "discard",
+        "reason": f"Metric did not improve (current={current}, best={best})",
+        "improved": False,
+        "gap_remaining": gap,
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Compute the next agentic-loop decision from metric numbers only.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Decisions:
+  keep               current improved vs best
+  discard            current same or worse
+  refine             3+ consecutive discards (improvement needed in approach)
+  pivot              5+ consecutive discards (strategy change required)
+  stop               3+ pivots already attempted
+  threshold_reached  current meets or surpasses the goal threshold
+
+Direction values:
+  higher   larger numbers are better  (e.g. accuracy, passing tests)
+  lower    smaller numbers are better (e.g. error rate, latency ms)
+        """,
+    )
+    parser.add_argument("--current", required=True, type=float, help="Metric value for the current run")
+    parser.add_argument("--best", required=True, type=float, help="Best metric seen so far (from state.json)")
+    parser.add_argument("--threshold", required=True, type=float, help="Target threshold to reach")
+    parser.add_argument(
+        "--direction",
+        required=True,
+        choices=["higher", "lower"],
+        help="Whether higher or lower values are better",
+    )
+    parser.add_argument(
+        "--consecutive-discards",
+        required=True,
+        type=int,
+        metavar="N",
+        help="Number of consecutive discard outcomes so far (from state.json)",
+    )
+    parser.add_argument(
+        "--pivot-count",
+        required=True,
+        type=int,
+        metavar="N",
+        help="Number of pivots executed so far (from state.json)",
+    )
+    args = parser.parse_args()
+
+    # --- Input validation ---
+    errors = []
+    if args.consecutive_discards < 0:
+        errors.append("--consecutive-discards must be >= 0")
+    if args.pivot_count < 0:
+        errors.append("--pivot-count must be >= 0")
+
+    if errors:
+        for err in errors:
+            print(f"error: {err}", file=sys.stderr)
+        sys.exit(1)
+
+    result = decide(
+        current=args.current,
+        best=args.best,
+        threshold=args.threshold,
+        direction=args.direction,
+        consecutive_discards=args.consecutive_discards,
+        pivot_count=args.pivot_count,
+    )
+
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/dist/gaia-ops/tools/agentic-loop/parse-metric.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""
+parse-metric.py
+
+Read stdout from eval_command and extract METRIC lines.
+
+Usage:
+    echo "output" | python3 parse-metric.py --metric accuracy
+    python3 parse-metric.py --metric accuracy --file /tmp/eval-output.txt
+
+Input lines must match: METRIC {name}={number}
+Output: JSON to stdout with metric name, numeric value, and raw line.
+"""
+
+import argparse
+import json
+import re
+import sys
+from typing import Optional
+
+
+METRIC_PATTERN = re.compile(r"^METRIC\s+(\w+)=([\d.]+)\s*$")
+
+
+def parse_lines(lines: list[str]) -> list[dict]:
+    """Extract all METRIC entries from a sequence of lines."""
+    results = []
+    for line in lines:
+        stripped = line.rstrip("\n")
+        match = METRIC_PATTERN.match(stripped)
+        if match:
+            name = match.group(1)
+            raw_value = match.group(2)
+            # Preserve int vs float from the source text.
+            value: int | float
+            if "." in raw_value:
+                value = float(raw_value)
+            else:
+                value = int(raw_value)
+            results.append(
+                {
+                    "metric": name,
+                    "value": value,
+                    "raw_line": stripped,
+                }
+            )
+    return results
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Extract METRIC lines from eval_command output.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  echo "METRIC accuracy=94.5" | python3 parse-metric.py --metric accuracy
+  python3 parse-metric.py --metric passing_tests --file /tmp/out.txt
+  python3 parse-metric.py --file /tmp/out.txt          # returns all metrics
+        """,
+    )
+    parser.add_argument(
+        "--metric",
+        metavar="NAME",
+        help="Return only this named metric (case-sensitive). Exits 1 if not found.",
+    )
+    parser.add_argument(
+        "--file",
+        metavar="PATH",
+        help="Read from file instead of stdin.",
+    )
+    args = parser.parse_args()
+
+    # --- Read input ---
+    try:
+        if args.file:
+            with open(args.file, "r") as fh:
+                lines = fh.readlines()
+        else:
+            lines = sys.stdin.readlines()
+    except OSError as exc:
+        print(f"error: cannot read input: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    # --- Parse ---
+    all_metrics = parse_lines(lines)
+
+    if args.metric:
+        # Filter to the requested metric name.
+        matches = [m for m in all_metrics if m["metric"] == args.metric]
+        if not matches:
+            print(
+                f"error: metric '{args.metric}' not found in input",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        # Return the last occurrence if there are duplicates.
+        result = matches[-1]
+    else:
+        # Return all metrics as a list when no --metric filter is given.
+        result = all_metrics  # type: ignore[assignment]
+
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()