Skip to content
LQMS
Trace Items — Requirements, Risks & Risk Controls
Initializing search
nburri/lqms
LQMS
nburri/lqms
Home
Evaluate LQMS
Evaluate LQMS
LQMS Known Limits
LQMS Security Posture
Architecture
Architecture
1. Introduction and Goals
2. Architecture Constraints
3. Context and Scope
4. Solution Strategy
5. Building Block View
6. Runtime View
7. Deployment View
8. Crosscutting Concepts
9. Architecture Decisions
10. Quality Requirements
11. Risks and Technical Debt
12. Glossary
The arrival bundle format
Decisions (ADRs)
Decisions (ADRs)
ADR-0001: Content-Addressed Document Storage with PostgreSQL as Source of Truth
ADR-0002: Single Instance with Scope Hierarchy and Copy-on-Derive
ADR-0003: Fixed Life Cycle States with Configurable Review Processes
ADR-0004: Global Catalogs for Roles and Document Types with Per-Scope Activation
ADR-0005: Modular Monolith
ADR-0006: Three-Layer Search with In-Database Index and Pluggable LLM
ADR-0007: Angular Frontend with Server-Side-Only Enforcement
ADR-0008: Flyway Migrations and jOOQ Codegen from the Migrated Schema
ADR-0009: RLS Enforcement via a Session-Scoped Authorized Scope Set
ADR-0010: Self-Managed QMS via an Internal Mandator
ADR-0011: Authentication via OIDC SSO with Server-Side (BFF) Sessions
ADR-0012: Permission-Based Authorization and System Bootstrap
ADR-0013: User Identity Lifecycle
ADR-0014: Electronic Signatures (Part 11 / Annex 11-Capable)
ADR-0015: Document Effectivity, Periodic Review & Validity
ADR-0016: Data Retention, Disposal & Privacy (FADP / GDPR)
ADR-0017: Multi-Part Version Content
ADR-0018: Non-Functional Targets (Capacity, Availability, Security)
ADR-0019: Notifications & Tasks
ADR-0020: Internationalization (Content Language, Time Zones, Formatting)
ADR-0021: General Typed Document Relationships
ADR-0022: Read-Acknowledgement & Questionnaires
ADR-0023: Migration / Import — Current Released State
ADR-0024: Draft / In-Review Cancellation
ADR-0025: Disposal & Erasure Mechanics (Storage, Index, Backups)
ADR-0026: RLS Runtime Safety — Connection-Pool Scope Isolation
ADR-0027: RLS Boundary — Content-Plane vs Control-Plane
ADR-0028: Stateless Encrypted Token-State Cookie (no server-side session store)
ADR-0029: Document Content Model — Draft-Freeze, Content-Table RLS, Append-Only Audit
ADR-0030: Review & Life-Cycle Realization Model
ADR-0031: Released-base readability enforcement & copy-on-derive mechanics
ADR-0032: Frontend realization — Quinoa, Angular Material, i18n & E2E
ADR-0033: CSRF control for the BFF session — SameSite + JSON content-type
ADR-0034: Notification realization — in-process domain events + system-context fan-out
ADR-0035: Fan-out contract as shipped — gate semantics, count disclosure, audit protocol
ADR-0036: Repository layer — services carry rules, repositories carry jOOQ
ADR-0037: Task scheduler — in-process tick, advisory-lock election, SQL sweep
ADR-0038: Periodic-review realization — derived due date, policy-gated confirmation
ADR-0039: Sweep & periodic-review contract as shipped — grants, guards, addressing
ADR-0040: Disposal-due surfacing — closure-anchored retention, scope-level legal hold
ADR-0041: Email channel & notification i18n — notification-as-outbox, structured messages
ADR-0042: Disposal execution — document tombstoning, single-actor hard-gated destruction
ADR-0043: Disposal blob deletion is post-commit, GC-backstopped
ADR-0044: Search FTS baseline — event-indexed, RLS-scoped search_index
ADR-0045: Image Attachments as Content Parts (Rich-Content Slice R2)
ADR-0046: Four-Eyes — Submitter Excluded from Approval
ADR-0047: Four-Eyes — Submitter-Only Exclusion
ADR-0048: Document Organization — Folder Tree per Scope
ADR-0049: Content Model Round 2 — Type Categories, Template Instantiation, Trace Relations, Completeness Rules
ADR-0050: Live Frontend — SSE State Push, CodeMirror 6, Draft Presence
ADR-0051: In-Text Document Links (doc: Scheme)
ADR-0052: Addressees & Read-Acknowledgement (REQ-TRN Realization)
ADR-0053: Addressees Per Document + Process Owner (amends ADR-0052 K-1)
ADR-0054: Process Owner Is a Role (amends ADR-0053 P-3)
ADR-0055: WYSIWYG Editing Mode over Markdown (editor step R4)
ADR-0056: Visual-Editor Chrome via Milkdown Crepe (gated adoption)
ADR-0057: Content Record Is the ProseMirror Document Tree; Markdown Becomes a Derived Projection
ADR-0058: PM_DOC Is the Only Content Format (pre-production cut; amends ADR-0057 §5)
ADR-0059: Editor Engine Switches to TipTap (spike-gated; supersedes the Milkdown/Crepe choice)
ADR-0060: Backup & Restore — Scripted Ordered Backup with Automated Restore Rehearsal
ADR-0061: CSV — Generated Validation Package per Release
ADR-0062: SBOM — CycloneDX over the Production Layers, Validated Against the Artifact
ADR-0063: User Identity Binds on Subject Only (Issuer Becomes Provenance)
ADR-0064: Per-Document Workflow Role Bindings (Author / Reviewer / Releaser), Enforced
ADR-0065: Diagrams — Excalidraw as the Manual Layer, Mermaid Stays for Text-First/UML
ADR-0066: WITHDRAW — the Author Side May Reclaim a Version from Review
ADR-0067: Review Comments — Anchored, Immutable, Resolvable
ADR-0068: Confluence/Jira QMS Import — Staged, Read-Only, Repeatable
ADR-0069: Arbitrary File Attachments — Download-Only Confinement
ADR-0070: Training Questionnaires — Versioned, Auto-Scored, Release-Gated
ADR-0071: Training Plans — Document Obligations + External Trainings & Certifications
ADR-0072: Diagrams — Self-Hosted draw.io Replaces Excalidraw
ADR-0073: Per-Scope QMS Configuration Surface
ADR-0074: PDF Export of Released Documents — Server-Side via Apache FOP over the Canonical Projection
ADR-0075: Source History Import — Continuity Without Forged Audit
ADR-0076: Periodic-review status visibility (completing MVP gap #2)
ADR-0077: Requirement Items — Keyed Blocks Inside Controlled Documents
ADR-0078: Generalized Trace Items (Traceability Model — Stage A)
ADR-0079: Risk & Risk-Control Items (Traceability Model — Stage B)
ADR-0080: Traceability Workspace — Hub, Sub-Pages, and Role-Gated Views
ADR-0081: Draft-Only Trace-Structure Changes, Server-Enforced
ADR-0082: Table-Shaped Risk Authoring over Risk Blocks
ADR-0083: The TD Dossier — a Versioned, Cross-Scope, Regulatory-Structured Deliverable
ADR-0084: Validation & Regulatory Axes (Traceability Model — Stage C)
ADR-0085: Relation-Layer Consolidation — One Trace Vocabulary, One Surface
ADR-0086: Requirement Traceability Chains — End-to-End Path View + Flat Path Export
ADR-0087: The Scope Traceability Report — One Derived Overview Artifact, Never a Controlled Document
ADR-0088: Verification Evidence Classes — Planned vs. Verified, Derived at the Read Layer
ADR-0089: Recurring Obligations — Periodic Tasks With Record Evidence, Not Calendar Series
ADR-0090: Release & Versioning Policy — Deliberate Releases, One Auditor-Facing Number
ADR-0091: Release Modes — Single-Person Record Release With a Structural Four-Eyes Floor
ADR-0092: Orphan-Blob Garbage Collection With a Quarantine Bin
ADR-0093: One Scope Context — the Toolbar Switcher Is the Only Scope Selector
ADR-0094: Calendar-Anchored Obligation Schedules (Clamped, Never Too Late)
ADR-0095: Key-Rule Governance — Free Until First Use, Then Frozen
ADR-0096: Transition Permissions — Always Visible, Deny Unless Granted
ADR-0097: A Governed Provisioning Surface — MANAGE_SCOPES
ADR-0098: Org Chart × Role System — Marriage at the Evidence Level, Never in Authorization
ADR-0099: The User Manual is an In-App Topic Reference, Not a Document
ADR-0100: LQMS Is the Living Quality Management System
ADR-0101: The Executable Validation Journey (PQ Evidence That Cannot Drift)
ADR-0102: Typed Template Variables (text | date | number — and Deliberately No Enum)
ADR-0103: npm audit Joins the Verification Gate as a Second Standing Input
ADR-0104: The Issued Dossier Is a Persisted Artifact of Record — and Clones to a New Draft
ADR-0105: Navigation Information Architecture — Group by Moment-of-Use
ADR-0106: The Client Reflection Follows Assignments, Not Only Content Reach
ADR-0107: The Audit Append Gate Follows Assignment Reach, Not Content Reach
ADR-0108: Mandator Membership — Invite-Accept, with Pre-Assigned Responsibilities
ADR-0109: Organization Founding Is Its Own Process
ADR-0110: The Audit Trail Is Not a Read Model
ADR-0111: The Imported-Person Model, and Project Portability's First Doctrines
ADR-0112: The Element-Kind Catalog — Semantics in the Model, Not Only in the Code
ADR-0113: Project Arrival Import — Records Arrive as They Are, People Arrive as They Were
ADR-0114: The Operating Model Arrives — Roles as Functions, Names as Words, People as This Instance's Decision
ADR-0115: Collaborative Draft Editing — Two Carets, One Truth, Honest Credit
ADR-0116: The System Maintenance Surface — the App Backs Itself Up, the Host Keeps One Dumb Job
ADR-0117: Role Documentation — a Link, a Finding, Per-Source Recognizers; Substitution Rejected
ADR-0118: The Offline QMS Copy — the Repo Carries the Audit Pack, Not a Second Renderer
ADR-0119: Module-Internal Package Structure — Capabilities First, Layers Second, the Root Is the Surface
ADR-0120: The Shared Kernel — the Domain-Exception Vocabulary Leaves the Authorization Module
ADR-0121: The Project Administrator Role — Per-Scope Administration With Read Access, Seeded in the Base Catalog
ADR-0122: Organization-Level Administration — the Cascade Stays, Becomes Visible, and Founds Projects
ADR-0123: Draft Save-Points — Every Save Restorable, Kept for the Life of the Version
ADR-0124: The Birth Path Completes Without Borrowing Content Clothes
ADR-0125: The Export Twin — Export Emits an Arrival Bundle
ADR-0126: Project Dissolution — the Un-Birth of an Unused Scope
ADR-0127: The Base-QMS Layers — One Library, Derived Adaptations, Local Records
ADR-0128: The GLOBAL Cascade Carries Administration, Never Content
ADR-0129: Role Identity from a GLOBAL Assignment Acts in GLOBAL Alone
ADR-0130: Break-Glass — the Project Administrator's Escalation Is a First-Class, Witnessed, Self-Expiring Act
ADR-0131: Role Substitution as Declared Adoption Edges — Emergency Cover Is Governed, Own-Name, Timed Staffing
ADR-0132: Dual-Hat Reviewer Satisfaction Is a Declared Policy Choice — the Strict Floor Stays the Default
ADR-NNNN:
</span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5" > <div class="md-nav__link md-nav__container"> <a href="../../requirements/" class="md-nav__link "> <span class="md-ellipsis"> Requirements </span> </a> <label class="md-nav__link " for="__nav_5" id="__nav_5_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_5"> <span class="md-nav__icon md-icon"></span> Requirements </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../requirements/stakeholder_requirements/" class="md-nav__link"> <span class="md-ellipsis"> Stakeholder Requirements </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/gap-analysis/" class="md-nav__link"> <span class="md-ellipsis"> Requirements Gap Analysis </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_admin/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Administration, Permissions & Onboarding </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_api_ui/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: API & User Interface </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_audit_reporting/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Audit Trail & Regulatory Reporting </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_auth/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Authentication & Session </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_backup/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Backup & Restore </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_catalogs/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Catalogs, Roles & Users </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_data_protection/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Data Protection, Retention & Disposal </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_documents/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Documents, Versions & Storage </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_dossiers/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Technical Documentation Dossiers </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_effectivity/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Effectivity, Periodic Review & Validity </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_gspr/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Regulatory Conformity (GSPR / Essential Principles) </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_i18n/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Internationalization </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_lifecycle/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Life Cycle & Reviews </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_memberships/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Mandator Membership & Invitations </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_migration/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Migration & Import </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_nfr/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Non-Functional </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_notifications/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Notifications & Tasks </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_obligations/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Recurring Obligations </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_relationships/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Document Relationships </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_risk/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Risk Management (ISO 14971 Hazards & Controls) </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_sbom/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Software Bill of Materials & Supply-Chain Assurance </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_search/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Search </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_separation/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Scopes, Mandators & Separation </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_signatures/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Electronic Signatures </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_training/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Read-Acknowledgement & Questionnaires </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_users/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: User Identity & Lifecycle </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_validation/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Design Validation & the Validation Traceability Axis </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_6" > <div class="md-nav__link md-nav__container"> <a href="../../process/" class="md-nav__link "> <span class="md-ellipsis"> Process (IEC 62304) </span> </a> <label class="md-nav__link " for="__nav_6" id="__nav_6_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_6"> <span class="md-nav__icon md-icon"></span> Process (IEC 62304) </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../process/configuration_management_plan/" class="md-nav__link"> <span class="md-ellipsis"> Configuration Management Plan </span> </a> </li> <li class="md-nav__item"> <a href="../../process/problem_resolution/" class="md-nav__link"> <span class="md-ellipsis"> Problem Resolution Process </span> </a> </li> <li class="md-nav__item"> <a href="../../process/risk_management/" class="md-nav__link"> <span class="md-ellipsis"> Risk Management </span> </a> </li> <li class="md-nav__item"> <a href="../../process/software_development_plan/" class="md-nav__link"> <span class="md-ellipsis"> Software Development Plan </span> </a> </li> <li class="md-nav__item"> <a href="../../process/verification_plan/" class="md-nav__link"> <span class="md-ellipsis"> Verification Plan </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_7" > <label class="md-nav__link" for="__nav_7" id="__nav_7_label" tabindex="0"> <span class="md-ellipsis"> Operations </span> <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_7_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_7"> <span class="md-nav__icon md-icon"></span> Operations </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../operations/genesis-installation/" class="md-nav__link"> <span class="md-ellipsis"> Genesis: Birthing an LQMS Installation with a Base Library </span> </a> </li> <li class="md-nav__item"> <a href="../../operations/deployment/" class="md-nav__link"> <span class="md-ellipsis"> LQMS Deployment Guide </span> </a> </li> <li class="md-nav__item"> <a href="../../operations/server-deployment/" class="md-nav__link"> <span class="md-ellipsis"> LQMS Server Deployment (single Linux host, public HTTPS) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8" > <div class="md-nav__link md-nav__container"> <a href="../../traceability/" class="md-nav__link "> <span class="md-ellipsis"> Traceability </span> </a> <label class="md-nav__link " for="__nav_8" id="__nav_8_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_8_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8"> <span class="md-nav__icon md-icon"></span> Traceability </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../traceability/matrix/" class="md-nav__link"> <span class="md-ellipsis"> Requirements Traceability Matrix </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_9" > <div class="md-nav__link md-nav__container"> <a href="../../validation/" class="md-nav__link "> <span class="md-ellipsis"> Validation (tool lane) </span> </a> <label class="md-nav__link " for="__nav_9" id="__nav_9_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_9_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_9"> <span class="md-nav__icon md-icon"></span> Validation (tool lane) </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../validation/templates/ai-authorship-posture/" class="md-nav__link"> <span class="md-ellipsis"> AI-Authorship Posture — How LQMS Is Built, and Why the Validation Evidence Does Not Rest on It (TEMPLATE) </span> </a> </li> <li class="md-nav__item"> <a href="../../validation/templates/intended-use/" class="md-nav__link"> <span class="md-ellipsis"> Intended-Use Specification — LQMS as a QMS / Document-Control Tool (TEMPLATE) </span> </a> </li> <li class="md-nav__item"> <a href="../../validation/templates/tool-risk-assessment/" class="md-nav__link"> <span class="md-ellipsis"> Tool-Risk Assessment — LQMS as a QMS Tool (TEMPLATE) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_10" > <label class="md-nav__link" for="__nav_10" id="__nav_10_label" tabindex="0"> <span class="md-ellipsis"> Regulatory </span> <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_10"> <span class="md-nav__icon md-icon"></span> Regulatory </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../regulatory/mdr-annex-i-skeleton/" class="md-nav__link"> <span class="md-ellipsis"> MDR Annex I — GSPR authoring skeleton (paraphrased) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--active md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" checked> <div class="md-nav__link md-nav__container"> <a href="../" class="md-nav__link "> <span class="md-ellipsis"> User guide </span> </a> <label class="md-nav__link " for="__nav_11" id="__nav_11_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="true"> <label class="md-nav__title" for="__nav_11"> <span class="md-nav__icon md-icon"></span> User guide </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../tutorial/" class="md-nav__link"> <span class="md-ellipsis"> Tutorial — from zero to a released document </span> </a> </li> <li class="md-nav__item"> <a href="../administration/" class="md-nav__link"> <span class="md-ellipsis"> Administering an LQMS Installation </span> </a> </li> <li class="md-nav__item"> <a href="../diagrams/" class="md-nav__link"> <span class="md-ellipsis"> Diagrams </span> </a> </li> <li class="md-nav__item"> <a href="../documents-lifecycle/" class="md-nav__link"> <span class="md-ellipsis"> Documents & the Lifecycle </span> </a> </li> <li class="md-nav__item"> <a href="../exports/" class="md-nav__link"> <span class="md-ellipsis"> PDF Exports & the Audit Pack </span> </a> </li> <li class="md-nav__item"> <a href="../obligations/" class="md-nav__link"> <span class="md-ellipsis"> Recurring Obligations </span> </a> </li> <li class="md-nav__item"> <a href="../project-context/" class="md-nav__link"> <span class="md-ellipsis"> The Project Context & App Version </span> </a> </li> <li class="md-nav__item"> <a href="../review-comments/" class="md-nav__link"> <span class="md-ellipsis"> Review Comments </span> </a> </li> <li class="md-nav__item"> <a href="../topics/activity-trail/" class="md-nav__link"> <span class="md-ellipsis"> Who did what, when — reading a project's activity </span> </a> </li> <li class="md-nav__item"> <a href="../topics/admin-scopes/" class="md-nav__link"> <span class="md-ellipsis"> Renaming a project, and what can never change </span> </a> </li> <li class="md-nav__item"> <a href="../topics/authority-view/" class="md-nav__link"> <span class="md-ellipsis"> Who holds each function here, and what may it do </span> </a> </li> <li class="md-nav__item"> <a href="../topics/break-glass/" class="md-nav__link"> <span class="md-ellipsis"> The permission I need is held by a role I do not hold — what now? </span> </a> </li> <li class="md-nav__item"> <a href="../topics/coverage-and-chains/" class="md-nav__link"> <span class="md-ellipsis"> Coverage or chains? — which requirement view answers your question </span> </a> </li> <li class="md-nav__item"> <a href="../topics/credentials/" class="md-nav__link"> <span class="md-ellipsis"> Your password: changing it, resetting it — and why LQMS never sees it </span> </a> </li> <li class="md-nav__item"> <a href="../topics/emergency-cover/" class="md-nav__link"> <span class="md-ellipsis"> Who may cover for whom here — declaring emergency cover, and reading where the glass was broken </span> </a> </li> <li class="md-nav__item"> <a href="../topics/key-rules/" class="md-nav__link"> <span class="md-ellipsis"> Special elements: what a project declares, and when its names freeze </span> </a> </li> <li class="md-nav__item"> <a href="../topics/memberships/" class="md-nav__link"> <span class="md-ellipsis"> Belonging to an organization: invitations, acceptance, and what they change </span> </a> </li> <li class="md-nav__item"> <a href="../topics/provisioning-birth-path/" class="md-nav__link"> <span class="md-ellipsis"> How a new organization and project are born </span> </a> </li> <li class="md-nav__item"> <a href="../topics/review-policies/" class="md-nav__link"> <span class="md-ellipsis"> What a review policy controls, and what an empty grant means </span> </a> </li> <li class="md-nav__item"> <a href="../topics/setup-wizard-lanes/" class="md-nav__link"> <span class="md-ellipsis"> The setup wizard: the lanes, and what it writes </span> </a> </li> <li class="md-nav__item"> <a href="../topics/staffing-and-assignments/" class="md-nav__link"> <span class="md-ellipsis"> Staffing people into roles, and the accountable holder </span> </a> </li> <li class="md-nav__item"> <a href="../topics/technical-dossier/" class="md-nav__link"> <span class="md-ellipsis"> How do I assemble a technical dossier? </span> </a> </li> <li class="md-nav__item md-nav__item--active"> <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc"> <label class="md-nav__link md-nav__link--active" for="__toc"> <span class="md-ellipsis"> Trace Items — Requirements, Risks & Risk Controls </span> <span class="md-nav__icon md-icon"></span> </label> <a href="./" class="md-nav__link md-nav__link--active"> <span class="md-ellipsis"> Trace Items — Requirements, Risks & Risk Controls </span> </a> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#1-what-a-trace-item-is" class="md-nav__link"> <span class="md-ellipsis"> 1. What a trace item is </span> </a> </li> <li class="md-nav__item"> <a href="#2-authoring-an-item-in-the-editor" class="md-nav__link"> <span class="md-ellipsis"> 2. Authoring an item in the editor </span> </a> <nav class="md-nav" aria-label="2. Authoring an item in the editor"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#pre-save-authoring-on-the-create-form" class="md-nav__link"> <span class="md-ellipsis"> Pre-save authoring (on the create form) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#3-system-requirements--the-fixed-attribute-set" class="md-nav__link"> <span class="md-ellipsis"> 3. System requirements — the fixed attribute set </span> </a> <nav class="md-nav" aria-label="3. System requirements — the fixed attribute set"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#31-stakeholder-requirements--the-level-above" class="md-nav__link"> <span class="md-ellipsis"> 3.1 Stakeholder requirements — the level above </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#4-risks--the-recorded-score-not-a-computed-one" class="md-nav__link"> <span class="md-ellipsis"> 4. Risks — the recorded score, not a computed one </span> </a> </li> <li class="md-nav__item"> <a href="#5-risk-controls" class="md-nav__link"> <span class="md-ellipsis"> 5. Risk controls </span> </a> </li> <li class="md-nav__item"> <a href="#6-the-risk-table--a-grid-over-the-same-blocks" class="md-nav__link"> <span class="md-ellipsis"> 6. The risk table — a grid over the same blocks </span> </a> </li> <li class="md-nav__item"> <a href="#7-the-stage-c-item-types--validation--regulatory-axes" class="md-nav__link"> <span class="md-ellipsis"> 7. The Stage C item types — validation & regulatory axes </span> </a> <nav class="md-nav" aria-label="7. The Stage C item types — validation & regulatory axes"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#71-user-needs" class="md-nav__link"> <span class="md-ellipsis"> 7.1 User needs </span> </a> </li> <li class="md-nav__item"> <a href="#72-stakeholder-requirements-vs-user-needs-verification-vs-validation" class="md-nav__link"> <span class="md-ellipsis"> 7.2 Stakeholder requirements vs. user needs (verification vs. validation) </span> </a> </li> <li class="md-nav__item"> <a href="#73-validation-cases" class="md-nav__link"> <span class="md-ellipsis"> 7.3 Validation cases </span> </a> </li> <li class="md-nav__item"> <a href="#74-design-elements--and-the-per-scope-design-kinds-vocabulary" class="md-nav__link"> <span class="md-ellipsis"> 7.4 Design elements — and the per-scope Design kinds vocabulary </span> </a> </li> <li class="md-nav__item"> <a href="#75-regulatory-references--gspr--essential-principles" class="md-nav__link"> <span class="md-ellipsis"> 7.5 Regulatory references — GSPR / essential principles </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#8-the-gspr-table--a-grid-over-the-regulatory-ref-blocks" class="md-nav__link"> <span class="md-ellipsis"> 8. The GSPR table — a grid over the regulatory-ref blocks </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../trace-links/" class="md-nav__link"> <span class="md-ellipsis"> Trace Links & the Suspect Cycle </span> </a> </li> <li class="md-nav__item"> <a href="../traceability-workspace/" class="md-nav__link"> <span class="md-ellipsis"> The Traceability Workspace </span> </a> </li> <li class="md-nav__item"> <a href="../training/" class="md-nav__link"> <span class="md-ellipsis"> Training & Acknowledgements </span> </a> </li> </ul> </nav> </li> </ul> </nav> </div> </div> </div> <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" > <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner"> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#1-what-a-trace-item-is" class="md-nav__link"> <span class="md-ellipsis"> 1. What a trace item is </span> </a> </li> <li class="md-nav__item"> <a href="#2-authoring-an-item-in-the-editor" class="md-nav__link"> <span class="md-ellipsis"> 2. Authoring an item in the editor </span> </a> <nav class="md-nav" aria-label="2. Authoring an item in the editor"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#pre-save-authoring-on-the-create-form" class="md-nav__link"> <span class="md-ellipsis"> Pre-save authoring (on the create form) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#3-system-requirements--the-fixed-attribute-set" class="md-nav__link"> <span class="md-ellipsis"> 3. System requirements — the fixed attribute set </span> </a> <nav class="md-nav" aria-label="3. System requirements — the fixed attribute set"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#31-stakeholder-requirements--the-level-above" class="md-nav__link"> <span class="md-ellipsis"> 3.1 Stakeholder requirements — the level above </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#4-risks--the-recorded-score-not-a-computed-one" class="md-nav__link"> <span class="md-ellipsis"> 4. Risks — the recorded score, not a computed one </span> </a> </li> <li class="md-nav__item"> <a href="#5-risk-controls" class="md-nav__link"> <span class="md-ellipsis"> 5. Risk controls </span> </a> </li> <li class="md-nav__item"> <a href="#6-the-risk-table--a-grid-over-the-same-blocks" class="md-nav__link"> <span class="md-ellipsis"> 6. The risk table — a grid over the same blocks </span> </a> </li> <li class="md-nav__item"> <a href="#7-the-stage-c-item-types--validation--regulatory-axes" class="md-nav__link"> <span class="md-ellipsis"> 7. The Stage C item types — validation & regulatory axes </span> </a> <nav class="md-nav" aria-label="7. The Stage C item types — validation & regulatory axes"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#71-user-needs" class="md-nav__link"> <span class="md-ellipsis"> 7.1 User needs </span> </a> </li> <li class="md-nav__item"> <a href="#72-stakeholder-requirements-vs-user-needs-verification-vs-validation" class="md-nav__link"> <span class="md-ellipsis"> 7.2 Stakeholder requirements vs. user needs (verification vs. validation) </span> </a> </li> <li class="md-nav__item"> <a href="#73-validation-cases" class="md-nav__link"> <span class="md-ellipsis"> 7.3 Validation cases </span> </a> </li> <li class="md-nav__item"> <a href="#74-design-elements--and-the-per-scope-design-kinds-vocabulary" class="md-nav__link"> <span class="md-ellipsis"> 7.4 Design elements — and the per-scope Design kinds vocabulary </span> </a> </li> <li class="md-nav__item"> <a href="#75-regulatory-references--gspr--essential-principles" class="md-nav__link"> <span class="md-ellipsis"> 7.5 Regulatory references — GSPR / essential principles </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#8-the-gspr-table--a-grid-over-the-regulatory-ref-blocks" class="md-nav__link"> <span class="md-ellipsis"> 8. The GSPR table — a grid over the regulatory-ref blocks </span> </a> </li> </ul> </nav> </div> </div> </div> <div class="md-content" data-md-component="content"> <article class="md-content__inner md-typeset"> <a href="https://github.com/nburri/lqms/edit/main/docs/user-guide/trace-items.md" title="Edit this page" class="md-content__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M10 20H6V4h7v5h5v3.1l2-2V8l-6-6H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h4zm10.2-7c.1 0 .3.1.4.2l1.3 1.3c.2.2.2.6 0 .8l-1 1-2.1-2.1 1-1c.1-.1.2-.2.4-.2m0 3.9L14.1 23H12v-2.1l6.1-6.1z"/></svg> </a> <h1 id="trace-items--requirements-risks--risk-controls">Trace Items — Requirements, Risks & Risk Controls<a class="headerlink" href="#trace-items--requirements-risks--risk-controls" title="Permanent link">¶</a></h1> <p><em>Audience: authors of specifications, risk analyses, and design documents.</em></p> <p>LQMS lets you trace at a finer grain than "document → document". A <strong>requirement</strong>, a <strong>risk</strong>, or a <strong>risk control</strong> is a <em>keyed block inside a controlled document</em> — not a separate register, not a linked ticket. Once a block has a key it can be linked, counted for coverage, and walked in the traceability views (see <a href="../trace-links/">trace-links</a> and the <a href="../traceability-workspace/">traceability workspace</a>).</p> <p>The design choice that makes everything else simple: <strong>the document's lifecycle IS the item's lifecycle.</strong> A requirement is draft/in-review/released/superseded exactly as the document version that defines it is. There is no separate item state to manage, no item to approve on its own, no way for the register and the document to disagree — because they are the same thing.</p> <h2 id="1-what-a-trace-item-is">1. What a trace item is<a class="headerlink" href="#1-what-a-trace-item-is" title="Permanent link">¶</a></h2> <p>A trace item lives in the document's content, right where you write about it. It carries:</p> <ul> <li>A <strong>key</strong> — the stable identifier (e.g. <code>SSRS_API_012</code>, <code>RISK-004</code>, <code>RC-002</code>). The key is what links point at and what the coverage views count.</li> <li>A short <strong>type-specific attribute set</strong> (below) — fixed per type, no custom fields.</li> <li>A <strong>body</strong> — the normal rich text of the block: the requirement's statement, the risk's narrative, the control's description.</li> </ul> <p>Identity and history are <strong>derived, never managed</strong>. LQMS tracks the block's content across document versions by its content hash — "this requirement changed in v6" simply means its hash differs from v5. You never set a version number on an item or move it through states by hand.</p> <p>A key is <strong>unique within its scope</strong> and <strong>defined in exactly one document</strong>. Moving a definition to another document is a deliberate act (remove it from one draft, add it to another) — both under document review. <em>Links</em> to an item may originate anywhere; only its <em>definition</em> is single-homed.</p> <blockquote> <p><strong>What a project declares, and which documents may define it.</strong> The product ships a <strong>catalog of element kinds</strong> — the eight above — and knows what each one <em>means</em>: that a risk control mitigates a risk, that a user need is satisfied through a system requirement, that a stakeholder requirement is resolved by one. A <strong>project</strong> then declares which of them it uses, what it <strong>calls</strong> them (naming conventions differ between organisations, so the catalog name is a starting point), and the <strong>key prefix</strong> its items are minted from. That is one row per kind in the setup wizard's <strong>Special elements</strong> section — see <a href="../topics/key-rules/">special elements</a> for the whole story, including the freeze that locks a name and its prefix together once the first item exists, and the <strong>pairing</strong>: risks and risk controls come as a pair, because a control exists to reduce a risk.</p> <p><strong>Which documents may define which items</strong> is decided <strong>per project, per document type, per kind</strong> — on that same row, as the <em>"document types that may define it"</em> selection, and equally on the <strong>Scope configuration → Document types</strong> tab (the gear menu), where each activated type carries its row of <em>may-define</em> switches: <strong>May define requirements</strong>, <strong>May define stakeholder requirements</strong>, <strong>May define risks</strong>, <strong>May define risk controls</strong>, <strong>May define user needs</strong>, <strong>May define validation cases</strong>, <strong>May define design elements</strong>, <strong>May define regulatory references</strong>. One model, two places to read it from. A type is enabled only for the items it should author: specification types define requirements and user needs, risk-analysis types define risks and risk controls, design documents define design elements, a Validation Plan defines validation cases, a GSPR / applicability matrix defines regulatory references. This is deliberate — a <em>record</em> type (a form, a log, a report) is not allowed to start minting requirements.</p> <p>A project can leave this half-done in three ways, and its <strong>setup check</strong> names each: a type may define a kind the project never declared; a declared kind no type may define; or a kind in use whose prerequisite kind is not (risk controls with no risks is loud — <em>nothing can ever be mitigated</em>; risks with no controls is a quieter note, because accepting a risk without reducing it is legitimate).</p> <p><em>(Project-local </em><em>custom</em><em> kinds — an assumptions register, a SOUP inventory — are a planned later step: keyed and citable, but deliberately outside derived traceability and marked as such.)</em></p> <p><strong>This is why the insert menu can look "empty".</strong> The slash blocks in §2 (and the table toggles in §6 and §8) appear <strong>only for the item types the current document's type may define in this scope</strong>. If you open a draft and a block you expected is missing from the <code>/</code> menu, the document's type is simply not enabled for that item here — that is governance working as designed, not a bug. The remedy is in Scope configuration: a quality manager turns on the matching <em>May define…</em> switch for that type, and the block appears when you reopen the editor. (If the <em>kind itself</em> was never declared by the project, the switch alone is not enough — the setup check says so, and the setup wizard's Special elements section is where the declaration is made.)</p> </blockquote> <h2 id="2-authoring-an-item-in-the-editor">2. Authoring an item in the editor<a class="headerlink" href="#2-authoring-an-item-in-the-editor" title="Permanent link">¶</a></h2> <p>In the draft editor, type <code>/</code> and pick the block:</p> <ul> <li><strong>System requirement</strong> — opens the <em>New requirement</em> dialog.</li> <li><strong>Stakeholder requirement</strong> — opens the <em>New stakeholder requirement</em> dialog (§3.1).</li> <li><strong>Risk</strong> — opens the <em>New risk</em> dialog.</li> <li><strong>Risk control</strong> — opens the <em>New risk control</em> dialog.</li> <li><strong>User need</strong> — opens the <em>New user need</em> dialog (Stage C — §7).</li> <li><strong>Validation case</strong> — opens the <em>New validation case</em> dialog (§7).</li> <li><strong>Design element</strong> — opens the <em>New design element</em> dialog (§7).</li> <li><strong>Regulatory reference</strong> — opens the <em>New regulatory reference</em> dialog (§7).</li> </ul> <p>Only the blocks the document's type may define in this scope are offered (§1) — the list you see follows the may-define governance, not a fixed menu.</p> <p>Each dialog has a <strong>Suggest</strong> button next to the <strong>Key</strong> field that fills in the next free key using the scope's prefix convention (so keys stay consistent and collision-free). Uniqueness is checked against the scope when you save; a clash is rejected with a clear message.</p> <p>To change an item later, open its block and use <strong>Edit</strong> (requirements show their kind/priority as chips with a <strong>Details</strong> expander for rationale and acceptance criteria). Editing an item is a content change, so it follows the normal rule: <strong>you edit items on a draft</strong>, and a released item is changed by revising its document.</p> <h3 id="pre-save-authoring-on-the-create-form">Pre-save authoring (on the create form)<a class="headerlink" href="#pre-save-authoring-on-the-create-form" title="Permanent link">¶</a></h3> <p>Unlike diagrams, trace items do <strong>not</strong> require you to save the draft first. Every trace-item slash block — <code>/requirement</code>, <code>/stakeholder requirement</code>, <code>/risk</code>, <code>/risk control</code>, and the four Stage C blocks (<code>/user need</code>, <code>/validation case</code>, <code>/design element</code>, <code>/regulatory reference</code>) — is available <strong>on the create form</strong>, before the document's first save, whenever the chosen type and scope allow that item. This means you can lay a specification's keyed requirements — or a risk analysis's first rows, or a stakeholder document's user needs — into the very first draft as you write it, and they are persisted with the initial save. (The set of offered items follows the type you pick in the create form; change the type and the offering updates.)</p> <h2 id="3-system-requirements--the-fixed-attribute-set">3. System requirements — the fixed attribute set<a class="headerlink" href="#3-system-requirements--the-fixed-attribute-set" title="Permanent link">¶</a></h2> <table> <thead> <tr> <th>Field</th> <th>Meaning</th> </tr> </thead> <tbody> <tr> <td><strong>Key</strong></td> <td>Stable identifier, unique in scope. Use <strong>Suggest</strong> for the next free key.</td> </tr> <tr> <td><strong>Kind</strong></td> <td>Fixed vocabulary: <em>Functional</em>, <em>Non-functional</em>, <em>Safety</em>, <em>Other</em> (or unset). Drives the coverage view's kind filter.</td> </tr> <tr> <td><strong>Priority</strong></td> <td>A short free-text token in your project's own priority language (e.g. <em>must</em>, <em>high</em>).</td> </tr> <tr> <td><strong>Rationale</strong></td> <td>Why the requirement exists.</td> </tr> <tr> <td><strong>Acceptance criteria</strong></td> <td>How you will know it is met.</td> </tr> </tbody> </table> <p>There is <strong>no custom-attribute engine</strong> — the set is fixed on purpose. The key hint in the dialog states the rule you are living under: <em>"Unique within the scope; defined in exactly one document."</em></p> <p>The item is called a <strong>system requirement</strong> because a device that is not software still has requirements of its system, and for a pure-software product the system <em>is</em> the software. A supplier project working under IEC 62304 usually renames it <em>Software requirement</em> for its own people — the name is the project's (see <a href="../topics/key-rules/">key rules</a> §0); what the system derives from it is not. Software and architecture requirements typically carry <em>Functional</em>, <em>Non-functional</em>, or <em>Safety</em>.</p> <h3 id="31-stakeholder-requirements--the-level-above">3.1 Stakeholder requirements — the level above<a class="headerlink" href="#31-stakeholder-requirements--the-level-above" title="Permanent link">¶</a></h3> <p>A <strong>stakeholder requirement</strong> is its own item type, not a system requirement wearing a label. It is the specification-lane input at the top of the V — what any stakeholder requires (not only the clinical user: service, regulatory affairs, the business) — and it is distinct from a <em>user need</em>, which is the validation lane; the difference is verification vs. validation, spelled out in §7.2.</p> <p>Its slash block is <strong>Stakeholder requirement</strong> and its dialog carries the same fields as a system requirement <strong>minus Kind</strong>: a type that <em>is</em> the level needs no attribute saying so. Its default key prefix is <code>STK-</code>, and its own may-define switch governs which document types may write one — typically a Stakeholder Requirements specification, which usually also defines the <em>user needs</em> beside them.</p> <p>The requirement chains view reads the type — stakeholder requirements are the top of each chain (see <a href="../traceability-workspace/">traceability-workspace</a> §3), resolved downward by the system requirements that <strong>Satisfy</strong> them.</p> <h2 id="4-risks--the-recorded-score-not-a-computed-one">4. Risks — the recorded score, not a computed one<a class="headerlink" href="#4-risks--the-recorded-score-not-a-computed-one" title="Permanent link">¶</a></h2> <p>A risk block mirrors one row of an ISO 14971 risk table: a <strong>hazard</strong>, the <strong>hazardous situation</strong> that exposes someone to it, and the <strong>harm</strong> that may result. The <em>New risk</em> dialog captures:</p> <ul> <li><strong>Hazard</strong>, <strong>Hazardous situation</strong>, <strong>Harm</strong> — the three-part risk statement.</li> <li><strong>Initial risk</strong> — the pre-control estimate as tokens: <strong>Severity (S)</strong>, <strong>P1 (situation)</strong>, <strong>P2 (harm)</strong>, and <strong>Level</strong>.</li> <li><strong>Residual risk — after controls</strong> — the same four tokens for the post-control estimate, in a subsection you fill in once mitigating controls are linked.</li> <li><strong>Acceptability (current evaluation)</strong> — <em>Acceptable</em> / <em>Not acceptable</em> / <em>Not evaluated</em>.</li> </ul> <p>The two-factor probability (P1 = probability the hazardous situation arises, P2 = probability it then leads to harm) is the ISO 14971 shape. The narrative — sequence of events, justification — goes in the block body.</p> <blockquote> <p><strong>The tool records; it does not compute.</strong> LQMS never multiplies S × P or derives a level from your tokens. As the risk dialog states: <em>"Recorded per your risk-scoring scheme (a controlled document) — the tool records, it does not compute."</em> Your scoring scale and how a level is reached live in <strong>content</strong> — your Risk Management Plan / risk policy — not in the tool. That is why the score fields accept the tokens <em>your</em> scheme uses (a 3×3 scale, a 5×5 scale, qualitative labels — all fine) and why a score renders as tokens like <code>S3 · P1 · P2 — High</code>, never as an equation.</p> </blockquote> <p><strong>Acceptability is the current evaluation, not a residual-only field.</strong> It always shows, even before any residual score. An initial risk you judge <em>Acceptable</em> with no control and no residual is complete — "accepted without reduction" — and the traceability views treat it as such, not as a gap (ISO 14971 does not require reducing a risk that is already acceptable). See <a href="../traceability-workspace/">traceability-workspace</a> §4.</p> <p>Implementation and verification of a risk are <strong>not</strong> attributes — they are links (a control <code>mitigates</code> a risk; the control is <code>implemented-by</code> something and <code>verifies</code>-d by evidence). See <a href="../trace-links/">trace-links</a>.</p> <h2 id="5-risk-controls">5. Risk controls<a class="headerlink" href="#5-risk-controls" title="Permanent link">¶</a></h2> <p>A risk control is a measure that reduces one or more risks. Its only fixed attribute is the <strong>Control kind (ISO 14971 §7.1)</strong> — the standard's priority order:</p> <ul> <li><strong>Inherent safety by design</strong></li> <li><strong>Protective measure</strong></li> <li><strong>Information for safety</strong></li> </ul> <p>(or <em>Unspecified</em>). This vocabulary is fixed because it is normative — it comes from the standard, not from a project preference. The control's description goes in the block body; what it mitigates, what implements it, and what verifies it are all links.</p> <h2 id="6-the-risk-table--a-grid-over-the-same-blocks">6. The risk table — a grid over the same blocks<a class="headerlink" href="#6-the-risk-table--a-grid-over-the-same-blocks" title="Permanent link">¶</a></h2> <p>Risk-analysis work is table-native, so a risk-defining document offers a <strong>Risk table</strong> toggle (<em>"Switch between prose and a risk table over the same content."</em>). This is the key thing to understand: <strong>each row of the grid IS a <code>:::risk</code> block in the document.</strong> The grid is a view and controller over the very same content the editor holds — there is no second record and no parallel copy:</p> <ul> <li><strong>Add risk</strong> inserts a new risk block; editing a cell edits that block's attribute; <strong>Delete</strong> removes the block from the document (<em>"Delete risk {{key}}? This removes the risk block from the document."</em>).</li> <li>Columns are the fixed attribute set — <strong>Key</strong>, <strong>S / P1 / P2 / Level</strong> (initial and residual), <strong>Acceptability</strong> — plus <strong>Derived (from links)</strong> columns that are read-only: <strong>Controls</strong>, <strong>Impl. by</strong>, <strong>Verified by</strong>, and <strong>Gaps</strong>. Those derived columns are the same derivation as the risk traceability view, scoped to this document — you author the risk in the grid and see its coverage build up as you add links.</li> <li>The same grid renders <strong>read-only</strong> on a released version's detail — that is the risk table an auditor reads, alongside the narrative body.</li> </ul> <p>The single-item <strong>Risk</strong> dialog and risks embedded in narrative sections stay first-class; the grid is an additional surface over the one document, not a replacement. Everything you author either way is one and the same tree.</p> <h2 id="7-the-stage-c-item-types--validation--regulatory-axes">7. The Stage C item types — validation & regulatory axes<a class="headerlink" href="#7-the-stage-c-item-types--validation--regulatory-axes" title="Permanent link">¶</a></h2> <p>Stage C (ADR-0084) adds four more trace-item types so the whole V-model is traceable at item level, not just requirements and risk. They are authored exactly like the types above — a keyed block, a small fixed attribute set, a body — and each is gated by its own <em>may-define</em> switch (§1).</p> <table> <thead> <tr> <th>Item type</th> <th>Slash block</th> <th>The role it plays</th> <th>Typically defined in</th> </tr> </thead> <tbody> <tr> <td><strong>User need</strong></td> <td><em>User need</em></td> <td>The top of the V — "the right thing" the device must do for its user</td> <td>Stakeholder Requirements</td> </tr> <tr> <td><strong>Validation case</strong></td> <td><em>Validation case</em></td> <td>A validation activity — proof you built the right thing</td> <td>Validation Plan</td> </tr> <tr> <td><strong>Design element</strong></td> <td><em>Design element</em></td> <td>The design "how" — architecture / interface / component / unit</td> <td>Software Design</td> </tr> <tr> <td><strong>Regulatory reference</strong></td> <td><em>Regulatory reference</em></td> <td>One GSPR / essential-principle / standard clause the scope claims</td> <td>GSPR Applicability Matrix</td> </tr> </tbody> </table> <p>The "typically defined in" column is the shipped default governance for the SAMPLE demo scope; your own scope decides its mapping in Scope configuration.</p> <h3 id="71-user-needs">7.1 User needs<a class="headerlink" href="#71-user-needs" title="Permanent link">¶</a></h3> <p>A <strong>user need</strong> captures a stakeholder's need at the top of the V-model — the input the design must ultimately satisfy and that validation must confirm. The <em>New user need</em> dialog captures one fixed attribute:</p> <ul> <li><strong>Source</strong> — a short free-text token naming the stakeholder the need comes from (e.g. <em>Clinician</em>, <em>Biomed</em>). The need statement itself is the block body.</li> </ul> <p>The key hint reads <em>"Unique per scope (e.g. UN-001)."</em> User needs are the rows of the <strong>Validation matrix</strong> (see <a href="../traceability-workspace/">traceability-workspace</a> §7) and the target of the <strong>Validates</strong> link (see <a href="../trace-links/">trace-links</a> §6). How a user need differs from a <em>stakeholder requirement</em> — the two lanes — is the next section.</p> <h3 id="72-stakeholder-requirements-vs-user-needs-verification-vs-validation">7.2 Stakeholder requirements vs. user needs (verification vs. validation)<a class="headerlink" href="#72-stakeholder-requirements-vs-user-needs-verification-vs-validation" title="Permanent link">¶</a></h3> <p>A recurring question: <em>what is the difference between a stakeholder requirement and a user need — is this verification versus validation?</em> They sit at the same end of the V-model, but they belong to two different lanes, and LQMS keeps them apart on purpose.</p> <p>A <strong>stakeholder requirement</strong> is the <em>specification</em> lane. It is its own item type — a <code>:::stakeholder-requirement</code> block (§3.1) — stating what the product must do, raised by any stakeholder: not only the clinical user, but service, regulatory affairs, or the business. A stakeholder requirement is <strong>decomposed</strong> — a system (or architecture) requirement <strong>Satisfies</strong> it, and that requirement is in turn <strong>verified</strong> by evidence (a <strong>Verifies</strong> link from the evidence document). This is the "did we build the product <em>right</em>?" question, and it is exactly what the <strong>Requirement chains</strong> view walks (<em>stakeholder requirement → satisfying system requirement → verification evidence</em>), each stakeholder requirement being the top of one chain. Depth: <a href="../traceability-workspace/#3-requirement-chains">the traceability workspace §3</a>.</p> <p>A <strong>user need</strong> is the <em>validation</em> lane. It is a <code>:::user-need</code> block stated in the terms the user uses (its <strong>Source</strong> names whose need it is), and it is deliberately <strong>not</strong> decomposed into software requirements. A user need is confirmed by <strong>validation</strong> — a <strong>Validates</strong> link from a validation case or a released validation record — checking the <em>finished</em> device against the need in its real use context. This is the "did we build the <em>right</em> product?" question, and it is what the <strong>Validation matrix</strong> view reads (see <a href="../traceability-workspace/">traceability-workspace</a> §7).</p> <p>The distinction is precisely <strong>verification vs. validation</strong>, and the norms frame it that way. IEC 62304 governs the software requirements-and-verification chain (the stakeholder-requirement lane); ISO 13485 §7.3.6 (design and development <em>verification</em>) and §7.3.7 (design and development <em>validation</em>) name the two as separate design-control activities — verification shows the output meets the input, validation shows the product meets the user's needs and intended use. You <em>verify</em> a stakeholder requirement through its satisfying system requirements; you <em>validate</em> a user need against the working device.</p> <p>In practice the two lanes <strong>overlap</strong>, and that is correct, not duplication. A user need is often <strong>restated</strong> as one or more stakeholder requirements so the design can be specified and verified against them — while the original need still stands in the validation lane to be validated in use. Both lanes then legitimately apply to the same underlying need: it appears once as a user need (a row of the Validation matrix) and again as a stakeholder requirement (the top of a Requirement chain). Keeping the two item types distinct is what lets a project prove <em>both</em> that it built the product right (chains) <strong>and</strong> that it built the right product (validation) — the whole point of the V.</p> <h3 id="73-validation-cases">7.3 Validation cases<a class="headerlink" href="#73-validation-cases" title="Permanent link">¶</a></h3> <p>A <strong>validation case</strong> records a validation activity — the evidence that the device does the <em>right thing</em> for its user (validation), as distinct from meeting its <em>written requirements</em> (verification). The <em>New validation case</em> dialog captures one fixed attribute:</p> <ul> <li><strong>Intended-use reference</strong> — free text pointing at the intended use / user need the activity validates (the load-bearing linkage is the <strong>Validates</strong> link, not this field).</li> </ul> <p>The case narrative is the block body. A validation case — or a whole Validation Plan / Validation Report document — <strong>Validates</strong> a user need; that link, and its planned-vs-verified class, is what the Validation matrix reads.</p> <h3 id="74-design-elements--and-the-per-scope-design-kinds-vocabulary">7.4 Design elements — and the per-scope Design kinds vocabulary<a class="headerlink" href="#74-design-elements--and-the-per-scope-design-kinds-vocabulary" title="Permanent link">¶</a></h3> <p>A <strong>design element</strong> is a unit of the design "how" — the architecture, an interface, a component, a unit. It sits below requirements in the V: a design element <strong>Satisfies</strong> a requirement (see <a href="../trace-links/">trace-links</a> §1). The <em>New design element</em> dialog captures one fixed attribute:</p> <ul> <li><strong>Design kind</strong> — a value chosen from the scope's configured vocabulary. The shipped default set is <strong>Architecture</strong>, <strong>Interface</strong>, <strong>Component</strong>, <strong>Unit</strong> (plus <strong>Unspecified</strong>).</li> </ul> <p>Unlike the risk-control kind — fixed because it is normative (ISO 14971 §7.1) — the design-kind vocabulary is a <strong>per-scope configurable list</strong>, because design taxonomies genuinely differ between projects. It is edited in <strong>Scope configuration</strong> under <strong>Design kinds</strong>: <em>"The vocabulary a design element's kind is chosen from in this scope. Leave empty to use the default (architecture, interface, component, unit)."</em> Add a value with <strong>New design kind</strong>, <strong>Remove</strong> ones you do not use, and <strong>Save design kinds</strong>. A scope that has not customised the list shows <em>"Using the default vocabulary (architecture, interface, component, unit)."</em> The design-element dialog then offers exactly that scope's set, and the server validates the chosen kind against it.</p> <h3 id="75-regulatory-references--gspr--essential-principles">7.5 Regulatory references — GSPR / essential principles<a class="headerlink" href="#75-regulatory-references--gspr--essential-principles" title="Permanent link">¶</a></h3> <p>A <strong>regulatory reference</strong> is one clause of a regulation or standard the scope claims conformity to — a General Safety and Performance Requirement (GSPR) from MDR Annex I, an IEC 62304 clause, and so on. A scope's conformity "checklist" is simply a controlled document holding one <code>:::regulatory-ref</code> block per clause. The <em>New regulatory reference</em> dialog captures four fixed attributes, in this order:</p> <ul> <li><strong>Source</strong> — a free-text token naming the regulation/standard (e.g. <code>mdr-annex-i</code>).</li> <li><strong>Clause</strong> — a free-text token naming the clause (e.g. <code>10.1</code>).</li> <li><strong>Applicability</strong> — <strong>Applicable</strong> or <strong>Not applicable</strong>. A new clause is born <strong>Applicable</strong> — the honest "all applicable, mark the exceptions" default.</li> <li><strong>Justification</strong> — free text. It may be left empty while authoring, but an unjustified <em>Not applicable</em> is flagged (see §8 and the conformity view).</li> </ul> <p>The regulation text itself is never tool data — LQMS ships the <strong>type</strong> and the conformity <strong>view</strong>, not the standard (a deliberate licensing boundary). To help you author a GSPR checklist there is a paraphrased <strong>MDR Annex I skeleton</strong> — clause numbers plus one-line house paraphrases only — at <a href="../../regulatory/mdr-annex-i-skeleton/">docs/regulatory/mdr-annex-i-skeleton.md</a>; consult the MDR itself for the authoritative wording. A requirement (or a design element) <strong>Complies with</strong> a regulatory reference; that link is what the <strong>GSPR conformity view</strong> reads (see <a href="../traceability-workspace/">traceability-workspace</a> §8).</p> <h2 id="8-the-gspr-table--a-grid-over-the-regulatory-ref-blocks">8. The GSPR table — a grid over the regulatory-ref blocks<a class="headerlink" href="#8-the-gspr-table--a-grid-over-the-regulatory-ref-blocks" title="Permanent link">¶</a></h2> <p>A GSPR / applicability matrix is intensely table-native (one row per clause), so — exactly like the risk table (§6) — a regulatory-ref-defining <strong>saved</strong> document offers a <strong>GSPR table</strong> toggle (<em>"Switch between prose and a GSPR conformity table over the same content."</em>). Each row of the grid <strong>is</strong> a <code>:::regulatory-ref</code> block in the document; the grid is a view over the same content, not a second record. Its columns are the fixed attribute set — <strong>Key</strong>, <strong>Clause</strong>, <strong>Source</strong>, <strong>Applicability</strong>, <strong>Justification</strong>:</p> <ul> <li><strong>Add clause</strong> inserts a new regulatory-reference block (born <em>Applicable</em>); editing a cell edits that block's attribute; <strong>Delete</strong> removes the block (<em>"Delete {{key}}? This removes the regulatory-reference block from the document."</em>).</li> <li>A row whose applicability is <em>Not applicable</em> with <strong>no justification</strong> is flagged inline as <strong>N/A without justification</strong> — <em>"A not-applicable clause needs a justification — this is a hard gap in the conformity view."</em> This is your early warning, right in the authoring grid, of the hard gap the conformity view will raise.</li> <li>On a released version the grid renders <strong>read-only</strong> as the <strong>GSPR conformity checklist</strong> — the clause table an auditor reads alongside the narrative body.</li> </ul> <p>Unlike the risk table, the GSPR grid has <strong>no derived (from links)</strong> columns — the conformity roll-up lives in the workspace <strong>GSPR conformity</strong> view (see <a href="../traceability-workspace/">traceability-workspace</a> §8), not in the authoring grid.</p> <hr /> <p><em>Governing decisions: ADR-0077 (requirement items — keyed blocks, scope-unique keys, derived identity, definition governance), ADR-0078 (generalized trace items — one substrate, per-type attribute schemas), ADR-0079 (risk & risk-control items — the recorded-score model, P1/P2, acceptability, normative control kind), ADR-0082 (table-shaped risk authoring — grid over the risk blocks), ADR-0084 (Stage C — the user-need / validation-case / design-element / regulatory-ref types, the per-scope design-kind vocabulary, the GSPR authoring grid). Presentation honesty: conventions.md "Presentation honesty" (record vs compute). Standards: ISO 14971 (risk), MDR (2017/745) Annex I (GSPR).</em></p> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type="button" class="md-top md-icon" data-md-component="top" hidden> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class="md-footer"> <nav class="md-footer__inner md-grid" aria-label="Footer" > <a href="../topics/technical-dossier/" class="md-footer__link md-footer__link--prev" aria-label="Previous: How do I assemble a technical dossier?"> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class="md-footer__title"> <span class="md-footer__direction"> Previous </span> <div class="md-ellipsis"> How do I assemble a technical dossier? </div> </div> </a> <a href="../trace-links/" class="md-footer__link md-footer__link--next" aria-label="Next: Trace Links & the Suspect Cycle"> <div class="md-footer__title"> <span class="md-footer__direction"> Next </span> <div class="md-ellipsis"> Trace Links & the Suspect Cycle </div> </div> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class="md-copyright"> <div class="md-copyright__highlight"> Built from <code>v0.9.56-4-g06c7f811</code> (commit <code>06c7f811</code>, 2026-09-09) — the same Markdown the repository ships. </div> </div> </div> </div> </footer> </div> <div class="md-dialog" data-md-component="dialog"> <div class="md-dialog__inner md-typeset"></div> </div> <script id="__config" type="application/json">{"base": "../..", "features": ["navigation.instant", "navigation.tracking", "navigation.top", "navigation.footer", "navigation.indexes", "toc.follow", "search.suggest", "search.highlight", "content.code.copy", "content.action.edit"], "search": "../../assets/javascripts/workers/search.6ce7567c.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script> <script src="../../assets/javascripts/bundle.83f73b43.min.js"></script> </body> </html>