@jaguilar87/gaia 5.0.2 → 5.0.5

package/scripts/check_schema_drift.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""Build/pre-publish schema-drift guard.
+
+Fails (non-zero) when gaia/store/schema.sql has changed but the schema version
+was not bumped and no new migration was added for it. This catches at build
+time the drift that `gaia doctor` only flags at runtime as a warning.
+
+How it works
+------------
+A committed fingerprint file (scripts/migrations/schema.checksum) pins the
+sha256 of schema.sql to the EXPECTED_SCHEMA_VERSION it corresponds to:
+
+    version=18
+    sha256=<hex digest of gaia/store/schema.sql>
+
+The guard reads EXPECTED_SCHEMA_VERSION from bin/cli/doctor.py and the live
+sha256 of schema.sql, then:
+
+  1. No fingerprint file yet (first run): record the current
+     (version, sha256) and pass. This is how the baseline for the current
+     floor (v18) is established.
+
+  2. Recorded version == EXPECTED but sha256 differs: schema.sql changed
+     without a version bump. FAIL with a message telling the dev to bump
+     EXPECTED_SCHEMA_VERSION in doctor.py and add a migration file.
+
+  3. Recorded version < EXPECTED (a bump happened): verify the corresponding
+     forward migration file scripts/migrations/v{EXPECTED-1}_to_v{EXPECTED}.sql
+     exists, then re-record the new (version, sha256). FAIL if the migration
+     file is missing.
+
+  4. Recorded version == EXPECTED and sha256 matches: no drift, pass.
+
+  5. Recorded version > EXPECTED: the fingerprint is ahead of the CLI -- this
+     is a misconfiguration (someone lowered EXPECTED). FAIL.
+
+Usage:
+    python3 scripts/check_schema_drift.py            # check (+ record on first run / after bump)
+    python3 scripts/check_schema_drift.py --record   # force re-record for current EXPECTED (rare)
+
+Exit codes:
+    0  no drift (or baseline/bump recorded)
+    1  drift detected, or missing migration after a bump, or misconfiguration
+    2  internal error (file not found, parse failure)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import sys
+from pathlib import Path
+
+_REPO_ROOT = Path(__file__).resolve().parents[1]
+_SCHEMA_SQL = _REPO_ROOT / "gaia" / "store" / "schema.sql"
+_DOCTOR_PY = _REPO_ROOT / "bin" / "cli" / "doctor.py"
+_MIGRATIONS_DIR = _REPO_ROOT / "scripts" / "migrations"
+_CHECKSUM_FILE = _MIGRATIONS_DIR / "schema.checksum"
+
+
+def _fail(msg: str) -> None:
+    print(f"[schema-drift] FAIL: {msg}", file=sys.stderr)
+    sys.exit(1)
+
+
+def _err(msg: str) -> None:
+    print(f"[schema-drift] ERROR: {msg}", file=sys.stderr)
+    sys.exit(2)
+
+
+def _read_expected_version() -> int:
+    if not _DOCTOR_PY.is_file():
+        _err(f"doctor.py not found at {_DOCTOR_PY}")
+    text = _DOCTOR_PY.read_text()
+    m = re.search(r"^EXPECTED_SCHEMA_VERSION\s*=\s*(\d+)\s*$", text, re.MULTILINE)
+    if m is None:
+        _err(f"could not parse EXPECTED_SCHEMA_VERSION from {_DOCTOR_PY}")
+    return int(m.group(1))
+
+
+def _schema_sha256() -> str:
+    if not _SCHEMA_SQL.is_file():
+        _err(f"schema.sql not found at {_SCHEMA_SQL}")
+    return hashlib.sha256(_SCHEMA_SQL.read_bytes()).hexdigest()
+
+
+def _read_checksum_file() -> tuple[int, str] | None:
+    if not _CHECKSUM_FILE.is_file():
+        return None
+    version: int | None = None
+    sha: str | None = None
+    for raw in _CHECKSUM_FILE.read_text().splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" not in line:
+            continue
+        key, _, val = line.partition("=")
+        key, val = key.strip(), val.strip()
+        if key == "version":
+            try:
+                version = int(val)
+            except ValueError:
+                _err(f"malformed version in {_CHECKSUM_FILE}: {val!r}")
+        elif key == "sha256":
+            sha = val
+    if version is None or sha is None:
+        _err(f"{_CHECKSUM_FILE} is missing version= or sha256=")
+    return version, sha
+
+
+def _write_checksum_file(version: int, sha: str) -> None:
+    content = (
+        "# Schema fingerprint for the build/pre-publish drift guard.\n"
+        "# Generated and verified by scripts/check_schema_drift.py.\n"
+        "# Pins the sha256 of gaia/store/schema.sql to the schema version it\n"
+        "# corresponds to (EXPECTED_SCHEMA_VERSION in bin/cli/doctor.py).\n"
+        "# Do NOT edit by hand: bump EXPECTED_SCHEMA_VERSION + add a migration,\n"
+        "# then re-run the guard to refresh this file.\n"
+        f"version={version}\n"
+        f"sha256={sha}\n"
+    )
+    _CHECKSUM_FILE.write_text(content)
+
+
+def _migration_for(version: int) -> Path:
+    return _MIGRATIONS_DIR / f"v{version - 1}_to_v{version}.sql"
+
+
+def main() -> None:
+    force_record = "--record" in sys.argv[1:]
+
+    expected = _read_expected_version()
+    live_sha = _schema_sha256()
+    recorded = _read_checksum_file()
+
+    if force_record:
+        _write_checksum_file(expected, live_sha)
+        print(
+            f"[schema-drift] recorded fingerprint for v{expected} "
+            f"(sha256={live_sha[:12]}...) [--record]"
+        )
+        sys.exit(0)
+
+    # Case 1: first run -- establish the baseline for the current version.
+    if recorded is None:
+        _write_checksum_file(expected, live_sha)
+        print(
+            f"[schema-drift] no fingerprint on record; baseline recorded for "
+            f"v{expected} (sha256={live_sha[:12]}...)"
+        )
+        sys.exit(0)
+
+    rec_version, rec_sha = recorded
+
+    # Case 5: recorded ahead of the CLI -- misconfiguration.
+    if rec_version > expected:
+        _fail(
+            f"recorded schema fingerprint is for v{rec_version} but "
+            f"EXPECTED_SCHEMA_VERSION is v{expected} (lower). The CLI cannot "
+            f"expect a version older than the recorded fingerprint. Restore "
+            f"EXPECTED_SCHEMA_VERSION to >= v{rec_version}."
+        )
+
+    # Case 3: a version bump happened -- require the migration, then re-record.
+    if rec_version < expected:
+        mig = _migration_for(expected)
+        if not mig.is_file():
+            _fail(
+                f"EXPECTED_SCHEMA_VERSION was bumped to v{expected} "
+                f"(fingerprint was for v{rec_version}), but the forward "
+                f"migration {mig.relative_to(_REPO_ROOT)} is missing. Add the "
+                f"migration file in the same commit as the version bump."
+            )
+        _write_checksum_file(expected, live_sha)
+        print(
+            f"[schema-drift] version bump v{rec_version} -> v{expected} "
+            f"detected; migration {mig.name} present; fingerprint re-recorded "
+            f"(sha256={live_sha[:12]}...)"
+        )
+        sys.exit(0)
+
+    # rec_version == expected from here on.
+
+    # Case 4: fingerprint matches -- no drift.
+    if rec_sha == live_sha:
+        print(
+            f"[schema-drift] OK: schema.sql matches the recorded fingerprint "
+            f"for v{expected}"
+        )
+        sys.exit(0)
+
+    # Case 2: schema.sql changed without a version bump -- DRIFT.
+    _fail(
+        f"gaia/store/schema.sql changed but EXPECTED_SCHEMA_VERSION is still "
+        f"v{expected} and no new migration was added.\n"
+        f"           recorded sha256: {rec_sha}\n"
+        f"           current  sha256: {live_sha}\n"
+        f"           To fix: bump EXPECTED_SCHEMA_VERSION in bin/cli/doctor.py "
+        f"to v{expected + 1}, add scripts/migrations/v{expected}_to_v{expected + 1}.sql, "
+        f"then re-run this guard to refresh scripts/migrations/schema.checksum.\n"
+        f"           (If the schema.sql edit is genuinely a no-op change that "
+        f"needs no migration, re-run with --record to re-pin the fingerprint.)"
+    )
+
+
+if __name__ == "__main__":
+    main()

