---
id: docs-frontmatter-cleanup
name: Docs frontmatter cleanup — the 11 invalid YAML frontmatters
status: pending
depends_on: []
scope: single
risk: trivial
impact: isolated
level: implementation
tags: [wave-8, docs, hygiene]
---

## Description

Eleven docs carry invalid YAML frontmatter: the `last_updated` values
are unquoted multi-line plain scalars containing `: ` (colon+space)
sequences — which YAML plain scalars cannot carry — so frontmatter
parsers fail on them. The affected files (verified this session with a
PyYAML parse sweep over `docs/**/*.md`):

- `docs/architecture/README.md`
- `docs/architecture/core-contract.md`
- `docs/architecture/deployment.md`
- `docs/architecture/engine-mem.md`
- `docs/architecture/engine-postgres.md`
- `docs/architecture/engine-sqlite.md`
- `docs/architecture/overview.md`
- `docs/architecture/queues.md`
- `docs/plans/implementation.md`
- `docs/research/consumer-inventory.md`
- `docs/research/phase-0.md`

The fix is quoting (the annotation prose is content — keep it verbatim;
the family's alksocks docs use the same multi-line annotation style and
parse fine, so the style is fine, only the quoting is missing). Choose
the quoting that survives the values' own characters: several values
contain apostrophes (`trim_to's`) and em-dashes; double quotes with
`"` escaped (none observed) or single quotes with `''` escaping both
work — pick one convention and apply it uniformly. Do not reword or
trim the annotations.

While in the sweep: confirm every other frontmatter-carrying doc under
`docs/` parses (the POC spec/findings docs already do) and confirm the
`tasks/*.md` frontmatters still parse and `taskgraph validate` stays
green (they are valid today — do not touch them beyond what the parse
check demands).

## Acceptance Criteria

- [ ] All 11 listed files' frontmatter parses as valid YAML (a
      scripted parse sweep over `docs/**/*.md` reports zero failures),
      with the `last_updated` annotation prose preserved verbatim
- [ ] One quoting convention applied uniformly across the fixed files
- [ ] `taskgraph validate` still green; no `tasks/*.md` content changed
- [ ] The parse sweep command recorded in Notes so future sessions can
      re-run it

## References

- docs/plans/implementation.md §Wave 8 (this cleanup rides the
  pre-release pass)
- docs/architecture/engine-sqlite.md (an example of the invalid
  pattern, `status: stable` — the fix must not disturb the status
  fields the review gates set)

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion