docs-frontmatter-cleanup: the 11 invalid last_updated frontmatter scalars quoted — double-quote convention applied uniformly (one escaped quote in phase-0.md), annotation prose verbatim; PyYAML sweep over docs/**/*.md + tasks/*.md reports 0 failures, taskgraph validate green (79 tasks); task status -> completed with Notes (recorded sweep command, date-scalar caveat) + Summary

This commit is contained in:
glm-5.3-flash committed 2026-10-10 23:49:08 +00:00
1 parent 9e069ced59
commit 2cb9301a4f
12 files changed
+71 -26

No files matched your search

+52 -7
View File
@@ -1,7 +1,7 @@
---
id: docs-frontmatter-cleanup
name: Docs frontmatter cleanup — the 11 invalid YAML frontmatters
status: pending
status: completed
depends_on: []
scope: single
risk: trivial
@@ -47,12 +47,12 @@ check demands).
## Acceptance Criteria
- [ ] All 11 listed files' frontmatter parses as valid YAML (a
- [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
- [ ] 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
- [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
@@ -65,8 +65,53 @@ check demands).
## Notes
> To be filled by implementation agent
- 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
> To be filled on completion
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.