ReadViewSDK/.planning/phases/03-page-metadata-pagination/03-VALIDATION.md

phase	slug	status	nyquist_compliant	wave_0_complete	created
3	page-metadata-pagination	draft	true	false	2026-05-22

Phase 3 — Validation Strategy

Per-phase validation contract for page metadata and paginator-semantic work.

---

Test Infrastructure

Property	Value
Framework	shell assertions + Xcode build smoke + demo EPUB diagnostics
Config file	none — repo still has no dedicated XCTest target for this phase
Quick run command	test -f .planning/phases/03-page-metadata-pagination/03-RESEARCH.md && test -f .planning/phases/03-page-metadata-pagination/03-PATTERNS.md
Full suite command	xcodebuild -workspace ReadViewDemo/ReadViewDemo.xcworkspace -scheme ReadViewDemo -destination 'platform=iOS Simulator,name=iPhone 17' build
Estimated runtime	~60-90 seconds

Sampling Rate

• After every task commit: Run the task’s rg assertions against touched rendering/pagination files.
• After every wave: Run the ReadViewDemo simulator build smoke.
• Before $gsd-verify-work: Demo sample EPUB diagnostics must still pass, and Phase 3 plans/summaries must exist.
• Max feedback latency: 90 seconds

Per-Task Verification Map

Task ID	Plan	Wave	Requirement	Secure Behavior	Test Type	Automated Command	Status
03-01-01	01	1	REND-03	Page/chapter models expose richer metadata without dropping offset continuity	source	`rg -n "metadata	attachment
03-02-01	02	2	REND-04	Paginator no longer relies on pure visible-range slicing and introduces layouter/frame semantics	source	`rg -n "Layouter	LayoutFrame
03-03-01	03	3	REND-03, REND-04	Sample EPUBs and page diagnostics prove large blocks/images keep offset-compatible pagination	smoke/source	`rg -n "diagnostic	metadata

Wave 0 Requirements

• ReadViewDemo/ReadViewDemo.xcworkspace and ReadViewDemo scheme still build before close-out.
• Validation continues to use ReadViewDemo/ReadViewDemo/book/ as the regression corpus.
• No plan may remove pageStartOffset, pageEndOffset, or fragment offset compatibility.

Manual-Only Verifications

Behavior	Requirement	Why Manual	Test Instructions
Large blocks and images break at better boundaries	REND-04	Visual edge quality still needs a human read-through	Open a sample EPUB with images and long paragraphs; confirm boundaries are improved versus old slicing.
Highlight/search navigation still lands on the correct page after repagination	REND-03, REND-04	Requires end-to-end interaction with existing reader flow	Use the demo reader to navigate to saved ranges or search matches after pagination changes.

Validation Sign-Off

• All tasks have automated verification commands
• Sampling continuity: no 3 consecutive tasks without automated verify
• Wave 0 covers offset-compatibility invariants
• No watch-mode flags
• Feedback latency < 90s
• nyquist_compliant: true set in frontmatter

Approval: pending