@jaguilar87/gaia-ops 4.4.0 → 4.7.2

package/dist/gaia-ops/skills/README.md

@@ -0,0 +1,109 @@
+# Skills System
+
+Skills are knowledge modules that extend agent capabilities. They use Claude Code's native skill system for automatic discovery and injection.
+
+## Architecture
+
+```
+.claude/skills/
+├── agent-protocol/        # json:contract format, state machine, repair flow
+├── agent-response/        # Orchestrator: interpret agent json:contract responses
+├── security-tiers/        # T0-T3 classification
+│   └── reference.md
+├── investigation/         # Diagnosis methodology and pattern analysis
+├── command-execution/     # Defensive execution, safe shell patterns
+│   └── reference.md
+├── context-updater/       # CONTEXT_UPDATE format and contract-driven writable sections
+│   └── examples.md
+├── git-conventions/       # Conventional commits (on-demand)
+├── skill-creation/        # How to create new skills
+├── gaia-patterns/         # Gaia meta-system patterns
+│   └── reference.md
+├── terraform-patterns/    # Terraform/Terragrunt patterns
+│   └── reference.md
+├── gitops-patterns/       # GitOps/Flux patterns
+│   └── reference.md
+├── developer-patterns/    # Developer workflow patterns
+├── fast-queries/          # Quick diagnostic scripts
+├── speckit-workflow/      # Speckit phase management
+├── specification/         # Feature specification workflow
+├── orchestrator-approval/ # T3 approval presentation for orchestrator
+├── approval/              # T3 plan presentation and approval workflow
+│   └── examples.md
+├── execution/             # Post-approval execution protocol
+└── reference.md           # Cross-skill reference
+```
+
+## How Skills Work
+
+Skills are assigned to agents via the `skills:` field in agent frontmatter (`.claude/agents/<name>.md`). Claude Code injects the full skill content at subagent startup.
+
+```yaml
+# Example: agents/cloud-troubleshooter.md
+---
+name: cloud-troubleshooter
+skills:
+  - security-tiers
+  - agent-protocol
+  - context-updater
+  - fast-queries
+  - command-execution
+  - investigation
+---
+```
+
+## Skill Assignment Matrix
+
+| Agent | Core Skills | Domain Skills |
+|-------|-------------|---------------|
+| cloud-troubleshooter | agent-protocol, security-tiers | fast-queries |
+| terraform-architect | agent-protocol, security-tiers, terraform-patterns | fast-queries |
+| gitops-operator | agent-protocol, security-tiers, gitops-patterns | fast-queries |
+| devops-developer | agent-protocol, security-tiers, developer-patterns | fast-queries |
+| gaia | agent-protocol, security-tiers, gaia-patterns, skill-creation | - |
+| speckit-planner | agent-protocol, security-tiers, speckit-workflow | - |
+
+Orchestrator skills (loaded on-demand via Skill tool, not assigned to agents):
+- **agent-response** -- contract status interpretation and presentation
+- **orchestrator-approval** -- T3 approval presentation and grant activation
+
+## Skill Types
+
+| Type | Injection | Examples |
+|------|-----------|----------|
+| **Core** | Always via `skills:` | agent-protocol, security-tiers |
+| **Common** | Most agents via `skills:` | command-execution, context-updater |
+| **Domain** | Per-agent via `skills:` | terraform-patterns, gitops-patterns, developer-patterns, gaia-patterns |
+| **Workflow** | On-demand (agent reads file) | approval, execution, git-conventions |
+| **Orchestrator** | On-demand via Skill tool | agent-response, orchestrator-approval |
+
+Workflow skills are loaded on-demand -- agents read them from disk when needed rather than receiving them at startup. Supporting files (`examples.md`, `reference.md`) are also read on-demand.
+
+## SKILL.md Format
+
+```yaml
+---
+name: skill-name
+description: When Claude should use this skill
+metadata:
+  user-invocable: false  # Background knowledge, not a slash command
+  type: core             # Optional: core, common, domain, workflow
+---
+
+# Skill Content
+
+Instructions and patterns the agent follows.
+```
+
+## Development Guidelines
+
+- Keep skills focused and specific
+- Use `metadata.user-invocable: false` for background knowledge
+- Keep injected skills under 100 lines (move details to supporting files)
+- Reference workflow skills as readable files, not injected content
+- Avoid duplicating content across skills -- use references instead
+- See `skill-creation/SKILL.md` for detailed creation guidelines
+
+---
+
+**Updated:** 2026-03-19 | **Total skills:** 20

