@jaguilar87/gaia 5.0.2 → 5.0.5

package/skills/gaia-release/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gaia-release
-description: Use when testing, validating, or publishing Gaia releases -- live install, dry-run, RC, or stable
+description: Use when testing, validating, or publishing Gaia releases -- "install local", "dry-run", "release", live install, sandbox verify, RC, or stable
 metadata:
   user-invocable: false
   type: technique
@@ -8,24 +8,52 @@ metadata:
 
 # Gaia Release
 
-Single source of truth for install modes. Each mode exercises a different surface: live tests the working tree against a real workspace, dry-run tests the full install pipeline in an ephemeral sandbox, and the published channels (rc / latest) test npm registry delivery. Skipping a layer means discovering its bugs in production -- a clean dry-run does not prove that a freshly published tarball is what consumers actually receive, and a live install over an existing workspace does not predict a missing file on a clean project.
+The norm for getting Gaia onto a machine and into the registry. The user expresses exactly one of three intentions -- **install local**, **dry-run**, or **release** -- and each maps to a complete, automated sequence the orchestrator runs end-to-end. The user never recalls a sub-step and never runs a release script by hand: the script is a tool the flow invokes, not a command the human must remember. This is the lesson of the sagas that shipped broken: a release failed because a version source was bumped one file at a time and a forgotten `pyproject.toml` drifted; another needed a force-push to reconcile a tag. Every one of those was a manual step a human was trusted to remember and didn't. The fix is to norm the sequence so the steps cannot be forgotten -- they are the flow, not a checklist beside it.
 
-## Install Modes
+## The three intentions
 
-| Mode | Command | When to use |
-|------|---------|-------------|
-| **live self** | `cd /path/to/gaia && npm run gaia:install-local` | Re-install Gaia in the same workspace where Claude Code is running (e.g. `me/`). Validates working-tree changes against your dev environment. |
-| **live external** | `cd /path/to/gaia && bash bin/validate-sandbox.sh --tarball ./jaguilar87-gaia-*.tgz --target local --workspace /path/to/target` | Install the working tree into a different workspace (e.g. `qxo/`). Validates consumer-real conditions without touching your dev environment. |
-| **live fresh** | Add `--fresh` to either of the above | Wipes `node_modules/`, `package.json`, and `package-lock.json` from the target before install. Forces a clean postinstall run. |
-| **dry-run** | `npm run gaia:verify-install:local` | Pack + install into `/tmp/gaia-sandbox-<ts>/` + run the 8-check harness. Validates exactly what `npm publish` would ship. |
-| **RC** | Version bump to `X.Y.Z-rc.N` + GitHub Release | Pipeline publishes to npm with `--tag rc`. Consumers opt-in: `npm install @jaguilar87/gaia@rc`. |
-| **stable** | Version bump to `X.Y.Z` + GitHub Release | Pipeline publishes to npm with `--tag latest`. Default install: `npm install @jaguilar87/gaia`. |
+When the user says one of these, run the *whole* sequence. Do not stop after the first command and wait to be told the next one -- the sequence below IS the intention.
 
-For step-by-step commands per mode (including version-bump syntax, `--stay` for interactive inspection, and how to test both `ops` and `security` plugin modes), see `reference.md` -> "Mode runbooks".
+### "install local" -- put the working tree into a real workspace
 
-## Wire-up Verification Checklist
+```
+npm run gaia:install-local
+```
+Then, without being asked:
+1. Run the **Wire-up verification checklist** (below). If any check fails, jump to `reference.md` -> "Diagnostic guide".
+2. **Remind the user to restart `claude`** -- skills, hooks, and agents cache at startup, so a fresh install is invisible until restart.
 
-After any install (live, dry-run, RC, stable), the same checklist applies. If any check fails, jump to `reference.md` -> "Diagnostic guide".
+Installing into a *different* workspace (e.g. `qxo/`) or wiping install metadata first is the same intention with a different target -- see `reference.md` -> "Mode runbooks" for the `--workspace` and `--fresh` forms. Always pass `--workspace` explicitly when invoking from inside the gaia repo (the self-referencing `node_modules/@jaguilar87/gaia/` tricks auto-detect; guarded by `is_gaia_repo_root()` in `validate-sandbox.sh`).
+
+### "dry-run" -- prove a clean install works, reproducing CI locally
+
+This is not just the sandbox harness -- it is the **local stand-in for CI**, so it must run the same gates CI runs (see the pre-flight principle below). Run, in order:
+1. `npm run pre-publish:validate` -- the version-drift gate (`validate-manifests` in `ci.yml`).
+2. `npm run gaia:verify-install:local` -- packs, installs into `/tmp/gaia-sandbox-<ts>/`, runs the 8-check harness. Validates exactly what `npm publish` would ship.
+3. `npm test` -- the L1 suite (the harness/tests CI runs that reasonably reproduce locally).
+
+A green dry-run that skips step 1 is a *subset* of CI, not a stand-in for it -- the gap surfaces only after publish, when the fix costs another release.
+
+### "release [version]" -- end-to-end publish, fully automated
+
+The orchestrator runs every step below in order. The user supplies (or confirms) the version and approves the T3 operations; the orchestrator does the rest. **The user does not run `release:prepare` -- step (b) invokes it.**
+
+| Step | Action | Notes |
+|------|--------|-------|
+| **(a)** | Determine the version | Default to the next **patch**. If the change is major/minor, **confirm with the user** (`NEEDS_INPUT`) before proceeding -- never silently pick major/minor. |
+| **(b)** | `npm run release:prepare <version>` | The atomic core: bumps ALL version sources at once (`package.json`, `pyproject.toml`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `CHANGELOG.md`), runs `build:plugins`, then `pre-publish:validate`. Fails loud on any drift. This is `scripts/release-prepare.mjs` -- invoked by the flow, never by the user. |
+| **(c)** | Pre-flight that reproduces CI | `pre-publish:validate` already ran inside (b). Now run `npm test` (plus any harness that applies) so the local gate matches CI before the tag exists. |
+| **(d)** | Commit | `git add` + `git commit` -- local-only, not T3. |
+| **(e)** | Tag, **force-free** | A *new* tag (`v<version>`); never move an existing one. If the remote diverged, reconcile with **merge, not rebase** (rebase forces a tag move, hard-denied locally). See `reference.md` -> "Reconciling a diverged remote". |
+| **(f)** | Push | `git push` (T3). If diverged, the merge from (e) makes this force-free. |
+| **(g)** | `gh release create v<version>` | Triggers `publish.yml`, which builds, validates, and publishes to npm with the auto-detected tag (`-rc.` -> rc, else latest). Mark RC as pre-release. |
+| **(h)** | Monitor to the outcome | Watch the workflow run to its desenlace, then verify the package landed on npm (`npm run gaia:verify-install:rc` / `:latest`). The release is not done when the tag is pushed -- it is done when npm serves the new version. |
+
+For the full command forms, the schema-migration lockstep, and the diverged-remote reconciliation, see `reference.md`.
+
+## Wire-up verification checklist
+
+After any install (install local, dry-run sandbox, RC, stable), the same checklist applies. If any check fails, jump to `reference.md` -> "Diagnostic guide".
 
 1. `ls -la <workspace>/.claude/` -- 7 symlinks (agents, hooks, skills, commands, config, templates, tools) + `logs/`, `approvals/`, `plugin-registry.json`, `settings.local.json`.
 2. `cat <workspace>/.claude/plugin-registry.json` -- `installed[].name` includes `gaia-ops` (or `gaia-security`) at the expected version.
