Spike GOV.UK Frontend integration

[kevinrapley]

Summary

Continues the GOV.UK Frontend integration spike.

This branch now uses GOV.UK Frontend for representative and registered service pages, restores shared x-include page chrome, keeps the ResearchOps home styling source-led from Sass, fixes preview asset paths, migrates the Project Dashboard route to the GOV.UK Frontend/Nunjucks model, hardens the Cloudflare Pages /api/* proxy, repairs Project Dashboard stage/status rendering, and restores the working main Mural integration behaviour with GOV.UK Frontend dashboard state hooks.

Key implemented changes

• GOV.UK Frontend is installed and built from src/styles/govuk.scss.
• $govuk-assets-path is set so compiled GOV.UK CSS points at /assets/govuk/assets/.
• ResearchOps home styling is sourced from src/styles/researchops-home.scss.
• Shared header and footer remain loaded through x-include.
• Route-specific CSS is preserved where still route-specific.
• The Project Dashboard now has a Nunjucks source at src/govuk/templates/pages/project-dashboard.njk and generated output at public/pages/project-dashboard/index.html.
• The Cloudflare Pages /api/* proxy now applies a bounded upstream timeout when forwarding preview route calls to the Worker.
• The Project Dashboard status-strip tags populate from loaded project data instead of remaining as static not recorded defaults.
• The Project Dashboard now tries the D1-first /api/projects?limit=200 list route before falling back to /api/projects/:id.
• The Project Dashboard Mural component now restores the working main verify, resolve, setup, await-link and open-board flow.
• The Mural component now updates GOV.UK Frontend dashboard state through #mural-account-state, #mural-board-state, #mural-summary-tag, and the separate #mural-open action.
• The passwordless preview Worker deploy workflow includes the Mural OAuth client secret in the preview secret availability check and bulk secret upload.

Project Dashboard model preserved

The migrated route preserves:

• project details
• project area links
• reflexive journal route
• Mural account and board actions
• stakeholder management
• objectives
• user groups
• participants
• studies
• insights and outcomes

The ResearchOps journal remains the system record. Mural is presented as linked visual support for teams that choose to use it.

D1-first dashboard data loading

The Project Dashboard controller now loads the project from /api/projects?limit=200 first. That route is the D1-first path and uses Airtable as the secondary source. The controller then matches the requested project against known identifiers and only falls back to /api/projects/:id if the D1-first list does not contain the project.

The dashboard script cache token is now project-dashboard-d1-first-20260526, and the Mural component cache token is now project-dashboard-mural-optional-20260526.

Restored Mural integration behaviour

The Mural component has been realigned with the working version on main and adapted to the GOV.UK Frontend dashboard markup.

It restores:

• pages.dev fallback to https://rops-api.digikev-kevin-rapley.workers.dev when no explicit API origin is supplied
• startup /api/health warm-up
• startup Mural verify and resolve checks once project metadata is present
• Connect Mural OAuth routing with a dashboard return path
• create-board setup with project record lookup by name when needed
• await-link polling after board creation
• cached board resolution for the dashboard and journal integration
• window.MuralIntegration.resolve() and window.MuralIntegration.getMuralIdForProject()

It adds GOV.UK Frontend support for:

• Mural account summary-list state
• Mural board summary-list state
• top-level Mural status tag
• the separate Open Mural board GOV.UK button/link

Mural OAuth diagnosis

The observed Mural page error was The redirect URL is invalid. That happens inside Mural before ResearchOps receives a callback. It means the redirect_uri advertised by the Worker is not in the Mural app's allowed redirect URL list.

The checked-in preview callback URI is:

https://rops-api-passwordless-preview.digikev-kevin-rapley.workers.dev/api/mural/callback

To complete the Mural OAuth fix for the passwordless preview Worker, one of these must happen outside the page controller:

1. Add that preview callback URI to the Mural app's allowed redirect URL list; or
2. Configure the preview Worker to advertise a callback URI that is already registered in Mural, and ensure that target Worker has the Mural OAuth secret and compatible token storage.

Restoring the working main fallback means the Pages preview can also use the production Worker path when no explicit API origin is supplied, matching the known working behaviour.

Guardrails and tests

Tests guard that:

• the Project Dashboard is generated from the Nunjucks source template
• shared x-include header and footer chrome remain in use
• legacy clone CSS is not loaded on the dashboard route
• invented dashboard concepts such as Add a project note and Setup checks do not return
• dynamic study rows keep GOV.UK-compatible markup
• the Pages proxy has a finite upstream timeout and diagnostic headers
• project service stage and project stage tags are populated from loaded project data
• the Mural component restores the working main flow, including pages.dev fallback, /api/health, verify, resolve, setup, await, and board opening
• the Mural component updates GOV.UK dashboard tags and the separate Open Mural board action
• the Mural idle state does not say Mural not checked

Trace artefacts

• docs/agent-audit/reasoning/2026/05/23/govuk-frontend-integration-main-merge.md
• docs/agent-audit/reasoning/2026/05/23/govuk-frontend-integration-main-merge.json
• docs/agent-audit/reasoning/2026/05/23/govuk-x-include-page-chrome.md
• docs/agent-audit/reasoning/2026/05/23/govuk-x-include-page-chrome.json
• docs/agent-audit/reasoning/2026/05/23/home-grid-styling-regression.md
• docs/agent-audit/reasoning/2026/05/23/home-grid-styling-regression.json
• docs/agent-audit/reasoning/2026/05/23/govuk-frontend-integration-test-remediation.md
• docs/agent-audit/reasoning/2026/05/23/govuk-frontend-integration-test-remediation.json
• docs/agent-audit/reasoning/2026/05/24/govuk-frontend-sass-output-and-service-chrome.md
• docs/agent-audit/reasoning/2026/05/24/govuk-frontend-sass-output-and-service-chrome.json
• docs/agent-audit/reasoning/2026/05/25/project-dashboard-govuk-frontend.md
• docs/agent-audit/reasoning/2026/05/25/project-dashboard-govuk-frontend.json
• docs/agent-audit/reasoning/2026/05/26/project-dashboard-pages-api-proxy-timeout.md
• docs/agent-audit/reasoning/2026/05/26/project-dashboard-pages-api-proxy-timeout.json
• docs/agent-audit/reasoning/2026/05/26/project-dashboard-mural-routing-and-status-labels.md
• docs/agent-audit/reasoning/2026/05/26/project-dashboard-mural-routing-and-status-labels.json
• docs/agent-audit/reasoning/2026/05/26/project-dashboard-d1-first-and-mural-oauth.md

Validation status

Latest checked head: dea86e3f9aeff7b21a921c0a907e9faffa5bdfa4.

Passing workflows on that head:

• CI
• Validate ResearchOps
• Release Gate
• Accessibility audit (pa11y-ci)
• qa-bdd
• Format pull request
• QA — Broken links (Lychee)
• Build and deploy agent documentation Pages
• Update GitHub bundle registry manifest

Known limitation

The Mural app redirect allow-list remains outside this repository change. If the passwordless preview Worker callback URI is not registered in Mural, Mural will continue to reject that specific OAuth callback before ResearchOps receives control.

The build path regenerates public/pages/project-dashboard/index.html from the Nunjucks template. If a deployment serves stale generated HTML without running the build, the dashboard should be redeployed after the build output is refreshed.

[cloudflare-workers-and-pages]

Deploying researchops with    Cloudflare Pages

Latest commit:	dea86e3
Status:	✅  Deploy successful!
Preview URL:	https://77f5c7ef.researchops.pages.dev
Branch Preview URL:	https://chore-govuk-frontend-integra.researchops.pages.dev

View logs