72 lines
2.5 KiB
Markdown
72 lines
2.5 KiB
Markdown
---
|
|
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 |