Support design/generic docs, tables + risk register

.gitignore

@@ -166,3 +166,5 @@ test.pdf
 playwright/node_modules/
 *.webm
 playwright/test-results/
+
+coverage.lcov

README.md

@@ -9,6 +9,7 @@ By leveraging TraceFlow, you can:
 - Maintain your documentation in the same git repository as your code, ensuring version control and easy collaboration.
 - Automatically produce a "validation pack" containing all requirements, design, and test plans in PDF format.
 - Generate a traceability matrix linking all requirements to all tests.
+- Capture structured risk registers with requirement/test cross-links and colour-coded pre/post-mitigation risk levels.
 - Create fillable PDF forms for manual tests.
 - Run automated tests and capture their output as Markdown, then include them in the PDF report.
 - The result will look something [like this](example.pdf)
@@ -25,6 +26,9 @@ project/
   ├── design/
   │   ├── design.md
   │   └── ...
+  ├── risks/
+  │   ├── risk-register.md
+  │   └── ...
   └── tests/
       ├── test_plan.md
       └── ...
@@ -163,3 +167,33 @@ To address **REQ-003**, we will create a Python API for building and executing i
 - Functions to connect and execute pipeline components
 - Compliance checks to ensure the pipeline adheres to the required standards
 ```
+
+### Risk Register Example
+TraceFlow now understands risk registers and renders them on A3 landscape pages with colour-coded severity, probability, and residual risk ratings.
+
+```
+# Risk Register
+
+## RISK-001: Incorrect study-patient association
+
+Hazardous Situation: Clinician views wrong patient's images believing they are correct
+Harm: Misdiagnosis, inappropriate treatment
+Cause: Race condition during HL7/DICOM message processing leading to incorrect PatientID or AccessionNumber assignment
+Severity: High
+Probability: Medium
+Controls: Unit/integration tests for identifier logic (REQ-005, TEST-002)
+Residual Severity: Medium
+Residual Probability: Low
+Residual Risk: Operator review plus automatic quarantine when mismatches occur
+```
+
+### Generic Document Example
+Any additional Markdown files (e.g., Installation/User Specifications) are included verbatim and can link to requirements, tests, or risks using their IDs:
+
+```
+# Installation & User Specification
+
+- Execute TEST-003 and record the release tag.
+- Confirm the identifier reconciliation feature (REQ-005) is active before go-live.
+- Review RISK-001 and RISK-002 residual risk statements with the clinical safety officer.
+```

examples/design/design-spec.md

@@ -1,25 +1,62 @@
 # Functional Design Spec
 
-## User Authentication
+This document provides a high-level architectural view of the TraceFlow demo and links each design decision to the requirements, tests, and clinical safety risks that drive them. Refer to **RISK-001** when assessing identifier safety controls described below.
 
-To address **REQ-001**, we will implement an authentication system using JWT (JSON Web Tokens). The system will include the following components:
+## Architecture overview
 
-- A login page with input fields for email and password
-- A backend API endpoint to validate user credentials
-- Middleware to validate JWT tokens for accessing protected resources
+The system is split into ingestion, orchestration, and presentation tiers in order to satisfy **REQ-001** through **REQ-004** while maintaining a clean boundary for audit logging (**REQ-005**).
 
-## MRI Dataset Import
+```mermaid
+graph TD
+    subgraph Ingestion
+        HL7[HL7 listener]
+        DICOM[DICOM listener]
+    end
+    subgraph Core Platform
+        Auth[Auth Service]
+        Reconcile[Identifier Reconciliation Engine]
+        Pipeline[Analysis Pipeline API]
+        Audit[Audit Ledger]
+    end
+    subgraph Presentation
+        UI[Clinician UI]
+    end
+    HL7 --> Reconcile
+    DICOM --> Reconcile
+    Reconcile --> Audit
+    Reconcile --> Pipeline
+    Auth --> UI
+    Pipeline --> UI
+    UI --> Audit
+```
 
-To address **REQ-002**, we will develop a module to import MRI datasets in DICOM format. The module will include:
+## Identifier reconciliation engine (REQ-005, RISK-001, TEST-002)
 
-- A function to parse DICOM files
-- Error handling for unsupported or malformed files
-- Integration with the existing data storage system
+The reconciliation engine protects against the hazardous situation captured in **RISK-001** where patient and study identifiers might be mismatched. Design goals:
 
-## Image Analysis Pipeline
+- Compare the DICOM `PatientID` and `AccessionNumber` with the HL7 metadata stream.
+- If mismatches are detected, the transaction is quarantined and **TEST-002** exercises the operator override.
+- Successful transactions emit structured audit events so **REQ-005** is met.
 
-To address **REQ-003**, we will create a Python API for building and executing image analysis pipelines. This API will include:
+### UML activity view
 
-- A set of Python classes to represent pipeline components
-- Functions to connect and execute pipeline components
-- Compliance checks to ensure the pipeline adheres to the required standards
+1. Receive the incoming DICOM objects and perform schema checks.
+2. Compare HL7 metadata with extracted tags and branch depending on whether identifiers match.
+3. Persist successful studies and emit reconciliation metrics for **RISK-001**.
+4. Quarantine mismatches and require an operator acknowledgement that is captured by **TEST-002**.
+
+## Authentication and authorization (REQ-001, TEST-001)
+
+Authentication relies on OpenID Connect so automated tests (**TEST-001**) can exercise both success and failure paths. Tokens carry the clinician's study permissions, and the middleware enforces them for every API endpoint.
+
+## Imaging pipeline (REQ-002, REQ-003, RISK-002)
+
+The MRI import module normalizes DICOM before invoking the analysis pipelines described in **REQ-003**. The pipelines emit validation artifacts:
+
+- DICOM specific logs for regulatory review.
+- Image-derived measurements tied to their source requirement/test pairs.
+- Alerts for saturation or out-of-range values, contributing to **RISK-002** mitigations.
+
+## Operational documents (General IUS)
+
+Operational guidance for installations is maintained in `docs/ius.md`. That supplemental document links directly to **TEST-003** for continuous integration evidence and references **RISK-002** to remind the operator of the residual hazards.

examples/docs/ius.md

@@ -0,0 +1,28 @@
+# Installation & User Specification
+
+This generic operational document demonstrates how TraceFlow can include arbitrary Markdown artifacts that link back to requirements, tests, and risks.
+
+## Installation checklist
+
+1. Deploy the ingestion stack and confirm that the `traceflow` service exposes `/healthz`.
+2. Verify that authentication (**REQ-001**) succeeds for a clinical account with the `clinician` role by following **TEST-001**.
+3. Enable the identifier reconciliation engine (**REQ-005**) and record the resulting audit entry.
+4. Capture Playwright evidence from **TEST-003** and attach it to the release ticket.
+
+## Operational monitoring
+
+- Operators review the reconciler dashboard hourly to ensure the guardrails for **RISK-001** and **RISK-002** remain in place.
+- When a mismatch occurs, follow the escalation steps documented in the clinical SOP and reference the impacted **REQ-005** controls.
+- Residual risks shall be re-evaluated whenever a new modality is onboarded.
+
+## Traceability table
+
+| Step                                    | Linked Requirement/Test | Linked Risk |
+|-----------------------------------------|-------------------------|-------------|
+| Configure audit webhooks                | REQ-005                 | RISK-001    |
+| Re-run integration suite after upgrade  | TEST-003                | RISK-002    |
+| Attach validation pack to submission    | TEST-001 / TEST-002     | RISK-003    |
+
+## Sign-off
+
+The implementation owner confirms that installation and operational verification were executed per procedure and that the TraceFlow validation pack is archived with the evidence references listed above.

examples/requirements/basic-requirements.md

@@ -14,7 +14,7 @@ $$ H = L \times \log_2(N) $$
 
 Where $H$ is the entropy, $L$ is the password length, and $N$ is the number of possible symbols.
 
-### Example inline code formatting
+### Example inline code formatting
 
 The ID of the user is, e.g., `1af345e6`.
 
@@ -47,15 +47,39 @@ def hello_world():
     print("Hello world!")
 ```
 
