Development
roadmap.

# Quality OS Roadmap

Quality OS is a configurable, installable quality-management platform for
controlled documents, change control, training, evidence capture, audit
readiness and regulated workflow management.

This roadmap distinguishes between:

- **Implemented** — working capability exists in the current application.
- **Foundation present** — core structures exist but require further
  production hardening or configuration.
- **Near-term** — current or immediately upcoming engineering work.
- **Next-stage** — major functional development after the current foundation.
- **Later-stage** — advanced configuration, additional modules and
  commissioning capabilities.

The canonical project origin and provenance statement is maintained in
`PROJECT_ORIGIN.md`.

---

## Current Implementation Status

### Implemented

Quality OS now has working foundations across controlled documents, change
control, Training, identity/security, auditability, installation management and
the public project surface.

Implemented capability includes:

- controlled-document register, revision families and lifecycle handling;
- RFC/change-register, periodic review, Draft creation and Cancel Review;
- deterministic Current-versus-Draft comparison, rendered-first comparison
  evidence and AI-assisted comparison summaries under human authority;
- configurable document metadata, document types, code families, review
  frequencies and roles;
- durable PostgreSQL audit persistence, append-only audit controls, regulated
  command foundations, authenticated identity, role/permission authorisation,
  session lifecycle and the shared electronic-signature foundation;
- revision-specific Read & Understand requirements, assignments,
  acknowledgement evidence and Training coverage administration;
- versioned competency-assessment authoring linked to exact controlled-document
  revisions;
- learner-safe approved-assessment delivery and deterministic scoring;
- governed advanced scoring and competency-assessment setup/binding;
- document-first authoring presets and AI-assisted, source-grounded question
  suggestions;
- retained per-question identity, source grounding, provenance and human review
  controls;
- installation-managed organisation/site/presentation branding with a generic
  source-controlled product identity;
- governed logo upload with immutable hash-named installation assets and
  automatic favicon derivation; and
- repository-backed public About and Roadmap surfaces under the installation
  profile's public-landing policy.

**Stage 3K2F assessment authoring is closed.** Retained closeout evidence records
functional exercise, deployment verification and human-factors review for that
engineering slice.

**Installation branding and the public project surface are closed for the
current development scope.** They remain subject to formal validation and later
controlled production-change requirements.

The next active vertical slice is **Regulatory / standards SOP gap analysis**.

### Foundation Present but Incomplete

Remaining work includes later domain integration, qualification-aware
authorisation, segregation-of-duties rules, remaining document-lifecycle and
comparison defects, commissioning hardening, production-runtime replacement,
operational qualification and formal validation evidence.

These foundations must not be interpreted as completed validation,
21 CFR Part 11 compliance or production commissioning.

### Engineering estimate

The standing planning rate is **12 engineering hours per week**. The current
rolling commissioning estimate is **112-212 engineering hours**, equivalent to
about **9.3-17.7 weeks** at that rate. From 20 August 2026, the projected
commissioning window is approximately **25 October to 22 December 2026**,
subject to scope discoveries and commissioning evidence.

## Near-Term Engineering Priorities

### 1. Close Remaining Document-Lifecycle Defects

- Verify every review path consistently resolves the correct Current and Draft
  records.
- Eliminate incomplete RFC-to-document links where possible.
- Preserve revision history without relying on ambiguous status combinations.
- Prevent Current and Superseded revisions from being overwritten through
  draft-upload paths.
- Improve visibility of upload, extraction, metadata and comparison outcomes.
- Add controlled recovery paths where automated processing fails.

### 2. Remove Authoritative Worker-Local Caching

Lifecycle, qualification, permission and signature-sensitive reads must not
depend on process-local cache state.

Work includes:

- identify authoritative queries currently served through worker-local caches;
- remove caching where correctness outweighs performance;
- introduce shared cache infrastructure only where invalidation and audit
  behaviour are controlled;
- retain explicit fresh-read paths for regulated decisions;
- test behaviour with multiple application workers.

### 3. Training, Qualification and Gated-Authorisation Architecture

The shared Training and qualification architecture is now substantially
implemented rather than awaiting initial design.

Implemented foundations include revision-specific training requirements,
Read & Understand acknowledgement, competency-assessment authoring, learner
delivery/scoring, assessment assignment completion, electronic-signature
integration, controlled source grounding and reusable qualification concepts.

Remaining Training work is driven by later observed-competency workflows,
qualified-observer rules, refresher/retraining policy, qualification expiry,
startup/exceptional authorisation and cross-module qualification gates.

### Shared Platform Foundation Progress

