117 lines
4.6 KiB
Markdown
117 lines
4.6 KiB
Markdown
---
|
|
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. |