Michael Ramos
33ff0edea5
Review findings on the durable feedback archive. 1. The archive is default-on, and most server tests boot a real plan, review, or annotate server without redirecting PLANNOTATOR_DATA_DIR, so `bun test` deposited records in the contributor's own ~/.plannotator/feedback (24 files across 12 buckets from two test files alone) on CI and every machine. A new bunfig test preload, tests/setup/feedback-archive-off.ts, turns the archive off for the suite; the archive's own tests opt back in inside their test bodies, which is also how they exercise the opt-out. Those tests now use distinctive project names and remove the annotate history they leave in the real data dir, since storage.ts fixes its data directory at import time. 2. PR reviews bucketed under feedback/pr-<n>/. PR mode never sets gitContext and --local points agentCwd at a pool/pr-<n> checkout, so deriving the project from the review cwd was wrong. ReviewServerOptions now takes a `project` option, mirroring the annotate server, preferred over the cwd derivation on both runtimes; the Claude Code, OpenCode, and Pi entry points pass their already-computed detectProjectName() result. 3. changedFiles overcounted renames: extractChangedFiles unions the a/ and b/ sides so a reader can resolve either path. The record now counts b-side paths through countChangedFiles, so a rename is one file. 4. Docs: the feedback archive is added to the privacy page and PLANNOTATOR_FEEDBACK_HISTORY (plus PLANNOTATOR_ANNOTATE_HISTORY) to the environment variables reference. The overclaim that every submitted review is archived is corrected: a review posted straight to GitHub or GitLab through /api/pr-action is not archived locally yet. Three behaviors are now written down: O_APPEND is not atomic on NFS or SMB and a genuine interleave damages both records that raced, folder-session records carry the folder path rather than the open document, and URL-session records store the full URL including its query string. 5. Pi parity: the Node mirror now has the failed-archive-write test (the one invariant its handler copies by hand) and the PR-mode bucketing test. Comments only, no behavior change: the pool checkout recorded in target.review.cwd can be cleaned up before anyone reads the record, and getPlanVersionPath resolves the data directory storage.ts captured at import while the archive resolves it per call. AI-assisted (Claude) under maintainer direction.
Tests
This directory contains manual testing scripts for Plannotator.
Manual Browser UI Smokes (tests/manual/local/)
These are local-only scripts for launching Plannotator UI flows with fixture data so you can manually verify them in a browser. They are not automated CI tests.
Plan review UI smoke tests:
./tests/manual/local/test-hook.sh # Claude Code simulation
./tests/manual/local/test-hook-2.sh # OpenCode origin badge test
./tests/manual/local/test-codex-plan-review-e2e.sh # Real Codex Stop-hook flow in disposable HOME
Code review UI:
./tests/manual/local/test-opencode-review.sh # Code review UI test
./tests/manual/local/test-worktree-review.sh # Worktree support test (creates sandbox with 4 worktrees)
See UI-TESTING.md for detailed UI testing documentation.
The end-to-end, user-centered Vim controls matrix lives in manual/vim-ux-smoke.md. It covers real Markdown and raw-HTML navigation, selection, annotation, focus recovery, HUD behavior, and native-control compatibility.
Integration & Utility Tests (manual/local/)
These scripts test integrations, releases, and provide utilities.
Binary release testing:
./tests/manual/local/test-binary.sh # Test installed binary from ~/.local/bin/
Tests the installed plannotator binary to verify releases work correctly.
Bulk plan testing (Obsidian integration):
./tests/manual/local/test-bulk-plans.sh # Iterate through ~/.claude/plans/
Opens each .md file from ~/.claude/plans/ in Plannotator. Great for testing Obsidian integration with multiple
plans.
OpenCode integration sandbox:
./tests/manual/local/sandbox-opencode.sh [--disable-sharing] [--keep] [--no-git]
Creates a temporary sandbox with a sample React/TypeScript project, initializes git with uncommitted changes, sets up the local OpenCode plugin, and launches OpenCode for full integration testing.
Options:
--disable-sharing: Createsopencode.jsonwith sharing disabled--keep: Don't clean up sandbox on exit--no-git: Skip git initialization (tests non-git fallback)
Codex Stop-hook end-to-end harness:
./tests/manual/local/test-codex-plan-review-e2e.sh [--keep] [--skip-build]
Builds the hook and review apps, creates a disposable HOME plus sample git repo, copies your Codex auth.json,
enables hooks, and runs a real codex exec against the sample project. The script writes logs, rollout paths,
history indices, and session URLs into an artifact directory under the temp root.
Tips:
- Set
PLANNOTATOR_BROWSER=/usr/bin/truewhen you want to drive the opened plan-review session with Playwright instead of auto-opening a browser. - The validated workflow is: run the script in one terminal, then point Playwright at the printed session URL from a second terminal.
Obsidian utility:
./tests/manual/local/fix-vault-links.sh /path/to/vault/plannotator
Adds Obsidian backlinks ([[Plannotator Plans]]) to existing plan files in your vault.
SSH Remote Testing (manual/ssh/)
Tests SSH session detection and port forwarding for remote development scenarios.
cd tests/manual/ssh/
docker-compose up -d
./test-ssh.sh
See manual/ssh/DOCKER_SSH_TEST.md for detailed setup instructions.