Roadmap¶

Last reviewed: 2026-08-21 against the current implementation and test suite, following clinician review of non-score escalation on 2026-08-11 and NHSE child-health representative feedback on 2026-08-05. Open findings from that review are recorded in bug-log.md.

Legend: [x] delivered, [~] implemented but incomplete, [ ] not started. Item codes are stable and must not be renumbered when priorities change.

Clinical correctness, safety evidence, and conformance take precedence over packaging and presentation work.

The immediate priority is requirements traceability and source-derived clinical fixtures. The current chart UI is clinically acceptable for this stage; a formal design baseline is deferred until later clinical review and should not delay component-contract or fixture work.

Completed Foundation¶

Chart UI Changes From Clinical Review¶

These are the granular changes requested in the 2026-08-05 clinical review. All are delivered except R41, which continues as a running quality pass, and R50, which is blocked externally on NHSE and cannot be progressed here.

R47 - Increase parameter-heading legibility. Chart parameter headings use 16px type in landscape and portrait layouts and 14px in the constrained mobile label column, increased from 14px, 13px, and 12px respectively. Wrapping, row height, truncation, and readability have been checked across every supported layout and at 200% browser zoom.
R48 - Replace the decorative age-band strip with a chart identifier. The toolbar shows the deterministically resolved visible age-band code in large text and the decorative coloured header strip has been removed. A visible window crossing a boundary shows both codes in chronological order, for example 1-4y → 5-12y.
R49 - Refine blood-pressure markers. Blood pressure uses small open inward-pointing arrow marks with their tips at the exact systolic and diastolic positions, joined by the required vertical line. The lighter marks replace the previous filled blocky triangles and conform to U11.5.
[~] R50 - Verify exact reference-chart colours. The component uses interim web-rendered screenshot samples: white #ffffff, yellow #fff8ae, orange #fcc88e, and pink #f9cbd7. Poppler renders the supplied PDFs differently, demonstrating that PDFs are not a normative RGB specification. Issue #5 assigns NHSE the action to supply authoritative screen values, print/screen intent, Human Factors provenance, and change governance; see implementation-notes.md.
R51 - Make the demographics bar optional. The separate assignable .options object exposes showDemographics, defaulting to true; only an explicit false hides the patient-identification header, and data reassignment preserves the setting. The demo provides a “Show demographics bar” checkbox.
R56 - Keep current patient and escalation status visible. The standard chart keeps the combined demographics and current-escalation block sticky while the observation chart scrolls, including when demographics are explicitly hidden.
R57 - Decouple demo playback from the chart time axis. The demo uses a timestamp-proportional slider that snaps to the nearest observation during drag and moves exactly one observation per arrow-key press. It starts at the latest observation and supplies only the selected observation plus its history to the unmodified chart component. The selected chart window ends at that simulated current observation; future observations are hidden; the old canvas-aligned overlay and chart-geometry coupling have been removed.
R58 - Keep the current PEWS status bar structurally stable. The sticky status always renders a neutral PEWS 0 state when no escalation is indicated, preventing playback layout jumps. Escalation source provenance sits at the right end of the main status line on supported widths, reducing banner height while remaining visible on narrow layouts.
R59 - Remove excess space below numeric plots. Numeric Canvas rows retain only the clearance required for minimum-axis labels and endpoint markers, reducing bottom padding from 28px to 8px so scoring bands end close to the row boundary.
[~] R41 - Complete the clinical UI quality pass. Apply the agreed changes coherently across realistic data, supported themes, and mobile/tablet/desktop layouts while preserving NHS chart fidelity and clinical semantics.

Stage 1 - Clinical Behaviour And Component Contract¶

Settle what the component calculates, accepts, displays, and deliberately excludes before freezing its API or generating broad evidence.

ED-PEWS source intake and development¶

Added 2026-11-10. See ed-pews.md for preliminary findings and implementation gates. The public default charts retain BP with explicit derogation scoring; this is not simply a row-removal change. No ED runtime support is claimed.

