Skip to content
LQMS
ADR-0079: Risk & Risk-Control Items (Traceability Model — Stage B)
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-0079: Risk & Risk-Control Items (Traceability Model — Stage B)
Table of contents
Context
Decisions (each marked with the recommendation for review)
D-A — Two types: risk and risk-control [recommend: yes]
D-B — The scheme reference: link to the Risk Management Plan, don't bind it [recommend: doc-relation for Stage B]
D-C — Residual risk: a second score triple on the risk item [recommend: yes]
D-D — Score tokens are free text, not a tool vocabulary [recommend: yes]
Proposed model
risk item — node risk, fence :::risk
risk-control item — node riskControl, fence :::risk-control
Edges (extend the existing type-agnostic link vocabulary)
Governance (pays off the deferred ADR-0078 generalization)
View — the risk traceability table (per scope)
Non-goals (Stage B)
Consequences
Decisions confirmed (Nicolas, 2026-07-18)
Clarification (2026-07-19): an acceptable initial risk needs no reduction
Clarification 2 (2026-07-19): implemented-by targets a requirement item OR a document
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--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" > <div class="md-nav__link md-nav__container"> <a href="../../user-guide/" 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="false"> <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="../../user-guide/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="../../user-guide/administration/" class="md-nav__link"> <span class="md-ellipsis"> Administering an LQMS Installation </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/diagrams/" class="md-nav__link"> <span class="md-ellipsis"> Diagrams </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/documents-lifecycle/" class="md-nav__link"> <span class="md-ellipsis"> Documents & the Lifecycle </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/exports/" class="md-nav__link"> <span class="md-ellipsis"> PDF Exports & the Audit Pack </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/obligations/" class="md-nav__link"> <span class="md-ellipsis"> Recurring Obligations </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/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="../../user-guide/review-comments/" class="md-nav__link"> <span class="md-ellipsis"> Review Comments </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/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="../../user-guide/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="../../user-guide/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="../../user-guide/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="../../user-guide/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="../../user-guide/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="../../user-guide/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="../../user-guide/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="../../user-guide/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="../../user-guide/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="../../user-guide/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="../../user-guide/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="../../user-guide/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="../../user-guide/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"> <a href="../../user-guide/trace-items/" class="md-nav__link"> <span class="md-ellipsis"> Trace Items — Requirements, Risks & Risk Controls </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/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="../../user-guide/traceability-workspace/" class="md-nav__link"> <span class="md-ellipsis"> The Traceability Workspace </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/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="#context" class="md-nav__link"> <span class="md-ellipsis"> Context </span> </a> </li> <li class="md-nav__item"> <a href="#decisions-each-marked-with-the-recommendation-for-review" class="md-nav__link"> <span class="md-ellipsis"> Decisions (each marked with the recommendation for review) </span> </a> <nav class="md-nav" aria-label="Decisions (each marked with the recommendation for review)"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#d-a--two-types-risk-and-risk-control-recommend-yes" class="md-nav__link"> <span class="md-ellipsis"> D-A — Two types: risk and risk-control [recommend: yes] </span> </a> </li> <li class="md-nav__item"> <a href="#d-b--the-scheme-reference-link-to-the-risk-management-plan-dont-bind-it-recommend-doc-relation-for-stage-b" class="md-nav__link"> <span class="md-ellipsis"> D-B — The scheme reference: link to the Risk Management Plan, don't bind it [recommend: doc-relation for Stage B] </span> </a> </li> <li class="md-nav__item"> <a href="#d-c--residual-risk-a-second-score-triple-on-the-risk-item-recommend-yes" class="md-nav__link"> <span class="md-ellipsis"> D-C — Residual risk: a second score triple on the risk item [recommend: yes] </span> </a> </li> <li class="md-nav__item"> <a href="#d-d--score-tokens-are-free-text-not-a-tool-vocabulary-recommend-yes" class="md-nav__link"> <span class="md-ellipsis"> D-D — Score tokens are free text, not a tool vocabulary [recommend: yes] </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#proposed-model" class="md-nav__link"> <span class="md-ellipsis"> Proposed model </span> </a> <nav class="md-nav" aria-label="Proposed model"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#risk-item--node-risk-fence-risk" class="md-nav__link"> <span class="md-ellipsis"> risk item — node risk, fence :::risk </span> </a> </li> <li class="md-nav__item"> <a href="#risk-control-item--node-riskcontrol-fence-risk-control" class="md-nav__link"> <span class="md-ellipsis"> risk-control item — node riskControl, fence :::risk-control </span> </a> </li> <li class="md-nav__item"> <a href="#edges-extend-the-existing-type-agnostic-link-vocabulary" class="md-nav__link"> <span class="md-ellipsis"> Edges (extend the existing type-agnostic link vocabulary) </span> </a> </li> <li class="md-nav__item"> <a href="#governance-pays-off-the-deferred-adr-0078-generalization" class="md-nav__link"> <span class="md-ellipsis"> Governance (pays off the deferred ADR-0078 generalization) </span> </a> </li> <li class="md-nav__item"> <a href="#view--the-risk-traceability-table-per-scope" class="md-nav__link"> <span class="md-ellipsis"> View — the risk traceability table (per scope) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#non-goals-stage-b" class="md-nav__link"> <span class="md-ellipsis"> Non-goals (Stage B) </span> </a> </li> <li class="md-nav__item"> <a href="#consequences" class="md-nav__link"> <span class="md-ellipsis"> Consequences </span> </a> </li> <li class="md-nav__item"> <a href="#decisions-confirmed-nicolas-2026-07-18" class="md-nav__link"> <span class="md-ellipsis"> Decisions confirmed (Nicolas, 2026-07-18) </span> </a> </li> <li class="md-nav__item"> <a href="#clarification-2026-07-19-an-acceptable-initial-risk-needs-no-reduction" class="md-nav__link"> <span class="md-ellipsis"> Clarification (2026-07-19): an acceptable initial risk needs no reduction </span> </a> </li> <li class="md-nav__item"> <a href="#clarification-2-2026-07-19-implemented-by-targets-a-requirement-item-or-a-document" class="md-nav__link"> <span class="md-ellipsis"> Clarification 2 (2026-07-19): implemented-by targets a requirement item OR a document </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/decisions/adr-0079-risk-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="adr-0079-risk--risk-control-items-traceability-model--stage-b">ADR-0079: Risk & Risk-Control Items (Traceability Model — Stage B)<a class="headerlink" href="#adr-0079-risk--risk-control-items-traceability-model--stage-b" title="Permanent link">¶</a></h1> <ul> <li><strong>Status:</strong> accepted (Nicolas 2026-07-18 — decisions confirmed at the foot of this ADR).</li> <li><strong>Date:</strong> 2026-07-18</li> <li><strong>Deciders:</strong> Nicolas Burri, design by Claude.</li> <li><strong>Builds on:</strong> ADR-0078 (generalized trace items — this is purely <em>register two new types</em>), ADR-0077 (the requirement item, the template), the traceability model (traceability-model.md §2/§3, view 2).</li> <li><strong>Standard:</strong> ISO 14971 (risk management for medical devices) is the domain shape below.</li> </ul> <h2 id="context">Context<a class="headerlink" href="#context" title="Permanent link">¶</a></h2> <p>The traceability model's biggest audited gap is the <strong>risk thread</strong>: hazard → hazardous situation → harm, with an estimated risk that risk controls reduce to a residual risk, and each control implemented and verified. Nicolas's scope line (2026-07-18): <strong>risk and risk-control ITEMS + a risk-score RECORDING are in the tool; the scoring scale and how the level is calculated are CONTENT</strong> (a controlled document — the Risk Management Plan / risk policy). The tool records "S3 × P2 = High, per <plan>, by X on D"; it never computes the level or owns the matrix.</p> <p>ADR-0078 made this additive: a new item type = register a <code>TraceItemType</code> (tiptap node + fence + fixed attribute schema) and its frontend twin; the registry/link/suspect/coverage engines do not change (proven by <code>TraceItemGeneralizationTest</code>). Stage B registers <strong>two</strong> types.</p> <h2 id="decisions-each-marked-with-the-recommendation-for-review">Decisions (each marked with the recommendation for review)<a class="headerlink" href="#decisions-each-marked-with-the-recommendation-for-review" title="Permanent link">¶</a></h2> <h3 id="d-a--two-types-risk-and-risk-control-recommend-yes">D-A — Two types: <code>risk</code> and <code>risk-control</code> <strong>[recommend: yes]</strong><a class="headerlink" href="#d-a--two-types-risk-and-risk-control-recommend-yes" title="Permanent link">¶</a></h3> <p>A risk is <em>estimated and evaluated</em>; a control is a <em>measure</em> that mitigates one-or-more risks and is itself <em>implemented and verified</em>. The relationship is <strong>many-to-many</strong> (one risk → several controls; one control → several risks) and a control carries its own outward edges — neither fits inside the other's attributes. So two sibling types, connected by links, not one type with a sub-role.</p> <h3 id="d-b--the-scheme-reference-link-to-the-risk-management-plan-dont-bind-it-recommend-doc-relation-for-stage-b">D-B — The scheme reference: link to the Risk Management Plan, don't bind it <strong>[recommend: doc-relation for Stage B]</strong><a class="headerlink" href="#d-b--the-scheme-reference-link-to-the-risk-management-plan-dont-bind-it-recommend-doc-relation-for-stage-b" title="Permanent link">¶</a></h3> <p>The scores are recorded tokens; their <em>meaning</em> is the scope's Risk Management Plan. Two ways to tie a risk to that plan:</p> <ul> <li><strong>(rec) Document relation (minimal).</strong> The Risk Analysis document that <em>contains</em> the risk items already <code>references</code> / <code>derives-from</code> the Risk Management Plan via existing document relations (ADR-0021). The scheme linkage exists at document granularity with zero new mechanism; the risk items just carry tokens.</li> <li><strong>(alt) Scope-level scheme binding (enforced).</strong> Declare the scheme document once per scope (ADR-0073 config surface); every risk inherits it; when the plan's version changes, all risk scores go <em>suspect</em> (re-evaluate) via the ADR-0078 mechanism at the binding level. Stronger and very much on-theme for 14971 ("change your risk policy → re-evaluate your risks"), but more build.</li> </ul> <p><strong>Recommendation:</strong> ship the doc-relation form in Stage B; keep the scope-binding + suspect-on- scheme-change as a <strong>flagged Stage B+ enhancement</strong> if you want the tool to <em>enforce</em> one scheme per scope and drive automatic re-evaluation. This keeps scoring firmly as content and Stage B tight.</p> <h3 id="d-c--residual-risk-a-second-score-triple-on-the-risk-item-recommend-yes">D-C — Residual risk: a second score triple on the <code>risk</code> item <strong>[recommend: yes]</strong><a class="headerlink" href="#d-c--residual-risk-a-second-score-triple-on-the-risk-item-recommend-yes" title="Permanent link">¶</a></h3> <p>Residual risk is the <em>net effect of a risk's controls on that risk</em>, so it belongs on the risk item, not on a control and not as a separate "phase" item. The <code>risk</code> item carries <strong>two triples — initial and residual</strong> — plus a small acceptability outcome. No phase-discriminated duplicate items.</p> <h3 id="d-d--score-tokens-are-free-text-not-a-tool-vocabulary-recommend-yes">D-D — Score tokens are free text, not a tool vocabulary <strong>[recommend: yes]</strong><a class="headerlink" href="#d-d--score-tokens-are-free-text-not-a-tool-vocabulary-recommend-yes" title="Permanent link">¶</a></h3> <p>Risk scales genuinely vary (3×3, 5×5, qualitative) — that is a <em>proven variation point</em>, so per the opinionated principle the severity/probability/level values are <strong>short free tokens supplied from the scheme</strong>, not a fixed tool enum. The tool records them; it does not validate them against a matrix (that would pull the scheme into the tool, which your line puts in content).</p> <h2 id="proposed-model">Proposed model<a class="headerlink" href="#proposed-model" title="Permanent link">¶</a></h2> <h3 id="risk-item--node-risk-fence-risk"><code>risk</code> item — node <code>risk</code>, fence <code>:::risk</code><a class="headerlink" href="#risk-item--node-risk-fence-risk" title="Permanent link">¶</a></h3> <p>Mirrors one row of a 14971 risk table. Fixed attributes (all recorded; the tool never computes a level from S and P):</p> <table> <thead> <tr> <th>Attribute</th> <th>Meaning</th> </tr> </thead> <tbody> <tr> <td><code>hazard</code></td> <td>the hazard (short)</td> </tr> <tr> <td><code>hazardousSituation</code></td> <td>the exposure circumstance (short)</td> </tr> <tr> <td><code>harm</code></td> <td>the potential harm (short)</td> </tr> <tr> <td><code>initialSeverity</code> / <code>initialP1</code> / <code>initialP2</code> / <code>initialRiskLevel</code></td> <td>pre-control estimate (tokens). P1 = probability of the hazardous situation arising; P2 = probability it then leads to harm (ISO 14971 two-factor probability). The tool records P1, P2 and the level; it does not compute P1×P2 or the level.</td> </tr> <tr> <td><code>residualSeverity</code> / <code>residualP1</code> / <code>residualP2</code> / <code>residualRiskLevel</code></td> <td>post-control estimate (tokens)</td> </tr> <tr> <td><code>residualAcceptability</code></td> <td>evaluation outcome — enum <code>acceptable</code> | <code>not-acceptable</code> (benefit-risk justification goes in the body / a linked document)</td> </tr> </tbody> </table> <p>Block body = the descriptive narrative (sequence of events, rationale). The full structured row (hazard/situation/harm structured, both score triples, acceptability) was chosen over the leaner scores-only variant (Nicolas, 2026-07-18, Q-1).</p> <h3 id="risk-control-item--node-riskcontrol-fence-risk-control"><code>risk-control</code> item — node <code>riskControl</code>, fence <code>:::risk-control</code><a class="headerlink" href="#risk-control-item--node-riskcontrol-fence-risk-control" title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Attribute</th> <th>Meaning</th> </tr> </thead> <tbody> <tr> <td><code>controlKind</code></td> <td>14971 §7.1 priority order — enum <code>inherent-safety-by-design</code> | <code>protective-measure</code> | <code>information-for-safety</code>. Normative (from the standard), so a <em>fixed</em> vocabulary is correct here.</td> </tr> </tbody> </table> <p>Body = the control description. Implementation and verification are edges, not attributes.</p> <h3 id="edges-extend-the-existing-type-agnostic-link-vocabulary">Edges (extend the existing type-agnostic link vocabulary)<a class="headerlink" href="#edges-extend-the-existing-type-agnostic-link-vocabulary" title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Edge</th> <th>Source → Target</th> <th>New?</th> </tr> </thead> <tbody> <tr> <td><code>mitigates</code></td> <td><code>risk-control</code> → <code>risk</code></td> <td>new edge type</td> </tr> <tr> <td><code>implemented-by</code></td> <td><code>risk-control</code> → <code>requirement</code> (design-element in Stage C)</td> <td>new edge type</td> </tr> <tr> <td><code>verifies</code></td> <td>document → <code>risk-control</code></td> <td><strong>existing</strong> edge type, control is just a new target (additive per ADR-0078)</td> </tr> </tbody> </table> <p>Suspect directions fall out correctly: re-score a risk → its controls' <code>mitigates</code> links go suspect (re-review adequacy); change a requirement → the control's <code>implemented-by</code> link goes suspect.</p> <h3 id="governance-pays-off-the-deferred-adr-0078-generalization">Governance (pays off the deferred ADR-0078 generalization)<a class="headerlink" href="#governance-pays-off-the-deferred-adr-0078-generalization" title="Permanent link">¶</a></h3> <p>Generalize <code>may_define_requirements</code> → a <strong>per-(scope, type) may-define</strong> flag: <code>risk</code> definable in Risk-Analysis document types, <code>risk-control</code> in Risk-Analysis / Design types — configured per scope, exactly like requirements. The per-(scope, type) key rule generalizes likewise (<code>RISK-*</code>, <code>RC-*</code>). Keys remain one scope-wide keyspace across all types (ADR-0078).</p> <h3 id="view--the-risk-traceability-table-per-scope">View — the risk traceability table (per scope)<a class="headerlink" href="#view--the-risk-traceability-table-per-scope" title="Permanent link">¶</a></h3> <p>Rows = risks; for each: initial score → its controls (<code>mitigates</code>⁻¹) → each control's implementing requirement (<code>implemented-by</code>) and verification (<code>verifies</code>⁻¹) → residual score + acceptability. Gap flags (the completeness property): risk with no control, control not implemented, control not verified, residual not <code>acceptable</code>. A read-model in the shape of the ADR-0077 coverage panel.</p> <h2 id="non-goals-stage-b">Non-goals (Stage B)<a class="headerlink" href="#non-goals-stage-b" title="Permanent link">¶</a></h2> <p>No score <strong>computation</strong> (S×P→level is content); no fixed score vocabulary (scales are content); no verification-case <strong>items</strong> (verification is document-level here — items are Stage C); no <code>design-element</code> type (<code>implemented-by</code> targets requirements for now — Stage C); no benefit-risk <strong>engine</strong> (recorded as <code>residualAcceptability</code> + narrative); no automatic re-evaluation on scheme change (the flagged Stage B+ enhancement under D-B).</p> <h2 id="consequences">Consequences<a class="headerlink" href="#consequences" title="Permanent link">¶</a></h2> <ul> <li>The risk thread becomes traceable at item level and links into the V-model through <code>implemented-by</code> → requirement → (its verification), so a single trace runs hazard → control → requirement → verification → residual.</li> <li>The per-(scope, type) may-define + key-rule generalization lands here and serves every later type.</li> <li>Stage C (validation + GSPR) and Stage D (completeness surface, change-impact, baselines) remain additive on the same substrate.</li> </ul> <h2 id="decisions-confirmed-nicolas-2026-07-18">Decisions confirmed (Nicolas, 2026-07-18)<a class="headerlink" href="#decisions-confirmed-nicolas-2026-07-18" title="Permanent link">¶</a></h2> <ol> <li><strong>Q-1 — risk attribute richness →</strong> the <strong>full structured row</strong> (hazard/situation/harm + both score triples + acceptability), not the leaner scores-only variant.</li> <li><strong>Q-2 — scheme reference →</strong> <strong>doc-relation now</strong> (the Risk Analysis document references its Risk Management Plan via existing relations); the enforced scope-level scheme binding + re-evaluation suspect is deferred to Stage B+.</li> <li><strong>Q-3 — <code>residualAcceptability</code> →</strong> <strong>kept</strong> as a recorded evaluation outcome.</li> <li><strong>Q-4 — probability →</strong> <strong>split P1 × P2</strong> (P1 = probability of the hazardous situation; P2 = probability it leads to harm) for both the initial and residual estimates.</li> </ol> <h2 id="clarification-2026-07-19-an-acceptable-initial-risk-needs-no-reduction">Clarification (2026-07-19): an acceptable initial risk needs no reduction<a class="headerlink" href="#clarification-2026-07-19-an-acceptable-initial-risk-needs-no-reduction" title="Permanent link">¶</a></h2> <p>Round-2 play-test (Nicolas 2026-07-19). ISO 14971 does not require risk reduction when the <strong>initial</strong> risk is already acceptable — the risk is <em>accepted as-is</em>, and the absence of a mitigating control is by design, not a completeness gap. Two consequences follow. Neither changes any decision above, and — the hard constraint — <strong>no serialization / attribute change</strong>: the storage attribute keeps its name <code>residualAcceptability</code>.</p> <ul> <li> <p><strong>Acceptability is the <em>current-evaluation</em> outcome, not a residual-only field.</strong> In the risk dialog the acceptability control moves OUT of the collapsible "Residual risk" subsection and is relabelled <em>"Acceptability (current evaluation)"</em>; it always shows (an acceptable initial risk records its acceptability without ever touching residual scores). The residual S/P1/P2/level triple stays in the subsection. Acceptability is therefore <strong>not</strong> treated as "a residual was recorded" — only the residual <em>score</em> tokens are.</p> </li> <li> <p><strong>Gap derivation (<code>RiskTraceabilityService</code>).</strong> A risk with <strong>zero mitigating controls AND no residual score recorded AND acceptability == <code>acceptable</code></strong> is <strong>complete — "accepted without reduction"</strong> — and the "risk without control" flag must NOT fire (<code>acceptedWithoutReduction</code>, new derived flag; not stored). The other control-less cases are unchanged: a residual <em>score</em> recorded without a control still raises <code>residualWithoutControl</code>; a missing or <code>not-acceptable</code> acceptability without a control still raises the "risk without control" gap. The aggregate <code>risksWithoutControl</code> now counts only that genuine gap (it no longer double-counts a residual-without-control row, which has its own count). The panel/grid render the accepted-without-reduction row neutrally (a positive note, no red flag).</p> </li> </ul> <p>A companion UX fix in the same round (not an ADR-0079 semantic change): the completeness gap flags in the risk-traceability panel/grid gained an in-context <strong>remedy tooltip</strong> naming where and how to author the clearing link (e.g. "open the control's document as a draft and add an <em>Implemented by</em> link"), because the derivation was found correct — both control gaps clear the moment the correct edge is authored (proven end-to-end by <code>RiskTraceItemTest</code>) — so the reported "flags don't clear" was a discoverability problem, not a bug.</p> <h2 id="clarification-2-2026-07-19-implemented-by-targets-a-requirement-item-or-a-document">Clarification 2 (2026-07-19): <code>implemented-by</code> targets a requirement item OR a document<a class="headerlink" href="#clarification-2-2026-07-19-implemented-by-targets-a-requirement-item-or-a-document" title="Permanent link">¶</a></h2> <p>Decided by Nicolas (2026-07-19). The Stage-B <code>implemented-by</code> edge (risk-control → requirement) modelled the common case — a control realized by a <strong>product requirement</strong> — but ISO 14971 §7.1 recognises control <strong>kinds</strong> that are <em>not</em> implemented by a product requirement: an <strong>information-for-safety</strong> control (labelling, a warning, a user-manual instruction) or an <strong>organizational</strong> control (a training / operating procedure) is implemented by a <strong>procedure or work instruction</strong> — an SOP/WI <strong>document</strong>, not a requirement item. Forcing every control to name a requirement would either fabricate a requirement that does not exist or leave a genuinely-implemented control flagged "not implemented" forever.</p> <p><strong>Decision.</strong> An <code>implemented-by</code> link may target a <strong>requirement item</strong> (as in Stage B) <strong>OR a DOCUMENT</strong>. The <code>trace_link</code> table already carries the document-target shape (V055 — <code>target_document_id</code>, no key) that the type-agnostic link path stores, so this is <strong>no schema change</strong>: it is a picker + derivation + guidance change only.</p> <ul> <li><strong>Derivation (<code>RiskTraceabilityService</code>).</strong> A control's <code>implemented-by</code> links are resolved to a mixed list of implementation targets — a requirement key (resolved in the registry, as before) <strong>and</strong> a document target (rendered as its human id + title, resolved via the RLS-bounded doc display; an invisible/disposed target degrades to inert text, never a leak). The <strong>"control not implemented"</strong> gap clears when the control carries <em>any</em> <code>implemented-by</code> target of either form — a document target counts.</li> <li><strong>UI.</strong> For <code>implemented-by</code> the trace-links add-flow offers a target-mode toggle — <em>a requirement item</em> (the existing item autocomplete) OR <em>a document (SOP/WI)</em> (the shared RLS-scoped document typeahead) — and POSTs the <code>targetDocumentId</code> shape for a document. The risk-traceability panel/grid render document implementation targets distinctly (a document marker + the title on hover) alongside requirement keys. The <code>hintNotImplemented</code> remedy names <strong>both</strong> forms.</li> <li><strong>Scope.</strong> Only <code>implemented-by</code> is broadened to documents here (the control-realization edge). Other edges keep their existing target vocabularies; <code>verifies</code> already targets a document-level source or an item, unchanged.</li> </ul> <p><strong>Rationale.</strong> This aligns the tool with the 14971 control taxonomy — organizational / information-for-safety controls are implemented by procedures and labelling, which live as controlled <strong>documents</strong> in the QMS, not as product requirements. It keeps scoring/vocabulary as content (unchanged) and adds no attribute or table.</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="../adr-0078-generalized-trace-items/" class="md-footer__link md-footer__link--prev" aria-label="Previous: ADR-0078: Generalized Trace Items (Traceability Model — Stage A)"> <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"> ADR-0078: Generalized Trace Items (Traceability Model — Stage A) </div> </div> </a> <a href="../adr-0080-traceability-workspace/" class="md-footer__link md-footer__link--next" aria-label="Next: ADR-0080: Traceability Workspace — Hub, Sub-Pages, and Role-Gated Views"> <div class="md-footer__title"> <span class="md-footer__direction"> Next </span> <div class="md-ellipsis"> ADR-0080: Traceability Workspace — Hub, Sub-Pages, and Role-Gated Views </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>