QM v2 Requirements Tracker¶
Living document. Update checkboxes (
[ ]→[x]) and the traceability status column as work lands.Each requirement maps to a phase in the Product Features Roadmap. Detailed designs and acceptance criteria live in the per-feature briefs under docs/features/.
Defined: 2026-02-13 Unified: 2026-02-17 (integrated screening, PRISMA, deduplication, project groups) Total v1 requirements: 101 Core value: Reconciled, authoritative annotation and screening data per study, with full PRISMA 2020 reporting
v1 Requirements¶
Requirements grouped by area. Each is mapped to one or more phases in the traceability table below.
Architecture & Foundation¶
- ARCH-01: All contradictions between spec files and design-decisions.md are resolved (12 identified)
- ARCH-02: Angular 21 signal forms API verified — imports exist, expected signatures confirmed
- ARCH-03: Scope, OwnerId, and DerivedFrom fields present on all versionable entities (future-proofing for cross-scope sharing)
- ARCH-04: Optimistic concurrency added to Study document writes (version field + filter check)
- ARCH-05: New
pmAnnotationQuestionMongoDB collection created with scope/owner indexes - ARCH-06: New
pmQuestionSetMongoDB collection created with scope/owner and published indexes - ARCH-07: New
pmReferenceMongoDB collection created (system-scoped bibliographic identity with DOI/PMID indexes)
PRISMA Specification¶
- PRISMA-01: PRISMA 2020 flow diagram data requirements documented as binding constraints on all data models before implementation begins
- PRISMA-02: Source type taxonomy defined for systematic searches (database, register, website, citation, other)
- PRISMA-03: Three-level data model specified: Reference (system-scoped, global bibliographic identity) → ImportRecord (project-scoped, immutable citation from search) → Study (project-scoped, reviewable entity)
- PRISMA-04: Study lifecycle status model documented (Active, Duplicate, PendingReview, Screened, Excluded, Included) with PRISMA count derivation rules
- PRISMA-05: Deduplication counts available per source type for PRISMA box population
- PRISMA-06: PRISMA 2020 flow diagram auto-generated from study lifecycle and screening data
- PRISMA-07: PRISMA flow data exportable as structured data (JSON/CSV)
Question Management¶
- QM-01: PA can create Draft Questions (DQs) in the QM Design tab — mutable, saved on project entity
- QM-02: PA can edit DQ text, options, help text, and answer option filters while in draft state
- QM-03: PA can assign DQs to a disabled stage via the QM Assign tab (DQIds added to stage collection)
- QM-04: PA can preview assigned DQs on the QM Preview tab before activating a stage
- QM-05: PA can enable a stage, triggering DQ → AQ activation (DQs converted to AQs with initial AQVersions, SQS/SQSV created, stage enabled)
- QM-06: AQ structural properties (parent, data type, group-as-single) are fixed on AQ identity at creation time
- QM-07: AQ content properties (text, options, help text, answer option filters) are versionable — editing creates a new AQVersion
- QM-08: QuestionSet → QuestionSetVersion (QSV) model — immutable snapshots of ordered AQVersionId lists
- QM-09: Parent integrity constraint enforced at QSV composition time (all AQV ancestors included)
- QM-10: Project Question Library — flat manifest of AQVersionId references available to the project
- QM-11: PA can view question version history with diffs between any two versions
- QM-12: PA can create new AQV when editing an activated question (versioning wizard with version badge)
- QM-13: Admin decision framework — when new QSV assigned to stage with active sessions, PA chooses handling (pin, invalidate, require re-annotation)
- QM-14: Version badge displayed on each question card showing current version number
Annotation Form v2¶
- FORM-01: Annotation form rebuilt with Angular 21 signal forms (
form(),[formField],FormValueControl<T>) - FORM-02: All question type controls rebuilt with signal forms (boolean, select, checklist, text, numeric, autocomplete)
- FORM-03: Per-question auto-save — individual AnnotationVersions created on save
- FORM-04: Session model — mutable working state during annotation, immutable SessionVersion on submit
- FORM-05: SessionVersion holds explicit AnnotationVersionIds (not computed filters)
- FORM-06: Virtual scroll for large question sets (performant with 100+ questions per stage)
- FORM-07: Unsaved-changes guard prevents navigation away from dirty form without warning
- FORM-08: Annotator sees only their own answers (candidate blinding enforced at API level)
Project Groups & Permissions¶
- PGRP-01: Custom project permission groups with CRUD operations (backend exists in PR #2224)
- PGRP-02: Project group management UI for administrators (incomplete frontend in PR #2224)
- PGRP-03: Reconciler role assignable via group-based stage permissions (StageActivity.Reconcile)
- PGRP-04: Screener role assignable via group-based stage permissions
Annotation Reconciliation¶
- RECON-01: ReconciliationSession as authority mechanism — versioned gold standard per study
- RECON-02: ReconciliationSessionVersion with complete answer snapshot (newly reconciled + carried forward)
- RECON-03: Authority determination rules — SingleAnnotator auto-promote when 1 session meets MinAnnotators=1
- RECON-04: Authority determination rules — study enters reconciliation pool when >=2 completed sessions
- RECON-05: MinAnnotators acts as readiness threshold (not authority mechanism)
- RECON-06: Reconciler is randomly assigned a study from the unresolved pool (no browsing/claiming)
- RECON-07: Candidate blinding — annotators never see other candidates' answers (system invariant)
- RECON-08: Reconciler always creates own annotation when reconciliation occurs (even when agreeing)
- RECON-09: Bulk approve for studies where all candidates agree — system creates annotations on reconciler's behalf
- RECON-10: Per-study reconciliation scope — required questions = current stage SQS + questions already in this study's RSV
- RECON-11: Cross-stage visibility admin-configurable per stage (Blind, ShowOwnPrior, ShowReconciled)
- RECON-12: Anonymised candidate presentation during reconciliation (Annotator A, Annotator B)
- RECON-13: Percent Agreement metric computed per question, per study, and per stage
- RECON-14: Cohen's Kappa metric computed for categorical questions (null for free-text/numeric, handles edge cases)
- RECON-15: Reconciliation dashboard — pool size, agreement summary, bulk approve vs manual split
- RECON-16: Reconciliation form — side-by-side candidate comparison with required/optional question sections
- RECON-17: Optional per-answer rationale field (admin-configurable to require per stage)
Deduplication¶
- DEDUP-01: ASySD deduplication algorithm available as server-side service (ported or wrapped from R package)
- DEDUP-02: Automated duplicate detection triggered on study import with configurable confidence threshold
- DEDUP-03: Import pipeline creates ImportRecord (immutable, project-scoped) and links to or creates Reference (system-scoped) on each study import
- DEDUP-04: Study status model (Active/Duplicate/PendingReview/Merged) with duplicate records linked to canonical study
- DEDUP-05: Canonical study enrichment — best-of-breed bibliographic metadata from all ImportRecords and cross-project Reference data, with field-level provenance
- DEDUP-06: Admin review queue for probable duplicates below auto-confirm confidence threshold
- DEDUP-07: Merge wizard for already-reviewed duplicate pairs — same-stage: review data becomes additional sessions for reconciliation; cross-stage: link only; admin always decides
- DEDUP-08: Duplicate studies excluded from stage study pools as system invariant
Screening Infrastructure¶
- SCR-01: Screening Profiles — named, reusable screening criteria configurations with agreement modes (Single, DualManual, DualAutomated)
- SCR-02: Screening Annotations — structured exclusion reasons with hierarchical categories linked to profile criteria
- SCR-03: Screening reconciliation with random assignment from pool (consistent with annotation reconciliation pattern)
- SCR-04: FinalScreeningOutcome as screening authority mechanism (Reconciled or CandidateAgreement source)
- SCR-05: Stage Filtering — stage-level study pools with configurable filter rules (Filter Set JSON)
- SCR-06: Screening reconciliation must precede annotation reconciliation (ordering constraint)
- SCR-07: Screening reconciliation bypass criteria (admin-configurable rules for skipping reconciliation pool)
Stage Settings¶
- STAGE-01: Unified stage settings model consolidating screening, annotation, and reconciliation configuration
- STAGE-02: ReviewMode flags enum (Screening, Annotation, ScreeningAndAnnotation, Reconciliation)
- STAGE-03: Stage policy settings (MinAnnotators, CrossStageVisibility, AllowSelfReconciliation, MaxInProgress, SessionCountTarget)
- STAGE-04: Stage settings schema versioning with backward-compatible migration from legacy booleans
Stage Filtering¶
- FILT-01: Filter Set JSON model (v2 schema with nested condition groups) configurable per stage
- FILT-02: FilterCompiler translates filter rules to MongoDB $elemMatch queries
- FILT-03: Stage study pool computed and maintained from filter rules on stage enable
- FILT-04: Random study selection with precomputed random field for fair distribution
- FILT-05: Profile-outcome-based filter rules for post-screening stage population
Data Migration¶
Release 1 Migration:
- MIG-01: Existing questions backfilled as v1 AQVersions with Scope=Project, OwnerId=ProjectId
- MIG-02: Initial QSVs created for each stage from current stage question assignments
- MIG-03: Source type field added to systematic search model (nullable, populated in R3)
- MIG-04: Study status field added (nullable, populated in R3)
- MIG-05: Feature flag rollout — versioning → form v2 → QM UI (ordered dependency)
- MIG-06: Additive-only migration — no data deleted, rollback =
$unset
Release 2 Migration:
- MIG-07: Reconciliation pool populated from studies with ≥2 completed annotation sessions
- MIG-08: Single-annotator studies auto-promoted with RSV (SingleAnnotator resolution)
- MIG-09: Existing admin permissions mapped to project group model (Administrator group preserved)
- MIG-10: Feature flag rollout for reconciliation features (ordered after R1 flags)
Release 3 Migration:
- MIG-11: Study status field backfilled on all existing studies (default: Active)
- MIG-12: Existing screening decisions migrated to structured format with profile references
- MIG-13: Source type metadata backfilled on systematic searches where determinable from import source
- MIG-14: Stage settings migrated from legacy boolean fields to new unified schema
Data Export¶
- EXP-01: Data export includes reconciliation status (reconciled/unreconciled per question)
- EXP-02: Data export includes version references (AQVersionId, QSVId for each annotation)
- EXP-03: Agreement metrics exportable as CSV (per-question and per-study)
- EXP-04: Screening decision export with exclusion reasons and screening profile references
- EXP-05: PRISMA 2020 flow diagram data export (structured data for all PRISMA boxes)
- EXP-06: Deduplication report export (canonical mappings, confidence scores, source counts)
v2 Requirements (Deferred)¶
Tracked but not in current roadmap. Will be considered for a future release.
Cross-Scope Sharing¶
- SHARE-01: Import-as-reference workflow (shared QSV assigned to stage, no copy)
- SHARE-02: Fork-to-customize workflow (copy-on-write for modified questions)
- SHARE-03: Community catalogue UI (browse Published question sets)
- SHARE-04: Organisation model CRUD and member management
- SHARE-05: Researcher personal question libraries
- SHARE-06: Publish workflow (promote project questions to community)
Advanced Question Management¶
- AQM-01: AQV update impact assessment wizard (Options A/B/C for affected annotations)
- AQM-02: Question reorganization wizards (Copy, Copy & Disable, Copy & Delete with descendants)
- AQM-03: System questions remodelled as CAMARADES curated QuestionSet
Out of Scope¶
Explicitly excluded. Documented to prevent scope creep.
| Feature | Reason |
|---|---|
| Annotation reconciliation bypass | Bulk approve handles efficiency; bypass risks undermining quality assurance (D15) |
| Claim-based reconciliation | Prevents cherry-picking; random assignment is methodologically stronger (D9) |
| Automatic conflict resolution (majority vote) | Undermines reconciler judgement; methodologically unsound |
| Reconciled flag on annotations | Replaced by ReconciliationSession model (D5) |
| DecisionSource enum (picking candidate answers) | Reconciler always creates own annotation (D7) |
| Decimal comparison tolerance | Exact match for now; tolerance can be added later |
| E2E test suite | Planned separately, not part of this initiative |
| Cross-project aggregation API | Depends on sharing + reconciliation being stable |
| Mobile app | Web-first platform |
Traceability¶
Which phases cover which requirements. Status column reflects current phase progress; update as work lands.
| Requirement | Phase | Release | Status |
|---|---|---|---|
| ARCH-01 | Phase 1 | — | Complete |
| ARCH-02 | Phase 1 | — | Complete |
| PRISMA-01 | Phase 2 | — | Complete |
| PRISMA-02 | Phase 2 | — | Complete |
| PRISMA-03 | Phase 2 | — | Complete |
| PRISMA-04 | Phase 2 | — | Complete |
| DEDUP-01 | Phase 2 (design) / Phase 12 (build) | R3 | Design complete; build pending |
| ARCH-03 | Phase 3 | R1 | Pending |
| ARCH-04 | Phase 3 | R1 | Pending |
| ARCH-05 | Phase 3 | R1 | Pending |
| ARCH-06 | Phase 3 | R1 | Pending |
| QM-01 | Phase 4 | R1 | Pending |
| QM-02 | Phase 4 | R1 | Pending |
| QM-03 | Phase 4 | R1 | Pending |
| QM-04 | Phase 4 | R1 | Pending |
| QM-05 | Phase 4 | R1 | Pending |
| QM-06 | Phase 4 | R1 | Pending |
| QM-07 | Phase 4 | R1 | Pending |
| QM-08 | Phase 4 | R1 | Pending |
| QM-09 | Phase 4 | R1 | Pending |
| QM-10 | Phase 4 | R1 | Pending |
| FORM-01 | Phase 5 | R1 | Pending |
| FORM-02 | Phase 5 | R1 | Pending |
| FORM-03 | Phase 5 | R1 | Pending |
| FORM-04 | Phase 5 | R1 | Pending |
| FORM-05 | Phase 5 | R1 | Pending |
| FORM-06 | Phase 5 | R1 | Pending |
| FORM-07 | Phase 5 | R1 | Pending |
| FORM-08 | Phase 5 | R1 | Pending |
| QM-11 | Phase 6 | R1 | Pending |
| QM-12 | Phase 6 | R1 | Pending |
| QM-13 | Phase 6 | R1 | Pending |
| QM-14 | Phase 6 | R1 | Pending |
| MIG-01 | Phase 7 | R1 | Pending |
| MIG-02 | Phase 7 | R1 | Pending |
| MIG-03 | Phase 7 | R1 | Pending |
| MIG-04 | Phase 7 | R1 | Pending |
| MIG-05 | Phase 7 | R1 | Pending |
| MIG-06 | Phase 7 | R1 | Pending |
| PGRP-01 | Phase 8 | R2 | Pending |
| PGRP-02 | Phase 8 | R2 | Pending |
| PGRP-03 | Phase 8 | R2 | Pending |
| PGRP-04 | Phase 8 | R2 | Pending |
| RECON-01 | Phase 9 | R2 | Pending |
| RECON-02 | Phase 9 | R2 | Pending |
| RECON-03 | Phase 9 | R2 | Pending |
| RECON-04 | Phase 9 | R2 | Pending |
| RECON-05 | Phase 9 | R2 | Pending |
| RECON-06 | Phase 10 | R2 | Pending |
| RECON-07 | Phase 10 | R2 | Pending |
| RECON-08 | Phase 10 | R2 | Pending |
| RECON-09 | Phase 10 | R2 | Pending |
| RECON-10 | Phase 10 | R2 | Pending |
| RECON-11 | Phase 10 | R2 | Pending |
| RECON-12 | Phase 10 | R2 | Pending |
| RECON-13 | Phase 10 | R2 | Pending |
| RECON-14 | Phase 10 | R2 | Pending |
| RECON-15 | Phase 10 | R2 | Pending |
| RECON-16 | Phase 10 | R2 | Pending |
| RECON-17 | Phase 10 | R2 | Pending |
| MIG-07 | Phase 11 | R2 | Pending |
| MIG-08 | Phase 11 | R2 | Pending |
| MIG-09 | Phase 11 | R2 | Pending |
| MIG-10 | Phase 11 | R2 | Pending |
| ARCH-07 | Phase 12 | R3 | Pending |
| DEDUP-01 | Phase 12 | R3 | Pending |
| DEDUP-02 | Phase 12 | R3 | Pending |
| DEDUP-03 | Phase 12 | R3 | Pending |
| DEDUP-04 | Phase 12 | R3 | Pending |
| DEDUP-05 | Phase 12 | R3 | Pending |
| DEDUP-06 | Phase 12 | R3 | Pending |
| DEDUP-07 | Phase 12 | R3 | Pending |
| DEDUP-08 | Phase 12 | R3 | Pending |
| SCR-01 | Phase 13 | R3 | Pending |
| STAGE-01 | Phase 13 | R3 | Pending |
| STAGE-02 | Phase 13 | R3 | Pending |
| STAGE-03 | Phase 13 | R3 | Pending |
| STAGE-04 | Phase 13 | R3 | Pending |
| SCR-05 | Phase 14 | R3 | Pending |
| FILT-01 | Phase 14 | R3 | Pending |
| FILT-02 | Phase 14 | R3 | Pending |
| FILT-03 | Phase 14 | R3 | Pending |
| FILT-04 | Phase 14 | R3 | Pending |
| FILT-05 | Phase 14 | R3 | Pending |
| SCR-02 | Phase 15 | R3 | Pending |
| SCR-03 | Phase 15 | R3 | Pending |
| SCR-04 | Phase 15 | R3 | Pending |
| SCR-06 | Phase 15 | R3 | Pending |
| SCR-07 | Phase 15 | R3 | Pending |
| MIG-11 | Phase 16 | R3 | Pending |
| MIG-12 | Phase 16 | R3 | Pending |
| MIG-13 | Phase 16 | R3 | Pending |
| MIG-14 | Phase 16 | R3 | Pending |
| EXP-01 | Phase 16 | R3 | Pending |
| EXP-02 | Phase 16 | R3 | Pending |
| EXP-03 | Phase 16 | R3 | Pending |
| EXP-04 | Phase 16 | R3 | Pending |
| EXP-05 | Phase 16 | R3 | Pending |
| EXP-06 | Phase 16 | R3 | Pending |
| PRISMA-05 | Phase 16 | R3 | Pending |
| PRISMA-06 | Phase 16 | R3 | Pending |
| PRISMA-07 | Phase 16 | R3 | Pending |
Coverage summary¶
- v1 requirements: 101 total
- Mapped to phases: 101
- Unmapped: 0
By release:
- Phase 1 (complete): 2 requirements
- Phase 2 (PRISMA gate, complete): 5 requirements (includes DEDUP-01 design)
- Release 1 (Phases 3–7): 32 requirements
- Release 2 (Phases 8–11): 25 requirements
- Release 3 (Phases 12–16): 37 requirements
History¶
- 2026-02-13: Initial requirements defined (annotation management scope, 54 requirements)
- 2026-02-17: Unified — integrated screening, PRISMA, dedup, project groups (101 requirements)
- 2026-04-23: Migrated from
.planning/REQUIREMENTS.mdto docs framework as part of PR #2398 cleanup