package/dist/gaia-ops/skills/agent-protocol/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: agent-protocol
+description: Defines json:contract response format, state machine, and evidence reporting
+metadata:
+  user-invocable: false
+  type: protocol
+---
+
+# Agent Protocol
+
+## Response Contract
+
+Every response MUST end with a single fenced `json:contract` block.
+
+```json:contract
+{
+  "agent_status": {
+    "plan_status": "<STATUS>",
+    "agent_id": "<a + 5+ hex chars>",
+    "pending_steps": [],
+    "next_action": "done"
+  },
+  "evidence_report": {
+    "patterns_checked": [],
+    "files_checked": [],
+    "commands_run": [],
+    "key_outputs": [],
+    "verbatim_outputs": [],
+    "cross_layer_impacts": [],
+    "open_gaps": []
+  },
+  "consolidation_report": null,
+  "approval_request": null
+}
+```
+
+### agent_status (always required)
+
+- `plan_status` -- one of the 5 valid states below
+- `agent_id` -- generate once, reuse across responses
+- `pending_steps` -- remaining work (`[]` when done)
+- `next_action` -- `"done"` or what happens next
+
+### evidence_report (always required)
+
+All 7 fields validated by runtime. Use `[]` when not applicable.
+Keep each to 1-3 items unless the task genuinely needs more.
+
+- `key_outputs` -- actionable findings, not descriptions of what you ran. Highlight what matters: what is wrong, what changed, what needs attention.
+- `verbatim_outputs` -- literal command output; truncate at ~100 lines
+- `cross_layer_impacts` -- adjacent surfaces affected
+- `open_gaps` -- what remains unverified; never imply certainty
+
+### consolidation_report (when multi-surface)
+
+Required when `investigation_brief.consolidation_required` or
+`surface_routing.multi_surface` is true. Otherwise `null`.
+
+Fields: `ownership_assessment`, `confirmed_findings`,
+`suspected_findings`, `conflicts`, `open_gaps`, `next_best_agent`.
+
+For examples, read `examples.md` in this skill directory.
+
+### approval_request (when REVIEW)
+
+Required when `plan_status` is `REVIEW`. Otherwise `null`.
+
+Fields: `operation`, `exact_content`, `scope`, `risk_level`, `rollback`, `verification`.
+When a hook blocked a T3 command with `[T3_BLOCKED]` and an `approval_id`:
+- Do NOT retry the command -- retrying generates new nonces in a loop
+- Set `plan_status` to `REVIEW` and include `approval_id` in `approval_request`
+- The orchestrator will resume you after user approval; only then retry
+
+## State Machine
+
+| Status | Meaning |
+|--------|---------|
+| `IN_PROGRESS` | Active work: investigating, planning, executing, retrying (max 2 cycles) |
+| `REVIEW` | Presenting plan or analysis for user feedback. May include `approval_id` when hook-blocked. |
+| `COMPLETE` | Task finished |
+| `BLOCKED` | Cannot proceed -- escalated |
+| `NEEDS_INPUT` | Missing information from user |
+
+### Transitions
+
+```
+IN_PROGRESS -> COMPLETE                                    (T0/T1/T2)
+IN_PROGRESS -> REVIEW -> IN_PROGRESS -> COMPLETE           (plan-first or hook-blocked T3)
+IN_PROGRESS -> BLOCKED | NEEDS_INPUT                       (any point)
+IN_PROGRESS -> IN_PROGRESS                                 (retry, max 2)
+```
+
+## Error Handling
+
+| Type | Action | Status |
+|------|--------|--------|
+| Recoverable | Fix and retry (max 2 cycles) | `IN_PROGRESS` |
+| Blocker | Log details, list solutions | `BLOCKED` |
+| Ambiguous | List options | `NEEDS_INPUT` |
+
+## Contract Repair
+
+If resumed with repair instructions, reissue a complete response
+with `json:contract`. Do not rerun the full investigation.
+Retries capped at 2.

package/dist/gaia-ops/skills/agent-protocol/examples.md

