@jaguilar87/gaia-ops 4.5.0 → 4.7.2

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": "4.7.2",
       "source": "./dist/gaia-security"
     }
   ]

package/.claude-plugin/plugin.json

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

package/ARCHITECTURE.md

@@ -25,7 +25,8 @@ User request
     v
 user_prompt_submit.py  (UserPromptSubmit hook)
     |  Inject orchestrator identity via ops_identity.py
-    |  Skills loaded on-demand: project-dispatch, agent-response
+    |  Inject surface routing recommendation (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
 ```
@@ -170,7 +171,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 +183,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,12 +257,12 @@ 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) |
 
@@ -292,7 +293,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.
 
@@ -311,7 +312,7 @@ 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) |
+| `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/agents/terraform-architect.md

@@ -19,7 +19,7 @@ skills:
 
 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.
+3. **Before T3 operations**: When `terragrunt apply` is needed, present a REVIEW plan first. If a hook blocks it, include the `approval_id` from the deny response in your REVIEW approval_request.
 4. **Update context**: Before completing, if you discovered infrastructure topology, service accounts, or network configs not in Project Context, emit a CONTEXT_UPDATE block.
 
 ## Identity

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)
 

package/bin/gaia-update.js

@@ -12,12 +12,14 @@
  *   2. Run gaia-scan --npm-postinstall to create .claude/, symlinks, settings, project-context
  *   3. Create plugin-registry.json
  *   4. Merge permissions into settings.local.json
- *   5. Fall through to verification
+ *   5. Merge hooks into settings.local.json
+ *   6. Fall through to verification
  * - Update (.claude/ exists):
  *   1. Show version transition (previous → current)
- *   2. settings.json: REPLACE from template (hooks only — no permissions)
- *   3. Merge permissions into settings.local.json (union, preserves user config)
- *   4. Symlinks: recreate if missing, fix broken ones
+ *   2. settings.json: create only if missing (non-invasive, never overwrites)
+ *   3. Merge permissions + env vars into settings.local.json (union, preserves user config)
+ *   4. Merge hooks from hooks.json into settings.local.json (npm mode requires this)
+ *   5. Symlinks: recreate if missing, fix broken ones
  *   5. Verify: hooks, python, project-context, config files
  *   6. Report: summary with any issues found
  *
