@jaguilar87/gaia-ops 4.4.0 → 4.7.2

package/bin/gaia-update.js

@@ -7,13 +7,21 @@
  * Also available as: npx gaia-update
  *
  * Behavior:
- * - First-time install (.claude/ doesn't exist): skip silently (gaia-scan handles it)
+ * - First-time install (.claude/ doesn't exist):
+ *   1. Check Python 3 is available
+ *   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. 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 (template is source of truth)
- *   3. Symlinks: recreate if missing, fix broken ones
- *   4. Verify: hooks, python, project-context, config files
- *   5. Report: summary with any issues found
+ *   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
  *
  * Usage:
  *   npm update @jaguilar87/gaia-ops   # Automatic via postinstall
@@ -72,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
-    await fs.copyFile(templatePath, settingsPath);
-    spinner.succeed('settings.json updated from template');
+    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}`);
@@ -92,6 +106,223 @@ async function updateSettingsJson() {
   }
 }
 
+async function updateLocalPermissions() {
+  const spinner = ora('Merging permissions 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;
+    }
+
+    // Load permissions from plugin_setup.py — the single source of truth.
+    // We use ast.literal_eval to extract the constants without importing
+    // the module (which has relative imports that fail standalone).
+    let gaiaPerms;
+    try {
+      const setupPath = join(__dirname, '..', 'hooks', 'modules', 'core', 'plugin_setup.py');
+      const { stdout } = await execAsync(
+        `python3 -c "
+import ast, json, re
+
+source = open('${setupPath.replace(/'/g, "\\'")}').read()
+
+# Extract _DENY_RULES list
+deny_match = re.search(r'^_DENY_RULES\\s*=\\s*\\[', source, re.MULTILINE)
+if deny_match:
+    bracket_start = deny_match.start() + source[deny_match.start():].index('[')
+    depth, i = 0, bracket_start
+    for i, ch in enumerate(source[bracket_start:], bracket_start):
+        if ch == '[': depth += 1
+        elif ch == ']': depth -= 1
+        if depth == 0: break
+    deny_rules = ast.literal_eval(source[bracket_start:i+1])
+else:
+    deny_rules = []
+
+# Extract OPS_PERMISSIONS allow list
+ops_match = re.search(r'^OPS_PERMISSIONS\\s*=', source, re.MULTILINE)
+if ops_match:
+    bracket_start = source.index('{', ops_match.start())
+    depth, i = 0, bracket_start
+    for i, ch in enumerate(source[bracket_start:], bracket_start):
+        if ch == '{': depth += 1
+        elif ch == '}': depth -= 1
+        if depth == 0: break
+    # Replace _DENY_RULES reference with actual list for eval
+    ops_str = source[bracket_start:i+1].replace('_DENY_RULES', json.dumps(deny_rules))
+    ops_perms = ast.literal_eval(ops_str)
+else:
+    ops_perms = {'permissions': {'allow': [], 'deny': deny_rules, 'ask': []}}
+
+print(json.dumps(ops_perms))
+"`,
+        { timeout: 10000 }
+      );
+      gaiaPerms = JSON.parse(stdout.trim());
+    } catch (pyError) {
+      spinner.warn(`Could not load permissions from Python — ${pyError.message || 'unknown error'}`);
+      return false;
+    }
+
+    const ourAllow = new Set(gaiaPerms.permissions.allow || []);
+    const ourDeny = new Set(gaiaPerms.permissions.deny || []);
+
+    // Load existing settings.local.json — preserve everything (enabledPlugins, MCP servers, etc.)
+    let existing = {};
+    if (existsSync(localPath)) {
+      try {
+        existing = JSON.parse(await fs.readFile(localPath, 'utf-8'));
+      } catch {
+        existing = {};
+      }
+    }
+
+    const perms = existing.permissions || {};
+    const currentAllow = new Set(perms.allow || []);
+    const currentDeny = new Set(perms.deny || []);
+
+    // Union merge — add ours without removing user's
+    const mergedAllow = [...new Set([...currentAllow, ...ourAllow])].sort();
+    const mergedDeny = [...new Set([...currentDeny, ...ourDeny])].sort();
+
+    // Check if anything changed
+    const allowChanged = mergedAllow.length !== currentAllow.size
+      || mergedAllow.some(r => !currentAllow.has(r));
+    const denyChanged = mergedDeny.length !== currentDeny.size
+      || mergedDeny.some(r => !currentDeny.has(r));
+
+    if (!allowChanged && !denyChanged) {
+      spinner.succeed('settings.local.json permissions already up to date');
+      return false;
+    }
+
+    // Update only permissions, preserve everything else
+    existing.permissions = existing.permissions || {};
+    existing.permissions.allow = mergedAllow;
+    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 and env merged');
+    return true;
+  } catch (error) {
+    spinner.fail(`settings.local.json: ${error.message}`);
+    return false;
+  }
+}
+
+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 {
@@ -206,7 +437,7 @@ async function runVerification() {
   }
 
   // 4. Config files accessible
-  const configFiles = ['classification-rules.json', 'git_standards.json', 'universal-rules.json'];
+  const configFiles = ['git_standards.json', 'universal-rules.json', 'surface-routing.json'];
   for (const cfg of configFiles) {
     const path = join(CWD, '.claude', 'config', cfg);
     if (existsSync(path)) {
@@ -218,7 +449,7 @@ async function runVerification() {
   }
 
   // 5. Agent definitions accessible
-  const agentFiles = ['terraform-architect.md', 'gitops-operator.md', 'cloud-troubleshooter.md', 'devops-developer.md', 'gaia.md'];
+  const agentFiles = ['terraform-architect.md', 'gitops-operator.md', 'cloud-troubleshooter.md', 'devops-developer.md', 'gaia-system.md', 'speckit-planner.md'];
   let agentsOk = 0;
   for (const agent of agentFiles) {
     if (existsSync(join(CWD, '.claude', 'agents', agent))) agentsOk++;
@@ -226,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;
@@ -256,48 +490,106 @@ async function runVerification() {
 // Main
 // ============================================================================
 
+async function runFreshInstall() {
+  const packageDir = join(__dirname, '..');
+  const scanScript = join(packageDir, 'bin', 'gaia-scan.py');
+  const { current } = await detectVersions();
+
+  console.log(chalk.cyan(`\n  gaia-ops ${chalk.green(current)} — fresh install\n`));
+
+  // 1. Check Python 3 is available
+  const spinner = ora('Checking Python 3...').start();
+  try {
+    await execAsync('python3 --version', { timeout: 5000 });
+    spinner.succeed('Python 3 found');
+  } catch {
+    spinner.warn('Python 3 not found — skipping project setup');
+    console.log(chalk.gray('  Install Python 3.9+ and run: npx gaia-scan\n'));
+    return;
+  }
+
+  // 2. Run gaia-scan --npm-postinstall
+  const scanSpinner = ora('Running gaia-scan...').start();
+  try {
+    const { stdout, stderr } = await execAsync(
+      `python3 "${scanScript}" --npm-postinstall --root "${CWD}"`,
+      { timeout: 60000 }
+    );
+    scanSpinner.succeed('Project scanned and configured');
+    if (VERBOSE && stdout) console.log(chalk.gray(stdout));
+    if (VERBOSE && stderr) console.log(chalk.yellow(stderr));
+  } catch (error) {
+    scanSpinner.warn('gaia-scan encountered issues (non-fatal)');
+    if (VERBOSE && error.stderr) console.log(chalk.gray(error.stderr));
+  }
+
+  // 3. Create plugin-registry.json (in .claude/, same path Python hooks expect)
+  try {
+    const claudeDirPath = join(CWD, '.claude');
+    if (!existsSync(claudeDirPath)) {
+      await fs.mkdir(claudeDirPath, { recursive: true });
+    }
+    const registryPath = join(claudeDirPath, 'plugin-registry.json');
+    const registry = {
+      installed: [{ name: 'gaia-ops', version: current || 'unknown' }],
+      source: 'npm-postinstall',
+    };
+    await fs.writeFile(registryPath, JSON.stringify(registry, null, 2) + '\n');
+  } catch {
+    // Non-fatal — plugin-registry is a convenience, not critical
+  }
+
+  // 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() {
   const claudeDir = join(CWD, '.claude');
   const isUpdate = existsSync(claudeDir);
 
   if (!isUpdate) {
-    // First-time install — gaia-scan handles everything
-    process.exit(0);
+    // First-time install — run gaia-scan to bootstrap everything
+    await runFreshInstall();
+  } else {
+    // Version info
+    const { previous, current } = await detectVersions();
+    const versionLine = previous && previous !== current
+      ? `${chalk.gray(previous)} → ${chalk.green(current)}`
+      : chalk.green(current);
+
+    console.log(chalk.cyan(`\n  gaia-ops update ${versionLine}\n`));
+
+    // Step 1-4: Update files
+    await updateSettingsJson();
+    await updateLocalPermissions();
+    await updateLocalHooks();
+    await updateSymlinks();
   }
 
-  // Version info
-  const { previous, current } = await detectVersions();
-  const versionLine = previous && previous !== current
-    ? `${chalk.gray(previous)} → ${chalk.green(current)}`
-    : chalk.green(current);
-
-  console.log(chalk.cyan(`\n  gaia-ops update ${versionLine}\n`));
-
-  // Step 1-2: Update files
-  const settingsUpdated = await updateSettingsJson();
-  const { updated: symlinksUpdated, fixed: symlinksFix } = await updateSymlinks();
+  // Ensure plugin-registry.json exists in .claude/ (both fresh and update)
+  try {
+    const registryPath = join(CWD, '.claude', 'plugin-registry.json');
+    if (!existsSync(registryPath)) {
+      const { current } = await detectVersions();
+      const registry = {
+        installed: [{ name: 'gaia-ops', version: current || 'unknown' }],
+        source: 'npm-postinstall',
+      };
+      await fs.writeFile(registryPath, JSON.stringify(registry, null, 2) + '\n');
+    }
+  } catch { /* non-fatal */ }
 
-  // Step 3: Verify
+  // Verify (runs for both fresh install and update)
   const { issues, passed, total } = await runVerification();
 
-  // Summary
-  const changes = [settingsUpdated, symlinksUpdated].filter(Boolean).length;
-
   console.log('');
-  if (changes > 0 || issues.length > 0) {
-    // Changes summary
-    if (changes > 0) {
-      console.log(chalk.green(`  ${changes} file(s) updated`));
-      if (settingsUpdated) console.log(chalk.gray('    settings.json: replaced from template'));
-      if (symlinksFix > 0) console.log(chalk.gray(`    ${symlinksFix} symlink(s) fixed`));
-    }
-
-    // Issues
-    if (issues.length > 0) {
-      console.log(chalk.yellow(`\n  ${issues.length} issue(s) found:`));
-      for (const issue of issues) {
-        console.log(chalk.yellow(`    - ${issue}`));
-      }
+  if (issues.length > 0) {
+    console.log(chalk.yellow(`  ${issues.length} issue(s) found:`));
+    for (const issue of issues) {
+      console.log(chalk.yellow(`    - ${issue}`));
     }
   } else {
     console.log(chalk.green('  Everything up to date'));

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)