@@ -36,25 +64,33 @@ After any install (live, dry-run, RC, stable), the same checklist applies. If an
 
 These six checks are not redundant with `gaia doctor`. Steps 1-5 catch what doctor cannot reach when the wire-up is so broken that doctor itself walks up to the user `.claude/` instead of the workspace.
 
-## Release Checklist
-
-Pre-publish, publish, and post-publish steps -- plus the schema migration protocol when `EXPECTED_SCHEMA_VERSION` changes -- live in `reference.md` -> "Release checklist" and "Schema migration protocol". Both are read on-demand from the SKILL when actually doing a release; they are not in this file because they would dominate the line budget without informing the day-to-day mode decision.
-
 ## CI/CD
 
 | Workflow | File | Triggers |
 |----------|------|----------|
-| CI | `.github/workflows/ci.yml` | Push / PR -- runs pytest (Python 3.9/3.11/3.12), Node tests, and plugin build verification |
+| CI | `.github/workflows/ci.yml` | Push / PR -- runs pytest (Python 3.11/3.12), Node tests, plugin build verification, and `validate-manifests` |
 | Publish | `.github/workflows/publish.yml` | GitHub Release event -- builds plugins, validates artifacts, auto-detects npm tag from version (`-rc.` -> rc, `-beta.` -> beta, else -> latest), and publishes |
 
 `NPM_TOKEN` lives in GitHub Secrets; local `npm publish` bypasses build verification and is not the supported path.
 
+## Principles -- why the sequence is normed, not optional
+
+- **The pre-flight reproduces what CI validates, not a subset of it.** When the local check skips a gate CI runs (`pre-publish:validate`), that gate's failures surface only *after* publishing, on the published tarball, where the only remedy is another release. That is exactly how a `pyproject.toml` drift shipped green-local and red-CI. The "dry-run" intention and step (c) of "release" close the gap -- `pre-publish:validate` for drift. See `reference.md` -> "The pre-flight reproduces what CI validates".
+- **Bump every version source in one step, never one at a time.** `pre-publish:validate` requires `package.json`, `pyproject.toml`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, and the `CHANGELOG.md` top header to agree. A partial bump leaves the tree in a state the validator rejects and lets a stale source ship. `release:prepare` writes all of them from one target version, so a hand-desync is impossible. See `scripts/release-prepare.mjs`.
+- **Tag force-free; reconcile with merge, never rebase.** `publish.yml` commits built artifacts back to `main`, so the remote leads after every release. Rebasing rewrites hashes and forces a tag move (`git tag -f` / `--force`), hard-denied by local hooks (`git_destructive` in `blocked_commands.py`, exit 2, not approvable). Merge preserves hashes and tags; a new release gets a *new* tag, never a moved one. See `reference.md` -> "Reconciling a diverged remote".
+- **A release ends at npm, not at the tag.** Pushing the tag only starts `publish.yml`. The intention is not satisfied until the workflow reaches its outcome and npm serves the new version -- step (h) is part of the sequence, not a follow-up.
+
 ## Anti-Patterns
 
-- **Live-only testing** -- live install runs against your accumulated workspace state; only dry-run proves a clean-install works.
+- **Stopping after the first command of an intention** -- "install local" is not just `gaia:install-local`; "release" is not just `release:prepare`. Each intention is the *whole* sequence. Running one command and waiting to be told the next reintroduces the forgettable manual step the norm exists to remove.
+- **Asking the user to run `release:prepare`** -- it is a tool the "release" flow invokes at step (b), not a command the human runs. Surfacing it as a manual step is the same failure mode (a step someone must remember) wearing a new script.
+- **Pre-flight that is a subset of CI** -- skipping `pre-publish:validate` locally means the version drift surfaces after publish. Reproduce CI; do not approximate it.
+- **Bumping version sources one at a time** -- desyncs a source by hand; `pre-publish:validate` rejects the tree and a forgotten file ships if the check is skipped. Always go through `release:prepare`.
+- **Rebase to reconcile a diverged remote** -- forces a tag move, hard-denied locally. Merge instead.
+- **Live-only testing** -- live install runs against accumulated workspace state; only dry-run proves a clean install works.
 - **Local npm publish** -- bypasses the pipeline's build verification step.
 - **Single-mode testing** -- `ops` and `security` load different skill sets and hook configurations; one can break while the other passes.
