# ADR 0273: A runtime CLI field conflict is one command's unavailability

> Source: https://github.com/max-listov/stitchkit/blob/master/docs/decisions/0273-a-runtime-cli-field-conflict-is-one-commands-unavailability.md

---

# ADR 0273 — A runtime CLI field conflict is one command's unavailability

**Invariants:** I2, I3, I8, I13.

## Context

The CLI lifts application globals out of argv and reserves its own behaviour
options. A command input with the same field name cannot receive that value.
The shared surface walk threw on the first such entry, so one independently
changing runtime catalogue operation prevented every managed command, including
unrelated diagnostics, from running. A two-entry public API probe reproduced it;
removing the conflicting entry restored the healthy command.

## Decision

The argv shape checker still throws for command identity and local presentation
policy faults. It classifies reserved/global field conflicts with one exact reason.
The CLI surface walk retains a conflicting `kind: runtime` descriptor in help,
marked unavailable with that reason, and omits it from executable tools. Authored
native and contract-defined commands keep startup failure for the same conflict.
Local policy guards run before classification, so an unavailable field cannot hide
an aliased passthrough or another application configuration fault.

Dispatch resolves presentation before execution: command help remains available,
then an unavailable call returns canonical `CLI_COMMAND_UNAVAILABLE` with the full
reason, status 409, `retryable: false` and default CLI exit 1. The existing error
projection, hint and exit overrides apply. Refusal precedes argument admission,
stdin, context, hooks and handler; dry run cannot turn it into success. The same
refusal covers a known unavailable polling target; unknown targets keep NOT_FOUND.

The in-process invoker receives globals and command input separately, so argv
field conflicts do not make those operations unavailable there. It keeps the same
surface owner and runner without imposing a terminal-only restriction on parsed data.

## Consequences

A runtime catalogue can contain an unavailable entry without taking down unrelated
commands. Help explains the actual conflict instead of hiding the entry or claiming
it is unknown. There is no catch-all recovery for malformed catalogues: duplicate
names, reserved command names and local policy faults remain fatal configuration
errors. A minimal installed-package proof exercises both catalogue orders, help,
refusal and the direct-invoker boundary on Bun and Node.
