ADR 0013: YAML-only lifecycle status
Date: 2026-07-13 Status: Accepted
Context
Section titled “Context”The docs tooling originally read lifecycle status from bold Markdown lines such as **Status:** open. That convention was hard to parse reliably: status tokens, notes, punctuation, and placement all varied across repositories. Harnery introduced a shared YAML-frontmatter parser and a bulk docs frontmatter-migrate command so hosts could convert without interrupting lint, sweep, or index behavior.
Once the initial host corpus had been migrated, keeping the fallback would leave two competing metadata contracts indefinitely. It would also let newly created bold-only files pass lint, including archived plans and handoffs the earlier lint scope did not check.
Alternatives considered
Section titled “Alternatives considered”- Keep dual-read support permanently. Avoided a cutover but preserved ambiguous metadata and let legacy files keep entering the corpus.
- Dual-read, but warn on bold-only files. Prolonged the transition and made CI enforcement depend on consumers treating warnings as failures.
- Require YAML after a verified bulk migration. Creates one canonical contract and isolates legacy parsing to the migration command.
Decision
Section titled “Decision”readDocStatusFromText and hasYamlStatus read only a leading YAML status: field. docs lint treats missing YAML status as an error for plans, issues, handoffs, and archived plans. docs sweep and docs index use the same YAML-only reader.
The legacy bold parser was retained temporarily inside
docs frontmatter-migrate. ADR 0083 superseded that transition: the command
and its parser were deleted after the host completed the harnery-doc/v2
cutover.
Consequences
Section titled “Consequences”The initial host migration completed with zero remaining updates or errors from
the one-shot command. The later v2 cutover removed that command. Current
fixtures prove that bold-only and unversioned lifecycle files fail lint; hosts
must write harnery-doc/v2 metadata directly.