<!-- 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 `tdt_`). Terminal-cycle verification means spawning the affected program attached to a PTY and confirming its behavior — either running the command one-shot and checking its output and exit code, OR driving an interactive session (REPL / shell / TUI) and capturing the rendered output.

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-observable behavior

`terminal-devtools` drives CLIs, REPLs, shells, and TUIs through a PTY. It does NOT apply to web-only UI changes with no command-line surface. If the change produces no terminal-observable output (stdout / stderr / exit code / rendered TUI), do NOT call `tdt_*` tools — use the browser cycle for web-only projects.

**Misconfiguration recovery.** If you reach this state, the operator enabled the terminal cycle by mistake. The Stop hook will keep blocking with `incomplete_tools` for the terminal cycle. Don't attempt to spawn a PTY. Instead, stop and clearly report to the user: this change has no terminal-observable behavior; 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 the affected command one-shot (`tdt_pty_run`) and confirm its output AND exit code match expectation
  - **Interactive-evidence**: spawn a pane (`tdt_pty_start`) → drive input (`tdt_interaction_send-keys` / `tdt_interaction_send-text`) → synchronize (`tdt_sync_wait-for`) → capture output (`tdt_content_capture`, `mode: stream` for REPLs/shells, `mode: screen` for TUIs) → stop the pane (`tdt_pty_stop`). Auxiliary only (NOT evidence): `tdt_sync_wait-for-idle`, `tdt_content_get-cursor`, `tdt_pty_resize` / `tdt_pty_signal` / `tdt_pty_list`.
- **Within step 6 (submit verdict):** submit one platform-agnostic verdict with `status` + `checks` (+ `issues`/`fixes` as needed). Terminal-cycle pass criteria: (command ran via `tdt_pty_run` with output + exit code confirmed) OR (pane spawned AND input driven AND output captured showing the expected result).

### Additional BANNED for terminal cycle

- Calling `tdt_*` tools without first opening a verification cycle (`ironbee hook verification-start`).
- **Calling `tdt_*` tools when the change has NO terminal-observable behavior.** Use the browser cycle only for web-only projects.
- Claiming `status: pass` for a terminal cycle when no evidence path was exercised.
- Claiming `status: pass` on the run-evidence path without confirming the exit code, or on the interactive-evidence path without capturing output that shows the expected result.