`--override` bypasses the transition rules and leaves no trace

Class: missing · Severity: material Flow: arch-3e305bc76ff0 · Step: --override on an illegal status transition Question: issue-99afeec3a7ce · Frequency: unknown

Finding¶

--override bypasses the transition rules and leaves no trace. The resulting document is indistinguishable from one that transitioned legally.

What happens today¶

Status changes; no marker, no note, no audit field. The status grammar — a Tier 0 hard rule — has an unlogged escape hatch.

Impact¶

Coverage checklist: "Admin: who can override a rule, and is the override audited?" — the override exists, the audit does not. git history records that the status changed but not that a rule was bypassed to change it.

Proposed default¶

Either record the override in frontmatter (e.g. an overrides: note), or drop the flag and require an explicit two-step transition.

Resolution¶

DECIDED 2026-07-29 by the maintainer, from three options: warn loudly, store nothing. --override keeps working and now prints a stderr warning naming the rule it broke and the legal moves from the current status; DocumentView.forced_transition carries the same description over the wire. Nothing is written to the file. WHY NOT AN AUDIT FIELD: docir has no actors or permissions (adr-90e994d931cc), so "who overrode this" has no answer worth storing; git already records the status change; and an overridden: field would be permanent schema surface on every type, plus a decision about whether a later legal transition clears it. What was actually missing was not a record but a signal — the operator was never told a rule had been bypassed at the moment they bypassed it. WHY NOT DROPPING THE FLAG: a document stranded by a schema change may have no legal path out, and the only remaining fix would be hand-editing status — which the issue-6817ed1851e2 contract now explicitly tells people not to do. THE FINDING OVERSTATED THE HOLE. --override still calls validate_status, so it permits an illegal jump between declared statuses, never an undeclared one; it is not a general Tier 0 bypass. Pinned by a test asserting --override --status invented still raises. Also pinned: passing the flag on a transition that was legal anyway does not warn — a guard that cries wolf gets ignored, which is the issue-9cb85759076d/issue-40d1792bc9f9 lesson.

Actors affected¶

• repository maintainer
• AI coding agent

Evidence¶

• src/docir/modules/documents/application/services/document_service.py:324-329

---

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