The flag is `--include-resolved` but the concept is "inactive status"

Class: misleading · Severity: material Flow: arch-f220a644d654 · Step: asking for closed documents Question: None · Frequency: any query for closed documents of a type without a resolved status

Finding¶

The flag is --include-resolved but the concept is "inactive status", which is rejected/superseded for decisions, deprecated for architecture, retired for policy, and so on. resolved is a status of only two of the fifteen shipped types.

What happens today¶

The wire field is named include_inactive (dispatch.py:116) and the CLI renames it to --include-resolved on the way out (app.py:269, 288, 303).

Impact¶

A user querying decisions has no reason to guess that a flag named --include-resolved controls whether superseded decisions appear.

Proposed default¶

Rename to --include-inactive (keeping --include-resolved as a hidden alias), matching the internal name and the schema key.

Resolution¶

FIXED 2026-07-28, as proposed, on all three read commands (query/search/context). --include-inactive is the documented flag; --include-resolved remains accepted but hidden, because it appears in scripts and in agent instruction files installed before this release — breaking it would be a silent behaviour change for them. Using it prints a deprecation notice to stderr, never stdout, so a captured JSON payload is untouched. FOUND WHILE DOING IT — describe_help filtered hidden commands but not hidden options. The asymmetry was invisible while nothing was hidden; the first deprecated alias then disappeared from the Rich panel a human reads and stayed in the JSON help an agent reads. That is precisely backwards: the JSON help is the agent contract, and two flags for one concept there is the confusion this gap is about. Both are now filtered, pinned by test_hidden_options_stay_out_of_the_agent_contract (verified to fail against the old comprehension). The general shape, third time recorded: a rule applied to one of two parallel paths. issue-8c37bf22ba3c was the visibility filter on 3 of 4 read paths; issue-be95d3e242a3 is the stale-write guard on 1 of 5 edit modes and is still open. Worth grepping for the rest.

Actors affected¶

• AI coding agent
• repository maintainer

Evidence¶

• src/docir/entry_points/cli/app.py:269
• src/docir/entry_points/dispatch.py:116
• src/docir/modules/documents/infra/profiles.py

---

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