@jaguilar87/gaia-ops 4.5.0 → 5.0.0-beta.1

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "gaia-security",
       "description": "Keeps you in the loop only when it matters. Gaia Security analyzes every command and classifies it into risk tiers: read-only queries run freely, simulations and validations pass through, and state-changing operations (create, delete, apply, push) pause for your explicit approval before executing. Irreversible commands like dropping databases or deleting cloud infrastructure are permanently blocked.",
-      "version": "4.5.0",
+      "version": "5.0.0-beta.1",
       "source": "./dist/gaia-security"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia-ops",
-  "version": "4.5.0",
+  "version": "5.0.0-beta.1",
   "description": "Security-first orchestrator with specialized agents, hooks, and governance for AI coding",
   "author": {
     "name": "jaguilar87"

package/ARCHITECTURE.md

@@ -15,7 +15,7 @@ The package is published as `@jaguilar87/gaia-ops` on npm and installed into a p
 | **Hook** | Python scripts that intercept tool calls before and after execution |
 | **Tool** | Python modules in `tools/` providing context assembly, memory, and validation |
 | **Config** | JSON files in `config/` defining contracts, rules, surface routing, and security |
-| **Orchestrator** | Identity injected by UserPromptSubmit hook; routes requests to the correct agent via on-demand skills |
+| **Orchestrator** | Agent definition in `agents/gaia-orchestrator.md`, activated via `settings.json: { "agent": "gaia-orchestrator" }`; routes requests to the correct agent via on-demand skills |
 
 ## Runtime Flow
 
@@ -23,9 +23,10 @@ The package is published as `@jaguilar87/gaia-ops` on npm and installed into a p
 User request
     |
     v
-user_prompt_submit.py  (UserPromptSubmit hook)
-    |  Inject orchestrator identity via ops_identity.py
-    |  Skills loaded on-demand: project-dispatch, agent-response
+Orchestrator (agents/gaia-orchestrator.md, activated via settings.json agent config)
+    |  Identity defined in agent definition file
+    |  Surface routing recommendation injected by UserPromptSubmit hook (deterministic)
+    |  Skills loaded on-demand: agent-response
     v
 Orchestrator dispatches to agent
     |  Routes by surface classification
@@ -49,7 +50,7 @@ subagent_stop.py  (SubagentStop hook)
     v
 Orchestrator processes json:contract (via agent-response skill)
     |  COMPLETE -> summarize to user
-    |  AWAITING_APPROVAL -> get approval -> resume via SendMessage
+    |  REVIEW (with approval_id) -> get approval -> resume via SendMessage
     |  NEEDS_INPUT -> ask user -> resume via SendMessage
     |  BLOCKED -> report blocker
 ```
@@ -119,9 +120,10 @@ Classifies user tasks into surfaces using signal matching against `config/surfac
 | `live_runtime` | cloud-troubleshooter | pods, services, logs, kubectl, gcloud |
 | `gitops_desired_state` | gitops-operator | manifests, Flux, Helm, Kustomize |
 | `terraform_iac` | terraform-architect | Terraform, Terragrunt, IAM, modules |
-| `app_ci_tooling` | devops-developer | CI/CD, Docker, package tooling |
+| `app_ci_tooling` | developer | CI/CD, Docker, package tooling |
 | `planning_specs` | speckit-planner | specs, plans, task breakdowns |
 | `gaia_system` | gaia | hooks, skills, agents/, CLAUDE.md |
+| `workspace` | gaia-operator | memory, email, schedules, file transfers |
 
 **Classification algorithm:**
 1. Normalize task text
@@ -170,7 +172,7 @@ Nonce-based T3 approval lifecycle:
 3. BashValidator generates 128-bit nonce via generate_nonce()
 4. write_pending_approval() saves pending-{nonce}.json to .claude/cache/approvals/
 5. Hook returns corrective deny (exit 0) with NONCE:{hex} in message
-6. Agent includes NONCE:{hex} in PENDING_APPROVAL status to orchestrator
+6. Agent includes NONCE:{hex} in REVIEW status to orchestrator
 7. Orchestrator presents plan to user, asks for approval
 8. User approves -> orchestrator resumes agent with "APPROVE:{nonce}"
 9. pre_tool_use.py detects APPROVE: prefix, calls activate_pending_approval()
@@ -182,7 +184,7 @@ Nonce-based T3 approval lifecycle:
 
 Every agent response must end with a `json:contract` block containing `agent_status`. The contract validator (`hooks/modules/agents/contract_validator.py`) enforces:
 
-- **AGENT_STATUS**: PLAN_STATUS (from 6 valid states: COMPLETE, NEEDS_INPUT, REVIEW, AWAITING_APPROVAL, BLOCKED, IN_PROGRESS), PENDING_STEPS, NEXT_ACTION, AGENT_ID
+- **AGENT_STATUS**: PLAN_STATUS (from 5 valid states: COMPLETE, NEEDS_INPUT, REVIEW, BLOCKED, IN_PROGRESS), PENDING_STEPS, NEXT_ACTION, AGENT_ID
 - **EVIDENCE_REPORT**: required for all valid states. Seven fields: PATTERNS_CHECKED, FILES_CHECKED, COMMANDS_RUN, KEY_OUTPUTS, VERBATIM_OUTPUTS, CROSS_LAYER_IMPACTS, OPEN_GAPS
 - **CONSOLIDATION_REPORT**: required when multi-surface or cross-check. Fields: OWNERSHIP_ASSESSMENT (enum), CONFIRMED_FINDINGS, SUSPECTED_FINDINGS, CONFLICTS, OPEN_GAPS, NEXT_BEST_AGENT
 
@@ -256,14 +258,14 @@ The adapter layer connects Claude Code's hook protocol to gaia-ops business logi
 | **Adapter methods called** | `ClaudeCodeAdapter.format_validation_response()` |
 | **Business logic modules** | None (pure formatting bridge) |
 
-### CP-5: `templates/settings.template.json` / `hooks/hooks.json` -- Hook Configuration
+### CP-5: `hooks/hooks.json` -- Hook Configuration
 
 | Attribute | Value |
 |-----------|-------|
-| **File (npm channel)** | `templates/settings.template.json` -- paths use `.claude/hooks/` prefix |
 | **File (plugin channel)** | `hooks/hooks.json` -- paths use `${CLAUDE_PLUGIN_ROOT}/hooks/` prefix |
+| **File (npm channel)** | `hooks/hooks.json` (symlinked into `.claude/hooks/`) |
 | **What it does** | Maps Claude Code hook events to handler scripts. Defines which events fire which entry points, the tool matchers (Bash, Task, Agent, `*`), and permissions (allow/deny lists). |
-| **Events configured** | PreToolUse (Bash, Task, Agent, SendMessage), PostToolUse, SubagentStop, SessionStart, Stop, TaskCompleted, SubagentStart, UserPromptSubmit (identity injection) |
+| **Events configured** | PreToolUse (Bash, Task, Agent, SendMessage), PostToolUse, SubagentStop, SessionStart, Stop, TaskCompleted, SubagentStart, UserPromptSubmit (routing injection) |
 
 ### HookAdapter ABC Contract
 
@@ -292,7 +294,7 @@ To add support for a new Claude Code hook event (e.g., a future `PreCompact` eve
 2. **Add adapter method** to `ClaudeCodeAdapter` in `hooks/adapters/claude_code.py` -- implement `adapt_<event_name>(raw: dict) -> <ResultType>` and the corresponding `format_<result>_response()` if a new result type is needed.
 3. **Add extract/format methods** for the event type -- the extract method pulls typed data from the raw payload, the format method builds the CLI response JSON.
 4. **Create hook script entry point** -- a new `hooks/<event_name>.py` file that reads stdin, calls `adapter.parse_event()`, delegates to business logic, and writes the response to stdout.
-5. **Add entry to `hooks/hooks.json`** (plugin channel) and `templates/settings.template.json` (npm channel) mapping the event name to the new script.
+5. **Add entry to `hooks/hooks.json`** mapping the event name to the new script.
 
 **Zero changes to business logic modules required.** The adapter is the only layer that touches CLI-specific JSON.
 
@@ -310,8 +312,8 @@ To support a CLI other than Claude Code (e.g., a hypothetical Cursor or Windsurf
 
 | File | Purpose |
 |------|---------|
-| `hooks/modules/identity/ops_identity.py` | Orchestrator identity (injected by UserPromptSubmit) |
-| `skills/project-dispatch/SKILL.md` | Agent routing table and dispatch rules (on-demand) |
+| `agents/gaia-orchestrator.md` | Orchestrator identity and routing (activated via settings.json agent config) |
+| `config/surface-routing.json` | Surface routing config (agent table, signals, dispatch) |
 | `skills/agent-response/SKILL.md` | Contract status handling protocol (on-demand) |
 | `hooks/pre_tool_use.py` | PreToolUse hook entry point |
 | `hooks/subagent_stop.py` | SubagentStop hook entry point |

package/INSTALL.md

@@ -276,7 +276,7 @@ When you update `@jaguilar87/gaia-ops`, these files are **regenerated from templ
 | `.claude/logs/` | ✅ **Preserved** | Safe |
 | Other `.claude/` files | ✅ **Auto-updated via symlinks** | Safe |
 
-Orchestrator identity is injected dynamically by the UserPromptSubmit hook -- no `CLAUDE.md` is generated.
+Orchestrator identity lives in `agents/gaia-orchestrator.md` and is activated via `settings.json: { "agent": "gaia-orchestrator" }` -- no `CLAUDE.md` is generated.
 
 ### Update Process
 
@@ -431,7 +431,7 @@ A: `npm update @jaguilar87/gaia-ops` - symlinks point to the new version automat
 
 ---
 
-**Version:** 4.4.0-rc.5
-**Last updated:** 2026-03-19
+**Version:** 4.7.2
+**Last updated:** 2026-04-09
 **Maintained by:** Jorge Aguilar + Gaia (meta-agent)
 

package/README.md

@@ -15,9 +15,9 @@ Multi-agent DevOps system that classifies every operation by risk, routes work t
 ### Features
 
 - **Multi-cloud support** - GCP, AWS, Azure
-- **6 agents** - terraform-architect, gitops-operator, cloud-troubleshooter, devops-developer, speckit-planner, gaia-system (meta-agent)
+- **8 agents** - terraform-architect, gitops-operator, cloud-troubleshooter, developer, speckit-planner, gaia-operator, gaia-orchestrator, gaia-system (meta-agent)
 - **Contracts as SSOT** - Cloud-agnostic base contracts with per-cloud extensions (GCP, AWS)
-- **Dynamic identity** - Orchestrator identity injected by UserPromptSubmit hook; skills loaded on-demand
+- **Dynamic identity** - Orchestrator identity defined in `agents/gaia-orchestrator.md`, activated via `settings.json` agent config; skills loaded on-demand
 - **Dual-barrier security** - Settings deny rules (Claude Code native) + hook-level blocking (inalterable via symlink)
 - **Indirect execution detection** - Catches `bash -c`, `eval`, `python -c` wrappers that bypass regex patterns
 - **Approval gates** for T3 operations via native `ask` dialog
@@ -64,7 +64,7 @@ This will:
 4. Create `settings.json` with hooks only (no permissions in settings.json)
 5. Merge deny rules + allow permissions into `settings.local.json` (preserves existing user config)
 
-No `CLAUDE.md` is generated -- orchestrator identity is injected dynamically by the UserPromptSubmit hook.
+No `CLAUDE.md` is generated -- orchestrator identity lives in `agents/gaia-orchestrator.md` and is activated via `settings.json: { "agent": "gaia-orchestrator" }`.
 
 ### Settings Architecture
 
@@ -105,7 +105,7 @@ Once installed, the agent system is ready:
 claude
 ```
 
-The orchestrator identity is injected dynamically by the UserPromptSubmit hook. Skills are loaded on-demand.
+The orchestrator identity is defined in `agents/gaia-orchestrator.md` and activated via `settings.json` agent config. Skills are loaded on-demand.
 
 Skills and injection diagnosis:
 
@@ -136,7 +136,7 @@ For organization-wide enforcement, deploy `templates/managed-settings.template.j
 
 ```
 node_modules/@jaguilar87/gaia-ops/
-├── agents/              # Agent definitions (6 agents)
+├── agents/              # Agent definitions (8 agents)
 ├── skills/              # Skill modules (21 skills)
 ├── tools/               # Orchestration tools
 ├── hooks/               # Claude Code hooks (modular architecture)

package/agents/cloud-troubleshooter.md

@@ -57,7 +57,7 @@ If unclear, ask before proceeding.
 |------|-------|
 | Fix infrastructure drift | `terraform-architect` |
 | Fix Kubernetes manifests | `gitops-operator` |
-| Application code changes | `devops-developer` |
+| Application code changes | `developer` |
 | gaia-ops modifications | `gaia` |
 
 **This agent never modifies files, never executes writes, never invokes other agents directly.**

package/agents/{devops-developer.md → developer.md}

@@ -1,6 +1,6 @@
 ---
-name: devops-developer
-description: Full-stack DevOps specialist unifying application code, infrastructure, and developer tooling across Node.js/TypeScript and Python ecosystems.
+name: developer
+description: Full-stack software engineer for application code, CI/CD, and developer tooling across Node.js/TypeScript and Python stacks.
 tools: Read, Edit, Write, Agent, Glob, Grep, Bash, Task, Skill, WebSearch, WebFetch
 model: inherit
 maxTurns: 50
@@ -46,6 +46,13 @@ You are a full-stack software engineer. You build, debug, and improve applicatio
 | Live cloud diagnostics | `cloud-troubleshooter` |
 | gaia-ops modifications | `gaia` |
 
+During investigation, if you discover that a resource type is managed
+by Terraform, Terragrunt, Helm, Flux, or any other IaC/GitOps tool,
+creating new instances of that resource belongs to the agent that owns
+that tool — even if you need the resource as a prerequisite for your
+task. Report it as a dependency or blocker. The fastest path for you
+is the wrong path for the project if it causes drift.
+
 ## Domain Errors
 
 | Error | Action |

package/agents/gaia-operator.md

@@ -0,0 +1,60 @@
+---
+name: gaia-operator
+description: Workspace operator — extensible agent for personal workspace tasks, memory management, and integrations
+tools: Read, Edit, Write, Glob, Grep, Bash, Task, Skill, WebSearch, WebFetch
+model: sonnet
+skills:
+  - agent-protocol
+  - security-tiers
+  - command-execution
+  - context-updater
+  - memory-management
+  - gmail-triage
+  - gws-setup
+---
+
+# Workspace Operator
+
+## Identity
+
+You are the workspace operator — an extensible agent that specializes in personal workspace
+tasks. You manage the user's persistent memory, workspace organization, and tool integrations.
+Your capabilities grow through on-demand skills — each new integration is a skill, not a
+code change.
+
+## Core Capabilities
+
+- **Memory management** — MEMORY.md index, memory files, cross-session knowledge persistence
+- **Web research** — search and summarize information for the user
+- **Workspace file operations** — organize, transfer, manage files across the workspace
+
+Future capabilities arrive as on-demand skills (email, calendar, scheduling, etc.).
+Load them with `Skill('skill-name')` when the task requires it.
+
+## Scope
+
+### CAN DO
+
+| Task | How |
+|------|-----|
+| Create/update/search memory files | Read/Write + memory-management skill |
+| Web research and summarization | WebSearch + WebFetch |
+| File organization and management | Bash + Read/Write |
+| Load integration skills on-demand | Skill('gmail-policy'), Skill('calendar'), etc. |
+
+### CANNOT DO → DELEGATE
+
+| Task | Agent |
+|------|-------|
+| Application code, CI/CD, Docker | developer |
+| Terraform, cloud resources, IaC | terraform-architect |
+| Kubernetes manifests, Helm, Flux | gitops-operator |
+| Live infrastructure diagnostics | cloud-troubleshooter |
+| Gaia system changes (hooks, skills, agents) | gaia-system |
+| Feature planning and specs | speckit-planner |
+
+## Domain Errors
+
+- **Memory index conflict** — MEMORY.md does not match actual files → reconcile index before proceeding
+- **Skill not found** — requested integration skill does not exist → report to orchestrator, suggest creation via gaia-system
+- **File permission denied** — cannot access target path → verify path and permissions, report exact error

package/agents/gaia-orchestrator.md

@@ -0,0 +1,113 @@
+---
+name: gaia-orchestrator
+description: Gaia governance orchestrator — routes requests to specialist agents, enforces security tiers, presents results
+tools: Agent, SendMessage, AskUserQuestion, Skill, TaskCreate, TaskUpdate, TaskList, TaskGet, CronCreate, CronDelete, CronList, WebSearch, WebFetch, ToolSearch
+disallowedTools: [Read, Glob, Grep, Bash, Edit, Write, NotebookEdit, EnterPlanMode, ExitPlanMode, EnterWorktree, ExitWorktree]
+model: inherit
+maxTurns: 200
+skills:
+---
+
+# Gaia Orchestrator
+
+The user installed Gaia, a governance layer for Claude Code agents.
+Your role: analyze requests, decompose them into specialist tasks,
+dispatch agents with focused objectives, and consolidate their results.
+
+## Why delegation matters
+
+- Agents are injected with domain skills and security policies at spawn time
+- Each agent has its own context window optimized for its domain
+- Agents return structured json:contract responses (atomic, preserves your context)
+- Direct tool use bypasses the governance pipeline (no audit trail, no security tiers)
+- Built-in subagent types (Explore, Plan) return raw text that inflates your context
+
+## Capabilities
+
+- Route user requests to specialist agents using deterministic signal matching
+- Enforce security tiers and approval workflows for T3 operations
+- Present structured agent responses and manage approval cycles
+- Track work progress across multi-agent tasks
+
+## Your tools (ONLY these exist)
+
+- **Agent** -- dispatch specialist agents (each has injected skills and tool restrictions)
+- **SendMessage** -- resume a running agent by name or ID
+- **AskUserQuestion** -- clarify with user, or present approval requests
+- **Skill** -- load on-demand procedures (agent-response, orchestrator-approval)
+- **TaskCreate/Update/List/Get** -- track work progress
+- **WebSearch/WebFetch** -- web research (allowed, no delegation needed)
+- **ToolSearch** -- discover deferred tool schemas
+
+You do NOT have: Read, Glob, Grep, Bash, Edit, Write.
+These tools do not exist in your session. Do not attempt to use them.
+
+## Routing
+
+Each message may include a routing suggestion from signal matching.
+Use it as input, not as a directive. Match the user's request against
+these surface intents. Dispatch ALL agents whose intent matches.
+If 2+ match, dispatch in parallel.
+
+| Surface | Agent | Intent |
+|---------|-------|--------|
+| live_runtime | cloud-troubleshooter | Inspect, diagnose, or validate actual state of running systems — pods, logs, cloud resources, SSH, network |
+| terraform_iac | terraform-architect | Create, modify, review, or validate IaC — Terraform, Terragrunt, cloud resources, state, plan/apply |
+| gitops_desired_state | gitops-operator | Create, modify, or review Kubernetes desired state — Flux, Helm, Kustomize, manifests |
+| app_ci_tooling | developer | Write, modify, test, or build app code — Node/TS, Python, Docker, CI/CD, packages |
+| planning_specs | speckit-planner | Plan features, break down requirements, create specs, plans, task lists |
+| gaia_system | gaia-system | Modify or analyze Gaia itself — hooks, skills, agents, routing, security, architecture |
+| workspace | gaia-operator | Personal workspace — memory, schedules, loops, email, file transfers, general automation |
+
+If no intent matches clearly — ask the user to clarify.
+Do not default to built-in agents (Explore, Plan) for tasks that match a surface intent.
+
+## Dispatch strategy
+
+When dispatching, ask yourself:
+1. What domains does this request touch? (match against intents above)
+2. What specific question does each specialist need to answer?
+3. Can they work in parallel, or does one depend on another?
+
+Each agent gets a DIFFERENT prompt focused on their domain.
+Do not send the same user message to multiple agents — decompose it.
+
+## Briefing agents
+
+Dispatch objectives, not commands. Agents have domain skills,
+injected project-context, and investigation procedures.
+They choose their own execution path.
+
+Your prompt = the objective + business requirements.
+Never include:
+- File names, paths, or directory structures to create
+- Resource names, values, or configuration details
+- Shell commands or implementation steps
+- "What to create" or "How to implement" sections
+
+Agents receive project-context with paths, names, and topology.
+They investigate existing patterns before proposing anything.
+Trust the agent's domain expertise — your job is WHAT to achieve
+and WHY, never HOW.
+
+## Response handling
+
+When an agent returns a json:contract, load Skill('agent-response').
+When an agent returns REVIEW with approval_id, load Skill('orchestrator-approval').
+
+## Memory Protocol
+
+Claude Code handles auto-save and auto-prune natively.
+Gaia complements with structured curation via gaia-operator:
+
+- After productive sessions with decisions → dispatch gaia-operator
+- Operator loads memory-management skill → curates, categorizes, deduplicates
+- Does NOT replace Claude Code's native memory — organizes it
+
+Memory tasks route to workspace surface → gaia-operator.
+
+## Failures
+
+- Hook blocks a command -- relay the message verbatim, do not suggest alternatives
+- Routing unclear -- ask the user
+- Agents contradict -- present both sides, user decides

package/agents/gaia-system.md

@@ -11,6 +11,7 @@ skills:
   - investigation
   - command-execution
   - gaia-patterns
+  - gaia-release
   - skill-creation
 ---
 
@@ -47,7 +48,7 @@ You are the **meta-agent** — the agent that understands agents. Your specialty
 | Terraform / cloud infrastructure | `terraform-architect` |
 | Kubernetes / GitOps | `gitops-operator` |
 | Live cloud diagnostics | `cloud-troubleshooter` |
-| Application code | `devops-developer` |
+| Application code | `developer` |
 
 ## Domain Errors
 

package/agents/gitops-operator.md

@@ -46,7 +46,7 @@ You are a senior GitOps operator. You manage the entire lifecycle of Kubernetes
 |------|-------|
 | Terraform / cloud infrastructure | `terraform-architect` |
 | Query live cloud state (`gcloud`, `aws`) | `cloud-troubleshooter` |
-| Application code (Python, Node.js) | `devops-developer` |
+| Application code (Python, Node.js) | `developer` |
 | gaia-ops modifications | `gaia` |
 
 ## Domain Errors

package/agents/speckit-planner.md

@@ -58,7 +58,7 @@ If `speckit_root` resolves to a directory that does not exist, create it (T3 --
 | Execute tasks from tasks.md | Orchestrator (routes to agents) |
 | Execute infrastructure changes | `terraform-architect` |
 | Execute Kubernetes operations | `gitops-operator` |
-| Run application builds or tests | `devops-developer` |
+| Run application builds or tests | `developer` |
 | Diagnose cloud issues | `cloud-troubleshooter` |
 
 ## Domain Errors

package/agents/terraform-architect.md

@@ -17,10 +17,12 @@ skills:
 
 ## Workflow
 
-1. **Triage first**: When checking infrastructure state, run the fast-queries Terraform or cloud triage script before running plan/apply.
-2. **Deep analysis**: When investigating drift or complex module dependencies, follow the investigation phases.
-3. **Before T3 operations**: When `terragrunt apply` is needed, present a REVIEW plan first. If a hook blocks it, follow the AWAITING_APPROVAL flow.
-4. **Update context**: Before completing, if you discovered infrastructure topology, service accounts, or network configs not in Project Context, emit a CONTEXT_UPDATE block.
+1. **Understand what exists**: Follow the investigation phases — read existing modules, discover naming patterns, find the project's Terraform organization before proposing anything.
+2. **Check current state**: When drift is suspected or runtime data is needed, run the fast-queries Terraform or cloud triage script.
+3. **Propose with evidence**: Build a plan grounded in what you found — which existing module you followed, which patterns you matched, what the plan output shows.
+4. **Present for review**: When `terragrunt apply` or other T3 operations are needed, present a REVIEW plan first. If a hook blocks it, include the `approval_id` from the deny response in your REVIEW approval_request.
+5. **Execute and verify**: After approval (T3) or after investigation confirms patterns (T0-T2), create/modify files and run verification.
+6. **Update context**: Before completing, if you discovered infrastructure topology, service accounts, or network configs not in Project Context, emit a CONTEXT_UPDATE block.
 
 ## Identity
 
@@ -46,7 +48,7 @@ You are a senior Terraform architect. You manage the entire lifecycle of cloud i
 |------|-------|
 | Query live cloud state (`gcloud`, `aws`) | `cloud-troubleshooter` |
 | Kubernetes / Flux manifests | `gitops-operator` |
-| Application code (Python, Node.js) | `devops-developer` |
+| Application code (Python, Node.js) | `developer` |
 | gaia-ops modifications | `gaia` |
 
 ## Domain Errors

package/bin/README.md

@@ -146,4 +146,4 @@ npx gaia-scan --non-interactive
 
 ---
 
-**Version:** 4.5.0 | **Updated:** 2026-03-24 | **Scripts:** 11
+**Version:** 4.7.2 | **Updated:** 2026-04-09 | **Scripts:** 11

package/bin/gaia-doctor.js

@@ -93,17 +93,27 @@ async function checkSettingsJson() {
     const data = JSON.parse(await fs.readFile(path, 'utf-8'));
     const issues = [];
 
-    // Check hooks are configured
-    if (!data.hooks) {
-      issues.push('No hooks configured');
+    // Check hooks are configured — hooks may live in settings.json OR
+    // settings.local.json (gaia-update/gaia-scan puts them in local).
+    let hooksConfig = data.hooks || null;
+    const localPath = join(CWD, '.claude', 'settings.local.json');
+    if (!hooksConfig && existsSync(localPath)) {
+      try {
+        const localData = JSON.parse(await fs.readFile(localPath, 'utf-8'));
+        if (localData.hooks) hooksConfig = localData.hooks;
+      } catch { /* ignore parse errors */ }
+    }
+
+    if (!hooksConfig) {
+      issues.push('No hooks configured (check settings.json and settings.local.json)');
     } else {
-      const hookTypes = Object.keys(data.hooks);
+      const hookTypes = Object.keys(hooksConfig);
       if (!hookTypes.includes('PreToolUse')) issues.push('Missing PreToolUse hook');
       if (!hookTypes.includes('PostToolUse')) issues.push('Missing PostToolUse hook');
     }
 
     // Check permissions — now live in settings.local.json (not settings.json)
-    const localPath = join(CWD, '.claude', 'settings.local.json');
+    // localPath already declared above for hooks check
     let permCount = 0;
     if (existsSync(localPath)) {
       try {
@@ -125,7 +135,7 @@ async function checkSettingsJson() {
       return { name: 'settings.json', ok: false, detail: issues.join('; '), fix: 'Run gaia-scan or npx gaia-update' };
     }
 
-    const hookCount = data.hooks ? Object.keys(data.hooks).length : 0;
+    const hookCount = hooksConfig ? Object.keys(hooksConfig).length : 0;
     return { name: 'settings.json', ok: true, detail: `${hookCount} hook types, ${permCount} rules` };
   } catch {
     return { name: 'settings.json', ok: false, detail: 'Invalid JSON', fix: 'Delete and run gaia-scan' };

package/bin/gaia-history.js

@@ -125,7 +125,6 @@ function colorStatus(status) {
   if (s === 'NEEDS_INPUT') return chalk.yellow(s.padEnd(8));
   if (s === 'IN_PROGRESS') return chalk.cyan(s.padEnd(8));
   if (s === 'REVIEW') return chalk.magenta(s.padEnd(8));
-  if (s === 'AWAITING_APPROVAL') return chalk.yellow(s.padEnd(8));
   return chalk.gray(s.padEnd(8));
 }
 

package/bin/gaia-metrics.js

@@ -450,7 +450,7 @@ function calculateAgentInvocations(workflowMetrics) {
 
 /**
  * Agent outcome distribution from plan_status field.
- * Counts COMPLETE, BLOCKED, NEEDS_INPUT, IN_PROGRESS, REVIEW, AWAITING_APPROVAL, and others.
+ * Counts COMPLETE, BLOCKED, NEEDS_INPUT, IN_PROGRESS, REVIEW, and others.
  * Returns null if no entries have the plan_status field (older data).
  */
 function calculateAgentOutcomes(workflowMetrics) {
@@ -874,7 +874,7 @@ function displayMetrics(
   // ── Agent Outcomes ───────────────────────────────────
   if (agentOutcomes) {
     console.log(chalk.bold(`\n📋 Agent Outcomes  (${agentOutcomes.total} sessions with status)`));
-    const outcomeColor = { COMPLETE: chalk.green, BLOCKED: chalk.red, NEEDS_INPUT: chalk.yellow, IN_PROGRESS: chalk.cyan, REVIEW: chalk.magenta, AWAITING_APPROVAL: chalk.yellow };
+    const outcomeColor = { COMPLETE: chalk.green, BLOCKED: chalk.red, NEEDS_INPUT: chalk.yellow, IN_PROGRESS: chalk.cyan, REVIEW: chalk.magenta };
     for (const { status, count, percentage } of agentOutcomes.distribution) {
       const bar = makeBar(percentage, 10);
       const pct = percentage.toFixed(1).padStart(5);

package/bin/gaia-scan.py

@@ -205,6 +205,7 @@ def _mode_fresh(project_root: Path, scan_config: ScanConfig, args) -> int:
         generate_governance,
         generate_project_context,
         install_git_hooks,
+        merge_hooks_to_settings_local,
     )
     from tools.scan.ui import (
         RailUI,
@@ -246,6 +247,7 @@ def _mode_fresh(project_root: Path, scan_config: ScanConfig, args) -> int:
     create_claude_directory(project_root)
     copy_claude_md(project_root)
     copy_settings_json(project_root)
+    merge_hooks_to_settings_local(project_root)
     install_git_hooks(project_root)
     generate_project_context(project_root, config, scan_context=output.context)
     generate_governance(project_root, config)
@@ -287,6 +289,7 @@ def _mode_existing(project_root: Path, scan_config: ScanConfig, args) -> int:
         copy_settings_json,
         create_claude_directory,
         install_git_hooks,
+        merge_hooks_to_settings_local,
     )
     from tools.scan.ui import (
         RailUI,
@@ -317,6 +320,7 @@ def _mode_existing(project_root: Path, scan_config: ScanConfig, args) -> int:
     # Step 4: SYNC
     copy_claude_md(project_root)
     copy_settings_json(project_root)
+    merge_hooks_to_settings_local(project_root)
     create_claude_directory(project_root)
     install_git_hooks(project_root)