Should the corrupt-state findings have a repair path, or only detection?

Gap: issue-476b4e188fab · Also resolves: issue-fd547a293d01 Blocking: yes · Rank: 7 · Asked: 2026-07-26 · Answered: 2026-07-26 Authority: repo maintainer (directed the fix; check --fix proposal adopted)

Question¶

duplicate-id, dangling, malformed and unknown-type all describe corrupt state, and no command can fix any of them. Combined with "agents never edit markdown directly", how is a user meant to recover — and should delete --force strip the edges it breaks, the way tag rm --force already strips tags?

What the system does today¶

check reports; nothing repairs. OBSERVED: after delete issue-0001 --force, adr-0001's file still reads related: [issue-0001], and update adr-0001 --set-title X succeeds and re-persists the broken edge — Tier 0 validates only edges supplied in the current call. Evidence: document_service.py:190-206, validation.py:61-66; contrast tag_service.py:97-103.

Proposed answer¶

(a) delete --force strips the edge from referencing documents in the same transaction — the pattern already exists for tags. (b) Add docir check --fix for the mechanical cases: re-issue one of a duplicated id pair (rewriting inbound edges), drop dangling edges, resync the counter.

Why it matters¶

Every confirmed failure mode in this analysis ends in a state the product detects and cannot exit, and the documented recovery contradicts the product's second thesis.

Answer¶

ANSWERED 2026-07-26 in part, completed 2026-07-28. Both halves are now implemented. (b) docir check --fix repairs duplicate ids and dangling edges. (a) delete --force strips the edge from each referencing document in the same transaction and names them in its output, so the dead edge is no longer created. It does not advance their updated, unlike tag rm --force — a link removed from underneath you is not a human re-verification (issue-9ed4905e0db8 tracks the tag path doing the opposite). The recovery path remains for edges broken outside the CLI, which after this is the only way to break one. See issue-fd547a293d01 resolution.

---

Migrated from the discovery question queue (Q-007); the queue itself now lives in this store.