-- **Stale dist/** -- forgetting `npm run build:plugins` before pack means validating old code.
-- **Missing restart** -- the process caches skills, hooks, and agents at startup; mode switches and fresh installs require restarting `claude`.
-- **Ignoring `~/.gaia/last-install-error.json`** -- when postinstall fails silently, this is the marker that says so. Treat its presence as a hard failure regardless of what `gaia doctor` reports.
-- **Relying on auto-detect when cwd is inside the gaia repo** -- the repo has a self-referencing `node_modules/@jaguilar87/gaia/` entry that can trick the workspace detector. Always pass `--workspace /home/jorge/ws/me` explicitly when running installs from within the gaia repo. Verify with `readlink /home/jorge/ws/me/.claude/hooks` post-install -- it must point to the consumer workspace's `node_modules`, not the repo's.
+- **Stale dist/** -- forgetting `npm run build:plugins` before pack means validating old code. `release:prepare` and `build:plugins` regenerate it; dry-run packs fresh.
+- **Missing restart** -- the process caches skills, hooks, and agents at startup; installs and mode switches require restarting `claude`.
+- **Ignoring `~/.gaia/last-install-error.json`** -- when postinstall fails silently, this is the marker. Treat its presence as a hard failure regardless of what `gaia doctor` reports.
+- **Relying on auto-detect when cwd is inside the gaia repo** -- the self-referencing `node_modules/@jaguilar87/gaia/` entry tricks the workspace detector. Pass `--workspace /home/jorge/ws/me` explicitly; verify with `readlink /home/jorge/ws/me/.claude/hooks`.

package/skills/gaia-release/reference.md

@@ -44,7 +44,7 @@ Append `--fresh` to either form. The harness will delete `node_modules/`, `packa
 **What postinstall does:**
 1. Ships `scripts/` (bootstrap_database.sh) -- failed silently in pre-rc.4 builds; verified in `npm pack --dry-run`.
 2. Creates `.claude/` if missing.
-3. Runs `bootstrap_database.sh` -- seeds the schema (v17), agent rows, and `schema_version`. Fails loud on any error (writes `~/.gaia/last-install-error.json` and exits non-zero).
+3. Runs `bootstrap_database.sh` -- seeds the schema (current floor v18), agent rows, and `schema_version`. Fails loud on any error (writes `~/.gaia/last-install-error.json` and exits non-zero).
 4. Merges hooks into `settings.local.json` via the consolidated `merge_hooks` step.
 5. Creates 7 symlinks under `.claude/` to `node_modules/@jaguilar87/gaia/<dir>/`.
 6. Writes `plugin-registry.json` with `installed[].name == "gaia-ops"`.
@@ -87,20 +87,32 @@ A change that works in one mode can break the other because they load different
 
 ### RC and stable (pipeline)
 
-Both modes share the same pipeline. The pipeline auto-detects the npm tag from the version string.
+Both modes share the same pipeline. The pipeline auto-detects the npm tag from the version string. These steps are the expansion of the "release" intention in `SKILL.md`; the orchestrator runs them, the user supplies/confirms the version.
 
 1. Dry-run must pass locally first.
-2. Version bump:
-   - RC: edit `package.json` to `X.Y.Z-rc.N` (the tooling does not provide a single-shot `npm version` for RC; bump manually + rebuild dist/).
-   - Stable: `npm version minor` (or `major` / `patch` as appropriate).
-3. Rebuild `dist/`: `npm run build:plugins`.
-4. Update `dist/*/plugin.json` and `marketplace.json` to match the new version.
-5. Commit + push (PR or direct to main).
+2. **`npm run release:prepare <version>`** -- the atomic bump. This is `scripts/release-prepare.mjs`, invoked by the flow, **never run by the user by hand**. In one command it:
+   - writes `<version>` to ALL sources at once -- `package.json`, `pyproject.toml`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` (every plugin entry), and the `CHANGELOG.md` top header (inserts a dated stub above the current top if absent -- edit its body before release);
+   - runs `npm run build:plugins` to regenerate `dist/` (including the per-plugin manifests that carry the version);
+   - runs `npm run pre-publish:validate` and fails loud on any drift.
+
+   This replaces hand-bumping one file at a time. `pre-publish:validate` fails the release unless every version source agrees, and the two real escapes a hand-bump leaves are a `pyproject.toml` left behind on a prior version (caught only by `pre-publish:validate`) and a `marketplace.json` that still advertises the old tag. `release:prepare` makes the desync impossible because all sources are written from one target version. For a bare semver: `5.0.5` for stable, `5.1.0-rc.1` for RC (no leading `v` -- the tag adds it). The script is idempotent: re-running with the same version is a no-op bump that re-validates.
+3. Pre-flight that reproduces CI (steps already partly done inside `release:prepare`): `npm test`. `pre-publish:validate` ran in step 2.
+4. Commit (`git add` + `git commit` -- local-only, not T3). **If the remote diverged, reconcile with MERGE, never rebase** (see "Reconciling a diverged remote" below).
+5. Tag (force-free -- a *new* `v<version>`, never moved) + push (`git push`, T3). The merge in step 4 keeps the push force-free.
 6. Create a GitHub Release:
    - Tag: the version from `package.json` (e.g., `v5.0.0-rc.4` or `v5.3.0`).
    - Title: the version.
    - Mark RC releases as pre-release.
 7. `publish.yml` triggers automatically and publishes with `--tag <auto-detected>`.
