ADR-174 — Verb-led IA synthesis: nine verb-routes over a preserved noun-route catalogue

Status: Proposed Date: 2026-05-08 Decider: Operator Extends: ADR-058 (five-mode platform UI), ADR-059 (project-first IA), ADR-062 (design system + component strategy), ADR-065 (persona-aware IA + niceties), ADR-070 (<PlaybookRunner> UI contract), ADR-125 (Heed/Brief/Ramp/Vie product surfaces + four substrates) Related: ADR-006 (gyrum-ui as design canon), ADR-067 (playbooks unified primitive), ADR-115 (principle-aware reviewers), ADR-116 (RAG knowledge-base), ADR-117 (module guidelines), warp#1809 (canon-extraction Phase 3 precondition), warp#944-947 (Heed/Brief/Ramp/Vie epics), warp#1804 (preview source-of-truth), warp#974 (console-error smoke gate)

TL;DR

ai-frontend has 95 noun-routes (/operate, /infra, /projects, /platform, /me, /ops, /team, /incidents, /release-status, …) shaped around organisational silos rather than user JTBDs. The four personas defined in ADR-065 walk in with verb-shaped first questions ("what's on fire?", "what shipped?", "what changed?", "what needs my decision?") and pay a translation tax — "which silo do I click" — to reach the answer. This ADR ratifies the nine verb-routes that become the discovery primary: four already proposed in ADR-125 (/heed, /brief, /ramp, /vie) plus five net-new ones (/pulse, /board, /trace, /canon, /graph). Existing noun-routes are preserved as deep-links — only five (/changes, /compare, /incidents, /health, /release-status) are scheduled for redirect. Verb-routes are additive, not a big-bang. Persona homes (/, /me, /ops, /team) survive unchanged per ADR-065.

Context

The translation tax

ADR-058 carved the platform into five modes (Home / Ship / Operate / Infra / Experiment); modes are verbs at the lens layer ("which projection am I looking through?"). ADR-059 added Project as a first-class noun ("which thing am I looking at?"). ADR-065 layered four persona homes ("who is asking?"). Each axis is sound; together they answer three of the four questions a user has at the door. They do not answer the fourth: what is the user actually trying to do right now?

The 2026-05-02 vision-setting that produced ADR-125 surfaced the gap: the factory generates rich SIGNAL — agent reports, structural-check verdicts, persona-review findings, deploy events, probe outcomes, validate-projects results — and exposes it on passive surfaces. /operate aggregates if you look. /infra renders if you click. There is no PUSH, no SCOPED ROUTING, no DAILY DIGEST, no STAGED DEPLOY, no VARIANT-COMPARISON DECISION SUPPORT. ADR-125 named the four product surfaces that solve the activation gap (Heed / Brief / Ramp / Vie) and the four substrates that back them (user/role/area, channel-out, inference, signal-collection). What ADR-125 did not answer: how does the user discover those surfaces in a 95-route app, and what about the operational and strategic questions the four product surfaces don't directly answer (status now, status this week, "what changed", "what's the principle here", "what's the blast radius")?

The verb-led IA fills the discovery gap and the question gap. It is the synthesis layer above ADR-058 (modes), ADR-059 (project), ADR-065 (persona), ADR-070 (playbook-runner), and ADR-125 (Heed/Brief/Ramp/Vie). It does not contradict any of them; it routes through them.

Phase 3 unblocked the redesign

The redesign was structurally blocked until warp#1809 (canon-extraction Phase 3) closed. That epic moved every factory consumer off parallel gy-* CSS shadow-shape onto <gy-*> Web Components from @gyrum-labs/components, ratifying ADR-006 + ADR-062 as the design canon. With the substrate honest, new surfaces can compose primitives instead of forking visual contracts. Phase 3 is the precondition, not the redesign itself; this ADR is the redesign.

Five personas, no reinvention

ADR-065 names four personas (Owner / Dev / SRE / Manager) with persona homes at /, /me, /ops, /team. CEO and Product are not new personas — they are KPI-emphasis modes within Owner and Manager respectively. Reviewer is a sub-journey within Dev, not a fifth persona route; ADR-065's four-persona contract is load-bearing for ⌘K palette grouping, the home-mode sidebar, and the journey-cap discipline (≤3 red routes per persona). Adding a fifth route would require an ADR-065 amendment and re-cut every downstream contract. The verb-led IA respects the four-persona ceiling and treats Reviewer as a ?lens=reviewer filter on top of Dev's surfaces (primarily /canon + /trace?q=pr/<n>).

Decision

1. Nine verb-routes, additive to the noun-route catalogue

Five net-new in this ADR (rows 1-6 minus duplicates with ADR-125). Four already proposed in ADR-125 (rows 7-10). /vie is reserved per ADR-125 but not delivered in Phase 4-5; the slot is held so the route map is honest.

