alkstore/tasks/docs-frontmatter-cleanup.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
docs-frontmatter-cleanup	Docs frontmatter cleanup — the 11 invalid YAML frontmatters	completed		single	trivial	isolated	implementation	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

• 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):

  # 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.