package/scripts/migrations/README.md

@@ -5,16 +5,67 @@ adding any new migration file.
 
 ---
 
-## 1. One feature per migration version
+## 0. The schema floor (baseline = current version)
+
+Gaia is a single-user personal tool. Nobody upgrades a database older than the
+current version, and fresh installs build the schema directly from
+`gaia/store/schema.sql`. The full historical `v1 -> v17` migration chain was
+therefore collapsed into a **schema floor**: the lowest schema version that is
+supported for in-place use.
+
+The floor is **v18**. It is declared in three places that must agree:
+
+| Location | What it holds |
+|----------|---------------|
+| `gaia/store/schema.sql` | Produces the v18 shape directly (fresh installs land here). |
+| `scripts/bootstrap_database.sh` Section 3b (`SCHEMA_FLOOR=18`) | Seeds/stamps the ledger at the floor; rejects DBs below it. |
+| `bin/cli/doctor.py` (`EXPECTED_SCHEMA_VERSION`) | The version the CLI expects; equals the floor until a forward migration is added. |
+
+How bootstrap treats each case:
+
+* **Fresh install** (no `schema_version` rows): `schema.sql` already produced
+  the floor shape, so bootstrap stamps `(version=18, ...)` directly. It does
+  **not** seed v1 and walk the chain.
+* **DB at or above the floor** (the common case, e.g. `~/.gaia/gaia.db`): no
+  migration needed. Section 3c only runs if a forward migration exists.
+* **DB below the floor** (`1 <= version < 18`): **no longer supported** for
+  in-place upgrade. Bootstrap aborts with a clear message asking you to
+  recreate the DB (back up, delete `~/.gaia/gaia.db`, re-run `gaia install`).
+
+There are no `_fresh` / `_merge` variants under the floor model. Those existed
+only because the old baseline was v1 and the whole chain was walked on every
+fresh install. With the floor, a fresh install is already at the expected
+version after `schema.sql`, so the migration loop is skipped entirely.
 
