`reindex` silently skips unparseable files and reports the rebuild as a success

Class: misleading · Severity: material Flow: arch-0a3c2d6d54a6 · Step: reindex over a corpus containing a malformed file Question: None · Frequency: any reindex following a bad hand-edit — the scenario reindex exists for

Finding¶

reindex silently skips files that fail to parse and reports only documents_indexed, so a partial rebuild is indistinguishable from a complete one.

What happens today¶

scan() swallows ValidationError and continues (markdown_store.py:58-62). ReindexResult has no skipped/failed count.

Impact¶

A user rebuilding after a hand-edit that broke frontmatter is told the rebuild succeeded. The document is simply absent from retrieval.

Proposed default¶

Add documents_skipped to ReindexResult and print it; the data is already available via find_malformed().

Resolution¶

FIXED 2026-07-29, as proposed. ReindexResult.documents_skipped counts files that would not parse (from the existing find_malformed()), it is in the JSON, and a non-zero count also prints a stderr warning naming docir check as the next step. The agent guide now tells agents to read the field. THE FINDING UNDERSTATED ONE CASE AND OVERSTATED ANOTHER — both found by running it: (a) with an index already present, a broken file did produce a signal, but a misleading one: documents_removed: 1, which reads as "a file was deleted" rather than "a file on disk is unreadable". Not silent, but pointing the wrong way. (b) on a fresh clone the count is documents_removed: 0, documents_indexed: 1 for two files on disk — genuinely no signal, and this is the worse case because it is exactly where the agent guide tells agents to run reindex. Attribution verified by removing the count: two of the three new tests fail. NOTE for issue-6817ed1851e2: this makes "reindex then check" a workflow that can be trusted for parse failures. It does nothing for a hand-edit that parses but violates Tier 0 — an unregistered tag or an undeclared status — which check still does not detect. The hand-editing contract cannot promise verification until that is closed.

Actors affected¶

• repository maintainer

Evidence¶

• src/docir/platform/filesystem/markdown_store.py:51-62
• src/docir/modules/documents/application/services/maintenance_service.py:26-33

---

Migrated from the discovery gap register (GAP-022); the register itself now lives in this store.