R63 - Preserve the four public ED charts with GCS. Exact downloaded PDFs, source URLs, publication labels and SHA-256 hashes are recorded in ../reference-sources/README.md, alongside the unchanged original inpatient references.
R64 - Reconcile ED requirements with the existing clinical specification. Obtain the current draft digital specification through authorised SPOT Futures access; compare both phases and all four age bands, numeric thresholds, BP derogations, neurological requirements and escalation. Record unresolved conflicts, review new inpatient references separately and resolve R53 with source-backed policy before implementing changed scoring.
R65 - Implement and verify an explicit ED clinical profile. Following R64, agree the profile/phase contract, reuse shared primitives rather than fork the renderer, add independent clinical fixtures and synthetic demo scenarios, preserve inpatient behaviour, and update traceability and hazard evidence. Include visual and clinical review; do not imply clinical release approval.
R66 - Establish reader documentation and a Zensical site. ../docs/index.md links authoritative specs and safety records. A pinned, hashed documentation-only toolchain, s/docs preview, generated scenario navigation with isolated demo frames, orphan/link checks in PR CI, and a combined Pages build serve Zensical at the site root. The standalone harness remains at /demo.html, the former single-chart root page is /single-chart.html, and old /docs/ HTML pages redirect while their download assets remain available.

Existing clinical-contract work¶

R10 - Complete non-score escalation triggers. Explicit CI, CQ, and SC decisions including None; automatic current-value AVPU, abnormal-pupil, sepsis, and septic-shock Specific Concern rules; non-escalating temperature warnings; unresolved raw-response semantics; provenance; and display across the banner, PEWS row, sticky footer, and demo playback are implemented. Clinician review on 2026-08-11 confirmed the current-value AVPU interpretation against the NHS England reference chart. See escalation.md and D18 in decisions.md.
R46 - Define clinical policy at age-band boundaries. The deterministic switch and explicit divider at the 1^st, 5^th, and 13^th birthdays are preserved without the C2.2 alternate-form override. The open research question, current behaviour, hazard implications, senior-discretion context, and governance route are documented in age-band-boundary-policy.md.
[~] R53 - Resolve PEWS scoring when blood pressure is unavailable in ED. The November 2026 public ED PDFs now provide explicit BP derogations scoring 0 or 4; see ed-pews.md. Verify digital codes, phase applicability and compatibility with the current scorer under R64 before implementing the policy. Do not rescale, change the starting value, infer no concern from missing BP or apply ED rules to inpatient scoring without source-backed guidance.
R20 - Decide which clinical configuration may be overridden. Define the governed boundary between canonical national defaults and any host-configurable clinical behaviour.
[~] R21 - Centralise escalation configuration. Presentation metadata is centralised, but score boundaries and non-score trigger policy are not yet represented by one canonical runtime structure.
[~] R22 - Complete respiratory-support handling. Known support codes are scored; configurable additions, national-code governance, and clinically useful device-change display remain incomplete.
R23 - Define typed presentation options. The separate assignable .options object now exposes showDemographics (boolean, default true), showValues (boolean, default true), initialLayout ('landscape' | 'portrait' | 'mobile' | 'auto', default 'auto'), and initialTimeWindow (positive number in hours, default 24). A JSDoc @typedef NpewsChartOptions documents the contract. The demo harness provides controls for all four. Options reassignment triggers a re-render and preserves the setting across data changes.
R24 - Define branding and explanatory-content extension points. Separate demo-owner branding, embedding-organisation branding, NHS identity approval, and host-supplied helper text.
[~] R9 - Add requirements traceability. The component critical-path matrix now records individual U* and C* allocation/evidence in requirements-traceability.md, and automated tests verify local Markdown links. Expand the matrix to every applicable U*, C*, and T* source requirement, including host, deployment, supplier, and deliberate-exclusion allocation.
R11 - Expand source-derived scorer vectors. test/scoring/scorer-source-vectors.test.js enumerates vectors from the canonical JSON and exercises the scorer itself, rather than re-checking the generator as config-matches-spec.test.js does. It covers every age band and numeric parameter at each band's lower bound, upper bound, interior and both sides of every transition, plus field isolation, respiratory-distress and capillary-refill categories, high-flow override, level devices in both delivery units, total summation, temperature/AVPU exclusion, and the escalation thresholds. Fallback paths through scoreFromBands and scoreOxygen are pinned as characterisation tests; the behaviour they record is not endorsed and is raised as B-01-B-06 in bug-log.md.

Stage 2 - Reproducible Development And Test Fixtures¶

Prepare stable inputs and repeatable tooling before building browser and screenshot gates.

