fix(frontmatter): defense-in-depth against JSON-style arrays in YAML

[garrytan-agents]

Problem

The #1 source of NESTED_QUOTES frontmatter errors is JSON-style arrays in YAML:

# This is what LLMs and ingestion code produce:
tags: ["yc", "w2025"]

# This is what YAML needs:
tags: ['yc', 'w2025']

JSON.stringify() wraps values in double quotes. When code does tags: [${items.map(t => JSON.stringify(t)).join(', ')}], it produces broken YAML. This caused 6,981 validation errors across a 105K-page brain — the single largest contributor to the frontmatter integrity health score.

Fix: Four Layers

1. Auto-fix on frontmatter validate --fix (brain-writer.ts)

New step 3a in autoFixFrontmatter() detects JSON-style arrays and rewrites them to single-quoted YAML. Handles apostrophes by falling back to double quotes.

2. Better detection in validator (markdown.ts)

NESTED_QUOTES detection now has two sub-patterns:

• 5a: JSON-style arrays (clearer message: "use single quotes")
• 5b: Original nested scalar quotes

3. Auto-normalize on put_page (operations.ts)

Every put_page call now runs autoFixFrontmatter() on incoming content before import. Non-blocking — if normalization throws, original content passes through. Agent-written pages with JSON arrays are silently fixed on write.

4. Agent guidance (frontmatter-guard SKILL.md)

New "Prevention" section with correct/incorrect YAML examples, explaining WHY JSON.stringify causes the bug and what to do instead.

Companion PRs

• PR fix(frontmatter): use single quotes for tags to prevent NESTED_QUOTES errors #1217: Serializer fix in frontmatter-inference.ts (the source of the pattern when gbrain itself infers frontmatter)
• Data fix: 11,819 files cleaned up in garrytan/brain

Impact

• Prevents ~7K validation errors per brain
• Silently heals agent-written pages on ingest
• Teaches agents to avoid the pattern in the first place

[garrytan]

Superseded by #1252 (v0.37.6.0 wave).

This PR's four-layer defense-in-depth was reviewed against the already-merged PR #1229 (validator fix, shipped as v0.37.5.0) and absorbed into the wave with two changes:

Kept (with refinements):

• ✅ Layer 1 (auto-fix engine): narrowed allow-list to tags: / aliases: keys only. The original broad regex ([A-Za-z_][\w-]*) would have rewritten typed-numeric arrays like scores: ["1", "2"] into string arrays — caught by codex outside-voice review.
• ✅ Layer 1: shared nestedQuotesFixed dedup gate with existing step 3 so a file with both JSON-array AND nested-scalar rewrites surfaces as ONE NESTED_QUOTES audit entry, not two.
• ✅ Layer 4 (SKILL.md Prevention section): absorbed verbatim with v0.37.5.0-aware framing.

Dropped:

• Layer 2 (markdown.ts NESTED_QUOTES regex sub-pattern): superseded by PR v0.37.5.0 fix(markdown): YAML-aware NESTED_QUOTES validator (stops flagging valid YAML) #1229's YAML-aware js-yaml.safeLoad validator. v0.37.5.0 fix(markdown): YAML-aware NESTED_QUOTES validator (stops flagging valid YAML) #1229's approach is strictly better — it catches single-quoted scalars with literal inner " that the regex would have missed.
• Layer 3 (put_page auto-normalization): dropped. Reason: put_page parses YAML into typed fields and hashes them at import-file.ts:241 — single-quoted and double-quoted arrays produce identical hashes in storage. Layer 3 would have done zero observable work AND opened a DoS surface (autoFixFrontmatter scans the entire payload before the import-file.ts:229 size guard). The "auto-heal on write" framing doesn't match the actual storage shape. Codex outside-voice review caught it.

Thank you @garrytan-agents — Layer 1 + Layer 4 + the original framing made it into v0.37.6.0 via #1252. Attribution preserved via Co-Authored-By: trailer on the wave commit.