v0.22.4 — Frontmatter Guard

What ships

gbrain frontmatter CLI (validate / audit / install-hook)
frontmatter_integrity subcheck under gbrain doctor
New frontmatter-guard skill (skills/frontmatter-guard/SKILL.md)
Pre-commit hook helper for git-backed brain repos
Audit-only migration that scans every registered source, writes ~/.gbrain/migrations/v0.22.4-audit.json, and queues per-source TODO entries to ~/.gbrain/migrations/pending-host-work.jsonl
0 warnings on gbrain check-resolvable (down from 7 on master)

What the agent should do post-upgrade

The orchestrator handles the mechanical side. Your job is to surface the audit to the user and apply fixes with their consent.

1. Run the orchestrator

gbrain apply-migrations --yes

This runs three idempotent phases:

schema (no-op in v0.22.4)
audit — scanBrainSources() over every registered source; writes ~/.gbrain/migrations/v0.22.4-audit.json
emit-todo — appends one entry per source-with-issues to ~/.gbrain/migrations/pending-host-work.jsonl. Each entry contains the exact gbrain frontmatter validate <source-path> --fix command.

The migration never mutates brain pages. Auto-fixes only run when the user explicitly invokes the validate-with-fix command below.

2. Read the audit report

cat ~/.gbrain/migrations/v0.22.4-audit.json

The shape:

{
  "ok": false,
  "total": 17,
  "errors_by_code": { "MISSING_CLOSE": 8, "NESTED_QUOTES": 5, "NULL_BYTES": 4 },
  "per_source": [
    {
      "source_id": "default",
      "source_path": "/Users/me/brain",
      "total": 17,
      "errors_by_code": { "MISSING_CLOSE": 8, "NESTED_QUOTES": 5, "NULL_BYTES": 4 },
      "sample": [
        { "path": "people/jane.md", "codes": ["MISSING_CLOSE"] }
      ]
    }
  ],
  "scanned_at": "2026-04-25T22:30:00.000Z"
}

3. Surface the report to the user

State the per-source counts in plain language. Example:

"v0.22.4 ships frontmatter-guard. I ran an audit and found 17 issues across 1 source (default: 8 MISSING_CLOSE, 5 NESTED_QUOTES, 4 NULL_BYTES). The mechanical errors are auto-fixable; SLUG_MISMATCH cases (if any) need your review. Want me to fix the auto-fixable ones now?"

Per source with issues, the queued command is:

gbrain frontmatter validate <source_path> --fix

--fix writes a .bak backup for every modified file. SLUG_MISMATCH errors are surfaced for manual review (not auto-fixed) — gbrain derives slugs from path, so a mismatched slug usually means the user renamed the file intentionally or the slug field is stale.

5. (Optional) Install the pre-commit hook

For git-backed sources only:

gbrain frontmatter install-hook [--source <id>]

This blocks future malformed-frontmatter commits at the git layer. Bypass with git commit --no-verify. Skip this step for non-git brains.

6. Verify

gbrain doctor --json | jq '.checks[] | select(.name == "frontmatter_integrity")'
gbrain frontmatter audit --json | jq '.total'

Both should report 0 issues after fixes are applied.

7. If anything fails

Open an issue at https://github.com/garrytan/gbrain/issues with:

output of gbrain doctor
contents of ~/.gbrain/migrations/v0.22.4-audit.json
contents of ~/.gbrain/upgrade-errors.jsonl if it exists
which step broke

v0.22.4