@jaguilar87/gaia 5.0.2 → 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/agent-contract-handoff/SKILL.md

@@ -43,6 +43,7 @@ The fenced `agent_contract_handoff` block. Parsed by `parse_contract` (regex `_R
 | `consolidation_report` | Conditional | required when INPUT set `consolidation_required` / `cross_check_required` / `surface_routing.multi_surface` (`requires_consolidation_report`); else may be `null` |
 | `approval_request` | Conditional | required when `plan_status` is `APPROVAL_REQUEST`; see sub-field table |
 | `loop_state` | Conditional | agentic-loop turns only; `_check_loop_state_blocking` blocks `COMPLETE` when `iteration < max_iterations AND metric < threshold` |
+| `user_facing_summary` | Optional | a brief prose summary written ONCE for the human reader; `parse_user_facing_summary`. The only human-audience field in the contract -- every other field is machine-audience for the orchestrator. On a single-agent `COMPLETE` (N=1) the orchestrator relays it near-verbatim (adapted to the user's language) instead of re-synthesizing `key_outputs`. Absent, or N>1 (multi-agent), the orchestrator falls back to synthesizing `key_outputs`. Purely additive: never required, never rejected. |
 | `memorialize_suggestions` | Optional | structured memory candidates for the user to triage; `parse_memorialize_suggestions` |
 | `memory_suggestions` | Optional | advisory text-only notes (array of strings); `parse_memory_suggestions` |
 | `update_contracts` | Optional | array of `{contract, payload}` for project-context writes; `parse_update_contracts`; see sub-field table |
@@ -67,6 +68,8 @@ The required keys are EXACTLY 7 (`_EVIDENCE_REQUIRED_FIELDS` in `contract_valida
 
 `verification` is a SEPARATE field, NOT one of the 7. It is required ONLY when `plan_status` is `COMPLETE`: it must be a dict and `verification.result` must equal `"pass"`. Missing -> `VERIFICATION_RESULT_REQUIRED_FOR_COMPLETE`; non-pass -> `VERIFICATION_RESULT_MUST_BE_PASS`. For non-COMPLETE statuses `verification` may be absent.
 
+**Audience boundary.** `key_outputs` and every other `evidence_report` key are written for the **orchestrator** -- distilled findings it reasons over to route the next turn. The optional top-level `user_facing_summary` is the **single** field written for the **human**. Keeping the two distinct is what lets the orchestrator relay a human-shaped summary on N=1 without re-synthesizing machine-shaped evidence, and lets it still synthesize from `key_outputs` when the summary is absent or when multiple agents must be consolidated.
+
 ### consolidation_report
 
 Required keys when present (`_CONSOLIDATION_REQUIRED_FIELDS`):

package/dist/gaia-ops/skills/agent-response/SKILL.md

@@ -16,7 +16,7 @@ The orchestrator loads this to interpret a returned `agent_contract_handoff` and
 
 ```
 parse_contract(agent_output)  ->  read agent_status.plan_status
-  |- COMPLETE         -> summarize key_outputs + surface verification, then close
+  |- COMPLETE         -> relay user_facing_summary if present & N=1, else summarize key_outputs; surface verification, then close
   |- APPROVAL_REQUEST -> split on approval_id (present: present-approval; absent: plan options)
   |- NEEDS_INPUT      -> AskUserQuestion, then SendMessage the answer
   |- BLOCKED          -> present open_gaps; new dispatch or accept the limitation
@@ -29,7 +29,7 @@ Before any branch runs, the contract must parse. A block that fails `parse_contr
 
 | `plan_status` | Action |
 |---|---|
-| `COMPLETE` | Summarize `key_outputs` in 3-5 bullets AND surface `verification.result` / `verification.details` -- that block is the proof the work landed, and relaying it is what lets the user trust the increment rather than take "done" on faith. Mention `cross_layer_impacts` and `open_gaps` when non-empty. |
+| `COMPLETE` | If `user_facing_summary` is present AND this is a single-agent turn (N=1), relay it near-verbatim -- adapt only to the user's language, do not re-synthesize -- because the subagent already wrote the human-shaped summary and re-summarizing its `key_outputs` only spends tokens to restate what it said. If the field is absent, or N>1 (multiple agents being consolidated), summarize `key_outputs` in 3-5 bullets as before. Either way, surface `verification.result` / `verification.details` -- that block is the proof the work landed, and relaying it is what lets the user trust the increment rather than take "done" on faith. Mention `cross_layer_impacts` and `open_gaps` when non-empty. |
 | `APPROVAL_REQUEST` | Split on `approval_request.approval_id`: present -> load `Skill('orchestrator-present-approval')`; absent -> present the plan with options (execute / modify / cancel) and on execute/modify resume the SAME agent via `SendMessage`. It splits because a hook-issued `approval_id` carries a pending T3 grant that needs the structured consent flow, while a plan-first request only needs direction (`agent-approval-protocol`, combo decision 2). |
 | `NEEDS_INPUT` | `AskUserQuestion` with the options in `next_action`, then `SendMessage` the answer back to resume. |
 | `BLOCKED` | Present `open_gaps` to the user. If they give direction, dispatch a NEW agent addressing the blocker; if they accept the limitation, close the task as incomplete and move on. |
@@ -41,6 +41,8 @@ These ride alongside `plan_status` and carry signal the orchestrator loses if it
 
 **`verification`** -- covered in COMPLETE above. It is required only on `COMPLETE` and its `result` must equal `"pass"` (`VERIFICATION_RESULT_MUST_BE_PASS`, `contract_validator.py`); surface `result` and `details` so the user sees the proof, never just the word "done."
 
+**`user_facing_summary`** -- the one human-audience field (every other field is machine-audience for the orchestrator). On a single-agent `COMPLETE` it is what you relay to the user, near-verbatim and language-adapted, *instead of* re-synthesizing `key_outputs`; that is the whole point -- the subagent wrote the summary once, so re-summarizing duplicates work the user never sees value in. It is optional and additive: when absent, fall back to `key_outputs`; when multiple agents are in flight (N>1), ignore it and synthesize across them, because no single agent's summary speaks for the consolidated result.
+
 **`memorialize_suggestions` / `memory_suggestions`** -- present each entry to the user before closing the turn and persist ONLY on consent. The orchestrator is the sole memory writer; subagents are blocked from curated writes by design so each entry enters the substrate as a named choice. For the curation mechanics -- how to triage, slug, and persist -- load `Skill('memory')` (combo decision 1: the HOW lives in `memory`).
 
 **`ownership_assessment`** (in `consolidation_report`, enum `VALID_OWNERSHIP_ASSESSMENTS`) -- a ROUTING INPUT the orchestrator acts on silently, not a user-facing field. `owned_here` means the output is authoritative; `cross_surface_dependency` or `not_my_surface` means another dispatch may be needed to close the gap. Route on it; do not narrate it (combo decision 4).

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

@@ -29,7 +29,7 @@ SessionStart emits a one-shot `hookSpecificOutput.additionalContext` manifest (E
 | Package | Files | Purpose |
 |---------|-------|---------|
 | `core/` | `hook_entry`, `paths`, `plugin_mode`, `plugin_setup`, `state`, `stdin` | Entry dispatch, path resolution, mode detection, shared state |
-| `security/` | `blocked_commands`, `mutative_verbs`, `tiers`, `gitops_validator`, `command_semantics`, `approval_grants`, `approval_scopes`, `approval_cleanup`, `approval_constants`, `approval_messages`, `blocked_message_formatter`, `prompt_validator` | T3 gate, blocked commands, approval nonce lifecycle |
+| `security/` | `blocked_commands`, `mutative_verbs`, `tiers`, `command_semantics`, `approval_grants`, `approval_scopes`, `approval_cleanup`, `approval_constants`, `approval_messages`, `blocked_message_formatter`, `prompt_validator` | T3 gate, blocked commands, approval nonce lifecycle |
 | `audit/` | `logger`, `metrics`, `event_detector`, `workflow_auditor`, `workflow_recorder` | Structured logging, metrics collection, workflow audit trail |
 | `tools/` | `bash_validator`, `cloud_pipe_validator`, `shell_parser`, `task_validator`, `hook_response` | Command validation, pipe detection, shell parsing |
 | `context/` | `context_injector`, `context_writer`, `context_freshness`, `contracts_loader`, `compact_context_builder`, `anchor_tracker` | Project-context injection, freshness checks, contract loading |
@@ -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 |
 
@@ -254,7 +253,7 @@ The hook invoker is `python3 <script>` rather than executing the script directly
 | Category | Directory | What it tests |
 |----------|-----------|---------------|
 | Prompt regression | `tests/layer1_prompt_regression/` | Routing table, skill content rules, agent frontmatter, agent prompts, security tier consistency, skills cross-reference, context contracts |
-| Hooks | `tests/hooks/modules/` | Security modules (mutative_verbs, blocked_commands, tiers, gitops_validator, approval_grants, approval_scopes, command_semantics), tools (bash_validator, shell_parser, cloud_pipe_validator, task_validator), core (paths, state), context (context_writer) |
+| Hooks | `tests/hooks/modules/` | Security modules (mutative_verbs, blocked_commands, tiers, approval_grants, approval_scopes, command_semantics), tools (bash_validator, shell_parser, cloud_pipe_validator, task_validator), core (paths, state), context (context_writer) |
 | System | `tests/system/` | Directory structure, permissions, agent definitions, configuration, schema compatibility |
 | Tools | `tests/tools/` | context_provider, episodic, pending_updates, deep_merge, review_engine, surface_router |
 | Integration | `tests/integration/` | Context enrichment, subagent lifecycle, subagent stop, nonce approval relay |

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.