@jaguilar87/gaia 5.0.2 → 5.0.5

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

@@ -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/hooks/modules/agents/contract_validator.py

@@ -19,6 +19,7 @@ Provides:
     - parse_rollback_executed(): Parse rollback_executed clause (advisory)
     - parse_context_consumption(): Parse context_consumption clause (advisory)
     - parse_memory_suggestions(): Parse memory_suggestions clause (advisory)
+    - parse_user_facing_summary(): Parse user_facing_summary clause (advisory)
 """
 
 import json
@@ -655,6 +656,23 @@ def parse_memory_suggestions(contract: dict) -> List[str]:
     return [str(item) for item in raw if item is not None]
 
 
+def parse_user_facing_summary(contract: dict) -> Optional[str]:
+    """Parse the optional top-level ``user_facing_summary`` clause (advisory).
+
+    The single human-audience field in the contract: a short prose summary the
+    subagent writes once for the user. The orchestrator relays it near-verbatim
+    on a single-agent COMPLETE (N=1) instead of re-synthesizing ``key_outputs``.
+
+    Strictly additive and advisory -- the validator never rejects based on this
+    field. Returns the trimmed string when present and non-empty, else None.
+    """
+    raw = contract.get("user_facing_summary")
+    if not isinstance(raw, str):
+        return None
+    text = raw.strip()
+    return text or None
+
+
 def extract_plan_status_from_output(agent_output: str) -> str:
     """Extract the effective plan_status string from agent output.
 

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