@@ -0,0 +1,170 @@
+# Agent Protocol -- Status-Specific Examples
+
+Read on-demand when constructing a `json:contract` block.
+See `SKILL.md` for the schema definition and field rules.
+
+## COMPLETE (task finished, evidence-backed)
+
+```json:contract
+{
+  "agent_status": {
+    "plan_status": "COMPLETE",
+    "agent_id": "ab7e4d2",
+    "pending_steps": [],
+    "next_action": "done"
+  },
+  "evidence_report": {
+    "patterns_checked": ["existing HelmRelease naming convention in flux/apps/"],
+    "files_checked": ["flux/apps/qxo-api/helmrelease.yaml"],
+    "commands_run": ["kubectl get hr -n qxo -> all reconciled"],
+    "key_outputs": ["All 12 HelmReleases healthy, no drift detected"],
+    "verbatim_outputs": [],
+    "cross_layer_impacts": [],
+    "open_gaps": []
+  },
+  "consolidation_report": null,
+  "approval_request": null
+}
+```
+
+## BLOCKED (cannot proceed)
+
+```json:contract
+{
+  "agent_status": {
+    "plan_status": "BLOCKED",
+    "agent_id": "ac3a1f9",
+    "pending_steps": ["validate IAM binding", "apply terraform change"],
+    "next_action": "User must grant roles/container.admin to SA"
+  },
+  "evidence_report": {
+    "patterns_checked": ["SA binding pattern in terraform/iam/"],
+    "files_checked": ["terraform/iam/main.tf", "terraform/iam/variables.tf"],
+    "commands_run": ["gcloud iam service-accounts get-iam-policy sa@proj.iam -> missing binding"],
+    "key_outputs": ["SA lacks roles/container.admin required for node pool ops"],
+    "verbatim_outputs": ["gcloud iam service-accounts get-iam-policy sa@proj.iam:\n```\nbindings: []\n```"],
+    "cross_layer_impacts": ["GKE node pool scaling depends on this SA"],
+    "open_gaps": ["Whether SA should get role directly or via workload identity"]
+  },
+  "consolidation_report": null,
+  "approval_request": null
+}
+```
+
+## NEEDS_INPUT (missing information)
+
+```json:contract
+{
+  "agent_status": {
+    "plan_status": "NEEDS_INPUT",
+    "agent_id": "ad9f2b1",
+    "pending_steps": ["create namespace manifest", "configure HelmRelease"],
+    "next_action": "User must choose: Option A (shared namespace) or Option B (dedicated namespace)"
+  },
+  "evidence_report": {
+    "patterns_checked": ["namespace conventions in flux/clusters/"],
+    "files_checked": ["flux/clusters/dev/namespaces/"],
+    "commands_run": [],
+    "key_outputs": ["Both patterns exist in codebase -- no single convention"],
+    "verbatim_outputs": [],
+    "cross_layer_impacts": ["Network policies differ per pattern"],
+    "open_gaps": ["User preference for namespace isolation"]
+  },
+  "consolidation_report": null,
+  "approval_request": null
+}
+```
+
+## REVIEW (plan ready for user feedback, no nonce)
+
+```json:contract
+{
+  "agent_status": {
+    "plan_status": "REVIEW",
+    "agent_id": "ae5c8a3",
+    "pending_steps": ["execute terraform apply", "verify state"],
+    "next_action": "Awaiting user feedback on terraform apply plan"
+  },
+  "evidence_report": {
+    "patterns_checked": ["existing bucket naming in terraform/gcs/"],
+    "files_checked": ["terraform/gcs/main.tf", "terraform/gcs/variables.tf"],
+    "commands_run": ["terraform plan -out=tfplan -> 1 to add, 0 to change, 0 to destroy"],
+    "key_outputs": ["Plan adds 1 GCS bucket with standard config"],
+    "verbatim_outputs": ["terraform plan:\n```\n+ google_storage_bucket.events\n  name: qxo-events-dev\n  location: us-east4\n```"],
+    "cross_layer_impacts": ["Flux ExternalSecret must reference new bucket"],
+    "open_gaps": []
+  },
+  "consolidation_report": null,
+  "approval_request": {
+    "operation": "Create GCS bucket qxo-events-dev",
+    "exact_content": "terraform apply -auto-approve",
+    "scope": "terraform/gcs/main.tf, GCS bucket in us-east4",
+    "risk_level": "MEDIUM",
+    "rollback": "terraform destroy -target=google_storage_bucket.events",
+    "verification": "gcloud storage buckets describe gs://qxo-events-dev"
+  }
+}
+```
+
+## REVIEW with approval_id (hook blocked T3 command)
+
+```json:contract
+{
+  "agent_status": {
+    "plan_status": "REVIEW",
+    "agent_id": "af1d9b7",
+    "pending_steps": ["execute git push", "verify Flux reconciliation"],
+    "next_action": "Hook blocked git push -- awaiting user approval"
+  },
+  "evidence_report": {
+    "patterns_checked": ["git branch naming in flux/clusters/"],
+    "files_checked": ["flux/apps/qxo-api/helmrelease.yaml"],
+    "commands_run": ["git diff HEAD -> 1 file changed", "git push origin main -> BLOCKED by hook"],
+    "key_outputs": ["Push blocked by security hook, approval_id issued"],
+    "verbatim_outputs": ["[T3_BLOCKED] MUTATIVE operation requires user approval. approval_id: a1b2c3..."],
+    "cross_layer_impacts": ["Flux will reconcile HelmRelease on push"],
+    "open_gaps": []
+  },
+  "consolidation_report": null,
+  "approval_request": {
+    "operation": "Push HelmRelease changes to main",
+    "exact_content": "git push origin main",
+    "scope": "flux/apps/qxo-api/helmrelease.yaml",
+    "risk_level": "MEDIUM",
+    "rollback": "git revert HEAD && git push",
+    "verification": "flux get hr -n qxo -> reconciled",
+    "approval_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
+  }
+}
+```
+
+## With Consolidation (multi-surface task)
+
+```json:contract
+{
+  "agent_status": {
+    "plan_status": "COMPLETE",
+    "agent_id": "af4b2e8",
+    "pending_steps": [],
+    "next_action": "done"
+  },
+  "evidence_report": {
+    "patterns_checked": ["terraform module structure in terraform/modules/"],
+    "files_checked": ["terraform/modules/gke/main.tf", "flux/clusters/dev/kustomization.yaml"],
+    "commands_run": ["terragrunt plan -chdir=/abs/path -> no changes"],
+    "key_outputs": ["Terraform state matches code; Flux kustomization references correct cluster"],
+    "verbatim_outputs": [],
+    "cross_layer_impacts": ["Flux depends on GKE node pool count from terraform output"],
+    "open_gaps": ["HPA config in flux not verified"]
+  },
+  "consolidation_report": {
+    "ownership_assessment": "cross_surface_dependency",
+    "confirmed_findings": ["GKE cluster config matches terraform code", "Node pool count is 3 in both plan and live"],
+    "suspected_findings": ["HPA max replicas may exceed node capacity"],
+    "conflicts": [],
+    "open_gaps": ["HPA config in flux not verified -- gitops-operator should check"],
+    "next_best_agent": "gitops-operator"
+  },
+  "approval_request": null
+}
+```

