<!-- Terminal verification is ENABLED for this project. The stop hook
     enforces a terminal cycle whenever an edited file matches
     `terminal.verifyPatterns`. -->

## Terminal cycle

Terminal file changes IF the file matches `terminal.verifyPatterns` ALSO require verification through the **terminal-devtools** MCP server (prefix `MCP:tdt_*`). Terminal-cycle verification means spawning the program attached to a PTY (like tmux) and either running a one-shot command to confirm its output and exit code — OR driving a REPL / shell / full-screen TUI with input and capturing the output to confirm the changed code path behaves correctly.

Both cycles can be active simultaneously (e.g. you edit both a React component and a CLI command in the same task). One `verification-start` covers all active cycles; one platform-agnostic verdict covers them all; one retry counter applies globally.

### ⚠️ `terminal-devtools` is ONLY for terminal programs

`terminal-devtools` drives CLIs, REPLs, shells, and full-screen TUIs through a PTY. It does NOT apply to web-only UI, or to changes with no terminal-observable behavior. If the change has no command / REPL / TUI surface, do NOT call `MCP:tdt_*` tools — a web-only change belongs to the browser cycle.

**Misconfiguration recovery.** If this cycle activated but the change has no terminal-observable behavior, the operator enabled the terminal cycle by mistake. The stop hook will keep blocking with `incomplete_tools` for the terminal cycle. Don't fabricate a PTY session. Instead, stop and clearly report to the user: the change has no terminal surface; ask them to run `ironbee terminal disable` to unblock the gate.

### Terminal-cycle additions to the main flow

These attach to the **Required steps** above — they don't replace any step. Numbering follows the main flow:

- **Within step 3 (run flow):** also run the terminal flow — pick ONE evidence path:
  - **Run-evidence**: run a one-shot command (`MCP:tdt_pty_run`) and confirm its output AND exit code are what the change should produce.
  - **Interactive-evidence**: spawn a pane (`MCP:tdt_pty_start`) → drive input (`MCP:tdt_interaction_send-keys` / `MCP:tdt_interaction_send-text`) → synchronize with `MCP:tdt_sync_wait-for` → capture output (`MCP:tdt_content_capture`, `mode: stream` for REPLs/shells with an incremental `since` cursor, `mode: screen` for full-screen TUIs) → stop the pane (`MCP:tdt_pty_stop`). Auxiliary only (NOT evidence): `MCP:tdt_sync_wait-for-idle`, `MCP:tdt_content_get-cursor`, `MCP:tdt_pty_resize` / `MCP:tdt_pty_signal` / `MCP:tdt_pty_list`.
- **Within step 6 (submit verdict):** submit one platform-agnostic verdict with `status` + `checks` (+ `issues`/`fixes` as needed). Terminal-cycle pass criteria: (a one-shot command was run via `tdt_pty_run` and its output/exit code confirm the change) OR (a pane was spawned AND input was driven AND output was captured and shows the expected result).

### Additional BANNED for terminal cycle

- Calling `MCP:tdt_*` tools without first opening a verification cycle (`ironbee hook verification-start`).
- **Calling `MCP:tdt_*` tools when the change has no terminal-observable behavior.** Use the browser cycle for web-only changes.
- Claiming `status: pass` for a terminal cycle when no evidence path was exercised.
- Claiming `status: pass` on the run-evidence path while ignoring a non-zero exit code — the exit code is part of the evidence.