The durable PostgreSQL audit repository, append-only database controls,
regulated transaction foundations, authenticated identity, role/permission
authorisation, session lifecycle, shared electronic-signature foundation and
installation-profile authority are implemented.

The current development installation also has repository-backed public
project surfaces and governed installation-managed branding. Remaining platform
work is driven by domain integration, qualification-aware authorisation,
segregation-of-duties rules, commissioning hardening, production-runtime
replacement and formal validation evidence.

These controls support eventual validation. They do **not** by themselves make
Quality OS validated, commissioned or 21 CFR Part 11 compliant.

### 4. Identity, Access, Audit and Signature Foundations

Establish the technical foundations required by later modules:

- user identity and authentication;
- role-based permissions;
- contextual and qualification-based authorisation;
- segregation of duties;
- electronic-record ownership;
- audit trails;
- electronic signatures;
- signature meaning and re-authentication;
- session and account controls;
- controlled administrative delegation.

These controls are to support eventual 21 CFR Part 11 validation. The system
must not be described as compliant until formally validated and supported by
all applicable procedural, technical and predicate-rule controls.

### 5. Continue Targeted Application Decomposition

The initial low-risk route-extraction phase is substantially complete.

Further decomposition should occur where it directly supports new capability,
rather than as refactoring for its own sake:

- move remaining domain logic from routes into services;
- introduce reusable templates where duplication is material;
- reduce direct NocoDB access from presentation code;
- strengthen transaction and error boundaries;
- preserve incremental tests throughout;
- avoid wholesale rewrites.

---

## Next-Stage Functional Development

## Documentation Module

### Controlled Document Workflow

- Complete configurable document lifecycle rules.
- Add configurable approval routes by document type, site and risk.
- Add document-impact and training-impact decisions to revision approval.
- Add configurable effective-date rules.
- Add controlled review, approval, rejection and withdrawal records.
- Add revision-specific acknowledgement and qualification requirements.
- Add controlled PDF generation, watermarking and verification identifiers.

### Core Side-by-Side Comparison

The core comparison capability is a document-workflow feature and should not
be deferred until final commissioning.

Next-stage work includes:

- reliable Current-versus-Draft selection;
- side-by-side presentation;
- deterministic text differences;
- paragraph, table and structural-change indicators;
- clear added, removed and changed content;
- source and rendered-document access;
- reviewer comments and disposition;
- stored comparison evidence tied to the RFC;
- training-impact prompts based on meaningful changes.

Advanced comparison configuration remains a later-stage refinement.

---

## Learning Management System Module

Each controlled document revision may carry one or more configurable training
requirements.

The detailed target design is maintained in
`docs/TRAINING_QUALIFICATION_ARCHITECTURE.md`.

### Read and Understand

- controlled assignment to users or roles;
- access to the exact effective revision;
- explicit read-and-understand acknowledgement;
- electronic signature where configured;
- retained acknowledgement wording;
- assignment, completion and revision history;
- retraining when a later revision requires it.

Opening or scrolling through a document alone must not count as completion.

### Source-position-aware learner delivery

Accepted target architecture for the learner experience:

- progressive section/source-span document presentation rather than a required
  monolithic scrolling document;
- **Contextual competency**: questions may be presented immediately after the
  controlled source segment they assess;
- **End-of-document competency** remains configurable;
- **Mixed delivery** may combine contextual checks with a final assessment;
- Read & Understand remains a distinct acknowledgement workflow;
- question delivery is tied to exact controlled-revision source evidence;
- server-owned source spans provide the durable authoring/delivery anchor
  foundation; physical rendered page number alone is not authoritative.

The 3K2F source-span authoring foundation is implemented before the final
learner-reader delivery slice so the later LMS does not require a grounding
retrofit.

### Competency Assessment

Provide a configurable assessment-authoring module supporting:

- text;
- images;
- video;
- audio;
- attachments;
- single-answer multiple choice;
- multiple-answer questions;
- configurable answer options;
- pass marks;
- attempt limits;
- question and answer randomisation;
- question pools;
- configurable feedback;
- remediation and reassignment;
- version-controlled assessments linked to document revisions.

Historical completions must remain linked to the assessment version actually
taken.

### Observed Competency

- configurable observation checklists;
- competent, not yet competent and remediation outcomes;
- observer electronic signature;
- optional trainee acknowledgement;
- observer qualification and authorisation checks;
- document-revision linkage;
- retained observation evidence.

An observer would normally require current qualification in the procedure and
the relevant observer permission.

### Startup and Exceptional Observer Authorisation

Where no internally qualified observer exists, Quality OS must support a
controlled exception recording:

- the authorised observer;
- the authorising person;
- the basis of external competence;
- applicable procedure and revision;
- scope and restrictions;
- effective and expiry dates;
- justification;
- approvals and electronic signatures;
- complete audit history.

This must be a controlled authorisation record, not an unrestricted text field
or bypass checkbox.

### Training Impact

Each new document revision should require an explicit decision such as:

- no retraining required;
- read and understand required;
- competency assessment required;
- observed competency required;
- selected roles or users require retraining;
- all previously qualified users require retraining.

The decision and justification form part of document approval.

---

## Qualification-Gated Actions

Quality OS must distinguish between:

1. **Permission** — whether a role may perform an action.
2. **Qualification** — whether the individual is currently trained and
   competent for that action.
3. **Context** — whether the authorisation applies to the relevant site,
   department, product, method, equipment or record.

Completing training must not itself grant system permission.

Qualification-gated controls will apply to actions such as:

- document approval;
- laboratory test execution;
- result review and approval;
- material or batch Holds;
- Hold release;
- deviation and investigation approval;
- CAPA approval and closure;
- equipment operation;
- training observation;
- audit execution;
- electronic record review;
- product or batch release.

A shared authorisation service should evaluate role permission, qualification,
scope, expiry, delegation, segregation of duties and exceptional
authorisations before permitting regulated workflow actions.

---

## LIMS / Laboratory Module

Planned capabilities include:

- configurable laboratories and test areas;
- sample registration;
- test methods and specifications;
- result entry;
- calculations;
- units and limits;
- attachments and instrument output;
- result review;
- electronic approval;
- retest and resample controls;
- OOS and OOT initiation;
- method and equipment qualification checks;
- audit trail;
- retained result history.

Test execution and approval must be gated by both role permission and current
qualification for the relevant method, procedure, equipment and supporting
quality processes.

Only appropriately authorised and qualified users may:

- perform specified tests;
- approve results;
- initiate or release Holds;
- initiate investigations;
- approve OOS/OOT decisions;
- electronically sign relevant records.

---

## Quality Event Modules

Later functional modules will share the same identity, permission,
qualification, audit and signature foundations.

Planned modules include:

- Holds;
- deviations and nonconformances;
- investigations;
- CAPA;
- complaints;
- supplier quality;
- audits;
- change control;
- risk management;
- foreign-matter register;
- equipment and calibration;
- validation and verification;
- environmental monitoring;
- product and batch release.

For each module, creation, review, approval, closure and electronic signature
permissions may require different role and qualification combinations.

---

## Administration and Setup

Continue replacing hard-coded values with controlled setup data.

Planned configurable areas include:

- organisation and site structure;
- departments;
- users and roles;
- permissions;
- qualification requirements;
- document types;
- document code families;
- review frequencies;
- lifecycle rules;
- approval routes;
- training methods;
- assessment rules;
- observer permissions;
- refresher periods;
- metadata statuses;
- AI profiles;
- standards and clause sets;
- laboratories;
- methods and specifications;
- quality-event classifications;
- risk matrices;
- signature meanings;
- retention rules.

Configuration changes must be explicit, controlled and auditable.

---

## Advanced and Later-Stage Capabilities

### Advanced Comparison Configuration

- comparison profiles by document type;
- configurable ignored formatting changes;
- table-aware comparison rules;
- image-change indicators;
- configurable structural comparison;
- reviewer annotations;
- disposition of individual differences;
- accepted-change tracking;
- comparison thresholds;
- configurable training-impact prompts;
- stored rendered comparison reports.

### AI-Assisted Quality Work

AI remains advisory and must not approve controlled records or invent
controlled changes.

Potential capabilities include:

- configurable review profiles;
- document summarisation;
- comparison explanation;
- standards and clause suggestions;
- metadata assistance;
- investigation support;
- CAPA drafting support;
- evidence retrieval;
- document librarian;
- QMS relationship graph;
- background AI jobs;
- model and prompt governance;
- retained prompt and response evidence where appropriate.

### Standards and Evidence

- standards library;
- clause mapping;
- document-to-clause relationships;
- evidence packs;
- audit-readiness views;
- gap analysis;
- obligation tracking;
- standards-change impact analysis.

### Controlled Output

- controlled PDF generation;
- watermarks;
- uncontrolled-copy marking;
- QR or verification links;
- print and download controls;
- effective-copy identification;
- withdrawn-copy handling.

### Reporting and Analytics

- lifecycle dashboards;
- training compliance;
- qualification expiry;
- overdue reviews;
- CAPA and investigation trends;
- laboratory performance;
- supplier performance;
- audit findings;
- risk trends;
- data-integrity reporting;
- management-review packs.

