v0.37.9.0 fix(frontmatter): canonical-style normalization for tag arrays (wave: #1217 + #1238)

[garrytan]

Summary

Wave PR aligning the auto-fix engine, the inferred-frontmatter serializer, and the agent-facing skill on a single canonical YAML shape for tag arrays. v0.37.5.0 (already on master) fixed the validator so tags: [\"yc\", \"w2025\"] stops getting flagged. This release lines up everything else with that fix.

• ✅ When gbrain emits a tag list (inferred frontmatter, frontmatter validate --fix), it writes tags: ['yc', 'w2025'] in the canonical single-quote form.
• ✅ Apostrophe fallback for "Men's Fashion" — YAML stays valid without ugly '' escaping.
• ✅ Agents learn the canonical form via the new Prevention section in frontmatter-guard/SKILL.md.

Three layers, not four

Original PR #1238 proposed four layers. After interactive plan-eng-review + codex outside-voice review, Layer 3 (put_page auto-normalization) was dropped. Reason: put_page parses YAML into typed fields and hashes them (import-file.ts:241). Single-quoted vs double-quoted arrays are functionally identical in storage. Layer 3 would have done zero observable work AND opened a DoS surface (autoFixFrontmatter scans before the import-file.ts:229 size guard). The fix lives where the writes happen, not on the read path.

What landed

Layer	File	Change
Auto-fix step 3a	src/core/brain-writer.ts:155-220	New pass narrowed to tags: / aliases: keys. Rewrites JSON-style arrays to single-quoted YAML with apostrophe fallback. Shares a nestedQuotesFixed dedup gate with existing step 3 so one file with both rewrites surfaces as one audit entry, not two.
Serializer	src/core/frontmatter-inference.ts:411-416	serializeFrontmatter() emits canonical single-quoted by default. JSON.stringify fallback only when tag contains '.
Agent guidance	skills/frontmatter-guard/SKILL.md:170-217	New "Prevention — Writing Valid Frontmatter" section with correct/incorrect examples and the JSON.stringify trap explanation.
Tests	test/brain-writer.test.ts, test/frontmatter-inference.test.ts, test/markdown-validation.test.ts	7 new step 3a cases (rewrite, apostrophe fallback, empty item, non-allow-list keys untouched, aliases parity, step 3a+3 dedup, idempotency) + 1 serializer apostrophe-fallback case + 1 gray-matter vs validator parity test.

Wave packaging: VERSION 0.37.5.0 → 0.37.9.0, CHANGELOG entry written in the GStack voice (ELI10 lead, precision after), TODOS.md cleanup (removed the v0.37.5.0 P3 follow-up — resolved by this release).

Source PR map

• fix(frontmatter): use single quotes for tags to prevent NESTED_QUOTES errors #1217 (closed, by @garrytan-agents): one-line serializer fix. Absorbed verbatim.
• fix(frontmatter): defense-in-depth against JSON-style arrays in YAML #1238 (closed by this wave, by @garrytan-agents): four-layer defense-in-depth. Layers 1, 4, 5 absorbed; Layer 2 superseded by v0.37.5.0 fix(markdown): YAML-aware NESTED_QUOTES validator (stops flagging valid YAML) #1229's already-merged validator; Layer 3 dropped per codex review.
• v0.37.5.0 fix(markdown): YAML-aware NESTED_QUOTES validator (stops flagging valid YAML) #1229 (merged as v0.37.5.0): validator fix. Already on master.

How this got reviewed

Two-round interactive review under /plan-eng-review + codex outside-voice. Decisions log:

• D1 Static import for autoFixFrontmatter (moot — Layer 3 dropped)
• D2 Comments + CHANGELOG framed as canonical-style normalization, not bug fix (post-validator-fix, both forms are valid YAML)
• D3 Full test coverage in-wave (11 cases total)
• D4 Codex outside-voice review → 11 findings
• D5 Drop Layer 3 (put_page normalization) — zero observable change in storage, DoS surface
• D6 Narrow Layer 1 allow-list to tags: / aliases: only (codex caught the broad regex would rewrite typed-numeric arrays like scores: ["1", "2"])
• D7 Apply five codex housekeeping fixes

Plan file: ~/.claude/plans/system-instruction-you-are-working-velvet-dolphin.md

Test plan

• bun run verify — clean (typecheck + 8 pre-checks)
• bun test test/brain-writer.test.ts test/frontmatter-inference.test.ts test/markdown-validation.test.ts test/markdown.test.ts — 119/119 ✅
• Full bun run test ran — 8133/5. The 5 failures are pre-existing on origin/master (verified by stash + checkout + run), not introduced by this wave: 4× test/search/hybrid-reranker-integration.test.ts (reranker reorder tests) + 1× test/doctor-report-remote.test.ts:68 (health score 50 < 70). Filed as separate concerns.
• Post-merge: confirm gbrain frontmatter validate --fix on a file with tags: ["yc"] rewrites to tags: ['yc'] with a backup under ~/.gbrain/backups/frontmatter/.

To take advantage of v0.37.9.0

gbrain upgrade should do this automatically.

1. Existing files stay valid. Only new writes use the canonical form.
2. To normalize an existing brain's tag style in place:

   gbrain frontmatter validate <path> --fix

3. Verify the outcome:

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

🤖 Generated with Claude Code