[Slice 18] Large-report artifact packaging and visual acceptance gate

[EmersonBraun]

Parent PRD

#99

What to build

Make report delivery practical for enterprise-sized repositories. Keep small reports self-contained, split large reports into local offline-readable artifacts, and add deterministic plus perceptual acceptance checks that prevent regressions like the current unreadable agentskit-os report.

Type

AFK

Scope

• Add configurable automatic artifact selection with a default single-file threshold of 5,000,000 bytes.
• Keep small output as one offline HTML file.
• For larger output, write an atomic report directory containing an index HTML, manifest and local JavaScript data chunks for overview, levels and findings.
• Preserve file:// compatibility; do not require a server or network request.
• Include artifact/schema/configuration/source hashes and generation metadata in the manifest.
• Add a visual acceptance command/test covering 1440×900, 1600×1000, 1920×1080 and 2048×1320, light/dark or configured themes, first-screen containment, readable graph controls and grouped findings.
• Preserve last-known-good output on failed generation.

Non-goals

• Do not add hosted storage, telemetry, Archify dependency or a general-purpose diagram editor.
• Do not claim visual quality from DOM/unit tests alone.
• Do not change canonical snapshot or reconciliation semantics.

Acceptance criteria

• Output mode is deterministic and configurable; identical inputs choose the same artifact layout and hashes.
• A report below the threshold is a single offline HTML file; a report above it is a directory with a loadable index and manifest.
• The large agentskit-os case loads from file:// without external assets, fetches or network access, and exposes all report levels and findings through explicit controls.
• Failed rendering never replaces the last-known-good report or leaves a partially committed artifact directory as current.
• Manifest hashes bind the exact snapshot, reconciliation report, configuration and generated artifact files.
• Visual checks detect horizontal overflow, unreadable clipping, missing controls, excessive first-screen density and a findings page that grows linearly with every duplicate diagnostic.
• The visual test records screenshots/evidence and reports a truthful pending/failed/passed status; automated checks do not masquerade as human visual review.
• Existing single-file consumers and current CLI/MCP report paths remain compatible.
• Full typecheck, tests and build pass.

Verification

Run:

pnpm typecheck
pnpm test -- --run
pnpm build

Then run the complete dogfood workflow in agentskit-os, generate the report, open it offline, inspect the screenshots, and confirm that tracked source files are unchanged.

Blocked by

• Blocked by [Slice 14] Deterministic hierarchical report view and bounded architecture map #126
• Blocked by [Slice 15] Code-to-documentation drift comparison lens #127
• Blocked by [Slice 16] Grouped findings triage and evidence-first attention queue #128
• Blocked by [Slice 17] Read-only graph investigation controls and stable report navigation #129

User stories addressed

• User stories 21, 22, 41, 42, 64, 69, 70, 71, 72 and 73

Definition of done

Small projects retain a frictionless single-file report, large projects receive a navigable offline artifact, and the release gate can detect both functional and visible regressions before delivery.

[EmersonBraun]

Implemented the first large-report delivery pass.

• Added a configurable 5,000,000-byte default threshold.
• Small reports remain single-file and self-contained.
• Large reports are written atomically as a local directory with index.html, manifest.json, and overview/levels/findings JavaScript chunks.
• The existing report.html path remains usable through a local iframe launcher.
• Manifest hashes bind snapshot, report, configuration, source revision, index, and chunk contents.

Validated on agentskit-os: directory output generated with all five expected files; manifest hashes verified; no network-backed script/link assets detected.

[EmersonBraun]

Correction to the previous update: added scripts/report-visual-check.mjs and the pnpm report:visual command. It captures 1440x900, 1600x1000, 1920x1080 and 2048x1320 in light and dark themes, checks overflow, clipping, first-screen placement, required controls, bounded findings and external requests, and reports failed, pending-human-review, or passed. It never treats automated checks as human approval. Also added UTF-8 byte thresholds, render options and hashes to the artifact manifest, atomic launcher and directory rollback, dark-mode defaults, and public artifact exports. Full typecheck, test suite, build, and agentskit-os large-report dogfood pass. Visual review remains pending because the embedded browser blocks automated file URL inspection.