[Feat] Add architecture snapshots to task evidence

[roomote-roomote]

​Opened on behalf of @daniel-lxs. Follow up by mentioning @roomote-roomote, in the web UI, or in Slack.

What changed

• Added a versioned architecture-snapshot artifact contract with schema version 1, Mermaid source, and validated repository-relative source references with optional line ranges and descriptions.
• Allowed agents to upload snapshots through the existing manage_artifacts path. Valid snapshots are stored as application/json even when their file name has no extension, while invalid snapshot JSON is rejected before publication begins.
• Rendered valid snapshots only inside the existing task artifact viewer, with a generated-evidence warning, contract version, Mermaid diagram, source references, and a raw JSON toggle.
• Added focused shared-contract, API, worker publication, and web UI tests.

Why this change was made

Reviewers currently need to reconstruct the changed system boundary and likely blast radius from the repository before they can assess multi-package work. This prototype gives Roomote agents a small, review-oriented evidence artifact that explains the affected architecture while citing the files behind the explanation.

Impact

Architecture snapshots are optional task evidence and use the existing artifact storage, authorization, path-based versioning, listing, and viewer flows. Normalizing validated snapshots to JSON ensures the viewer fetches extensionless artifacts without changing MIME handling for other artifact types. Existing persisted general, plan, and visual-proof artifacts remain valid, and no database migration or automatic generation path is introduced.

Security and guardrails

• Snapshot JSON is validated against a strict, bounded schema before agent publication and again before rendering.
• Source paths reject absolute paths, traversal segments, URL schemes, backslashes, empty segments, and control characters. References render as inert text rather than links, preventing untrusted navigation.
• Mermaid renders through Streamdown with securityLevel: "strict" and suppressed error rendering. Dynamically sized Markdown fences prevent Mermaid source from escaping into surrounding Markdown.
• Invalid or unsupported snapshots fail closed to a warning with raw/download access; they are never interpreted as Mermaid.
• UI copy explicitly labels snapshots as generated explanatory evidence, not authoritative architecture documentation.
• Agent guidance states that snapshot publication is optional and upload failures must not block task completion.

Validation

• Focused tests passed: shared contract (9), artifact API (2), worker publication/tooling (75), and web renderer/viewer (10).
• The worker upload regression test covers a valid extensionless snapshot and verifies application/json reaches artifact creation.
• pnpm lint, pnpm check-types, and the pre-push oxlint, residual lint, fast typecheck, and knip gates passed.
• Browser capture reached the real task viewer, but the seeded task had no artifacts and the local app exposed no supported artifact fixture mutation. No screenshot is claimed; rendered-state behavior is covered by the focused client tests.

Deferred work

• Automatic multi-package or multi-service detection and snapshot generation.
• Pilot targeting and generation policy for larger changes.
• Snapshot engagement, open, reference, or task-duration metrics.
• Clickable provider-specific source navigation, which requires a trusted repository-link abstraction rather than accepting artifact-provided URLs.

[roomote-community]

No new code issues found. See task

• apps/worker/src/mcp/roomote-mcp-server/upload.ts:47 Valid extensionless snapshot files are stored as binary content, so the artifact viewer never fetches or renders them.

_{Reviewed f613b1c}

[roomote-roomote]

Fixed extensionless architecture snapshots in f613b1c0. Validated snapshots now upload as application/json regardless of file extension, so the artifact viewer fetches their content. The extensionless regression test, worker typecheck, worker lint, and pre-push checks pass; the review thread is resolved.