2. Verb-routes are additive entry primaries; nouns survive as deep-links

The 95-route audit (full table in §Migration path) shows that 90 routes are preserved as deep-links and only 5 are scheduled for redirect. This is the load-bearing invariant: the redesign does not delete the project-first IA (ADR-059), it adds a verb-shaped entry layer above it. A user who knows the URL keeps it. A user who knows the JTBD finds the verb-route. The two paths converge on the same data.

The five redirected routes are:

• /changes → /trace
• /compare → /trace
• /incidents → /heed + /trace (push primary, timeline secondary)
• /health → /pulse?lens=sre
• /release-status → /pulse + /board

Each redirect is a 301 with the query-string carrying the original scope. No bookmark loss.

3. Lens parameter is the persona projection axis

Each verb-route accepts ?lens=dev|sre|manager|owner|reviewer, which shapes priority sort but never hides data. /pulse?lens=dev foregrounds "PRs awaiting me, my failing CI, what changed in repos I touched"; /pulse?lens=sre foregrounds "alerts, degraded services, deploys with blast radius". The same surface, the same query API, the same primitives — different priority sort. Default lens is inferred from the operator's persona (warp users table per ADR-125 substrate 1; falls back to Dev if unset).

This is the structural answer to the "persona dropdown vs persona route" question ADR-065 §2 already settled at the home layer: the URL is the contract at the home layer (/me ≠ /ops), but at the verb layer the URL is the action (/pulse) and lens is the projection. Mixing the two would have two URL-axes for one user-question; the split is honest.

4. Substrate dependencies + status

Substrates are the load-bearing engineering. Surfaces compose against them; some surfaces ship "v1 cheap" against existing substrates and graduate when the new substrate lands.

Cross-link: each substrate has its own spec at docs/fleet/ai-frontend/docs/substrates/<slug>.md (this PR), naming schema, API, producers, consumers, v1/v2 split, status, and migration path.

5. Persona × surface matrix

The matrix below is the contract: each persona's primary surfaces, ordered by frequency-of-use. ADR-065's persona homes (/, /me, /ops, /team) sit alongside, not in conflict.

6. Visual contract — preview-canvas first

Per CLAUDE.md / warp#1804: every new verb-route delivers at minimum one preview-canvas page at /dev/factory-preview/* or /dev/platform-preview/* matching one of the 14 carved categories (project-shells, dashboards, tables-and-lists, forms-and-inputs, empty-and-state, detail-pages, overlays-and-feedback, full-chrome, live-state, legacy, marketing, network-diagrams, data-views, live-shell). The preview is the source of truth, not current production. Each surface spec in this PR cites its preview category.

7. Phasing (12-16 weeks calendar; parallel-friendly)

