@jaguilar87/gaia 5.0.4 → 5.0.5

package/dist/gaia-ops/hooks/modules/validation/commit_validator.py

@@ -23,11 +23,75 @@ Usage:
 import json
 import os
 import re
-from typing import Dict, List, Any, Optional
+from typing import Dict, List, Optional
 from datetime import datetime
 from dataclasses import dataclass
 
 
+# ---------------------------------------------------------------------------
+# Git commit standards -- inlined constants.
+#
+# These were previously loaded from config/git_standards.json. They are now
+# module-level constants: commit_validator.py is the single runtime consumer
+# of these format/subject/body rules, so the JSON indirection added drift risk
+# without any benefit. Footer detection/stripping is NOT here -- it lives,
+# hardcoded, in bash_validator (footers are bash_validator's responsibility).
+# ---------------------------------------------------------------------------
+
+FORMAT = "conventional_commits"
+
+TYPE_ALLOWED = (
+    "feat",
+    "fix",
+    "refactor",
+    "docs",
+    "test",
+    "chore",
+    "ci",
+    "perf",
+    "style",
+    "build",
+)
+
+SCOPE_REQUIRED = False
+SCOPE_EXAMPLES = ("helmrelease", "terraform", "pg-non-prod", "infrastructure")
+
+SUBJECT_MAX_LENGTH = 72
+SUBJECT_RULES = {
+    "capitalize_first_letter": False,
+    "no_period_at_end": True,
+    "imperative_mood": True,
+    "no_emoji": True,
+}
+
+BODY_MAX_LINE_LENGTH = 72
+BODY_REQUIRED = False
+
+EXAMPLES_VALID = (
+    "feat(helmrelease): add Phase 3.3 services",
+    "fix(pg-non-prod): correct API key environment variable mappings",
+    "refactor: simplify context provider logic",
+    "docs: update README with new workflow",
+    "chore(deps): update terraform to v1.6.0",
+)
+
+EXAMPLES_INVALID = (
+    "Added new feature",
+    "Fixed bugs",
+    "Updates",
+    "feat: add feature\n\n🤖 Generated with Claude Code",
+    "feat: add new feature 🚀",
+    "fix: 🐛 correct bug",
+)
+
+ENFORCEMENT = {
+    "enabled": True,
+    "block_on_failure": True,
+    "log_violations": True,
+    "log_path": ".claude/logs/commit-violations.jsonl",
+}
+
+
 @dataclass
 class ValidationResult:
     """Result of commit message validation."""
@@ -44,43 +108,30 @@ class CommitMessageValidator:
     """
     Validates git commit messages against project standards.
 
-    Standards are defined in .claude/config/git_standards.json
+    Standards are inlined as module-level constants (TYPE_ALLOWED,
+    SUBJECT_MAX_LENGTH, SUBJECT_RULES, etc.). Footer detection is not handled
+    here -- that is bash_validator's responsibility.
     """
 
     def __init__(self, config_path: Optional[str] = None):
         """
-        Initialize validator with configuration.
+        Initialize validator.
 
         Args:
-            config_path: Optional path to git_standards.json
-                        If None, uses default location
+            config_path: Accepted for backward compatibility only. When given,
+                         it anchors base_path (used to resolve the relative
+                         violation log path); the rules themselves come from
+                         the module-level constants, not from any file.
         """
         if config_path is None:
-            # Default path relative to this file
-            # From hooks/modules/validation/ go up to gaia-ops root
+            # base_path -> gaia-ops root, used to resolve the violation log.
             # __file__ -> hooks/modules/validation/commit_validator.py
-            # dirname(dirname(dirname(dirname(__file__)))) -> gaia-ops root
             base_path = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))))
-            config_path = os.path.join(base_path, 'config', 'git_standards.json')
         else:
-            # If config_path provided, derive base_path from it
             base_path = os.path.dirname(os.path.dirname(config_path))
 
         self.base_path = base_path
