@jaguilar87/gaia 5.0.0-rc1 → 5.0.4

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-rc1",
+      "version": "5.0.4",
       "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-rc1",
+      "version": "5.0.4",
       "category": "security",
       "author": {
         "name": "jaguilar87",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia-ops",
-  "version": "5.0.0-rc1",
+  "version": "5.0.4",
   "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,11 +46,11 @@ 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
-    |  REVIEW (with approval_id) -> get approval -> resume via SendMessage
+    |  APPROVAL_REQUEST (with approval_id) -> get approval -> resume via SendMessage
     |  NEEDS_INPUT -> ask user -> resume via SendMessage
     |  BLOCKED -> report blocker
 ```
@@ -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
@@ -108,7 +107,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,9 +118,9 @@ 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, task breakdowns |
+| `planning_specs` | gaia-planner | briefs, plans (materializados cuando una conversación alcanza Cerrar) |
 | `gaia_system` | gaia-system | hooks, skills, agents/, CLAUDE.md |
 | `workspace` | gaia-operator | memory, email, schedules, file transfers |
 
@@ -141,12 +140,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)
@@ -172,7 +170,7 @@ Nonce-based T3 approval lifecycle:
 3. BashValidator generates 128-bit nonce via generate_nonce()
 4. write_pending_approval() saves pending-{nonce}.json to .claude/cache/approvals/
 5. Hook returns corrective deny (exit 0) with NONCE:{hex} in message
-6. Agent includes NONCE:{hex} in REVIEW status to orchestrator
+6. Agent includes NONCE:{hex} in APPROVAL_REQUEST status to orchestrator
 7. Orchestrator presents plan to user, asks for approval
 8. User approves -> orchestrator resumes agent with "APPROVE:{nonce}"
 9. pre_tool_use.py detects APPROVE: prefix, calls activate_pending_approval()
@@ -182,9 +180,9 @@ 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, REVIEW, BLOCKED, IN_PROGRESS), PENDING_STEPS, NEXT_ACTION, AGENT_ID
+- **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
 - **CONSOLIDATION_REPORT**: required when multi-surface or cross-check. Fields: OWNERSHIP_ASSESSMENT (enum), CONFIRMED_FINDINGS, SUSPECTED_FINDINGS, CONFLICTS, OPEN_GAPS, NEXT_BEST_AGENT
 
@@ -244,9 +242,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 +326,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,355 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+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
+
+Hotfix for rc.2. The previous release shipped successfully to npm under
+the `@rc` dist-tag but failed its post-publish sandbox harness gate
+because `bin/cli/approvals.py` used PEP 604 union syntax (`X | None`)
+which requires Python 3.10+ at module-import time. The publish.yml
+runner pins Python 3.9, and the `ci.yml` test matrix also includes 3.9.
+The plugin loader caught the resulting `ImportError` and emitted a
+`Warning:` line that leaked into stdout, breaking JSON parsing for
+several `gaia` subcommands on 3.9-only environments.
+
+#### Fixed
+- **Python 3.9 compatibility** — added `from __future__ import annotations`
+  to 7 files that used PEP 604 union syntax without it. With deferred
+  annotation evaluation, the type hints become string literals and no
+  longer execute the `|` operator at definition time. A repo-wide audit
+  of 21 PEP-604 files confirmed 14 were already safe (had `__future__`)
+  and 7 were the actual 3.9 breakers; all 7 are now fixed:
+  - `bin/cli/approvals.py` (the publish.yml-failing one)
+  - `bin/cli/plans.py`
+  - `bin/cli/context.py`
+  - `tests/cli/test_gaia_context.py`
+  - `tests/cli/test_gaia_plans.py`
+  - `tools/scan/tests/conftest.py`
+  - `tools/agentic-loop/record-iteration.py`
+
+The audit also confirmed no PEP 634 `match` statements, no `TypeAlias`,
+no runtime PEP 604 in `isinstance()`, and no runtime parameterized
+stdlib generics, so the `__future__` route is sufficient — no actual
+type-hint rewrites required.
+
+5.0.0-rc.2 is superseded by this release. Users on Python 3.10+ were
+unaffected by the bug; users on Python 3.9 should upgrade to rc.3.
+Failing run for reference:
+https://github.com/metraton/gaia/actions/runs/24951053090
+
+## [5.0.0-rc.2] - 2026-04-26
+
+### Release Candidate 2: Converger Identity, Session Liveness, Install-Gate Hardening
+
+Second release candidate for v5.0.0. Adds the orchestrator's Converger
+("Cerrar") conversational closure identity, real-PID session liveness in the
+registry, the `agent-creation` and `session-reflection` skills, and an
+end-to-end consumer-install validation harness that now actually exercises the
+gate. Three install-time bugs surfaced and were fixed alongside the harness
+that found them.
+
+#### Added
+- **Converger identity for orchestrator** — "Cerrar" conversational closure
+  framing. Brief-spec reframed as closure ritual (Size gate removed),
+  `planning_specs` surface routing narrowed to explicit artifact keywords,
+  architecture docs aligned with closure framing.
+- **session-reflection skill** — conversational session-close ritual. Surfaced
+  by orchestrator at session end; complements `gaia-compact`.
+- **agent-creation skill** — coach skill for designing new agents end-to-end:
+  identity, tool surface, contract, and verification.
+- **SessionEnd hook + PID liveness** — `session_end_hook.py` for clean
+  unregister; session_registry now uses real PID + `/proc` starttime to detect
+  liveness across sessions. `Stop` hook no longer mutates the registry (was
+  causing premature unregister mid-conversation).
+- **validate-sandbox.sh** — end-to-end consumer-install verification harness.
+  Two targets: `--target sandbox` (ephemeral fixture project) and
+  `--target local` (real workspace install with `--workspace` override). Eight
+  pass/fail checks: version, doctor, status, context show, memory stats,
+  memory search, scan, settings preservation. Wired into `publish.yml` so
+  every release smoke-tests the published tarball before notifying success.
+- **`gaia:verify-install:{local,rc,latest}` and `gaia:install-local`** scripts
+  in package.json for manual local validation against tarballs or registry.
+
+#### Changed
+- **REVIEW → APPROVAL_REQUEST** rename across active doctrine (state machine,
+  skills, hooks). Comments and references in `hooks/**` updated. The previous
+  `REVIEW` state caused confusion with the human review activity; the new name
+  reflects what the state actually represents (an agent requesting human
+  approval for a specific T3 operation).
+- **Stop hook decoupled from registry** — Stop event no longer mutates
+  session_registry. SessionEnd handles unregister cleanly; this avoids the
+  Stop-then-resume race where the registry would drop a still-active session.
+- **`publish.yml`** — sandbox harness step added after npm publish; waits for
+  registry propagation, then runs validate-sandbox.sh against the freshly
+  published tarball as a smoke test.
+
+#### Fixed
+- **Sandbox harness on noexec /tmp** — validate-sandbox.sh now detects
+  `noexec` mounts via `findmnt` (with `/proc/mounts` fallback) and falls back
+  to `$TMPDIR` → `/tmp` → `$HOME/.cache/gaia-sandbox`. Previously the harness
+  was unrunnable on WSL/Linux setups with `noexec /tmp` (rc=126 Permission
+  denied on the installed bin shims); the gate appeared to validate but never
+  actually ran.
+- **`gaia scan` harness check** — was invoking bare `gaia-scan --dry-run`,
+  which routes to `gaia-scan.py` whose argparse rejects `--dry-run`. Now uses
+  `gaia context scan --dry-run` (the higher-level CLI subcommand that does
+  accept `--dry-run`); drops the dead fallback.
+- **doctor `<lambda>` check** — `cmd_doctor` wrapped each check in a bare
+  `lambda`, so any exception surfaced as `'<lambda>'` in the JSON output
+  hiding which check actually failed. Replaced with `functools.partial` so
+  `__name__` resolves to the wrapped function (e.g. `check_project_dirs`).
+- **doctor `check_project_dirs` PosixPath/list TypeError** — code did
+  `project_root / dir_path` while iterating `paths.items()`; when a value was
+  a list (e.g. `"scan_targets": ["."]`), `Path / list` raised TypeError.
+  Values are now normalized to a flat sequence of `(label, str)` pairs before
+  joining; list values expand into `label[0]`, `label[1]`, ...
+- **postinstall FTS5 backfill on fresh install** — `maybeBackfillFts5()`
+  returned early when `search.db` was missing with comment "doctor --fix will
+  create it on first use", but nothing in the install flow runs `doctor --fix`
+  automatically. A consumer reinstalling after `gaia uninstall` (which scrubs
+  search.db) would have an empty FTS5 index until manual intervention. The
+  early return is gone; missing search.db now falls through to `doctor --fix`
+  which creates and populates the index.
+- **postinstall dynamic package resolution** — `gaia-update.js` now resolves
+  the gaia package name from `node_modules/@jaguilar87/` instead of
+  hardcoding, supporting both the v5+ `gaia` name and legacy `gaia-ops`. Also
+  detects and repairs symlinks pointing at the legacy path.
+- **memory sentinel return** — sentinel value returned with a surfaced warning
+  instead of a silent failure when memory paths fail to resolve.
+
+#### Internal
+- **Regenerated plugin artifacts** — `dist/gaia-ops/` and `dist/gaia-security/`
+  rebuilt for rc2.
+- **Cross-session liveness test** — real PID isolation in
+  `session_registry` test fixtures.
+
 ## [5.0.0-rc1] - 2026-04-21
 
 ### Release Candidate: Context Evals, Planner M1-M6, Memory CLI, Security Hardening
@@ -81,7 +430,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
 
@@ -174,7 +523,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
@@ -267,8 +616,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
@@ -565,7 +914,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
@@ -649,7 +998,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