Phase 4 — ratify + ship the cheap surfaces (3-4 weeks). This ADR ratified; 8 surface specs + 5 substrate specs landed (this PR); 7 missing primitives shipped in gyrum-ui (<gy-form>, <gy-form-field>, <gy-select>, <gy-action-button>, <gy-timeline>, <gy-handoff>, <gy-risk-pyramid>, <gy-cost-bar>, <gy-trust-meter>, <gy-pulse-grid>); action-registry YAML schema + loader; session-log + findings query APIs; /pulse v1; /brief v1 (= ADR-125 Brief delivery, warp#945); /compose v1 with 5 starter actions; /canon v1 (grep + metadata, no RAG); /heed follows ADR-125 phasing.

Phase 5 — substrates + harder surfaces (4-6 weeks). Unified event stream; cross-manifest dep index; /trace v1 (timeline-only); /graph v1; /board v1 (KPIs from existing data, no cost ROI); lens parameter coordination on /board; /ramp per ADR-125 phasing.

Phase 6 — substrates that need real engineering (4-6 weeks). Agent cost ledger; RAG indexer + query API (ADR-116); /canon v2 (RAG-backed); /board v2 (ROI panel real); /trace v3 (causal-graph upgrade); /vie per ADR-125 phasing; persona-aware deep-link redirects for the five scheduled routes.

8. Coordination with ADR-125

ADR-125 owns Heed / Brief / Ramp / Vie as product surfaces and four substrates (user/role/area, channel-out, inference, signal-collection). This ADR does not duplicate any of that; it cites ADR-125 by number wherever a verb-route lands on Heed/Brief/Ramp/Vie. Specifically:

• /brief v1 in this ADR's Phase 4 is the ADR-125 Brief epic delivery (warp#945). Closing this ADR's /brief ticket closes the ADR-125 deferred status for Brief.
• /heed follows ADR-125's Phase 1 (substrate 1 + alert-kind) → Phase 7 (first-fire) sequence; this ADR adds the discovery layer (/heed is reachable from /pulse?lens=sre and /board "What needs your attention" panel).
• /ramp and /vie are ADR-125 deliverables; this ADR reserves their slots in the verb-route map but does not duplicate their phasing.

Tradeoffs / what we considered + rejected

Persona dropdown on a single home. Rejected — same shape as ADR-065 §2 rejected at the home layer. Adding a persona dropdown at the verb layer would force two-axes-per-URL and break shareability.

Five-persona route extension (add /review for Reviewer). Rejected — ADR-065's four-persona contract is load-bearing across ⌘K palette grouping, sidebar, and journey-cap discipline. Reviewer fits cleanly as a sub-journey of Dev with ?lens=reviewer on /canon and /trace.

Big-bang URL migration. Rejected — 95 routes audited, 90 preserved. Bookmark loss + redirect cost + agent-context loss across 40+ Markdown docs that cite specific routes. Additive verb-layer is the lowest-risk evolution.

Substrates-first, surfaces-second. Considered. Rejected — operator-facing value lands later; the cheap-surfaces-first ordering (/pulse, /brief, /canon v1, /compose v1) ships value in 3-4 weeks and earns the substrate work. Substrate-first would add 4-6 weeks before any operator sees benefit and increases the chance the substrate shape doesn't match real use.

Verb-route count > 9. Considered (/diff, /decide, /onboard, /audit). Rejected for v1 — every new verb-route adds a discovery surface to maintain. Nine fits the muscle-memory ceiling (⌘K palette + sidebar). Future ADRs may extend; this ADR is not the cap.

Replacing /operate / /infra mode homes. Rejected — ADR-058's five-mode contract is unchanged. /operate, /infra, /ship, /experiment, / remain as cross-cutting catalogues; verb-routes are entry primaries that route into them.

Auto-redirect noun-routes by persona. Considered (a Dev opening /operate gets redirected to /pulse?lens=dev). Rejected for v1 — too magic, breaks shareability, surprises users mid-bookmark. Phase 6 may revisit if telemetry shows persistent confusion.

Migration path

Five redirected noun-routes (Phase 5/6)

90 preserved noun-routes

Persona homes (/, /me, /ops, /team), mode homes (/ship, /operate, /infra, /experiment), per-mode sub-routes, per-project routes (/[project]/{build,deploys,docs,manifest,run,todos,tools} per ADR-059), catalogues (/projects, /platform, /playbooks, /pipelines, /experiments, /operators), per-thing detail (/platform/[project], /playbooks/[id], /pipelines/[name], /[buildID], /retro/[buildID]), search/discovery (/explore, /sitemap), docs (/docs, /docs/[...path], /docs/systems), tooling (/assets, /patches, /proxy, /retro), preview canvas (/dev, /dev/factory-preview/*, /dev/platform-preview/* — kept forever per ADR-006), restricted (/restricted, /restricted/[project]).

Full route table in docs/fleet/ai-frontend/docs/surfaces/00-overview.md "deep-link survival list".

Bookmark migration

No active bookmark migration in Phase 4-5. The five redirected routes ship 301s preserving query-string semantics. Phase 6 may add a one-time per-operator "your old bookmark X now lives at Y" toast (gated on user-identity from ADR-125 substrate 1).

Documentation cross-links

This ADR cross-links to:

• 8 surface specs (docs/fleet/ai-frontend/docs/surfaces/{00-overview,pulse,board,trace,compose,canon,graph}.md) — one per verb-route plus index
• 5 substrate specs (docs/fleet/ai-frontend/docs/substrates/{event-stream,dep-index,action-registry,cost-ledger,rag}.md) — one per substrate
• Updated journey docs (docs/fleet/ai-frontend/docs/journeys/{dev,sre,manager,owner}.md) — append "Verb-route shortcuts" section per persona
• New fleet-level personas doc (docs/fleet/personas.md) — single canonical fleet-wide persona reference

Consequences

Easier

• A user who knows the JTBD walks one verb-route URL to the answer; no 95-route translation tax.
• Persona × surface matrix is testable: each persona's red-routes (ADR-065 / journey docs) cite the verb-route they walk.
• Discovery layer is keyboard-first by default — every verb-route earns a ⌘K palette entry (per ADR-065 Nicety #2), grouped by persona.
• Substrates are exposed as first-class spec docs; engineering work is named and orderable across phases.
• Future verb-routes earn admission against the same matrix discipline (persona × JTBD × substrate dep × preview-canvas).

Harder

• Nine verb-routes to keep fresh + four persona homes + five mode homes = 18 living surfaces. ADR-065 already named "persona pages as living surfaces" as the maintenance contract; this ADR extends the contract to verb-routes. A /pulse showing 6-month-stale data is worse than no /pulse.
• The five redirects must preserve query-string semantics or break tooling links (gh CLI, Slack unfurls, dashboard cross-references).
• Substrate phasing dependencies (/canon v1 → v2 on RAG, /board v1 → v2 on cost ledger, /trace v1 → v3 on event-graph) require version-aware tests so an upgrade does not silently regress v1 contracts.
• Lens parameter is a new axis the design system must absorb consistently — every dashboard tile, list row, and timeline frame must know how to render in four lens projections.

What we sign up to maintain

• The nine verb-routes as living surfaces with the same maintenance bar ADR-065 set for persona homes.
• The five preserved-bookmark redirect contracts (query-string semantics carry through).
• The substrate spec documents as the engineering contract — when a substrate v2 lands, the spec doc is the diff target.
• The persona × surface matrix in §5 — every new surface earns admission against this matrix; the matrix is amended via ADR.
• The verb-route ⌘K palette entries (pulse, board, trace, compose, canon, graph, heed, brief, ramp, vie) as the keyboard-first contract.

Cross-references

• ADR-058 — five-mode platform UI. Modes preserved; verb-routes are the orthogonal entry layer.
• ADR-059 — project-first IA. Project axis preserved; verb-routes route into project-scoped views via ?project= query.
• ADR-062 — design system + component strategy. All new primitives ship in @gyrum-labs/gyrum-ui; verb-routes compose primitives.
• ADR-065 — persona-aware IA + niceties. The four personas + Reviewer-as-sub-journey are this ADR's persona contract.
• ADR-067 — playbooks unified primitive. /compose/<action> is the user surface for kind: action playbooks.
• ADR-070 — <PlaybookRunner> UI contract. /compose/<action> reuses this; does not re-implement.
• ADR-115 — principle-aware reviewers. /canon exposes the principles they cite.
• ADR-116 — RAG knowledge-base. /canon v2 substrate.
• ADR-117 — module guidelines. /canon exposes versioned guidelines per module type.
• ADR-125 — Heed/Brief/Ramp/Vie product surfaces + four substrates. This ADR is the discovery layer above ADR-125's product surfaces.
• ADR-006 — gyrum-ui as design canon. All new visual primitives ship there.

Surface specs (this PR)

• docs/fleet/ai-frontend/docs/surfaces/00-overview.md — verb-route map; persona × surface matrix; substrate dependency graph; deep-link survival list (90 noun-routes that stay)
• docs/fleet/ai-frontend/docs/surfaces/pulse.md — /pulse operational now
• docs/fleet/ai-frontend/docs/surfaces/board.md — /board strategic week→quarter
• docs/fleet/ai-frontend/docs/surfaces/trace.md — /trace?q=… causal timeline (v1) → graph (v3)
• docs/fleet/ai-frontend/docs/surfaces/compose.md — /compose/<action> declarative actions
• docs/fleet/ai-frontend/docs/surfaces/canon.md — /canon searchable principles + ADRs + guidelines
• docs/fleet/ai-frontend/docs/surfaces/graph.md — /graph service deps + blast radius

Substrate specs (this PR)

• docs/fleet/ai-frontend/docs/substrates/event-stream.md — unified event log (warp + GH + playbooks + sessions)
• docs/fleet/ai-frontend/docs/substrates/dep-index.md — cross-manifest dependency index
• docs/fleet/ai-frontend/docs/substrates/action-registry.md — YAML schema + loader contract
• docs/fleet/ai-frontend/docs/substrates/cost-ledger.md — per-PR / per-agent token-cost rollup
• docs/fleet/ai-frontend/docs/substrates/rag.md — RAG indexer + query API (ADR-116 substrate)

Open questions

1. /vie slot reserved but not delivered until Phase 6. ADR-125 owns the variant-comparison surface; this ADR holds the slot in the verb-map. If Phase 6 ordering shifts, the slot is renumbered; the URL is canon.
2. Reviewer as sub-journey vs new persona route. Operator-call settled in §1 — ADR-065's four-persona contract holds; Reviewer is ?lens=reviewer on Dev surfaces. Re-litigation requires an ADR-065 amendment.
3. CEO vs Owner emphasis in /board?lens=owner. Open. ADR-059 §8 homepage shape (current /) is Owner today; the question is whether /board?lens=owner replaces / or augments it. Plan recommends augment for v1 (add tiles + ROI panel + risk pyramid + agedness section to /); migrate fully in Phase 6 once telemetry validates.
4. Auto-detect lens from operator identity. Depends on ADR-125 substrate 1 (users table); Phase 4 can read the warp persona on first lens-default and fall back to Dev. Requires the warp /personas UI shipping (cross-link in delivery plan).

Followed by: Placeholder — a future ADR may amend the verb-route count, the lens-parameter axis, or the persona × surface matrix once telemetry from Phase 4-5 lands.