---
id: docs-frontmatter-cleanup
name: Docs frontmatter cleanup — the 11 invalid YAML frontmatters
status: completed
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

- [x] 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
- [x] One quoting convention applied uniformly across the fixed files
- [x] `taskgraph validate` still green; no `tasks/*.md` content changed
- [x] 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

- Quoting convention chosen: double quotes (`"`-quoted scalars).
  Correction to the description's observation: `"`-escapes were not
  "none observed" — phase-0.md's annotation contains `"pg-side"` in
  double quotes. Double quotes still won on balance: one `\"` escape in
  phase-0.md vs. `''` escaping at every apostrophe (`trim_to`'s,
  `read`'s, `OQ-ST-04`'s across engine-mem.md and phase-0.md) under the
  single-quote convention. Applied uniformly across all 11 files.
- Mechanic confirmed first with a PyYAML probe: a multi-line
  double-quoted scalar folds line breaks to single spaces whether the
  continuation lines sit at column 0 or indented — so the existing
  column-0 wrapping was kept verbatim and no line rewrapping was needed.
- One caveat, not a defect: `tasks/*.md` frontmatters like
  `last_updated: 2026-10-10` parse as YAML *date* scalars, not strings
  — parse-valid, and per the task description tasks are untouched
  beyond the parse check.
- Recorded sweep command (re-runnable; reports zero failures):

  ```python
  # python3 - <<'EOF'
  import yaml, glob, re
  fail = 0
  for f in sorted(glob.glob('docs/**/*.md', recursive=True)) + \
           sorted(glob.glob('tasks/*.md')):
      m = re.match(r'^---\n(.*?)\n---\n', open(f).read(), re.S)
      if not m:
          continue
      try:
          fm = yaml.safe_load(m.group(1))
          assert isinstance(fm, dict)
      except yaml.YAMLError as e:
          fail += 1
          print('FAIL:', f, '|', str(e).splitlines()[0])
  print('sweep failures:', fail)
  # EOF
  ```

  (`---`/`---` lines are extracted before `safe_load`, as frontmatter
  parsers like gray-matter do — feeding the raw file to `safe_load`
  reports a spurious "single document" error because `---` is a
  document-start marker.)

## Summary

Landed: the 11 listed docs' `last_updated` frontmatter values quoted as
double-quoted YAML scalars (annotation prose verbatim; only the three
quote/escape characters added — one `\"` in phase-0.md). Verified with
the recorded PyYAML sweep (0 failures across `docs/**/*.md` +
`tasks/*.md` frontmatter blocks), `status` fields untouched, and
`taskgraph validate` green (79 tasks). No crate code or `tasks/*.md`
content changed.