Plan: close the review pane (#43) — terminal acceptance and close

On this page

Closes: #43. Branch: docs/close-review-pane. Status: Done (2026-09-07) — the operator ran the checklist on the live pane presenting this plan and reported "all rows behaved, including the short window".

TL;DR

Everything #43 asked for is in the package: one ui.custom component (packages/pi-modes/review-pane.ts) with a scrollable document viewport, the last cold-review line, and the choice list under one handleInput. The plan page docs/modules/ROOT/pages/plans/review-pane.adoc is behind the repository: its header prose and steps 5 and 9 still say the 0.8.2 cut is pending, and tag v0.8.2 with the == 0.8.2 - 2026-09-03 entry in CHANGELOG.adoc says it landed. Its step 6 — acceptance at the terminal — has waited since 2026-09-03 for scrolling, the key split and the short-window case to be observed live. This plan is that observation, run on the pane itself: this draft is longer than a screen on purpose, so the pane presenting it is the pane under test. When the operator has seen each row of the checklist below, the close is three small edits and one comment.

Design

What is observed, and why each row is there

The pane is a single focused component; every row below is a property the code claims and a unit test pins at a fixed width and height in packages/pi-modes/test/review-pane.test.ts. The terminal run exists because "verified" means observed, and a component’s fit inside a real terminal — with the transcript behind it, ctrl+o’s expansion, and pi’s bottom-up slicing of an over-tall overlay — is not something a fixed-size unit render can show.

Test titles below are from packages/pi-modes/test/review-pane.test.ts; the code seam is routeKey in review-pane.ts throughout.

Key Expected Pinned by

pageDown, ctrl+d

Viewport moves down one page less one row; the choice stays.

"PgDn, j, k, end, home move the offset and the indicator says lines a–b of N"; "scroll bounds are computed at the last rendered width, not a default"

pageUp, ctrl+u

Viewport moves up the same amount.

the same two

j / k

One row down / up.

"PgDn, j, k, end, home move the offset …"

home / end

Top / bottom of the document.

"PgDn, j, k, end, home move the offset …"; "a fitting document shows no indicator and does not scroll"

↑ / ↓

Choice moves; the document does not.

"up/down move the cursor within bounds and enter resolves the highlighted value"; "viewport keys never change the choice and choice keys never scroll"

ctrl+o

pi expands the transcript render; the pane is unchanged, because there is no second overlay for it to clobber.

By construction (one component); observed only

review line

Cold review: <VERDICT> — <reviewer>, <N> s, and — draft edited since when the draft changed after the reviewed round.

"renders the three variants as specified"; "the review body scrolls with the plan under its own heading, and is absent when nothing was recorded"; the marker comes from matchingPlanReview in packages/pi-modes/plan-tools.ts (0.17.0)

esc

Declines: back to plan mode, no approval.

"escape resolves undefined"; "an unrecognised key changes neither region and resolves nothing"

short window

On a terminal of ~15 rows the pane fits inside the screen with the consent row visible; on a window too short for any pane the tool declines with the fit refusal rather than presenting a clipped consent.

"from 0 rows to 200: the render never exceeds the budget, and shows every choice or nothing"; "below the choices themselves the pane declares it does not fit"; "a budget below the choices renders nothing rather than a partial consent" (paneLayout, paneFits, PANE_MAX_FRACTION)

Why the run is in this session

pi refuses to load a second copy of an already-loaded extension, so the pane cannot be driven from a checkout beside the installed package; the installed one is what runs. The plan-mode entry is a real one, this draft a real plan-mode artefact, and the two exit_plan_mode calls are the real cadence: round one is the cold read (its working row and settle line are 0.14.0’s presence work, also observable here), the second call reaches the human with the review beside it. Editing the draft between the calls is what makes the marker appear; the edit is the reviewer’s own notes appended under a heading, which is also what a FLAGS outcome would show, so the scroll test has something below the fold either way.

The close

Three edits on docs/close-review-pane, then the comment:

  • docs/modules/ROOT/pages/plans/review-pane.adoc: the header Status: becomes Done (YYYY-MM-DD) — accepted live by the operator (the vocabulary task plan-lint enforces admits a ` — …` tail after the date); the header’s "what remains" sentence is deleted. The page’s per-step (Status: …) lines are kept as a form — the page predates the v2026.5 plan rule and is archived under the dated override in project-conventions.adoc — but three of them are corrected to what the repository shows, so the archived page does not contradict its own header: step 5 (docs) and step 9 (known-zero) become Done (2026-09-03) naming tag v0.8.2 (pi-modes 0.6.2, meta 0.8.2), and step 6 (acceptance) becomes Done (YYYY-MM-DD) with the operator’s observation. Step 10 (close) becomes Done on the same day.

  • docs/modules/ROOT/nav.adoc: the page moves from Active to Archive.

  • CHANGELOG.adoc: no entry — nothing shipped changes; the close is a record, not a release.

  • The closing comment on #43: the merge SHAs already on the plan page, the releases, the tests named, and the operator’s acceptance in the operator’s words, including anything that did NOT behave — which becomes its own issue, not a reopen.

Scope

In

  • The acceptance run described above, in this session, on the installed package.

  • The three edits and the closing comment.

Out

  • Any fix the run surfaces. A misbehaving key, a clipped row, a wrong reviewer name — each is a new fix: issue with the observation in it. This plan closes #43 on what shipped; it does not grow.

  • The scroll-to-top jump on tool-call starts (#67, upstream, closed by the operator’s choice) — if it fires during the run it is not the pane’s.

  • plan-lint and the per-step Status lines on the archived page.

Risks

  • A key inside the split does nothing live: fail-closed for the decision (the only way to resolve the pane is enter on a choice; a dead pager key leaves the consent unanswered, never answered wrongly — "an unrecognised key changes neither region and resolves nothing") and a finding for the run — filed as its own fix: issue with the key and the terminal named, not fixed under this plan.

  • The operator’s terminal is taller than this draft: silent — the document has nothing to scroll and the scroll rows cannot be observed, so the run is inconclusive on them, not passed. The draft is ~140 lines; a 60-row terminal at the 0.8 fraction still leaves most of it below the fold.

  • Round one’s cold read finds P-fails in this plan: fail-closed by design — the review returns to the author before the human sees the pane; the findings are answered in the draft where they are right and presented beside it either way, which is the FLAGS row of the checklist.

Edit this page · latest