@jaguilar87/gaia 5.0.0-rc1

package/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/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/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/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/templates/README.md

@@ -0,0 +1,69 @@
+# Templates
+
+Templates are the reference files that Gaia uses to generate per-project configuration. They are not consumed by the Claude Code runtime — they are consumed by the install scripts in `bin/` and by organization administrators deploying managed policies. Think of this directory as the catalog of files that exist as skeletons, ready to be filled in during installation or deployed verbatim as a policy.
+
+There are two audiences for this directory, and they do not overlap. The first is the individual developer installing Gaia into their project — their scanner reads templates during `npx gaia-scan` and generates the files their project needs. The second is the enterprise administrator — they take `managed-settings.template.json` and deploy it as a managed policy via the Claude.ai Admin Console or by placing it at `/etc/claude-code/managed-settings.json` on managed workstations.
+
+Keeping these files here, rather than embedding them in `bin/gaia-scan.py`, means policies and skeletons can be audited and customized without touching executable code. An admin can diff `managed-settings.template.json` against a previous version. A developer can read `governance.template.md` (when present) before letting the scanner interpolate it.
+
+## Cuándo se activa
+
+This component does not activate in the runtime Claude Code pipeline. Templates are consumed only by install-time tooling and by administrators deploying policies out-of-band.
+
+**When each template is consumed:**
+
+```
+Individual developer runs: npx gaia-scan
+        |
+bin/gaia-scan.py reads templates/ directory
+        |
+For each template:
+  managed-settings.template.json   -> NOT consumed by gaia-scan (enterprise only)
+  governance.template.md           -> interpolated with project-context.json values
+  (any other *.template.* files)   -> interpolated or copied per install logic
+        |
+Generated files written to project .claude/ or project root
+```
+
+```
+Enterprise admin deploys managed policy
+        |
+Admin copies templates/managed-settings.template.json
+        |
+Deploys to Claude.ai Admin Console
+   OR writes to /etc/claude-code/managed-settings.json (Linux managed workstations)
+        |
+Managed settings take highest precedence — cannot be overridden by user or project
+```
+
+## Qué hay aquí
+
+```
+templates/
+├── managed-settings.template.json   # Enterprise reference — deployed by admin, not gaia-scan
+└── README.md
+```
+
+Currently only `managed-settings.template.json` ships in this directory. A `governance.template.md` is referenced by some Gaia docs as generated during `gaia-scan` setup, but the file is not present here in source — it may live in a future location or be inlined in the scanner script.
+
+## Convenciones
+
+**Audience per file:**
+
+| File | Audience | Consumed by | Trigger |
+|------|----------|-------------|---------|
+| `managed-settings.template.json` | Enterprise administrator | Claude.ai Admin Console or `/etc/claude-code/managed-settings.json` | Admin action — out of band, not automated |
+| `governance.template.md` (if present) | Individual developer | `bin/gaia-scan.py` | `npx gaia-scan` on first install |
+
+**Managed settings precedence:** `managed-settings.template.json` contains wildcard deny rules that cannot be overridden by user or project settings. It also sets `disableBypassPermissionsMode: true` to prevent `--dangerously-skip-permissions`. Deploy this only when you want organization-wide enforcement.
+
+**No CLAUDE.md generated:** Orchestrator identity is no longer generated from a template. It lives in `agents/gaia-orchestrator.md` and is activated via `settings.json: { "agent": "gaia-orchestrator" }`. Surface routing is injected by the `UserPromptSubmit` hook, not by a template.
+
+**Template naming:** Files intended for interpolation use the `.template.<ext>` suffix (e.g., `governance.template.md`, `managed-settings.template.json`). Files without that suffix should not be here.
+
+## Ver también
+
+- [`bin/gaia-scan.py`](../bin/gaia-scan.py) — consumes interpolation templates at install time
+- [`bin/gaia-update.js`](../bin/gaia-update.js) — updates settings.local.json (merges, does not use templates here)
+- [`agents/gaia-orchestrator.md`](../agents/gaia-orchestrator.md) — orchestrator identity (replaces old CLAUDE.md template path)
+- [`build/gaia-ops.manifest.json`](../build/gaia-ops.manifest.json) — plugin-level permission defaults (distinct from managed-settings)

package/templates/managed-settings.template.json

@@ -0,0 +1,43 @@
+{
+  "_comment": [
+    "Managed settings template for enterprise/organization deployment.",
+    "Deploy to: /etc/claude-code/managed-settings.json (Linux/WSL)",
+    "           /Library/Application Support/ClaudeCode/managed-settings.json (macOS)",
+    "           Or via Claude.ai Admin > Claude Code > Managed Settings",
+    "",
+    "These rules have the HIGHEST precedence and CANNOT be overridden by",
+    "user, project, or local settings. They are the ultimate security gate."
+  ],
+  "permissions": {
+    "deny": [
+      "Bash(aws * delete-*:*)",
+      "Bash(aws * terminate-*:*)",
+      "Bash(az * delete:*)",
+      "Bash(gcloud * delete:*)",
+      "Bash(gsutil rb:*)",
+      "Bash(gsutil rm:*)",
+      "Bash(gcloud storage rm:*)",
+      "Bash(kubectl delete:*)",
+      "Bash(kubectl drain:*)",
+      "Bash(terraform destroy:*)",
+      "Bash(terragrunt destroy:*)",
+      "Bash(terragrunt run-all destroy:*)",
+      "Bash(helm uninstall:*)",
+      "Bash(helm delete:*)",
+      "Bash(flux uninstall:*)",
+      "Bash(docker system prune:*)",
+      "Bash(docker volume prune:*)",
+      "Bash(git push --force:*)",
+      "Bash(git push -f:*)",
+      "Bash(git reset --hard:*)",
+      "Bash(gh repo delete:*)",
+      "Bash(glab project delete:*)",
+      "Bash(dd:*)",
+      "Bash(fdisk:*)",
+      "Bash(mkfs:*)",
+      "Bash(mkfs.*:*)"
+    ]
+  },
+  "disableBypassPermissionsMode": "disable",
+  "allowManagedHooksOnly": false
+}

package/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/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()