---

## Installation, Migration and Commissioning

Quality OS is intended to support:

- blank installations;
- starter Quality OS configurations;
- imports from existing registers and systems;
- demonstration installations;
- system-agnostic deployment from Git.

Later-stage work includes:

- first-run installation workflow;
- installation-supplied organisation configuration;
- database migrations;
- controlled seed data;
- import validation;
- environment checks;
- backup and restore;
- disaster recovery;
- upgrade procedures;
- irreversible commissioning controls;
- IQ, OQ and PQ evidence;
- validation documentation;
- procedural controls;
- release and rollback governance.

Commissioning must be explicit and auditable. A development or demonstration
installation must not be mistaken for a validated production system.

---

## Technical Hardening Still Required

The initial structural hardening and low-risk route decomposition are not the
end of production hardening.

Remaining work includes:

- authentication and account controls;
- authorisation and segregation of duties;
- qualification-gated permissions;
- immutable and reviewable audit trails;
- electronic signatures;
- shared-cache or cache-free authoritative reads;
- database transaction boundaries;
- concurrency controls;
- error recovery;
- secure file handling;
- malware and content validation strategy;
- retention and archival controls;
- backup and restore qualification;
- infrastructure monitoring;
- performance testing;
- security review;
- penetration testing;
- deployment hardening;
- validation evidence;
- commissioning controls.

---

## Development Principles

- Design backward from the intended production system.
- Keep site-specific values in controlled configuration, not Python code.
- Make lifecycle state explicit and auditable.
- Keep RFC/review state in the change workflow rather than mutating the
  Current document into a temporary review state.
- Treat PostgreSQL as the intended authoritative long-term data platform.
- Keep NocoDB and n8n replaceable.
- Keep authentication, authorisation, audit, workflow and electronic
  signatures under Quality OS control.
- Treat AI as advisory only.
- Never permit AI to approve or invent controlled changes.
- Support both imported QMS data and blank installations.
- Prefer incremental inspected changes over rewrites.
- Compile, test and verify each implementation step.
- Do not claim regulatory compliance before formal validation.

### PostgreSQL audit repository foundation implemented

Implemented: PostgreSQL driver boundary, transaction helper, idempotent audit migration, append-only update/delete rejection, caller-transaction-owned audit repository and automated tests.

Still required: reviewed live migration, least-privilege grants, transaction-bound domain integration, integrity verification, operational probes and audit-review tooling.

### Audit database role separation implemented

Implemented:

- NOLOGIN owner, writer and reader audit roles;
- public-access revocation;
- writer-only insert and identity-sequence access;
- reader-only select access;
- live installation and privilege validation.

Still required:

- dedicated runtime login identities and secret management;
- transaction-bound integration with regulated business writes;
- integrity verification and audit-review tooling.

### Dedicated audit runtime logins implemented

Implemented:

- separate writer and reviewer login identities;
- password-free, repeatable role migration;
- installation-time credential generation;
- password-authentication validation;
- writer and reader privilege-boundary validation.

Still required:

- deployment-secret integration;
- connection-pool configuration;
- transaction-bound integration with regulated business writes;
- integrity verification and audit-review tooling.

### Runtime audit service boundary implemented

Implemented: typed redacted writer/reader settings, lazy Flask registration, separate connection construction and repository construction through a shared service boundary.

Next: add a transaction-scoped regulated-command service, integrate the first business mutation and audit event atomically, add rollback tests, then add reader-backed audit review queries and deployment wiring.

### Regulated-command journal foundation implemented

Implemented: durable command table, state model, idempotency key, traceability,
least-privilege grants and enqueue repository.

Next: guarded state transitions, document-retirement dispatch, requested and
outcome audit events, ambiguous-outcome reconciliation and live validation.

### Retirement command service foundation implemented

Implemented guarded command transitions, explicit authenticated context,
idempotent retirement command construction, requested/outcome audit events,
definite failure handling and ambiguous-outcome reconciliation state.

Next: implement authentication and trusted request-context construction, then
replace the legacy retirement route mutation with this command service.

### Trusted request-context foundation implemented

Implemented authenticated-principal validation, signed-session storage,
secure cookie policy, session expiry, CSRF token handling and request-level
`ActionContext` construction.

Next: implement credential verification, login/logout and access-denial audit
events; then require authentication and CSRF validation on the regulated
document-retirement route.

### Identity-store foundation implemented

Implemented the PostgreSQL identity schema, scrypt password hashing,
active/locked account controls and generic credential-failure behaviour.