+8. Monitor the workflow run to its outcome, then verify npm serves the new version (`npm run gaia:verify-install:rc` / `:latest`). The release is done at npm, not at the tag.
+
+### Reconciling a diverged remote -- merge, never rebase; never move a tag
+
+`publish.yml` commits built artifacts back to `main` and pushes (the "Commit built plugins" step), so after a release the remote `main` is *ahead* of your local. When you next go to release and find the remote diverged, the reconciliation choice is forced by local policy:
+
+- **Reconcile with merge, not rebase.** Rebase rewrites your local commit hashes. If a tag already pointed at one of those commits, you would have to re-point it -- which means `git tag -f` or a force-push of the tag. Both match the `git_destructive` pattern in `hooks/modules/security/blocked_commands.py` and are **hard-denied locally** (exit 2, not approvable) -- there is no `approval_id` that unblocks them. Merge preserves the existing hashes, so existing tags stay valid and no force is ever needed.
+- **Tags are create-only -- never move one.** A published tag is immutable history; a new release gets a *new* tag (`-rc.N+1`, next patch/minor), it does not re-point an old one. Moving a tag requires the same force path that local hooks deny.
+- **The force-deny is a local hooks policy, not a CI one.** `publish.yml` itself runs `git tag -f` and `git push --force` for the tag after committing `dist/` -- that is the pipeline operating under its own permissions, outside the local hook layer. Do not read the pipeline's force-push as license to force locally; the local deny stands regardless of what CI does.
 
 **Verify from npm** (registry round-trip):
 - RC: `npm run gaia:verify-install:rc`
@@ -134,17 +146,29 @@ When you bump `EXPECTED_SCHEMA_VERSION` in `bin/cli/doctor.py`, the four steps b
 3. Add migration SQL (`UPDATE` / `ALTER TABLE`) when existing DBs need to upgrade in place; otherwise old workspaces stay below the expected version and `gaia doctor` fails.
 4. Run `pytest tests/cli/test_schema_version_lockstep.py` -- it cross-references the constant, the bootstrap insert, and the migration SQL to confirm they all agree.
 
+### Build/pre-publish Schema-Drift Guard
+
+`bin/pre-publish-validate.js` Step 5c runs `scripts/check_schema_drift.py`, which sha256-fingerprints `gaia/store/schema.sql` and compares it against `scripts/migrations/schema.checksum` (pinned to `EXPECTED_SCHEMA_VERSION`). If the schema has changed but the version was not bumped and no migration file added, the guard fails the build.
+
+**Consequence:** if you edit `schema.sql` you MUST either (a) bump `EXPECTED_SCHEMA_VERSION` + add the migration file (following the lockstep above), OR (b) re-pin the checksum with `python3 scripts/check_schema_drift.py --record` (the escape hatch for pure-comment or non-semantic edits). Without one of these, `npm run pre-publish:validate` — and therefore `release:prepare` — will FAIL.
+
 ## Release Checklist
 
+### The pre-flight reproduces what CI validates, not a subset of it
+
+A green pre-flight only protects the release if it runs the same gates CI runs. When the local check is a *subset* of CI, the gaps CI covers are discovered after publishing -- on the published tarball, where the only remedy is another release. `npm run gaia:verify-install:local` packs and installs into a sandbox, but it does **not** run `pre-publish:validate`. CI (`.github/workflows/ci.yml`) runs it separately. A real failure escaped exactly through that gap: a `pyproject.toml` version drift that only `pre-publish:validate` catches, which was green locally and red in CI *after* the tag was pushed.
+
+So the pre-flight must close that gap before any tag or push:
+
 **Pre-publish:**
 - `pytest tests/` green (or `npm test` for the L1 subset).
+- **`npm run pre-publish:validate` green locally** -- this is the version-drift gate (`validate-manifests` job in `ci.yml`). Run it before tag/push, not only in CI. It is what catches a `pyproject.toml` / `package.json` / `plugin.json` / `marketplace.json` desync before it ships.
 - `npm pack --dry-run | grep scripts/` confirms `scripts/bootstrap_database.sh` is included in the tarball.
 - `bash bin/validate-sandbox.sh --tarball ./jaguilar87-gaia-*.tgz --target sandbox --fresh` green (or `npm run gaia:verify-install:local`).
 - Optional smoke: `npm run gaia:install-local -- --workspace /tmp/test-install --fresh`.
 
 **Publish:**
-- Bump version in `package.json`, `dist/*/plugin.json`, and `marketplace.json`.
-- `npm run build:plugins` regenerates `dist/`.
+- Run `npm run release:prepare <version>` -- atomically bumps all version sources (`package.json`, `pyproject.toml`, `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`), regenerates `dist/` via `build:plugins`, and runs `pre-publish:validate` (including the schema-drift guard). Nothing else should write a version.
 - Commit + push.
 - Create GitHub Release with the version tag.
 - Pipeline publishes (`publish.yml` triggers on Release event):
@@ -165,7 +189,7 @@ The workflow at `.github/workflows/publish.yml` runs on every GitHub Release eve
 - Installs deps with `npm ci`.
 - Builds plugins with `npm run build:plugins`.
 - Verifies all expected artifacts in `dist/`.
-- Commits built artifacts back if changed.
+- Commits built artifacts back if changed (commit message carries `[skip ci]` so the dist commit-back does not re-trigger CI).
 - Runs `npm run pre-publish:validate`.
 - Auto-detects npm tag from version string (see "Publish" above).
 - Publishes with `npm publish --access public --tag <detected>`.

package/skills/git-conventions/SKILL.md

@@ -43,5 +43,9 @@ requires explicit user instruction.
 
 ## Hook Enforcement
 
-The `commit_validator.py` hook validates against `config/git_standards.json`.
-Format violations block the commit. Body line length triggers warnings only.
+The `commit_validator.py` hook validates against standards inlined as
+module-level constants in that file (`TYPE_ALLOWED`, `SUBJECT_MAX_LENGTH`,
+`SUBJECT_RULES`, `BODY_MAX_LINE_LENGTH`) -- it covers the conventional-commits
+format, subject, and body rules. Forbidden-footer detection lives separately
+in `bash_validator` (hardcoded there). Format violations block the commit.
+Body line length triggers warnings only.

package/skills/orchestrator-present-approval/SKILL.md

@@ -30,9 +30,16 @@ without the data needed to decide. The job is **verbatim relay, not
 re-authoring**: rewriting any of the 7 sealed fields breaks the fingerprint and
 `verify_fingerprint` (`gaia/approvals/chain.py`) raises `ChainTamperError`.
 
-## Step 0 -- Fingerprint validation (mandatory before SHOWN)
+## Step 0 -- Verify the approval against the DB (mandatory before SHOWN)
 
