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

## ⚠️ CRITICAL: when NOT to use terminal-devtools

**`terminal-devtools` is ONLY for programs that speak through a terminal** — CLIs, REPLs, and full-screen TUIs (the tools drive them by spawning them attached to a PTY, like tmux). Do **NOT** call `tdt_*` tools for changes with no terminal-observable behavior.

**How to tell whether the change has a terminal surface:**
- A CLI subcommand / script / binary that produces output and an exit code
- A REPL or interactive prompt the user types into
- A full-screen terminal UI (a TUI rendered on the terminal grid)

If the change is **pure library internals with no runnable entry point**, or a **web-only UI change** (that's the browser cycle) — there is nothing terminal to drive. Do NOT call any `tdt_*` tools.

**Misconfiguration recovery.** If this cycle activated but the project has nothing terminal to drive, the operator enabled the terminal cycle by mistake. The Stop hook will keep blocking with `incomplete_tools` until `maxRetries` is exhausted. Don't attempt to spawn a PTY. Stop and tell the user clearly: the project has no terminal-observable surface; ask them to run `ironbee terminal disable` to unblock the gate.

## Terminal flow

Pick **ONE evidence path** per changed code area:

- **Run-evidence path** (one-shot CLI command — best for non-interactive CLIs: a subcommand, a script):
  - Run the command with `mcp__terminal-devtools__tdt_pty_run` — it spawns, runs, and returns the full output + exit code in one call.
  - Confirm the output AND exit code reflect the change (expected text present, `exitCode: 0` unless a failure is the expected result).
- **Interactive-evidence path** (REPL / TUI / multi-step flows):
  - Spawn the program: `mcp__terminal-devtools__tdt_pty_start` (returns a `paneId`).
  - Drive input: `mcp__terminal-devtools__tdt_interaction_send-keys` (keystrokes, tmux syntax: `Enter` / `C-c` / `Up` / `Tab`) or `mcp__terminal-devtools__tdt_interaction_send-text` (literal text).
  - Synchronize: `mcp__terminal-devtools__tdt_sync_wait-for` to block until the expected output appears — **prefer this over fixed delays**.
  - Read output: `mcp__terminal-devtools__tdt_content_capture` — `mode: stream` for line-oriented programs / REPLs / shells (incremental cursor reads via `since`); `mode: screen` for the rendered grid of a full-screen TUI.
  - Tear down when done: `mcp__terminal-devtools__tdt_pty_stop`.
  - **Auxiliary (NOT evidence — synchronization / process-control helpers only):** `mcp__terminal-devtools__tdt_sync_wait-for-idle` (wait until output goes quiet when there's no clean marker), `mcp__terminal-devtools__tdt_content_get-cursor`, `mcp__terminal-devtools__tdt_pty_resize`, `mcp__terminal-devtools__tdt_pty_signal`, `mcp__terminal-devtools__tdt_pty_list`. These shape / control the run; they don't inspect it, so they don't count toward the gate.

### Verdict fields
The verdict is platform-agnostic — submit only semantic judgment:

```json
{
  "session_id": "<sid>",
  "status": "pass",
  "checks": ["`mycli deploy` exits 0 with expected summary", "no stack trace in output"]
}
```

On fail, include `issues`. On pass after a previous fail, include `fixes`.

Terminal-cycle pass criteria:
- **Run-evidence**: a command ran via `mcp__terminal-devtools__tdt_pty_run` AND its output + exit code confirm the change.
- **Interactive-evidence**: a pane was spawned AND input was driven AND output was captured AND it shows the expected result.

## Multi-cycle (browser + terminal simultaneously)

When you edit both a web frontend file (browser-cycle) and a CLI source file (terminal-cycle) in the same task, both cycles activate. **Single** `verification-start`, **single** `verdict.json`, **single** retry counter cover both. One platform-agnostic verdict regardless of how many cycles ran:

```json
{
  "session_id": "<sid>",
  "status": "pass",
  "checks": ["web dashboard renders", "`mycli sync` exits 0 with expected summary"]
}
```

For a multi-cycle `pass`, ALL active cycles' pass criteria must hold.