-Each independent feature that introduces new DDL gets its own migration version.
-Do NOT extend a version that has already been stamped. The migration ledger is
-monotonic: once a version is written to `schema_migrations`, its content is
-frozen and `bootstrap_database.sh` will not re-run it.
+---
+
+## 1. Adding a future migration (one file per bump, forward-only)
+
+Going forward the convention is **forward-only, one migration file per
+version bump**. To raise the schema from the current floor (or any later
+version) to `N`:
+
+1. Add the new DDL to `gaia/store/schema.sql` so fresh installs land in the
+   target shape.
+2. Create exactly one `scripts/migrations/v{N-1}_to_v{N}.sql` containing the
+   full DDL delta applied to a DB at version `N-1`.
+3. Bump `EXPECTED_SCHEMA_VERSION` to `N` in `bin/cli/doctor.py` **in the same
+   commit**.
 
-If you have two unrelated features ready at the same time, assign them
-consecutive versions (e.g., v6 and v7). Do not bundle them into v6 to save a
-number -- bundling violates atomicity and makes rollback reasoning impossible.
+`bootstrap_database.sh` Section 3c then applies `v{N-1}_to_v{N}.sql` inside a
+single `BEGIN/COMMIT` transaction for any DB behind `N`, and stamps the ledger
+only on success. A fresh install is already at `N` after `schema.sql`, so it
+never enters the loop -- no `_fresh` variant is required.
+
+`tests/cli/test_schema_version_lockstep.py` enforces that
+`EXPECTED_SCHEMA_VERSION` equals the floor when no forward migrations exist,
+and equals the highest migration target once they do.
+
+Each independent feature that introduces new DDL gets its own migration
+version. Do NOT extend a version that has already been stamped: the ledger is
+monotonic, and `bootstrap_database.sh` will not re-run a frozen version. Two
+unrelated features ready at once get consecutive versions (e.g. v19 and v20),
+never bundled.
 
 ---
 
