tmk241/mim
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

NS10 slice: Add terminal control-byte snapshots and golden policy #70

New Issue
Closed
opened 2026-06-21 14:50:34 +00:00 by tmk241 · 1 comment
tmk241 commented 2026-06-21 14:50:34 +00:00
Owner
Copy Link
Copy Source

OBJECTIVE: Make terminal E2E failures debuggable by adding stable snapshot artifacts that expose LF/CR/ESC/control bytes with visible glyphs and a clear golden-update policy.

AUTHORITY: Parent #65; recent terminal regressions; src/terminal_debug.zig; REQUIREMENTS.md req: testing/001-004 and coding/001; AGENTS.md.

AGENT AUTHORITY:

  • Delivery authority: local-commit
  • Tracker authority: this issue may be commented and closed when acceptance passes; comment parent #65 with completion receipt.
  • Handoff state: committed clean, tracker commented/closed.

PARENT: #65 NS10 via explicit parent link and parent checklist.

SCOPE: terminal E2E harness artifacts; src/terminal_debug.zig or adjacent test-support code; small documentation in harness help/output if needed.

BOUNDARIES:

  • Do not add a large screenshot cemetery.
  • Do not make pixel snapshots the only assertion.
  • Do not add runtime user-visible debug modes/config.

REGRESSION CLASS: catches invisible terminal-control regressions where LF, CR, ESC, tabs, or control bytes are normalized away in logs and make browser-terminal failures hard to diagnose.

EVIDENCE ARTIFACTS: visible-control semantic snapshots, normalized transcripts, failing-fixture output, and golden-policy text.

REQUIREMENT IMPACT: protects existing testing and coding requirement authority; update requirement authority only if visible-control snapshots become a durable verification obligation beyond this harness.

ACCEPTANCE:

  • Terminal E2E artifacts include a semantic transcript/snapshot where \r, \n, ESC, tabs, and other control bytes are rendered visibly (for example ␍, ␊, ␛).
  • A deliberately malformed fixture or unit test proves bare LF/newline skew risk is detected and reported with visible glyphs.
  • Snapshot normalization removes volatile paths/timestamps/PIDs while preserving terminal layout-relevant bytes.
  • The repository documents the golden update rule near the harness: what is safe to update, what must be investigated, and how screenshot + semantic artifacts relate.
  • Existing terminal_debug helpers remain product-test support only, not runtime config or end-user UI.