-## REQ-004: Output data
+## REQ-004: Output data
 
 The platform must be able to export the results of image analysis pipelines in a standard format, including the following parameters:
 
 
 | **DICOM Series**       | **Key Parameters**              | **Typical Parameters**                                        | **Map to Image Type** |
 |------------------------|---------------------------------|---------------------------------------------------------------|-----------------------|
-| T1 VFA                 | TR, TE, FA                      | 96x96x24<br><br>FA=2°,17°,32°                                 | `vfa`                 |
-| High-res pre-contrast  | TR, TE, FA                      | 512x512x92<br><br>FA=32°                                      | `high-res-pre`        |
-| T1-weighted dynamic    | TR, TE, FA, Temporal resolution | 96x96x24 <br><br>FA=17°<br><br>Temporal resolution: 2s to 10s | `dynamic-uncorrected` |
-| High-res post-contrast | TR, TE, FA                      | 512x512x92<br><br>FA=32°                                      | `high-res-post`       |
+| T1 VFA                 | TR, TE, FA                      | 96x96x24 FA=2°,17°,32°                                        | `vfa`                 |
+| High-res pre-contrast  | TR, TE, FA                      | 512x512x92 FA=32°                                             | `high-res-pre`        |
+| T1-weighted dynamic    | TR, TE, FA, Temporal resolution | 96x96x24  FA=17° Temporal resolution: 2s to 10s               | `dynamic-uncorrected` |
+| High-res post-contrast | TR, TE, FA                      | 512x512x92 FA=32°                                             | `high-res-post`       |
 
+## REQ-005: Patient-study reconciliation
+
+The ingestion service shall ensure that study metadata stays associated with the correct patient identifier to reduce **RISK-001** and **RISK-002**.
+
+- Cross-validate the incoming HL7 and DICOM identifiers before persisting them.
+- Flag mismatches for operator review and capture evidence via TEST-002.
+- Provide a reconciliation webhook so downstream systems can resynchronize identifiers.
+
+### Example sequence diagram
+
+```mermaid
+sequenceDiagram
+    participant PACS
+    participant TraceFlow
+    participant Operator
+    PACS->>TraceFlow: DICOM C-STORE (StudyUID=123)
+    TraceFlow->>TraceFlow: Validate identifiers (REQ-005)
+    alt Identifier mismatch
+        TraceFlow->>Operator: Alert referencing TEST-002
+        Operator->>TraceFlow: Accept or reject mapping
+    else Identifiers aligned
+        TraceFlow-->>PACS: ACK with audit log entry
+    end
+```