-Before AskUserQuestion, call `verify_fingerprint(approval_id, payload_json, con) -> bool` from `gaia/approvals/chain.py`. It raises `ChainTamperError` if the payload was modified between subagent emission and your relay (security boundary, do not present), and `ValueError` if no REQUESTED event exists for this `approval_id`. Either case: **do not present**, report the failure, stop.
+A subagent's reported `approval_id` is an unverified claim, not a fact. The agent runs in its own context and can relay an id that is stale, from another session, or simply wrong -- and a stale id presented as a fresh block walks the user into consenting to nothing real (or to a grant that no longer exists). The DB is the source of truth; the agent's report is a pointer into it that you must resolve, never the authority itself.
+
+So before AskUserQuestion, two checks against the DB, in order:
+
+1. **The approval exists, is fresh, and is from the current session.** Query `gaia approvals pending --session "$CLAUDE_SESSION_ID"` (or `--json` for parsing). The reported `approval_id` MUST appear in that result. If it appears only under `--all-sessions` but not the current session, it is leakage from another session (a test session such as `e2e-sim`, a prior run) -- **do not present**. If it does not appear at all, it does not exist or was already consumed/rejected -- **do not present**. Freshness is the `created_at` of the pending row plus its presence as still-`pending`; an id the agent reports that is not currently pending in *this* session is not a fresh block, whatever the agent says.
+2. **The payload is untampered.** Call `verify_fingerprint(approval_id, payload_json, con) -> bool` from `gaia/approvals/chain.py`. It raises `ChainTamperError` if the payload was modified between subagent emission and your relay (security boundary, do not present), and `ValueError` if no REQUESTED event exists for this `approval_id`. Either case: **do not present**, report the failure, stop.
+
+**For a `command_set` (plan-first batch) the agent does not know the id at all.** The hook mints the `approval_id` at SubagentStop (`_intake_command_set_pending` -- see Rule 3); the subagent emits the `command_set` with **no** `approval_id`. So you do not have an agent-reported id to trust even if you wanted to -- you ALWAYS recover the freshly minted id from `gaia approvals pending` for the current session. This is the general shape made unavoidable: the DB mints, the orchestrator recovers, the agent never owns the id.
 
 ## Mandatory presentation -- 5 labeled fields + nonce-suffixed label
 
@@ -71,12 +78,27 @@ Fields above are extracted from the DB-stored canonical payload (`payload_json`
    grant consumed by the first retry (`consume_db_semantic_grant` in
    `gaia/store/writer.py`). A second invocation is a new APPROVAL_REQUEST.
 
-3. **No batch grant.** Legacy `verb_family` was removed; the `COMMAND_SET`
-   replacement has only the CHECK side wired (`match_command_set_grant` is
-   called by `bash_validator`, but `create_command_set_grant` has no production
-   caller). `batch_scope` is ignored. For N commands, expect N approvals.
+3. **Batch grant is `COMMAND_SET` -- one consent, N commands.** Legacy
+   `verb_family` was removed; its replacement, `COMMAND_SET`, is now wired
+   end-to-end (intake, activation, consume). When a subagent emits a plan-first
+   `APPROVAL_REQUEST` carrying a `command_set` of >= 2 `{command, rationale}`
+   items and **no** `approval_id`, the SubagentStop processor
+   (`handoff_persister._intake_command_set_pending`) mints ONE pending
+   `COMMAND_SET` with one `approval_id`. You present that single approval: list
+   **all N commands** in the question body, but use **one** Approve label with
+   **one** `[P-{nonce8}]` suffix -- one consent covers the whole batch. On
+   approval, `activate_db_pending_by_prefix` Step 3b creates a single
+   `COMMAND_SET` grant (60-min TTL); each command is consumed byte-for-byte on
+   its own retry. `batch_scope` is still ignored (the signal is `command_set`).
    See `reference.md` -> "On batch intents".
 
+   You present the batch the subagent chose to send; you do not steer it toward
+   batching. Whether grouping is warranted is the subagent's judgment (known
+   batch, >= 2, friction reduced -- see `subagent-request-approval`). A singular
+   approval arriving where you imagined a batch is not a defect to correct: the
+   default is just-in-time, and a batch you would have manufactured asks the
+   user to consent to commands that may never run.
+
 4. **Re-dispatch, do not resume.** `mode` does not survive a SendMessage resume:
    the resume runs in `default` and re-blocks the next protected operation even
    after the Gaia grant activated. Prefer a fresh re-dispatch with the same
@@ -97,5 +119,6 @@ wording, see `reference.md` -> "GOOD vs BAD Examples", "Option Label Patterns",
 | "I'll skip the [P-...] suffix, it's cosmetic" | The hook extracts the nonce from the label to find the right pending row; without it, targeted activation fails and no grant is created. |
 | "Similar command, slightly different path -- I'll reuse / wrap it" | Grants match the statement signature byte-for-byte. Any wrapper, redirect, flag, or path drift is a different signature and a fresh re-block. |
 | "The same command emitted a new approval_id" | Grants are single-use and consumed on the first retry. A second run is a new APPROVAL_REQUEST -- approve again. |
-| "I'll set batch_scope to approve many at once" | No batch activation exists in current code -- the field is ignored. Each blocked command needs its own approval. |
+| "I'll set batch_scope to approve many at once" | `batch_scope` is ignored -- but a real batch path exists: a plan-first `command_set` (>= 2 items, no `approval_id`) is intaken into ONE pending `COMMAND_SET`. Present that single approval (N commands shown, one `[P-...]` nonce, one consent), not N separate approvals. |
 | "I can paraphrase a field before relaying" | The fingerprint covers all 7 sealed fields; any modification raises `ChainTamperError` in Step 0 and the presentation is refused. |
+| **"The agent reported an `approval_id`, so it's a real fresh block"** -- trusting a nonce relayed by the subagent | The agent's reported id is an unverified pointer, not a fact. It can be stale or belong to another session -- subagents have presented a STALE nonce from a test session (`e2e-sim`) as if it were a fresh block. Resolve every reported id against `gaia approvals pending --session "$CLAUDE_SESSION_ID"` (Step 0): it must be currently pending in *this* session. Visible only under `--all-sessions`, or absent entirely, means do not present. For `command_set` the hook mints the id and the agent never has one -- you always recover it from the DB. |

