ADR-0154 and ADR-0189 do not parse; Adr::Repository silently skips them from the index #751

New issue

Open

opened 2026-09-26 22:00:57 +00:00 by jared · 1 comment

jared commented

2026-09-26 22:00:57 +00:00

Owner

Problem

Adr::Repository#entries silently skips unparseable ADR files without a warning, which allowed two malformed files to hide from the index and documentation.

Observed

docs/adr/0154-*.md has an unquoted (planned adapter, #518) in affected-components, which breaks YAML flow-scalar parsing.
docs/adr/0189-*.md uses the old bold-header format with no YAML frontmatter block.
Both are missing or wrong in docs/adr/README.md as a result.

Reproduce

n/a: design defect in repository class, discoverable via inspection

Approach

Required work:

Fix docs/adr/0154-*.md — quote the affected-components value
Fix docs/adr/0189-*.md — add YAML frontmatter block
Update Adr::Repository#entries to raise or warn on unparseable files
Add test coverage for the warning or error behavior

Acceptance criteria

Given a malformed ADR file with unquoted YAML flow-scalar, when the repository loads, then it raises or warns with a clear message.
Given a file using the old bold-header format with no YAML frontmatter, when the repository loads, then it raises or warns with a clear message.
Given both files are repaired to standard frontmatter, when the repository loads, then both appear correctly in the index.

Owner sketch

class Adr::Repository
  def entries
  end
end

Origin

Trigger: observed 2026-09-26 while superseding 63 ADRs
Improvised: none
Chain: silent skip in Repository#entries ← design flaw (no validation error handling)
Root candidate: this ticket (root cause)
Where: Adr::Repository#entries (plugins/os-adr/lib/adr/)

## Problem `Adr::Repository#entries` silently skips unparseable ADR files without a warning, which allowed two malformed files to hide from the index and documentation. ## Observed - `docs/adr/0154-*.md` has an unquoted `(planned adapter, #518)` in `affected-components`, which breaks YAML flow-scalar parsing. - `docs/adr/0189-*.md` uses the old bold-header format with no YAML frontmatter block. - Both are missing or wrong in `docs/adr/README.md` as a result. ## Reproduce n/a: design defect in repository class, discoverable via inspection ## Approach Required work: 1. Fix `docs/adr/0154-*.md` — quote the `affected-components` value 2. Fix `docs/adr/0189-*.md` — add YAML frontmatter block 3. Update `Adr::Repository#entries` to raise or warn on unparseable files 4. Add test coverage for the warning or error behavior ## Acceptance criteria 1. Given a malformed ADR file with unquoted YAML flow-scalar, when the repository loads, then it raises or warns with a clear message. 2. Given a file using the old bold-header format with no YAML frontmatter, when the repository loads, then it raises or warns with a clear message. 3. Given both files are repaired to standard frontmatter, when the repository loads, then both appear correctly in the index. ## Owner sketch ```ruby class Adr::Repository def entries end end ``` ## Origin - Trigger: observed 2026-09-26 while superseding 63 ADRs - Improvised: none - Chain: silent skip in Repository#entries ← design flaw (no validation error handling) - Root candidate: this ticket (root cause) - Where: `Adr::Repository#entries` (plugins/os-adr/lib/adr/)

jared added the

plugin/os-adr

filed-by/user

labels

2026-09-26 22:00:57 +00:00

jared added the

category/umbrella

label

2026-10-10 13:32:00 +00:00

jared commented

2026-10-18 18:58:44 +00:00

Author

Owner

Resolution

Done: Occurrence: #1013 "Fail loudly when an ADR file does not parse in os-adr Repository#entries" (same defect).

Evidence: #1013 adds that adr-find also drops unparseable ADRs silently (seen 2026-10-15 with 0154 and 0189), plus a runnable reproduction; commit 271431e9 fixed only 'adr-new challenge'.

Follow-ups: none

## Resolution **Done:** Occurrence: #1013 "Fail loudly when an ADR file does not parse in os-adr Repository#entries" (same defect). **Evidence:** #1013 adds that adr-find also drops unparseable ADRs silently (seen 2026-10-15 with 0154 and 0189), plus a runnable reproduction; commit 271431e9 fixed only 'adr-new challenge'. **Follow-ups:** none

jared referenced this issue

2026-10-18 18:59:26 +00:00

Fail loudly when an ADR file does not parse in os-adr Repository#entries #1013