Next: add a dedicated runtime authentication login, audited login/logout,
failed-attempt lockout orchestration and authenticated/CSRF-protected document
retirement route integration.

### Audited login and protected retirement implemented

Implemented the authentication runtime role definition, audited login/logout,
failed-attempt lockout orchestration and authenticated/CSRF-protected document
retirement routing.

Next: apply migrations 004-006 live, create and rotate runtime credentials,
create the initial controlled administrator account, validate privileges and
exercise retirement, reconciliation and recovery end to end.

### Authentication deployment wiring implemented

Implemented the dedicated authentication database URL, connection boundary,
browser login/logout routes, session/CSRF integration, authenticated navigation,
and a database-agnostic least-privilege authentication runtime migration.

Next: review and commit this increment, then apply migrations 004-006 live,
generate runtime credentials, create the initial controlled administrator,
validate privilege boundaries and exercise retirement and recovery end to end.

### Regulated command runtime-role repair implemented

Added migration 007 to create the missing regulated-command owner, writer and reader roles and reassert least-privilege ownership and grants before administrator provisioning.


### Step 3H6 — authorization and operating-mode foundation

Added migration 008 and shared services for explicit role/permission
authorization, initial controlled `SUPERADMIN` assignment, and durable
`DEVELOPMENT` / irreversible `COMMISSIONED` instance state. Document retirement
now requires the explicit `documentation.document.retire` permission in
addition to authentication and CSRF validation.

Still required before live deployment: review and apply migration 008,
validate the Superadmin assignment and runtime grants, expose an unmistakable
development-mode banner, implement the controlled commissioning command and
prerequisite checks, restart, and execute end-to-end privilege and recovery
tests.

### Step 3H7 — persistent operating-mode visibility

Added a durable operating-mode service and persistent application-wide banner.
The development instance displays an unmistakable `DEVELOPMENT MODE` warning
on every page. Commissioned mode remains visible, and state-read failures
produce a prominent restricted-state warning rather than silently hiding mode.

Still required: audited authorization-denial events, controlled commissioning
prerequisites and command, role administration, validation evidence, and final
commissioned-state verification.

### Step 3H8A — unauthenticated boundary and logout

Implemented the isolated full-window sign-in surface, removed authenticated navigation from
anonymous HTML, added a server-side global authentication boundary, preserved the requested path
in login redirects and made the authenticated POST logout control explicit.

Next: Step 3H8B server-side session lifecycle, configurable inactivity and absolute timeouts,
expiry warning, revocation and audited configuration.

#### Step 3H8A audit-writer privilege repair

Completed the runtime grants required by the audit repository's
`INSERT ... RETURNING sequence_no, recorded_at` statement.

The dedicated audit role has SELECT/INSERT. The authentication role retains
INSERT for transactionally coupled login/logout audit events and receives
column-level SELECT only on the two returned columns. Neither role receives
UPDATE or DELETE.

### Step 3H8B1 — session lifecycle foundation

Added the durable session-policy schema, revocable session records, domain
rules and regression tests. Next: cut login, authenticated requests, inactivity
refresh, absolute expiry and logout over to the server-side store.

### Step 3H8B2 — application cutover

Cut login, authenticated request validation, inactivity refresh and logout over
to the durable server-side session store. Next: controlled policy configuration,
warning presentation, end-to-end expiry tests and master-manual closeout.

### Step 3H8B3 — session architecture closeout

Completed controlled session-policy administration, expiry-warning presentation,
regression coverage, live service verification and master-manual revision 2.1.
The authentication/session architecture block is closed for development; formal
qualification remains required before commissioning.

### Completed — Step 3H8C production validation harness

A reusable live smoke-test harness now validates application availability,
anonymous redirection, CSRF-protected login, authenticated home access,
logout, session termination and absence of recent application tracebacks.

### Stage 3H repository boundary — completed

Completed:

- backend-neutral `RecordRepository`;
- NocoDB and fake adapters;
- repository provider;
- `DocumentRepository`;
- `ChangeRepository`;
- `MetadataRepository`;
- focused repository tests and full-suite regression coverage.

The next engineering priority is visible document-review workflow capability:

1. confirm and harden Cancel Review so the active RFC closes without mutating
   the Current document;
2. provide an explicit Create Draft Revision action;
3. exercise and complete the review-to-issue workflow through the web
   interface.

Broad service-layer or repository refactoring is deferred unless required by
one of these deliverables.

### Configurable Training requirement-type foundation implemented

Implemented:

- PostgreSQL-native controlled Training requirement-type vocabulary;
- seeded architecture types including `EXTERNAL_EVIDENCE`;
- replacement of the migration-012 hard-coded type CHECK with a foreign key;
- stable-code protection for system and in-use requirement types;
- least-privilege Training reader/writer access;
- durable `training.configuration.manage` permission vocabulary.

The existing Read & Understand vertical slice remains unchanged while the
physical model can now support later configured Training requirement types.

### Shared electronic-signature foundation and signed R&U

Implemented:

- domain-neutral PostgreSQL electronic-signature schema;
- append-only electronic-signature records;
- controlled signature-meaning vocabulary;
- signer, subject/version, digest, timestamp, session, re-authentication,
  authorisation and manifestation evidence;
- shared platform signature decision/repository code;
- permanent and transfer-guarded Training-assignment-to-signature linkage;
- password re-authentication for signature-required Read & Understand;
- denied signature-attempt audit without Training state mutation;
- atomic successful R&U state + signature + audit persistence.

Training is the first consumer. Later regulated workflows will reuse this same
platform boundary rather than build module-specific signature systems.

### Versioned assessment authoring vertical slice implemented

Implemented controlled question/scoring configuration, retained assessment
versions, exact document-revision linkage, sections, single- and multiple-answer
questions, answer options, deterministic approval validation, approved-version
immutability, new Draft version creation and the
`training.assessment.manage` permission.

Learner assignment/delivery and deterministic scoring are implemented in
3K2B below.

### 3K2B learner assessment delivery and scoring

Learner assessment delivery now retains exact attempt evidence and deterministically scores EXACT_SET_MATCH, ALL_CORRECT_NO_INCORRECT and WEIGHTED_SELECTION without exposing answer-key configuration before submission. PARTIAL_CREDIT and MINIMUM_CORRECT_COUNT remain fail-closed until their accepted customer-configurable incorrect/omission rules are represented physically and exposed in controlled authoring.

### About / Roadmap maintenance ownership

The public `/about` page is intentionally evergreen product positioning.
Changing implementation status, completed slices, known follow-up and next
engineering work belong in this roadmap rather than being duplicated in About.

### 3K2C governed advanced assessment scoring configuration

Implemented explicit version-1 customer configuration for `PARTIAL_CREDIT`
and `MINIMUM_CORRECT_COUNT`, including retained attempt snapshots, controlled
authoring inputs, deterministic scoring and database approval/immutability
guards. Historical under-specified advanced-policy questions remain
fail-closed rather than receiving inferred defaults.

Next assessment work is to exercise a controlled live assessment binding and
learner attempt end to end, then continue with the configured pass, attempt
and remediation rules defined by the Training architecture.

### 3K2D controlled competency-assessment setup and binding implemented

The Training admin workflow can now create a revision-specific
`COMPETENCY_ASSESSMENT` requirement from an Approved retained assessment
version, reuse the existing USER/ROLE target and learner-assignment backbone,
and create the immutable assessment binding in the same transaction.

Migration 018 also removes the R&U-only unconditional acknowledgement constraint
while preserving acknowledgement wording as mandatory for
`READ_AND_UNDERSTAND`, and strengthens the binding guard so requirement and
assessment version must reference the exact same controlled document revision.

The next assessment evidence step is to create a real Approved assessment and
competency assignment through this product workflow, execute a retained learner
attempt end to end, and verify the resulting attempt/audit evidence before
claiming the flow demonstrated.

### Assessment submission JSONB parameter typing corrected

The first retained learner assessment exercise exposed a PostgreSQL/psycopg
runtime typing failure in the `SUBMITTED` attempt-event insert. The score and
pass/fail values passed to `jsonb_build_object` are now explicitly cast to
`numeric` and `boolean`, respectively, so PostgreSQL does not need to infer
variadic JSON argument types from bind parameters.

The failed live submission transaction rolled back completely; the learner's
Attempt 1 remained `IN_PROGRESS` with no retained responses, score, submitted
timestamp or `SUBMITTED` event. The learner can therefore retry the original
attempt after this repair is deployed.

This is development evidence, not a validation, commissioning or compliance
claim.

### Training learner document-first workflow corrected

The learner Training register now distinguishes requirement types instead of
treating every assigned item as Read & Understand. Competency assessments route
to the retained assessment flow; Read & Understand assignments route first to
the exact controlled-document viewer.

The shared document viewer now has an explicit Training context. In ordinary
document-control use it retains the existing "Back to Document" behaviour. In
Training context it validates the learner assignment, returns to Training, and
shows only the action appropriate to the requirement type. Read & Understand
acknowledgement is performed from the controlled-document view rather than
directly from the Training register. Opening a document alone is not recorded
as completion.