@@ -24,14 +75,14 @@ Tests that assert the schema version must use a floor check, not a point check:
 
 ```python
 # Correct -- survives future bumps without re-editing this test
-assert schema_version >= 5
+assert schema_version >= 18
 
 # Wrong -- breaks every time a new migration lands
-assert schema_version == 5
+assert schema_version == 18
 ```
 
-A floor assertion preserves test intent (the feature that introduced v5 is
-present) without becoming a maintenance burden as the ledger grows.
+A floor assertion preserves test intent without becoming a maintenance burden
+as the ledger grows.
 
 ---
 
@@ -39,25 +90,24 @@ present) without becoming a maintenance burden as the ledger grows.
 
 | Pattern | When to use |
 |---------|-------------|
-| `vN_to_vN+1.sql` | Applied to an existing DB at version N. Contains the full DDL delta. |
-| `vN_to_vN+1_fresh.sql` | Applied after a clean install where `schema.sql` already contains the target state. Usually carries only indexes and constraints that `schema.sql` cannot safely declare for older DBs. |
+| `vN_to_vN+1.sql` | Applied to an existing DB at version N. Contains the full DDL delta, applied inside a `BEGIN/COMMIT` transaction by bootstrap Section 3c. |
 
-Both files are driven by `bootstrap_database.sh`. The `_fresh` variant runs
-when the bootstrap detects that the target objects already exist (Section 3c
-case logic). It must be idempotent (`CREATE INDEX IF NOT EXISTS`, etc.).
+The historical `_fresh` and `_merge` variants are no longer used: under the
+floor model a fresh install is already at the expected version after
+`schema.sql`, so it never runs a migration script.
 
 ---
 
-## 4. Lessons from Plan B closure
-
-Plan B originally added the `evidence` table DDL into `v4_to_v5.sql` after
-that version had already been stamped and executed on existing installs.
-Bootstrap skipped the modified file because the ledger row for v4->v5 was
-already present, so the new DDL never ran.
+## 4. Why the floor (lesson from the collapsed chain)
 
-The fix was to extract evidence DDL into its own `v5_to_v6.sql` (and a
-matching `v5_to_v6_fresh.sql` for clean installs). This is the canonical
-example of the one-feature-per-version rule in practice.
+The pre-floor design seeded `(version=1)` then walked `v1 -> v2 -> ... -> v18`
+on every fresh install, each step guarded by a per-version "is the live DDL
+already at target?" probe in `bootstrap_database.sh`. That machinery existed
+solely to make a fresh install (which `schema.sql` had already built to the
+latest shape) walk the chain without re-running destructive DDL.
 
-See `v5_to_v6.sql` and `v5_to_v6_fresh.sql` in this directory for the
-resulting migration files.
+Since fresh installs build straight from `schema.sql` and no one runs a DB
+older than the current version, the entire chain plus its guard probes were
+dead weight. Collapsing to a floor removes ~35 migration files and the
+per-version `case` block, leaving a single forward-only loop for genuine future
+bumps.

package/scripts/migrations/schema.checksum

@@ -0,0 +1,8 @@
+# Schema fingerprint for the build/pre-publish drift guard.
+# Generated and verified by scripts/check_schema_drift.py.
+# Pins the sha256 of gaia/store/schema.sql to the schema version it
+# corresponds to (EXPECTED_SCHEMA_VERSION in bin/cli/doctor.py).
+# Do NOT edit by hand: bump EXPECTED_SCHEMA_VERSION + add a migration,
+# then re-run the guard to refresh this file.
+version=18
+sha256=6f728de0625d5011b86eaf536c21785d19cfa08592ecaf086ab46f9b0d0ebda0

