Build Review Tutor learning companion

[ElbertePlinio]

Goal

Build an open-source, local-first learning companion for reviewing pull requests, Git diffs, and code without interrupting the main coding-agent session.

Product contract

• Browser stays open while the user reviews code and asks questions.
• Pi is the first honest harness connector; other harnesses appear only after working connectors exist.
• The user chooses the harness, model, explanation language, and up to three comparison programming languages.
• Code clicks and selections open a concise learning dialog with plain meaning, local context, closest language matches, notes, review-later, and an optional short quiz.
• Questions run in a separate tutor process and never enter the main Pi conversation.
• Questions, answers, notes, and quizzes remain on the webpage and in local storage outside source repositories.
• GitHub stays the source of truth. The tool never approves, comments on, or edits a pull request.

Acceptance criteria

• Load a GitHub pull request at an immutable head, a local working-tree or staged diff, a commit or range, and arbitrary code.
• Render a responsive unified diff with files, line numbers, additions, and deletions.
• Connect a local browser session to the Pi extension without exposing provider credentials.
• List available Pi models and run questions in an isolated read-only child process.
• Stream question status and answer text into the open learning dialog.
• Support one explanation language and up to three user-selected comparison languages through dropdown controls.
• Match the canonical Pickforge design system with accessible semantics, keyboard behavior, focus, contrast, and responsive layouts.
• Show an immediate accessible loading state after Ask and prevent duplicate submission while pending.
• Persist a learning log with source identity, code context, explanation, notes, review-later state, and quiz outcome.
• Offer an optional short quiz based on reviewed code with no scores, streaks, timers, or automatic prompts.
• Export a self-contained, network-free HTML learning log.
• Pass headless server, protocol, persistence, child-process, input, export, accessibility, desktop, and mobile validation.

Non-goals

• No daemon, cloud account, telemetry, provider key in the browser, or remote binding.
• No connectors other than Pi in v1.
• No side-by-side diff, code edits, PR comments, review verdicts, or automatic approval.
• No write, shell, or network tools in the tutor child.
• No global installation, npm publication, new public repository, or release in the prototype phase.

PR plan

• PR 1: secure local core and Pi connector — #60
  • Protocol, input snapshots, isolated child process, durable log, export, and headless tests.
  • Merged as b88a04c after local, CI, independent-review, and real Pi/GitHub manual-smoke validation.
  • Depends on: none.
• PR 2: guided review web app — #61
  • Diff viewer, setup, learning dialog, live answers, log, quiz, responsive and accessible states.
  • Treat the PR 1 page as temporary: apply Pickforge design standards, language dropdowns, and an accessible Ask loading state.
  • Depends on: merged PR 1.
• PR 3: package and installation proof
  • Pi package manifest, portable skill, docs, clean install, and final end-to-end review.
  • Depends on: PR 2.

Traceability

Acceptance area	Slice	Validation	Status
Inputs and immutable source identity	PR 1	input and command-injection tests	validated locally and in CI; real GitHub PR smoke passed
Isolated model execution and live protocol	PR 1	fake-child and Pi NDJSON contract tests	validated locally and in CI; real Pi/provider smoke passed
Durable log and standalone export	PR 1	corruption, escaping, and offline export tests	validated locally and in CI
Diff and learning experience	PR 2	browser tests, visual proof, real Pi/provider human smoke	validated locally and in CI; PR #61 merged
Notes, review-later, and quiz	PR 2	persistence and interaction tests	validated locally and in CI; PR #61 merged
Package and skill	PR 3	clean Pi install and real PR smoke test	pending

Agent plan

Current status: PR #60 and PR #61 are merged. PR 3 remains package and installation proof.

