@jaguilar87/gaia 5.0.2 → 5.0.5

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "gaia-ops",
       "description": "Full DevOps orchestration for Claude Code. Eight specialized agents handle the complete development lifecycle — analysis, planning, execution, and deployment. Gaia-Ops scans your codebase to understand it and injects the right context into each sub-agent. Every command is classified by risk: read-only runs freely, state changes pause for your approval, and irreversible operations are permanently blocked.",
-      "version": "5.0.2",
+      "version": "5.0.5",
       "category": "devops",
       "author": {
         "name": "jaguilar87",
@@ -20,7 +20,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": "5.0.2",
+      "version": "5.0.5",
       "category": "security",
       "author": {
         "name": "jaguilar87",

package/.claude-plugin/plugin.json

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

package/ARCHITECTURE.md

@@ -72,7 +72,6 @@ Order is short-circuit -- first match wins:
    |                          If mutative + no active grant -> generate nonce, block
    |                          If mutative + active grant -> allow (T3)
    |                          If not mutative -> safe by elimination (T0)
-6. gitops_validator       --> GitOps policy for kubectl/helm/flux
 ```
 
 ### Task/Agent Validation

package/CHANGELOG.md

@@ -7,6 +7,116 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.0.5] - 2026-06-11
+
+### Repository Hygiene, Python 3.11 Floor, v18 Schema Floor + Drift Guard, Release-Pipeline Hardening
+
+Maintenance release focused on shrinking the surface area and hardening the release pipeline. Dead and redundant surfaces are removed, Python 3.9 support is dropped (minimum is now 3.11), the database migration history is collapsed to a v18 floor backed by a new build-time schema-drift guard, git-format rules are inlined into their single consumer, and several release-pipeline bugs that caused CI re-triggers and stale local installs are fixed.
+
+#### Added
+
+- **Schema-drift guard wired into pre-publish validation** — a new build/pre-publish
+  check (`scripts/check_schema_drift.py` + a recorded fingerprint in
+  `scripts/migrations/schema.checksum`, wired into pre-publish-validate **Step 5c**)
+  fails the build if `gaia/store/schema.sql` changes without a matching schema version
+  bump and migration. This makes silent schema drift impossible to ship: any edit to
+  the schema must be accompanied by a version bump, or the gate stops the release.
+
+#### Changed
+
+- **Python minimum is now 3.11 (Python 3.9 dropped)** — `pyproject.toml`
+  `requires-python`, the ruff target version, and the CI test matrix all move to 3.11
+  as the floor. The dead `scripts/check-py39-compat.py` compatibility checker and its
+  npm alias are removed along with the 3.9 support.
+
+- **Database migration history collapsed to a v18 floor** — fresh installs now stamp
+  schema **v18** directly instead of replaying the full migration chain. Databases below
+  the v18 floor are rejected cleanly with guidance to recreate, rather than attempting an
+  unsupported incremental upgrade. The per-step `vN_to_vN+1` migration SQL and their
+  obsolete version-specific tests are removed.
+
+- **Git commit-format rules inlined into their single consumer** — the commit-format
+  rules previously in `config/git_standards.json` are inlined directly into
+  `commit_validator.py` (its only reader), and the standalone config file is removed.
+  Forbidden-footer enforcement is consolidated into `bash_validator` (the duplicate dead
+  check is removed); runtime AI-attribution footer stripping continues to live in
+  `bash_validator`. The git-conventions skill is updated to match.
+
+- **Release pipeline hardened** — `publish.yml` now runs on Python 3.11 and appends
+  `[skip ci]` to the dist commit-back, stopping the CI re-trigger / version-churn loop
+  that re-ran the pipeline on every published dist commit. `gaia:install-local` now
+  rebuilds plugins before packing so a local install can never carry a stale `dist/`.
+  `ci.yml` drops the obsolete `settings.json` build assertions, and the gaia-release
+  skill drift is corrected.
+
+- **pytest tmp uses the default OS tmpdir** — the in-repo pytest `basetemp` that
+  polluted the working tree (and broke scanner project-identity isolation) is removed;
+  tests now use the default OS temporary directory. `config/README.md` is rewritten to
+  match the actual directory contents.
+
+#### Removed
+
+- **Dead and redundant surfaces and artifacts** — removed `evidence/`, `docs/`,
+  `git-hooks/` (the redundant `commit-msg` sed copy; runtime footer stripping stays in
+  `bash_validator`), `tools/agentic-loop/`, `tools/review/`, `logs/`, the `commands/`
+  slash-command surface (including `/gaia`), the `templates/` managed-settings surface,
+  and `config/crons-schema.md`. These were either unused, duplicated by an active code
+  path, or superseded surfaces with no remaining consumer.
+
+## [5.0.4] - 2026-06-06
+
+### COMMAND_SET Batch Approval, Consent-Reducing Approval Verbs, Contract Advisory Field, Version Source Sync
+
+Patch release superseding 5.0.3 (which was never published to npm due to a pyproject.toml version drift that failed pre-publish validation). This release adds the version source sync fix on top of all 5.0.3 changes: COMMAND_SET batch-approval wired end-to-end, consent-reducing approval verbs reclassified out of T3, advisory contract field added, redundant `gitops_validator` removed, and all version sources (package.json, pyproject.toml, .claude-plugin/plugin.json, .claude-plugin/marketplace.json, CHANGELOG.md) aligned. Full suite green (4555 passed).
+
+#### Added
+
+- **COMMAND_SET batch approval, end-to-end** — a payload carrying a `command_set`
+  of more than one mutative command now activates into ONE `COMMAND_SET` grant
+  covering the whole batch instead of being degraded to a single command. The
+  create side (`activate_db_pending_by_prefix` Step 3b in `approval_grants.py`,
+  fed by `_intake_command_set_pending` in `handoff_persister.py` and persisted via
+  `gaia/store/writer.py`) was previously orphaned; it is now wired to the
+  byte-for-byte consume path in `bash_validator`. The batch is consumed
+  item-by-item under a single consent.
+
+- **Advisory `user_facing_summary` field on the agent contract** — an additive,
+  optional field in the `agent_contract_handoff` envelope (`contract_validator.py`,
+  `response_contract.py`) carrying a human-readable summary for the orchestrator to
+  surface. Purely additive; absence does not affect validation.
+
+#### Changed
+
+- **Consent-reducing approval verbs are no longer T3** — `gaia approvals
+  revoke|reject|reject-all|clean` only revoke or discard grants Gaia itself issued
+  (they reduce capability, never reach remote state), so they are reclassified out
+  of T3 via `CONSENT_REDUCING_SUBCOMMAND_EXCEPTIONS` in `mutative_verbs.py`. `gaia
+  approvals approve` *grants* capability and remains T3.
+
+- **`gaia approvals revoke` unified with auto-detect** — `revoke` now auto-detects
+  a pending approval (pending → grant) and the separate `revoke-v2` command was
+  removed. Behavior is otherwise unchanged.
+
+- **Plan-first heuristic** — COMMAND_SET is now treated as a judgment call, not a
+  default, when deciding how to present batched mutative work.
+
+#### Fixed
+
+- **Guard empty/None `transcript_path`** — `transcript_reader.py` now guards against
+  an empty or `None` transcript path instead of failing downstream during nonce
+  extraction.
+
+- **Harden AI-attribution footer stripping** — the attribution-footer stripping in
+  `bash_validator.py` is hardened against additional footer shapes.
+
+#### Removed
+
+- **Redundant `gitops_validator`** — `hooks/modules/security/gitops_validator.py` and
+  its test are removed; its responsibilities are covered by the unified bash
+  validation path. All references (security `__init__`, `bash_validator` import/call,
+  simulator extractor, surface-routing config, architecture docs, and skill/README
+  references) are cleaned up.
+
 ## [5.0.2] - 2026-06-03
 
 ### Approval-Flow Hardening, mkdir Reclassification, Jira Skill

package/INSTALL.md

@@ -172,7 +172,6 @@ your-project/
 │   ├── hooks/ (symlink)           → Security validations
 │   ├── commands/ (symlink)        → Slash commands
 │   ├── config/ (symlink)          → Configuration (contracts, rules)
-│   ├── templates/ (symlink)       → Installation templates
 │   ├── logs/                      ← Audit logs
 │   ├── approvals/                 ← Pending T3 approval files
 │   ├── plugin-registry.json       ← installed[].name = "gaia-ops"
@@ -204,7 +203,6 @@ Once installed, you have access to **complete documentation** in each directory:
 ├── config/README.md      Contracts, git standards, surface routing
 ├── hooks/README.md       8 hook scripts (4 primary + 4 event handlers)
 ├── tools/                Context, memory, validation, review
-├── templates/README.md   Installation templates
 └── bin/README.md         CLI utilities
 ```
 

package/README.md

@@ -21,7 +21,7 @@ UserPromptSubmit  ->  routing  ->  PreToolUse  ->  agent  ->  PostToolUse  ->  S
                                      injection
 ```
 
-That pipeline is the spine. Everything else in this repo is either a component of that pipeline (`hooks/`, `agents/`, `skills/`, `config/`) or infrastructure that supports it (`build/`, `bin/`, `tests/`, `templates/`). Start with the folder that matches the behavior you want to understand, and its README will tell you where it fits in the flow.
+That pipeline is the spine. Everything else in this repo is either a component of that pipeline (`hooks/`, `agents/`, `skills/`, `config/`) or infrastructure that supports it (`build/`, `bin/`, `tests/`). Start with the folder that matches the behavior you want to understand, and its README will tell you where it fits in the flow.
 
 ## Overview
 
@@ -150,10 +150,6 @@ Gaia enforces a 6-layer security pipeline:
 | Mutative verb detection | `ask` dialog for state-changing ops | User approves via native dialog |
 | Settings deny rules | 147 deny rules in `settings.local.json` | Self-healing (restored each session) |
 
-### Enterprise Deployment
-
-For organization-wide enforcement, deploy `templates/managed-settings.template.json` as a managed settings policy via Claude.ai Admin Console. Managed settings have the highest precedence and cannot be overridden.
-
 ## Project Structure
 
 ```
@@ -164,7 +160,6 @@ gaia-dev/
 ├── config/              # Configuration — routing, contracts, rules, git standards
 ├── commands/            # Slash commands — /gaia, /scan-project
 ├── build/               # Plugin manifests — hook + agent registration for Claude Code
-├── templates/           # Installation templates — managed-settings for enterprise
 ├── bin/                 # Single `gaia` CLI; subcommands discovered from bin/cli/
 ├── tests/               # Test suite — 3-layer pyramid (pytest, LLM eval, e2e)
 └── tools/               # Context provisioning tools

package/bin/README.md

@@ -110,6 +110,5 @@ A single binary; subcommands are discovered, not registered.
 
 - [`package.json`](../package.json) -- exposes `bin/gaia`; `scripts.postinstall` / `scripts.preuninstall` wire the lifecycle subcommands
 - [`INSTALL.md`](../INSTALL.md) -- installation workflow that calls `gaia scan` and `gaia install`
-- [`templates/README.md`](../templates/README.md) -- `gaia install` and `gaia scan` consume templates from here
 - [`hooks/README.md`](../hooks/README.md) -- `gaia doctor` verifies the hook registrations are valid
 - [`bin/validate-sandbox.sh`](./validate-sandbox.sh) -- end-to-end harness that drives `gaia` subcommands against a fresh tarball install

package/bin/cli/_install_helpers.py

@@ -345,7 +345,7 @@ def merge_local_hooks(
 # ---------------------------------------------------------------------------
 
 # Directories the package exposes via .claude/<name> symlinks
-_SYMLINK_NAMES = ["agents", "tools", "hooks", "commands", "templates", "config", "skills"]
+_SYMLINK_NAMES = ["agents", "tools", "hooks", "commands", "config", "skills"]
 # Files (not dirs) we link or copy into .claude/
 _SYMLINK_FILES = ["CHANGELOG.md"]
 

package/bin/cli/approvals.py

@@ -440,13 +440,17 @@ def cmd_show(args) -> int:
 # Subcommand: revoke
 # ---------------------------------------------------------------------------
 
-def cmd_revoke(args) -> int:
-    """Revoke an active command_set grant by its approval_id.
+def _revoke_grant(args) -> int:
+    """Revoke an active command_set grant by its approval_id (legacy path).
 
     Calls ``writer.revoke_approval_grant(approval_id)`` to mark the grant
     REVOKED in the DB.  After revocation, any unconsumed commands in the
     command_set will require fresh approval.
 
+    This is the legacy ``approval_grants``-table path. It is invoked as the
+    fallback by the unified :func:`cmd_revoke` when an id is not found in the
+    new ``approvals`` table.
+
     Exits 0 on success, 1 if the grant is not found or already in a terminal
     state.
     """
@@ -939,18 +943,14 @@ def cmd_pending(args) -> int:
 # ---------------------------------------------------------------------------
 
 def _resolve_approval_id(raw_id: str) -> str:
-    """Normalize a raw approval_id input.
+    """Normalize a raw approval_id input by trimming surrounding whitespace.
 
-    Accepts:
-      - Full P-{uuid4hex} form: returned as-is.
-      - Bare hex (no P- prefix): prefixed with 'P-'.
-      - P-XXXX short form: returned as-is for prefix search downstream.
+    The input is passed through unchanged otherwise -- both the full
+    ``P-{uuid4hex}`` form and the ``P-XXXX`` short form are returned as-is for
+    exact or prefix lookup downstream. (A bare hex string with no ``P-`` prefix
+    is also returned untouched; the lookup layer handles that case.)
     """
-    stripped = raw_id.strip()
-    if stripped.upper().startswith("P-"):
-        return stripped
-    # Try to detect if it's a bare hex string missing the P- prefix.
-    return stripped
+    return raw_id.strip()
 
 
 def cmd_show_v2(args) -> int:
@@ -1019,14 +1019,16 @@ def cmd_history_single(args) -> int:
 
 
 # ---------------------------------------------------------------------------
-# T3.2: gaia approvals revoke-v2 <id> -- revoke using new approvals table
+# gaia approvals revoke <id> -- unified revoke (auto-detects pending vs grant)
 # ---------------------------------------------------------------------------
 
-def cmd_revoke_v2(args) -> int:
-    """Revoke a pending approval from the new approvals table.
+def cmd_revoke(args) -> int:
+    """Revoke an approval, auto-detecting which store owns it.
 
-    Inserts a REVOKED event and updates status to 'revoked'. Requires
-    the approval to be in 'pending' status.
+    First looks the id up in the new ``approvals`` table. If found and
+    ``pending``, inserts a REVOKED event and updates status to 'revoked'.
+    If the id is not present in the new table, falls back to the legacy
+    command_set grant path (:func:`_revoke_grant`).
 
     With ``--yes``, skips the interactive confirmation prompt.
     Exits 0 on success, 1 on error.
@@ -1042,8 +1044,8 @@ def cmd_revoke_v2(args) -> int:
         return 1
 
     if approval is None:
-        # Fall back to old revoke command if not found in new table.
-        return cmd_revoke(args)
+        # Fall back to legacy grant revoke if not found in new table.
+        return _revoke_grant(args)
 
     current_status = approval.get("status", "?")
     if current_status != "pending":
@@ -1596,7 +1598,7 @@ def register(subparsers) -> None:
         help="Full approval_id (P-{uuid4hex}) of the approval to revoke",
     )
     p_revoke.add_argument("--yes", action="store_true", help="Skip confirmation prompt")
-    p_revoke.set_defaults(func=cmd_revoke_v2)
+    p_revoke.set_defaults(func=cmd_revoke)
 
     # approve (T3.3) -- cross-session grant
     p_approve = sub.add_parser(
@@ -1839,7 +1841,7 @@ def _build_standalone_parser() -> argparse.ArgumentParser:
     p_revoke = subparsers.add_parser("revoke", help="Revoke a pending approval")
     p_revoke.add_argument("approval_id", metavar="APPROVAL_ID")
     p_revoke.add_argument("--yes", action="store_true")
-    p_revoke.set_defaults(func=cmd_revoke_v2)
+    p_revoke.set_defaults(func=cmd_revoke)
 
     p_history = subparsers.add_parser("history", help="Show approval history")
     p_history.add_argument("approval_id", metavar="APPROVAL_ID", nargs="?")

package/bin/cli/cleanup.py

@@ -333,7 +333,6 @@ SYMLINKS_TO_REMOVE = [
     ".claude/tools",
     ".claude/hooks",
     ".claude/commands",
-    ".claude/templates",
     ".claude/config",
     ".claude/CHANGELOG.md",
     ".claude/README.en.md",

package/bin/cli/doctor.py

@@ -762,7 +762,7 @@ def _extract_check_values(
 @register_check("Symlinks", order=50)
 def check_symlinks(project_root: Path) -> dict:
     """Check .claude/ symlinks resolve to package content."""
-    names = ["agents", "tools", "hooks", "commands", "templates", "config", "skills", "CHANGELOG.md"]
+    names = ["agents", "tools", "hooks", "commands", "config", "skills", "CHANGELOG.md"]
     critical = {"agents", "hooks", "skills"}
     valid = 0
     has_critical_missing = False

package/bin/cli/memory.py

@@ -19,6 +19,8 @@ Mutating subcommands operate on the curated ``memory`` table in
                                           ~/.claude/projects/.../memory/).
 """
 
+from __future__ import annotations
+
 # Repo-root import bootstrap so ``from gaia.store.writer import ...`` resolves
 # regardless of cwd (the CLI is launched from many places).
 import sys as _sys

package/bin/cli/update.py

@@ -256,7 +256,7 @@ def _run_verification(claude_dir: Path) -> dict:
         issues.append(f"project-context DB read error: {exc}")
 
     # 4. Config files
-    config_files = ["git_standards.json", "surface-routing.json"]
+    config_files = ["surface-routing.json"]
     for cfg in config_files:
         path = claude_dir / "config" / cfg
         ok = path.exists()

package/bin/pre-publish-validate.js

@@ -324,12 +324,9 @@ class PrePublishValidator {
       'hooks',
       'agents',
       'skills',
-      'commands',
       'config',
-      'templates',
       'tools',
       'dist',
-      'git-hooks',
     ];
 
     const missing = [];
@@ -385,6 +382,52 @@ class PrePublishValidator {
     this.log('✓ All critical directories covered by package.json files', 'success');
   }
 
+  /**
+   * Schema-drift guard.
+   *
+   * Fails the publish if gaia/store/schema.sql changed without a corresponding
+   * EXPECTED_SCHEMA_VERSION bump + migration file. Without this guard, schema
+   * drift is only caught at runtime by `gaia doctor` (as a warning) -- here we
+   * make it a hard, non-zero build failure.
+   *
+   * The actual logic lives in scripts/check_schema_drift.py (fingerprint of
+   * schema.sql pinned to the version in scripts/migrations/schema.checksum).
+   * This method just invokes it and surfaces a non-zero exit as a failure.
+   */
+  validateSchemaDrift() {
+    this.log('Step 5c: Schema-drift guard (schema.sql vs EXPECTED_SCHEMA_VERSION)...', 'info');
+
+    const guardPath = path.join(GAIA_OPS_ROOT, 'scripts', 'check_schema_drift.py');
+    if (!fs.existsSync(guardPath)) {
+      this.log(`✗ schema-drift guard missing: ${guardPath}`, 'error');
+      throw new Error('scripts/check_schema_drift.py not found -- cannot verify schema drift');
+    }
+
+    const pyCmd = findPython();
+    if (!pyCmd) {
+      // Python is required for the runtime; a publish that cannot run the
+      // guard cannot prove the schema is consistent, so fail rather than skip.
+      this.log('✗ Python not available -- cannot run schema-drift guard', 'error');
+      throw new Error('Python interpreter not found; schema-drift guard cannot run');
+    }
+
+    try {
+      const out = this.execute(`${pyCmd} "${guardPath}"`, GAIA_OPS_ROOT, true);
+      out.trim().split('\n').filter(Boolean).forEach(line => this.log(`  ${line}`, 'info'));
+      this.log('✓ No schema drift detected', 'success');
+    } catch (error) {
+      // execSync throws on non-zero exit; surface the guard's own stderr/stdout.
+      const detail = (error.stderr || error.stdout || error.message || '').toString().trim();
+      this.log('✗ Schema-drift guard failed:', 'error');
+      if (detail) detail.split('\n').forEach(line => console.error(`    ${line}`));
+      throw new Error(
+        'Schema drift detected: gaia/store/schema.sql changed without a ' +
+        'version bump + migration. Bump EXPECTED_SCHEMA_VERSION in ' +
+        'bin/cli/doctor.py and add the migration, then re-run the guard.'
+      );
+    }
+  }
+
   validatePluginManifest() {
     this.log('Step 6: Validating plugin manifest (.claude-plugin/plugin.json)...', 'info');
 
@@ -440,8 +483,7 @@ class PrePublishValidator {
       // Test 1: Validate JSON files
       this.log('Test 1: Validating JSON configuration files...', 'info');
       const jsonFiles = [
-        'config/clarification_rules.json',
-        'config/git_standards.json'
+        'config/clarification_rules.json'
       ];
 
       jsonFiles.forEach(file => {
@@ -654,6 +696,7 @@ class PrePublishValidator {
         this.validateFiles();
       }
       this.validateFilesCoverage();
+      this.validateSchemaDrift();
       this.validatePluginManifest();
       this.runTests();
 

package/config/README.md

@@ -1,68 +1,46 @@
 # Config
 
-Configuration lives here, separate from hooks, because these are data files — not code. Hooks are Python scripts that run at runtime; config files are JSON documents that those scripts read to make decisions. Keeping them apart means you can audit and change system behavior (which agents see which context sections, what git commit patterns are allowed, which surfaces route where) without touching executable code. It also makes the config files version-controllable and reviewable on their own terms.
+Configuration lives here, separate from hooks, because these are data files — not code. Hooks are Python scripts that run at runtime; config files are JSON documents that those scripts read to make decisions. Keeping them apart means you can audit and change system behavior (what git commit patterns are allowed, which surfaces route where) without touching executable code. It also makes the config files version-controllable and reviewable on their own terms.
 
-`context-contracts.json` is the seeding source for agent contracts. During `gaia install`, its contents are loaded into the `project_context_contracts` and `agent_contract_permissions` tables in `~/.gaia/gaia.db`. At runtime, the DB is the SSOT — the hook layer reads contracts from the DB, not from this file. Editing `context-contracts.json` without re-running `gaia install` (or manually applying the SQL) has no effect. The cloud extension files in `cloud/` extend these contracts for cloud-specific sections without modifying the base file, so adding a new cloud provider is a new file, not an edit to the core.
+The routing table is consumed at a well-defined point in the request lifecycle: on every user prompt. It is not loaded eagerly at startup — it is parsed exactly when `surface_router.py` is invoked. (Git commit standards used to live here too, in `git_standards.json`; they are now inlined as module-level constants in `hooks/modules/validation/commit_validator.py` — the single runtime consumer of those rules — so this folder no longer owns them.)
 
-The other files — routing and git standards — are each consumed by a specific module and do exactly what their names say. There is no magic here: the files are loaded, parsed, and applied by the module that reads them.
+## When activated
 
-## Cuándo se activa
-
-This component does not activate as a runtime process. Each file is read on-demand by the module that needs it. The table below shows the read point for each file.
-
-**Cuándo se lee cada archivo:**
-
-| File | Read by | When |
-|------|---------|------|
-| `surface-routing.json` | `hooks/user_prompt_submit.py` | Every prompt — determines routing recommendation injected into orchestrator context |
-| `context-contracts.json` | `gaia install` / `gaia update` | One-time at install; populates `~/.gaia/gaia.db` tables. Runtime reads come from DB. |
-| `git_standards.json` | `hooks/modules/validation/commit_validator.py` | Every `git commit` call intercepted by PreToolUse |
-| `cloud/gcp.json` | `tools/context/context_provider.py` | Agent dispatch when `cloud_provider = gcp` in workspace DB record |
-| `cloud/aws.json` | `tools/context/context_provider.py` | Agent dispatch when `cloud_provider = aws` in workspace DB record |
-
-**Base + cloud merge flow:**
+This folder has no single activation event. Each file is read on-demand by the module that owns it.
 
 ```
-Agent dispatch triggered
+User submits a prompt
         |
-hooks/modules/context/contracts_loader.py reads project_context_contracts from DB
+hooks/user_prompt_submit.py fires
         |
-Detects cloud_provider from workspace record in ~/.gaia/gaia.db
+tools/context/surface_router.py calls load_surface_routing_config()
         |
-Reads cloud/{provider}.json                         <- cloud extensions (still file-based)
+Reads config/surface-routing.json
         |
-Merges: extends read/write lists per agent (no duplicates)
-        |
-Result: complete contract for this agent on this cloud
-        |
-Agent receives filtered project-context sections
+Returns surface match + recommended agent injected into orchestrator context
 ```
 
-## Qué hay aquí
+If `surface-routing.json` is absent, `load_surface_routing_config()` returns a degraded config (`"version": "missing"`) and routing falls back to the `reconnaissance_agent` default.
+
+## What's here
 
 ```
 config/
-├── context-contracts.json   # Seeding source for per-agent read/write contracts (applied on install to gaia.db)
-├── surface-routing.json     # Intent classification and agent routing signals
-├── git_standards.json       # Commit type allowlist, footer rules, Conventional Commits config
-├── cloud/
-│   ├── gcp.json             # GCP-specific context sections (extends base contracts)
-│   └── aws.json             # AWS-specific context sections (extends base contracts)
+├── surface-routing.json   # Surface→agent routing table; consumed by tools/context/surface_router.py on every prompt
 └── README.md
 ```
 
-## Convenciones
+## Conventions
 
-**context-contracts.json schema:** Each entry is keyed by agent name. Each agent has `read` (list of project-context section names the agent receives) and `write` (list of sections the agent can update via an `update_contracts` clause). `core_sections` is a top-level list of sections injected into every agent regardless of per-agent config. This schema is mirrored in the DB tables `project_context_contracts` (one row per agent) and `agent_contract_permissions` (permission grants).
+**surface-routing.json schema:** Top-level keys are `version`, `reconnaissance_agent`, and `surfaces`. Each surface entry has `intent` (human description), `primary_agent` (agent id to dispatch), `adjacent_surfaces` (list of related surface names), `contract_sections` (context sections injected for that surface), `required_checks` (agent checklist), and `signals` with `keywords`, `commands`, and `artifacts` sub-lists. `surface_router.py` scores surfaces by matching task text against all signal lists; the highest-scoring surface wins.
 
-**Adding a new cloud:** Create `cloud/azure.json` following the same schema as `cloud/gcp.json`. Define agent-specific sections for that cloud. No code changes needed — `context_provider.py` detects the file automatically by matching `cloud_provider` from project-context.
+**Git commit standards (no longer in this folder):** The Conventional Commits rules — allowed types, subject/body length limits, subject rules — are inlined as module-level constants (`TYPE_ALLOWED`, `SUBJECT_MAX_LENGTH`, `SUBJECT_RULES`, `BODY_MAX_LINE_LENGTH`, `ENFORCEMENT`) in `hooks/modules/validation/commit_validator.py`. Forbidden-footer detection lives, hardcoded, in `bash_validator`. To add a new commit type, edit `TYPE_ALLOWED` in `commit_validator.py`.
 
-**surface-routing.json format:** Each surface entry has `intent`, `primary_agent`, `adjacent_surfaces`, and `signals` (with `high` and `medium` confidence keyword lists). High-confidence signals are checked first; medium signals act as tie-breakers.
+**Adding a new surface:** Add an entry to `surfaces` in `surface-routing.json` with all required sub-keys. Update L1 routing tests and the `gaia_system` signals if the new surface involves Gaia components.
 
-## Ver también
+## See also
 
-- [`~/.gaia/gaia.db`](../gaia/store/schema.sql) — `project_context_contracts` + `agent_contract_permissions` tables (runtime SSOT for contracts)
-- [`hooks/user_prompt_submit.py`](../hooks/user_prompt_submit.py) — reads `surface-routing.json` on every prompt
-- [`hooks/modules/validation/`](../hooks/modules/validation/) — reads `git_standards.json` on commit validation
-- [`tools/context/`](../tools/context/) — reads contracts (from DB) at agent dispatch time
-- [`agents/README.md`](../agents/README.md) — agent names that must match context-contracts.json keys
+- [`tools/context/surface_router.py`](../tools/context/surface_router.py) — loads and scores `surface-routing.json`; the routing pillar source of truth
+- [`hooks/user_prompt_submit.py`](../hooks/user_prompt_submit.py) — calls `classify_surfaces` from `surface_router` on every prompt
+- [`hooks/modules/validation/commit_validator.py`](../hooks/modules/validation/commit_validator.py) — enforces Conventional Commits on every `git commit`; standards inlined as module-level constants
+- [`skills/git-conventions/`](../skills/git-conventions/) — the agent-facing skill teaching the commit conventions

package/config/surface-routing.json

@@ -17,7 +17,6 @@
         "infrastructure",
         "orchestration",
         "cluster_details",
-        "monitoring_observability",
         "application_services",
         "infrastructure_topology",
         "architecture_overview"
@@ -364,7 +363,6 @@
           "hooks/",
           "skills/",
           "agents/",
-          "templates/",
           "claude.md",
           "project-context.json"
         ]

package/dist/gaia-ops/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia-ops",
-  "version": "5.0.2",
+  "version": "5.0.5",
   "description": "Full DevOps orchestration for Claude Code. Eight specialized agents handle the complete development lifecycle \u2014 analysis, planning, execution, and deployment. Gaia-Ops scans your codebase to understand it and injects the right context into each sub-agent. Every command is classified by risk: read-only runs freely, state changes pause for your approval, and irreversible operations are permanently blocked.",
   "author": {
     "name": "jaguilar87",