@jaguilar87/gaia 5.0.0-rc.3 → 5.0.2

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.0-rc.3",
+      "version": "5.0.2",
       "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.0-rc.3",
+      "version": "5.0.2",
       "category": "security",
       "author": {
         "name": "jaguilar87",

package/.claude-plugin/plugin.json

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

package/ARCHITECTURE.md

@@ -38,7 +38,7 @@ pre_tool_use.py  (PreToolUse hook)
     |  4. Validate SendMessage (agent resumption)
     v
 Agent executes
-    |  Uses tools, follows skills, emits json:contract
+    |  Uses tools, follows skills, emits agent_contract_handoff
     v
 subagent_stop.py  (SubagentStop hook)
     |  1. Read transcript, extract task description
@@ -46,9 +46,9 @@ subagent_stop.py  (SubagentStop hook)
     |  3. Validate response contract
     |  4. Detect anomalies
     |  5. Store episodic memory
-    |  6. Process CONTEXT_UPDATE blocks
+    |  6. Process update_contracts from the agent_contract_handoff envelope
     v
-Orchestrator processes json:contract (via agent-response skill)
+Orchestrator processes agent_contract_handoff (via agent-response skill)
     |  COMPLETE -> summarize to user
     |  APPROVAL_REQUEST (with approval_id) -> get approval -> resume via SendMessage
     |  NEEDS_INPUT -> ask user -> resume via SendMessage
@@ -108,7 +108,7 @@ Fires after every agent tool completes:
 4. Detect anomalies          --> execution failures, consecutive failures
    |  If anomalies found -> create needs_analysis.flag for Gaia
 5. Capture episodic memory   --> store episode via tools/memory/episodic.py
-6. Process context updates   --> apply CONTEXT_UPDATE blocks via context_writer.py
+6. Process context updates   --> apply update_contracts entries from the agent_contract_handoff envelope via context_writer.py (process_update_contracts)
 ```
 
 ## Surface Routing: surface_router.py
@@ -119,7 +119,7 @@ Classifies user tasks into surfaces using signal matching against `config/surfac
 |---------|--------------|-----------------|
 | `live_runtime` | cloud-troubleshooter | pods, services, logs, kubectl, gcloud |
 | `gitops_desired_state` | gitops-operator | manifests, Flux, Helm, Kustomize |
-| `terraform_iac` | terraform-architect | Terraform, Terragrunt, IAM, modules |
+| `iac` | platform-architect | Terraform, Terragrunt, IAM, modules |
 | `app_ci_tooling` | developer | CI/CD, Docker, package tooling |
 | `planning_specs` | gaia-planner | briefs, plans (materializados cuando una conversación alcanza Cerrar) |
 | `gaia_system` | gaia-system | hooks, skills, agents/, CLAUDE.md |
@@ -141,12 +141,11 @@ Assembles the context payload injected into agent prompts by pre_tool_use.py.
 ```
 context_provider.py <agent_name> <user_task>
     |
-    +--> Load project-context.json
-    +--> Detect cloud provider (GCP/AWS)
-    +--> Load base contracts (config/context-contracts.json)
+    +--> Load project context from ~/.gaia/gaia.db (project_context_contracts table)
+    +--> Detect cloud provider (GCP/AWS) from DB workspace record
+    +--> Load base contracts from DB (agent_contract_permissions table)
     +--> Merge cloud overrides (config/cloud/{provider}.json)
     +--> Extract contracted sections for this agent (read permissions)
-    +--> Load universal rules (config/universal-rules.json)
     +--> Load relevant episodic memory (similarity match)
     +--> Classify surfaces (surface_router.py)
     +--> Build investigation brief (surface_router.py)
@@ -182,7 +181,7 @@ Nonce-based T3 approval lifecycle:
 
 ## Response Contract Validation
 
-Every agent response must end with a `json:contract` block containing `agent_status`. The contract validator (`hooks/modules/agents/contract_validator.py`) enforces:
+Every agent response must end with a `agent_contract_handoff` block containing `agent_status`. The contract validator (`hooks/modules/agents/contract_validator.py`) enforces:
 
 - **AGENT_STATUS**: PLAN_STATUS (from 5 valid states: COMPLETE, NEEDS_INPUT, APPROVAL_REQUEST, BLOCKED, IN_PROGRESS), PENDING_STEPS, NEXT_ACTION, AGENT_ID
 - **EVIDENCE_REPORT**: required for all valid states. Seven fields: PATTERNS_CHECKED, FILES_CHECKED, COMMANDS_RUN, KEY_OUTPUTS, VERBATIM_OUTPUTS, CROSS_LAYER_IMPACTS, OPEN_GAPS
@@ -244,9 +243,9 @@ The adapter layer connects Claude Code's hook protocol to Gaia business logic th
 |-----------|-------|
 | **File** | `hooks/subagent_stop.py` |
 | **Hook event** | SubagentStop |
-| **What it does** | Fires after every agent completes. Consumes approval files, captures workflow metrics, validates the response contract (AGENT_STATUS, EVIDENCE_REPORT, CONSOLIDATION_REPORT), detects anomalies, stores episodic memory, and processes CONTEXT_UPDATE blocks. |
+| **What it does** | Fires after every agent completes. Consumes approval files, captures workflow metrics, validates the response contract (AGENT_STATUS, EVIDENCE_REPORT, CONSOLIDATION_REPORT), detects anomalies, stores episodic memory, and processes the update_contracts array from the agent_contract_handoff envelope. |
 | **Adapter methods called** | `ClaudeCodeAdapter.parse_event()`, `ClaudeCodeAdapter.parse_agent_completion()` |
-| **Business logic modules** | `agents/response_contract.py` (`validate_response_contract`, `save_pending_repair`, `clear_pending_repair`), `tools/memory/episodic.py` (`EpisodicMemory.store_episode`), `context/context_writer.py` (`process_agent_output`) |
+| **Business logic modules** | `agents/response_contract.py` (`validate_response_contract`, `save_pending_repair`, `clear_pending_repair`), `tools/memory/episodic.py` (`EpisodicMemory.store_episode`), `context/context_writer.py` (`process_update_contracts`) |
 
 ### CP-4: `hooks/modules/tools/hook_response.py` -- Response Formatting
 
@@ -328,8 +327,7 @@ To support a CLI other than Claude Code (e.g., a hypothetical Cursor or Windsurf
 | `tools/context/surface_router.py` | Surface classification and investigation briefs |
 | `tools/memory/episodic.py` | Episodic memory storage |
 | `config/context-contracts.json` | Agent read/write section permissions |
-| `config/universal-rules.json` | Universal and agent-specific rules |
 | `config/surface-routing.json` | Surface signals and routing config |
 | `agents/*.md` | Agent identity definitions |
 | `skills/*/SKILL.md` | Injected procedural knowledge |
-| `bin/*.js` | CLI tools (gaia-scan, gaia-doctor, gaia-status, etc.) |
+| `bin/gaia` + `bin/cli/*.py` | Unified `gaia` CLI; subcommands auto-discovered from `bin/cli/` |

package/CHANGELOG.md

@@ -7,6 +7,177 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.0.2] - 2026-06-03
+
+### Approval-Flow Hardening, mkdir Reclassification, Jira Skill
+
+Patch release accumulating security and approval-flow fixes, one new skill, and a quality-of-life exemption for Gaia's own planning bookkeeping commands. All 4575 tests pass on a clean install.
+
+#### Fixed
+
+- **Stop double-approval on re-dispatched T3 grants** — a T3 command that was
+  re-dispatched after approval could be blocked a second time with a fresh nonce,
+  forcing the user to approve the same operation twice. Two gaps caused the grant miss:
+  `command_semantics` was not normalizing output-redirect tokens out of the semantic
+  signature (causing the retry signature to drift from the approved one), and
+  `bash_validator._find_pending_in_db` was matching too narrowly and minting a new
+  nonce instead of reusing the granted one. Both gaps are closed; a regression test
+  reproduces the redirect-normalization grant miss.
+
+- **Flag-classifier grants + cross-session grant matching** — the flag-classifier
+  branch in `bash_validator` was never consulting approval grants, so curl-family T3
+  commands that had been approved were blocked again on retry. `check_db_semantic_grant`
+  is now session-agnostic (session is audit-only); `_find_pending_in_db` accepts
+  `all_sessions=True`; grant insert is fingerprint-idempotent so cross-session
+  block→approve→retry converges. `matches_approval_signature` derives identity from
+  `analyze_command` only; `_normalize_flag_token` binds long `--flag=value` tokens to
+  fix a critical over-match. Grant TTL raised from 5 to 60 minutes
+  (`APPROVAL_GRANT_TTL_MINUTES`), kept distinct from the 1440-minute pending TTL.
+
+- **Unify T3 decision across bash validator classifiers** — mutative-verb,
+  `file_to_exec` composition, and flag-mutation classifiers now all route through a
+  single `decide_t3_outcome()` keyed on `has_orchestrator_above` (is_subagent AND
+  is_ops_mode). `file_to_exec` and curl flag-mutations no longer hardcode the native
+  CC approval dialog; in ops+subagent mode they produce `deny+approval_id` like
+  mutative verbs, keeping them inside the Gaia approval/audit trail. Local workspace
+  data files (`.json`/`.yaml`/`.csv`/`.txt`) are degraded to ALLOW for the
+  `file_to_exec` composition; network/decode→exec pipelines still BLOCK.
+
+- **`mkdir` reclassified as T0 for non-sensitive working-tree paths** — `mkdir` on
+  relative, home-relative, or absolute non-system paths is non-destructive and
+  idempotent with `-p`; it no longer triggers T3. `mkdir` targeting kernel
+  pseudo-filesystems or privileged OS directories (`/dev`, `/sys`, `/proc`, `/etc`,
+  `/boot`, `/usr`, `/bin`, `/sbin`, `/lib`, `/lib64`, `/root`) retains T3. Scratch
+  space (`/tmp`, `/run`) is excluded — ephemeral, world-writable by design. Adds
+  `MKDIR_SENSITIVE_PATH_PREFIXES` (11 prefixes) and `_mkdir_targets_sensitive_path()`
+  in `mutative_verbs.py`.
+
+#### Added
+
+- **Schema v18 — stable project identity** — `project_identity` column and a partial
+  unique index on the `projects` table collapse the same physical repo scanned from
+  different vantages into one row. `store_populator.resolve_project_identity()` derives
+  stable identity from git-common-dir → normalized remote → realpath. Migration files:
+  `scripts/migrations/v17_to_v18.sql` and `v17_to_v18_fresh.sql`.
+
+- **Skill `jira-ticket-writing`** — technique skill for writing human-readable Jira
+  Stories and Subtasks following Atlassian conventions: structured title formula,
+  acceptance criteria, story points, label taxonomy, and worked examples. User-invocable
+  (`user-invocable: true`); not injected into any agent frontmatter by default.
+
+#### Changed
+
+- **`gaia brief` / `gaia ac` exempted from T3 gate** — `gaia brief <verb>` and
+  `gaia ac <verb>` (`edit`/`set-status`/`set-field`/`add`/`remove`/`new`/`show`/`list`)
+  now classify as non-mutative. Local planning bookkeeping that is reversible and has no
+  external side effects is treated like `git commit`. The exemption is anchored to
+  `(base_cmd, subcommand)` — not a generic `gaia *` pattern — so the consent layer
+  (`gaia approvals approve/revoke`) and other groups (`gaia memory`) remain T3.
+  Whole-record destruction (`gaia brief delete`) and dangerous flags (`--force`) still
+  re-gate.
+
+## [5.0.0] - 2026-06-02
+
+### Stable Release: Scan Overhaul, Zero-Dep Install, Soft-Delete, DB-Canonical Context
+
+Fifth major release of Gaia. Promotes the rc.7 release candidate to stable after passing the full dry-run, CI, and live-install gate. The headline work is a ground-up rewrite of the workspace scanner, a zero-dependency NPM install path, a soft-delete model for projects and workspaces, and the retirement of `project-context.json` in favour of the DB as the single canonical source of project context.
+
+#### Added
+
+- **Scan overhaul — taxonomy and recursive discovery** — `gaia scan` now classifies
+  discovered items across three orthogonal dimensions: *workspace* (the Claude Code
+  working environment), *project* (the user's source tree), and *installation* (the
+  Gaia artefacts wired into `.claude/`). Discovery walks recursively so nested
+  monorepo structures and workspace-within-workspace layouts are captured correctly.
+  Taxonomy is defined in `tools/scan/` and tested independently of the CLI.
+
+- **On-demand `gaia scan <path>`** — the scan subcommand now accepts an explicit
+  target path, enabling agents to scan a directory that is not the current working
+  directory without changing cwd. Useful for multi-root workspaces and cross-project
+  context enrichment.
+
+- **Scan/install separation + scan-core** — the scan pipeline is now split into a
+  pure discovery core (`scan-core`) with no install-time side effects, and a
+  separate install phase that consumes core output. This makes scan deterministic
+  and testable without triggering postinstall hooks, and lets the install phase be
+  skipped when scanning for context only.
+
+- **Pure-NPM zero-dependency install** — `postinstall` now completes with zero
+  runtime npm dependencies. All install-time logic runs through `python3 bin/gaia
+  install --postinstall` (Python stdlib only). The devDependencies remain for build
+  tooling (`chalk`, `eslint`) but consumers take no transitive runtime deps.
+
+- **Soft-delete for projects and workspaces** — `gaia scan` handles pruning
+  automatically: when a previously-registered project path is no longer found on
+  disk, the prune pass marks it missing; scanning a directory that has no Gaia
+  installation demotes the workspace (marks it missing) and tombstones its
+  projects. No explicit remove or demote commands exist — lifecycle state flows
+  from the scanner. Soft-deleted rows are hidden from list views. Schema migrated
+  from v12 to v17 to carry the new columns and the `project_workspace_archive`
+  table.
+
+- **`project-context.json` retired — DB is canonical** — the on-disk
+  `project-context.json` file is no longer written or read by any Gaia component.
+  Project context lives exclusively in `~/.gaia/gaia.db` (tables `projects`,
+  `workspaces`, `project_resources`). The context provider and all CLI subcommands
+  read directly from the DB. Existing `project-context.json` files are ignored on
+  upgrade; run `gaia scan` to populate the DB.
+
+#### Fixed
+
+- **`gaia approvals list` crash** — `bin/cli/approvals.py` raised an unhandled
+  exception when the `approval_grants` table contained rows with a `None` nonce
+  (rows inserted by older schema versions). Added a null-guard before nonce
+  formatting; the command now lists all rows cleanly and marks legacy rows as
+  `(no nonce)`.
+
+#### Changed
+
+- **Schema v12 → v17** — five incremental migrations applied in lockstep with
+  `EXPECTED_SCHEMA_VERSION` in `bin/cli/doctor.py` and the bootstrap insert in
+  `scripts/bootstrap_database.sh`. The `test_schema_version_lockstep.py` test
+  confirms all three agree.
+
+- **CI hardening** — `ci.yml` now runs the full pytest suite on Python 3.9, 3.11,
+  and 3.12 in parallel, blocks merges on any failure, and verifies `build:plugins`
+  produces valid `dist/` artefacts. The `validate-sandbox.sh` harness is wired
+  into the publish gate.
+
+- **Suite green** — all Layer 1 tests pass on the three supported Python versions.
+  The scan-core and soft-delete paths are covered by dedicated test modules.
+
+- **`bin/validate-sandbox.sh`** -- harness now drives `gaia` subcommands end
+  to end (no `gaia-X.js` callers remain). The 8-check matrix is unchanged.
+  Sandbox DB is now isolated via `GAIA_DATA_DIR` so memory checks run against
+  a seeded fixture DB rather than the global `~/.gaia/gaia.db`.
+
+- **CLI docstrings** -- `bin/cli/*.py` modules dropped the
+  "Mirrors gaia-X.js" parity comments now that there is no JS counterpart on
+  disk to mirror.
+
+#### Removed
+
+- **Legacy JS CLI binaries** -- `bin/gaia-doctor.js`, `bin/gaia-status.js`,
+  `bin/gaia-history.js`, `bin/gaia-metrics.js`, `bin/gaia-cleanup.js`,
+  `bin/gaia-update.js`, `bin/gaia-uninstall.js`, `bin/gaia-skills-diagnose.js`,
+  `bin/gaia-review.js`, `bin/gaia-evidence`, `bin/gaia-scan` (Node wrapper),
+  and `bin/gaia-scan.py` are gone. The `bin` field in `package.json` now
+  exposes a single binary: `gaia`. Every subcommand previously available as
+  `npx gaia-X` is now reached through `gaia X` -- subcommands are discovered
+  automatically from `bin/cli/*.py` via the `register()` / `cmd_<name>()`
+  contract. Lifecycle scripts (`postinstall`, `preuninstall`) call
+  `python3 bin/gaia install --postinstall` and `python3 bin/gaia uninstall
+  --preuninstall` directly. `gaia-skills-diagnose`, `gaia-review`, and
+  `gaia-evidence` had no Python successor and are not migrated; for general
+  health checks use `gaia doctor`.
+
+#### Internal
+
+- Regenerated `dist/gaia-ops/` and `dist/gaia-security/` for 5.0.0.
+- `pyproject.toml` version aligned with `package.json` at `5.0.0`.
+
+---
+
 ## [5.0.0-rc.3] - 2026-04-26
 
 ### Release Candidate 3: Python 3.9 Compatibility Fix
@@ -205,7 +376,7 @@ The unified CLI also provides subcommands that did not exist as standalone JS CL
 | `python3 bin/gaia plans list` | List all feature briefs |
 | `python3 bin/gaia plans show BRIEF_NAME` | Show a brief and plan |
 | `python3 bin/gaia context show` | Display project-context.json summary |
-| `python3 bin/gaia context scan` | Invoke gaia-scan to refresh context |
+| `python3 bin/gaia context scan` | Refresh project-context via the scanner |
 
 #### Deprecation timeline
 
@@ -298,7 +469,7 @@ Contracts now fully control what context each agent receives. Removed the progre
 #### Changed
 - **context_provider.py**: Contracts are the single source of truth -- removed progressive disclosure filtering that overrode contract-defined sections
 - **context_provider.py**: Simplified output payload -- removed `enrichment` and `progressive_disclosure` keys from response
-- **contracts/terraform-architect.json**: Now reads `cluster_details` and `application_services` sections
+- **contracts/platform-architect.json**: Now reads `cluster_details` and `application_services` sections
 - **contracts/gitops-operator.json**: Now reads `gcp_services` section (GCP overlay)
 - **pre_tool_use.py**: Updated log message to show sections count and rules count
 - **templates/CLAUDE.template.md**: Synced agent routing descriptions with CLAUDE.md
@@ -391,8 +562,8 @@ Major redesign of skills and agents. Skills now teach principles instead of enum
 - **`skills/reference.md`** - Agent template and npm release checklist (moved from gaia agent)
 - **`skills/terraform-patterns/reference.md`** - Full HCL examples
 - **`skills/gitops-patterns/reference.md`** - Full YAML examples
-- **`investigation` skill** assigned to cloud-troubleshooter, terraform-architect, gitops-operator, devops-developer, gaia
-- **`git-conventions` skill** assigned to terraform-architect, gitops-operator, devops-developer
+- **`investigation` skill** assigned to cloud-troubleshooter, platform-architect, gitops-operator, devops-developer, gaia
+- **`git-conventions` skill** assigned to platform-architect, gitops-operator, devops-developer
 - **`agent-protocol` + `security-tiers` skills** assigned to speckit-planner
 
 #### Metrics
@@ -689,7 +860,7 @@ Inspired by [memory-graph](https://github.com/gregorydickson/memory-graph) analy
 ### Changed - Agent Optimization
 
 - **agents/*.md** - All 6 agents reduced by 78%
-  - terraform-architect: 916 → 183 lines
+  - platform-architect: 916 → 183 lines
   - gitops-operator: 1,238 → 217 lines
   - gcp-troubleshooter: 600 → 156 lines
   - aws-troubleshooter: 565 → 142 lines
@@ -773,7 +944,7 @@ Inspired by [memory-graph](https://github.com/gregorydickson/memory-graph) analy
   - Better Flux CD integration guidance
   - Enhanced troubleshooting protocols
 
-- **agents/terraform-architect.md** - Enhanced with 47 new lines
+- **agents/platform-architect.md** - Enhanced with 47 new lines
   - Improved Terragrunt support
   - Better module design guidance
   - Enhanced security scanning protocols

package/CONTRIBUTING.md

@@ -67,7 +67,7 @@ See [README.md](./README.md) for the full directory tree. Key areas for contribu
 | `tools/` | Orchestration tools (context provider, memory, validation) |
 | `config/` | Configuration files (contracts, git standards, rules) |
 | `tests/` | Test suite organized by layer |
-| `bin/` | CLI utilities (`gaia-scan`, `gaia-doctor`, etc.) |
+| `bin/` | Unified `gaia` CLI -- subcommands live in `bin/cli/*.py` |
 
 ## Coding Standards
 
@@ -81,7 +81,9 @@ See [README.md](./README.md) for the full directory tree. Key areas for contribu
 ### JavaScript / Node.js
 
 - ES modules (`import`/`export`), not CommonJS.
-- Follow the existing patterns in `bin/` and `index.js`.
+- The CLI surface is now Python (`bin/cli/*.py`); JS lives in `index.js`
+  (programmatic API helpers) and `bin/pre-publish-validate.js` /
+  `bin/python-detect.js` (tooling).
 
 ### Commit Messages