Next action: plan PR 3 clean-package installation and final end-to-end proof. Structure (#62), additional harness connectors (#63), and streaming/multi-tab hardening (#64) remain separate follow-ups.

Human gate: PR 3 must stop at ready for human review unless Elberte explicitly authorizes its merge.

[ElbertePlinio]

PR 1 local checkpoint

Secure local core and Pi connector implementation is ready for human review in the isolated worktree.

Validated on the current uncommitted tree:

• 55 focused Review Tutor tests passed.
• 496 repository tests passed; 25 skipped.
• Coverage passed: 76.22% statements overall; 83.54% in review-tutor/src.
• Typecheck, build, frozen lockfile install, and git diff --check passed.
• Real loopback browser smoke passed with token removal, safe hostile-label rendering, complete streaming, durable log refresh, and offline export.
• Real SSE disconnect/replay/state recovery passed.
• Real subprocess EPIPE containment passed.
• Independent Opus reviews confirmed the export, startup/shutdown, abort, SSE, persistence, and child-process corrections. The final oversized-output finding was fixed with an exact ERR_CHILD_PROCESS_STDIO_MAXBUFFER regression test.

Still intentionally deferred:

• real Pi/provider execution
• real gh pr diff and GitHub head-race execution
• Windows-native process and browser behavior
• PR 2 diff viewer and polished learning UI

No commit, push, publication, PR creation, installation, or merge was performed.

[ElbertePlinio]

PR 1 is ready for human review: #60

Reviewed HEAD: cb9e8dd44ba8cc83a5dea7a3a7f8edab8364497f

Proof:

• rebased cleanly onto 429c865 and is mergeable
• Bun 1.3.12 frozen install and full check passed
• 348 tests passed, 25 skipped; Review Tutor focused suite has 57 passing tests
• 78.27% statements overall; 84.63% in review-tutor/src
• Gitleaks, dependency audit, workspace check, and database CI jobs all passed in run 32253104394
• independent review closed all accepted findings

Still intentionally unproven: real Pi/provider execution, real GitHub diff/head-race execution, and Windows-native process/browser behavior.

Status: Ready for human review. No merge was performed. PR 2 remains blocked on this review.

[ElbertePlinio]

Manual PR 1 smoke passed locally with a real Pi session and provider. The GitHub PR source loaded and the isolated question flow worked.

PR 2 must treat the current page as temporary and materially redesign it before release:

• follow the canonical Pickforge visual system, tokens, typography, spacing, and interaction patterns
• complete an accessibility pass covering semantic labels, keyboard/focus behavior, contrast, and announced async states
• use dropdown controls for both human explanation language and programming-language comparisons
• preserve the maximum of three programming-language comparisons and label them Closest matches
• show an immediate loading state after Ask, disable duplicate submission while pending, and expose progress to assistive technology
• validate desktop and mobile layouts through the Pickforge UI/design workflow

These are PR 2 acceptance criteria, not deferred polish. The current PR 1 page is not an approved visual baseline.

[ElbertePlinio]

PR 1 merged: #60

• squash commit: b88a04c1f6aeedfe8d1086cf52ea38df691be1c0
• required CI: passed
• real local Pi/provider and GitHub PR smoke: passed
• manual finding: the PR 1 page is functionally valid but not an approved Pickforge visual baseline

PR 2 now owns the recorded Pickforge design-system, accessibility, language-dropdown, responsive-layout, and Ask loading-state requirements. No PR 2 source work has started yet.

[ElbertePlinio]

Agent plan — PR 2

Goal: replace the temporary PR 1 page with a Pickforge-standard guided review surface that is responsive and accessible.

Checklist:

• audit the rendered PR 1 surface and lock one Pickforge design contract
• render a navigable unified diff from the immutable input snapshot
• add guided selection, question, answer, notes, review-later, and quiz states
• use dropdowns for explanation language and up to three Closest matches languages
• add immediate accessible loading/disabled/cancel feedback for Ask
• validate keyboard, focus, semantics, contrast, reduced motion, desktop, and mobile
• run repository gates, independent review, CI, and stop at human review

Validation:

• focused DOM/server tests
• Bun 1.3.12 frozen install and bun run check
• rendered browser inspection at 1440px and 390px across empty, loaded, asking, answer, error, and quiz/log states
• keyboard-only and accessibility checks

Feature flag: none. The package remains private with no released product entry point; PR 3 owns installation and release exposure.

Current status: design audit in progress
Next action: design lead inspects the current surface and locks the implementation contract

[ElbertePlinio]

Design contract locked by Fable 5 (run-20260820T213139-f991).

Direction:

• Pickforge product window, not a form or AI dashboard
• 1440px diff stage + 400px tutor rail; 390px diff flow + full-screen tutor dialog
• one-ember state model, semantic emerald/rose diff colors, dense mono operator chrome
• unified diff/file navigation and contiguous line selection
• native dropdowns for explanation language and three deduplicated Closest matches
• synchronous accessible Ask busy state, streamed answer, cancellation, and recovery
• learning notes, review-later filter, and self-assessed quiz outcomes through existing APIs
• stable live regions/dialog nodes, keyboard selection, focus restoration, contrast, reduced motion, and 44px mobile targets

No framework, protocol, route, CSP, external asset, credential, or network-boundary change is allowed.

Current status: contract locked; implementation handoff next.

[ElbertePlinio]

PR 2 is open: #61

This slice delivers the Pickforge-standard guided review UI on top of PR 1's unchanged local/security boundary:

• responsive diff stage and tutor rail/mobile dialog
• keyboard and touch code selection with truthful diff coordinates
• streamed Ask states, language controls, learning log, review-later, and quiz outcomes
• executable browser-DOM regressions for parsing, accessibility, responsive teardown, SSE races, drafts, and quiz association

Local validation is clean: 75 focused tests; 366 full-suite tests passed with 25 skipped; typecheck, lint, build, coverage, diff checks, and real Chrome renders at 1440/1024/390. Independent design and correctness review accepted the current direction; final fix verification found no issues.

Still unproven for this slice: a real Pi/provider question cycle through the redesigned page and Windows-native browser/process behavior. PR 3 remains packaging and installation proof.

Status: CI running. Merge remains human-authorized only.

[ElbertePlinio]

PR 2 #61 is Ready for human review at bedee25d7578200b559fcf67be4f440ef354f8f3.

Gates:

• reviewed commit matches the PR HEAD and is mergeable
• design review: accepted
• correctness/security review: accepted with bounded nonblocking follow-ups
• targeted fix verification: accepted, no findings, KISS keep
• CI run 32424885510: check, dependency audit, Gitleaks, and Database all passed
• Database initially hit a hosted-runner 54322 port collision; its single failed-job rerun passed without source changes

Bounded deferrals for later triage:

• measure a real large-snapshot render before adding virtualization
• a log refresh deferred while an entry action owns focus can remain visually stale until the next refresh; canonical state is unchanged
• a narrow state-reconciliation/delta overlap can temporarily replace streamed text; the terminal question event restores the canonical answer
• small copy/duplicate-refresh/file-option polish remains nonblocking

Still unproven for this slice: a real Pi/provider question cycle through the redesigned page and Windows-native browser/process behavior. PR 3 remains packaging and installation proof.

No merge has been attempted. Final review and merge authorization remain with Elberte.

[ElbertePlinio]

Human smoke testing found and resolved a desktop scrolling regression in PR #61.

Cause: .diff-pane and .rail retained CSS grid's default min-height:auto, so a large diff expanded the fixed-height workbench to the full content height while body remained overflow:hidden.

Fix at b6019f2247f4f61601a6a8edfe3e32eb066bd76e: constrain both desktop grid children with min-height:0, preserving independent diff and tutor-rail scrolling. The mobile <=1040px layout remains unchanged.

Proof with the 91.8 KiB PR #61 diff in real Chrome:

• before: document/workbench expanded to ~52.7k px; diff had no internal scroll range
• after: document/workbench equal the viewport; diff viewport 1,955 px vs 52,618 px content; scroll reached offset 500
• 75 focused tests and 366 full-suite tests passed
• typecheck, lint, build, coverage, and diff checks passed
• targeted fix verification accepted with no findings; KISS keep
• CI run 32480560913 passed all jobs

PR #61 is again Ready for human review. No merge attempted.

[ElbertePlinio]

Human smoke correction — contextual tutor flow

The latest PR #61 smoke exposed a discoverability and layout mismatch:

• gutter-only selection had no visible GitHub-like affordance, so code selection appeared broken
• the right rail mixed persistent configuration with the per-selection question flow
• Harness and Model were conflated in one model selector

The corrected PR 2 contract is now locked:

• show a visible neutral + affordance on diff-line hover/focus; click selects one line and Shift-click extends a contiguous range while code text remains natively selectable
• open one stable inline Ask/Quiz composer directly beneath the selected range
• make the desktop configuration rail collapsible
• expose the same configuration as an accessible mobile/high-zoom drawer
• add separate native Harness and Model selectors; Harness truthfully contains only Pi in v1, with no fake Claude Code or Codex options and no protocol change
• move the stable Learning Log into the review flow, reachable through configuration navigation at every width
• preserve the current 860px reflow, sticky bars, long-line wrapping, selection limits, Ask/SSE reconciliation, quiz/log behavior, security boundary, and local-only architecture

Actual Claude Code and Codex connectors remain follow-up architecture work because they require real isolated execution, model discovery, cancellation, and security behavior. They will not be represented as working options before those connectors exist.

Current status: frozen design contract reviewed; focused four-file implementation handoff next. No commit, push, or merge authorized.

[ElbertePlinio]

Contextual review correction — ready for human smoke

Human feedback on selection, harness/model clarity, and the overloaded sidebar has been implemented locally in PR #61's isolated worktree.

Delivered:

• GitHub-like line flow: click a line number, Shift-click to extend, then select the visible neutral + or press Enter to open the inline Ask/Quiz composer
• native code text selection remains independent
• stable inline composer beneath the selected range, with drafts/answers preserved through re-anchoring and responsive transitions
• collapsible desktop configuration rail
• accessible mobile/high-zoom configuration drawer
• separate honest Harness (Pi only) and live Model selectors; no fake connectors and no protocol payload change
• stable Learning Log moved into the review flow with reachable navigation
• one mobile scrollbar owner, modal focus containment, and clean inert/body-lock teardown
• preserved long-line wrapping, 860px boundary, sticky bars, desktop dual scrolling, and 400px two-row toolbar

Acceptance corrections closed:

• layout containment prevents file/log scrollIntoView from displacing the desktop root; real Chromium keeps rootTop 0 and toolbar y52 after range centering, file navigation, and log jump
• desktop-only resize preserves question focus/caret
• selection-only and genuinely open composer states now roundtrip honestly across zoom
• 947px toolbar is a single row after the final flex-basis correction

Proof on the final local tree:

• 43/43 page tests
• 100/100 Review Tutor tests
• 391 repository tests passed, 25 skipped
• typecheck, lint, build, and git diff --check passed
• real Chromium: 8-line range, + composer gap 8px, native copy unchanged, 1420 collapsed 1376/44, 947 rail 320/single-row toolbar/no overflow, 800/400 dialogs single-scroll, 400 toolbar y52/h99/file-head y150
• final independent Fable design/accessibility re-review: accepted, no high or medium findings

Status: Ready for Elberte's manual smoke. Changes remain uncommitted and unpushed; no merge attempted. Actual Claude Code and Codex connectors remain follow-up architecture work.

[ElbertePlinio]

Progress update:

• Planned the evidence-backed Structure/architecture view as follow-up Add evidence-backed Structure view to Review Tutor #62.
• Split it into analysis core, accessible Connections list, deterministic graph, and Dart/Rust+tutor integration slices.
• Marked it deferred until PR feat(review-tutor): redesign guided review interface #61 is finished and human-approved.

Latest local PR #61 smoke corrections:

• tutor answers render a safe Markdown subset instead of raw Markdown text
• redundant visible Running and Ready to ask labels removed
• cancellation completion race now reconciles canonical question state instead of leaving the page stuck on running

Proof on the current local tree:

• 104/104 Review Tutor tests
• 395 repository tests passed, 25 skipped
• typecheck, lint, build, and git diff --check passed

Current status: PR #61 manual smoke remains the priority. Changes are local, uncommitted, and unpushed.
Next: finish PR #61 human review; resume #62 afterward.