package/scripts/release-prepare.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+/**
+ * release-prepare -- atomically bump every version source, rebuild dist/, and
+ * validate, in one command. Invoked by the gaia-release skill's "release" flow
+ * (step b), NOT run by hand: the whole point is that no human has to remember
+ * the five files that must agree or the order they move in.
+ *
+ * The saga this prevents: bumping package.json but forgetting pyproject.toml
+ * (which then ships stale and fails CI's validate-manifests leg AFTER the tag
+ * is pushed -- a 5.0.3 -> 5.0.4 re-release). pre-publish:validate is the gate
+ * that catches drift; this script makes drift impossible to introduce by hand
+ * by writing all sources from a single target version, then running that same
+ * gate locally so a drift fails here, loudly, before any tag exists.
+ *
+ * Steps (atomic -- a failure leaves the working tree for inspection, never
+ * half-published):
+ *   1. Bump ALL version sources to <version>:
+ *        - package.json
+ *        - pyproject.toml         ([project].version)
+ *        - .claude-plugin/plugin.json
+ *        - .claude-plugin/marketplace.json  (every plugin entry)
+ *        - CHANGELOG.md           (top versioned header; inserts a stub if absent)
+ *   2. npm run build:plugins      (regenerates dist/, including the per-plugin
+ *                                  manifests that carry the version)
+ *   3. npm run pre-publish:validate  (the drift gate -- fails loud on any
+ *                                     source that did not move)
+ *
+ * Idempotent: re-running with the same version is a no-op bump (sources already
+ * agree) and re-validates. Usage:
+ *   node scripts/release-prepare.mjs <version>
+ *   npm run release:prepare <version>
+ *
+ * <version> is a bare semver, e.g. 5.0.5 or 5.1.0-rc.1 (no leading "v").
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+
+const __filename = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(__filename), '..');
+
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+function log(msg, level = 'info') {
+  const ts = new Date().toLocaleTimeString();
+  const p = `[${ts}]`;
+  switch (level) {
+    case 'error': console.error(chalk.red(`${p} ✗ ${msg}`)); break;
+    case 'success': console.log(chalk.green(`${p} ✓ ${msg}`)); break;
+    case 'warning': console.warn(chalk.yellow(`${p} ⚠️  ${msg}`)); break;
+    case 'step': console.log(chalk.bold.cyan(`\n${p} ${msg}`)); break;
+    default: console.log(chalk.blue(`${p} ℹ️  ${msg}`));
+  }
+}
+
+function fail(msg) {
+  log(msg, 'error');
+  process.exit(1);
+}
+
+function readText(rel) {
+  return fs.readFileSync(path.join(REPO_ROOT, rel), 'utf-8');
+}
+
+function writeText(rel, content) {
+  fs.writeFileSync(path.join(REPO_ROOT, rel), content);
+}
+
+function exists(rel) {
+  return fs.existsSync(path.join(REPO_ROOT, rel));
+}
+
+// --- version-source bumpers ------------------------------------------------
+// Each returns a short status string describing what it did, or throws.
+
+function bumpJsonVersionField(rel, version) {
+  const data = JSON.parse(readText(rel));
+  const before = data.version;
+  data.version = version;
+  // Preserve npm's 2-space style + trailing newline (matches pre-publish-validate.js).
+  writeText(rel, JSON.stringify(data, null, 2) + '\n');
+  return `${rel}: ${before} -> ${version}`;
+}
+
+function bumpMarketplace(rel, version) {
+  const data = JSON.parse(readText(rel));
+  const plugins = data.plugins || [];
+  if (plugins.length === 0) throw new Error(`${rel}: no plugins[] to bump`);
+  const befores = plugins.map((p) => `${p.name}=${p.version}`);
+  for (const plugin of plugins) plugin.version = version;
+  writeText(rel, JSON.stringify(data, null, 2) + '\n');
+  return `${rel}: [${befores.join(', ')}] -> all ${version}`;
+}
+
+function bumpPyproject(rel, version) {
+  const text = readText(rel);
+  // Bump only the version line inside the [project] table, not [tool.*] tables.
+  const projectMatch = text.match(/(\[project\][\s\S]*?)(?=\n\[|$)/);
+  if (!projectMatch) throw new Error(`${rel}: [project] section not found`);
+  const block = projectMatch[1];
+  const verLine = block.match(/^(\s*version\s*=\s*)["']([^"']+)["']/m);
+  if (!verLine) throw new Error(`${rel}: [project].version not found`);
+  const before = verLine[2];
+  const newBlock = block.replace(
+    /^(\s*version\s*=\s*)["'][^"']+["']/m,
+    `$1"${version}"`,
+  );
+  writeText(rel, text.replace(block, newBlock));
+  return `${rel}: ${before} -> ${version}`;
+}
+
+function bumpChangelog(rel, version) {
+  const text = readText(rel);
+  // Find the first real versioned header (skip "## [Unreleased]").
+  const headerRe = /^##\s*\[([^\]]+)\](.*)$/gm;
+  let m;
+  while ((m = headerRe.exec(text)) !== null) {
+    if (m[1].trim().toLowerCase() === 'unreleased') continue;
+    if (m[1].trim() === version) {
+      return `${rel}: top header already [${version}] (no change)`;
+    }
+    // Insert a new dated stub entry above the current top version, right after
+    // the "## [Unreleased]" line if present, else above the first version header.
+    const today = new Date().toISOString().slice(0, 10);
+    const stub = `## [${version}] - ${today}\n\n`;
+    const insertAt = m.index;
+    const updated = text.slice(0, insertAt) + stub + text.slice(insertAt);
+    writeText(rel, updated);
+    return `${rel}: inserted stub [${version}] above [${m[1].trim()}] ` +
+      `(EDIT the body before release)`;
+  }
+  throw new Error(`${rel}: no versioned header found to anchor the new entry`);
+}
+
+// --- main ------------------------------------------------------------------
+
+function run(cmd) {
+  log(`Running: ${cmd}`, 'info');
+  execSync(cmd, { cwd: REPO_ROOT, stdio: 'inherit' });
+}
+
+function main() {
+  const version = process.argv[2];
+  if (!version) {
+    fail('Usage: node scripts/release-prepare.mjs <version>  (e.g. 5.0.5 or 5.1.0-rc.1)');
+  }
+  if (version.startsWith('v')) {
+    fail(`Pass a bare semver without the leading "v" (got "${version}"). The tag adds the v; the sources do not carry it.`);
+  }
+  if (!SEMVER_RE.test(version)) {
+    fail(`"${version}" is not a valid semver. Expected MAJOR.MINOR.PATCH with optional -prerelease.`);
+  }
+
+  log(`Target version: ${version}`, 'step');
+
+  // Step 1 -- atomic bump of every version source.
+  log('Step 1: Bumping all version sources atomically...', 'step');
+  const results = [];
+  try {
+    results.push(bumpJsonVersionField('package.json', version));
+    results.push(bumpPyproject('pyproject.toml', version));
+    if (exists('.claude-plugin/plugin.json')) {
+      results.push(bumpJsonVersionField('.claude-plugin/plugin.json', version));
+    }
+    if (exists('.claude-plugin/marketplace.json')) {
+      results.push(bumpMarketplace('.claude-plugin/marketplace.json', version));
+    }
+    results.push(bumpChangelog('CHANGELOG.md', version));
+  } catch (err) {
+    fail(`Version bump failed (working tree left for inspection): ${err.message}`);
+  }
+  for (const r of results) log(`  ${r}`, 'success');
+
+  // Step 2 -- rebuild dist/ so the per-plugin manifests carry the new version.
+  log('Step 2: Rebuilding plugins (npm run build:plugins)...', 'step');
+  try {
+    run('npm run build:plugins');
+  } catch {
+    fail('build:plugins failed -- dist/ is not regenerated. Fix the build, then re-run release:prepare.');
+  }
+  log('dist/ regenerated', 'success');
+
+  // Step 3 -- the drift gate. Fails loud if any source did not move.
+  log('Step 3: Validating version sync (npm run pre-publish:validate)...', 'step');
+  try {
+    run('npm run pre-publish:validate');
+  } catch {
+    fail('pre-publish:validate FAILED -- version drift or a manifest problem remains. ' +
+      'This is the gate that protects the release; do NOT tag until it is green.');
+  }
+
+  log(`release:prepare complete -- all sources at ${version}, dist/ rebuilt, validation green.`, 'success');
+  log('Next (driven by the gaia-release "release" flow, not by hand): pre-flight (Python 3.11/3.12 + tests), commit, tag, push, gh release.', 'info');
+}
+
+main();

package/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/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/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/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/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 |