From bdc9de0d1c237700d65fce3cb8fe109c21458981 Mon Sep 17 00:00:00 2001 From: slhx agent Date: Sun, 21 Jun 2026 19:36:41 +0200 Subject: [PATCH] Document terminal E2E verification gate --- AGENTS.md | 13 +++++++++++++ tools/TERMINAL_E2E.md | 20 ++++++++++++++++++++ 2 files changed, 33 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 0938671..250a914 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,6 +38,19 @@ zig build v1-smoke zig build run -- --help ``` +Canonical terminal/browser E2E check for terminal rendering, raw input, panels, +KEYMAP workflows, LSP/tool workflow reachability, viewport/chrome/color behavior, +or NS10 work: + +```sh +zig build terminal-e2e +``` + +Run `terminal-e2e` after the regular build/test checks for behavior slices that +touch terminal UI, input, panel focus, workflow routing, or screenshot-visible +rendering. It writes ignored artifacts under `.zig-cache/terminal-e2e/`; a clean +source tree must remain clean after the command. + Canonical server install verification for a selected profile: ```sh diff --git a/tools/TERMINAL_E2E.md b/tools/TERMINAL_E2E.md index 6c9f387..2ff87e3 100644 --- a/tools/TERMINAL_E2E.md +++ b/tools/TERMINAL_E2E.md @@ -2,6 +2,15 @@ `zig build terminal-e2e` runs `tools/terminal_e2e.py` against the compiled `mim` binary and writes ignored artifacts under `.zig-cache/terminal-e2e//`. +It is the canonical local gate for terminal rendering/input/panel/workflow slices +(NS10). Run it after `zig build`, `zig build test`, and `zig build v1-smoke` when +a change can affect terminal-visible behavior; pure protocol/headless or docs-only +changes may use cheaper checks unless their claim is terminal-visible. + +The command is expected to finish in seconds on a normal development machine +(current matrix target: under 30s). A timeout or nonzero exit should be treated as +a product regression or harness bug, not a flaky benchmark: inspect the scenario +artifact directory named in the failure output. Matrix input profiles: @@ -36,6 +45,17 @@ Artifact roles: this is not a runtime config surface. - `raw.bin`: exact PTY bytes for low-level debugging. +Failure triage: + +1. Start with the scenario directory reported by the command. +2. Read `manifest.tsv` for hashes, CR/LF status, ANSI roles, key budget, and + artifact list. +3. Read `visible-controls.normalized.txt` for visible `␍`, `␊`, `␛`, and path + normalized raw terminal evidence. +4. Read `transcript.txt`, `widths.tsv`, `keystrokes.tsv`, and any + `saved-files.tsv` for semantic assertions before inspecting screenshots. +5. Use `screenshot.svg`/`terminal.html` to explain what a user would see. + Golden policy: - Investigate before updating any expected artifact or assertion.