Skip to content
View in Notion

PPP Roadmap ​

Feature Overview ​

Short- and long-term view of what a doctor needs to achieve. Surfaces predetermined learning objectives as a timeline of SMART goals, compartmentalising a large dataset of compliance requirements into small achievable steps so the clinician is not overwhelmed. Renders as Section 3 of the PPP Dashboard; also accessible as a standalone page. Matt's explicit purpose: "deload the clinician" — Roadmap is about cognitive load reduction, not just compliance tracking.

Core idea ​

Roadmap is a projection of existing PPP activity onto a timeline, not a separate data store. Every milestone resolves to an existing activity type (WBA, Appraisal, Retrospective entry, Logbook case). Completion signal is already captured in the system — the Roadmap just aggregates and sequences.

Three milestone sources ​

SourcePopulated fromExamples
Cadence MeterWBA cadence rules + Appraisal cycle"Submit MCR by 30 June"
Enterprise-setHospital / training-body pathways attached to user's org"Complete AMC PGY1 by end of Year 1"
SMART GoalsUser-authored"Complete 50 laparoscopic appendicectomies by Jun 2026"
Source ​
  • Matt's PPP Road Map Notion brief — sub-page of PPP Dashboard
  • 22 Apr 2026 Catchup transcript — Matt flagged national-framework auto-prefill as a separate (QLD-Health-adjacent) build
  • 28 Jun 2026 update of the same Notion page (now titled "PPP Road Map / Yearly Appraisal / Compliance Runner ie What's Up Next", last edited 2026-07-01). Matt bundles Roadmap, Yearly Appraisal and "What's Up Next" into one work thread "due to the cross over and belief they should be build together and with each in mind". He walked through it live in the 2026-07-01 Dev Session (~00:40:26–00:58:18). Task issue: #11144. The Yearly Appraisal part is in appraisals-wba.md. "What's Up Next" is the renamed "This Year's Compliance" runner, owned by dashboard.md dashboard.compliance-snapshot (see the Widget note).
  • Re-ingested 2026-04-28 against #5325 — content from the Notion brief is already absorbed in this spec (intent, three milestone sources, UK ePortfolio reference, ternary states, alternating-row layout) and in roadmap-national-frameworks.md (AMC PGY1/PGY2 deep-dive). New material since 22 Apr captured under Delivery Horizons below

Open Questions ​

