Skip to content

SyRF Stage Review and AF2 — Status and Remaining Delivery Plan

Feature State: Active Delivery. The Stage Review Redesign and Annotation Form V2 (AF2) programme modernizes the reviewer experience across annotation, screening, and combined stages. Slices 0, 1, 2A, 2B, and 3A are completed. Slice 3B is the next active implementation target.

The runtime feature flag is stageReviewRedesign (currently default-off).

1. Executive Summary & Delivery Scoreboard

Slice Title / Description Status Evidence / Location
Slice 0 CI & Test Isolation Unblockers Done PR #3207 (6bfd8b0941) fixed NgRx MockStore selector leakage (#3173); PR #3174 (4f14e2253f) eliminated .NET fake clock flakes (#3135).
Slice 1 Repeatable-Branch Tabs & Status Glyphs Merged PR #2810 (branch tabs) and PR #3084 (shape-distinct glyphs), both merged 2026-09-06. Unblocked by web spec test isolation (#3207).
Slice 2A Action Rules & Category Identity Parity Merged Delivered in PR #3210: Complete button disabled on invalid form with tooltip; Save progress enabled when dirty; AF1 category font icons & themes restored; visited progression & status indicators (check_circle/error_outline).
Slice 2B Entity Append Ordering & Navigation Merged Delivered in PR #3210: New entities append canonically (Model 1 then Model 2), preserving creation order, pagination, and target page navigation.
Slice 3A Controls & Comments Gallery Alignment Merged Delivered in PR #3223, merged 2026-09-06: questions, helper text, controls, and error feedback aligned with the Section 4A control gallery; quieter comment treatment without layout shifts.
Slice 3B Panels, Dialog & Navigation Polish Next Implementation Reduced header-to-first-question gap; hover surface inset; full-screen dialog close control polish; remove My Studies internal footnote; resolve Skip button placement.
Slice 4 Baseline Release & Capability Matrix Planned Verification across annotation-only, screening-only, and combined stages; light/dark theme audit; preview rollout under stageReviewRedesign.
Slice 5A Explicit Entity Reordering Planned Drag handles and accessible keyboard alternatives with persistent order contract.
Slice 5B Personal Reviewer Workspace Layouts Planned Responsive, movable panel grid saved in reviewer settings.
Slice 5C Study Source Presentation Modes Planned Embedded, floating in-page, and detached-window modes.
Slice 6 Deferred Backlog & Legacy Cleanup Planned Resolution of #3067 and retirement of legacy components once baseline is stable.

2. Pull Request & Branch Architecture Stack

The stack below has fully landed on main; it is retained as the delivery record for slices 1, 2A and 2B.

graph TD
    M[main] --> P2810[PR #2810: feat/annotation-af2-outline-navigation<br/>AF2 Repeatable Branch Tabs<br/>MERGED 2026-09-06]
    P2810 --> P3084[PR #3084: feat/af2-branch-status-cues<br/>Shape-Distinct Branch Glyphs<br/>MERGED 2026-09-06]
    P3084 --> P3210[PR #3210: feat/af2-actions-categories-entity-ordering<br/>Slices 2A and 2B: Action States, Category Icons, Append Order<br/>MERGED into #3084]
    M --> P3223[PR #3223: codex/af2-controls-gallery<br/>Slice 3A: Controls and Comments Gallery Alignment<br/>MERGED 2026-09-06]

Status of the stack

  1. PR #2810 (feat/annotation-af2-outline-navigation) — merged 2026-09-06.
  2. 69 review threads resolved, preview build healthy.
  3. Was blocked on CI by the cross-file test isolation flake (#3173) until #3207 landed on main.
  4. PR #3084 (feat/af2-branch-status-cues) — merged 2026-09-06.
  5. Shape-distinct glyphs (circle complete, square incomplete, triangle attention) on repeatable branch tabs.
  6. Carried the merged changes from PR #3210 (slices 2A and 2B).
  7. PR #3223 (codex/af2-controls-gallery) — merged 2026-09-06.
  8. Slice 3A: controls and comments aligned with the review gallery.

The next slice, 3B, branches directly from main.

3. Reference Material & Source Truth

  1. Design Handoff: UI mockups for form screens.zip (design_handoff_stage_review_page).
  2. Control Specifications: Section 4A Control Type Gallery in the design pack.
  3. Behavioral Reference: AF1 is authoritative for core behavior:
  4. Complete button disabled when invalid, with tooltip explanation.
  5. Save progress enabled whenever form is dirty.
  6. Category identity icons (fa-file-text, fa-eyedropper, fa-medkit, fa-eye, fa-paw, fa-flask).
  7. Category status feedback (check_circle valid, error_outline invalid, hidden when unvisited).
  8. Entities append to end of category list.
  9. Planning Documents. These are untracked local handover notes held outside the repository, so they are named rather than linked:
  10. handover/syrf-stage-review-remaining-work-plan.md
  11. handover/syrf-af2-stage-review-ui-notes.md
  12. handover/HANDOVER-af2-and-stage-review-codex.md

The in-repository counterparts are AF2 and stage-review remaining delivery and the AF2 overview.

4. Implementation Details for Next Slices

Slice 3A: Question and Control Layout Alignment

  • Stacking Order: Question text \(\to\) helper/description text \(\to\) control \(\to\) validation feedback beneath control.
  • Wrapping: Long prompts must wrap naturally across the available card width, not restricted to the input control's width.
  • Comments: Quieter "Add comment" button; do not expand comment editor unless activated; ensure hover/focus does not cause layout shifts.
  • Controls Gallery Parity: Audit text inputs, number steppers, single-select radio groups, multi-select checkboxes, nested branches, and outcome/treatment controls against Section 4A.

Slice 3B: Panels, Spacing & Navigation Polish

  • Entity Heading Gap: Reduce padding between the expanded entity title card and the first question.
  • Header Actions Inset: Add sufficient margin/inset to overflow menu triggers and action buttons so hover rings and focus rings are not clipped by parent card bounds.
  • Full-Screen Dialog: Fix close button hover alignment; ensure clean escape/backdrop interaction without losing dirty state.
  • My Studies Dialog Copy: Remove internal designer note explaining why reviewers can navigate studies.
  • Skip Button Placement: Standardize Skip placement across annotation-only, screening-only, and combined stages in the top review header.

5. Verification Commands

# Web unit tests for AF2 and stage review
cd src/services/web
pnpm exec ng test --watch=false --include="src/app/shared/annotation/annotation-form-v2/**/*.spec.ts"
pnpm exec ng test --watch=false --include="src/app/stage/stage-review/**/*.spec.ts"

# Documentation validation
./docs/scripts/validate-docs.sh --verbose