design: CLI is the brain — the FSM computes and prescribes the exact next command; the model only executes; decisions go to the human

[ccisnedev]

North star

Inquiry's value is making a simple, accessible model (e.g. qwen3-coder:30b, affordable to buy/run) reliable — a capable model does not need the harness. So the weak model's unreliability is the problem to solve, not something to work around with a bigger model.

Evidence across the OpenCode local-model experiments shows the weak model fails exactly where the harness asks it to decide or reason about FSM state (engagement, picking the right ape transition event, blind-retrying, producing a gate-compliant artifact). Root cause: the firmware asks the model to be the scheduler via prose. A weak model follows prose unreliably.

Principles

1. The CLI is the brain; the model is the hands. The model performs only bounded, punctual reasoning (search, logic, reading code) and executes one prescribed command at a time. It does not run the FSM.
2. The model never decides. LLM decisions are unreliable, and decisions carry consequences and require responsibility. Whenever a real decision arises, the model gathers the information and hands it to the human to decide — it does not choose. (This generalizes the existing completion_authority: user gates: anywhere a choice has consequences, stop and present, don't decide.)
3. The FSM is the key. Because the system is a multi-layer finite-state machine in the CLI (not a sub-agent with skills), the CLI can always emit the exact next command / next state. Lean on that: the model's loop becomes "ask the CLI what's next, do exactly that".
4. The CLI computes events, not the model. The model must never choose next/complete/etc. The CLI determines the correct event from current state + artifacts.
5. Structure over prose. Don't tell the model "do not blind-retry" (it ignores prose) — make the CLI not offer the same event until the artifact changed. Enforce contracts in the FSM, not in firmware text.
6. A human can use the CLI as a step-by-step dev guide. Simplify the CLI surface; the prescribed next command should be followable by a person, not just an agent. The firmware shrinks as the CLI prescribes more.

Concrete plan (incremental, evidence-driven)

• Lever 1 — prescribe the next command. iq fsm state / iq ape state emit a next field: the exact next command to run, computed deterministically (e.g. iq ape prompt --name socrates; or STOP: present <deliverable> to the human, ask "<question>" when a decision is due). The model's firmware reduces to "run iq fsm state; do its next; repeat".
• Lever 2 — remove event choice. A single iq advance (or next carrying the exact event) so the model never names an event.
• Lever 3 — structural anti-blind-retry / verify-before-advance (extends harness: ANALYZE operator advances sub-phases without writing diagnosis.md — the sub-agent's artifact (function output) is never produced #266): the CLI refuses to re-offer a failing transition until its artifact changed.
• Lever 4 — shrink the firmware as the CLI prescribes more; simplify the CLI surface for human usability.

Each lever: implement, then run the qwen conducted experiment and measure the ANALYZE→PLAN crossing rate.

Supersedes the "test with a capable model" idea (that measures the wrong thing). Relates to #260 (orchestrator context), #264 (engagement), #266/#268 (artifact contract).