[~] R40 - Make the local development experience reliable. A clean checkout needs one documented setup path, reproducible locked serving dependencies, useful startup errors, automatic browser opening, and straightforward test and scoring-generation commands.
R12 - Add general CI. .github/workflows/ci.yml runs npm ci, npm test, and npm run generate:scoring:check on every push to main and on pull requests, plus REUSE licence compliance via fsfe/reuse-action and GitHub Actions security scanning via zizmor. Action SHAs are pinned with # vX.Y.Z comments per house style. Dependabot now also tracks github-actions updates.
[~] R5 - Maintain clinical review scenarios. All age bands and major trajectories are represented, but clinical plausibility, expected outcomes, named edge cases, and reuse as automated fixtures remain incomplete.
[~] R36 - Complete named edge-case scenarios. Add dedicated skipped-observation, oxygen-transition, missing-data, sparse-ED, and non-score-trigger cases with explicit expected behaviour.
[~] R43 - Establish reusable synthetic test patients. Use the aggregate archetype strategy in patient-derived-data-assessment.md, review fixtures for clinical plausibility, document expected scores and escalation outcomes, and never publish lightly perturbed patient-derived records.
R19 - Reuse scenarios as automated fixtures. Import the scenario catalogue into browser and regression checks instead of maintaining separate test data.

Stage 3 - Browser, Accessibility, And Visual Evidence¶

Begin this stage after R54 so screenshot baselines protect an agreed design rather than freezing known defects.

R14 - Establish accessible rendering. Ensure Canvas colour lookup reads from the effective component scope and rendering meets WCAG 2.2 AA contrast and target-size requirements; add automated browser assertions.
R15 - Add browser interaction tests. Cover initial render, repeated .data assignment, scenario switching, connect/disconnect cycles, controls, layout locking, empty and malformed input, keyboard use, and 200% browser zoom.
R16 - Establish deterministic visual-regression infrastructure. Add Playwright with controlled fonts, timezone, data, viewport, and device scale without Storybook or a hosted visual-testing service; see the Visual Regression Testing Plan.
R17 - Approve the visual baseline matrix. Capture all age bands, landscape/portrait/mobile layouts, supported themes, birthday crossing, skipped values, oxygen-modality changes, sparse observations, and non-score triggers against the NHS reference chart.
R18 - Add visual CI and change governance. Run browser checks on pull requests and document who approves intentional clinical visual changes and baseline updates.
R55 - Verify observation-chart rendering. Use R14-R19 to provide browser and Canvas regression evidence for the behaviour delivered under R3: proportional spacing, exact points, trend continuity, skip and modality breaks, birthday transitions, PEWS totals, escalation presentation, fixed time windows, and responsive layouts.

Stage 4 - Web Component Hardening¶

Harden the component after browser evidence can detect lifecycle, isolation, and visual regressions.

R25 - Add Shadow DOM isolation. Scope rendering, styles, DOM lookup, and custom-property reads to the component root.
R26 - Support multiple simultaneous instances. Replace fixed ids and module-global renderer/view state with per-instance state.
R27 - Complete component lifecycle cleanup. Bind and release resize and control listeners per instance, preserving state deliberately across updates.
R28 - Publish generated consumer types. Provide consistent PatientObject and ObservationObject JSDoc and .d.ts declarations.

See the Web Component Phase 2 Specification for detailed acceptance criteria.

Stage 5 - Clinical Review And Interoperability¶

