API contract clarity

Define and document the interface contract for requests/commands so the system’s behavior is unambiguous, deterministic, and consistent across call paths and modes.

Apply these rules:

• Gate on explicit intent: only execute the behavior when the caller’s request clearly triggers it (e.g., the request must literally include/qualify the activation directive). Never “helpfully” run the flow uninvited.
• Honor forwarded directives: if your API/workflow passes directives through an internal router/agent, treat a forwarded directive as meeting the same “explicit ask” requirement (don’t accidentally drop the target parameters).
• Be mode-aware: interactive callers may ask clarifying questions when intent is unclear; headless/non-interactive callers must not prompt—return a structured refusal/blocked response including the reason.
• Make overrides and validation deterministic: for non-interactive parameter setting (CLI/HTTP fields), document:
  • which keys are valid,
  • what happens on unknown keys,
  • how enums are treated,
  • and which actions preserve vs overwrite stored config. Warnings are fine, but the persistence/ignore rules must be explicit and consistent.

Example (mode-aware, contract-driven behavior):

{
  "request": "review",
  "mode": "headless",
  "payload": { "diff": "..." }
}

Headless response when intent can’t be inferred:

{
  "status": "blocked",
  "reason": "Intent not explicitly specified for review action"
}

Checklist for every endpoint/command: 1) What exact inputs qualify as an explicit trigger? 2) Does routing/forwarding preserve those qualifiers and parameters? 3) What are the interactive vs headless behaviors on ambiguity? 4) What is the precise contract for validation, persistence, and action-specific side effects? 5) Are focus hints handled as hints only (never changing scope/meaning)?