package/dist/gaia-ops/skills/agent-response/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: agent-response
+description: Use when an agent returns a json:contract response that needs to be interpreted and presented to the user
+metadata:
+  user-invocable: false
+  type: protocol
+---
+
+# Agent Response Protocol
+
+## State Machine
+
+```
+Agent returns json:contract
+  |- COMPLETE         -> Summarize key_outputs (3-5 bullets)
+  |- NEEDS_INPUT      -> AskUserQuestion, then SendMessage answer back
+  |- REVIEW           -> Load Skill("orchestrator-approval") if approval_id present,
+  |                      otherwise AskUserQuestion (execute/modify/cancel)
+  |- BLOCKED          -> Present open_gaps via AskUserQuestion
+  +- IN_PROGRESS      -> SendMessage to resume agent
+```
+
+## Mandatory Actions per Status
+
+| Status | Action | Tool |
+|---|---|---|
+| `COMPLETE` | Summarize `key_outputs` in 3-5 bullets. Mention `cross_layer_impacts` and `open_gaps` if non-empty. Say "ask for details" if `verbatim_outputs` exists. | Direct response |
+| `NEEDS_INPUT` | Present the agent's question with options | `AskUserQuestion` -> `SendMessage` |
+| `REVIEW` | If `approval_request.approval_id` is present: load `Skill("orchestrator-approval")`. Otherwise: present plan with options execute / modify / cancel. | `AskUserQuestion` -> `SendMessage` |
+| `BLOCKED` | Present alternatives from `open_gaps` | `AskUserQuestion` |
+| `IN_PROGRESS` | Agent was interrupted, let it continue | `SendMessage` |
+
+## Output Fields
+
+| Field | When to surface |
+|---|---|
+| `key_outputs` | Always -- base your summary on these |
+| `verbatim_outputs` | Only when user asks for details -- relay in code blocks |
+| `cross_layer_impacts` | Always mention if non-empty |
+| `open_gaps` | Always mention -- never imply certainty |
+| `consolidation_report` | Check for `conflicts` and `next_best_agent` |
+| `next_best_agent` | Ask user if they want to dispatch |
+
+## Multiple Agents
+
+Wait for ALL dispatched agents before responding. Consolidate findings.
+If agents conflict, present both sides and ask user to decide.
+
+## Error Handling
+
+| Situation | Action |
+|---|---|
+| Malformed contract | Resume agent with repair instructions (max 2 retries). |