@@ -10,11 +10,187 @@ 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__)
 
 
+def _normalize_command_set(raw) -> list:
+    """Coerce a raw ``command_set`` into the canonical ``[{command, rationale}]``.
+
+    Mirrors the normalization in ``bash_validator._build_sealed_payload`` and
+    ``approval_grants.activate_db_pending_by_prefix`` so the intake writes the
+    exact shape the activation/consume sides expect. Items without a non-empty
+    ``command`` are dropped; ``rationale`` defaults to "".
+    """
+    out: list = []
+    if isinstance(raw, list):
+        for item in raw:
+            if isinstance(item, dict) and item.get("command"):
+                out.append(
+                    {
+                        "command": item["command"],
+                        "rationale": item.get("rationale", ""),
+                    }
+                )
+    return out
+
+
+def _filter_mutative_command_set(items: list) -> list:
+    """Keep only the command_set items whose command is mutative/T3.
+
+    The consume side (``bash_validator._validate_single_command``) gates the
+    whole COMMAND_SET match path on ``detect_mutative_command(command).is_mutative``:
+    a command that the matcher does not see as mutative NEVER reaches
+    ``match_command_set_grant`` and its index is therefore NEVER consumed. If
+    such a command is included in the grant's ``command_set``, ``len(consumed)``
+    can never reach ``len(command_set)`` and the grant is stuck PENDING forever
+    (it never flips to CONSUMED). To stay in lockstep with the consume gate, the
+    intake filters with the EXACT same predicate, dropping non-mutative commands
+    (e.g. ``touch``, ``ls``, ``cat``) before the grant is ever minted.
+
+    Items that fail to classify (import error, unexpected exception) are kept --
+    failing open here is safer than silently dropping a command from a consent
+    batch the user is about to approve.
+    """
+    try:
+        from modules.security.mutative_verbs import detect_mutative_command
+    except ImportError:
+        import pathlib as _pl
+        import sys as _sys
+
+        _hooks_root = _pl.Path(__file__).resolve().parent.parent.parent
+        _sys.path.insert(0, str(_hooks_root))
+        from modules.security.mutative_verbs import detect_mutative_command
+
+    kept: list = []
+    for item in items:
+        command = item.get("command", "")
+        try:
+            if detect_mutative_command(command).is_mutative:
+                kept.append(item)
+        except Exception:
+            # Fail open: if classification raises, keep the item rather than
+            # silently dropping a command from the user's consent batch.
+            kept.append(item)
+    return kept
+
+
+def _intake_command_set_pending(
+    approval_req: dict,
+    *,
+    agent_id,
+    session_id: str,
+) -> str | None:
+    """INTAKE bridge: plan-first COMMAND_SET envelope -> ONE pending row.
+
+    When a subagent emits an ``APPROVAL_REQUEST`` whose ``approval_request``
+    carries a ``command_set`` of >= 2 ``{command, rationale}`` items and NO
+    ``approval_id`` (plan-first: the batch is declared up-front, before any
+    command was attempted/blocked), this persists exactly ONE pending approval
+    whose ``payload_json`` contains the ``command_set`` key. That is the signal
+    ``activate_db_pending_by_prefix`` reads (Step 3b) to branch into
+    ``create_command_set_grant`` on user approval.
+
+    Mutative filtering (Thread a): the command_set is first reduced to ONLY the
+    commands the consume side will treat as mutative/T3 -- see
+    ``_filter_mutative_command_set``. Non-mutative commands (``touch``, ``ls``,
+    ...) never reach the bash_validator matcher, so leaving them in the grant
+    would strand its ``consumed_indexes_json`` short of completion and pin the
+    grant at PENDING forever. After filtering:
+
+      * >= 2 mutative items  -> mint the COMMAND_SET over exactly those items.
+      * exactly 1 mutative   -> NOT a batch. Return None; the caller falls
+        through to the singular ``approval_id`` path and the lone command is
+        gated by the normal hook-block / SCOPE_SEMANTIC_SIGNATURE flow when the
+        agent attempts it. We deliberately do NOT degrade-to-singular here: this
+        function's contract is "mint a COMMAND_SET or stand aside", and the
+        singular flow is owned end-to-end by the hook block path -- minting a
+        singular row from here would duplicate that ownership.
+      * 0 mutative           -> nothing to approve. Return None (no pending).
+
+    A raw ``command_set`` of <= 1 item is likewise not a batch and returns None
+    before filtering, preserving the original contract (never mint for one
+    command, never degrade a batch the other way) and the working plan-first
+    flow for genuine multi-command mutative batches.
+
+    Returns the minted ``approval_id`` (``P-{uuid4hex}``) on success, or None
+    when this is not a plan-first command_set envelope (no action taken).
+    """
+    if not isinstance(approval_req, dict):
+        return None
+    # Plan-first is defined by command_set present AND no approval_id. A request
+    # that already carries an approval_id was minted by the hook block path; it
+    # is the singular flow and must not be re-intaken here.
+    if approval_req.get("approval_id"):
+        return None
+
+    raw_items = _normalize_command_set(approval_req.get("command_set"))
+    if len(raw_items) < 2:
+        # 0 or 1 item: not a batch. Singular path owns it.
+        return None
+
+    # Reduce to the mutative/T3 commands only -- the exact predicate the consume
+    # side uses to decide whether a command reaches the COMMAND_SET matcher.
+    command_set_items = _filter_mutative_command_set(raw_items)
+    if len(command_set_items) < 2:
+        # After filtering there is no batch left: either every command was
+        # non-mutative (0 -> nothing to approve) or just one mutative command
+        # remained (1 -> singular path owns it). Either way, no COMMAND_SET.
+        logger.info(
+            "INTAKE: command_set not minted -- %d/%d items mutative after filter "
+            "(need >= 2 for a batch)",
+            len(command_set_items), len(raw_items),
+        )
+        return None
+
+    # Build a sealed_payload that mirrors bash_validator._build_sealed_payload's
+    # COMMAND_SET shape: command_set verbatim + commands listing every string.
+    # Carry through the subagent's operation/risk fields when present so the
+    # orchestrator's presentation has real values, falling back to neutral
+    # COMMAND_SET defaults otherwise.
+    first_command = command_set_items[0]["command"]
+    sealed_payload = {
+        "operation": approval_req.get("operation")
+        or f"COMMAND_SET intercepted: {len(command_set_items)} commands under one consent",
+        "exact_content": approval_req.get("exact_content") or first_command,
+        "scope": approval_req.get("scope")
+        or (first_command.split()[0] if first_command.strip() else "unknown"),
+        "risk_level": approval_req.get("risk_level") or "medium",
+        "rollback_hint": approval_req.get("rollback") or approval_req.get("rollback_hint"),
+        "rationale": approval_req.get("rationale")
+        or (
+            f"A batch of {len(command_set_items)} related T3 commands requires user "
+            "approval under one consent per the COMMAND_SET policy."
+        ),
+        "commands": [it["command"] for it in command_set_items],
+        "command_set": command_set_items,
+    }
+
+    try:
+        from gaia.approvals.store import insert_requested
+    except ImportError:
+        import pathlib as _pl
+        import sys as _sys
+
+        _repo_root = _pl.Path(__file__).resolve().parent.parent.parent.parent
+        _sys.path.insert(0, str(_repo_root))
+        from gaia.approvals.store import insert_requested
+
+    approval_id = insert_requested(
+        sealed_payload,
+        agent_id=agent_id,
+        session_id=session_id or None,
+    )
+    logger.info(
+        "INTAKE: plan-first COMMAND_SET pending created approval_id=%s items=%d",
+        (approval_id or "")[:16], len(command_set_items),
+    )
+    return approval_id
+
+
 def persist_handoff(
     parsed_contract,
     agent_output: str,
@@ -38,6 +214,38 @@ def persist_handoff(
     import pathlib as _pl
     import sys as _sys
 
+    agent_id = task_info.get("agent_id") or task_info.get("agent") or "unknown"
+
+    # ---------------------------------------------------------------------
+    # INTAKE bridge (plan-first COMMAND_SET) -- run FIRST and INDEPENDENTLY.
+    #
+    # Minting the pending COMMAND_SET approval is the security-critical path:
+    # it is the consent the user must act on. It must not be coupled to the
+    # audit handoff-row write below -- if insert_agent_contract_handoff fails
+    # for any reason, the user must still get the approval to review. So the
+    # intake runs in its own isolated try, before the handoff-row write.
+    #
+    # Only plan-first envelopes act here: command_set >= 2 items AND no
+    # approval_id. A <= 1 item set or a request that already carries an
+    # approval_id (hook-block / singular path) is a no-op for the intake.
+    # ---------------------------------------------------------------------
+    minted_command_set_id = None
+    if parsed_contract is not None:
+        _env = parsed_contract if isinstance(parsed_contract, dict) else {}
+        _approval_req = _env.get("approval_request")
+        if isinstance(_approval_req, dict):
+            try:
+                minted_command_set_id = _intake_command_set_pending(
+                    _approval_req,
+                    agent_id=agent_id,
+                    session_id=session_id,
+                )
+            except Exception as _intake_exc:
+                logger.warning(
+                    "M4: COMMAND_SET intake failed (non-blocking): %s",
+                    _intake_exc,
+                )
+
     try:
         # Prefer a sibling gaia package if installed; fall back to the repo
         # layout where gaia/ lives two levels above hooks/.
@@ -48,7 +256,6 @@ def persist_handoff(
             _sys.path.insert(0, str(_repo_root))
             from gaia.store import writer as _writer
 
-        agent_id = task_info.get("agent_id") or task_info.get("agent") or "unknown"
         workspace = task_info.get("workspace") or _os.environ.get("GAIA_WORKSPACE") or "global"
         db_path_str = task_info.get("db_path")
         db_path = _pl.Path(db_path_str) if db_path_str else None
@@ -99,7 +306,12 @@ def persist_handoff(
             envelope = parsed_contract if isinstance(parsed_contract, dict) else {}
             approval_req = envelope.get("approval_request")
             if approval_req and isinstance(approval_req, dict):
-                approval_id = approval_req.get("approval_id")
+                # The approval_id is either the one the subagent relayed (hook-block
+                # / singular path) or the one the INTAKE bridge just minted for a
+                # plan-first COMMAND_SET. Either way it points at the pending row
+                # the handoff_approvals audit row should link to.
+                approval_id = approval_req.get("approval_id") or minted_command_set_id
+
                 if approval_id:
                     # Look up the grant to determine the decision at stop time.
                     try:

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

@@ -402,6 +402,31 @@ def parse_memorialize_suggestions(
     return _extract_memorialize_suggestions(contract)
 
 
+def parse_user_facing_summary(
+    agent_output: str,
+    parsed_contract: Optional[dict] = None,
+) -> Optional[str]:
+    """Parse the optional top-level ``user_facing_summary`` field (Option A).
+
+    This is the ONE human-audience field in the contract: a brief prose summary
+    the subagent writes once, intended for the user. The orchestrator relays it
+    near-verbatim on a single-agent COMPLETE (N=1) instead of re-synthesizing
+    ``key_outputs``; for N>1 it is ignored and synthesis proceeds.
+
+    Strictly additive and advisory: the field is never required and never
+    affects contract validity. Returns the trimmed string when present and
+    non-empty, otherwise None (absent, null, blank, or non-string).
+    """
+    contract = parsed_contract if parsed_contract is not None else parse_contract(agent_output)
+    if contract is None:
+        return None
+    raw = contract.get("user_facing_summary")
+    if not isinstance(raw, str):
+        return None
+    text = raw.strip()
+    return text or None
+
+
 def _is_resume_agent_id(value: str) -> bool:
     return bool(_AGENT_ID_PATTERN.match(value or ""))
 
@@ -659,6 +684,7 @@ __all__ = [
     "parse_evidence_report",
     "parse_consolidation_report",
     "parse_memorialize_suggestions",
+    "parse_user_facing_summary",
     "validate_response_contract",
     "save_validation_result",
     "load_last_validation",

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

@@ -139,10 +139,25 @@ def extract_injected_context_payload_from_transcript(
     """
     import os
 
+    # Empty/None path guard. Without it, Path("").stem == "" and the substring
+    # match below (``candidate.stem in "" or "" in candidate.stem``) is ALWAYS
+    # True because ``"" in any_string`` is True -- so an empty path would match
+    # (and return) the FIRST payload sitting in gaia-context-payloads/, making
+    # the result depend on whatever happens to be in that directory. Mirror the
+    # guard in read_first_user_content_from_transcript: no path, no match.
+    if not transcript_path:
+        return {}
+
     try:
         payload_dir = Path(os.environ.get("TMPDIR", "/tmp")) / "gaia-context-payloads"
         if payload_dir.exists():
             agent_file = Path(transcript_path).stem  # e.g. "agent-ae190a4da68d626d4"
+            # A stem that came out empty (e.g. path was "/" or "."): nothing to
+            # match against, so the substring test would again degrade to the
+            # always-true ``"" in candidate.stem``. Bail rather than grab an
+            # arbitrary payload.
+            if not agent_file:
+                return {}
             # Match by agent ID substring
             for candidate in payload_dir.glob("*.json"):
                 if candidate.stem in agent_file or agent_file in candidate.stem:

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

@@ -5,7 +5,6 @@ Provides:
 - tiers: SecurityTier enum and classification
 - blocked_commands: Permanently blocked pattern matching
 - mutative_verbs: Mutative verb detection (user approval workflow)
-- gitops_validator: kubectl/helm/flux validation
 - approval_constants: Approval token patterns (legacy APPROVE: and ElicitationResult)
 - approval_grants: Time-limited T3 command passthrough after user approval
 - shell_unwrapper: Detect and strip wrapper shells for inner command classification
@@ -21,7 +20,6 @@ from .blocked_commands import (
     get_blocked_patterns,
     BlockedCommandResult,
 )
-from .gitops_validator import validate_gitops_workflow, GitOpsValidationResult
 from .mutative_verbs import (
     CLI_FAMILY_LOOKUP,
     CATEGORY_MUTATIVE,
@@ -73,9 +71,6 @@ __all__ = [
     "is_blocked_command",
     "get_blocked_patterns",
     "BlockedCommandResult",
-    # GitOps
-    "validate_gitops_workflow",
-    "GitOpsValidationResult",
     # Mutative verbs
     "CLI_FAMILY_LOOKUP",
     "CATEGORY_MUTATIVE",