Files

T

claude@clouddev1 88204f25c5 docs(tt4,nfr): record Tier-4 + NFR verification (ADR-0008 A1, ADR-0057)

Document the regression-hardening work from this session:

- ADR-0008 Amendment 1 — Tier 4 realized: the portable-pty + vt100 harness,
  expectrl dropped, serial/fail-fast design, the four flows, sidebar-region
  reads, command pacing (issue #39), CI default-target (advances TT5).
- ADR-0057 (new) — NFR verification strategy: contrast + ΔE2000 gates
  (NFR-5/7), startup/RSS measured (NFR-1/3: release ~29 ms / ~10 MB),
  NFR-2 by architecture, NFR-4/6 reviewer note. Records the two shipped
  light-theme contrast defects this work caught and fixed.
- requirements.md: TT4 [~]->[x], TT5 [/] (only a Windows exec runner left),
  NFR-1/2/3/5/7 ->[x], NFR-4/6 ->[/], each with evidence.
- CHANGELOG.md (new): Keep a Changelog + SemVer, [Unreleased] + [0.2.0].
- README ADR index updated; handoff-76; the working plan.

Docs-only (CI gate skips via paths-ignore).

2026-06-22 13:15:45 +00:00

5.2 KiB

Raw Blame History

Session handoff — 2026-06-22 (76)

Continues from handoff-75 (D3 package managers). This session took up the regression-hardening trio identified as "what's next" now that public binaries ship: TT4 (Tier-4 PTY tests), NFR verification, and a CHANGELOG — plus a real palette accessibility fix the work uncovered.

§1. State

Branch main. Three commits this session:

65eab71 fix(theme) — WCAG-AA palette fix + contrast/ΔE2000 gates + scripts/palette-preview.py.
fd63de3 test(tt4) — Tier-4 PTY end-to-end suite (tests/e2e_pty.rs).
(pending) a docs commit — ADR-0008 Amendment 1, ADR-0057, README index, requirements.md, CHANGELOG.md, this handoff, and the plan doc docs/plans/20260622-tt4-nfr-changelog.md. (Propose + confirm before committing; not yet committed at time of writing.)

Test baseline: 2519 passed / 0 failed / 1 ignored (was 2509; +4 theme gates, +6 e2e_pty). clippy --all-targets -D warnings + fmt --check clean. Full suite verified green 3× under parallel load.

§2. What shipped

Palette accessibility (ADR-0057, commit 65eab71). Computing real WCAG ratios while writing the gate found two shipped defects in v0.2.0's light theme — tok_string (4.42:1) and tok_flag (3.15:1), below the 4.5:1 the scheme promises — and two dark token pairs that were perceptually close despite distinct hex. All four fixed (only theme.rs colours changed, 4 values). New gated tests in src/theme.rs:

all_text_colours_meet_wcag_aa_contrast (≥4.5:1, both themes),
advanced_mode_border_meets_ui_contrast (≥3:1; plain border exempt),
delta_e_2000_matches_reference_vectors (CIEDE2000 validated vs Sharma data),
syntax_token_colours_are_perceptually_distinct (ΔE2000 ≥15). Dev tool scripts/palette-preview.py renders the live palette (truecolor swatch + contrast + ΔE2000), supports theme:key=HEX overrides for previewing changes.

TT4 — Tier-4 PTY tests (ADR-0008 Amendment 1, commit fd63de3). tests/e2e_pty.rs drives the real built binary in a pseudo-terminal: portable-pty 0.9 + vt100 0.16 (expectrl dropped — conflicting PTY layer; replaced by a hand-rolled wait_for on the vt100 grid). 100×30, temp --data-dir, serial, tight 3 s fail-fast waits. The four ADR-0008 flows all green. Runs by default in cargo test → the Linux gate now exercises Tier 4 (advances TT5). PTY-in-container validated (openpty+spawn under Docker).

Gotchas baked into the harness: read table presence from the Tables sidebar region (the Output panel echoes commands, polluting whole-screen matches); pace commands to completion (a command sent mid-rebuild misparses — issue #39); simple-mode insert needs the values keyword and a single-value insert needs add column (a 2nd col in with pk … makes a compound PK).

NFR verification (ADR-0057). All seven NFRs formally verified:

NFR-1/3 measured via the PTY harness — release figures ~29 ms startup / ~10 MB idle RSS (well under 500 ms / 50 MB). Harness tests gate generous debug-binary bounds for gross-regression detection (tight gates declined as flaky — user decision).
NFR-5/7 gated (the contrast/ΔE2000 tests above).
NFR-2 by architecture (worker thread ADR-0010 + separate input task).
NFR-4/6 reviewer note ([/]).

CHANGELOG.md — Keep a Changelog + SemVer; [Unreleased] + [0.2.0] (0.1.0 = pre-history). v0.2.0 tag = bd5be5e; the palette fix + package managers + TT4 are post-tag → Unreleased.

§3. Decisions taken with the user

Palette: fix the two light contrast bugs and the two dark near-duplicates (4 hex changes, approved after a rendered preview).
Borders <3:1 → accept + document (decorative chrome).
Work directly on main; ADR-0057 numbered now (not draft).
NFR perf: measured + generously bounded, not tightly CI-gated.
CHANGELOG depth: 0.2.0 + Unreleased only.
Schema-cache finding → file a Gitea issue, defer the fix (see §4).

§4. Open / follow-ups

Issue #39 (filed this session): simple-mode Form-B insert (insert into T values (…)) submitted faster than the post-DDL schema-cache refresh validates against stale schema and is misparsed as SQL. No interactive-user impact (cast driver + tests pace); deferred fix. Repro + diagnosis in the issue.
TT5 remaining: only a Windows execution runner now (macOS + Tier-4 gaps closed this session). First real CI run is the final confirmation that the PTY tests pass in the Gitea container (validated locally; very low risk).
Untouched larger items from the "what's next" survey: hint/help issues #36/#37/#38; the big features (V4 session journal, TU1 tutorial). The CHANGELOG can later feed --release-notes-url into the CI winget job (handoff-75 §6).

§5. Process pins

Commits user-confirmed, no AI attribution, append-only, push is the user's step.
/runda + DA pass was run on both the plan and the implementation (it caught the two light-theme contrast bugs and the #39 schema-cache behaviour — both before finalizing).
Consider a cargo sweep at this milestone (release build added ~ a GB).

5.2 KiB Raw Blame History Unescape Escape