package/skills/orchestrator-present-approval/reference.md

@@ -107,32 +107,49 @@ contain `[P-<hex>]`. Reject labels never carry a nonce. The captured hex is the
 `get_pending(all_sessions=True)` and selects the one whose `id` starts with
 `P-{prefix}`.
 
-## On batch intents -- there is no multi-use grant
+## On batch intents -- the COMMAND_SET grant (one consent, N commands)
 
 The old `verb_family` design (one approval covering many commands of the same
 `base_cmd + verb`) **was removed**. The module docstring in
 `hooks/modules/security/approval_grants.py` is explicit: "The legacy verb_family
 path has been removed."
 
-The intended replacement is the `COMMAND_SET` grant: an explicit list of
+Its replacement is the `COMMAND_SET` grant: an explicit list of
 `{command, rationale}` items, each matched **byte-for-byte** (D10: no whitespace
 normalization, no quote canonicalization, no shell expansion) and consumed
 individually (`create_command_set_grant` and `match_command_set_grant` in
 `approval_grants.py`).
 
-**Current state of the code:** only the CHECK side is wired. `bash_validator`
-(`hooks/modules/tools/bash_validator.py`) calls `match_command_set_grant()` and
-consumes a matched item, but **no production path calls
-`create_command_set_grant()`** -- it exists only in the module and its tests.
-The ElicitationResult / adapter activation paths (`hooks/elicitation_result.py`,
-`hooks/adapters/claude_code.py`) contain no "batch", "verb_family", "multi_use",
-or "command_set" handling; they only call `activate_db_pending_by_prefix()`,
-which creates a single-use `SCOPE_SEMANTIC_SIGNATURE` grant.
-
-**Practical consequence:** putting the word "batch" in a label, or a `batch_scope`
-field in an `approval_request`, does nothing. Each blocked command produces its
-own single-use semantic grant and its own approval. For a sweep of N commands,
-expect N approvals until the COMMAND_SET create path is wired.
+**Current state of the code: all three sides are wired -- intake, activation,
+consume.** It is a **plan-first** flow: the subagent declares the batch up-front
+by emitting an `APPROVAL_REQUEST` whose `approval_request` carries a
+`command_set` list and **no** `approval_id`.
+
+- **Intake.** The SubagentStop processor
+  `hooks/modules/agents/handoff_persister.py` ->
+  `_intake_command_set_pending()` reads the `command_set`; when it holds **>= 2**
+  items it calls `gaia.approvals.store.insert_requested()` with a payload that
+  contains the `command_set` key, minting **exactly ONE** pending `COMMAND_SET`
+  approval with one `approval_id`. A set of `<= 1` item is declined (no
+  COMMAND_SET is minted for one command).
+- **Activation.** When the user approves, `activate_db_pending_by_prefix()`
+  (`hooks/modules/security/approval_grants.py`) reads `payload["command_set"]`,
+  and because it has > 1 item branches at **Step 3b** into
+  `create_command_set_grant()`, inserting ONE `COMMAND_SET` grant row (status
+  `PENDING`, `command_set_json` holding the whole set, 60-min TTL via
+  `DEFAULT_COMMAND_SET_TTL_MINUTES`) instead of a singular
+  `SCOPE_SEMANTIC_SIGNATURE` grant.
+- **Consume.** On each retry, `bash_validator` calls `match_command_set_grant()`
+  (byte-for-byte index match), then `mark_command_set_item_consumed()`; a
+  consumed index never matches again (replay protection), and when every index
+  is consumed the grant flips to `CONSUMED`.
+
+**Practical consequence:** a `batch_scope` field still does nothing -- the signal
+is `command_set`. To approve a sweep of N related commands under one consent,
+present the single `COMMAND_SET` approval the intake minted: show **all N
+commands** in the question body, with **one** Approve label carrying **one**
+`[P-{nonce8}]` suffix. The user gives one consent; each command then runs on its
+own retry within the 60-minute window. You do NOT issue N separate approvals.
 
 ## Grant Activation Mechanics
 

package/skills/readme-writing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: readme-writing
-description: Use when writing or updating a README for a Gaia component folder (agents/, skills/, hooks/, commands/, config/, bin/, tests/, build/, templates/, or the repo root)
+description: Use when writing or updating a README for a Gaia component folder (agents/, skills/, hooks/, commands/, config/, bin/, tests/, build/, or the repo root)
 metadata:
   user-invocable: false
   type: technique

package/skills/readme-writing/reference.md

@@ -185,4 +185,3 @@ Copy this when writing a README from scratch. Fill every section -- do not delet
 | `bin/` | Low -- CLI tools, user-invoked | No |
 | `tests/` | Low -- run by CI or developer | No |
 | `build/` | Medium -- triggered by npm run build | Optional |
-| `templates/` | Low -- read by build scripts | No |

package/skills/security-tiers/SKILL.md

@@ -17,7 +17,11 @@ security-tiers classifies every operation into four tiers so an agent knows whet
 | **T0** | Read-only; observes state, changes nothing | No | get, list, describe, show, logs, status |
 | **T1** | Local validation; no remote calls, no state | No | validate, lint, fmt, check |
 | **T2** | Simulation / dry-run; may read remote, never writes | No | plan, diff, dry-run, template |
