@jaguilar87/gaia 5.0.4 → 5.0.6

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
 
@@ -114,3 +121,4 @@ wording, see `reference.md` -> "GOOD vs BAD Examples", "Option Label Patterns",
 | "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" | `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/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/tools/scan/ui.py

@@ -16,6 +16,22 @@ import sys
 from typing import Any, Dict, List, Optional
 
 
+# ---------------------------------------------------------------------------
+# Glyphs
+#
+# Hoisted to module-level constants so they are never written as escape
+# sequences *inside* an f-string replacement field. A backslash within an
+# f-string expression (e.g. f"{self._green('◇')}") is a SyntaxError on
+# Python 3.11 (our declared minimum); it is only permitted on 3.12+ via PEP
+# 701. Referencing a bare name inside the braces keeps the same rendered
+# output while staying 3.11-compatible.
+# ---------------------------------------------------------------------------
+
+_GLYPH_DIAMOND_OUTLINE = "◇"  # ◇
+_GLYPH_WARNING = "⚠"          # ⚠
+_GLYPH_CORNER_BL = "└"        # └
+
+
 # ---------------------------------------------------------------------------
 # ANSI color helpers
 # ---------------------------------------------------------------------------
@@ -119,7 +135,7 @@ class RailUI:
             name: Section title (e.g. "Stack", "Infrastructure").
             lines: Detail lines to display under the section.
         """
-        self._write(f"{self._green('\u25c7')}  {self._cyan(name)}")
+        self._write(f"{self._green(_GLYPH_DIAMOND_OUTLINE)}  {self._cyan(name)}")
         for line in lines:
             self._write(f"{self._rail()}  {line}")
         self._write(self._rail())
@@ -131,7 +147,7 @@ class RailUI:
             names: List of section names to join with middle-dot.
         """
         joined = self._cyan(" \u00b7 ".join(names))
-        self._write(f"{self._green('\u25c7')}  {joined}")
+        self._write(f"{self._green(_GLYPH_DIAMOND_OUTLINE)}  {joined}")
         self._write(self._rail())
 
     def warning(self, count: int, messages: List[str]) -> None:
@@ -141,7 +157,7 @@ class RailUI:
             count: Total number of warnings.
             messages: Warning messages to display.
         """
-        self._write(f"{self._yellow('\u26a0')}  {self._yellow(f'Warnings ({count})')}")
+        self._write(f"{self._yellow(_GLYPH_WARNING)}  {self._yellow(f'Warnings ({count})')}")
         for msg in messages:
             self._write(f"{self._rail()}  {msg}")
         self._write(self._rail())
@@ -193,7 +209,7 @@ class RailUI:
         Args:
             message: Footer message text.
         """
-        self._write(f"{self._dim('\u2514')}  {message}")
+        self._write(f"{self._dim(_GLYPH_CORNER_BL)}  {message}")
 
 
 # ---------------------------------------------------------------------------

package/tools/scan/verify.py

@@ -45,8 +45,8 @@ class CheckResult:
 def check_symlinks(project_root: Path) -> CheckResult:
     """Verify that all expected symlinks exist in .claude/.
 
-    Checks for: agents, tools, hooks, commands, templates, config,
-    skills, CHANGELOG.md (8 total).
+    Checks for: agents, tools, hooks, commands, config,
+    skills, CHANGELOG.md (7 total).
 
     Args:
         project_root: Project root directory.
@@ -56,7 +56,7 @@ def check_symlinks(project_root: Path) -> CheckResult:
     """
     names = [
         "agents", "tools", "hooks", "commands",
-        "templates", "config", "skills",
+        "config", "skills",
         "CHANGELOG.md",
     ]
     valid = 0

package/tools/validation/README.md

@@ -25,7 +25,7 @@ without requiring explicit imports in agent code.
 - ✅ Subject line rules (max 72 chars, no period at end)
 - ✅ Forbidden footers (no "Generated with" footers)
 
-**Configuration:** `.claude/config/git_standards.json` (SSOT)
+**Configuration:** Standards are inlined as module-level constants in `hooks/modules/validation/commit_validator.py` (`TYPE_ALLOWED`, `SUBJECT_MAX_LENGTH`, `SUBJECT_RULES`, `BODY_MAX_LINE_LENGTH`, `ENFORCEMENT`). Forbidden-footer detection lives in `bash_validator`.
 **Logs:** `.claude/logs/commit-violations.jsonl`
 
 ---
@@ -108,16 +108,11 @@ This validation module works with skills in a **hybrid model**:
 
 ```
 ┌──────────────────────────────────────────────────────────┐