package/dist/gaia-ops/skills/approval/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: approval
+description: Use when a T3 operation is ready and needs to be presented to the user for approval before execution
+metadata:
+  user-invocable: false
+  type: technique
+---
+
+# Approval
+
+## Overview
+
+The plan is a contract. The user approves the exact contract --
+not a vague intent. Structure your plan in the `approval_request`
+field of your `json:contract` so the orchestrator can present it
+directly to the user.
+
+## Approval Request
+
+Include an `approval_request` object in your `json:contract` block
+with these 6 fields:
+
+```json
+"approval_request": {
+  "operation": "verb + target",
+  "exact_content": "literal command, config, or file change",
+  "scope": "files, resources, environments affected",
+  "risk_level": "LOW | MEDIUM | HIGH | CRITICAL",
+  "rollback": "how to undo if wrong",
+  "verification": "how to confirm success after execution"
+}
+```
+
+When a hook blocked your command with an `approval_id`, also include:
+```json
+"approval_id": "hex from hook deny response"
+```
+
+### Risk Levels
+
+| Level | Criteria |
+|-------|----------|
+| LOW | Single resource, non-prod, no dependencies |
+| MEDIUM | Multiple resources, non-prod, some dependencies |
+| HIGH | Production, dependencies, potential downtime |
+| CRITICAL | Irreversible, data loss possible |
+
+## Which Status to Emit
+
+- `REVIEW` -- presenting a plan before executing (no hook block)
+- `REVIEW` with `approval_id` -- hook blocked your command with an approval_id
+
+Both use `REVIEW` as the plan_status. The presence or absence of
+`approval_id` in `approval_request` tells the orchestrator which
+handling path to take.
+
+## Hook Block Flow
+
+When a hook blocks your command with `[T3_BLOCKED]` and an `approval_id`:
+
+1. **STOP** -- do NOT retry the command. Retrying generates a new nonce
+   each time, creating an infinite loop.
+2. **Report REVIEW** -- set `plan_status` to `REVIEW` in your `json:contract`.
+3. **Include the approval_id** -- copy the hex identifier from the hook deny
+   response into `approval_request.approval_id`.
+4. **Wait** -- the orchestrator presents your plan to the user. When the user
+   approves, the orchestrator resumes you with the grant activated.
+5. **Then retry** -- only after the orchestrator resumes you, retry the command.
+
+The hook deny message looks like:
+```
+[T3_BLOCKED] This command requires user approval.
+Do NOT retry this command. Report REVIEW with this approval_id in your json:contract.
+approval_id: <hex>
+```
+
+If you lose the approval_id, re-attempt the command once for a fresh one.
+
+## Anti-Patterns
+
+- **Retrying after T3_BLOCKED** -- generates a new nonce, causes infinite loop
+- Presenting approval without all 6 fields in `approval_request`
+- Putting approval fields in text only without the JSON object
+- Treating prior approvals as valid for new operations
+- Fabricating or paraphrasing the approval_id token

package/dist/gaia-ops/skills/approval/examples.md

