# 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

```bash
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

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

The shape:

```json
{
  "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?"

### 4. Run the fix (with consent)

Per source with issues, the queued command is:

```bash
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:

```bash
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

```bash
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
