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

New issue

Closed

opened 2026-10-15 17:17:26 +00:00 by jared · 1 comment

jared commented

2026-10-15 17:17:26 +00:00

Owner

Problem

Repository#entries in plugins/os-adr/lib/adr/repository.rb skips any ADR whose frontmatter does not parse. So the index build and adr-find act as if the file does not exist, and nobody is told. An unreadable ADR silently drops out of the decision record.

Observed

On 2026-10-15, adr-new challenge 0154 and adr-new challenge 0189 printed:

adr-new: ADR NNNN not found

Both files existed. 0154 had an unquoted #518 in a YAML flow list, which YAML reads as a comment. 0189 used the legacy bold-key format with no frontmatter. Both were also missing from docs/adr/README.md. Commit 271431e9 made challenge name the parse failure. The index build and adr-find still drop the file silently.

Reproduce

printf -- '---\nid: "0999"\naffected-components: [a, #1]\n---\n# 0999 — x\n' > /tmp/r/docs/adr/0999-x.md
ruby plugins/os-adr/bin/adr-find --root /tmp/r x

Origin

Trigger: bulk adr-new challenge run on 2026-10-15 (ADR-0296 cleanup).
Improvised this session: the two files were repaired by hand, then the judge deleted both.
Chain: ADR missing from index and find ← Repository#entries rescues the parse error and skips the file (DESIGN, plugins/os-adr/lib/adr/repository.rb).
Root candidate: this ticket.
Where: plugins/os-adr/lib/adr/repository.rb (Repository#entries)
Session: dc4053c4-4f38-4e1b-b4f9-aa3849695102
Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/dc4053c4-4f38-4e1b-b4f9-aa3849695102.jsonl

VERDICT: CREATE
REASON: Repository#entries rescues ParseError and returns nil, so an unparseable ADR silently drops out of the index and adr-find; seen with 0154 and 0189.

## Problem `Repository#entries` in `plugins/os-adr/lib/adr/repository.rb` skips any ADR whose frontmatter does not parse. So the index build and `adr-find` act as if the file does not exist, and nobody is told. An unreadable ADR silently drops out of the decision record. ## Observed On 2026-10-15, `adr-new challenge 0154` and `adr-new challenge 0189` printed: ``` adr-new: ADR NNNN not found ``` Both files existed. 0154 had an unquoted `#518` in a YAML flow list, which YAML reads as a comment. 0189 used the legacy bold-key format with no frontmatter. Both were also missing from `docs/adr/README.md`. Commit 271431e9 made `challenge` name the parse failure. The index build and `adr-find` still drop the file silently. ## Reproduce ``` printf -- '---\nid: "0999"\naffected-components: [a, #1]\n---\n# 0999 — x\n' > /tmp/r/docs/adr/0999-x.md ruby plugins/os-adr/bin/adr-find --root /tmp/r x ``` ## Origin - Trigger: bulk `adr-new challenge` run on 2026-10-15 (ADR-0296 cleanup). - Improvised this session: the two files were repaired by hand, then the judge deleted both. - Chain: ADR missing from index and find ← `Repository#entries` rescues the parse error and skips the file (DESIGN, `plugins/os-adr/lib/adr/repository.rb`). - Root candidate: this ticket. - Where: `plugins/os-adr/lib/adr/repository.rb` (`Repository#entries`) - Session: dc4053c4-4f38-4e1b-b4f9-aa3849695102 - Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/dc4053c4-4f38-4e1b-b4f9-aa3849695102.jsonl VERDICT: CREATE REASON: Repository#entries rescues ParseError and returns nil, so an unparseable ADR silently drops out of the index and adr-find; seen with 0154 and 0189.

jared added the

plugin/os-adr

filed-by/agent

category/code-change

labels

2026-10-15 17:17:26 +00:00

jared referenced this issue

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

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

jared commented

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

Author