Add visual verification harness and section-line reference#45
Open
bhairaav wants to merge 3 commits into
Open
Conversation
…changes OpenPlans renders are visual, and code-only review missed real regressions (mirrored section-line arrows). Wire up the official @playwright/mcp server via .mcp.json, pre-approve it in .claude/settings.json, and codify the screenshot-before-done rule in AGENTS.md with a CLAUDE.md pointer. https://claude.ai/code/session_01BYwRnHk86NuZbi5MWHT4KL
… signal Codifies a binding Definition of Done for any change that affects a rendered example. Adds three harness pieces so the DoD is actually checkable: - Render-ready signal: OpenThree.animate now sets window.__OP_READY__ and dispatches 'openplans:ready' after the first frame, so screenshots don't race the Three.js first paint. - Preflight: scripts/visual-verify.sh probes the dev server and prints the canonical URL for a given example path, with distinct exit codes for missing file, missing args, and dev server down. - Reference library: docs/references/ holds per-feature expected.md files describing the traits a correct render must satisfy. Seeds the section-line reference with NCS/AIA-cited traits and an ASCII sketch. AGENTS.md § Visual Verification is rewritten as an 8-step checklist plus a handoff template. CLAUDE.md mirrors it. scripts/visual-verify.sh is negated out of the gitignored scripts/ directory. https://claude.ai/code/session_01BYwRnHk86NuZbi5MWHT4KL
Adds a CONTRIBUTING.md section that explains the harness pieces (Playwright MCP, preflight script, render-ready signal, reference library), gives the local bring-up steps, and pitches a concrete smoke-test task a local agent can run to confirm the harness works end-to-end. The test task calls out the known current defect (section-head arrows point in opposite directions) so an agent that misses it can be identified as not actually exercising the harness. Adds a top-level README link to the new section. https://claude.ai/code/session_01BYwRnHk86NuZbi5MWHT4KL
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description/Context/What Does Your PR Do
This PR establishes a visual verification harness for OpenPlans, ensuring that rendered output is checked against industry-standard references before changes are merged. It includes:
Visual verification infrastructure:
scripts/visual-verify.sh— preflight script that validates dev server availability and example file existence, printing the canonical URL to screenshot.mcp.json— Playwright MCP server configuration for headless browser automationwindow.__OP_READY__signal inOpenThree.animate()— fires after the first Three.js frame is rendered, preventing screenshots of blank canvasesReference library foundation:
docs/references/datums/section-line/expected.md— trait-based specification for section-line rendering (7 concrete, verifiable traits sourced from NCS, AIA, and architectural standards)docs/references/README.md— organizational guide for the reference libraryAgent and contributor contracts:
AGENTS.md§ Visual Verification — binding Definition of Done checklist (8 steps) for any change affecting rendered examplesCLAUDE.md— Claude-specific operating contract referencing the agent contract.claude/settings.json— Claude Code settings enabling Playwright MCP and build/dev commandsCONTRIBUTING.mdupdates — harness overview and smoke-test instructionsBuild configuration:
.gitignore— allowscripts/visual-verify.shwhile excluding other scriptsThe harness is designed to catch visual regressions that code review misses (wrong glyphs, mirrored arrows, misplaced labels) by making "correct" concrete and repeatable.
Steps To Run/Review for Other Devs
For reviewers:
AGENTS.md§ Visual Verification to understand the Definition of Donescripts/visual-verify.sh examples/src/datums/section-line.htmlexits 0 and prints a valid URLdocs/references/datums/section-line/expected.mdtraits are clear and sourced from standardsFor contributors adding visual changes:
AGENTS.mdbefore marking work completescripts/visual-verify.sh <example-path>to validate the dev server and file before screenshottingwindow.__OP_READY__ === truebefore taking screenshotsdocs/references/<area>/<feature>/expected.mdtrait-by-traitSmoke test (optional, for agents):
Run the task in
CONTRIBUTING.md§ Smoke test for the harness to verify end-to-end functionality. Expected finding: trait 4 in section-line reference currently fails (arrows point in opposite directions).Production Log Message
[x] - Visual verification harness added. Any change affecting rendered examples must now be screenshot-verified against a reference before merge. See
AGENTS.md§ Visual Verification for the binding Definition of Done.https://claude.ai/code/session_01BYwRnHk86NuZbi5MWHT4KL