@jaguilar87/gaia 5.0.4 → 5.0.6

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.4",
+      "version": "5.0.6",
       "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.4",
+      "version": "5.0.6",
       "category": "security",
       "author": {
         "name": "jaguilar87",

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -7,6 +7,71 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.0.6] - 2026-06-12
+
+### Fixed
+
+- **`gaia doctor` no longer reports a freshly-installed workspace as "degraded"
+  (rc=1)** — an empty project-context contracts table is now `info` (an advisory
+  to run `gaia scan`) instead of `warning`, so a clean install passes doctor with
+  rc=0. Fixes the post-publish sandbox-validation failure seen in 5.0.5.
+
+## [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

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/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
@@ -935,7 +935,7 @@ def check_project_context(project_root: Path) -> dict:
         return _result("project-context", "warning", f"DB read error: {exc}", "Run `gaia scan`")
 
     if count == 0:
-        return _result("project-context", "warning", "No contracts in DB", "Run `gaia scan`")
+        return _result("project-context", "info", "No contracts in DB", "Run `gaia scan`")
 
     if count < 3:
         return _result(

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

@@ -363,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.4",
+  "version": "5.0.6",
   "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",

package/dist/gaia-ops/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/dist/gaia-ops/config/surface-routing.json

@@ -363,7 +363,6 @@
           "hooks/",
           "skills/",
           "agents/",
-          "templates/",
           "claude.md",
           "project-context.json"
         ]

package/dist/gaia-ops/hooks/modules/agents/handoff_persister.py

@@ -10,6 +10,8 @@ arise if the adapter imported _persist_handoff directly from subagent_stop
 (which itself imports from the adapter's dependency tree).
 """
 
+from __future__ import annotations
+
 import logging
 
 logger = logging.getLogger(__name__)

package/dist/gaia-ops/hooks/modules/security/approval_grants.py

@@ -76,6 +76,8 @@ fallback plane retained for grants created before the DB cutover. The active
 flow runs through the DB plane in gaia.store.writer.
 """
 
+from __future__ import annotations
+
 import json
 import logging
 import os

package/dist/gaia-ops/hooks/modules/tools/bash_validator.py

@@ -23,6 +23,8 @@ Earlier flat-pipeline order preserved within phases for backward compat:
   - Blocked commands run before cloud_pipe and mutative_verbs in phase 3
 """
 
+from __future__ import annotations
+
 import os
 import re
 import json