-        self.config_path = config_path
-        self.config = self._load_config()
-        self.standards = self.config.get('commit_message', {})
-        self.enforcement = self.config.get('enforcement', {})
-
-    def _load_config(self) -> Dict[str, Any]:
-        """Load git standards configuration from JSON file."""
-        if not os.path.exists(self.config_path):
-            raise FileNotFoundError(
-                f"Git standards configuration not found at: {self.config_path}"
-            )
-
-        with open(self.config_path, 'r') as f:
-            return json.load(f)
+        self.enforcement = ENFORCEMENT
 
     def validate(self, message: str) -> ValidationResult:
         """
@@ -95,19 +146,19 @@ class CommitMessageValidator:
         errors = []
         warnings = []
 
-        # 1. Check for forbidden footers (CRITICAL)
-        footer_errors = self._check_forbidden_footers(message)
-        errors.extend(footer_errors)
+        # Note: forbidden-footer detection is intentionally NOT done here.
+        # Footers are bash_validator's responsibility (stripping/detection
+        # is hardcoded there).
 
-        # 2. Check conventional commits format
+        # 1. Check conventional commits format
         format_errors = self._check_conventional_format(message)
         errors.extend(format_errors)
 
-        # 3. Check subject line rules
+        # 2. Check subject line rules
         subject_errors = self._check_subject_rules(message)
         errors.extend(subject_errors)
 
-        # 4. Check body rules (warnings only)
+        # 3. Check body rules (warnings only)
         body_warnings = self._check_body_rules(message)
         warnings.extend(body_warnings)
 
@@ -121,22 +172,6 @@ class CommitMessageValidator:
             warnings=warnings
         )
 
-    def _check_forbidden_footers(self, message: str) -> List[Dict[str, str]]:
-        """Check for forbidden footers in commit message."""
-        errors = []
-        forbidden = self.standards.get('footer_forbidden', [])
-
-        for forbidden_text in forbidden:
-            if forbidden_text.lower() in message.lower():
-                errors.append({
-                    'type': 'FORBIDDEN_FOOTER',
-                    'message': f"Commit message contains forbidden footer: '{forbidden_text}'",
-                    'fix': f"Remove all occurrences of '{forbidden_text}'",
-                    'severity': 'error'
-                })
-
-        return errors
-
     def _check_conventional_format(self, message: str) -> List[Dict[str, str]]:
         """Check if message follows Conventional Commits format."""
         errors = []
@@ -147,16 +182,16 @@ class CommitMessageValidator:
 
         # Pattern: type(scope)?: description
         # Examples: feat: add feature, fix(api): correct bug
-        allowed_types = '|'.join(self.standards.get('type_allowed', []))
+        allowed_types = '|'.join(TYPE_ALLOWED)
         pattern = rf'^({allowed_types})(\(.+?\))?: .+$'
 
         if not re.match(pattern, subject):
             errors.append({
                 'type': 'INVALID_FORMAT',
                 'message': 'Commit message does not follow Conventional Commits format',
-                'fix': f"Use format: type(scope): description\nAllowed types: {', '.join(self.standards.get('type_allowed', []))}",
+                'fix': f"Use format: type(scope): description\nAllowed types: {', '.join(TYPE_ALLOWED)}",
                 'severity': 'error',
-                'examples': self.standards.get('examples_valid', [])
+                'examples': list(EXAMPLES_VALID)
             })
 
         return errors
@@ -175,7 +210,7 @@ class CommitMessageValidator:
             description = match.group(2)
 
             # Check max length
-            max_length = self.standards.get('subject_max_length', 72)
+            max_length = SUBJECT_MAX_LENGTH
             if len(subject) > max_length:
                 errors.append({
                     'type': 'SUBJECT_TOO_LONG',
@@ -185,7 +220,7 @@ class CommitMessageValidator:
                 })
 
             # Check for period at end
-            rules = self.standards.get('subject_rules', {})
+            rules = SUBJECT_RULES
             if rules.get('no_period_at_end', True) and description.endswith('.'):
                 errors.append({
                     'type': 'SUBJECT_ENDS_WITH_PERIOD',
@@ -242,7 +277,7 @@ class CommitMessageValidator:
             })
 
         # Check body line length
-        max_length = self.standards.get('body_max_line_length', 72)
+        max_length = BODY_MAX_LINE_LENGTH
         for i, line in enumerate(lines[2:], start=3):  # Skip subject and blank line
             if len(line) > max_length and not line.startswith('http'):
                 warnings.append({
@@ -285,13 +320,13 @@ class CommitMessageValidator:
     def get_examples(self) -> Dict[str, List[str]]:
         """Get example commit messages (valid and invalid)."""
         return {
-            'valid': self.standards.get('examples_valid', []),
-            'invalid': self.standards.get('examples_invalid', [])
+            'valid': list(EXAMPLES_VALID),
+            'invalid': list(EXAMPLES_INVALID)
         }
 
     def get_allowed_types(self) -> List[str]:
         """Get list of allowed commit types."""
-        return self.standards.get('type_allowed', [])
+        return list(TYPE_ALLOWED)
 
     def format_error_message(self, validation: ValidationResult) -> str:
         """

