Local review · This projection presents reviewed governance source; it is not runtime or publication evidence.

123 — Commands Must Be Legible to Reasoning

Every Reframe command publishes a reasoning-facing semantic declaration through the MIDI2 instrument boundary. The declaration enables grounded selection and dialogue; the MIDI2 IDL remains the sole operational contract.

Principal illustration — a deterministic governance projection. It explains how command declarations support reasoning and dialogue; it is not a command-catalog response, operation receipt, or live acceptance record.

The decision

Every command Reframe exposes SHALL carry a reasoning-facing semantic declaration. A command name and one-line label are not enough. The declaration must let a companion agent compare the writer's intention with what the command actually does, explain that comparison in dialogue, identify missing information, and predict what evidence would establish completion.

The declaration is a discoverable projection of the existing MIDI2 instrument and operation contract. It does not create an OpenAPI, a second command router, or a prose authority beside the MIDI2 IDL. Operational identity, arguments, lifecycle, and result types remain governed by the IDL and live instrument state.

writer intention
      │
      ▼
Composer mediation
      │
      ▼
reason over live command declarations + live Reframe/FountainStore state
      │
      ├── no grounded fit ──► ask one precise question or report the missing command
      │
      └── grounded fit ─────► invoke one existing typed MIDI2 operation
                                      │
                                      ▼
                           terminal result + evidence address

Why names and terse help fail

A short name helps a human remember a command after learning it. It does not tell a reasoning peer enough to select that command safely. “Sync”, “run”, “publish”, or “materialize” can each hide different authorities, targets, preconditions, mutations, confirmations, and terminal meanings.

When those facts are absent, an agent has only bad options: choose from memory, infer effects from wording, search implementation details, try commands until one advances, or ask the writer to babysit the run. None is grounded reasoning. The defect belongs to the command declaration, not to the writer's phrasing.

The declaration standard

1. Stable semantic identity — command name, owning MIDI2 instrument, operation identity, and contract version.
2. Invocation grammar — exact usage, named inputs, required and optional values, and value meanings.
3. Short description — one sentence supporting rapid catalogue scanning.
4. Long semantic description — the intention satisfied, excluded meanings, and intended human outcome.
5. Preconditions and availability — required live state, current availability, and a typed unavailable reason.
6. Effect and mutation boundary — authoritative State A, possible State B, permitted mutations, and forbidden boundaries.
7. Authorization and cost — confirmation, role, consent, credential, provider, or spend conditions.
8. Lifecycle and turn ownership — admitted, awaiting-confirmation, running, blocked, canceled, failed, and succeeded states, including who acts next.
9. Terminal predicates — the facts required before success may be claimed.
10. Evidence addresses — FountainStore records, result identities, MIDI2 terminal events, and applicable AX projections.

The short description supports discovery. The long description supports semantic comparison. The remaining fields support safe execution and proof. None may promise an effect the owning instrument cannot establish.

One declaration, several projections

• /commands presents readable names, usage, descriptions, availability, and relevant live state;
• MIDI-CI Property Exchange exposes instrument identity, profiles, operation vocabulary, and declaration properties;
• Composer receives the semantically relevant declaration subset for the current intention;
• Copilot presents the explanation, clarification, confirmation, progress, and result; and
• generated reasoning orientation may index declarations but may not override live state.

A button, slash command, natural-language request, scenario actor, and remote peer may differ in presentation, but they cannot teach different effects for the same operation.

The governed reasoning sequence

1. establish peer identities through MIDI-CI before Composer traffic begins;
2. obtain the current command surface once from Reframe;
3. restrict attention to declarations relevant to the writer's outcome;
4. compare intention, inputs, preconditions, effect, authorization, and terminal predicates;
5. explain the selected fit, or ask one precise question when no unique safe fit exists;
6. invoke one existing command through Composer mediation;
7. respect MIDI2 lifecycle and turn signals;
8. follow the terminal event to its evidence addresses; and
9. report only the result those artifacts establish.

Dialogue is part of the operation

Writer: Publish this chapter.

Codex: The route-scoped publication command matches that outcome.
       It will update one declared route, requires the remote Store credential,
       and completes only after remote read-back and public digest verification.
       Shall Reframe proceed?

Reframe: Awaiting writer confirmation.

This is not decorative conversation. The explanation identifies the selected operation, mutation boundary, authorization gate, and completion proof before execution.

OpenAPI is only an analogy

An OpenAPI document can make an HTTP operation inspectable, which makes its names, descriptions, inputs, and outcomes a useful analogy. Reframe does not adopt OpenAPI for its command plane. The applicable pattern is self-describing operations, not an additional protocol.

Validation and drift

A declaration is executable governance. Validation fails when ownership is missing, usage disagrees with inputs, descriptions exceed mutation authority, availability contradicts live state, authorization gates are hidden, success lacks proof, projections disagree, or retired operations remain visible.

Governing rules

1. Every Reframe command publishes a reasoning-facing semantic declaration.
2. The MIDI2 IDL and live instrument state remain operational authority.
3. The declaration covers identity, usage, descriptions, inputs, preconditions, availability, effects, authorization, lifecycle, terminal predicates, and evidence.
4. Companion agents obtain the live command surface before operational selection.
5. Selection is a semantic comparison, never a phrase match or remembered recipe.
6. Composer asks when one safe fit cannot be established.
7. One selected command enters one typed MIDI2 operation path.
8. Turn ownership is signaled through MIDI2 lifecycle.
9. Acknowledgement and completion are distinct.
10. OpenAPI, private code search, transcript matching, and trial-and-error invocation are not command authority.

Current boundary

Reframe already exposes parts of this declaration across several surfaces. This chapter defines the convergence target; it does not claim that the current catalogue has passed a declaration audit.

Governing sentence

A Reframe command must explain itself well enough for a companion agent to reason with the writer before acting, while the MIDI2 instrument contract and terminal evidence remain the authority for what the command can make true.