# Verixa — User Requirements Specification # Module 21: Findings | Field | Value | |---|---| | Document ID | VRX-URS-21 | | Version | 1.0 | | Status | Final — ready for QA, Validation, Regulatory Affairs, Information Security, Manufacturing Head, Clinical / PV Head, Site Quality Lead, and Founder approval. URS approval is separate from validation execution. This document becomes "Approved Controlled URS — released for engineering implementation and validation planning" only after signature capture in the Document Approval block. It becomes "Released for validation execution" only after the module migration evidence gate (URS-21-VAL-008) and validation evidence pack are satisfied. | | Document Type | User Requirements Specification (URS) | | GAMP 5 Category | Category 5 — Custom Application | | Code Modules | Target implementation binding: expected primary code module `findings`, expected API mounts `/api/v1/findings/*` and `/api/v1/reviews/:reviewId/findings/*` (parent-scoped), expected reviews integration through the `reviews` module (URS-20 sibling) for parent-review status-gated creation, expected event-bus emission for `finding_created`, `finding_status_changed`, `finding_capa_linked`, expected MIRA context integration through the `useMiraRecord('finding', id)` mapping, expected investigations hook for evidence-gathering escalation, expected Authority Profile + HITL + e-signature integration through the `authority` and `hitl` subsystems for non-bypassable disposition / closure, expected CAPA-linkage UI through the `findings` linked-CAPA list. Implementation evidence remains subject to repository verification and validation evidence. | | Architecture Bindings | This module is subject to **ARCH-AI-001 AI Optionality and Manual Continuity**. Verixa internally classifies this AI surface as **high-risk under internal AI governance**, aligned with the high-risk classification approach in **EU AI Act (Regulation 2024/1689) Annex III**, unless a jurisdiction-specific legal assessment determines otherwise — escalated under Annex III when the finding feeds a CAPA (URS-18), inspection response (URS-22), or compliance disposition. AI-assisted findings surfaces (AI finding classification, AI severity suggestion, AI CAPA-linkage recommendation, MIRA findings copilot, AI investigations hook) are advisory only under internal AI governance aligned with EU AI Act Article 13 transparency principles. Every AI surface shall provide a fully functional manual finding path; finding creation, classification, severity assignment, CAPA linkage, reviewer e-signature, and closure shall be executable when AI services are disabled, degraded, or overridden by the reviewer or CAPA owner. **No AI service shall be the sole path to classify, dispose, or close a finding.** This module binds ARCH-AI-001 AC-2, AC-3, AC-4, and AC-7. Verixa treats **EU GMP Annex 22 Draft 2025** as an internal forward-looking architectural control (not an enacted predicate rule); under that internal control, generative / probabilistic AI is **PROHIBITED** in finding-classification disposition, severity-driven escalation decisions, CAPA-linkage decisions, and closure decision paths. Static deterministic AI may surface similar prior findings and historical classification patterns; the reviewer's signed disposition is the system of record. Jurisdiction-specific legal enforceability of Annex 22 and the EU AI Act remains subject to a future jurisdiction-specific legal assessment. | | Regulatory Classification | Critical infrastructure substrate — operates the canonical Findings register, the finding lifecycle state machine (`open → in_progress → resolved | deferred → closed`; reopen is a governed transition event from `closed → in_progress` per DEC-21-22 + SoD-21-06 that appends a new investigation iteration and does not mutate or erase the prior closed evidence), the severity classification (`critical` / `major` / `minor` / `observation`) with severity-driven authority gating, the parent-linkage controls (review per URS-20 — primary; standalone findings creatable per DEC-21-04), the multi-dimensional context capture (`study_id`, `site_id`, `product_id`, `supplier_id`, `batch_id`, `project_id`, `process_scope`), the regulation-reference field linking findings to predicate-rule clauses, the controlled response and evidence capture, the linked-CAPA association to URS-18 with severity-gated mandatory CAPA for `critical` / `major` per DEC-21-09, the investigations hook to URS-17 RCA for evidence-gathering escalation, the Authority Profile + HITL + e-signature gates on every status transition, the post-closure record immutability across the finding header and linked CAPA references, the controlled reopen workflow with executive authority co-sign, the MIRA copilot read-only context integration on finding records, and the per-jurisdictional regulatory expectations under FDA 21 CFR Part 11, EU GMP Annex 11 §16 (incident management), MHRA Data Integrity, ICH Q10 §3.2.1 (CAPA system), ISO 19011 (audit principles), and FDA 483 / EIR observation handling. | | Date of Issue | 2026-05-06 | | Module Owner (Engineering) | Quality / Findings Squad | | Module Owner (Quality Validation) | CSV / CSA Lead — Findings | | Module Owner (Compliance) | Quality Assurance, Manufacturing, Clinical / Pharmacovigilance, Regulatory Affairs | | Approving Authority | Founder / Chairman & MD; QA Head; Manufacturing Head; Clinical / PV Head; Validation Head; RA Head; Information Security Head; Site Quality Lead | --- ## 0. Document Framing ### 0.1 Purpose of this document This URS defines the target expected state for Verixa's Findings module (Module 21). It is the binding contract between product, engineering, quality validation, regulatory affairs, manufacturing, clinical / pharmacovigilance, distribution, laboratory operations, information security, and the executive authority for the design, implementation, validation, release, and on-going periodic review of the regulated findings substrate: the canonical Findings register; the lifecycle state machine (`open → in_progress → resolved | deferred → closed` with reopen as a governed transition event from `closed → in_progress` per executive authority co-sign + reason — DEC-21-22 + SoD-21-06 — that appends a new investigation iteration without mutating or erasing the prior closed evidence; `deferred → resolved` and `deferred → closed` are governed transitions per DEC-21-02); the severity classification (`critical` / `major` / `minor` / `observation`) with severity-driven authority gating per DEC-21-08; the parent-linkage controls (review per URS-20 — primary; standalone findings creatable for findings that arise from inspection observations per URS-22, complaint trends per URS-14, or proactive observations —); the multi-dimensional context model (`study_id`, `site_id`, `product_id`, `supplier_id`, `batch_id`, `project_id`, `process_scope`) with at least one scope anchor required and aligned with the platform context filter; the regulation-reference field (`regulation_ref`) linking findings to predicate-rule clauses (e.g., `21 CFR 211.192`); the controlled response and evidence capture with reviewer-signed evidence references; the linked-CAPA association to URS-18 with severity-gated mandatory CAPA for `critical` and `major` findings per DEC-21-09; the investigations hook to URS-17 RCA for evidence-gathering escalation; the Authority Profile + HITL + e-signature gates on every status transition extracted from any user-role string comparison; the bound e-signature persistence on resolution and closure; the post-closure record immutability across the finding header and linked CAPA references; the controlled reopen workflow with executive authority co-sign; the parent-review status-gating per URS-20 DEC-20-08 (findings creatable only while parent review is in `draft` or `under_review`); the MIRA copilot read-only context integration through `useMiraRecord('finding', id)`, with no MIRA write paths; the audit trail coverage with reason-for-change discipline; the canonical-status-model alignment; and the per-jurisdictional regulatory expectations. Compliance with this URS is mandatory. ### 0.2 Audience Engineering, QA, RA, Manufacturing, Clinical / Pharmacovigilance, Distribution, Laboratory Operations, Validation, Information Security, executive authority, the platform's Implementation team, internal and external auditors, and inspectors from regulatory bodies (FDA, EMA, MHRA, Health Canada, CDSCO, PIC/S, PMDA). The plain-language primer (§0.4) and worked examples (§3.5) make Module 21 accessible to non-domain engineers, product owners, validation engineers, and quality investigators. ### 0.3 Cross-references - **URS-01** Authentication, Session & Access Control — identity envelope for every finding mutation - **URS-02** RBAC & Permissions — the `findings:*` permission set - **URS-03** Context Gate & Approval Scope — context-gate enforcement for finding scope dimensions - **URS-04** Workflow / HITL / E-Signature / Approval Authority — Controlled Approval Modal contract for finding resolution / closure / reopen - **URS-05** Authority Profile / Delegation / SoD — Authority Profiles consumed (`finding_owner_authority`, `finding_review_authority`, `final_quality_approver`, `executive_authority`) - **URS-06** Audit Trail / Hash Chain / Tamper-Evident — append-only audit substrate - **URS-07** Study Management — study-scope dimension consumed - **URS-08** Tenant Management Lifecycle — tenant context for finding records - **URS-09** Site / Facility Management — site-scope dimension consumed - **URS-10** Product / SKU / Drug Master Data — product-scope dimension consumed - **URS-11** Supplier Management — supplier-scope dimension consumed; supplier-finding source - **URS-12** Document Control / SOP — affected-document linkage; closure-evidence document references - **URS-13** Change Control — finding-precipitated change linkage where mitigation requires platform change - **URS-14** Complaints — complaint-trend finding source - **URS-15** OOS / OOT — OOS-trend finding source - **URS-16** Deviations — deviation-trend finding source - **URS-17** RCA — investigations hook for root-cause analysis where finding requires investigation - **URS-18** CAPA — primary downstream consumer; linked-CAPA association with severity-gated mandatory CAPA per DEC-21-09 - **URS-19** Risk Assessment — risk-assessment-precipitated finding source - **URS-20** Reviews — primary parent linkage with status-gated creation per URS-20 DEC-20-08 - **URS-22** Inspection Mgmt — audit-observation finding source (FDA 483 / EIR observations); inspection-readiness export - **URS-23** Batch Records — batch-scope dimension consumed - **URS-26** APQR — periodic finding consumer - **URS-30** Notifications — notification delivery for finding lifecycle events - **URS-32** MIRA AI — read-only MIRA copilot context integration on finding records - **URS-35** Infrastructure / Backup-Restore — operational continuity ### 0.4 Plain-language primer In a regulated pharmaceutical operation, **a finding is the documented observation of a non-conformance, gap, or improvement opportunity**. Findings arise from internal audits, vendor audits, regulatory inspections (FDA 483 observations, EU GMP inspection observations, EIR findings, MHRA findings), CSV reviews, periodic process reviews, complaint trends, OOS trends, deviation trends, and risk-assessment outputs. Each finding requires structured handling under **21 CFR Part 11, EU GMP Annex 11 §16 (Incident Management), ICH Q10 §3.2.1 (CAPA system), MHRA Data Integrity Guidance, and ISO 19011 (audit principles)**: (1) document the finding with severity and regulation reference, (2) assign an owner, (3) gather evidence and capture a response, (4) link a CAPA where severity warrants (mandatory for `critical` / `major`), (5) escalate to RCA where root-cause investigation is required, (6) resolve with reviewer-signed evidence, and (7) close only after the linked CAPA is closed (where applicable). Module 21 is the target specification for this regulated workflow. The most common mistake in regulated finding handling is **closure without CAPA**. The regulator's tell-tale at inspection is a `critical` or `major` finding marked `closed` with no linked CAPA in URS-18 or with the linked CAPA still open. Module 21 enforces the pathway: severity-gated mandatory CAPA per DEC-21-09 (every `critical` and `major` finding MUST have at least one linked CAPA before resolution); closure requires the linked CAPA to be in terminal status (per URS-18 lifecycle); reopen is a governed transition that appends a new investigation iteration without erasing the prior closed evidence; finding creation against a parent review is gated by parent-review state per URS-20 DEC-20-08. The **AI-assistance** dimension is critical. Static deterministic AI may surface "similar prior findings" or "historical classification patterns by source type" or "suggested CAPA links from prior findings" as advisory help. Generative AI (LLMs / MIRA copilot) is **prohibited** from writing to the finding classification, severity assignment, CAPA-linkage decision, or closure decision under the internal Annex 22 Draft 2025 forward-looking AI governance control. MIRA copilot may read closed findings for read-only context via `useMiraRecord('finding', id)` but no AI service writes to `findings` tables. The signed disposition is the system of record, attributable to the human reviewer. The **two-step release path** mirrors every other Module: this URS becomes "Approved Controlled URS — released for engineering implementation and validation planning" upon signature capture in the Document Approval block; it becomes "Released for validation execution" only after URS-21-VAL-008 (Migration Evidence Gate) and the §17 validation evidence pack are satisfied. ### 0.5 Conventions Each requirement has a unique identifier. "MUST" denotes a mandatory requirement; "SHOULD" denotes a strong recommendation; "MAY" denotes an option. The document is self-contained: front end (§5), back end (§6), data model (§6.2), application programming interface (§6.3), workflow (§6.4), business rules (§6.5), audit (§6.6), security (§12), regulatory mapping (§14), test cases (§16), and validation evidence (§17) are all in this single file. Every requirement is mandatory unless explicitly marked SHOULD or MAY. ### 0.6 Glossary | Term | Definition | |---|---| | Finding | A documented observation of a non-conformance, gap, or improvement opportunity arising from a review, audit, inspection, complaint trend, OOS trend, deviation trend, or risk assessment. | | Severity | The categorical classification of finding impact: `critical` / `major` / `minor` / `observation`. | | Regulation reference | The predicate-rule clause cited in the finding (e.g., `21 CFR 211.192`, `EU GMP Annex 11 §16`). | | Parent review | The URS-20 review record under which the finding was created; nullable for standalone findings. | | Standalone finding | A finding created without a parent review (typically from inspection observations per URS-22, complaint trends per URS-14, or proactive observations); requires explicit source-type capture. | | Linked CAPA | A URS-18 CAPA record associated to the finding; severity-gated mandatory for `critical` / `major` per DEC-21-09. | | Investigations hook | The `findings:trigger_investigation` route that escalates a finding to URS-17 RCA for root-cause analysis. | | Response | The narrative response to the finding describing the planned remediation; reviewer-signed at status transition. | | Evidence | Document references and observations supporting the finding; reviewer-signed at resolution. | | Resolution | The narrative resolution at `in_progress → resolved` transition; reviewer-signed; preserves attribution. | | Deferred | A controlled lifecycle state for findings whose remediation is intentionally deferred per DEC-21-02; requires justification. | | Reopen | A governed transition event from `closed → in_progress` requiring executive authority co-sign and documented reason; appends a new investigation iteration without mutating prior closed evidence. | | Reviewer independence | The Segregation-of-Duties enforcement that the finding closer MUST NOT be the finding creator (SoD-21-04). | | ARCH-AI-001 | Platform architecture binding requiring manual continuity for every AI surface (AC-1.AC-7). | | Annex 22 | EU GMP Annex 22 (Draft 2025). Verixa treats Annex 22 and EU AI Act high-risk / transparency concepts as internal forward-looking AI governance controls unless a jurisdiction-specific legal assessment determines otherwise. Under the internal control, generative / probabilistic AI is prohibited in finding classification, severity assignment, CAPA-linkage decision, and closure decision paths. Binding predicate-rule obligations remain those listed in §14. | | MIRA | The platform's read-only AI copilot service; for Module 21 MIRA is read-only context on finding records via `useMiraRecord('finding', id)`. | ### 0.7 Module-21 architectural picture ```mermaid flowchart TD U[Reviewer / Finding Owner / Closure Authority] --> FN[/Findings register/] FN --> SEV[Severity classification] FN --> RSP[Response + Evidence] FN --> CAPA_LINK[Linked CAPAs - mandatory for critical/major] FN --> INV[Investigations hook to URS-17 RCA] FN --> RESOLVE[Resolution HITL + bound e-sign + SoD-21-03] FN --> CLOSE[Closure HITL + bound e-sign + SoD-21-04 + linked-CAPA terminal check] CLOSE -. governed reopen + executive co-sign.-> FN M20[URS-20 Reviews - primary parent linkage] --> FN M22[URS-22 Inspection Observations] --> FN M14[URS-14 Complaint Trends] --> FN M15[URS-15 OOS Trends] --> FN M16[URS-16 Deviation Trends] --> FN M19[URS-19 Risk Assessment Outputs] --> FN FN --> M18[URS-18 CAPA linked] FN -. investigations hook.-> M17[URS-17 RCA] FN -. mitigation precipitates change.-> M13[URS-13 Change Control] M30[URS-30 Notifications] <-- FN M32[URS-32 MIRA AI] <-- FN (read-only context) M26[URS-26 APQR] <-- FN ARCHAI[ARCH-AI-001] -.governs advisory AI.-> FN ANNEX22[Internal Annex 22 control — forward-looking; not enacted predicate rule] -.governs.-> SEV ANNEX22 -.governs.-> CAPA_LINK ANNEX22 -.governs.-> RESOLVE ANNEX22 -.governs.-> CLOSE AIAct[Internal EU AI Act Annex III high-risk classification — forward-looking] -.classifies.-> FN ``` Diagram 0.7-A — Module 21 architectural picture. The target `findings` code module is the expected owner of the findings register, lifecycle, severity classification, parent-linkage to URS-20 reviews (primary) and standalone source linkage, multi-dimensional context, response + evidence capture, linked-CAPA association with severity-gated mandatory CAPA, investigations hook to URS-17 RCA, Authority Profile + HITL + e-signature gates on every status transition, MIRA context integration, and reopen; ownership is target binding and remains subject to repository verification and validation evidence. Verixa treats EU GMP Annex 22 Draft 2025 and EU AI Act high-risk / transparency concepts as internal forward-looking AI governance controls unless a jurisdiction-specific legal assessment determines otherwise; under the internal control, generative AI is prohibited in finding classification / severity / CAPA-linkage / resolution / closure decision paths and the module is internally classified high-risk AI. ARCH-AI-001 governs advisory deterministic AI in similarity / signal surfacing. Binding predicate-rule obligations remain those listed in §14. ### 0.8 Entity-relationship overview ```mermaid flowchart LR FN[(findings)] --> CL[(finding_capa_links)] FN --> EV[(finding_evidence_refs)] FN --> LCE[(finding_lifecycle_events)] FN --> APPR[(finding_approvals)] FN --> NOTES[(finding_transition_notes)] RV[(URS-20 reviews via review_id FK)] --> FN M22[(URS-22 inspection observations via source_id)] --> FN M18[(URS-18 capas via finding_capa_links)] <-- FN M17[(URS-17 rcas via investigations hook)] <-- FN ``` Diagram 0.8-A — Module 21 entity-relationship overview. The target `findings` code module is the expected owner of 5 tables (finding header, CAPA-linkage, evidence references, lifecycle events with notes, approvals signature-slot); parent reviews owned by URS-20 with FK linkage; CAPAs owned by URS-18 with linkage table; RCAs owned by URS-17. Ownership is target binding and remains subject to repository verification and validation evidence. URS-06 substrate is consumed for audit; URS-04 HITL + e-signature subsystem is consumed for non-bypassable resolution / closure and bound signature persistence. --- ## 1. Document Control This document is the User Requirements Specification (URS) for Verixa Module 21 — Findings. The document is controlled per URS-12; all revisions follow URS-12 versioning and approval. Approval and signature evidence is captured in the Document Approval block at the end of this document. Distribution is governed by URS-12 entitlement; the document is read-accessible to all Verixa internal staff and to authorised external auditors / inspectors at the platform administrator's discretion under the existing inspection-readiness export pattern of URS-22. Version 1.0 is the launch version. Future revisions follow URS-13 Change Control with the `module_21_specification` change-class tag. --- ## 2. Scope ### 2.1 In scope #### Findings Registry - The Findings master registry per DEC-21-01: per-tenant registry with `id`, `tenant_id`, `display_id` (server-authoritative `FND-{YYYY}-{nnnnnn}` per DEC-21-03), `title`, `description`, `severity` (`critical` / `major` / `minor` / `observation`), `status` (`open` / `in_progress` / `resolved` / `deferred` / `closed`), `regulation_ref`, `source_type` (`review` / `inspection_observation` / `complaint_trend` / `oos_trend` / `deviation_trend` / `risk_assessment` / `proactive_observation`), `source_id` (nullable for `proactive_observation`; required for review-source — corresponds to `review_id`), `review_id` (FK URS-20 nullable; populated when source_type = `review`), `study_id` (FK URS-07 nullable), `site_id` (FK URS-09 nullable), `product_id` (FK URS-10 nullable), `supplier_id` (FK URS-11 nullable), `batch_id` (FK URS-23 nullable), `project_id` (nullable), `process_scope`, `assigned_to_user_id` (nullable until assigned), `response`, `evidence_jsonb` (array of evidence references), `due_date`, `resolution` (nullable), `defer_justification` (nullable; required when `deferred`), `created_by`, `created_at`, `updated_at`, `resolved_at` (nullable), `resolved_by_user_id` (nullable), `resolved_e_sig_id` (nullable), `closed_at` (nullable), `closed_by_user_id` (nullable), `closed_e_sig_id` (nullable), `closure_rationale` (nullable), `deleted_at` (nullable; for soft-delete). **At least one scope anchor** (`study_id`, `site_id`, `product_id`, `supplier_id`, `batch_id`, `project_id`, or `process_scope`) is required. - Server-authoritative race-safe finding number per DEC-21-03 via DB sequence. #### Source Linkage and Standalone-Finding Support - Source-linkage validation per DEC-21-04: every finding MUST be linked to one source (`source_type` non-null). The controlled gate is required: `review_id` is required on every review-attached finding via the parent-scoped route, and standalone findings are supported via a dedicated standalone create route for `source_type ∈ {inspection_observation, complaint_trend, oos_trend, deviation_trend, risk_assessment, proactive_observation}`. For `source_type = review`, the parent-scoped route remains primary and `review_id` MUST be populated; for non-review sources, `source_id` MUST reference the corresponding URS-22 / URS-14 / URS-15 / URS-16 / URS-19 record. - Cross-tenant source linkage is forbidden: the linked source record MUST be in the same tenant as the finding being created. - Parent-review status-gated creation per URS-20 DEC-20-08: when `source_type = review`, finding creation is permitted only while the parent review is in `draft` or `under_review`; attempts on `pending_approval`, `approved`, `rejected`, or `closed` review return `FINDING_CREATION_BLOCKED_BY_REVIEW_STATE`. #### Finding Lifecycle - Lifecycle state machine per DEC-21-02: `open → in_progress → resolved | deferred → closed`; allowed transitions are: `open → in_progress`, `open → resolved` (with required `resolution`), `open → deferred` (with required `defer_justification`), `in_progress → resolved` (with required `resolution`), `in_progress → closed`, `in_progress → deferred`, `resolved → closed`, `deferred → resolved` (with required `resolution`), `deferred → closed`. Reopen is a governed transition event from `closed → in_progress` per DEC-21-22 + SoD-21-06 that appends a new investigation iteration and a new lifecycle event without mutating or erasing the prior closed evidence. **Reopen MUST NOT erase the prior closed evidence.** - Each transition is electronically signed; all transitions log dual-write to `finding_lifecycle_events` + URS-06 substrate. - Canonical-status alignment per DEC-21-23: the canonical state set (`open`, `in_progress`, `resolved`, `deferred`, `closed`) MUST be aligned across `packages/backend/src/modules/findings/workflow.ts`, `packages/backend/src/modules/findings/service.ts`, `packages/shared/src/types/db.ts`, and `packages/frontend/src/api/hooks/useFindings.ts`. #### Severity Classification and Severity-Driven Authority Gating - Severity classification per DEC-21-08: `critical` / `major` / `minor` / `observation`. Severity is captured at create and is immutable post-resolution; severity changes during `open` or `in_progress` require reason-for-change. - Severity-driven authority gating: `critical` findings require `final_quality_approver` + executive authority co-sign at closure per DEC-21-21 + SoD-21-07; `major` findings require `final_quality_approver` at closure; `minor` and `observation` findings require `qa_reviewer` at closure. #### Severity-Gated Mandatory CAPA - Severity-gated mandatory CAPA per DEC-21-09: every `critical` and `major` finding MUST have at least one linked CAPA (URS-18) before the finding can transition to `resolved`. Attempts to transition `open → resolved`, `in_progress → resolved`, or `deferred → resolved` without a linked CAPA on a `critical` or `major` finding MUST return `LINKED_CAPA_REQUIRED_FOR_SEVERITY`. Linked CAPAs are persisted in `finding_capa_links` (entity per DEC-21-10). #### CAPA Linkage - CAPA-linkage entity per DEC-21-10: `id`, `tenant_id`, `finding_id`, `capa_id` (FK URS-18), `link_type` (`primary_remediation` / `preventive_action` / `parallel_capa`), `linked_by_user_id`, `linked_at`, `unlinked_at` (nullable), `unlinked_by_user_id` (nullable), `unlink_reason` (nullable). Findings emit `finding_capa_linked` event when a CAPA is associated; URS-18 service receives the event and may auto-populate the CAPA's source linkage to this finding. - Closure-prerequisite per DEC-21-16: before a finding can transition `resolved → closed` (and `in_progress → closed` and `deferred → closed`), all linked CAPAs MUST be in terminal status (`closed` per URS-18 lifecycle). Attempts to close with open linked CAPAs return `FINDING_CLOSURE_BLOCKED_BY_OPEN_LINKED_CAPAS`. #### Investigations Hook - Investigations hook per DEC-21-11: the `POST /findings/:id/trigger-investigation` route escalates a finding to URS-17 RCA for root-cause analysis. Service creates a new RCA via the URS-17 service with `source_type = 'finding'` and `source_id = finding_id`; URS-21 audit records `FINDING_INVESTIGATION_TRIGGERED`. The created RCA's id is stored on the finding for traceability. #### Authority + HITL + E-Signature on Status Transitions - Authority gate per DEC-21-06: every status transition MUST go through `withAuthority(.)` Authority Profile resolution and the Controlled Approval Modal e-signature contract (URS-04). The controlled gate's workflow validation MUST be augmented with the controlled authority gate. SoD-21-03 enforced at resolution (resolver ≠ creator for `critical` / `major`); SoD-21-04 enforced at closure (closer ≠ creator). - HITL decision orchestration per DEC-21-07: every resolution / closure / reopen transition MUST create a HITL decision record in the URS-04 platform `hitl` subsystem with `entity_type = 'finding'`, `entity_id = finding_id`. - Bound e-signature persistence per DEC-21-13: resolution persists `resolved_e_sig_id` and `resolved_by_user_id`; closure persists `closed_e_sig_id` and `closed_by_user_id`. #### Transition Notes Capture - Transition notes capture per DEC-21-14: every status transition MUST persist a `notes` payload in `finding_transition_notes` with `from_state`, `to_state`, `note_text`, `note_signed_by_user_id`, `note_signed_at`, `note_signed_e_sig_id`. The controlled gate is required: transition notes MUST be persisted and audited. #### Final-State Immutability - Post-closure immutability per DEC-21-15: once a finding reaches `closed` (the IMMUTABLE_STATUS), the finding header, evidence references, and CAPA-linkage records become immutable. Any mutation attempt MUST return `FINDING_IMMUTABLE_FINAL_STATE` with the 21 CFR Part 11 §11.10(e) message. This guard applies via `assertFindingMutable(.)` on every mutation route. #### Closure - Finding closure per DEC-21-16: closure requires the finding to be in `resolved` or `deferred` state (or `in_progress` for non-mandatory-CAPA findings per DEC-21-02), all linked CAPAs in terminal status, and a closure-rationale captured. Closure is e-signed by the closure authority appropriate to severity (`final_quality_approver` for `critical` / `major`; `qa_reviewer` for `minor` / `observation`); SoD-21-04 enforced (closure authority ≠ creator). #### Reopen - Reopen per DEC-21-22: reopen is a governed transition event from `closed → in_progress`; requires `executive_authority` co-sign + documented reason; appends a new lifecycle event and a new investigation iteration; **does NOT mutate or erase the prior closed evidence**. SoD-21-06 enforced: the executive-authority reopen co-signer cannot be the original closure authority. #### Multi-Dimensional Context - Context model per DEC-21-17: `MODULE_CONTEXT_CONFIG['finding']` declares `study`, `site`, `product`, `supplier`, `batch`, `project` filtering as applicable per scope dimensions captured on the registry record. The persistence layer MUST persist `study_id`, `site_id`, `product_id`, `supplier_id`, `batch_id`, `project_id`, `process_scope` per the registry schema (resolves audit context-filter vs persistence conflict). #### AI Architecture Binding - AI architecture binding per DEC-21-18: NO direct LLM / generative AI write to `findings`, `finding_capa_links`, or `finding_evidence_refs`. Static deterministic AI MAY surface "similar prior findings", "historical classification patterns by source type", "suggested CAPA links from prior findings", and "suggested severity from prior findings" as advisory; advisory output is visibly labelled per ARCH-AI-001 AC-3 and never autonomously writes per AC-4. MIRA copilot read-only context for closed findings via `useMiraRecord('finding', id)` is permitted; MIRA write paths are prohibited. #### Audit Trail - Audit trail per DEC-21-19: every finding mutation (create, update, response / evidence capture, status transition with notes, severity change with reason, CAPA link / unlink, investigation trigger, resolve, close, reopen, soft delete) emits `auditTrailService.log(.)` to the URS-06 hash-chained audit substrate with `tenantId`, `userId`, `action`, `resourceType`, `resourceId`, `details` (before-state and after-state for UPDATEs), `ipAddress`, `timestamp`. Reason-for-change captured for every UPDATE to a regulated field after `open`. ### 2.2 Out of scope - CAPA workflow itself (forward URS-18 CAPA — Module 21 owns the linked-CAPA association but URS-18 owns CAPA lifecycle). - RCA workflow itself (forward URS-17 RCA — Module 21 owns the investigations hook but URS-17 owns RCA lifecycle). - Inspection-programme management (forward URS-22 Inspection Mgmt — Module 21 receives inspection-observation source linkages but URS-22 owns the inspection programme). - AI-driven decision-making on classification / severity / CAPA-linkage / closure (explicitly prohibited per DEC-21-18; AI suggestion paths are advisory only). ### 2.3 Closed launch decisions | ID | Decision | |---|---| | DEC-21-01 | Findings master registry shape and per-tenant scoping. | | DEC-21-02 | Lifecycle state machine: `open → in_progress → resolved | deferred → closed`. Allowed transitions per §2.1. Reopen is a governed transition event from `closed → in_progress` per DEC-21-22 + SoD-21-06; appends a new lifecycle event + new investigation iteration without mutating or erasing prior closed evidence. | | DEC-21-03 | Server-authoritative race-safe `FND-{YYYY}-{nnnnnn}` numbering via DB sequence. | | DEC-21-04 | Source linkage: every finding MUST link to one source via `source_type` + `source_id`; standalone findings supported for non-review sources; cross-tenant source linkage forbidden. | | DEC-21-05 | Parent-review status-gated creation per URS-20 DEC-20-08: review-source findings creatable only while parent review in `draft` or `under_review`. | | DEC-21-06 | Authority gate: every status transition goes through `withAuthority(.)` + Controlled Approval Modal e-signature. SoD-21-03 / SoD-21-04 enforced. | | DEC-21-07 | HITL decision orchestration through URS-04 `hitl` subsystem with `entity_type = 'finding'` for every resolution / closure / reopen transition. | | DEC-21-08 | Severity classification (`critical` / `major` / `minor` / `observation`); severity is captured at create; severity changes during `open` / `in_progress` require reason-for-change; severity is immutable post-resolution. | | DEC-21-09 | Severity-gated mandatory CAPA: every `critical` and `major` finding MUST have at least one linked CAPA before resolution. | | DEC-21-10 | CAPA-linkage entity model with `link_type` (`primary_remediation` / `preventive_action` / `parallel_capa`); emits `finding_capa_linked` event consumed by URS-18. | | DEC-21-11 | Investigations hook: `POST /findings/:id/trigger-investigation` escalates to URS-17 RCA with `source_type = 'finding'`. | | DEC-21-12 | Segregation-of-duties enforcement: SoD-21-01.07 across creator, owner, severity-changer, resolver, closer, reopen co-signer, critical-finding matrix. | | DEC-21-13 | E-signature binding payload capture per Controlled Approval Modal contract (URS-04); `resolved_e_sig_id` and `closed_e_sig_id` persisted on the finding header. | | DEC-21-14 | Transition notes capture: every status transition persists `notes` payload;. | | DEC-21-15 | Post-closure immutability across finding header, evidence references, and CAPA-linkage records; IMMUTABLE_STATUS = {`closed`}; `assertFindingMutable(.)` guard on every mutation route. | | DEC-21-16 | Finding closure requires `resolved` / `deferred` / `in_progress` state per allowed transitions, all linked CAPAs in terminal status (per URS-18 lifecycle), closure-rationale captured, e-signature by severity-appropriate authority; SoD-21-04 enforced. | | DEC-21-17 | Multi-dimensional context: persistence layer MUST persist `study_id`, `site_id`, `product_id`, `supplier_id`, `batch_id`, `project_id`, `process_scope` per the registry schema. | | DEC-21-18 | AI architecture binding: NO direct LLM / generative AI write to finding tables; static deterministic AI advisory only; MIRA read-only context for closed findings. | | DEC-21-19 | Audit trail: every mutation emits to URS-06 substrate with reason-for-change discipline after `open`. | | DEC-21-20 | Defer transitions require `defer_justification` (text) captured on the finding; SoD-21-05 enforced (deferral approver carries quality-lead authority for `critical` / `major` findings). | | DEC-21-21 | Critical-finding closure matrix: `critical` findings require `final_quality_approver` + executive authority co-sign at closure per SoD-21-07; `major` findings require `final_quality_approver`; `minor` / `observation` require `qa_reviewer`. | | DEC-21-22 | Reopen of closed finding is a governed transition event from `closed → in_progress`; requires `executive_authority` co-sign + reason; appends a new lifecycle event + new investigation iteration; does NOT mutate or erase prior closed evidence. SoD-21-06: executive reopen co-signer ≠ original closure authority. | | DEC-21-23 | Canonical status-model alignment across backend workflow, backend service, shared DB type, and frontend hooks. | --- ## 3. Roles, Authority Profiles, Segregation of Duties ### 3.1 Roles consumed (URS-02 catalogue) | Role key | Description | |---|---| | `viewer` | Read-only access within Module 21. | | `finding_owner` | Assigned owner of the finding; captures response and evidence; advances the finding through the lifecycle. | | `qa_reviewer` | QA reviewer who closes `minor` / `observation` findings (subject to SoD-21-04). | | `quality_lead` | Module 21 administrative oversight within tenant; closes `major` findings (subject to SoD-21-04). | | `closure_authority` | `final_quality_approver` for `critical` / `major` closures (subject to SoD-21-04 / SoD-21-07). | | `auditor` | Read access to findings and finding audit trail. | | `admin` | Module 21 tenant-administrative actions (severity-threshold configuration). | | `platform_admin` | Verixa platform — tenant-scoped Module 21 actions are support / break-glass only with reason, support-ticket reference, electronic signature, `PLATFORM_TENANT_ACCESS_USED` audit emit, and SOC alert; routine tenant findings administration belongs to tenant `admin` users. | | `super_admin` | Verixa super-admin — tenant-scoped Module 21 actions are support / break-glass only under the same controls as `platform_admin`. | | `executive_authority` | Founder / Chairman & MD — co-signs critical-finding closures per DEC-21-21 and reopen events per DEC-21-22. | ### 3.2 Authority Profiles (URS-05) | Authority Profile | Purpose | |---|---| | `finding_owner_authority` | Finding ownership and response / evidence authoring. | | `finding_review_authority` | Finding reviewer-authority for resolution sign-off (subject to SoD-21-03). | | `final_quality_approver` | Critical / major finding closure sign by final quality approver. | | `closure_authority` | Finding closure sign per DEC-21-16 (severity-driven). | | `executive_authority` | Founder co-sign for critical-finding closure per DEC-21-21 and reopen per DEC-21-22. | | `finding_reopen_executive_authority` | Executive authority for reopen (DEC-21-22). | ### 3.3 Permissions (Module 21 owns) - `findings:read` - `findings:create` (via parent-scoped route for review-source; via standalone route for non-review sources) - `findings:update` (with reason-for-change) - `findings:assign_owner` (with authority + SoD-21-02) - `findings:capture_response_evidence` - `findings:change_severity` (with reason-for-change; immutable post-resolution) - `findings:link_capa` (with authority) - `findings:unlink_capa` (with authority + reason) - `findings:trigger_investigation` (with authority; escalates to URS-17 RCA) - `findings:transition_status` (with authority + Controlled Approval Modal e-sign + notes) - `findings:resolve` (with authority + bound e-sign + SoD-21-03 + linked-CAPA check for critical/major) - `findings:close` (with severity-appropriate authority + bound e-sign + SoD-21-04) - `findings:reopen_executive` (executive authority + SoD-21-06) - `findings:soft_delete` (with reason) - `findings:read_audit` ### 3.4 Segregation-of-Duties constraints | ID | Constraint | |---|---| | SoD-21-01 | The finding owner MUST NOT be the discoverer of the precipitating source record (where applicable for inspection-observation, complaint-trend, OOS-trend, deviation-trend sources). | | SoD-21-02 | The owner-assignment authority MUST NOT be the assigned owner. | | SoD-21-03 | The resolver MUST NOT be the finding creator for `critical` / `major` findings. | | SoD-21-04 | The closure authority MUST NOT be the finding creator. | | SoD-21-05 | The deferral approver MUST carry quality-lead authority for `critical` / `major` findings. | | SoD-21-06 | The executive-authority reopen co-signer MUST NOT be the original closure authority. | | SoD-21-07 | Critical-finding closure matrix: no single user can satisfy two required slots (`final_quality_approver` + executive authority). | ### 3.5 Worked SoD examples **Example 1: Standard internal-audit finding.** A senior auditor creates `FND-2026-000456` (`severity = major`, `source_type = review`, `review_id = REV-2026-000456`) under an in-progress internal audit. The finding owner (different from the discoverer per SoD-21-01) is assigned. Owner captures response + evidence. Owner links a CAPA `CAPA-2026-000789` per DEC-21-09. The reviewer (different from creator per SoD-21-03) signs `in_progress → resolved` with bound e-signature. CAPA progresses through URS-18 lifecycle to `closed`. Closure authority (different from creator per SoD-21-04, with `final_quality_approver` for `major` per DEC-21-21) signs closure. Finding `closed`. **Example 2: Critical-finding closure requires executive authority co-sign (DEC-21-21).** A critical FDA 483 observation is captured as a standalone finding with `source_type = inspection_observation`, `source_id = INS-2026-000123`, `severity = critical`. Linked CAPA opened. Closure requires `final_quality_approver` + executive authority co-sign per DEC-21-21. SoD-21-07 enforced (no user can satisfy two slots). **Example 3: SoD-21-04 enforcement — creator attempts to close own finding.** The finding creator attempts to close `FND-2026-000457`. Service rejects with HTTP 403 + `FINDING_SOD_VIOLATION_CLOSER_CANNOT_BE_CREATOR`. URS-06 records the attempt. **Example 4: Severity-gated CAPA negative path (DEC-21-09).** Owner attempts to transition `FND-2026-000458` (`severity = critical`) from `in_progress → resolved` without a linked CAPA. Service rejects with HTTP 409 + `LINKED_CAPA_REQUIRED_FOR_SEVERITY`. The proper path: link a CAPA via URS-18 first, then resolve. **Example 5: Closure blocked by open linked CAPA (DEC-21-16).** Closure authority attempts to close a finding with a linked CAPA in `in_progress`. Service rejects with HTTP 409 + `FINDING_CLOSURE_BLOCKED_BY_OPEN_LINKED_CAPAS`. **Example 6: Investigations hook to URS-17 RCA (DEC-21-11).** Owner triggers an investigation on a critical finding via `POST /findings/:id/trigger-investigation`. Service creates a new RCA record in URS-17 with `source_type = 'finding'`, `source_id = finding_id`. URS-21 audit records `FINDING_INVESTIGATION_TRIGGERED`. **Example 7: Defer with justification (DEC-21-20).** Owner defers a `minor` finding for prioritisation reasons, captures `defer_justification = "Resource constrained until next quarter; no patient-safety impact"`. Quality-lead authority signs the deferral. Finding transitions `in_progress → deferred`. URS-06 records the defer event with justification. **Example 8: Post-closure mutation attempt blocked (DEC-21-15).** A user attempts to update the finding description on a closed finding. Service rejects with HTTP 403 + `FINDING_IMMUTABLE_FINAL_STATE`. The proper path: reopen via executive authority co-sign per DEC-21-22, update, re-resolve, re-close. **Example 9: Governed reopen by executive authority (DEC-21-22).** A new audit observation suggests that a previously closed finding's CAPA was insufficient. QA proposes reopen. Executive authority opens the reopen surface, reviews QA rationale, e-signs reopen via `finding_reopen_executive_authority` with documented reason. SoD-21-06 enforced. Finding transitions `closed → in_progress`. Prior closed evidence preserved; a new investigation iteration appends. ### 3.6 Role-permission matrix (Module 21 administrative surface only) | Permission | viewer | finding_owner | qa_reviewer | quality_lead | closure_authority | auditor | admin | platform_admin | super_admin | |---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:| | `findings:read` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | support / break-glass only | support / break-glass only | | `findings:create` (parent-scoped) | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ | support / break-glass only | support / break-glass only | | `findings:create` (standalone) | ✗ | ✗ | ✓ | ✓ | ✗ | ✗ | ✓ | support / break-glass only | support / break-glass only | | `findings:update` (with reason-for-change) | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ | support / break-glass only | support / break-glass only | | `findings:assign_owner` (with SoD-21-02) | ✗ | ✗ | ✓ | ✓ | ✗ | ✗ | ✓ | support / break-glass only | support / break-glass only | | `findings:capture_response_evidence` | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ | support / break-glass only | support / break-glass only | | `findings:change_severity` (with reason; immutable post-resolution) | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ | support / break-glass only | support / break-glass only | | `findings:link_capa` | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ | support / break-glass only | support / break-glass only | | `findings:unlink_capa` (with reason) | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ | support / break-glass only | support / break-glass only | | `findings:trigger_investigation` | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ | support / break-glass only | support / break-glass only | | `findings:transition_status` (with authority + e-sign + notes) | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ | support / break-glass only | support / break-glass only | | `findings:resolve` (with bound e-sign + SoD-21-03 + linked-CAPA check) | ✗ | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ | support / break-glass only | support / break-glass only | | `findings:close` (with severity-appropriate authority + bound e-sign + SoD-21-04) | ✗ | ✗ | ✓ (minor / observation only) | ✓ (major) | ✓ (critical with executive co-sign) | ✗ | ✓ | support / break-glass only | support / break-glass only | | `findings:reopen_executive` (executive authority + SoD-21-06) | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ (executive authority only) | | `findings:soft_delete` | ✗ | ✗ | ✗ | ✓ | ✗ | ✗ | ✓ | support / break-glass only | support / break-glass only | | `findings:read_audit` | ✗ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | support / break-glass only | support / break-glass only | External identities (URS-01 §3.2.3) MAY be added as `viewer` for read-only access within their study-grant scope; cannot hold owner / approval / closure roles. --- ## 4. End-to-End User Journeys The 28 launch user journeys cover the full findings lifecycle: create from review, create standalone from each non-review source, severity classification, severity-gated mandatory CAPA, CAPA linkage / unlinking, investigations hook to RCA, status transitions with notes, resolve, defer with justification, closure (standard / critical), reopen, AI advisory MIRA context, AI prohibition negative paths, India CDSCO scope, multi-dimensional context, and immutability negative paths. ### J-01 — Create finding from a review (parent-scoped) A senior reviewer creates `FND-2026-000456` (`severity = major`, `source_type = review`) via `POST /reviews/REV-2026-000456/findings` while the parent review is in `under_review`. URS-21 service `create(.)` validates parent-review state per DEC-21-05 (URS-20 DEC-20-08), captures applicable scope dimensions, assigns server-authoritative `FND-2026-000456` (DEC-21-03), state `open`. URS-06 records create. ### J-02 — Create standalone finding from inspection observation (DEC-21-04) Inspection coordinator creates a standalone finding from an FDA 483 observation via `POST /findings` with `source_type = inspection_observation`, `source_id = INS-2026-000123`, `severity = critical`. URS-21 service validates the source exists same-tenant; captures applicable scope; assigns `FND-2026-000457`. State `open`. ### J-03 — Create standalone finding from complaint trend Quality lead identifies a complaint trend per URS-14 and creates a standalone finding with `source_type = complaint_trend`, `source_id = TREND-2026-000089`. Assigns `FND-2026-000458`. ### J-04 — Create standalone finding from OOS trend QC supervisor identifies an OOS trend per URS-15 and creates a standalone finding with `source_type = oos_trend`. Assigns `FND-2026-000459`. ### J-05 — Create standalone finding from deviation trend QA reviewer identifies a deviation trend per URS-16 and creates a standalone finding with `source_type = deviation_trend`. Assigns `FND-2026-000460`. ### J-06 — Create standalone finding from risk assessment output Risk assessor identifies a high-risk finding from URS-19 risk-assessment output and creates a standalone finding with `source_type = risk_assessment`. Assigns `FND-2026-000461`. ### J-07 — Create standalone proactive observation finding Quality lead creates a proactive observation finding with `source_type = proactive_observation`, `source_id = null`. Process scope captured. Assigns `FND-2026-000462`. ### J-08 — Parent-review status-gated finding creation negative path (DEC-21-05) User attempts to create a finding via the parent-scoped route on a review in `pending_approval`. URS-21 service rejects with HTTP 409 + `FINDING_CREATION_BLOCKED_BY_REVIEW_STATE`. URS-06 records the rejection. ### J-09 — Cross-tenant source linkage negative path User submits a finding in tenant A linked to a review in tenant B. Service rejects with HTTP 400 + `CROSS_TENANT_SOURCE_LINKAGE_FORBIDDEN`. URS-06 records the rejected attempt. ### J-10 — Owner assignment with SoD-21-01 / SoD-21-02 Reviewer assigns a finding owner. Service verifies the proposed owner is not the discoverer of the precipitating source record per SoD-21-01 and verifies the assigning authority is not the assigned owner per SoD-21-02. On valid assignment, finding transitions `open → in_progress` with the owner attributed. ### J-11 — Capture response and evidence Owner captures the finding response and evidence references via `PATCH /findings/:id` with `response`, `evidence_jsonb` array. Each evidence reference links to a URS-12 controlled document. URS-06 records the update. ### J-12 — Severity classification at create Owner sets `severity = major` at create time. Severity is captured as part of the finding header. Severity changes during `open` / `in_progress` require reason-for-change per DEC-21-08. ### J-13 — Severity change with reason Owner changes severity from `major` to `critical` after additional evidence emerges. Service requires reason-for-change per DEC-21-08; persists the change with audit attribution. ### J-14 — Link CAPA to finding (DEC-21-10) Owner links CAPA `CAPA-2026-000789` to the finding via `POST /findings/:id/capa-links` with `capa_id`, `link_type = primary_remediation`. Service emits `finding_capa_linked` event consumed by URS-18; URS-18 service may auto-populate the CAPA's source linkage to this finding. URS-06 records the link. ### J-15 — Severity-gated mandatory CAPA negative path (DEC-21-09) Owner attempts to transition a `critical` finding from `in_progress → resolved` without a linked CAPA. Service rejects with HTTP 409 + `LINKED_CAPA_REQUIRED_FOR_SEVERITY`. The proper path: link a CAPA via URS-18 first. ### J-16 — Investigations hook to URS-17 RCA (DEC-21-11) Owner triggers an investigation on a critical finding via `POST /findings/:id/trigger-investigation`. Service creates a new RCA in URS-17 with `source_type = 'finding'`, `source_id = finding_id`. URS-21 audit records `FINDING_INVESTIGATION_TRIGGERED`. ### J-17 — Resolve with SoD-21-03 (for critical/major) and bound e-signature Resolver (different from creator for `critical` / `major` per SoD-21-03) signs `in_progress → resolved` via `POST /findings/:id/resolve` with `resolution`, bound e-signature. Service validates SoD-21-03, validates linked CAPA exists for `critical` / `major`, persists `resolved_e_sig_id`, `resolved_by_user_id`, `resolved_at`. URS-06 emits `FINDING_RESOLVED`. ### J-18 — Defer with justification (DEC-21-20) Owner defers a `minor` finding via `POST /findings/:id/transition-status` with `to_state = deferred`, `defer_justification = "Resource constrained until next quarter; no patient-safety impact"`. Quality-lead authority signs the deferral. Finding transitions `in_progress → deferred`. URS-06 records the defer event with justification. ### J-19 — Closure with SoD-21-04 (severity-driven authority) Closure authority (different from creator per SoD-21-04, with severity-appropriate authority) signs closure via `POST /findings/:id/close` with bound e-signature + closure-rationale. Service validates finding is in a closeable state, all linked CAPAs in terminal status, closure-rationale captured. Persists `closed_e_sig_id`, `closed_at`, `closed_by_user_id`. Finding transitions to `closed`. URS-06 emits `FINDING_CLOSED`. ### J-20 — Critical-finding closure requires executive authority co-sign (DEC-21-21) A `critical` finding reaches resolved state. Closure requires `final_quality_approver` + executive authority co-sign per DEC-21-21. SoD-21-07 enforced. ### J-21 — Closure blocked by open linked CAPA Closure authority attempts to close a finding with a linked CAPA in `in_progress`. Service rejects with HTTP 409 + `FINDING_CLOSURE_BLOCKED_BY_OPEN_LINKED_CAPAS` listing the open CAPAs. ### J-22 — Closure blocked by missing rationale Closure authority attempts to close without `closure_rationale`. Service rejects with HTTP 400 + `CLOSURE_RATIONALE_REQUIRED`. ### J-23 — Post-closure mutation negative path (DEC-21-15) User attempts to update the finding description on a closed finding. Service rejects with HTTP 403 + `FINDING_IMMUTABLE_FINAL_STATE` and the 21 CFR Part 11 §11.10(e) message. URS-06 records the attempt. ### J-24 — Governed reopen by executive authority (DEC-21-22) QA proposes reopen of `FND-2026-000459` (closed) on the basis of recurrence. Executive authority opens the reopen surface, reviews QA rationale, e-signs reopen via `finding_reopen_executive_authority` with documented reason. SoD-21-06 enforced. Finding transitions `closed → in_progress`. Prior closed evidence preserved; a new investigation iteration appends. ### J-25 — MIRA copilot read-only context (DEC-21-18 / URS-32) A reviewer opens MIRA copilot from a closed finding. MIRA reads the finding context (`finding → findings` mapping per `useMiraRecord` hook) and answers questions about prior findings in natural language. MIRA MUST NOT write to any finding table. ### J-26 — AI prohibition runtime block (DEC-21-18) User attempts to invoke "AI-classify finding severity" via an experimental UI surface that would write to `findings.severity`. Runtime block returns HTTP 403 + `FINDING_GENAI_PROHIBITED`. URS-06 records the attempt. ### J-27 — Multi-dimensional context capture (DEC-21-17) Owner captures `study_id`, `site_id`, `product_id`, `supplier_id`, `batch_id`, `project_id`, `process_scope` for a process-spanning finding. The persistence layer persists all captured dimensions per the registry schema. ### J-28 — India CDSCO worked example A pharma manufacturer in India operates Module 21 for CDSCO inspection observations. The §14 regulatory mapping row applicable to India (D&C Act 1940 + Drugs Rules 1945 + Revised Schedule M + NDCT 2019 where clinical scope + Medical Devices Rules 2017 where device scope) applies to finding records originating from India tenant operation, subject to per-tenant jurisdictional regulatory assessment. --- ## 5. Front-end Module 21 ### 5.1 Routes | Route | Purpose | |---|---| | `/findings` | Module 21 landing — Findings register filtered by tenant + scope dimensions + severity + status | | `/findings/:id` | Finding detail with tabbed view (overview, response + evidence, linked CAPAs, lifecycle history with notes, audit, MIRA context) | | `/findings/new` | Standalone finding creation surface (for non-review sources) | | `/reviews/:reviewId/findings/new` | Parent-scoped finding creation surface (for review-source) | | `/findings/:id/transition` | Status transition surface with notes capture | | `/findings/:id/resolve` | Resolution surface (Controlled Approval Modal + linked-CAPA check) | | `/findings/:id/close` | Closure surface (Controlled Approval Modal + linked-CAPA terminal check) | | `/findings/:id/reopen` | Reopen surface (executive authority only) | | `/findings/:id/link-capa` | CAPA linkage surface | | `/findings/:id/trigger-investigation` | Investigations hook to URS-17 RCA | ### 5.2 Components - **FindingsRegisterTable** — paginated, filterable table of findings. - **FindingDetailTabs** — tabbed view of a finding with overview, response + evidence, linked CAPAs, lifecycle history with notes, audit, MIRA context. - **CreateFindingWizard** — multi-step: source-type picker (with parent-review picker if `source_type = review`) → severity → scope-dimension capture → submit. - **ResponseEvidenceCapturePanel** — owner captures response + evidence references (links to URS-12). - **SeverityChangePanel** — severity change with reason-for-change capture; locked post-resolution. - **CAPALinkagePanel** — link / unlink CAPAs with link-type selector; mandatory-CAPA enforcement surface for `critical` / `major`. - **InvestigationsHookButton** — escalates the finding to URS-17 RCA. - **ResolutionModal** — Controlled Approval Modal (URS-04) with linked-CAPA check + bound e-signature. - **DeferralModal** — defer transition with justification capture. - **ClosureModal** — closure surface with prerequisite check (linked CAPAs terminal) + bound e-signature; severity-driven authority routing. - **CriticalFindingClosureMatrix** — multi-sign matrix for critical-finding closure (DEC-21-21). - **ExecutiveAuthorityReopenModal** — executive-authority-only reopen. - **FindingAuditTrailView** — full finding audit trail consumed from URS-06. - **MIRAFindingContextPanel** — read-only MIRA copilot context integration via `useMiraRecord('finding', id)` (DEC-21-18); AI suggestions visibly labelled as advisory. ### 5.3 Accessibility WCAG 2.1 Level AA. Keyboard-navigable. Screen-reader labels for all interactive elements. --- ## 6. Back-end Module 21 ### 6.1 Architecture overview ```mermaid flowchart LR ROUTES[findings.routes.ts + reviews.routes.ts findings sub-route] --> SVC[findings.service.ts + workflow.ts] SVC --> DB[(findings tables)] SVC --> AUDIT[(URS-06 audit substrate)] SVC --> HITL[(URS-04 HITL subsystem entity_type=finding)] SVC --> ESIG[(URS-04 e-signature subsystem)] SVC --> EVT_C[event-bus emit finding_created] SVC --> EVT_S[event-bus emit finding_status_changed] SVC --> EVT_L[event-bus emit finding_capa_linked] EVT_L --> M18[URS-18 CAPA receives linkage] SVC --> RCA[URS-17 RCA service for investigations hook] SVC --> MIRA[(URS-32 MIRA context read-only)] ``` Diagram 6.1-A — Module 21 architecture overview. The target `findings` code module is the expected owner of routes, services, workflow validation, DB persistence, event emission, and MIRA context integration; ownership is target binding and remains subject to repository verification and validation evidence. URS-06 substrate is consumed for audit; URS-04 HITL + e-signature subsystem is consumed for non-bypassable resolution / closure and bound signature persistence; URS-17 RCA is consumed via the investigations hook; URS-18 CAPA is the primary downstream consumer. ### 6.1.1 Finding lifecycle state machine (full) ```mermaid stateDiagram-v2 [*] --> open : create open --> in_progress : owner_assigned + work_started open --> resolved : resolution_signed (DEC-21-06 + bound e-sig + linked-CAPA check for critical/major) open --> deferred : defer_signed (DEC-21-20 + justification + quality-lead authority for critical/major) in_progress --> resolved : resolution_signed (DEC-21-06 + bound e-sig + linked-CAPA check for critical/major) in_progress --> deferred : defer_signed in_progress --> closed : closure_signed (DEC-21-16 + SoD-21-04 + bound e-sig + linked-CAPA terminal check) resolved --> closed : closure_signed (DEC-21-16 + SoD-21-04 + bound e-sig + linked-CAPA terminal check) deferred --> resolved : resolution_signed (DEC-21-06 + bound e-sig) deferred --> closed : closure_signed (DEC-21-16 + SoD-21-04 + bound e-sig) closed --> in_progress : reopen — governed transition (DEC-21-22 + SoD-21-06; appends new lifecycle event + new investigation iteration; does NOT mutate or erase prior closed evidence) closed --> [*] : immutable parent + linked-CAPA refs DEC-21-15 note right of in_progress SoD-21-01: owner ≠ discoverer SoD-21-02: assigning authority ≠ assigned owner SoD-21-03: resolver ≠ creator (for critical/major) SoD-21-04: closure authority ≠ creator SoD-21-05: defer approver = quality-lead for critical/major SoD-21-06: reopen co-signer ≠ original closure authority SoD-21-07: critical-finding closure matrix — no user can hold two slots DEC-21-09: critical/major requires linked CAPA before resolution DEC-21-16: closure requires linked CAPAs terminal end note ``` Diagram 6.1-B — Finding lifecycle state machine including authority-gated transitions, executive-authority-cosigned reopen path (DEC-21-22), severity-gated mandatory CAPA (DEC-21-09), and post-closure parent + linked-CAPA-ref immutability (DEC-21-15). ### 6.2 Data model requirements | Entity | Purpose | Key fields | Required | Unique | Tenant isolation | Versioning | Retention | Soft-delete | Audit | E-sig link | |---|---|---|---|---|---|---|---|---|---|---| | `findings` | Canonical finding record per DEC-21-01 | `id`, `tenant_id`, `display_id`, `title`, `description`, `severity`, `status`, `regulation_ref`, `source_type`, `source_id` (nullable for proactive), `review_id` (FK URS-20 nullable), `study_id` (FK URS-07 nullable), `site_id` (FK URS-09 nullable), `product_id` (FK URS-10 nullable), `supplier_id` (FK URS-11 nullable), `batch_id` (FK URS-23 nullable), `project_id` (nullable), `process_scope`, `assigned_to_user_id` (nullable), `response`, `evidence_jsonb`, `due_date`, `resolution` (nullable), `defer_justification` (nullable), `created_by`, `created_at`, `updated_at`, `resolved_at` (nullable), `resolved_by_user_id` (nullable), `resolved_e_sig_id` (nullable), `closed_at` (nullable), `closed_by_user_id` (nullable), `closed_e_sig_id` (nullable), `closure_rationale` (nullable), `triggered_investigation_rca_id` (FK URS-17 nullable), `deleted_at` (nullable) | per-state | unique(`tenant_id`, `display_id`) | RLS on `tenant_id` | stateful + append-only audit | retain (long-term) | yes (soft-delete only) | yes | yes | | `finding_capa_links` | Per-finding CAPA linkage per DEC-21-10 | `id`, `tenant_id`, `finding_id`, `capa_id` (FK URS-18), `link_type`, `linked_by_user_id`, `linked_at`, `unlinked_at` (nullable), `unlinked_by_user_id` (nullable), `unlink_reason` (nullable) | core required | unique active(`finding_id`, `capa_id`) | RLS via finding tenant | stateful | retain (long-term) | not applicable | yes | not applicable | | `finding_evidence_refs` | Per-finding evidence reference (typed extraction from `evidence_jsonb`) | `id`, `tenant_id`, `finding_id`, `evidence_type` (`document` / `observation` / `screenshot` / `data_export`), `evidence_document_id` (FK URS-12 nullable), `evidence_observation`, `recorded_by_user_id`, `recorded_at` | core required | unique(`finding_id`, `id`) | RLS via finding tenant | append-only | retain (long-term) | not applicable | yes | not applicable | | `finding_lifecycle_events` | Append-only lifecycle transition log | `id`, `tenant_id`, `finding_id`, `from_state`, `to_state`, `event_code`, `signature_set_jsonb` (derived read snapshot only; authoritative multi-signature evidence is stored in the module signature-slot table), `reason_jsonb`, `audit_log_id` (FK URS-06), `triggered_at`, `previous_hash`, `record_hash` | all | unique(`finding_id`, `id`); unique(`record_hash`) | RLS via finding tenant | append-only | retain (long-term) | not applicable | yes | yes | | `finding_approvals` | Per-approval signature-slot table per DEC-21-13 / DEC-21-21 | `id`, `tenant_id`, `finding_id`, `slot_role` (`final_quality_approver` / `executive_authority`), `slot_user_id`, `slot_e_sig_id`, `slot_signed_at`, `slot_reason_for_change` | per-slot | unique(`finding_id`, `slot_role`, `slot_user_id`) | RLS via finding tenant | append-only | retain (long-term) | not applicable | yes | yes | | `finding_transition_notes` | Transition notes per DEC-21-14 | `id`, `tenant_id`, `finding_id`, `from_state`, `to_state`, `note_text`, `note_signed_by_user_id`, `note_signed_at`, `note_signed_e_sig_id` | core required | unique(`finding_id`, `from_state`, `to_state`, `note_signed_at`) | RLS via finding tenant | append-only | retain (long-term) | not applicable | yes | yes | ### 6.3 API requirements | Method | Endpoint | Actor | Request | Response | Permission | Audit | Error codes | |---|---|---|---|---|---|---|---| | GET | `/findings` | tenant-scoped | filters | `Finding[]` | tenant base role + `audit:read` | `FINDING_REGISTER_VIEW_OPENED` once per session | none | | GET | `/reviews/:reviewId/findings` | tenant-scoped | filters | `Finding[]` for the review | `findings:read` | none | none | | GET | `/findings/:id` | tenant-scoped | none | full finding detail with linked CAPAs + evidence + lifecycle history | `findings:read` | none | `NOT_FOUND` | | POST | `/findings` | finding owner / qa_reviewer / quality_lead | source-type + source_id (for non-review) + scope-dimension fields (electronic-signed) | `201` (state `open`) | `findings:create` | `FINDING_CREATED` (and emits `finding_created` event) | `SOURCE_RECORD_NOT_FOUND`, `CROSS_TENANT_SOURCE_LINKAGE_FORBIDDEN`, `SCOPE_ANCHOR_REQUIRED`, `SOURCE_LINKAGE_REQUIRED`, validation | | POST | `/reviews/:reviewId/findings` | reviewer / qa_reviewer / quality_lead | finding fields (electronic-signed) | `201` | `findings:create` | `FINDING_CREATED` (and emits `finding_created` event) | `FINDING_CREATION_BLOCKED_BY_REVIEW_STATE`, `SCOPE_ANCHOR_REQUIRED`, validation | | PATCH | `/findings/:id` | finding owner | partial fields including `response` / `evidence_jsonb` (electronic-signed; reason-for-change required after `open`) | `200` | `findings:update` | `FINDING_UPDATED` | `FINDING_IMMUTABLE_FINAL_STATE`, `REASON_FOR_CHANGE_REQUIRED`, validation | | PATCH | `/findings/:id/severity` | finding owner / quality_lead | new severity + reason-for-change | `200` | `findings:change_severity` | `FINDING_SEVERITY_CHANGED` | `SEVERITY_IMMUTABLE_POST_RESOLUTION`, `REASON_FOR_CHANGE_REQUIRED` | | POST | `/findings/:id/assign-owner` | qa_reviewer / quality_lead | new owner + reason | `200` | `findings:assign_owner` | `FINDING_OWNER_ASSIGNED` | `FINDING_SOD_VIOLATION_OWNER_CANNOT_BE_DISCOVERER`, `FINDING_SOD_VIOLATION_ASSIGNING_AUTHORITY_CANNOT_BE_OWNER` | | POST | `/findings/:id/capa-links` | finding owner / quality_lead | `capa_id` + `link_type` (electronic-signed) | `201` (and emits `finding_capa_linked` event) | `findings:link_capa` | `FINDING_CAPA_LINKED` | `CAPA_NOT_FOUND`, `CROSS_TENANT_CAPA_LINKAGE_FORBIDDEN`, validation | | DELETE | `/findings/:id/capa-links/:linkId` | finding owner / quality_lead | reason | `200` | `findings:unlink_capa` | `FINDING_CAPA_UNLINKED` | `LINKED_CAPA_REQUIRED_FOR_SEVERITY` (if unlink would leave critical/major without CAPA), validation | | POST | `/findings/:id/trigger-investigation` | finding owner / quality_lead | reason | `200` (creates RCA in URS-17) | `findings:trigger_investigation` | `FINDING_INVESTIGATION_TRIGGERED` | validation | | PATCH | `/findings/:id/status` | finding owner / qa_reviewer / quality_lead | new status + notes (electronic-signed; bound e-sig for `resolved` / `closed`) | `200` | `findings:transition_status` | `FINDING_STATUS_TRANSITIONED` (and emits `finding_status_changed` event; persists notes per DEC-21-14) | `STATE_TRANSITION_NOT_ALLOWED`, `NOTES_REQUIRED`, `BOUND_ESIGNATURE_REQUIRED`, validation | | POST | `/findings/:id/resolve` | resolver | resolution + bound e-sig | `200` | `findings:resolve` | `FINDING_RESOLVED` | `STATE_NOT_RESOLVABLE`, `LINKED_CAPA_REQUIRED_FOR_SEVERITY`, `FINDING_SOD_VIOLATION_RESOLVER_CANNOT_BE_CREATOR_FOR_SEVERITY`, `BOUND_ESIGNATURE_REQUIRED`, `RESOLUTION_REQUIRED` | | POST | `/findings/:id/close` | severity-appropriate authority | closure rationale + bound e-sig | `200` | `findings:close` | `FINDING_CLOSED` | `STATE_NOT_CLOSEABLE`, `FINDING_CLOSURE_BLOCKED_BY_OPEN_LINKED_CAPAS`, `CLOSURE_RATIONALE_REQUIRED`, `FINDING_SOD_VIOLATION_CLOSER_CANNOT_BE_CREATOR`, `MISSING_FOUNDER_COSIGN` (for critical), `BOUND_ESIGNATURE_REQUIRED` | | POST | `/executive/findings/:id/reopen` | executive authority | reason (electronic-signed + MFA + co-sign) | `200` | `findings:reopen_executive` | `FINDING_REOPENED` | `STATE_NOT_CLOSED`, `FINDING_SOD_VIOLATION_REOPEN_COSIGNER_CANNOT_BE_CLOSURE_AUTHORITY` | | DELETE | `/findings/:id` | quality_lead | reason (electronic-signed) | `200` (soft-delete) | `findings:soft_delete` | `FINDING_SOFT_DELETED` | `FINDING_IMMUTABLE_FINAL_STATE` | ### 6.4 Workflow requirements (inline above and in §4 journeys) ### 6.5 Business rules - **BR-21-01** — Every finding MUST have at least one scope anchor per DEC-21-04. - **BR-21-02** — Every finding MUST link to one source (`source_type` non-null); standalone findings supported for non-review sources per DEC-21-04. - **BR-21-03** — Cross-tenant source linkage forbidden. - **BR-21-04** — Lifecycle state machine per DEC-21-02; reopen is governed transition `closed → in_progress` per DEC-21-22 (does NOT mutate or erase prior closed evidence). - **BR-21-05** — Parent-review status-gated creation per DEC-21-05 (URS-20 DEC-20-08). - **BR-21-06** — Every status transition MUST go through `withAuthority(.)` + Controlled Approval Modal e-signature per DEC-21-06. - **BR-21-07** — Every status transition MUST persist `notes` payload per DEC-21-14. - **BR-21-08** — Severity captured at create per DEC-21-08; severity changes during `open` / `in_progress` require reason-for-change; severity is immutable post-resolution. - **BR-21-09** — Severity-gated mandatory CAPA enforced per DEC-21-09 (`critical` / `major` MUST have at least one linked CAPA before resolution). - **BR-21-10** — Resolution enforces SoD-21-03 (resolver ≠ creator for `critical` / `major`) + bound e-signature. - **BR-21-11** — Closure requires all linked CAPAs in terminal status per DEC-21-16; SoD-21-04 enforced; closure-rationale required; severity-driven authority routing (DEC-21-21). - **BR-21-12** — Critical-finding closure requires `final_quality_approver` + executive authority co-sign per DEC-21-21; SoD-21-07 enforced. - **BR-21-13** — Bound e-signature persistence: `resolved_e_sig_id`, `closed_e_sig_id` persisted on the finding header. - **BR-21-14** — Post-closure immutability enforced via `assertFindingMutable(.)` on every mutation route (DEC-21-15). - **BR-21-15** — Reopen is a governed transition event from `closed → in_progress` per DEC-21-22 + SoD-21-06; appends new lifecycle event + new investigation iteration; does NOT mutate or erase prior closed evidence. - **BR-21-16** — Every regulated mutation emits to URS-06 substrate with reason-for-change discipline after `open` (DEC-21-19). - **BR-21-17** — `finding_created`, `finding_status_changed`, `finding_capa_linked` events emitted; downstream consumers (URS-30 notifications, URS-22 inspection-readiness, URS-26 APQR, URS-18 CAPA) consume. - **BR-21-18** — Investigations hook escalates to URS-17 RCA per DEC-21-11 with `source_type = 'finding'`. - **BR-21-19** — Static deterministic AI may surface advisory similarity / signal output; generative AI prohibited in finding classification, severity assignment, CAPA-linkage, resolution, and closure decision paths (DEC-21-18). - **BR-21-20** — MIRA copilot read-only mapping `finding → findings` per `useMiraRecord('finding', id)`; no MIRA write paths. - **BR-21-21** — Audit-log writes atomic with originating action per URS-04 BR-04-15. - **BR-21-22** — Canonical status set MUST be aligned across backend service, shared DB type, workflow code, and frontend hooks per DEC-21-23. ### 6.6 Audit substrate Module 21 governance event vocabulary (canonical launch list; every code MUST have at least one writer and one regression test; adding a code is a Class 3 change): `FINDING_CREATED`, `FINDING_UPDATED`, `FINDING_OWNER_ASSIGNED`, `FINDING_SEVERITY_CHANGED`, `FINDING_CAPA_LINKED`, `FINDING_CAPA_UNLINKED`, `FINDING_INVESTIGATION_TRIGGERED`, `FINDING_STATUS_TRANSITIONED`, `FINDING_RESOLVED`, `FINDING_DEFERRED`, `FINDING_CLOSED`, `FINDING_REOPENED`, `FINDING_SOFT_DELETED`, `FINDING_HITL_DECISION_OPENED`, `FINDING_HITL_DECISION_DECIDED`, `FINDING_TRANSITION_NOTES_CAPTURED`, `FINDING_SOD_VIOLATION_OWNER_CANNOT_BE_DISCOVERER`, `FINDING_SOD_VIOLATION_ASSIGNING_AUTHORITY_CANNOT_BE_OWNER`, `FINDING_SOD_VIOLATION_RESOLVER_CANNOT_BE_CREATOR_FOR_SEVERITY`, `FINDING_SOD_VIOLATION_CLOSER_CANNOT_BE_CREATOR`, `FINDING_SOD_VIOLATION_REOPEN_COSIGNER_CANNOT_BE_CLOSURE_AUTHORITY`, `FINDING_GENAI_PROHIBITED`, `FINDING_IMMUTABLE_FINAL_STATE`, `PLATFORM_TENANT_ACCESS_USED`, `PLATFORM_TENANT_ACCESS_DENIED`, `FINDING_REGISTER_VIEW_OPENED`, `FINDING_INSPECTION_PREP_EXPORTED`. The following events are emitted by upstream / downstream modules and consumed (read-only) by Module 21: `REVIEW_STATUS_TRANSITIONED` (from URS-20; informs status-gated creation), `CAPA_CLOSED` (from URS-18; informs closure-prerequisite check), `RCA_CREATED` (from URS-17; confirms investigations-hook escalation). ### 6.7 Architecture binding — Internal Annex 22 GenAI prohibition control + ARCH-AI-001 (AC-2, AC-3, AC-4, AC-7) + internal EU AI Act Annex III high-risk classification (forward-looking; not enacted predicate rule; binding predicate-rule obligations remain those listed in §14) | Surface | AI use permitted | Governance | |---|---|---| | Finding-classification disposition | NONE — internal Annex 22 prohibition | Manual decision; reviewer-signed system of record | | Severity assignment | NONE — internal Annex 22 prohibition | Manual decision; reviewer-signed; immutable post-resolution | | CAPA-linkage decision | NONE — internal Annex 22 prohibition | Manual decision; severity-gated mandatory for critical/major | | Resolution decision | NONE — internal Annex 22 prohibition | Manual decision; bound e-sig + linked-CAPA check | | Closure decision | NONE — internal Annex 22 prohibition | Manual closure; deterministic linked-CAPA terminal check; bound e-sig | | AI similar-finding suggestion (advisory) | YES — static deterministic over closed findings | ARCH-AI-001 AC-2/3/4/7 | | AI severity suggestion (advisory) | YES — static deterministic; never autonomous | ARCH-AI-001 AC-2/3/4/7 | | AI CAPA-linkage suggestion (advisory) | YES — static deterministic; never autonomous | ARCH-AI-001 AC-2/3/4/7 | | MIRA copilot read-only context on finding | YES — read-only via `useMiraRecord('finding', id)` | URS-32 RAG; mapping `finding → findings`; advisory visibly labelled per DEC-21-18 | Internal AI-governance obligations aligned with EU AI Act Annex III high-risk classification (treated as internal forward-looking control, not enacted predicate rule) include AI-specific QMS, conformity assessment, technical documentation, ongoing monitoring, human oversight; supported by ARCH-AI-001 architectural reference + URS-06 audit substrate + Authority-gated workflow + URS-04 HITL non-bypassable orchestration. Jurisdiction-specific legal enforceability remains subject to a future jurisdiction-specific legal assessment. Binding predicate-rule obligations remain those listed in §14. --- ## 7. Cross-Module Wiring and Change-Impact ### 7.1 Cross-module wiring ```mermaid flowchart LR M20[URS-20 Reviews - primary parent] --> M21 M22[URS-22 Inspection Observations] --> M21 M14[URS-14 Complaint Trends] --> M21 M15[URS-15 OOS Trends] --> M21 M16[URS-16 Deviation Trends] --> M21 M19[URS-19 Risk Assessment] --> M21 M21 --> M18[URS-18 CAPA linked] M21 -. investigations hook.-> M17[URS-17 RCA] M21 -. mitigation precipitates change.-> M13[URS-13 Change Control] M21 --> M06[URS-06 Audit substrate] M21 --> M30[URS-30 Notifications] M22 <-- M21 M26[URS-26 APQR] <-- M21 M32[URS-32 MIRA AI] <-- M21 (read-only context) ANNEX22[Internal Annex 22 control — forward-looking] -.governs.-> M21 ARCHAI[ARCH-AI-001] -.governs advisory AI.-> M21 AIAct[Internal EU AI Act Annex III high-risk classification — forward-looking] -.classifies.-> M21 ``` Diagram 7.1-A — Module 21 cross-module wiring. ### 7.2 Change-Impact Matrix (CIM) | Asset | Cross-module consumers | Direction | Class | |---|---|---|---| | Finding event vocabulary | URS-22, URS-26, URS-30 | Outbound | Class 3 (add) | | CAPA-linkage event | URS-18 | Outbound | Class 3 (add) | | Investigations hook | URS-17 | Outbound | Class 3 (add) | | Finding register | URS-20, URS-22, URS-26 | Outbound | Class 2 | --- ## 8. AI / HITL controls - ARCH-AI-001 architectural reference applies. AC-2: advisory AI is secondary; manual primary path. AC-3: visible labelling. AC-4: no autonomous write. AC-7: graceful degradation. - Internal Annex 22 Draft 2025 forward-looking AI governance control prohibits generative / probabilistic AI in finding classification, severity assignment, CAPA-linkage decision, resolution, and closure decision paths. Static deterministic AI may surface similar prior findings and historical classification patterns as advisory. - Verixa internally classifies AI-assisted finding classification as high-risk AI under internal AI governance, aligned with the high-risk classification approach in EU AI Act Annex III, unless a jurisdiction-specific legal assessment determines otherwise — escalated when the finding feeds a CAPA, inspection response, or compliance disposition. - MIRA copilot read-only mapping `finding → findings` via `useMiraRecord('finding', id)` (per URS-32). MIRA MUST NOT write to any finding table. - AI service errors degrade gracefully: similarity panel hides if the AI service is unavailable; the findings core workflow proceeds. --- ## 9. Performance / scalability - Findings register listing supports filters by `status`, `severity`, `source_type`, scope dimensions; 95th-percentile response time MUST be ≤ 500 ms for tenants up to 100,000 findings. - Finding detail aggregation (parent finding + linked CAPAs + evidence references) returns within ≤ 300 ms for findings up to 50 linked CAPAs. - Concurrent finding mutation by independent owners MUST not deadlock; row-level locking on the finding header. --- ## 10. Localisation / i18n UI strings, lifecycle state labels, severity labels, source-type labels, and error messages localised per tenant locale (English, French, German, Spanish, Hindi, Japanese, Mandarin at launch). --- ## 11. Errors ### 11.1 Error envelope Standard envelope (human message, machine code in upper-snake-case, optional structured details, correlation identifier). ### 11.2 Error-code catalogue | Code | HTTP | Path | UI behaviour | |---|---|---|---| | SOURCE_RECORD_NOT_FOUND | 400 | finding create | inline error | | CROSS_TENANT_SOURCE_LINKAGE_FORBIDDEN | 400 | finding create | inline error | | CROSS_TENANT_CAPA_LINKAGE_FORBIDDEN | 400 | CAPA link | inline error | | SCOPE_ANCHOR_REQUIRED | 400 | finding create | inline error | | SOURCE_LINKAGE_REQUIRED | 400 | finding create | inline error | | FINDING_CREATION_BLOCKED_BY_REVIEW_STATE | 409 | parent-scoped finding create | inline error | | FINDING_SOD_VIOLATION_OWNER_CANNOT_BE_DISCOVERER | 403 | owner assignment | inline error | | FINDING_SOD_VIOLATION_ASSIGNING_AUTHORITY_CANNOT_BE_OWNER | 403 | owner assignment | inline error | | FINDING_SOD_VIOLATION_RESOLVER_CANNOT_BE_CREATOR_FOR_SEVERITY | 403 | resolve | inline error | | FINDING_SOD_VIOLATION_CLOSER_CANNOT_BE_CREATOR | 403 | close | inline error | | FINDING_SOD_VIOLATION_REOPEN_COSIGNER_CANNOT_BE_CLOSURE_AUTHORITY | 403 | reopen | inline error | | FINDING_IMMUTABLE_FINAL_STATE | 403 | any mutation post-closure | inline error citing 21 CFR Part 11 §11.10(e) | | REASON_FOR_CHANGE_REQUIRED | 400 | finding update / severity change | inline error | | RESOLUTION_REQUIRED | 400 | finding resolve | inline error | | NOTES_REQUIRED | 400 | finding status transition | inline error | | BOUND_ESIGNATURE_REQUIRED | 400 | resolve / close | inline error | | SEVERITY_IMMUTABLE_POST_RESOLUTION | 409 | severity change | inline error | | LINKED_CAPA_REQUIRED_FOR_SEVERITY | 409 | resolve | inline error | | CAPA_NOT_FOUND | 400 | CAPA link | inline error | | STATE_TRANSITION_NOT_ALLOWED | 409 | status transition | inline error | | STATE_NOT_OPEN | 409 | lifecycle endpoints | inline error | | STATE_NOT_IN_PROGRESS | 409 | lifecycle endpoints | inline error | | STATE_NOT_RESOLVABLE | 409 | finding resolve | inline error | | STATE_NOT_CLOSEABLE | 409 | finding close | inline error | | STATE_NOT_CLOSED | 409 | finding reopen | inline error | | FINDING_CLOSURE_BLOCKED_BY_OPEN_LINKED_CAPAS | 409 | finding close | inline error listing open CAPAs | | CLOSURE_RATIONALE_REQUIRED | 400 | finding close | inline error | | MISSING_FOUNDER_COSIGN | 401 | finding close (critical) | open executive authority co-sign request | | FINDING_GENAI_PROHIBITED | 403 | any AI surface that would write to finding tables | inline error citing internal Annex 22 control | | AUDIT_TRAIL_WRITE_FAILED | 500 | any state-changing action | toast; the originating action did NOT commit | | PLATFORM_TENANT_ACCESS_DENIED | 403 | platform identity outside support envelope | inline error; SOC alert | ### 11.3 Negative-path catalogue | Scenario | Detection | Response | UI behaviour | |---|---|---|---| | Create finding with non-existent source | back end | `400 SOURCE_RECORD_NOT_FOUND` | inline error | | Create finding without scope anchor | back end | `400 SCOPE_ANCHOR_REQUIRED` | inline error | | Create finding on review in `pending_approval` (parent-scoped) | back end | `409 FINDING_CREATION_BLOCKED_BY_REVIEW_STATE` | inline error | | Discoverer attempts to be owner | back end | `403 FINDING_SOD_VIOLATION_OWNER_CANNOT_BE_DISCOVERER` | inline error | | Resolve critical/major without linked CAPA | back end | `409 LINKED_CAPA_REQUIRED_FOR_SEVERITY` | inline error | | Resolve critical/major by creator | back end | `403 FINDING_SOD_VIOLATION_RESOLVER_CANNOT_BE_CREATOR_FOR_SEVERITY` | inline error | | Resolve without bound e-sig | back end | `400 BOUND_ESIGNATURE_REQUIRED` | inline error | | Edit on closed finding | back end | `403 FINDING_IMMUTABLE_FINAL_STATE` | inline error | | Severity change post-resolution | back end | `409 SEVERITY_IMMUTABLE_POST_RESOLUTION` | inline error | | Close with open linked CAPA | back end | `409 FINDING_CLOSURE_BLOCKED_BY_OPEN_LINKED_CAPAS` | inline error | | Close without rationale | back end | `400 CLOSURE_RATIONALE_REQUIRED` | inline error | | Close critical without executive co-sign | back end | `401 MISSING_FOUNDER_COSIGN` | inline error | | Reopen by original closure authority | back end | `403 FINDING_SOD_VIOLATION_REOPEN_COSIGNER_CANNOT_BE_CLOSURE_AUTHORITY` | inline error | | GenAI invocation in classification / severity / CAPA-linkage / closure path | back end runtime block | `403 FINDING_GENAI_PROHIBITED` | inline error | --- ## 12. Security and Observability ### 12.1 Security envelope Tenant isolation via TDAL.withTenant per QS-5; RLS on every finding-scoped table per QS-6; permission checks per QS-7; structured error handling per QS-9; e-signature via URS-04 Controlled Approval Modal with bound payload persistence per DEC-21-13; MFA step-up for executive authority co-sign and reopen. ### 12.2 Observability | Signal | Threshold | Action | |---|---|---| | Critical-finding closure rate per executive authority (high outliers) | > 95th percentile | Quality oversight | | Reopen rate per finding | > 1 reopen per finding | Quality oversight surface | | Time from finding creation to closure (SLA per severity) | critical > 30 days; major > 60 days; minor > 90 days | Notification to QA Lead | | `FINDING_SOD_VIOLATION_*` events | any single event | high; SOC chat | | `FINDING_GENAI_PROHIBITED` events | any single event | high; SOC chat | | `PLATFORM_TENANT_ACCESS_USED` events | any single event | medium; SOC e-mail | ### 12.3 Reports | Report | Purpose | Owner | |---|---|---| | Open findings register | Active findings by lifecycle state, severity, source | QA | | Critical-finding register | All critical findings with status and linked CAPAs | QA, executive authority | | Findings awaiting CAPA linkage | Critical/major findings without a linked CAPA | QA | | Findings awaiting closure | Resolved findings with closure-prerequisite check failing | QA | | Reopen audit register | Reopened findings with executive authority attribution | QA, executive authority | | Source-type distribution | Findings by source type per quarter | QA | | Cross-tenant indices (platform-admin support / break-glass only) | Aggregate Module 21 events | `platform_admin` (support / break-glass only with reason, support-ticket reference, electronic signature, `PLATFORM_TENANT_ACCESS_USED` audit emit, SOC alert) | Exports: - Finding evidence pack (zipped: full finding + linked CAPAs + evidence references + lifecycle events with notes + approvals + URS-06 audit excerpt with hash-chain). --- ## 13. Data integrity (ALCOA+) | Principle | How met | |---|---| | Attributable | Every finding mutation carries `created_by` / `updated_by` / `signed_by` per QS-2 | | Legible | UI surfaces the finding detail with lifecycle history and audit trail | | Contemporaneous | Server-generated timestamps per QS-3 | | Original | Soft-delete only on finding header; post-closure immutability for header / evidence / CAPA-linkage per DEC-21-15 | | Accurate | App-level source-record validation; severity-gated mandatory CAPA; SoD enforcement at every resolution / closure / reopen; bound e-signature persistence | | Complete | All finding mutations audited; HITL decision orchestration enforces non-bypassable resolution / closure | | Consistent | URS-06 chain integrity; canonical status set aligned across layers per DEC-21-23 | | Enduring | Long-term retention; chain sealing at tenant offboarding per URS-08 | | Available | Findings register surface; auditor read access per URS-22 | --- ## 14. Regulatory Mapping ### 14.1 Predicate-rule applicability matrix | Regulatory authority | Predicate | Module 21 obligation | |---|---|---| | FDA | 21 CFR Part 11 §11.10(a) — System validation | Module 21 must be validated per QS-15, QS-16; URS-21-VAL-* gates | | FDA | 21 CFR Part 11 §11.10(d) — Limit access to authorised individuals | Three-guard RBAC + Authority Profile + HITL non-bypassable | | FDA | 21 CFR Part 11 §11.10(e) — Audit trail | URS-06 hash-chained audit substrate, append-only | | FDA | 21 CFR Part 11 §11.50/§11.70/§11.100/§11.200/§11.300 | Controlled Approval Modal contract; bound e-sig persistence per DEC-21-13 | | FDA | FDA Form 483 / EIR observations | Standalone finding creation from inspection observation source | | FDA | 21 CFR Part 211 §211.192 (Production record review for unexplained discrepancies) | Finding workflow trigger from URS-16 | | EMA | EU GMP Annex 11 §16 (Incident Management) | Finding lifecycle | | EMA / PIC/S | EU GMP Chapter 1 §1.4 (Pharmaceutical Quality System) | Finding element of PQS | | MHRA | MHRA Data Integrity Guidance (2018) — ALCOA+ | §13 mapping | | Health Canada | C.02.020 — GMP records | Finding register and retention | | ICH | ICH Q10 §3.2.1 (CAPA system) | Finding-to-CAPA cascade | | ICH | ICH E6(R3) — GCP | Clinical finding handling | | ISO | ISO 19011 (Audit principles) | Finding documentation | | GAMP | GAMP 5 Cat 5 — Custom application | Validation per §17 | | FDA | FDA CSA Final Guidance (Sep 2025) | Risk-based finding handling | | WHO | TRS 996 Annex 5 — Good data management | ALCOA+ implementation | | Internal architectural control (forward-looking; not enacted predicate rule) | EU GMP Annex 22 (Draft 2025) | Internal forward-looking AI governance evidence (Annex 22 platform reference) | | Internal architectural control (forward-looking; not enacted predicate rule) | EU AI Act Regulation 2024/1689 Annex III (high-risk classification approach) | Internal high-risk AI governance aligned with the Annex III approach (jurisdiction-specific legal enforceability subject to future legal assessment) | | Internal architectural control (forward-looking; not enacted predicate rule) | EU AI Act Art. 13 — Transparency principles | Visible advisory labelling (jurisdiction-specific legal enforceability subject to future legal assessment) | | India CDSCO (per applicable scope) | India Drugs and Cosmetics Act 1940 + Drugs Rules 1945 + Revised Schedule M (finding handling within GMP) + Schedule M-III (where distribution-finding scope) + New Drugs and Clinical Trials Rules 2019 (where clinical finding scope) + CDSCO GCP guidance (where clinical / study finding scope) + Medical Devices Rules 2017 (where device / combination-product finding scope) + CDSCO inspection observation source — Applicable per India tenant operation and jurisdictional regulatory assessment | Findings register, severity classification, severity-gated CAPA, investigations hook, resolution with bound e-sig, closure with executive authority co-sign for critical, reopen audit chain; external jurisdictional legal / RA confirmation required for clause / form applicability per India finding scope | --- ## 15. URS Requirements Register ### 15.1 Front-end (FE) | ID | Requirement | Priority | |---|---|---| | URS-21-FE-001 | Module 21 landing route at `/findings` | MUST | | URS-21-FE-002 | Findings register table with filters by `status`, `severity`, `source_type`, scope dimensions | MUST | | URS-21-FE-003 | Finding detail tabbed view (overview, response + evidence, linked CAPAs, lifecycle history with notes, audit, MIRA context) | MUST | | URS-21-FE-004 | Standalone finding create wizard with source-type picker | MUST | | URS-21-FE-005 | Parent-scoped finding create wizard from review surface | MUST | | URS-21-FE-006 | Response + evidence capture panel | MUST | | URS-21-FE-007 | Severity change panel with reason-for-change capture; locked post-resolution | MUST | | URS-21-FE-008 | CAPA linkage panel with link-type selector and mandatory-CAPA enforcement surface for critical/major | MUST | | URS-21-FE-009 | Investigations hook button | MUST | | URS-21-FE-010 | Resolution modal (Controlled Approval Modal) with linked-CAPA check + bound e-signature | MUST | | URS-21-FE-011 | Deferral modal with justification capture | MUST | | URS-21-FE-012 | Closure modal with prerequisite check + bound e-signature; severity-driven authority routing | MUST | | URS-21-FE-013 | Critical-finding closure matrix per DEC-21-21 | MUST | | URS-21-FE-014 | Executive authority reopen modal (executive only) | MUST | | URS-21-FE-015 | Finding audit trail view consumed from URS-06 | MUST | | URS-21-FE-016 | MIRA finding context panel (read-only) per DEC-21-18 | MUST | | URS-21-FE-017 | AI-suggested content visibly labelled as advisory; not auto-saved | MUST | | URS-21-FE-018 | All Module 21 surfaces meet WCAG 2.1 Level AA | MUST | ### 15.2 Back-end (BE) | ID | Requirement | Priority | |---|---|---| | URS-21-BE-001 | Standalone finding create route via `POST /findings` | MUST | | URS-21-BE-002 | Parent-scoped finding create via `POST /reviews/:reviewId/findings` with parent-review state gating | MUST | | URS-21-BE-003 | Severity captured at create per DEC-21-08 | MUST | | URS-21-BE-004 | Severity-gated mandatory CAPA enforced at resolution per DEC-21-09 | MUST | | URS-21-BE-005 | CAPA-linkage entity model with `link_type` per DEC-21-10; emits `finding_capa_linked` event | MUST | | URS-21-BE-006 | Investigations hook to URS-17 RCA per DEC-21-11 | MUST | | URS-21-BE-007 | Status transition route uses `withAuthority(.)` + Controlled Approval Modal e-sign per DEC-21-06 | MUST | | URS-21-BE-008 | Transition notes persisted per DEC-21-14 | MUST | | URS-21-BE-009 | Resolution enforces SoD-21-03 + bound e-sig + linked-CAPA check | MUST | | URS-21-BE-010 | Closure enforces SoD-21-04 + bound e-sig + linked-CAPA terminal check | MUST | | URS-21-BE-011 | Critical-finding closure matrix per DEC-21-21 with SoD-21-07 | MUST | | URS-21-BE-012 | Bound e-signature persistence on `resolved_e_sig_id` and `closed_e_sig_id` per DEC-21-13 | MUST | | URS-21-BE-013 | Post-closure immutability via `assertFindingMutable(.)` on every mutation route | MUST | | URS-21-BE-014 | Reopen as governed transition `closed → in_progress` per DEC-21-22 + SoD-21-06 | MUST | | URS-21-BE-015 | Audit-log writes atomic with originating action per URS-04 BR-04-15 | MUST | | URS-21-BE-016 | Reason-for-change captured for every UPDATE after `open` | MUST | | URS-21-BE-017 | Multi-dimensional context persistence: `study_id`, `site_id`, `product_id`, `supplier_id`, `batch_id`, `project_id`, `process_scope` per registry schema | MUST | | URS-21-BE-018 | Canonical status set aligned across backend service, shared DB type, workflow code, and frontend hooks per DEC-21-23 | MUST | | URS-21-BE-019 | `finding_created`, `finding_status_changed`, `finding_capa_linked` events emitted | MUST | ### 15.3 Data (DATA) | ID | Requirement | Priority | |---|---|---| | URS-21-DATA-001 | `findings` per DEC-21-01 with required scope anchor enforcement | MUST | | URS-21-DATA-002 | `finding_capa_links` per DEC-21-10 | MUST | | URS-21-DATA-003 | `finding_evidence_refs` typed extraction from `evidence_jsonb` | MUST | | URS-21-DATA-004 | `finding_lifecycle_events` append-only with hash chain | MUST | | URS-21-DATA-005 | `finding_approvals` per-slot signature table for critical-finding matrix | MUST | | URS-21-DATA-006 | `finding_transition_notes` per DEC-21-14 | MUST | | URS-21-DATA-007 | RLS on every finding-scoped table per QS-6 | MUST | | URS-21-DATA-008 | Bound e-signature payload persistence on `resolved_e_sig_id`, `closed_e_sig_id` | MUST | ### 15.4 AI / HITL (AI) | ID | Requirement | Priority | |---|---|---| | URS-21-AI-001 | NO LLM / GenAI in classification / severity / CAPA-linkage / resolution / closure decision paths per the internal Annex 22 control | MUST (negative) | | URS-21-AI-002 | Static deterministic AI MAY surface similar prior findings + suggested severity + suggested CAPA links (advisory only) per ARCH-AI-001 AC-2 | MUST | | URS-21-AI-003 | Advisory output visibly labelled per ARCH-AI-001 AC-3 | MUST | | URS-21-AI-004 | Advisory output never autonomously writes to finding tables per ARCH-AI-001 AC-4 | MUST | | URS-21-AI-005 | AI service errors degrade gracefully per ARCH-AI-001 AC-7 | MUST | | URS-21-AI-006 | MIRA copilot read-only mapping `finding → findings` via `useMiraRecord('finding', id)` (per URS-32); no MIRA write path | MUST | | URS-21-AI-007 | Internal forward-looking AI governance evidence (EU AI Act Art. 13 transparency principles) | MUST | | URS-21-AI-008 | Internal forward-looking AI governance evidence (EU AI Act Annex III high-risk classification approach) | MUST | | URS-21-AI-009 | Finding-specific HITL decision orchestration through URS-04 `hitl` subsystem | MUST | ### 15.5 Audit (AUD) | ID | Requirement | Priority | |---|---|---| | URS-21-AUD-001 | Every Module 21 mutation produces an audit row through URS-06 | MUST | | URS-21-AUD-002 | Audit-write failure rolls back originating action | MUST | | URS-21-AUD-003 | HITL decision linkage captured in audit trail | MUST | | URS-21-AUD-004 | Bound e-signature evidence captured at resolution + closure | MUST | | URS-21-AUD-005 | Transition notes captured and persisted per DEC-21-14 | MUST | ### 15.6 Validation (VAL) | ID | Requirement | Status | |---|---|---| | URS-21-VAL-001 | Installation Qualification | Pending | | URS-21-VAL-002 | Operational Qualification | Pending | | URS-21-VAL-003 | Performance Qualification | Pending | | URS-21-VAL-004 | RLS enforcement evidence | Pending | | URS-21-VAL-005 | URS-06 chain integrity evidence | Pending | | URS-21-VAL-006 | SoD enforcement evidence (SoD-21-01.07) | Pending | | URS-21-VAL-007 | Post-closure immutability evidence (DEC-21-15) | Pending | | URS-21-VAL-008 | Migration evidence (canonical status alignment across layers per DEC-21-23; standalone create route per DEC-21-04; severity-gated mandatory CAPA enforcement per DEC-21-09; CAPA-linkage entity per DEC-21-10; investigations hook per DEC-21-11; authority-gated status transitions replacing user-role string comparison per DEC-21-06; transition-notes persistence per DEC-21-14; bound e-sig persistence per DEC-21-13; multi-dimensional context persistence per DEC-21-17; `assertFindingMutable(.)` extension per DEC-21-15) | Pending | | URS-21-VAL-009 | Internal forward-looking AI governance evidence (EU GMP Annex 22 Draft 2025 GenAI prohibition control) | Pending | | URS-21-VAL-010 | ARCH-AI-001 AC-2/3/4/7 advisory AI evidence pack | Pending | | URS-21-VAL-011 | Internal forward-looking AI governance evidence (EU AI Act Annex III high-risk classification approach) | Pending | | URS-21-VAL-012 | Internal forward-looking AI governance evidence (EU AI Act Art. 13 transparency principles) | Pending | | URS-21-VAL-013 | Critical-finding executive authority co-sign procedural evidence per DEC-21-21 | Pending | | URS-21-VAL-014 | Reopen executive authority co-sign procedural evidence per DEC-21-22 + SoD-21-06 | Pending | | URS-21-VAL-015 | Severity-gated mandatory CAPA evidence per DEC-21-09 | Pending | | URS-21-VAL-016 | Investigations hook evidence per DEC-21-11 | Pending | | URS-21-VAL-017 | Bound e-signature persistence evidence per DEC-21-13 | Pending | | URS-21-VAL-018 | Standalone finding create evidence per DEC-21-04 | Pending | | URS-21-VAL-019 | Authority-gated status transitions evidence per DEC-21-06 | Pending | | URS-21-VAL-020 | Multi-dimensional context persistence evidence per DEC-21-17 | Pending | ### 15.7 Integration (INT) | ID | Requirement | Priority | |---|---|---| | URS-21-INT-001 | URS-20 Reviews bidirectional (parent-scoped creation inbound; status-gated creation enforcement; finding-summary-count outbound) | MUST | | URS-21-INT-002 | URS-22 Inspection Observation inbound (standalone finding source) | MUST | | URS-21-INT-003 | URS-14 Complaints inbound (complaint trend source) | MUST | | URS-21-INT-004 | URS-15 OOS inbound (OOS trend source) | MUST | | URS-21-INT-005 | URS-16 Deviations inbound (deviation trend source) | MUST | | URS-21-INT-006 | URS-19 Risk Assessment inbound (risk-assessment-output source) | MUST | | URS-21-INT-007 | URS-18 CAPA outbound (`finding_capa_linked` event consumer + linked-CAPA terminal check) | MUST | | URS-21-INT-008 | URS-17 RCA outbound (investigations hook with `source_type = 'finding'`) | MUST | | URS-21-INT-009 | URS-13 Change Control outbound (mitigation precipitates change) | MUST | | URS-21-INT-010 | URS-22 Inspection Mgmt outbound | MUST | | URS-21-INT-011 | URS-26 APQR outbound | MUST | | URS-21-INT-012 | URS-30 Notifications outbound | MUST | | URS-21-INT-013 | URS-32 MIRA AI outbound (read-only context via `useMiraRecord('finding', id)`) | MUST | | URS-21-INT-014 | URS-06 audit substrate inbound | MUST | | URS-21-INT-015 | URS-04 Controlled Approval Modal contract + HITL subsystem + e-signature subsystem | MUST | | URS-21-INT-016 | URS-05 Authority Profile registry consumer | MUST | | URS-21-INT-017 | Internal forward-looking AI governance evidence (EU GMP Annex 22 Draft 2025) | MUST | | URS-21-INT-018 | Internal forward-looking AI governance evidence (EU AI Act Annex III high-risk classification approach) | MUST | ### 15.8 Reports (REP) | ID | Requirement | Priority | |---|---|---| | URS-21-REP-001 | Open findings register | MUST | | URS-21-REP-002 | Critical-finding register | MUST | | URS-21-REP-003 | Findings awaiting CAPA linkage | MUST | | URS-21-REP-004 | Findings awaiting closure | MUST | | URS-21-REP-005 | Reopen audit register with executive authority attribution | MUST | | URS-21-REP-006 | Source-type distribution per quarter | MUST | | URS-21-REP-007 | Finding evidence pack export | MUST | ### 15.9 Workflow (WF) | ID | Requirement | Priority | |---|---|---| | URS-21-WF-001 | Finding lifecycle state machine per DEC-21-02 | MUST | | URS-21-WF-002 | Authority-gated status transitions per DEC-21-06 | MUST | | URS-21-WF-003 | Severity classification + severity-gated mandatory CAPA per DEC-21-08 + DEC-21-09 | MUST | | URS-21-WF-004 | Resolution per DEC-21-06 + SoD-21-03 + bound e-sig + linked-CAPA check | MUST | | URS-21-WF-005 | Closure per DEC-21-16 + SoD-21-04 + bound e-sig + linked-CAPA terminal check | MUST | | URS-21-WF-006 | Critical-finding closure matrix per DEC-21-21 + SoD-21-07 | MUST | | URS-21-WF-007 | Defer transitions per DEC-21-20 with justification + quality-lead authority for critical/major | MUST | | URS-21-WF-008 | Reopen as governed transition per DEC-21-22 + SoD-21-06 | MUST | | URS-21-WF-009 | Investigations hook per DEC-21-11 | MUST | ### 15.10 Functional acceptance (FUN) | ID | Requirement | Priority | |---|---|---| | URS-21-FUN-001 | Finding create (parent-scoped + standalone) with source linkage validation | MUST | | URS-21-FUN-002 | Resolve with SoD-21-03 + linked-CAPA check + bound e-sig | MUST | | URS-21-FUN-003 | Close with linked-CAPA terminal check + bound e-sig | MUST | | URS-21-FUN-004 | Critical-finding closure with executive authority co-sign | MUST | | URS-21-FUN-005 | Reopen by executive authority with SoD-21-06 | MUST | | URS-21-FUN-006 | Post-closure mutation blocked per DEC-21-15 | MUST | --- ## 16. Test cases and Acceptance criteria ### 16.1 Test cases (TC) | ID | Test | |---|---| | TC-21-01 | Finding happy path from review parent (review-source) → owner assigned → response + evidence → CAPA linked → resolved → closed | | TC-21-02 | Finding happy path standalone from inspection observation source | | TC-21-03 | Finding happy path standalone from complaint trend | | TC-21-04 | Finding happy path standalone from OOS trend | | TC-21-05 | Finding happy path standalone from deviation trend | | TC-21-06 | Finding happy path standalone from risk assessment | | TC-21-07 | Finding happy path standalone proactive observation | | TC-21-08 | Parent-scoped create on review in `pending_approval` returns `409 FINDING_CREATION_BLOCKED_BY_REVIEW_STATE` | | TC-21-09 | Standalone create with non-existent source returns `400 SOURCE_RECORD_NOT_FOUND` | | TC-21-10 | Cross-tenant source linkage returns `400 CROSS_TENANT_SOURCE_LINKAGE_FORBIDDEN` | | TC-21-11 | Discoverer attempts to be owner returns `403 FINDING_SOD_VIOLATION_OWNER_CANNOT_BE_DISCOVERER` | | TC-21-12 | Resolve critical/major without linked CAPA returns `409 LINKED_CAPA_REQUIRED_FOR_SEVERITY` | | TC-21-13 | Resolve critical/major by creator returns `403 FINDING_SOD_VIOLATION_RESOLVER_CANNOT_BE_CREATOR_FOR_SEVERITY` | | TC-21-14 | Resolve without bound e-sig returns `400 BOUND_ESIGNATURE_REQUIRED` | | TC-21-15 | Resolve without resolution text returns `400 RESOLUTION_REQUIRED` | | TC-21-16 | Severity change post-resolution returns `409 SEVERITY_IMMUTABLE_POST_RESOLUTION` | | TC-21-17 | Mutation on closed finding returns `403 FINDING_IMMUTABLE_FINAL_STATE` | | TC-21-18 | Close with open linked CAPA returns `409 FINDING_CLOSURE_BLOCKED_BY_OPEN_LINKED_CAPAS` | | TC-21-19 | Close without rationale returns `400 CLOSURE_RATIONALE_REQUIRED` | | TC-21-20 | Close critical without executive co-sign returns `401 MISSING_FOUNDER_COSIGN` | | TC-21-21 | Critical-finding closure requires `final_quality_approver` + executive authority co-sign per DEC-21-21 | | TC-21-22 | Reopen by original closure authority returns `403 FINDING_SOD_VIOLATION_REOPEN_COSIGNER_CANNOT_BE_CLOSURE_AUTHORITY` | | TC-21-23 | Reopen by executive authority transitions `closed → in_progress`; appends new lifecycle event; preserves prior closed evidence | | TC-21-24 | CAPA link emits `finding_capa_linked` event consumed by URS-18 | | TC-21-25 | Investigations hook creates RCA in URS-17 with `source_type = 'finding'` | | TC-21-26 | Defer transition with justification; quality-lead authority required for critical/major | | TC-21-27 | MIRA copilot read-only context via `useMiraRecord('finding', id)`; MIRA write paths blocked | | TC-21-28 | Internal Annex 22 negative test: any GenAI invocation in classification / severity / CAPA-linkage / resolution / closure path blocked at runtime + lint | | TC-21-29 | Multi-dimensional context: `study_id`, `site_id`, `product_id`, `supplier_id`, `batch_id`, `project_id`, `process_scope` persisted per registry schema | | TC-21-30 | Race-condition test on `display_id` generation under concurrent creates per DEC-21-03 | | TC-21-31 | Audit-write failure rolls back originating action | | TC-21-32 | Platform identity outside support envelope returns `403 PLATFORM_TENANT_ACCESS_DENIED`; SOC alert fires | ### 16.2 Acceptance criteria (AC) | ID | Acceptance criterion | |---|---| | AC-21-01 | Every finding carries one source linkage and at least one scope anchor; existence validated. | | AC-21-02 | Standalone findings supported per DEC-21-04. | | AC-21-03 | Severity captured at create; severity-gated mandatory CAPA enforced for critical/major per DEC-21-09. | | AC-21-04 | SoD-21-01 enforced: owner ≠ discoverer. | | AC-21-05 | SoD-21-03 enforced: resolver ≠ creator for critical/major. | | AC-21-06 | SoD-21-04 enforced: closure authority ≠ creator. | | AC-21-07 | SoD-21-06 enforced: executive reopen co-signer ≠ original closure authority. | | AC-21-08 | Critical-finding closure matrix per DEC-21-21 enforced; SoD-21-07 enforced. | | AC-21-09 | Bound e-signature persisted on resolution (`resolved_e_sig_id`) and closure (`closed_e_sig_id`). | | AC-21-10 | Post-closure immutability per DEC-21-15 enforced via `assertFindingMutable(.)` on every mutation route. | | AC-21-11 | Reopen is governed transition per DEC-21-22; appends new investigation iteration without mutating prior closed evidence. | | AC-21-12 | Finding-specific HITL decision orchestration through URS-04 `hitl` subsystem. | | AC-21-13 | Investigations hook escalates to URS-17 RCA per DEC-21-11. | | AC-21-14 | CAPA linkage emits `finding_capa_linked` event per DEC-21-10. | | AC-21-15 | Internal Annex 22 GenAI prohibition enforced runtime + lint per DEC-21-18. | | AC-21-16 | Internal forward-looking AI governance evidence (EU AI Act Annex III high-risk classification approach) maintained. | | AC-21-17 | URS-06 hash-chain integrity preserved on every finding mutation. | | AC-21-18 | Canonical status set aligned across backend service, shared DB type, workflow code, and frontend hooks per DEC-21-23. | | AC-21-19 | Finding evidence pack export includes full finding + linked CAPAs + evidence references + lifecycle events with notes + approvals + URS-06 audit excerpt with hash-chain. | --- ## 17. Validation evidence pack ### 17.1 Validation gate URS-21-VAL-008 (Migration Evidence Gate) MUST be satisfied before "Released for validation execution": - Schema migration applied with `IF NOT EXISTS` / `IF EXISTS` guards per QS-13. - Canonical status alignment applied across backend service, shared DB type, workflow code, and frontend hooks per DEC-21-23. - Standalone finding create route mounted per DEC-21-04. - Severity-gated mandatory CAPA enforcement applied per DEC-21-09. - CAPA-linkage entity persisted per DEC-21-10 with `finding_capa_linked` event emission. - Investigations hook route mounted per DEC-21-11. - Authority-gated status transitions replace user-role string comparison per DEC-21-06. - Transition-notes persistence applied per DEC-21-14. - Bound e-signature payload persistence on `resolved_e_sig_id` and `closed_e_sig_id` per DEC-21-13. - Multi-dimensional context persistence aligned per DEC-21-17. - `assertFindingMutable(.)` extended to every mutation route per DEC-21-15. - Reopen route mounted with executive authority + SoD-21-06 + reason per DEC-21-22. ### 17.2 Validation evidence index - IQ pack (installation qualification). - OQ pack (operational qualification per finding happy path + negative paths). - PQ pack (performance qualification per §9 thresholds). - RLS evidence per QS-6. - URS-06 chain integrity evidence per DEC-21-19. - SoD enforcement evidence (SoD-21-01.07). - Post-closure immutability evidence. - Critical-finding executive authority co-sign procedural evidence. - Reopen executive authority co-sign procedural evidence. - Severity-gated mandatory CAPA evidence. - Investigations hook evidence. - Bound e-signature persistence evidence. - Standalone finding create evidence. - Authority-gated status transitions evidence. - Multi-dimensional context persistence evidence. - Internal forward-looking AI governance evidence (EU GMP Annex 22 Draft 2025 GenAI prohibition control). - Internal forward-looking AI governance evidence (EU AI Act Annex III high-risk classification approach). - Internal forward-looking AI governance evidence (EU AI Act Art. 13 transparency principles). - ARCH-AI-001 AC-2/3/4/7 advisory AI evidence pack. --- ## 18. Cross-module dependencies and integration points ### 18.1 Closed Decision Register (Module 21 inputs) | ID | Decision | |---|---| | DEC-21-01.23 | All Module 21 closed launch decisions per §2.3. | ### 18.2 Cross-module dependencies | Linked module | Direction | Source | |---|---|---| | URS-01 Authentication | Inbound | URS-01 module URS | | URS-02 RBAC | Inbound | URS-02 module URS | | URS-03 Context Gate | Inbound | URS-03 module URS | | URS-04 Workflow / HITL / E-Sign | Inbound (Controlled Approval Modal + bound e-sig + HITL) | URS-04 module URS | | URS-05 Authority Profile | Inbound | URS-05 module URS | | URS-06 Audit Trail | Inbound | URS-06 module URS | | URS-07 Study Management | Inbound (study scope) | URS-07 module URS | | URS-08 Tenant Management | Inbound (tenant context) | URS-08 module URS | | URS-09 Site / Facility | Inbound (site scope) | URS-09 module URS | | URS-10 Product / SKU | Inbound (product scope) | URS-10 module URS | | URS-11 Supplier Management | Inbound (supplier scope) | URS-11 module URS | | URS-12 Document Control | Inbound (closure-evidence + affected-document references) | URS-12 module URS | | URS-13 Change Control | Outbound (mitigation precipitates change) | URS-13 module URS | | URS-14 Complaints | Inbound (complaint trend source) | URS-14 module URS | | URS-15 OOS / OOT | Inbound (OOS trend source) | URS-15 module URS | | URS-16 Deviations | Inbound (deviation trend source) | URS-16 module URS | | URS-17 RCA | Outbound (investigations hook with `source_type = 'finding'`) | URS-17 module URS | | URS-18 CAPA | Outbound (`finding_capa_linked` event consumer + linked-CAPA terminal check) | URS-18 module URS | | URS-19 Risk Assessment | Inbound (risk-assessment output source) | URS-19 module URS | | URS-20 Reviews | Bidirectional (parent-scoped creation inbound; status-gated creation enforcement; finding-summary-count outbound) | URS-20 module URS | | URS-22 Inspection Mgmt | Bidirectional (audit-observation source inbound; finding register outbound) | URS-22 module URS | | URS-23 Batch Records | Inbound (batch scope) | URS-23 module URS | | URS-26 APQR | Outbound | URS-26 module URS | | URS-30 Notifications | Outbound | URS-30 module URS | | URS-32 MIRA AI | Outbound (read-only context via `useMiraRecord('finding', id)`) | URS-32 module URS | | EU GMP Annex 22 (Draft 2025) | Internal forward-looking architectural reference (not enacted predicate rule) | Internal forward-looking AI governance evidence (Annex 22 platform reference) | | ARCH-AI-001 AI Optionality and Manual Continuity | Architectural binding | ARCH-AI-001 platform binding | | EU AI Act Annex III (high-risk classification approach) | Internal forward-looking architectural reference (not enacted predicate rule) | EU AI Act | --- ## 19. Completeness Checklist | Item | Met | |---|---| | Header + mapping + Code Modules Mapped + Architecture Bindings (ARCH-AI-001 + Annex 22 + Annex III high-risk) | ✓ | | Glossary, primer, worked examples, regulatory anchors | ✓ | | Audience and stakeholders | ✓ | | Roles + Authority Profile catalogue + SoD constraints | ✓ | | Role-permission matrix (Module 21 administrative surface only) | ✓ | | End-to-end user journeys (28) | ✓ | | Front-end UI per §5 | ✓ | | Back-end per §6 (architecture, data model, APIs, workflow, business rules, audit, AI architecture binding) | ✓ | | Annex 22 + ARCH-AI-001 + Annex III high-risk architecture reference section | ✓ | | Cross-module wiring + Change-Impact Matrix per §7 | ✓ | | AI / Automation / HITL controls (with internal Annex 22 prohibition + finding-specific HITL orchestration) | ✓ | | Performance / scalability per §9 | ✓ | | Localisation / i18n per §10 | ✓ | | Errors + negative-path catalogue per §11 | ✓ | | Security + Observability per §12 | ✓ | | Data integrity (ALCOA+) per §13 | ✓ | | Regulatory mapping per §14 | ✓ | | URS requirements register per §15 (FE / BE / DATA / AI / AUD / VAL / INT / REP / WF / FUN) | ✓ | | Test cases + acceptance criteria per §16 | ✓ | | Validation evidence pack per §17 | ✓ | | Cross-module dependencies per §18 | ✓ | | Decisions and dependencies registered (no internal decisions outstanding)? | Yes | §18.1, §18.2 | --- ## 20. Final Module Output Quality Gate **URS approval is separate from validation execution.** This document becomes "Approved Controlled URS — released for engineering implementation and validation planning" upon signature capture in the Document Approval block; it becomes "Released for validation execution" only after URS-21-VAL-008 (Migration Evidence Gate) and the §17 validation evidence pack are satisfied. **No Module 21 internal decisions outstanding.** - **Specification ready for engineering review?** Yes — every requirement is fully specified within this URS. - **Specification ready for quality validation review?** Yes — IQ/OQ/PQ + RLS + audit chain + Annex 22 GenAI-prohibition evidence + ARCH-AI-001 AC-2/3/4/7 advisory AI evidence + EU AI Act Art. 13 transparency + SoD enforcement + post-closure immutability + critical-finding executive co-sign + reopen executive co-sign + severity-gated mandatory CAPA + investigations hook + bound e-signature persistence + standalone finding create + authority-gated status transitions + multi-dimensional context persistence evidence are itemised in §17. - **Specification ready for compliance review?** Yes — ALCOA+, 21 CFR Part 11, FDA Form 483 / EIR, 21 CFR Part 211 §211.192, EU GMP Annex 11 §16, EU GMP Chapter 1 §1.4, MHRA ALCOA+, ICH Q10 §3.2.1, ICH E6(R3), ISO 19011, GAMP 5 Cat 5, FDA CSA, WHO TRS 996 Annex 5 — all mapped in §14. EU GMP Annex 22 (Draft 2025) and EU AI Act Regulation 2024/1689 (Annex III high-risk classification approach + Art. 13 transparency principles) are treated as internal forward-looking architectural controls; jurisdiction-specific legal enforceability remains subject to a future jurisdiction-specific legal assessment. - **Specification ready for inspector / client review?** Yes — 28 journeys (§4), full requirements register (§15), evidence pack index (§17.2). - **Specification ready for Founder approval?** Yes. - **Blocking gaps?** None internal. - **Two-step release path:** 1. **Approved Controlled URS — released for engineering implementation and validation planning.** 2. **Released for validation execution.** After URS-21-VAL-008 + §17 evidence complete. --- ## Appendix A — Module 21 End-to-End Composite (Source → Owner → Response + Evidence → CAPA Link → Investigation → Resolve → Close → Immutable / Reopen) ```mermaid flowchart TD A[Trigger: Review / Inspection Observation / Complaint Trend / OOS Trend / Deviation Trend / Risk Assessment / Proactive] --> B[Create Finding - open] B --> C[Owner Assigned - SoD-21-01 + SoD-21-02] C --> D[Capture Response + Evidence] D --> E[Severity Captured + Optional Severity Change with Reason per DEC-21-08] E --> F{Severity Critical / Major?} F -- yes --> G[Mandatory CAPA Linkage per DEC-21-09] F -- no --> H[Optional CAPA Linkage] G --> I[Optional Investigations Hook to URS-17 RCA per DEC-21-11] H --> I I --> J[Status Transition with Notes per DEC-21-06 + DEC-21-14] J --> K{Outcome} K -- resolve --> L[Resolution - SoD-21-03 + bound e-sig + linked-CAPA check - resolved] K -- defer --> M[Deferral with Justification per DEC-21-20 - deferred] L --> N[All Linked CAPAs Terminal? Closure Rationale?] M --> N N -- yes --> O{Severity Critical?} N -- no --> P[Closure Blocked] O -- yes --> Q[final_quality_approver + Executive Authority Co-Sign per DEC-21-21 + SoD-21-07 + bound e-sig] O -- no --> R[Severity-Driven Closure Authority - SoD-21-04 + bound e-sig] Q --> S[closed] R --> S S --> T[Immutable Parent + Linked-CAPA Refs per DEC-21-15] T -. Reopen Path.-> U[Executive Authority Reopen - DEC-21-22 + SoD-21-06] U --> V[closed -> in_progress; new investigation iteration appended; prior closed evidence preserved] V --> D D -. MIRA read-only context.-> W[useMiraRecord finding id - per DEC-21-18 - AI advisory only - NOT auto-saved] ``` Diagram Appendix A — Module 21 End-to-End Composite. Trigger → finding create with source linkage → owner assignment per SoD-21-01/02 → response + evidence capture → severity classification with optional change → severity-gated mandatory CAPA per DEC-21-09 → optional investigations hook to URS-17 RCA → authority-gated status transitions with notes per DEC-21-06 + DEC-21-14 → resolution per SoD-21-03 + bound e-sig + linked-CAPA check or deferral with justification per DEC-21-20 → linked-CAPA terminal check + closure rationale → critical-finding closure matrix per DEC-21-21 + SoD-21-07 (executive authority co-sign) or standard closure per DEC-21-16 + SoD-21-04 + bound e-sig → immutable parent + linked-CAPA refs per DEC-21-15 → executive-authority-cosigned reopen path per DEC-21-22 + SoD-21-06; MIRA copilot read-only context integration per DEC-21-18. Verixa treats EU GMP Annex 22 Draft 2025 and EU AI Act high-risk / transparency concepts as internal forward-looking AI governance controls unless a jurisdiction-specific legal assessment determines otherwise; under the internal control, generative AI is prohibited in classification / severity / CAPA-linkage / resolution / closure decision paths and the module is internally classified high-risk AI. ARCH-AI-001 governs advisory deterministic AI in similarity / signal surfacing. Binding predicate-rule obligations remain those listed in §14. — End of Module 21 User Requirements Specification —