`delete --force` leaves referencing documents pointing at a document that no longer exists

Class: missing · Severity: material Flow: arch-3e305bc76ff0 · Step: delete --force, and every later write to a referencing document Question: issue-0a4ad65b8a70 · Frequency: every forced delete

Finding¶

delete --force leaves referencing documents pointing at a document that no longer exists, and nothing ever repairs it. Tier 0 validates only edges supplied in the current call, so the broken edge is rewritten to the canonical file on every subsequent update.

What happens today¶

OBSERVED. After docir delete issue-0001 --force, adr-0001's file still reads related: [issue-0001]. docir update adr-0001 --set-title X succeeds and re-persists the broken edge. docir check reports it forever; no command fixes it.

Impact¶

The graph — the feature that distinguishes docir from a folder of files — silently accumulates unresolvable edges, in the canonical files, permanently.

Proposed default¶

Strip the edge from referencing documents as part of the forced delete (the same transaction pattern tag rm --force already uses for tags — the machinery exists and is applied to the lesser case).

Resolution¶

FIXED 2026-07-28, as proposed. DocumentService.delete strips the edge from every referencing document in the same transaction as the delete, and returns their ids; delete now reports "deleted X; unlinked from Y" rather than silently rewriting other people's files. PROBE-6 and PROBE-7 replayed against the real CLI: the referencing file reads related: [], check reports only the (correct) orphan, and a later update has nothing broken to re-persist. DEVIATION from the proposed pattern, deliberate: tag rm --force advances updated on the documents it edits, and this does NOT. Staleness records when a human last vouched for the content, and having a link removed from underneath you is not that — the same reasoning check --fix already applies. Copying the tag path wholesale would have reproduced issue-9ed4905e0db8, which is open against that path for exactly this. CONSEQUENCE for the test suite, worth noting because it changes what the tests mean: five tests used delete --force as a convenient way to manufacture a dangling edge, and that route is now closed. They construct it the way it actually arises instead — remove the target's file as a merge from a branch that deleted it would, then reindex — via a drop_file_of fixture. The old shortcut had quietly made a merge-safety test not simulate a merge. GAP-007 is now prevented rather than merely recoverable; check --fix remains the recovery path for edges broken outside the CLI, which is the only way left to break one.

Actors affected¶

• AI coding agent
• repository maintainer

Evidence¶

• src/docir/modules/documents/application/services/document_service.py:190-206
• src/docir/modules/documents/domain/services/validation.py:61-66
• ref-1509d5dbb4c3 (discovery probe log)

---

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