-│  config/git_standards.json (SSOT)                         │
-│  - Conventional commit types                              │
-│  - Forbidden footers                                      │
-│  - Max lengths                                            │
-└──────────────────────────────────────────────────────────┘
-                        │
-                        ▼
-┌──────────────────────────────────────────────────────────┐
 │  hooks/modules/validation/ (Commit Validation)            │
 │  └─ commit_validator.py                                   │
+│     ├─ Standards inlined as module-level constants        │
+│     │   (types, subject/body max lengths, rules)          │
+│     ├─ Forbidden footers handled by bash_validator        │
 │     └─ Used by bash_validator.py only                     │
 └──────────────────────────────────────────────────────────┘
                         │
@@ -178,24 +173,20 @@ Note: commit_validator.py moved to hooks/modules/validation/
 
 ## Configuration
 
-**Git Standards:** `.claude/config/git_standards.json`
+**Git Standards:** Inlined as module-level constants in `hooks/modules/validation/commit_validator.py`.
 
 Example:
-```json
-{
-  "commit_message": {
-    "type_allowed": ["feat", "fix", "refactor", "docs", "test", "chore"],
-    "subject_max_length": 72,
-    "footer_forbidden": ["Generated with Claude Code"]
-  },
-  "enforcement": {
-    "enabled": true,
-    "block_on_failure": true,
-    "log_violations": true
-  }
-}
+```python
+TYPE_ALLOWED = ("feat", "fix", "refactor", "docs", "test", "chore",
+                "ci", "perf", "style", "build")
+SUBJECT_MAX_LENGTH = 72
+SUBJECT_RULES = {"no_period_at_end": True, "no_emoji": True,
+                 "imperative_mood": True, "capitalize_first_letter": False}
+ENFORCEMENT = {"enabled": True, "block_on_failure": True, "log_violations": True}
 ```
 
+Forbidden-footer detection lives, hardcoded, in `bash_validator`.
+
 ---
 
 ## Logs
@@ -232,7 +223,7 @@ Example entry:
 
 ## See Also
 
-- `.claude/config/git_standards.json` - Git standards configuration
+- `hooks/modules/validation/commit_validator.py` - Git standards (inlined constants)
 - `.claude/skills/subagent-request-approval/SKILL.md` - Approval-request workflow patterns
 - `.claude/skills/execution/SKILL.md` - Execution workflow patterns
 - `CLAUDE.md` - Orchestrator protocol with T3 workflow

package/commands/README.md

@@ -1,64 +0,0 @@
-# Commands
-
-Slash commands are direct shortcuts into Gaia's orchestration layer. When you type `/gaia` or `/scan-project`, Claude Code detects the slash prefix, finds the matching `.md` file in this directory, and injects its contents as instructions to the currently active orchestrator. There is no subagent spawn — the orchestrator reads the command file and executes inline.
-
-This makes slash commands different from agent dispatch. An agent dispatch creates a new Claude Code subprocess with its own identity, skills, and tool set. A slash command is a context injection into the orchestrator's current session. Think of it as a macro: the `.md` file says "when the user invokes this command, do the following." The orchestrator follows those instructions directly.
-
-The practical implication is that slash commands are best suited for tasks that the orchestrator can complete by delegating to existing agents — not tasks that require a new agent identity. They are entry points, not agents.
-
-## Cuándo se activa
-
-```
-User types /command-name [args]
-        |
-Claude Code detects / prefix
-        |
-Looks up commands/<command-name>.md
-        |
-Injects the file's contents into the orchestrator's active context
-        |
-Orchestrator reads the command instructions and executes them
-  (may dispatch agents, call tools, or respond directly)
-        |
-Result returned to user in the current session
-```
-
-No subagent is spawned. No new identity is loaded. The orchestrator handles execution within its current session using its existing tool set and the instructions from the command file.
-
-## Qué hay aquí
-
-```
-commands/
-├── gaia.md           # /gaia — invoke the Gaia meta-agent (gaia-system) for system work
-└── scan-project.md   # /scan-project — scan codebase, detect stack, update ~/.gaia/gaia.db
-```
-
-Note: a `/gaia-plan` command is referenced in some older documentation but the file does not exist here. Planning is handled conversationally through the orchestrator and the `gaia-planner` agent — not via a slash command.
-
-## Convenciones
-
-**File format:**
-
-```markdown
----
-name: command-name
-description: One-line description shown in Claude Code autocomplete
----
-
-# Command Name
-
-[Instructions the orchestrator follows when this command is invoked]
-```
-
-**Registration:** Each command file must also be listed in `build/gaia-ops.manifest.json` under the `commands` array. A file that exists here but is not in the manifest will not appear in Claude Code's slash command list.
-
-**Scope:** Commands inject instructions into the orchestrator. If the task requires domain work (Terraform, code changes, cloud ops), the command's instructions should dispatch the appropriate agent — the command itself should not attempt domain execution.
-
-**Arguments:** Slash commands can receive arguments after the command name (e.g., `/gaia-plan Add OAuth2 support`). The command's `.md` file can reference these as context, and the orchestrator receives them as part of the injected content.
-
-## Ver también
-
-- [`build/gaia-ops.manifest.json`](../build/gaia-ops.manifest.json) — command registration
-- [`agents/gaia-system.md`](../agents/gaia-system.md) — the Gaia meta-agent invoked by `/gaia`
-- [`agents/gaia-orchestrator.md`](../agents/gaia-orchestrator.md) — orchestrator that executes command instructions
-- [`skills/gaia-planner/SKILL.md`](../skills/gaia-planner/SKILL.md) — planning workflow (used by gaia-planner agent, not a slash command)

package/commands/gaia.md

@@ -1,37 +0,0 @@
----
-name: gaia
-description: Invoke the Gaia meta-agent for system architecture analysis, agent design, skill creation, and orchestration debugging
-allowed-tools:
-  - Bash(*)
-  - Read
-  - Edit
-  - Write
-  - Glob
-  - Grep
-  - WebSearch
-  - WebFetch
-  - Task
-  - Agent
-  - Skill
----
-
-Invoke the Gaia meta-agent (`gaia-system`) to work on the gaia-ops orchestration
-system itself. This is the entry point for tasks that modify or analyze agents,
-skills, hooks, or system architecture.
-
-## When to use
-
-- Analyze or improve the gaia-ops architecture
-- Create or update agent definitions (`.md` files)
-- Create or update skills (`SKILL.md` files)
-- Write or debug Python hooks and tools
-- Update `CLAUDE.md` or system configuration
-- Research best practices for agent orchestration
-
-## How it works
-
-This command delegates to the `gaia-system` agent, which is the meta-agent
-specialized in the orchestration system. It follows the standard agent protocol
-and returns a `agent_contract_handoff` block with findings and status.
-
-$ARGUMENTS

package/commands/scan-project.md

@@ -1,74 +0,0 @@
----
-name: scan-project
-description: Scan the current project to detect stack, infrastructure, tools, and update the project context in ~/.gaia/gaia.db
-allowed-tools:
-  - Bash(*)
-  - Read
----
-
-Run the gaia modular project scanner to detect the project stack, infrastructure,
-git setup, CLI tools, orchestration, and runtime environment. The scanner writes
-structured, machine-readable context to `~/.gaia/gaia.db` that agents consume.
-
-No `project-context.json` file is generated. The DB is the canonical source of
-truth. Use `gaia context show` to inspect the stored context.
-
-## What this does
-
-The scanner runs 6 independent modules in parallel:
-- **stack** -- languages, frameworks, package managers
-- **git** -- platform, remotes, branching strategy, monorepo detection
-- **infrastructure** -- cloud providers, IaC, CI/CD, containers
-- **orchestration** -- Kubernetes, GitOps (Flux/Argo), Helm charts
-- **tools** -- installed CLI tools (kubectl, terraform, gcloud, etc.)
-- **environment** -- OS info, language runtimes, .env file patterns
-
-It preserves agent-enriched sections (data added by agents via update_contracts)
-and merges new scan data with existing context using section-ownership rules.
-Projects that temporarily disappear are soft-deleted (`status='missing'`) and
-reactivated when they reappear -- data is never purged.
-
-## How to run
-
-```bash
-gaia scan
-```
-
-Optional flags:
-- `--verbose` -- show scanner-by-scanner progress
-- `--scanners stack,git` -- run only specific scanners
-- `--check-staleness` -- skip scan if context is already fresh (<24h old)
-
-$ARGUMENTS
-
-## Expected output
-
-The CLI prints a JSON summary to stdout:
-
-```
-{
-  "status": "success",
-  "scanner_version": "0.1.0",
-  "sections_updated": ["project_identity", "stack", "git", ...],
-  "scanners_run": 6,
-  "warnings_count": 0,
-  "duration_ms": 2500.0
-}
-```
-
-A human-readable summary is also printed to stderr showing scanner count,
-section count, warnings, and elapsed time.
-
-## After scanning
-
-Inspect the stored context:
-
-```bash
-gaia context show
-```
-
-Or query a specific section:
-
-```bash
-gaia context get stack
-```