VERIFICATION:

  • zig build terminal-e2e (after #66 lands)
  • zig build test
  • zig build v1-smoke
  • redgate lint /opt/repositories/mim/REQUIREMENTS.md && redgate health /opt/repositories/mim/REQUIREMENTS.md

BLOCKERS: depends on the harness seam from #69.

SLICE_CONTRACT:
objective: Add visible control-byte snapshots and golden policy to terminal E2E artifacts.
authority: #65, src/terminal_debug.zig, REQUIREMENTS.md testing/coding rows.
acceptance: CR/LF/ESC/control bytes are visible in semantic artifacts and bare-LF regressions fail diagnosably.
verification: terminal-e2e plus unit/build gates.
non_goals: user runtime debug mode, huge golden pile, pixel-only testing.
blockers: PTY/browser harness seam must exist.

OBJECTIVE: Make terminal E2E failures debuggable by adding stable snapshot artifacts that expose LF/CR/ESC/control bytes with visible glyphs and a clear golden-update policy. AUTHORITY: Parent #65; recent terminal regressions; src/terminal_debug.zig; REQUIREMENTS.md req: testing/001-004 and coding/001; AGENTS.md. AGENT AUTHORITY: - Delivery authority: local-commit - Tracker authority: this issue may be commented and closed when acceptance passes; comment parent #65 with completion receipt. - Handoff state: committed clean, tracker commented/closed. PARENT: #65 NS10 via explicit parent link and parent checklist. SCOPE: terminal E2E harness artifacts; src/terminal_debug.zig or adjacent test-support code; small documentation in harness help/output if needed. BOUNDARIES: - Do not add a large screenshot cemetery. - Do not make pixel snapshots the only assertion. - Do not add runtime user-visible debug modes/config. REGRESSION CLASS: catches invisible terminal-control regressions where LF, CR, ESC, tabs, or control bytes are normalized away in logs and make browser-terminal failures hard to diagnose. EVIDENCE ARTIFACTS: visible-control semantic snapshots, normalized transcripts, failing-fixture output, and golden-policy text. REQUIREMENT IMPACT: protects existing testing and coding requirement authority; update requirement authority only if visible-control snapshots become a durable verification obligation beyond this harness. ACCEPTANCE: - Terminal E2E artifacts include a semantic transcript/snapshot where `\r`, `\n`, `ESC`, tabs, and other control bytes are rendered visibly (for example `␍`, `␊`, `␛`). - A deliberately malformed fixture or unit test proves bare LF/newline skew risk is detected and reported with visible glyphs. - Snapshot normalization removes volatile paths/timestamps/PIDs while preserving terminal layout-relevant bytes. - The repository documents the golden update rule near the harness: what is safe to update, what must be investigated, and how screenshot + semantic artifacts relate. - Existing terminal_debug helpers remain product-test support only, not runtime config or end-user UI. VERIFICATION: - `zig build terminal-e2e` (after #66 lands) - `zig build test` - `zig build v1-smoke` - `redgate lint /opt/repositories/mim/REQUIREMENTS.md && redgate health /opt/repositories/mim/REQUIREMENTS.md` BLOCKERS: depends on the harness seam from #69. SLICE_CONTRACT: objective: Add visible control-byte snapshots and golden policy to terminal E2E artifacts. authority: #65, src/terminal_debug.zig, REQUIREMENTS.md testing/coding rows. acceptance: CR/LF/ESC/control bytes are visible in semantic artifacts and bare-LF regressions fail diagnosably. verification: terminal-e2e plus unit/build gates. non_goals: user runtime debug mode, huge golden pile, pixel-only testing. blockers: PTY/browser harness seam must exist.
tmk241 added the slice label 2026-06-21 14:50:34 +00:00
tmk241 commented 2026-06-21 15:23:02 +00:00
Author
Owner
Copy Link
Copy Source

Implemented and committed #70 as 86af6d7 Add terminal E2E control snapshots.

What changed:

  • tools/terminal_e2e.py now writes stable semantic artifacts:
    • manifest.tsv with scenario facts, artifact list, raw hash, saved hash, and bare-LF status
    • visible-controls.normalized.txt with normalized volatile temp paths
    • existing raw/transcript/browser-viewable artifacts remain
  • Added UTF-8-aware visible control rendering for CR (␍), LF (␊), ESC (␛), tab (⇥), and other controls.
  • Added harness self-tests for visible-control rendering and bare-LF detection.
  • Harness now fails if PTY raw output contains bare LF, guarding the diagonal-skew class directly.
  • Added tools/TERMINAL_E2E.md documenting artifact roles and golden update policy.

Verification:

  • zig build terminal-e2e
  • zig build test
  • zig build
  • zig build v1-smoke
  • redgate list /opt/repositories/mim/REQUIREMENTS.md
  • redgate lint /opt/repositories/mim/REQUIREMENTS.md && redgate health /opt/repositories/mim/REQUIREMENTS.md

Evidence artifacts from the run are under ignored .zig-cache/terminal-e2e/raw-key-chrome-crlf/.

Implemented and committed #70 as `86af6d7 Add terminal E2E control snapshots`. What changed: - `tools/terminal_e2e.py` now writes stable semantic artifacts: - `manifest.tsv` with scenario facts, artifact list, raw hash, saved hash, and bare-LF status - `visible-controls.normalized.txt` with normalized volatile temp paths - existing raw/transcript/browser-viewable artifacts remain - Added UTF-8-aware visible control rendering for CR (`␍`), LF (`␊`), ESC (`␛`), tab (`⇥`), and other controls. - Added harness self-tests for visible-control rendering and bare-LF detection. - Harness now fails if PTY raw output contains bare LF, guarding the diagonal-skew class directly. - Added `tools/TERMINAL_E2E.md` documenting artifact roles and golden update policy. Verification: - `zig build terminal-e2e` - `zig build test` - `zig build` - `zig build v1-smoke` - `redgate list /opt/repositories/mim/REQUIREMENTS.md` - `redgate lint /opt/repositories/mim/REQUIREMENTS.md && redgate health /opt/repositories/mim/REQUIREMENTS.md` Evidence artifacts from the run are under ignored `.zig-cache/terminal-e2e/raw-key-chrome-crlf/`.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
goal
Issue has a Pi goal contract
 northstar
Parent outcome for v1 product work
 ready-for-agent
Scoped and unblocked for agent implementation
 slice
Executable vertical child issue
No Label slice
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
tmk241
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: tmk241/mim#70
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?