• Date: 2026-06-07
• Status: Proposed (design spec, separate session work)
• Phase / Feature: Arno Sorgente — Workflow tab
• Builds on: ADR 0030 (page reconstruction / capture-v3), ADR 0049 (Arno Sorgente)

Context

When I open the Workflow tab in any normal ARNO project, I see that project's pages — captured screens arranged into a navigable tree of the product the designer is working on. ARNO's own Workflow tab inside Arno Sorgente must do the same: show the complete live product tree of ARNO itself — every route, every page, every shell, every panel. This is the maintainer's map of "what ARNO is, right now."

Without this view, I edit individual surfaces (Library, the navbar) without seeing the whole. With it, I get a satellite picture of the product and can navigate / edit / publish at the right altitude.

This ADR scopes that feature. Not a small one — it touches capture-v3, SSR, route discovery, dependency graphs. Worth a dedicated session later. For now, capture the invariants so I don't lose context.

Decision

§1 — Source of truth is automatic, not curated

The Workflow tab does not ask me to hand-list ARNO's pages. The tree comes from automated discovery:

1. Next.js route manifest. Walk apps/web/src/app/**/page.tsx at build time → emit a JSON of all routes + their hierarchy. Static routes (/app/library, /app/workflow) flat-listed; dynamic (/app/screen/[id]) marked parametric.
2. Composition manifest. For every route discovered, run the capture-v3 pipeline (ADR 0030) against a logged-in maintainer session → emit a composition_instance per route. Stored against prj-arno-sorgente like any other captured page.
3. Live recapture. A maintainer button "Refresh Workflow" runs the discovery + capture sweep on demand; nightly cron does the same as background drift detection.

Discovery is part of the build pipeline (Phase G in ADR 0049 §10 already covers this for Sorgente's structural Layer 3).

§2 — Tree shape

The tree mirrors the URL hierarchy with two extensions:

• Shells as wrapper nodes. apps/web/src/app/app/layout.tsx shows up as a shell wrapping every /app/* route — so I can pick the navbar or sidebar as their own editable nodes without diving into every page they appear on.
• Inline panels as child nodes. Popovers, drawers, dropdowns that open from a page are shown as collapsible children under their trigger surface. (E.g. the genealogy drawer in Library is a child node of /app/library/colors/semantic.)

Each node carries:

• Route path or shell name
• Thumbnail (rendered preview, refreshed on capture)
• Last-edited timestamp + author
• Status badge: clean / has-uncommitted-changes / mirrored-from-test

§3 — Click-to-edit cascade

Clicking any node opens it for editing in the same Sorgente surfaces already specified in ADR 0049:

• Visual edits → Colors / Typography / Spacing token panels (Tokens tab inside Library).
• Structural edits → composition editor (Layer 3 from ADR 0049 §8) with drag-rearrange of the tree.
• Variant edits → component variant panel (ADR 0044).

Every edit follows the mirror-to-Sorgente path from ADR 0049 §3. So clicking on the Library's "Mentor glossary" pill in the Workflow tree opens an editor where I can change its padding / color / order / whole JSX, and the change lands in Sorgente immediately.

§4 — Coverage badges

Each node displays accessibility + WCAG coverage badges at a glance:

• WCAG AA pass / fail count for the surfaced semantic role pairs.
• Foundation token usage percentage (how much of the page uses Foundation tokens vs hardcoded / inline values).
• Self-hosted percentage (how much of this page is editable through Sorgente vs substrate code that requires a PR).

The "self-hosted percentage" badge is the leading indicator of how close ARNO is to full self-hosting completeness. Sub-100% on critical pages → backlog item to make that surface fully composable.

§5 — Substrate boundary visualization

Nodes split into two visual tiers:

• Editable nodes (rendered from composition_instance) — clickable, open the editor. Drawn in mint outline (matches LayoutInspector's picked-element treatment).
• Code-only nodes (substrate — auth gate, renderer, dev-tools, middleware) — appear in the tree for completeness but show a "code PR required" tooltip on click instead of opening the editor.

This is the visual realization of ADR 0049 §8a's "if it renders, it's mirrorable; if it computes, it's code." Designer sees the line.

§6 — Out of scope (this ADR)

• Multi-environment tree merging (dev vs test vs prod). Workflow shows one env at a time; switcher in the tab header.
• Inline cross-page consistency lint (does the Button look the same on every page that uses it?). Belongs to a separate review/lint surface, not the Workflow tree.
• Designer collaboration / cursors / multiplayer. Single-maintainer assumption holds; team scale is a later ADR.

§7 — Phases (delivery order, post-Sorgente)

Same gating as ADR 0050: depends on Sorgente Phases A-J being live.

1. Phase P — Route + composition discovery (~2 days). Build step that walks app/**/page.tsx + drives capture-v3 against ARNO's own routes.
2. Phase Q — Tree UI in Workflow tab (~2-3 days). Node renderer, thumbnail loader, hierarchy view, click-to-open.
3. Phase R — Coverage badges (~1-2 days). Compute self-hosted % + Foundation-usage % + WCAG fail count per node.
4. Phase S — Refresh + drift detection (~1 day). Manual refresh button + nightly cron + diff highlight on the tree.

Total ~6-8 days post-Sorgente.

Open questions / parking

• Snapshot retention for tree captures. Each capture run produces composition_instance rows for every ARNO route. Storage grows. Same retention policy as ADR 0049 §11.5 (hourly/daily/monthly compaction) applies; the captures are just another kind of timeline entry.
• Dynamic routes that need fixtures. /app/screen/[id] can't be captured without an id. Solution: maintainer-curated list of representative ids per parametric route, stored in arno_sorgente_capture_fixtures table. One-time small overhead.