#QuestionProposed answer / statusRef
Q1Include surgical / practical logbook volume targets in Roadmap v1?RE-OPENED → now an active AC (Rob, 2026-05-27, #7641). Original closed resolution (2026-05-06): "Deferred — Roadmap v1 ships without logbook volume targets ... re-open when surgical-training-pathway customers enter the pipeline." CONTRADICT: Matt asked for it on #7298 26 May ("surgical numbers of a certain period to reach total goal"), so the defer is reversed — built via the existing SMART-goal tiedTo: { feature: 'logbook' } mechanism as a surgical_volume goal (see § Multi-year horizon + surgical cumulative-volume goals).#7641
Q2Enterprise pathways — who authors the templates (engineering vs Admin UX)?Proposed: Admin UX authors via a Super Admin / Hospital Admin "Pathway Builder" surface — engineering ships the data model + builder UI, content is enterprise-owned. Defers content authoring out of engineering's critical path. Awaiting Matt sign-off before turning into an AC.Notion 17 Apr
Q6PGY1 → PGY2 transition: auto-re-seed the roadmap, or prompt the user?Proposed: prompt the user with a one-click "Apply PGY2 preset" CTA on first login post-transition; never auto-overwrite user edits. Mirrors SMART-goal authorship ergonomics. Awaiting confirmation.AMC deep-dive
Q7Preset editability — is the preset read-only (health-service-owned) or user-editable?Proposed: preset rows are read-only; user-added milestones live alongside preset rows in the same timeline but are tagged source: smart-goal. Keeps the compliance contract clean while preserving user agency. Awaiting confirmation.AMC deep-dive
Q9Should CPD be excluded from the Roadmap and left to the CPD Home surface?RESOLVED — design #8167 (2026-06-17). CPD is delegated to CPD Home; the Roadmap surfaces only a single summary "Complete annual CPD audit" milestone (status derived from CPD Home's aggregated hours, deep-links there) — no duplicate activity tracking, preserving the deload principle. Reuses tiedTo.feature:'cpd'; no schema change. Original steer — Matt: "possibly we leave CPD just for the CPD home part" (#7298 26 May).†#7298 #7641
Q10Amalgamate annual reflection / PDP (as SMART goals) with the yearly appraisal?RESOLVED — design #8167 (2026-06-17). Linked lifecycle, not merged: SMART goals (annual reflection / PDP) live on the Roadmap year-round and evolve freely; the yearly Appraisal imports the currently-active goals as a point-in-time PDP section at review, and exports any supervisor-endorsed goals back to the Roadmap on sign-off. Keeps the signed Appraisal legally stable (locked archive) while preserving organic goal-setting. Reuses ppp_smart_goals + import/export logic in appraisalWorkflowService; no new table. Original steer — Matt: "...amalgamate with yearly appraisal so maybe thats how we work it" (#7298 26 May).†#7298 #7641
Q12Is the personal Roadmap separate from the Enterprise Framework Roadmaps (e.g. National Prevocational Pathway)?RESOLVED — design #8167 (2026-06-17). Unified instantiation, not separate: one personal Roadmap = framework base layer (AMC PGY1 / enterprise presets) + user SMART goals + cadence milestones on a single timeline, each tagged by source chip. Enterprise governance is delivered via filtered views (`source: enterpriseamc-*), not a second roadmap artefact. A doctor has one career timeline; parallel roadmaps double cognitive load. Existing RoadmapMilestone` already supports multiple sources — additive, no new tables. See roadmap-national-frameworks.md. Original steer — Matt: "Will this be separate to the Enterprise Framework Roadmaps" (#7298 26 May).†
Q13AMC prevocational like-for-like: which AMC requirements map onto existing PPP features, and which need new builds? Matt asked both sides to do this on #9667 (2026-06-28). He would "read AMC prevocational framework again and decide on elements that are like for like with our system already", and Rob would draft the same with AI. Rob posted a first-pass draft on #9667 (2026-07-07). It notes that the three AMC PDFs were not extracted. No Matt decision on the mapping has been found since.OPEN — awaiting Matt. Needed before ppp-roadmap.amc.map-to-existing-features can be built. Matt made the pathway the top roadmap priority on 2026-09-22.†#9667 #11144
Closed Questions (3) — click to expand
#QuestionResolutionRef
Q8Enterprise linkage — confirm the schema field used to attach a user to an enterprise (candidate: enterpriseId on users table). Needed to render the Enterprise Objectives panel.Resolved (Rob, 2026-05-19, #5523). There is no enterpriseId (or tenantId/organisationId) column on the users table in packages-shared/ppp/src/schema-groups/users.ts — and none is needed. Enterprise linkage already exists as a many-to-many junction: ppp_hospital (the enterprise account: id, name, slug, subscriptionTier, status) ↔ ppp_hospital_membership (userId → hospitalId, role ∈ executive_admin/hospital_admin/doctor, status ∈ pending/active/rejected/removed; unique on (userId, hospitalId)). A doctor can belong to multiple hospital enterprises, so a single scalar enterpriseId column would be architecturally wrong. Query path for "get enterprise pathway preset for user X": SELECT hospital_id FROM ppp_hospital_membership_view WHERE user_id = X AND status = 'active' → join ppp_hospital_view for subscription_tier/slug → resolve the matching RoadmapPreset where source = 'enterprise'. No migration required (CLAUDE.md pitfall #10 — no schema change added). Unblocks #5998.#5523
Q5EPA entrustability ladder — how is it implemented as a real feature (data source, verified rung labels, gating)?Resolved 2026-06-10 — re-mounted on verified seed (#8276). Path: demo (#5522) → removed from UAT for being static (#8433) → framework verified + seeded (#8277) → live re-mount (#8276). The EpaLadder is re-wired to ppp.roadmap.getEpaLadder and driven by seeded epa_assessment data (not component constants), gated to PGY1/2 AU doctors (resolveEpaFramework → visible:false otherwise, so the component renders nothing for every consultant). It shows the verified four EPAs on a three-rung scale (direct/proximal/minimal), latest awarded rung + progress to the per-EPA assessment minima ("X / Y assessments") — no pass/fail. Verified against the seeded fixture (4 EPA cards; epa-1 4/4 latest minimal; epa-3 2/2). See AC ppp-roadmap.epa-ladder.†#8276 #5522
Q11Roadmap shape — Notion hub-and-spoke vs timeline?Resolved 2026-06-03 — timeline confirmed. The timeline Roadmap (live RoadmapMilestoneTimeline on PPPDashboard, with the What's-Next banner) was shown at the investor demo and stays as the accepted shape; the Notion hub-and-spoke alternative is not pursued. Matt: "The notion shows a hub and spoke style but I like the time line" (#7298 26 May), confirmed post-demo (Rob, 2026-06-03 — "what we have for the roadmap stays").†#7298 #7641
Delivery Horizons ​

Engineering view of Matt's roadmap. Horizons reflect what's on the floor today (Now), what's queued behind the Q-Health demo (Next), and what's parked until those are proven (Later). Each item resolves to an existing spec or a tracked GitHub issue.

Now — in flight against the Q-Health demo ​

DeliverableSpecTracking
PPP Roadmap as Section 3 of PPP Dashboard (no time-filter on widget)dashboard.md, this spec#5350, #5356
Three-source milestone model (Cadence Meter / Enterprise / SMART goal)this spec#5356
UK ePortfolio milestone language + ternary states + alternating rowsthis spec#5356
AMC PGY1 / PGY2 preset (research + structural encoding)roadmap-national-frameworks.mdresearch pre-req on that spec
What's-Next banner + Appraisal-date prompt card on the Roadmap surfacethis specalready built in PPPDashboard

Next — after the Q-Health demo lands ​

DeliverableSpec
AMC PGY1/PGY2 auto-prefill on signup ({ pgyYear, country } → preset milestones). Top roadmap priority once baseline infrastructure works (Matt, 2026-09-22 — see Q13)roadmap-national-frameworks.md
Enterprise pathway overlays (QLD Health pathway authoring)this spec, roadmap-national-frameworks.md
Entrustability rating ladder visualisation on Roadmap (Q5)this spec — #5522
Enterprise schema linkage confirmation (Q8) ✅ Resolved — no enterpriseId column; ppp_hospital_membership junction confirms linkagethis spec
Compliance percentage rolled up to organisational dashboardorganisational-dashboard.md

Later — parked until Now/Next is proven ​

DeliverableNotes
Specialty college training programmes (RACS, RACP, RANZCOG SET) presetsPhase 2 — see roadmap-national-frameworks.md Out-of-scope
UK Foundation Programme / IMT presetMirror AU model once that's proven
Framework versioning with effective dates + per-doctor version pinningroadmap-national-frameworks.md
Wellbeing standard integration into Roadmap (Pulse/WHO-5 inline indicator)wellness.md, dashboard.md
MTS (Medical Training Survey) external-data overlayNew build — research not started
Original Vision — UK ePortfolio reference ​

Matt's Notion embeds a UK ePortfolio screenshot (Dr Matthew Randell, North Hampshire Hospital, Curriculum 2021, 03 Sept 2025 – 03 Mar 2026) as the target shape. Layout observed:

                                              [Training History] [My Learning Agreements]
 Progress Summary | Comments

Curriculum 2021 — transitioned 5th October 2024

                    ● MCR              ● MCR               ○ LA Final
                    (mid-point)        (final)             review meeting
                       │                  │                    │
    ●────────●─────────●─────────●────────●─────────●─────────●───── (locked future)
    Select/    LA                 Self-      LA Mid-       Self-
    Edit       Objective-         assess     point         assess
    Lead CS    setting            (mid)      review        (final)
                meeting                       meeting

Milestone types observed, and their PPP equivalents:

UK milestonePPP feature
Select / Edit Lead CSProfile — supervisor assignment
LA Objective-setting meetingNew — roadmap preset kick-off
Self-assessment (mid / final)Retrospective — reflection
LA Mid / Final review meetingAppraisals
MCR (mid / final)Appraisals — MCR

Three states (UK convention to preserve) ​

  • Completed — solid dark-navy circle + white ✓
  • Current / active — outlined navy with chevron arrow
  • Future / locked — grey + padlock icon

Layout density pattern ​

Horizontal timeline with alternating rows (above/below the line). Keeps readability at milestone-dense training periods without shrinking nodes. Period scope = one training period (6 months) per view — zoom out for longer horizons.

Data Model ​
ts
// A preset (AMC PGY1, RACS SET, Qhealth pathway, etc.) — a canned set of
// milestones that applies to a profile match.
interface RoadmapPreset {
  id: 'amc-pgy1' | 'amc-pgy2' | 'racs-set' | 'enterprise-qhealth-pgy1' | ...
  displayName: string
  jurisdiction: 'AU' | 'NZ' | 'UK' | ...
  source: 'national-framework' | 'enterprise' | 'user-smart-goal'
  appliesToProfile: (p: UserProfile) => boolean  // e.g. pgyYear === 1 && country === 'AU'
  milestones: RoadmapMilestone[]
}

// A single step on the timeline. Resolves to an existing PPP activity type
// where possible — never invents completion semantics.
interface RoadmapMilestone {
  id: number
  title: string                                  // "Submit MCR by 30 June"
  dueDate: Date
  userSetDate?: Date                             // nullable — user can move it within guardrails
  horizonMonths: number                          // 3 | 6 | 12 | 36 | 60 — for horizon tab filtering; 36 (3 yr) / 60 (5 yr) added for multi-year training-programme + overall-goal views (#7641)
  source: 'cadence-meter' | 'enterprise' | 'amc-pgy1' | 'amc-pgy2' | 'smart-goal'
  tiedTo?: {                                     // Projection onto existing PPP feature
    feature: 'wba' | 'appraisal' | 'retrospective' | 'logbook' | 'cpd' | 'profile'
    activityType?: string                        // e.g. 'mcr' for appraisals
    recordId?: number                            // once user creates the record, this links back
  }
  status: 'completed' | 'current' | 'overdue' | 'future' | 'locked'
  evidenceRequirements?: string[]                // ['record_of_learning_entry', 'supervisor_signoff']
}

// A training period grouping — matches the UK "Learning Agreement" concept.
// Groups milestones by rotation / ST year / PGY period.
interface LearningAgreementPeriod {
  id: number
  label: string                                  // "PGY1 — Term 2, General Surgery, Sept 2025 – Mar 2026"
  start: Date
  end: Date
  hospital?: string
  leadClinicalSupervisorId?: number
  milestones: RoadmapMilestone[]
}

// SMART goal — user-authored; fully expands to a milestone
interface SmartGoal {
  id: number
  userId: number
  title: string
  specific: string
  measurable: string
  achievable: string
  relevant: string
  timeBound: Date
  tiedTo?: RoadmapMilestone['tiedTo']
  status: 'active' | 'complete' | 'abandoned'
  // Surgical cumulative-volume goal (#7641): N cases of a category over a period.
  // Built on the existing tiedTo:{feature:'logbook'} mechanism — progress reads
  // logbook case counts, never a parallel store.
  goalType?: 'standard' | 'surgical_volume'      // default 'standard'
  targetCount?: number                            // e.g. 50 — required when goalType === 'surgical_volume'
  periodStart?: Date                              // cumulative window start; progress counts cases in [periodStart, timeBound]
}

Key invariants:

  • Milestone status is derived, not stored. Compute from: due-date vs now + tiedTo.recordId existence + record's own status.
  • Roadmap service has no write path for activity completion — completion signals come from feature tables (WBAs, appraisals, etc.). The roadmap only stores milestone definitions and due-date overrides.
  • User can add / remove / defer milestones but cannot falsify completion — only the source feature can mark complete.

Acceptance Criteria ​

Widget — Dashboard Section 3 ​

  • ✅ Renders as Section 3 of PPP Dashboard
  • ⏳ No time-filter toggle on the Roadmap widget (Matt 22 Apr)
  • ✅ "What's Next" banner surfaces the single most overdue / upcoming milestone with a direct action button — wired to live getDashboard.nextAction; the Open button deep-links by milestone type via MILESTONE_ROUTE_MAP, and the banner self-hides when no milestone is pending (no longer a hardcoded mock) (#7349). On the mobile app the Open button routes to the matching native tab via the navigateToTabs bridge instead of web navigation, so the native tab bar stays in sync (#7374)
    • Not the same as "What's Up Next": this banner shows one milestone. "What's Up Next" is the month-by-month runner that sits above the Roadmap, now titled "What's Up Next" (dashboard.compliance-snapshot, dashboard.md). Matt renamed it on 2026-06-28/07-01, said it should show a 3-month outlook on 2026-09-21, and described its layout as a horizontal runner in strict chronological order. Those requirements belong to dashboard.md and were handed over on #12720.†
  • ⏳ Appraisal-date-prompt card surfaces when user has no appraisal date set
  • ✅ Horizontal milestone timeline: ternary states (completed / current pulsing / future) — wired to live getMilestones (#5996)
  • ✅ Alternating-row (zigzag) layout for dense periods (#5996)
  • ✅ "Refresh suggestions" button re-computes preset milestones from current profile/cadence state (built on the dashboard Roadmap timeline, Task #11144; the 3 mo / 6 mo / 12 mo / 3 yr / 5 yr horizon toggle is built beside it). Enterprise and AMC source chips are not built: those sources have no milestone-source value yet
  • ⏳ Feedback icon (prototype-only)

Roadmap inputs & AMC mapping (28 Jun 2026 Notion update) ​

  • ⚠️ ppp-roadmap.inputs.cadence-all-types — (#12740 built: MCR/MSF/360 due dates with source cadence_meter, a yearly-appraisal milestone for this and next year, and the surgical-case target at the CCT date or 5 years out. Still ⚠️ until the onboarding confirm step for the pre-filled defaults ships, #12729.) The Roadmap is fed by the cadence meter for every input type Matt listed. Appraisal inputs are MCR, MSF and 360 at their cadence due dates, plus a yearly appraisal every roadmap year. Clinical inputs are surgical cases and the four WBA types. Defaults are pre-entered and the doctor confirms them during setup. The default values themselves are owned elsewhere: WBA/appraisal defaults by wba.cadence.default-values in appraisals-wba.md, and surgical-case defaults (specialty sign-off totals over a 5-year default denominator) by onboarding.md.††† Drift: the milestone engine (milestone-engine.ts WBA_CADENCE_MAP) only generates CBD/CEX/PBA/SSA cadence milestones. The yearly appraisal appears only as an appraisal_meeting taken from an existing appraisal record. MCR/MSF/360 and the surgical-case cadence never reach the timeline (#12740). This extends the WBA-only Cadence Meter ACs below and does not replace them.
  • ⏳ ppp-roadmap.amc.map-to-existing-features — the extra assessment requirements in the AMC prevocational framework are mapped onto features PPP already has (MCR, MSF, 360, or a WBA, with tweaks where needed) rather than built as new assessment types, so a PGY1/PGY2 roadmap gets "that level of fidelity" from existing features.†† Which requirement maps to which feature is Q13. This is the top roadmap priority once baseline infrastructure works (Matt, 2026-09-22). Preset storage and auto-prefill stay in roadmap-national-frameworks.md.†

Three sub-panels below timeline ​

  • ✅ Enterprise Objectives — read-only list from user's org pathway (#5998). AC id ppp-roadmap.enterprise-objectives: panel renders only when the user has an active ppp_hospital_membership (Q8 #5523); each objective shows title, category, due date and a derived completion state (completed / in-progress / not-started); objectives are read-only; panel is hidden (not empty) when no enterprise pathway exists. Note (Q2 still open): the org-pathway template/authoring data model is unconfirmed, so objectives are currently derived from the user's milestone-engine-sourced roadmap milestones rather than a dedicated preset table — the resolution query is a single seam to swap once Q2 lands. No schema migration added (CLAUDE.md pitfall #10).
  • ⏳ SMART Goals — user-editable list
  • ⏳ (Deferred) Cadence Meter surfaces inline on timeline nodes, not a separate panel

EPA entrustability ladder (live, gated) ​

  • ✅ AC id ppp-roadmap.epa-ladder (#8276): the EPA entrustability ladder is re-mounted on the live dashboard, gated to PGY1/2 AU doctors, driven by seeded epa_assessment data (not component constants). It self-hides — getEpaLadder returns visible:false for any other doctor, so every consultant sees nothing (no card, no border).†
  • ✅ Four EPAs / three rungs: the ladder renders the verified AMC framework — four EPAs on a three-rung scale (direct/proximal/minimal), top = least-supervision rung, with the latest awarded rung highlighted (or an "awaiting first assessment" state when none recorded).
  • ✅ Progress, not pass/fail: each EPA card shows a "X / Y assessments" chip toward its annual minimum — the AMC global end-of-year-judgement model. There is no pass/fail gate.
  • ✅ Drawer: tapping an EPA opens the full named scale with definitions, the current rung, the assessment history (date · level label · assessor) and the latest supervisor feedback.
  • ✅ Spike #8277 resolved (2026-06-10): the AMC framework is verified and seeded — see roadmap-national-frameworks.md → verified EPAs and packages-shared/ppp/src/constants/epa-framework-config.json.†

Milestone interaction ​

  • ⏳ Click completed milestone → drawer showing the underlying activity record
  • ⏳ Click current milestone → sheet to edit due date (within guardrails) or mark in-progress
  • ⏳ Click future/locked milestone → read-only detail
  • ⏳ Click SMART goal → edit sheet
  • ⏳ Click Enterprise objective → read-only drawer

Data / derivation ​

  • ⏳ Milestone status computed from dueDate + tiedTo.recordId + record.status (not stored)
  • ⏳ Completion signal never set by roadmap service — only by the source feature (WBA, Appraisal, etc.)
  • ⏳ User's pgyYear + country + specialty selects the AMC / RACS / Enterprise preset

Preset system ​

  • ⏳ AMC PGY1 preset available when pgyYear === 1 && country === 'AU'
  • ⏳ AMC PGY2 preset available when pgyYear === 2 && country === 'AU'
  • ⏳ Enterprise preset overlays attach when the user has an active row in ppp_hospital_membership for an enterprise hospital (Q8 resolved #5523 — no enterpriseId column; linkage is the ppp_hospital ↔ ppp_hospital_membership junction, see Closed Questions)
  • ⏳ Full preset library tracked separately in roadmap-national-frameworks.md / #5356

SMART goal authoring ​

  • ⏳ User can create a SMART goal with the 5 SMART fields explicitly captured
  • ⏳ User can tie a SMART goal to an existing PPP feature (optional tiedTo link)
  • ⏳ Abandoning a SMART goal preserves history; doesn't delete

Multi-year horizon + surgical cumulative-volume goals ​

  • ✅ The roadmap horizon filter supports multi-year views: 3 (3 mo), 6, 12, 36 (3 yr) and 60 (5 yr) months, so training programmes and overall goals can be projected over multiple years.† Backend getMilestones / getDashboard accept these horizon values (months); the standalone Roadmap timeline exposes "3 yr" / "5 yr" toggles in addition to 3/6/12 mo (#7641)
  • ✅ A SMART goal may be of type surgical_volume: a target of N logbook cases of a category accumulated over a period (periodStart → timeBound), surfaced on the roadmap timeline with cumulative progress (count vs target).† Progress is computed from logbook case counts via the existing SMART-goal tiedTo: { feature: 'logbook' } mechanism (a logbook-tied goal narrows the count to that procedure category) — no parallel data store (#7641)
  • ✅ Surgical-volume progress is read-only/derived: the percentage is capped at 100 and isComplete is true once current >= targetCount; the roadmap service never writes logbook completion state (#7641)
  • ✅ A surgical_volume goal must carry a positive targetCount (validated server-side); standard is the default goal type so all existing goals are unaffected (#7641)

Role / access ​

  • ⏳ All authenticated users see the Roadmap section
  • ⏳ Enterprise panel only renders when the user belongs to an enterprise (≥ 1 ppp_hospital_membership row with status = 'active' — Q8 #5523)
  • ⏳ Milestone sources visible as a small source-label chip (Cadence / Enterprise / AMC / SMART)

Cadence Meter — WBA milestone auto-generation ​

  • ✅ For each WBA cadence rule (CEX/CBD/PBA/SSA) with a non-zero target in cadenceTracker, generate a RoadmapMilestone with milestoneSource: 'cadence_meter' and suggestedDate = end of the current cadence period (#5999)
  • ✅ Milestone status is completed if the user has ≥ required verified WBAs in the period, in_progress if within the period and short, upcoming if the period hasn't started (#5999)
  • ✅ Cadence rules are read from the user's cadenceTracker JSONB field on the users table (#5999)
  • ✅ Milestones auto-refresh when refreshSuggestions is called (triggered after new logbook entry or CPD activity via query invalidation) (#5999)
  • ✅ If no WBA cadence rules exist, no cadence milestones are generated (#5999)
  • ✅ getMilestones procedure accepts an optional source filter to return only cadence_meter milestones (#5999)

BDD ​

  • ✅ @smoke scenario: Cadence Meter generates roadmap milestones from WBA rules (see ppp-roadmap.feature — @issue-5999)
  • ✅ @smoke scenario: Cadence Meter marks milestone completed when target is met (@issue-5999)
  • ✅ @regression scenario: no cadence milestones when no rules configured (@issue-5999)
  • ⏳ @smoke scenario: PGY1 AU user lands on dashboard and sees AMC PGY1 preset milestones seeded
  • ⏳ @smoke scenario: user creates SMART goal, it appears on the timeline
  • ⏳ @regression scenario: user marks an underlying WBA complete, corresponding milestone flips to completed automatically
  • ⏳ @regression scenario: no horizon-tab rendered on the widget (negative test for Matt's 22 Apr call)
  • ✅ @smoke scenario: user selects a multi-year (5 yr / 60 mo) horizon on the roadmap timeline (@issue-7641)
  • ✅ @smoke scenario: a surgical cumulative-volume goal shows count-vs-target progress (@issue-7641)
  • ✅ @regression scenario: a surgical-volume goal is marked complete once the target is reached (@issue-7641)
  • ✅ @smoke scenario: a PGY1 AU junior doctor sees the live EPA entrustability ladder (4 EPA cards; current rung + progress text per EPA) (@issue-8276 @requires-backend)
  • ✅ @smoke scenario: tapping an EPA opens its detail with the three named rungs + assessment history (@issue-8276 @requires-backend)
  • ✅ @regression scenario: a consultant does not see the EPA entrustability ladder — the gate hides it (@issue-8276)
  • ✅ @regression scenario: listSmartGoals returns HTTP 200 (not a swallowed 500 masked as empty) and the SMART Goals widget shows its genuine empty state on dashboard load — guards the ppp_smart_goals_view migrate-path drift (@issue-8430, recurrence of @issue-6578)
Non-goals ​
  • ❌ National-framework auto-prefill implementation detail — lives in roadmap-national-frameworks.md (#5356)
  • ❌ Roadmap cannot be the source-of-truth for activity completion — that belongs to the feature tables
  • ❌ No fixed time allocations (e.g. "10 weeks surgery") — AMC dropped these in 2024; Roadmap must mirror that
  • ❌ No arbitrary goal types — every goal ties to an existing PPP feature or is a SMART goal
Status ​
Sub-featureStatusNotes
Existing RoadmapTab component✅ BuiltCPD milestone timeline renders today
WhatNextBanner + AppraisalDatePrompt✅ BuiltCurrently in PPPDashboard
Three-source milestone model (Cadence / Enterprise / SMART)📋 Specified#5356
Ternary state rendering (UK convention)✅ Built#5996 — completed / current / future
Alternating-row timeline✅ Built#5996 — zigzag, live data, detail drawer
AMC PGY1 / PGY2 preset📋 SpecifiedAMC deep-dive — waiting on Q5/Q6/Q7
Enterprise preset attachment📋 SpecifiedSchema confirmed — ppp_hospital_membership junction (Q8 #5523)
SMART goal CRUD + tiedTo field📋 SpecifiedNew build
Derived milestone status📋 SpecifiedService refactor
No-time-filter on widget📋 SpecifiedMatt 22 Apr — reverses earlier horizon tabs
Multi-year horizon (36 / 60 mo)✅ Built#7641 — backend horizon values + standalone-timeline 3 yr / 5 yr toggles (additive; V2 dashboard unchanged)
Surgical cumulative-volume SMART goal✅ Built#7641 — surgical_volume goal type; logbook count-vs-target progress via existing tiedTo: logbook
Cadence inputs for MCR/MSF/360, yearly appraisal, surgical cases⚠️ DriftMatt 2026-06-28 / 2026-07-01 — only the four WBA types reach the timeline today (#12740)
AMC prevocational mapping onto existing features📋 SpecifiedMatt 2026-07-01 / 2026-09-22 — mapping awaits Matt's like-for-like decision (Q13)

Open issues on label:feature:ppp-roadmap — issue data unavailable at build time.Fetched at: 2026-10-13T07:29:49Z — live list on GitHub.

Downstream References ​

Other features that read from the Roadmap or feed it:

FeatureField / event usedConsequence
dashboard.mdRenders Roadmap as Section 3Changes to Section 3 layout ripple here
appraisals-wba.mdCompletion of MCR / 360 / MSF → milestone status completedWBA/Appraisal table writes are the source of truth
retrospective.mdReflection entry → self-assessment milestone completedReflection writes drive milestone completion
logbook.mdCase count → SMART goal progressSMART goals with logbook tiedTo read case counts
profile-doctor.mdpgyYear, country, specialty; enterprise via ppp_hospital_membership (no enterpriseId column — Q8 #5523)Drive preset selection
roadmap-national-frameworks.mdAMC / RACS preset libraryAuthors the preset milestone definitions
Change Log ​
DateChangePR/IssueReason
2026-10-04The milestone engine now emits MCR, MSF and 360 due dates from the doctor's cadence (source cadence_meter), a yearly-appraisal milestone for this and next year, and the surgical-case target from the cadence settings. ppp-roadmap.inputs.cadence-all-types stays drift until the onboarding confirm step lands.#12740, #11144Matt, Notion 28 Jun and Dev Session 1 Jul: MCRs, MSFs, 360s, the yearly appraisal, surgical cases and WBAs all feed the Roadmap. MCR is non-consultant only (Rob, #12806).
2026-10-04The dashboard Roadmap timeline gets a 3 mo / 6 mo / 12 mo / 3 yr / 5 yr horizon toggle (remembered, default 12 months) and a "Refresh suggestions" button that re-runs the milestone engine.#11144Task 1 (#11144) checklist T1-40 and T1-44. The toggle existed only in the unrouted RoadmapTimeline, and nothing in the product called refreshSuggestions. No issue exists for either, so the Task issue carries the BDD tag.
2026-10-03Spec refreshed against Matt's 28 Jun 2026 Notion update "PPP Road Map / Yearly Appraisal / Compliance Runner ie What's Up Next" (walked through in the 2026-07-01 Dev Session) and his #11144 answers of 2026-09-21 and 2026-09-29. New AC ppp-roadmap.inputs.cadence-all-types is marked drift (#12740): MCR, MSF, 360, the yearly appraisal and surgical cases must all feed the timeline, but only the four WBA types do today. New AC ppp-roadmap.amc.map-to-existing-features (built neither way yet). The AMC PGY1/PGY2 pathway is now noted as the top roadmap priority (Matt, 2026-09-22). Open Question Q13 asks for the like-for-like mapping. A note now separates the What's-Next banner from the "What's Up Next" runner, which dashboard.md owns.#11144, #12740, #9667Async Task spec refresh, Task 1 (#11144). The newest dated statement from Matt wins. The "What's Up Next" requirements (rename, 3-month outlook, chronological horizontal runner) were handed to dashboard.md on #12720 rather than written here.
2026-08-11Milestone status ('upcoming'/'in_progress'/'overdue') is now derived from a calendar-day difference instead of elapsed milliseconds, and the arithmetic — previously duplicated in smart-goal-service and roadmap-milestone-service — is shared in one helper. No acceptance criteria change; the 30-day in_progress window and overdue semantics are unchanged.#11462, #11338Across a DST spring-forward two local midnights 31 calendar days apart are 743 hours apart rather than 744, so flooring by 86400000ms yielded 30 and a milestone exactly 31 days out was classified 'in_progress' instead of 'upcoming' (31 affected days per year per DST zone; 0 in UTC, which is why CI never saw it).
2026-06-17Resolved roadmap scope open questions Q9/Q10/Q12 — CPD delegated to CPD Home (summary milestone only), reflection/PDP SMART goals linked-lifecycle with the yearly Appraisal (import at review, export on sign-off), and a single unified Roadmap timeline combining framework/enterprise/SMART sources with filtered views for enterprise governance.#8767, #8167Matt delegated the scope conceptualisation to engineering design (#8167); decided with Gemini design input. Reuses existing tables, no schema change.
2026-06-10Added code-paths for epaFrameworks.ts, epa-framework-config.json, competencyTargets.ts#8606, #8485ppp-roadmap.md already cites epa-framework-config.json (#8277); drift gate now fires correctly when EPA framework data changes, per #8485
2026-06-10Re-mount the live EPA entrustability ladder on the PPP dashboard, gated to PGY1/2 AU doctors. EpaLadder is re-wired to ppp.roadmap.getEpaLadder and driven by seeded epa_assessment data (not component constants) — the verified AMC framework (four EPAs, three-rung scale direct/proximal/minimal), showing the latest awarded rung + "X / Y assessments" progress to the per-EPA minima (no pass/fail), with a drawer for the named rungs, definitions, assessment history and supervisor feedback. The query returns visible:false for every other doctor (each consultant), so the component renders nothing. Deletes the static demo data (epaLadderData.ts).#8465, #8276Closes Q5 — completes the path demo (#5522) → removed-from-UAT for being static (#8433) → framework verified + seeded (#8277/#8449) → live gated re-mount (#8276). Flips AC ppp-roadmap.epa-ladder ✅ and roadmap-frameworks.pgy-gated / roadmap-frameworks.not-pass-fail ✅.
2026-06-10Correct the EPA entrustability ladder spec to the verified AMC framework (4 EPAs / 3 rungs, not 5) and point Q5 at the seeded epa-framework-config.json.#8449, #8277Spike #8277 resolved — records that the rung labels are now verified against the AMC PDF and the seed exists, leaving only the #8276 re-mount + EPA-assessment data source + Matt's go-ahead.
2026-06-10Add an @issue-8430 @regression BDD scenario (SMART Goals widget renders its empty state with listSmartGoals returning HTTP 200, not a swallowed 500) and a backend integration test that exercises listSmartGoals against the live ppp_smart_goals_view.#8438, #8430ppp.roadmap.listSmartGoals 500'd again on UAT (#8430) — the migrate-path ppp_smart_goals_view drift first reported as #6578 and fixed by migration 0155 (PR #8422), re-observed during the 2026-06-10 walkthrough before UAT was redeployed. db:push test DBs regenerate the view from the schema so unit tests never caught the migrate-path drift; these executable guards (plus the existing 0155 .validate.sql) make the empty-state path and the view-column contract part of the regression suite.
2026-06-10Removed the static-demo EPA "Training progress — entrustability" ladder from the live dashboard; AC ppp-roadmap.epa-ladder flipped to removed-pending-controlled-seed and Q5 re-opened.#8436, #8433The EpaLadder rendered hard-coded static demo data on the live UAT dashboard, reading as a real feature. Decision (Rob, 2026-06-10) — static demo data must not sit in UAT. The component is preserved on disk for a future build (#8276/#8277) that needs controlled seed data + Matt's implementation spec; it is just unmounted from PPPDashboardV2.
2026-06-09Migration 0155 recreates ppp_smart_goals_view to expose the goal_type, target_count and period_start columns (CREATE OR REPLACE, appended at the tail). This fixes the HTTP 500 on every ppp.roadmap.listSmartGoals call (PPP Dashboard) caused by the view drifting behind the schema, plus a 0155 .validate.sql guard.#8422, #6578#7641 (migration 0142) added goal_type/target_count/period_start to the ppp_smart_goals table and to the Drizzle smartGoalsView definition, but no migration ever recreated the database view — its last definition (0099) predated those columns. The resolver selects them by name from the view, so every listSmartGoals query 500'd on UAT/prod. CI never caught it because the backend unit tests mock the database (so they never touch the real view) and 0142 shipped only a table-level validator, none proving the VIEW exposed the new columns. The 0155 .validate.sql selects the columns from the view, so CI's migration-replay job and CD now block any recurrence.
2026-06-03Added a presentation-only EPA entrustability ladder to the Roadmap (compact five-rung ladder per EPA, current supervision level highlighted, tap opens activities + supervisor feedback). Resolves Q5.#8278, #5522Matt confirmed the EPA ladder is desired for the Q-Health demo (#5522, 2 Jun). Demo scope only — rung labels are an engineering reconstruction (not yet AMC-PDF-verified); live wiring tracked as #8276, AMC PDF spike as #8277.
2026-06-01Roadmap horizon toggle now actually filters the milestone set. RoadmapTimeline sent its getMilestones query with a horizonMonths key, but the backend input field is horizon (the #7641 multi-year filter); tRPC silently dropped the unknown key, so selecting a horizon never changed the result. The query now sends horizon, and a @regression BDD scenario asserts the wire request carries the selected horizon (and not horizonMonths).#7898, #7894Closes #7894. Type-resolution / input-shape drift fix — the horizon toggle was a no-op against the backend filter. Implementation of an existing AC (the horizon control already exists), not a new requirement.
2026-05-27WhatNextBanner "Open" button is now native-aware: in the mobile app (native WebView shell) it posts a navigateToTabs bridge message to the matching native tab instead of using web router navigation, so the native tab bar stays in sync. Web behaviour (react-router via MILESTONE_ROUTE_MAP) is unchanged. Adds a milestone -> native-tab route map (getMilestoneNativeRoute).#7811, #7374Mobile parity for the #7349 roadmap "What's Next" banner. The banner already renders on the mobile home screen (the dashboard tab is a WebView of the web dashboard), but its Open button web-navigated inside that WebView, leaving the native tab bar out of sync. Mirrors the existing avatar-menu navigateToTabs pattern (#7636). Implementation/parity of an existing AC, not a new requirement.
2026-05-27Multi-year roadmap horizon (36 / 60 months = 3 yr / 5 yr) plus a surgical_volume SMART-goal type that surfaces cumulative logbook count-vs-target progress on the roadmap. Re-opens the previously-deferred Q1 (logbook volume targets) as an active AC, built on the existing tiedTo:{feature:'logbook'} mechanism. Additive — the V2 dashboard default rendering is unchanged.#7672, #7641SGD-first translation of Matt's #7298 26 May brief ("expand the view to ... 3 or 5 years view ... surgical numbers of a certain period to reach total goal"). Undecided design points (CPD exclusion, reflection/appraisal amalgamation, hub-and-spoke vs timeline, enterprise-framework separation) recorded as Open Questions Q9–Q12 rather than built.
2026-05-26Replaced the hardcoded "Next action · Submit MCR by 30 June / Cadence Meter milestone #3" mock banner on the PPP Roadmap dashboard section with the live, data-driven WhatNextBanner. The backend ppp.roadmap.getDashboard now returns a structured nextAction ({ milestoneId, milestoneType, summary }) alongside the existing nextActionSummary; the banner's Open button deep-links by milestone type via MILESTONE_ROUTE_MAP (with a new smart_goal mapping), and the banner self-hides when no milestone is pending.#7371, #7349Bug #7349 — the mock banner claimed a next action "Linked to Cadence Meter milestone #3" while the live timeline below showed "No milestones yet" and SMART Goals showed "No SMART Goals yet", directly contradicting itself. The static strings were copied verbatim from this spec's example table. Wiring the existing WhatNextBanner (previously only mounted in the retired V1 dashboard) into the canonical V2 dashboard removes the contradiction and makes the Open button functional.
2026-05-19Recreated ppp_smart_goals_view on UAT via migration 0099_smart_goals_view_rescue (CREATE OR REPLACE VIEW, idempotent) with a .validate.sql companion that SELECTs from the view so CD blocks the deploy on silent no-op.#6590, #6578ppp.roadmap.listSmartGoals was returning HTTP 500 on every PPP Dashboard load because the view was missing on UAT — the table existed but neither 0073 nor the 0095 rescue actually created the view (same class of failure as #4756). Added @regression @issue-6578 BDD scenario on ppp-roadmap.feature that would have caught the 5xx.
2026-05-19Added the read-only Enterprise Objectives panel to the Roadmap dashboard section, backed by a new ppp.roadmap.getEnterpriseObjectives procedure that resolves the user's active enterprise via the ppp_hospital_membership junction (Q8 #5523) and derives objectives + completion state from milestone-engine roadmap milestones. Panel self-hides when the user belongs to no enterprise.#6533, #5998Decomposed from the PPP Roadmap epic (#5356). The Enterprise Objectives sub-panel was a hardcoded fixture; this wires it to live data using the confirmed enterprise linkage. Q2 (org-pathway template authoring model) remains an Open Question, so no schema/migration was added — the milestone resolution query is the single seam to swap once Q2 is resolved (CLAUDE.md pitfall #10).
2026-05-19Added the live horizontal milestone timeline widget to the PPP Roadmap dashboard section. Milestones from all three sources (Cadence Meter / Roadmap engine / SMART Goals) are merged and sorted by due date, rendered as an alternating-row (zigzag) scrollable timeline with ternary state chips (completed / current / future) and a tap-to-open detail drawer. Replaces the previous hardcoded mock timeline.#6525, #5996Delivers AC ppp-roadmap.milestone-timeline from the spec — the dashboard Section 3 timeline must reflect live milestone data rather than a static mock, with the UK ePortfolio ternary-state + alternating-row conventions Matt specified.
2026-05-19Resolved Open Question Q8 (enterprise linkage). Confirmed there is no enterpriseId/tenantId/organisationId column on the users table — enterprise linkage is the existing ppp_hospital ↔ ppp_hospital_membership many-to-many junction. Documented the query path for "get enterprise pathway preset for user X" and updated the Enterprise-preset acceptance criteria accordingly.#6319, #5523Schema research spike (#5523) that gated #5998 (Enterprise Objectives panel). A scalar enterpriseId column would be architecturally wrong because a doctor can belong to multiple hospital enterprises; the junction table already models this correctly, so no migration is needed.
2026-05-13Auto-create a linked RoadmapMilestone (source user, type smart_goal) whenever a SMART Goal is saved. Completing a goal flips its milestone to completed; abandoning a goal removes the milestone; updating timeBound propagates to suggestedDate.#6033Completes the deferred #5997 acceptance criterion — saved SMART Goals must surface on the roadmap timeline. Adds 'smart_goal' to MILESTONE_TYPE_ENUM via migration 0082 and wires the lifecycle through smart-goal-service.
2026-05-12Cadence Meter → RoadmapMilestone integration — WBA cadence rules auto-generate milestones with source cadence_meter, status derived from activity counts, deduplication via notes key.#5999Implements AC ppp-roadmap.cadence-meter (#5999); feeds the horizontal timeline widget with per-WBA-type milestones so clinicians can see their cadence progress at a glance.
2026-05-12Implement SMART Goals CRUD — create, edit, mark complete, and abandon user-authored goals with all five SMART fields; live SmartGoalList replaces fixture data in the Roadmap section of PPPDashboardV2.#5997Decomposed from #5356 (PPP Roadmap epic). Delivers the user-authored SMART Goals sub-panel with backend tRPC procedures, DB schema (ppp_smart_goals), and BDD smoke scenarios.
2026-04-22Spec created. Split out of dashboard.md once the UK ePortfolio reference + AMC PGY1/PGY2 deep-dive gave the Roadmap enough substance to stand on its own. Three-source milestone model (Cadence / Enterprise / SMART) locked. Data model proposes RoadmapPreset / RoadmapMilestone / LearningAgreementPeriod / SmartGoal. Time filter NOT on widget (Matt 22 Apr). National-framework preset library stays in roadmap-national-frameworks.md.#5356Matt reversed the earlier defer decision and flagged the Roadmap as central to the Qhealth deal
2026-04-28Re-ingest of Matt's PPP Road Map Notion page. Added Delivery Horizons section (Now / Next / Later) consolidating the work already scoped here and in roadmap-national-frameworks.md. New capability gaps spun out as enhancement issues against #5325 (entrustability ladder Q5, enterprise schema linkage Q8). Notion content from the page was already absorbed into this spec on 22 Apr — the 28 Apr pass found no net-new material from Matt beyond what is already captured.#5325Matt asked engineering to expand the PPP roadmap documentation with concrete examples and screenshots; horizons + linked enhancement issues give the engineering view
Sources & Recordings ​
SourceNotes
https://docs.google.com/document/d/1NC6uzEjdGk5jSll-LGNmXGcfYJZLwS5KQnTEEissjic/editDescription pending SGD audit

Internal documentation — org members only