The Read & Understand service now rejects non-READ_AND_UNDERSTAND assignments,
and nullable acknowledgement text remains NULL rather than being converted to
the literal string "None".

The first development competency exercise had previously been incorrectly
transitioned through the Read & Understand acknowledgement route. Its erroneous
history is retained. A separate corrective history transition restores that
development assignment to ASSIGNED with acknowledgement snapshot fields cleared
so its retained assessment Attempt 1 can continue.

This is development evidence, not a validation, commissioning or compliance
claim.

### 3K2E retained competency-assessment assignment completion implemented

Passing a retained competency assessment now completes the same shared Training
assignment used to deliver it. Migration 019 adds the generic `COMPLETED`
assignment state and a database guard requiring exact retained
`SUBMITTED`/passed competency-attempt evidence before the transition is allowed.

The application performs attempt submission, assignment completion,
assignment-history evidence and audit evidence in one transaction. The learner
register and Training-origin document viewer show completed competency
assignments as complete and no longer offer another assessment start action.
R&U remains `ACKNOWLEDGED`; qualification state remains a separate architecture
layer.

Failed submitted attempts intentionally remain `ASSIGNED` until the configured
attempt/remediation/retraining policy slice is implemented.

### 3K2F assessment-authoring workflow — closed

Stage 3K2F is closed following retained functional, deployment and human-UI
evidence.

The completed slice includes:

- governed per-question source grounding against exact controlled-document
  revisions;
- fresh controlled-source reads and retained source hashes/provenance;
- Draft-only section, question and option edit/reorder/delete operations;
- document-first question authoring presets;
- AI-assisted source-grounded question suggestions under human authority;
- explicit grounding status and rationale with fail-closed approval rules;
- per-question authoring controls and stable visible question identity;
- canonical retained Yes / No rendering derived from persisted semantics; and
- policy-relevant answer-table presentation.

The closeout is engineering commissioning evidence only. It is not a formal
validation record and does not establish 21 CFR Part 11 compliance.

### Installation-managed branding and public project surface — closed

The installation profile is durable PostgreSQL-managed installation authority
for setup state/mode, organisation/site identity, timezone/hostname and
presentation branding while `Quality OS` remains the generic product identity.

The current development scope includes:

- generic source defaults and first-run setup/profile management;
- authenticated branding administration with permission, CSRF, reason,
  optimistic profile versioning and retained audit evidence;
- repository-backed public About and Roadmap surfaces controlled by the durable
  public-landing policy;
- governed uploaded logos stored outside Git as immutable hash-named assets;
- automatic favicon reuse/derivation; and
- a database-enforced logo URL contract that permits controlled source-static
  assets and governed branding assets only.

This development closeout does not claim validated production change control,
21 CFR Part 11 compliance or commissioning.

<!-- QOS-ROADMAP-REGULATORY-SOP-GAP-ANALYSIS-V1 -->
### Active next capability — Regulatory / standards SOP gap analysis

Readiness probe RSGA-RP01 established the implementation boundary: authorised regulatory/standards sources, controlled SOPs only, exact revisions, clause-to-SOP evidence, covered/partial/not-covered/ambiguous/potential-conflict classifications, human authority, controlled follow-up, rerun/change comparison and retained provenance.

Quality OS shall support a comprehensive quality/compliance gap analysis using
regulatory documents, guidelines and standards held within the system as the
assessment basis.

The authorised user selects one or more applicable regulatory documents,
guidelines and/or standards. The assessed quality-document population is
restricted to **controlled SOPs only**, and the analysis uses the exact
controlled revision of every source and SOP.

Assessable clauses or requirements are mapped to traceable SOP evidence and
classified at minimum as **covered**, **partially covered**, **not covered**,
**ambiguous / insufficiently demonstrated**, or **potentially conflicting**.
Absence of SOP evidence is reported explicitly rather than treated as
compliance.

AI may identify, map, summarise and explain potential gaps, but remains
advisory. An authorised human reviewer retains authority to accept, reject,
edit or disposition findings. Accepted gaps can be converted into controlled
follow-up through RFC/change control, CAPA or assigned actions without losing
the originating requirement, exact SOP evidence or assessment provenance.

Assessments can be re-run after a regulatory/standards source or SOP revision,
with material changes highlighted against the retained prior assessment.
Retained provenance includes source revisions, SOP population, mappings,
findings, reviewer disposition, timestamps and applicable AI execution
metadata.

### Observed Competency first vertical slice (OCS1)