package/dist/gaia-ops/skills/README.md

@@ -64,7 +64,7 @@ skills/
 ├── gaia-patterns/         # Gaia component patterns: hooks, agents, routing, CLI
 │   └── reference.md
 ├── gaia-planner/          # Feature planning, briefs, task decomposition
-├── gaia-release/          # Gaia release pipeline: live, dry-run, beta, stable
+├── gaia-release/          # Gaia release pipeline: install local, dry-run, release
 ├── gaia-audit/            # Audit one component (agent or skill) against its standard + live implementation
 ├── gaia-verify/           # Verify a Gaia installation across delivery surfaces
 ├── git-conventions/       # Conventional Commits (on-demand workflow skill)

package/dist/gaia-ops/skills/gaia-patterns/SKILL.md

@@ -91,7 +91,7 @@ When you modify any Gaia component (hook, skill, agent definition, routing confi
 - Changed `_is_protected()` paths in `adapters/claude_code.py` → check `security-tiers/SKILL.md` for path documentation
 - Added a new agent definition → check `gaia-patterns/reference.md` for agents table
 - Modified hook enforcement logic → check `security-tiers` and `agent-protocol` references
-- When adding or modifying files in agents/, skills/, hooks/, commands/, config/, bin/, tests/, build/, templates/ or the repo root, load Skill('readme-writing') to update the relevant README.md
+- When adding or modifying files in agents/, skills/, hooks/, commands/, config/, bin/, tests/, build/ or the repo root, load Skill('readme-writing') to update the relevant README.md
 
 **Format:** In `cross_layer_impacts`, list the doc file and the behavior change, e.g.:
 ```

package/dist/gaia-ops/skills/gaia-patterns/reference.md

@@ -130,7 +130,6 @@ The package ships a single `gaia` binary (`bin/gaia.js`) that dispatches to Pyth
 |------|---------|
 | `config/context-contracts.json` | Seeding source for per-agent context contracts (applied to gaia.db on install; runtime SSOT is DB) |
 | `config/surface-routing.json` | Surface routing table (intent to agent mapping) |
-| `config/git_standards.json` | Git commit and branch standards |
 | `config/cloud/aws.json` | AWS service patterns and commands |
 | `config/cloud/gcp.json` | GCP service patterns and commands |
 

package/dist/gaia-ops/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/dist/gaia-ops/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/dist/gaia-ops/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/dist/gaia-ops/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/dist/gaia-ops/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/dist/gaia-ops/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/dist/gaia-ops/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}")
 
 
 # ---------------------------------------------------------------------------