-| **T3** | State-mutating; creates, updates, or destroys | **Yes** | apply, create, delete, commit, push, deploy |
+| **T3** | State-mutating; creates, updates, or destroys | **Yes** | apply, create, delete, push, deploy |
+
+`git commit` and `git add` are **not** T3 -- they are local-only operations (they touch the working tree and local refs, never remote state), so they classify as safe by elimination. Only `git push` mutates remote state and is T3. This matches `GIT_LOCAL_SAFE_SUBCOMMANDS` in `mutative_verbs.py`, where `commit` and `add` are listed as local-safe.
+
+**T3 gates a direction, not a category of verb.** An operation needs consent because it moves the system toward *more* capability (it grants) or *less* recoverability (it destroys). An operation that only moves the other way -- that *reduces* capability already granted -- does not need consent, because the worst it can do is take back power that was given. So within Gaia's own consent layer, `gaia approvals revoke|reject|reject-all|clean` are **not** T3: they only revoke or discard grants Gaia itself issued, never reaching outside the local approval store. The asymmetry is deliberate -- `gaia approvals approve` *grants* capability without the AskUserQuestion flow, so it stays T3. This is anchored to the `gaia approvals` group in `CONSENT_REDUCING_SUBCOMMAND_EXCEPTIONS` (`mutative_verbs.py`), not generalized to every CLI's "revoke" -- a cloud IAM revoke is a real remote mutation and remains T3.
 
 ## Classification heuristic
 

package/skills/security-tiers/reference.md

@@ -36,7 +36,9 @@ Read on-demand by infrastructure agents. Not injected automatically.
 - `kubectl apply -f manifest.yaml`
 - `helm upgrade` (without `--dry-run`)
 - `flux reconcile` (write operations)
-- `git commit`, `git push` (any branch)
+- `git push` (any branch) -- mutates remote state
+
+Note: `git commit` and `git add` are **not** T3. They are local-only (working tree + local refs, never remote), classified safe by elimination via `GIT_LOCAL_SAFE_SUBCOMMANDS` in `mutative_verbs.py`. Only `git push` reaches remote state.
 
 ## Edge Cases
 

package/skills/subagent-request-approval/SKILL.md

@@ -63,12 +63,47 @@ prose are invisible to the presentation -- the user would approve blind.
 - **The grant is single-use.** It is consumed on your first matching retry. A
   second run within the TTL will not match -- it needs a fresh approval.
 
-## Batch / many-command intents
-
-There is **no `batch_scope` field** and no production batch grant: each blocked
-command is one single-use approval, so a sweep of N commands is N approvals.
-The `COMMAND_SET` mechanism exists in code but no path activates it from an
-approval, so emitting `batch_scope` does nothing. See `reference.md` for why.
+## Batch / many-command intents -- COMMAND_SET as a judgment, not a default
+
+Grouping commands under one consent is a **judgment call you earn, not the
+reflex you reach for**. The default is singular, just-in-time approval: attempt
+the command, let the hook block it, request that one. Reach for `COMMAND_SET`
+**only when all three hold** -- the batch is already **known** (the commands are
+determined, not predicted), there are **>= 2** of them, and grouping **actually
+reduces friction** versus approving each as it arrives. If any fails (a single
+command, a sequential flow where the next depends on the last's output, or a
+set you cannot yet name), use the singular path. The principle with its
+consequence: **grouping trades the user's per-command visibility for fewer
+prompts; make that trade only when the batch is real and known, because a batch
+you guessed at asks the user to approve commands that may never run.**
+
+The hard prohibition this rules out: **never invent or predict commands just to
+have something to group.** Speculatively enumerating a `command_set` to "save
+turns" inverts the cost -- it manufactures ceremony (a multi-command consent
+surface) around work that was never determined, which is more overhead than the
+just-in-time blocks it was meant to avoid. If you do not already know the
+commands, you do not have a batch.
+
+When the three conditions do hold, emit an `APPROVAL_REQUEST` whose
+`approval_request` carries a `command_set` -- a list of `{command, rationale}`
+items -- and **no `approval_id`** (nothing has been attempted yet). The
+per-command rationale is what makes the grouped consent honest: the user sees
+why each *known* command is in the batch before approving (D10).
+
+What happens to that envelope: the SubagentStop processor
+(`hooks/modules/agents/handoff_persister.py` -> `_intake_command_set_pending`)
+reads the `command_set`, and when it holds **>= 2** items it calls
+`gaia.approvals.store.insert_requested` with a payload containing the
+`command_set` key. That mints **exactly ONE pending `COMMAND_SET` approval**
+with one `approval_id` -- so a batch of N commands is **one consent, N
+commands**, not N approvals. A set of `<= 1` item is not a batch: it does not
+mint a COMMAND_SET (use the normal singular block path for a single command).
+
+On the user's approval, that one pending activates into a single `COMMAND_SET`
+grant (60-minute TTL); each item is then consumed byte-for-byte on its own
+retry, with replay protection, until the whole set is `CONSUMED`. See
+`reference.md` for the envelope shape, the intake processor, the grant TTL, and
+the consume path.
 
 ## Pointers
 
@@ -84,3 +119,5 @@ approval, so emitting `batch_scope` does nothing. See `reference.md` for why.
 - **Fabricating `approval_id`, fingerprint, or `sealed_payload`** -- the orchestrator validates against the DB; invented values never match.
 - **Reusing a prior approval** -- single-use, consumed on first retry.
 - **Emitting `batch_scope`** -- the field does not exist; it is ignored.
+- **Grouping by reflex** -- reaching for `COMMAND_SET` because a batch *might* form, instead of because a known batch of >= 2 already exists that grouping makes cheaper. The default is singular just-in-time; grouping is the exception you justify.
+- **Predicting commands to fill a batch** -- inventing commands you have not determined so a `command_set` has >= 2 items. You cannot ask consent for work that does not yet exist; the speculative batch is pure overhead.

package/skills/subagent-request-approval/reference.md

@@ -69,35 +69,85 @@ On your retry, `check_approval_grant()` matches it and immediately consumes it
 TTL will NOT match -- the grant is gone. This is replay protection by design;
 re-approve if you need to run the command again.
 
-## Batch / COMMAND_SET -- designed, not wired
+## Batch / COMMAND_SET -- wired
 
 The legacy `verb_family` multi-use grant was removed (see module docstring in
-`approval_grants.py`: "The legacy verb_family path has been removed"). Its intended
+`approval_grants.py`: "The legacy verb_family path has been removed"). Its
 replacement is the `COMMAND_SET` grant -- an explicit list of `{command, rationale}`
 items, each matched byte-for-byte and consumed individually
 (`approval_grants.create_command_set_grant()`; `approval_grants.match_command_set_grant()`).