Implemented: versioned exact-revision observation checklists, explicit checklist approval, bootstrap administrative observer authorisation (not qualification), exact-revision learner assignments, no-self-observation enforcement, criterion-level retained evidence, deterministic competent/not-yet-competent outcomes, shared `PERFORMED` electronic signature binding, append-only final observation evidence, and governed assignment completion/retraining transitions.

Next Training slice: Qualification State and qualified-observer rules. The bootstrap observer-authorisation record must not be promoted into or represented as qualification state.

### Qualification State + qualified-observer rules (QFS1)

Implemented: exact-revision versioned qualification definitions; retained
COMPETENT Observed Competency evidence linkage; pending qualification state;
electronically signed `APPROVED` transition to current qualification; effective
and expiry dates; restrictions; append-only qualification status history; and
separate qualified-observer permission.

Observed Competency now evaluates normal observer authority as current
qualification + active observer permission. The OCS1 administrative
observer-authorisation remains a controlled startup/exception fallback and is
not represented as qualification.

Next Training slice: qualification lifecycle controls (suspend/revoke/supersede,
refresher/recertification and expiry workflows), followed by shared
qualification-gated actions.

### 3K2R qualification lifecycle / refresher / recertification

Qualification lifecycle now includes explicit expiry reconciliation, configurable
pre-expiry refresher windows, signed suspension/reinstatement/revocation,
retained recertification cases and controlled replacement qualification.

Training completion remains evidence rather than qualification. Qualification
remains separate from application permission, and dependent observer permission
fails closed when its supporting qualification is not current.

This is engineering capability only. It does not establish formal validation or
21 CFR Part 11 compliance.


### 3K2S shared qualification-gated authorization service

Implemented a reusable fail-closed decision boundary that composes existing
platform role permission with current exact-revision qualification,
organisation/site scope, effective/expiry state and explicit qualification
restriction handling.

Training completion remains evidence rather than application permission, and no
existing regulated action is silently cut over by this service-only slice.

Next Training slice: integrate the shared qualification gate into a selected
regulated action with action-specific scope, segregation-of-duties and signature
requirements defined explicitly.


### 3K2T first qualification-gated action integration

Document Retirement is the first regulated action connected to the shared
qualification-gated authorization service.

Migration 035 adds controlled action-to-qualification requirements with
organisation/site scope and no seeded default. Each requirement references an
exact approved qualification definition, keeping the regulated action target
separate from the controlled revision that establishes qualification.

Existing role permission remains mandatory. Where an ACTIVE requirement is
configured, retirement additionally requires a Current, effective, non-expired
qualification against that configured exact qualification source revision.

The runtime is read-only for requirement configuration in this slice.

Next Training slice: governed administration of action qualification requirements
and then expansion of the shared gate to further regulated actions after their
action-specific scope/SoD/signature rules are explicit.


### 3K2U governed action-qualification requirement administration

Implemented controlled create/retire administration for qualification-gated
actions using the existing `training.configuration.manage` permission.

Migration 036 keeps generic table mutation unavailable to the Training runtime and
exposes narrow SECURITY DEFINER create/retire functions with immutable actor and
reason provenance. Action codes now reference the canonical platform permission
registry.

The administration UI exposes only actions already integrated with the shared
gate; currently Document Retirement. It selects an Approved exact-source
qualification definition and supports Global / current Organisation / current
Site scope without arbitrary scope identifiers.

Successful create/retire transitions append audit evidence. No requirement is
seeded by deployment.

Next Training slice: exercise the first configured retirement requirement with
real qualification evidence, then expand qualification gating to the next
regulated action only after its scope, segregation-of-duties and signature
requirements are explicitly defined.

### Training searchable controlled-document selectors (3K2V)

Observed Competency checklist creation and Qualification definition creation now
use a shared searchable, naturally sorted Current-document selector while
retaining exact controlled record IDs and revisions. This is presentation-only;
qualification, evidence, authorisation, signature and audit semantics are
unchanged.

The real qualification-gated retirement exercise remains dependent on genuine
governed qualification evidence.

### Training governed-object selector UX (3K2W)

Observed Competency and Qualification State now treat existing governed Training objects
as primary navigation/selection objects rather than forcing repeated global document
lookup. Existing competency checklists are visible and searchable with exact retained
document scope and direct downstream actions. Qualification definitions, qualifications,
eligible COMPETENT observations, approved competency checklists and observer permissions
are searchable registers; dependent qualification-side choices are filtered by retained
exact document revision while authoritative IDs and backend validation are unchanged.

The global Current-document catalogue remains limited to creation of new checklist and
qualification-definition objects. Remaining Training selectors are naturally sorted and
search-enhanced as presentation-only behaviour. No schema or business-data mutation was
required.