Read report validation artifacts asynchronously

Traceability

• Spec ID: async-report-validation-reads
• Status: Implemented

Intent

Keep report validation non-blocking while it loads generated Markdown, findings, and HTML artifacts. The renderer already exposes an asynchronous validation pipeline, so independent artifact reads should use the promise-based filesystem API and complete together without changing report contents or validation decisions.

Acceptance Scenarios

• ARV-AC-1 (asynchronous reads): Markdown and HTML report validation reads generated artifacts through the promise-based filesystem API, with no synchronous file reads remaining in render-report.mjs.
• ARV-AC-2 (bounded concurrency): The independent findings, Markdown, and optional HTML reads begin through one bounded Promise.all operation; Markdown mode does not require an HTML artifact.
• ARV-AC-3 (output compatibility): Rendering preserves the existing artifact names, contents, ordering in the renderer result, and selected validation checks for Markdown and HTML modes.
• ARV-AC-4 (failure safety): An unreadable required artifact still rejects validation before the staged run is published, retaining the existing atomic publication boundary.

Non-goals

• Change report schemas, renderer output, validation rules, or reader-visible copy.
• Parallelize artifact writes, Canvas validation, or publication and rollback.
• Change CLI arguments, output locations, run-directory allocation, or supported hosts.
• Add caching, streaming, or performance claims that are not measured by this change.

Plan and Tasks

1. Update scripts/harness-analysis/render-report.mjs to import readFile from node:fs/promises and remove its synchronous read dependency.
2. Read findings, Markdown, and the optional HTML artifact through one Promise.all while preserving the current validation calls and artifact ordering.
3. Run focused HTML coverage and the complete report-render test file.
4. Run the full repository suite, separately verify loopback preview tests when sandbox networking blocks them, and check the final diff for whitespace errors.

Test and Review Evidence

• ARV-AC-1/ARV-AC-2: focused diff review confirms readFileSync is removed from render-report.mjs and the three independent reads share one Promise.all operation.
• ARV-AC-3: run node --test --test-name-pattern="render command writes disk-openable HTML artifacts|HTML mode validates canonical compact" test/harness-report-render-cli.test.mjs.
• ARV-AC-3: run node --test test/harness-report-render-cli.test.mjs; its staging, validation, output-location, Markdown, HTML, and publication coverage must remain green.
• ARV-AC-4: focused control-flow review must confirm artifact reads remain inside staged validation and publishStagedRun is reached only after validation succeeds.
• Regression gate: run npm test. If sandbox loopback restrictions produce listen EPERM, rerun node --test test/preview-servers.test.mjs with local loopback permission and record both results without presenting the sandbox result as a product failure.
• Documentation gate: regenerate the routing graph with node scripts/doc-link-graph/cli.mjs skills/better-harness, then run node --test test/doc-link-graph.test.mjs.
• Diff gate: run git diff --check and confirm the change remains limited to the renderer and this Spec.
• Primary risk: concurrent reads can change which filesystem error is observed first when multiple required staged artifacts are simultaneously unreadable. Normal rendering creates all required artifacts before validation, and the staged publication boundary prevents partial output from replacing a prior run.

Observed Evidence (2026-08-04)

• ARV-AC-1/ARV-AC-2: render-report.mjs now imports readFile from node:fs/promises; readFileSync is absent, and findings, Markdown, and the optional HTML artifact are read by one Promise.all.
• ARV-AC-3: the two focused HTML tests passed 2/2, and node --test test/harness-report-render-cli.test.mjs passed 32/32 across Canvas, Markdown, and HTML rendering contracts.
• ARV-AC-4: the existing control flow still writes into stageDir, validates that staging directory, throws on failed validation, and invokes publishStagedRun only after the validation gate passes.
• Full regression: npm test ran 1,148 tests; 1,145 passed and three loopback preview tests failed with sandbox-only listen EPERM. The bounded rerun node --test test/preview-servers.test.mjs passed 8/8 with loopback permission.
• Documentation gate: the routing graph generator reported 35 files and 51 links with no generated diff; node --test test/doc-link-graph.test.mjs passed 6/6.
• Package gate: the default npm run pack:verify attempt was blocked by an unwritable user npm cache. Re-running with the isolated task cache /tmp/better-harness-npm-cache-20260804 passed with 395 npm entries and 417 runtime ZIP entries; no user cache permissions were changed.
• git diff --check passed. The working tree remains unstaged so the reviewer can inspect the renderer and Spec together before commit.