R54 - Approve the chart UI design baseline. At a later clinical-review point, review R47-R51 and R56-R59 against the authoritative NHS references, resolve remaining visual feedback, record the review outcome, and decide whether the UI is stable enough for deterministic screenshot baselines. This is a design gate, not a claim of formal clinical release approval.
R34 - Show raw inputs and computed results together. Add a review table beside the demo chart for observation values, skipped reasons, component scores, total PEWS, escalation level, and trigger provenance.
R35 - Add side-by-side age-band comparison. Provide a clinical review view for comparing threshold and rendering differences without implying manual age-band selection.
[~] R6 - Maintain the FHIR adapter. Bidirectional conversion and current conformance fixtures are tested, but reverse round trips, national coding decisions, trigger mapping, and strict profile validation remain open.
R37 - Complete FHIR reverse round-trip coverage. Resolve outstanding FHIR -> chart -> FHIR cases for resources, scores, modality changes, skip reasons, and trigger provenance.
R38 - Resolve FHIR coding and validation scope. Determine how EPR and FHIR models represent Clinical Intuition, Carer Question, Specific Concern, selected escalation level, and provenance; decide canonical national codes and add strict FHIR R4 and UK Core validation where required.
R39 - Add SMART-on-FHIR conformance coverage. Test the adapter and component contract in a representative SMART host after the API is stable.
R61 - Return the chart version to the originating server in SMART-on-FHIR. Investigated and currently blocked: the SMART shell is deliberately read-only (patient/*.read), so it cannot write a Provenance resource - the standards-based way to record which component version produced a view - without a write-scope grant most EHR deployments will not give a viewer app, plus its own safety and governance review. A custom X-Npews-Chart-Version request header was tried as a scope-free alternative and confirmed, by running the local SMART sandbox end-to-end, to break reads: any non-simple header turns a plain GET into a CORS preflight, and an unconfigured FHIR server (as represented by the sandbox's HAPI instance) rejects it outright. No channel is currently known to work without either the write-scope decision or prior EHR-specific CORS coordination; see the appendix note in fhir.md.
R42 - Register the SMART app with Oracle Health code Console. The process is researched and documented in oracle-cerner-registration.md: create a CernerCare account, register a Provider-type app in code Console against R4 with explicit non-wildcard scopes (smart/launch.html now requests these correctly - Oracle's authorisation server rejects patient/*.read), then test against Oracle's shared sandbox. Registration is independent of GESH and gives an app ID/client ID immediately; going live at GESH is a separate, GESH-initiated Service Request (see the doc) that this roadmap item does not cover. Record account/credential ownership outside this repository.

Stage 6 - Distribution And Clinical Release Readiness¶

Distribution starts only after the component API and instance model are stable. Clinical deployment additionally requires the independent safety work in R52.

R29 - Prepare publishable package metadata and exports. Remove private-only packaging once the API is ready and define supported entry points.
R30 - Add a distribution-only ESM and browser bundle. Keep chart/ runnable as native modules while producing package/CDN artifacts separately.
R31 - Generate Subresource Integrity metadata. Produce and document SHA-384 integrity values for browser artifacts.
R32 - Test real package consumers. Verify package and CDN use from plain HTML and representative framework wrappers.
[~] R33 - Define the release process and support policy. releases.md defines 0.x development versioning, a single s/version++ command including guarded first publication of the existing version, git-cliff changelog and a tested CI auto-tag/source-prerelease cascade targeting OHTF. The first authorised snapshot is 0.1.0. Published packages/bundles, CDN URLs, long-term support/deprecation commitments and clinical release gates remain outstanding; complete them with R29-R32 and R52.
R62 - Add the release commit hash to the version display. Extend R60's toolbar version marker so it also shows the short git commit hash the running build was released from, letting a bug report pin the exact commit rather than only the semver. Because chart/ loads as native ES modules with no build step, the hash cannot be read from git at runtime - it has to be written into chart/version.js (alongside CHART_VERSION) at release time. Blocked on R33: do this once s/version++-equivalent release tooling exists (conventional commits, a generated CHANGELOG.md, one release command per house-style distribution.md) to write the hash automatically as part of the release commit and keep it in sync; hand-maintaining a second value alongside CHART_VERSION before then would just add a new drift risk. Keep the marker unobtrusive - small, muted text, consistent with R60's current top-right toolbar placement.
R52 - Complete formal clinical safety assurance before clinical release. Appoint a competent Clinical Safety Officer, determine manufacturer/supplier and regulatory roles, agree a risk method, conduct a multidisciplinary hazard workshop, review control effectiveness, accept or transfer residual risks, define release gates, and create the required Tier 2 hazard log, safety case, and safety plan.

House-Style Audit¶

Audit date: 2026-09-30. Standards reviewed: agents.md, new-repos.md, ci.md, licensing.md, security.md, scripts.md, dependencies.md, commits.md, specs.md, clinical-safety.md, repo-presentation.md, ui.md, testing.md. Not applicable: docs.md (no docs site), skills.md, tauri-gui.md, rust-cli.md, presentations.md, mcp.md. library-extraction.md/distribution.md are deliberately deferred by R29-R33, not a current gap.

The repository's strongest compliant patterns: LGPL-3.0-or-later with SPDX headers and a REUSE.toml that keeps the project at 117/117 REUSE-compliant files; .github/workflows/ci.yml running tests, REUSE compliance, and zizmor with every action SHA-pinned and version-commented; Dependabot grouping and cooldown for both npm and github-actions; a disciplined spec/roadmap.md with a stable R<n> code scheme and a checkbox legend; a root SAFETY.md with a populated hazard table; and .env / patient-derived data correctly excluded from version control.

P1 - Safety, Supply Chain, Release, And CI¶

HS-1 - Protect the main branch. gh api repos/rcpch/digital-pews/branches/main/protection returns 404 - no branch protection exists despite ci.yml now providing a real required-check candidate. house-style ci.md sets a Solo-tier baseline (require the CI check, block force pushes and branch deletion) as the minimum for every repository, and this one has accepted external contributor PRs (rlnet-a11y, mbarton forks), which pushes it toward the Public tier (PRs, one independent approval, CODEOWNERS for high-risk paths). Done when at least the Solo baseline is configured and a deliberate tier decision is recorded here or in AGENTS.md.
HS-2 - Record a structured medical-device applicability assessment. SAFETY.md states in prose that "no ... regulatory assessment has been completed" (line 37) and lists it as future CSO work, but does not carry the dated minimal record clinical-safety.md prescribes: decision-maker and role, decision date, next review date, evidence considered, conclusion, actions/owner, and reassessment triggers. Done when SAFETY.md (or a linked MEDICAL-DEVICE-ASSESSMENT.md) has that record, even if the recorded conclusion is "further advice required."

P2 - Workflow And Standards Gaps¶

HS-3 - Add s/test (and s/lint if a linter is adopted). s/ currently has only up and down; AGENTS.md's Workflow section tells contributors to run npm test and npm run generate:scoring:check directly rather than through a canonical s/ verb, so ls s/ does not show the full set of repeated processes as house-style scripts.md intends. Done when s/test wraps both commands and AGENTS.md references it.
HS-4 - Add .editorconfig. Listed as a new-repo minimum file in new-repos.md; absent from the repo root.
HS-5 - Enable "Automatically delete head branches". gh repo view --json deleteBranchOnMerge reports false. House-style commits.md recommends enabling it so merged PR branches (dependabot and contributor) are cleaned up without a manual --delete-branch on every merge.
HS-6 - Complete the agent-artefact .gitignore block. The current block only covers .playwright-mcp/ and a repo-specific test-output/screenshots/; agents.md's minimum block also lists .playwright/, playwright-report/, blob-report/, test-results/, and .claude/. Add the missing entries so a future tool's scratch directory does not silently fail reuse lint.

P3 - Polish And Consistency¶

HS-7 - Add a hero screenshot and CI/licence badges to README.md. The README has no image of the running chart and no badges. Both are now cheap and genuinely informative: ci.yml gives a real CI badge and LICENSE gives a real licence badge, and a screenshot directly serves house-style repo-presentation.md's "show, do not tell" principle for a visual clinical-charting product.
HS-8 - Fix or remove the dead test-output/VISUAL_COMPARISON.md reference. README.md's "Visual reference" section (line 159) points at a file that does not exist in the repository.
HS-9 - Add CODE_OF_CONDUCT.md and a PR template. new-repos.md recommends both once a project is collaborative or public; this repo is public and has merged external contributor PRs, but has neither.
HS-10 - State the git workflow and branch-protection tier in AGENTS.md. agents.md's "Required content" asks every agent-instructions file to state whether agents commit directly to main or use a branch+PR, and to name protected paths/environments. AGENTS.md currently covers "Approval Required" but not this.

Deliberate exceptions and non-findings¶

Reference images and PDFs are intentionally licensed as RCPCH-copyrighted redistributions of NHS England material rather than left unannotated; this is already correct in REUSE.toml and does not need a separate finding.
docs.md (Zensical/MkDocs docs-site conventions) does not apply: this repository has no docs site, only the demo harness and spec/ Markdown.
Formal browser/visual-regression evidence (ui.md's verification checklist) is already tracked in depth by roadmap R14-R19 and R55; this audit does not duplicate those items.