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).
This commit is contained in:
claude@clouddev1
@@ -0,0 +1,98 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user