@@ -0,0 +1,140 @@
+# Approval Plan Examples
+
+Reference examples for agents. Read on-demand when building your first plan or when unsure about format.
+
+## Example 1: Terraform Apply (GCP)
+
+```markdown
+## Terraform Apply Plan
+
+### Summary
+- Creating GCP VPC network for production cluster
+- Adds 3 subnetworks across us-east4-a, us-east4-b, us-east4-c
+- No existing resources affected
+
+### Changes Proposed
+
+**Resources to CREATE:**
+- `google_compute_network.prod-network`: VPC in auto-subnet mode disabled
+- `google_compute_subnetwork.prod-subnet-a`: 10.0.1.0/24 in us-east4-a
+- `google_compute_subnetwork.prod-subnet-b`: 10.0.2.0/24 in us-east4-b
+- `google_compute_subnetwork.prod-subnet-c`: 10.0.3.0/24 in us-east4-c
+
+**Resources to MODIFY:** None
+**Resources to DELETE:** None
+
+### Validation Results
+
+**Dry-run status:**
+- ✅ `terragrunt plan` - No errors, 4 to add, 0 to change, 0 to destroy
+- ✅ `terragrunt hclfmt --check` - No formatting issues
+- ✅ `terraform validate` - Success
+
+**Dependencies verified:**
+- GCP project [project-id]: accessible ✓
+- No CIDR conflicts with existing networks ✓
+
+### Risk Assessment
+
+**Risk Level:** MEDIUM
+
+**Potential Risks:**
+1. CIDR overlap with existing VPC networks
+   - Mitigation: Verified no overlaps via `gcloud compute networks list`
+2. Subnet creation timeout
+   - Mitigation: Timeout set to 300s, idempotent — safe to retry
+
+**Rollback Plan:**
+- If creation fails: `terragrunt destroy --terragrunt-working-dir "/abs/path/to/terraform/vpc"`
+- Recovery time: ~5 minutes
+
+### Execution Steps
+
+When approved, will execute:
+1. `git add [terraform_vpc_path]/`
+2. `git commit -m "feat(infra): add production VPC network"`
+3. `git push origin main`
+4. `terragrunt apply -auto-approve --terragrunt-working-dir "/abs/path/to/terraform/vpc"`
+
+### Verification Criteria
+
+- `gcloud compute networks describe prod-network --project=[project-id]` → `status: ACTIVE`
+- `gcloud compute networks subnets list --filter="network:prod-network" --project=[project-id]` → 3 subnets listed
+
+### Files Affected
+
+**Git changes:**
+- Added: `[terraform_vpc_path]/terragrunt.hcl`
+- Added: `[terraform_vpc_path]/main.tf`
+
+## Approval Required
+
+**Approval Code:** `NONCE:<hex from hook block response>`
+**Operation:** terragrunt apply
+**Environment:** prod
+**Risk Level:** MEDIUM
+```
+
+## Example 2: GitOps Deployment
+
+```markdown
+## GitOps Deployment Plan
+
+### Summary
+- Updating graphql-server image to v1.0.180
+- No configuration changes
+- Flux will auto-reconcile in ~1 minute
+
+### Changes Proposed
+
+**HelmRelease to MODIFY:**
+- `graphql-server` in namespace `common`
+  - Image: ghcr.io/vtr/graphql-server:v1.0.176 → v1.0.180
+  - No other changes
+
+### Validation Results
+
+**Dry-run status:**
+- ✅ `kubectl apply --dry-run=client` - Valid manifest
+- ✅ YAML syntax check - Passed
+- ✅ Image exists in registry - Verified
+
+### Risk Assessment
+
+**Risk Level:** LOW
+
+**Potential Risks:**
+1. New image might have bugs
+   - Mitigation: Tested in dev cluster, all tests passed
+2. Pod restart might cause brief downtime
+   - Mitigation: RollingUpdate strategy, 2 replicas ensure availability
+
+**Rollback Plan:**
+- If deployment fails: `git revert` + `flux reconcile`
+- Recovery time: ~2 minutes
+
+### Execution Steps
+
+When approved, will execute:
+1. `git add gitops/clusters/prod-digital-eks/common/graphql-server.yaml`
+2. `git commit -m "chore(graphql): update to v1.0.180"`
+3. `git push origin main`
+4. Flux auto-reconciles in ~1 minute (or force: `flux reconcile helmrelease graphql-server -n common --timeout=90s`)
+
+### Verification Criteria
+
+- `kubectl get helmrelease graphql-server -n common --request-timeout=30s` → `READY=True`, revision contains `v1.0.180`
+- `kubectl get pods -n common -l app=graphql-server --request-timeout=30s` → all pods `Running`
+
+### Files Affected
+
+**Git changes:**
+- Modified: `gitops/clusters/prod-digital-eks/common/graphql-server.yaml`
+
+## Approval Required
+
+**Approval Code:** `NONCE:<hex from hook block response>`
+**Operation:** git push + flux reconcile
+**Environment:** prod
+**Risk Level:** LOW
+```