@@ -78,19 +80,25 @@ async function readPackageVersion(path) {
 // ============================================================================
 
 async function updateSettingsJson() {
-  const spinner = ora('Updating settings.json...').start();
+  const spinner = ora('Checking settings.json...').start();
   try {
-    const templatePath = join(__dirname, '../templates/settings.template.json');
     const settingsPath = join(CWD, '.claude', 'settings.json');
 
-    if (!existsSync(templatePath) || !existsSync(join(CWD, '.claude'))) {
-      spinner.info('Skipped');
+    if (!existsSync(join(CWD, '.claude'))) {
+      spinner.info('Skipped (.claude/ not found)');
+      return false;
+    }
+
+    // Non-invasive: only create if missing. Never overwrite.
+    // Hooks come from hooks.json (auto-discovered via symlink).
+    // Env vars and permissions live in settings.local.json.
+    if (existsSync(settingsPath)) {
+      spinner.succeed('settings.json already exists (not overwriting)');
       return false;
     }
 
-    // Always replace from template -- template is the source of truth (hooks only)
-    await fs.copyFile(templatePath, settingsPath);
-    spinner.succeed('settings.json updated from template (hooks)');
+    await fs.writeFile(settingsPath, '{}\n');
+    spinner.succeed('settings.json created (minimal — hooks from hooks.json)');
     return true;
   } catch (error) {
     spinner.fail(`settings.json: ${error.message}`);
@@ -197,8 +205,14 @@ print(json.dumps(ops_perms))
     existing.permissions.deny = mergedDeny;
     existing.permissions.ask = existing.permissions.ask || [];
 
+    // Add env vars (smart merge: add if not present, don't overwrite)
+    existing.env = existing.env || {};
+    if (!('CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS' in existing.env)) {
+      existing.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
+    }
+
     await fs.writeFile(localPath, JSON.stringify(existing, null, 2) + '\n');
-    spinner.succeed('settings.local.json permissions merged');
+    spinner.succeed('settings.local.json permissions and env merged');
     return true;
   } catch (error) {
     spinner.fail(`settings.local.json: ${error.message}`);
@@ -206,6 +220,109 @@ print(json.dumps(ops_perms))
   }
 }
 
+async function updateLocalHooks() {
+  const spinner = ora('Merging hooks into settings.local.json...').start();
+  try {
+    const claudeDir = join(CWD, '.claude');
+    const localPath = join(claudeDir, 'settings.local.json');
+
+    if (!existsSync(claudeDir)) {
+      spinner.info('Skipped (.claude/ not found)');
+      return false;
+    }
+
+    // Read hooks.json from the installed package
+    const hooksJsonPath = join(__dirname, '..', 'hooks', 'hooks.json');
+    if (!existsSync(hooksJsonPath)) {
+      spinner.warn('hooks.json not found in package');
+      return false;
+    }
+
+    let hooksData;
+    try {
+      hooksData = JSON.parse(await fs.readFile(hooksJsonPath, 'utf-8'));
+    } catch {
+      spinner.warn('hooks.json is invalid JSON');
+      return false;
+    }
+
+    // Unwrap outer "hooks" key if present
+    const sourceHooks = hooksData.hooks || hooksData;
+
+    // Convert ${CLAUDE_PLUGIN_ROOT}/hooks/<script> to .claude/hooks/<script> for npm mode
+    const convertCommand = (cmd) => {
+      return cmd.replace(/\$\{CLAUDE_PLUGIN_ROOT\}\/hooks\//g, '.claude/hooks/');
+    };
+
+    const convertedHooks = {};
+    for (const [event, entries] of Object.entries(sourceHooks)) {
+      convertedHooks[event] = entries.map(entry => {
+        const converted = { ...entry };
+        if (converted.hooks) {
+          converted.hooks = converted.hooks.map(h => ({
+            ...h,
+            command: h.command ? convertCommand(h.command) : h.command,
+          }));
+        }
+        return converted;
+      });
+    }
+
+    // Load existing settings.local.json
+    let existing = {};
+    if (existsSync(localPath)) {
+      try {
+        existing = JSON.parse(await fs.readFile(localPath, 'utf-8'));
+      } catch {
+        existing = {};
+      }
+    }
+
+    // Smart merge: for each hook event, deduplicate by command string
+    const existingHooks = existing.hooks || {};
+    let changed = false;
+
+    for (const [event, newEntries] of Object.entries(convertedHooks)) {
+      if (!existingHooks[event]) {
+        existingHooks[event] = newEntries;
+        changed = true;
+        continue;
+      }
+
+      // Collect existing command strings for deduplication
+      const existingCommands = new Set();
+      for (const entry of existingHooks[event]) {
+        for (const h of (entry.hooks || [])) {
+          if (h.command) existingCommands.add(h.command);
+        }
+      }
+
+      // Add new entries whose commands are not already present
+      for (const newEntry of newEntries) {
+        const newCommands = (newEntry.hooks || []).map(h => h.command).filter(Boolean);
+        const allPresent = newCommands.length > 0 && newCommands.every(c => existingCommands.has(c));
+        if (!allPresent) {
+          existingHooks[event].push(newEntry);
+          changed = true;
+        }
+      }
+    }
+
+    if (!changed) {
+      spinner.succeed('settings.local.json hooks already up to date');
+      return false;
+    }
+
+    existing.hooks = existingHooks;
+    await fs.writeFile(localPath, JSON.stringify(existing, null, 2) + '\n');
+    spinner.succeed('settings.local.json hooks merged');
+    return true;
+  } catch (error) {
+    spinner.fail(`hooks merge: ${error.message}`);
+    return false;
+  }
+}
+
 async function updateSymlinks() {
   const spinner = ora('Checking symlinks...').start();
   try {
@@ -340,18 +457,21 @@ async function runVerification() {
   checks.push({ name: 'agent definitions', ok: agentsOk === agentFiles.length, detail: `${agentsOk}/${agentFiles.length}` });
   if (agentsOk < agentFiles.length) issues.push(`${agentFiles.length - agentsOk} agent definition(s) missing`);
 
-  // 6. settings.json has hooks configured
-  const settingsPath = join(CWD, '.claude', 'settings.json');
-  if (existsSync(settingsPath)) {
+  // 6. hooks.json exists (hooks are auto-discovered from hooks directory)
+  const hooksJsonPath = join(CWD, '.claude', 'hooks', 'hooks.json');
+  if (existsSync(hooksJsonPath)) {
     try {
-      const settings = JSON.parse(await fs.readFile(settingsPath, 'utf-8'));
-      const hasHooks = settings.hooks && Object.keys(settings.hooks).length > 0;
-      checks.push({ name: 'hooks config', ok: hasHooks });
-      if (!hasHooks) issues.push('settings.json has no hooks configured');
+      const hooksData = JSON.parse(await fs.readFile(hooksJsonPath, 'utf-8'));
+      const hasHooks = hooksData.hooks && Object.keys(hooksData.hooks).length > 0;
+      checks.push({ name: 'hooks.json', ok: hasHooks });
+      if (!hasHooks) issues.push('hooks.json has no hooks configured');
     } catch {
-      checks.push({ name: 'hooks config', ok: false });
-      issues.push('settings.json is invalid');
+      checks.push({ name: 'hooks.json', ok: false });
+      issues.push('hooks.json is invalid');
     }
+  } else {
+    checks.push({ name: 'hooks.json', ok: false });
+    issues.push('hooks.json not found (hooks symlink may be broken)');
   }
 
   const passed = checks.filter(c => c.ok).length;
@@ -421,6 +541,9 @@ async function runFreshInstall() {
 
   // 4. Merge permissions into settings.local.json (same approach as plugin mode)
   await updateLocalPermissions();
+
+  // 5. Merge hooks into settings.local.json (npm mode — Claude Code reads hooks from settings, not hooks.json)
+  await updateLocalHooks();
 }
 
 async function main() {
@@ -439,9 +562,10 @@ async function main() {
 
     console.log(chalk.cyan(`\n  gaia-ops update ${versionLine}\n`));
 
-    // Step 1-3: Update files
+    // Step 1-4: Update files
     await updateSettingsJson();
     await updateLocalPermissions();
+    await updateLocalHooks();
     await updateSymlinks();
   }
 

package/bin/pre-publish-validate.js

@@ -46,10 +46,10 @@ function detectGaiaOpsRoot(startPath) {
 // Buscar node_modules de múltiples maneras
 function findNodeModulesPath(gaiaOpsRoot) {
   const candidates = [
-    path.resolve(gaiaOpsRoot, '..', 'node_modules'),           // ../node_modules
-    path.resolve(gaiaOpsRoot, 'node_modules'),                 // ./node_modules
+    path.resolve(gaiaOpsRoot, 'node_modules'),                 // ./node_modules (CI: npm ci in repo root)
+    path.resolve(gaiaOpsRoot, '..', 'node_modules'),           // ../node_modules (monorepo consumer)
     path.resolve(process.cwd(), 'node_modules'),               // cwd/node_modules
-    path.join(gaiaOpsRoot, '..', '..', 'node_modules'),        // ../../node_modules
+    path.join(gaiaOpsRoot, '..', '..', 'node_modules'),        // ../../node_modules (deep nesting)
   ];
 
   for (const candidate of candidates) {
@@ -59,8 +59,16 @@ function findNodeModulesPath(gaiaOpsRoot) {
     }
   }
 
-  // Si no encuentra, retorna la ruta esperada (será creada por npm install)
-  return path.resolve(gaiaOpsRoot, '..', 'node_modules');
+  // In CI, node_modules exists inside the repo root (npm ci) but won't contain
+  // the package itself as a nested dependency. Prefer gaiaOpsRoot/node_modules
+  // over going up a level (which breaks in CI checkout structures).
+  const localNodeModules = path.resolve(gaiaOpsRoot, 'node_modules');
+  if (fs.existsSync(localNodeModules)) {
+    return localNodeModules;
+  }
+
+  // Fallback: use __dirname-relative path (repo root) instead of process.cwd()
+  return path.resolve(gaiaOpsRoot, 'node_modules');
 }
 
 const GAIA_OPS_ROOT = detectGaiaOpsRoot(path.resolve(__dirname, '..'));
@@ -219,14 +227,21 @@ class PrePublishValidator {
   }
 
   reinstallNodeModules() {
-    this.log('Reinstalling node_modules in monorepo...', 'info');
+    this.log('Reinstalling node_modules...', 'info');
 
     if (this.dryRun) {
       this.log('[DRY RUN] Would run: npm install', 'info');
       return;
     }
 
-    this.execute('npm install', MONOREPO_ROOT);
+    // In CI, MONOREPO_ROOT may resolve incorrectly (one level above checkout).
+    // Use GAIA_OPS_ROOT if it contains a package.json (i.e., we ARE the root).
+    const installDir = fs.existsSync(path.join(GAIA_OPS_ROOT, 'package-lock.json'))
+      ? GAIA_OPS_ROOT
+      : MONOREPO_ROOT;
+
+    this.log(`Install directory: ${installDir}`, 'info');
+    this.execute('npm install', installDir);
     this.log('✓ npm install completed', 'success');
   }
 
@@ -238,7 +253,6 @@ class PrePublishValidator {
       'bin/gaia-scan',
       'tools/context/context_provider.py',
       'hooks/pre_tool_use.py',
-      'templates/settings.template.json'
     ];
 
     let allValid = true;
@@ -330,7 +344,6 @@ class PrePublishValidator {
       // Test 1: Validate JSON files
       this.log('Test 1: Validating JSON configuration files...', 'info');
       const jsonFiles = [
-        'templates/settings.template.json',
         'config/clarification_rules.json',
         'config/git_standards.json'
       ];
@@ -505,12 +518,22 @@ class PrePublishValidator {
 // Parse command line arguments and run
 async function main() {
   const args = process.argv.slice(2);
+  const isCI = process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true';
+
   const options = {
     dryRun: args.includes('--dry-run'),
-    validateOnly: args.includes('--validate-only'),
+    validateOnly: args.includes('--validate-only') || isCI,
     versionBump: 'patch'
   };
 
+  if (isCI && !args.includes('--validate-only')) {
+    console.log(chalk.blue(
+      '[CI] Auto-enabling --validate-only: ' +
+      'self-install validation is not possible during npm publish ' +
+      '(package is not yet on the registry).'
+    ));
+  }
+
   if (args.includes('major')) options.versionBump = 'major';
   if (args.includes('minor')) options.versionBump = 'minor';
   if (args.includes('patch')) options.versionBump = 'patch';

package/commands/gaia.md

@@ -0,0 +1,37 @@
+---
+name: gaia
+description: Invoke the Gaia meta-agent for system architecture analysis, agent design, skill creation, and orchestration debugging
+allowed-tools:
+  - Bash(*)
+  - Read
+  - Edit
+  - Write
+  - Glob
+  - Grep
+  - WebSearch
+  - WebFetch
+  - Task
+  - Agent
+  - Skill
+---
+
+Invoke the Gaia meta-agent (`gaia-system`) to work on the gaia-ops orchestration
+system itself. This is the entry point for tasks that modify or analyze agents,
+skills, hooks, or system architecture.
+
+## When to use
+
+- Analyze or improve the gaia-ops architecture
+- Create or update agent definitions (`.md` files)
+- Create or update skills (`SKILL.md` files)
+- Write or debug Python hooks and tools
+- Update `CLAUDE.md` or system configuration
+- Research best practices for agent orchestration
+
+## How it works
+
+This command delegates to the `gaia-system` agent, which is the meta-agent
+specialized in the orchestration system. It follows the standard agent protocol
+and returns a `json:contract` block with findings and status.
+
+$ARGUMENTS

package/config/README.md

@@ -6,11 +6,9 @@ Central configuration for the orchestration system. Contracts are the SSOT for a
 
 | File | Purpose | Read by |
 |------|---------|---------|
-| `context-contracts.json` | Base cloud-agnostic contracts: `read`/`write` sections per agent | `context_provider.py`, `context_writer.py`, `pre_tool_use.py` |
+| `context-contracts.json` | Base cloud-agnostic contracts: `read`/`write` sections per agent, `core_sections` list, `workspace_repos` schema | `context_provider.py`, `context_writer.py`, `pre_tool_use.py` |
 | `cloud/gcp.json` | GCP extensions: `gcp_services`, `workload_identity`, `static_ips` | Same trio, merged at runtime |
 | `cloud/aws.json` | AWS extensions: `vpc_mapping`, `load_balancers`, `api_gateway`, `irsa_bindings`, `aws_accounts` | Same trio, merged at runtime |
-| `context-contracts.gcp.json` | **Legacy** -- kept for backward compatibility | Fallback if `context-contracts.json` not found |
-| `context-contracts.aws.json` | **Legacy** -- kept for backward compatibility | Fallback if `context-contracts.json` not found |
 | `git_standards.json` | Commit standards (Conventional Commits), allowed types, forbidden footers | `hooks/modules/validation/commit_validator.py` |
 | `universal-rules.json` | Behavior rules injected into all agents | `context_provider.py` |
 | `surface-routing.json` | Generic surface classification and investigation-brief rules | `surface_router.py`, `context_provider.py`, Spec-Kit |
@@ -27,18 +25,14 @@ At runtime, `tools/context/context_provider.py` executes the following logic:
 5. Result: complete contract for the agent on that cloud
 ```
 
-Fallback if `context-contracts.json` not found: uses `context-contracts.{provider}.json` (legacy).
-
 ## Structure
 
 ```
 config/
-├── context-contracts.json        <- agnostic base (all agents)
+├── context-contracts.json        <- agnostic base (all agents, v4)
 ├── cloud/
 │   ├── gcp.json                  <- GCP extensions + section_schemas
 │   └── aws.json                  <- AWS extensions + section_schemas
-├── context-contracts.gcp.json    <- legacy (fallback)
-├── context-contracts.aws.json    <- legacy (fallback)
 ├── surface-routing.json          <- generic surface routing + investigation brief config
 ├── git_standards.json
 ├── universal-rules.json
@@ -61,4 +55,4 @@ config/
 
 ---
 
-**Updated:** 2026-03-03 | **Active contracts:** base + 2 clouds (GCP, AWS)
+**Updated:** 2026-03-25 | **Active contracts:** base v4 + 2 clouds (GCP, AWS)