+All three sides are now wired end-to-end -- **intake**, **activation**, and
+**consume** -- so one consent covers N commands.
+
+**Intake -- plan-first, one pending.** The batch is declared up-front: you emit
+an `APPROVAL_REQUEST` whose `approval_request` carries a `command_set` list and
+**no `approval_id`** (you have attempted nothing). The production intake caller
+is the SubagentStop processor `handoff_persister.persist_handoff()`, which calls
+`_intake_command_set_pending()`. That helper normalizes the `command_set` and,
+when it holds **>= 2** `{command, rationale}` items, builds a sealed_payload
+carrying the `command_set` key (mirroring the shape
+`bash_validator._build_sealed_payload()` emits) and calls
+`gaia.approvals.store.insert_requested()` -- minting **exactly ONE** pending
+`COMMAND_SET` approval with one `approval_id`. A set of length `<= 1` is not a
+batch: the intake declines and the singular semantic-signature path owns it (no
+COMMAND_SET is ever minted for one command). The intake runs independently of
+the audit handoff-row write, so a batch consent is never lost to an unrelated
+DB failure.
+
+**Envelope shape.** The sealed_payload the intake writes carries a `command_set`
+key holding the verbatim list of `{command, rationale}` items, and `commands`
+listing every command string in the set:
 
-**Current state:** only the CHECK side is wired. `bash_validator._validate_single_command()`
-calls `match_command_set_grant()` and consumes a matched item, but **no
-production path calls `approval_grants.create_command_set_grant()`** -- it exists only in the
-module and its tests. The activation paths only call
-`approval_grants.activate_db_pending_by_prefix()`, which creates a single-use
-`SCOPE_SEMANTIC_SIGNATURE` grant.
+```json
+{
+  "operation": "MUTATIVE command intercepted: push",
+  "exact_content": "git add -A",
+  "commands": ["git add -A", "git commit -m 'v1.2.0'", "git push origin main"],
+  "command_set": [
+    {"command": "git add -A",             "rationale": "stage release files"},
+    {"command": "git commit -m 'v1.2.0'", "rationale": "record the release commit"},
+    {"command": "git push origin main",   "rationale": "publish to the remote"}
+  ]
+}
+```
 
-**Consequence:** a `batch_scope` field in `approval_request`, or the word "batch"
-in a label, does nothing. Each blocked command produces its own single-use
-semantic grant and its own approval. For a sweep of N commands, expect N
-approvals until the COMMAND_SET create path is wired.
+**Activation -- one consent, one grant.** When the user approves, the
+ElicitationResult hook (`approval_grants.activate_db_pending_by_prefix()`)
+detects the `command_set` and branches to `approval_grants.create_command_set_grant()`,
+which inserts a single `COMMAND_SET` grant row into `approval_grants`
+(status `PENDING`, `command_set_json` holding the whole set). The grant TTL is
+**60 minutes** (`DEFAULT_COMMAND_SET_TTL_MINUTES`), aligned to the singular
+active-grant TTL so the batch does not expire mid-consume across sessions.
+
+**Consume -- item by item, replay-protected.** On each retry,
+`bash_validator._validate_single_command()` calls `match_command_set_grant()`,
+which finds the matching command's index byte-for-byte and returns it; the
+validator then calls `mark_command_set_item_consumed()`, appending that index to
+`consumed_indexes_json`. A consumed index never matches again (replay
+protection), and when every index is consumed the grant flips to `CONSUMED`.
+Wrapping an approved command -- adding `cd`, a redirect, a pipe, or a flag --
+produces a different string and matches nothing in the set; it requires fresh
+approval.
+
+**Consequence:** for a set of N related T3 commands, emit the `command_set`
+envelope and the user approves once. Each command runs on its own retry,
+single-use within the 60-minute window.
 
 ## Status to emit -- with vs without approval_id
 
 Always `plan_status: "APPROVAL_REQUEST"`. The presence of `approval_id` tells the
 orchestrator which path:
 
-- **With `approval_id`** -- the hook blocked; orchestrator validates the
-  fingerprint and activates the grant on user approval.
-- **Without `approval_id`** -- plan-first (you are presenting a T3 plan before
-  attempting); the orchestrator gates on user consent before any execution.
+- **With `approval_id`** -- the hook blocked a single command; orchestrator
+  validates the fingerprint and activates the single-use semantic grant on user
+  approval.
+- **Without `approval_id`, with a `command_set` of >= 2 items** -- plan-first
+  batch. The SubagentStop intake processor mints ONE pending `COMMAND_SET` and
+  the orchestrator presents that single approval (N commands, one nonce) before
+  any execution. See "Batch / COMMAND_SET -- wired" above.
+- **Without `approval_id` and without a multi-item `command_set`** -- plan-first
+  single (you are presenting one T3 plan before attempting); the orchestrator
+  gates on user consent before any execution.
 
 ## Examples
 

package/tools/context/README.md

@@ -77,7 +77,7 @@ Agent contracts live in `~/.gaia/gaia.db` (`project_context_contracts` + `agent_
 **cloud-troubleshooter:**
 - project_identity, stack, git, environment, infrastructure, orchestration
 - cluster_details, infrastructure_topology, terraform_infrastructure
-- gitops_configuration, application_services, monitoring_observability, architecture_overview
+- gitops_configuration, application_services, architecture_overview
 
 The same contracts are exposed under `write_permissions`:
 - `readable_sections`

package/tools/gaia_simulator/extractor.py

@@ -221,7 +221,6 @@ class LogExtractor:
                 # Exit 2 BLOCK (block_response is None):
                 #   - "Command blocked by security policy ..." -- permanent deny list
                 #   - "Commit message validation failed ..." -- validation error
-                #   - "GitOps policy violation ..." -- GitOps validation
                 #   - "Empty command not allowed"
                 if (
                     reason.startswith("Dangerous")