Validation plan
| Document id | CS-VAL-01 |
| Title | Validation plan |
| Version | 1.0 |
| Applies to | Countersign 1.0.0 |
| Status | Template supplied with the software; to be completed, reviewed and approved by the regulated user |
Approval of the completed document:
| Role | Name | Signature | Date |
|---|---|---|---|
| Prepared by | |||
| Reviewed by | |||
| Approved by (quality assurance) |
1. Purpose
This plan defines how ______________________ (organisation) will establish and document that its installation of Countersign is fit for its intended use, and how the validated state will be maintained.
2. Scope
2.1 Intended use (complete)
| Item | Entry |
|---|---|
| Business process supported | |
| Records held (record types) | |
| Regulations and predicate rules that apply to these records | |
| Are the records GxP relevant, and why | |
| Are approvals in Countersign used as electronic signatures required by a predicate rule | |
| Sites and departments | |
| Approximate number of users, records, changes per month | |
| Systems that consume data from Countersign (interfaces, reports, exports) |
2.2 In scope
- The Countersign application, version 1.0.0, release identified by ______________________ (tag and commit hash).
- The configuration document of this installation, identified by its SHA-256 as printed by
countersign status. - The server path: storage adapter ______________________ (PostgreSQL recommended) and sign-in method ______________________ (Microsoft Entra ID, another OpenID Connect provider, or a trusted reverse proxy).
- The environments: test ______________________ and production ______________________.
- The command-line tool (
countersign: init, status, verify, config, import, export). - Data migration from ______________________ (delete if none).
2.3 Out of scope
- The demo path (no
COUNTERSIGN_STORAGEset, data in the browser's localStorage) and demo sign-in (COUNTERSIGN_AUTH=demo). Neither may be used for regulated records. - The memory store (lost on restart) and, unless justified here, the file and SQLite stores.
- Qualification of the identity provider, the database platform, the operating system and the network as products; they are covered by ______________________ (reference your infrastructure qualification).
- Reports and interfaces built by the organisation on top of the database view or the exports: validate them separately.
3. System description
Countersign is a four-eyes record system. Summary for this plan; details in the functional specification and Architecture.
| Aspect | Description |
|---|---|
| Records | Record types and fields come from a configuration document. Two record types are built in: option definitions and option values, which are inherited along the configured hierarchy |
| Changes | Every change is a command processed by one rules engine. A version passes Created, Confirmed, Approved; a change takes effect only when a second authorised person approves it |
| Versions | Every version is kept. The newest approved version is the one in effect |
| Audit trail | Every accepted command writes exactly one entry in an append-only, SHA-256 hash-chained audit trail. A refused command writes nothing |
| System of record | The audit trail is the only thing stored. The state of all records is obtained by replaying it; the server re-checks every entry it reads |
| Storage | PostgreSQL (recommended), SQLite, an append-only file, or memory. PostgreSQL and SQLite enforce append-only with triggers |
| Identity | OpenID Connect (Microsoft Entra ID by default), or headers from a trusted reverse proxy. Roles come from token claims or headers through a role map |
| Signature | An approval records the signer's id, name, roles, the time, the stated meaning and how the person was identified; with OpenID Connect it requires a sign-in no older than COUNTERSIGN_SIGN_MAX_AGE_MINUTES (default 15) |
| Administration | Imports are possible only through the command-line tool. A configuration change is proposed and approved by two people with the configure permission, in the application or with the tool; applying one in a single step is possible only with the tool |
| Interfaces | HTTP API used by the web interface (API); a read-only database view countersign_audit_trail; exports as JSON, JSON Lines and CSV |
Software category: see README, section 4. Confirmed category for this installation: ______.
4. Roles and responsibilities
| Role | Name | Responsibilities |
|---|---|---|
| Process owner | Owns the intended use and the user requirements; approves the configuration; accepts the system for use; owns the SOPs | |
| System owner | Owns the installation: availability, access to the server and database, backup, change control, incident handling; runs the command-line tool | |
| Quality assurance | Approves plan, requirements, risk assessment, protocols, deviations and the summary report; independent review of evidence | |
| Validation lead | Writes the plan and protocols, coordinates execution, compiles the report | |
| System administrator | Installs and configures; executes the IQ | |
| Database administrator | Applies the schema, creates roles and grants, configures backup; has no application role in Countersign | |
| Identity administrator | Maintains groups and role assignments in the identity provider on approved request | |
| Testers | Execute OQ and PQ cases; must be trained and must not review their own results | |
| Key users | Define and execute PQ scenarios |
Segregation of duties to confirm: people with database or server administration rights hold no author or approve role in Countersign; the person who proposes or applies a configuration change is not the one who approves or reviews it (the engine enforces different ids).
5. Lifecycle approach
The approach is risk-based: effort follows the risk to patient safety, product quality and data integrity, the novelty and complexity of the system, and what the supplier's verification already covers.
| Phase | Activity | Output |
|---|---|---|
| Plan | Define intended use, category, roles, scope | This plan, approved |
| Specify | Tailor user requirements; review the functional specification; write the configuration | User requirements; approved configuration document; functional specification acknowledged |
| Assess risk | Assess each function for your use; decide controls and test depth | Risk assessment |
| Assess supplier | Record what the project provides and decide compensating measures | Supplier assessment |
| Verify | IQ, OQ (automated, manual, negative), PQ; trace requirements to evidence | Executed IQ, OQ, PQ; traceability matrix; OQ execution report from node scripts/oq-report.ts |
| Prepare operation | Procedures, training, backup and restore test, anchoring set up, access granted | Approved SOPs (templates); training records; first anchor record |
| Migrate (if any) | Rehearsal, run, reconciliation | Migration report and cross-reference, signed (Migration) |
| Report and release | Summarise results and deviations; QA release | Validation summary report |
| Operate | Change control, audit trail review, periodic review | Records per SOP |
| Retire | Export and archive; verify readability | Retirement report |
Leveraging supplier verification: the 80 functional requirements verified by automated tests are verified by running
the project's suite in your environment (OQ part A) instead of rewriting those tests. The 8 user-interface requirements
(FR-UI-01 to FR-UI-08) are verified by the project's end-to-end walkthrough (scripts/guide-shots.mjs) and again by
your manual cases (OQ part B). High-risk functions are additionally tested by hand and at database level (OQ parts B
and C). Justification for this approach in your context: ______________________.
6. Deliverables
| Deliverable | Document | Required | Approved by |
|---|---|---|---|
| Validation plan | CS-VAL-01 (this document) | Yes | Process owner, QA |
| User requirements | CS-VAL-02 | Yes | Process owner, QA |
| Functional specification | CS-VAL-03 | Yes (review) | System owner |
| Configuration document | Yours; identified by SHA-256 | Yes | Process owner, QA |
| Risk assessment | CS-VAL-04 | Yes | Process owner, system owner, QA |
| Traceability matrix | CS-VAL-05, plus your own for requirements you add | Yes | QA |
| IQ protocol and report | CS-VAL-06, per environment | Yes | System owner, QA |
| OQ protocol and report | CS-VAL-07 with the generated execution report attached | Yes | QA |
| PQ protocol and report | CS-VAL-08 | Yes | Process owner, QA |
| Regulatory assessment | CS-VAL-09, assessed | If Part 11 or Annex 11 applies | QA |
| Data integrity assessment | CS-VAL-10, assessed | Yes | QA |
| Procedures | From CS-VAL-11 | Yes | Process owner, QA |
| Supplier assessment | CS-VAL-12 | Yes | QA |
| Migration report | Generated by countersign import |
If data is migrated | Process owner, QA |
| Training records | Yours | Yes | Process owner |
| Validation summary report | Yours | Yes | Process owner, QA |
The validation summary report states: the versions and hashes validated; each deliverable and its status; test totals; every deviation with its resolution; open items and conditions; residual risks accepted; and the release statement.
7. Acceptance criteria
The system is accepted for use when all of the following hold.
| No. | Criterion |
|---|---|
| 1 | All deliverables marked required in section 6 are approved |
| 2 | IQ: every step passed on the production environment, or deviations are closed |
| 3 | OQ part A: the automated suite ran on the qualified test environment with the storage adapter chosen for production; every test passed; no test for that adapter was skipped; the generated report is signed |
| 4 | OQ parts B and C: every case passed, or deviations are closed |
| 5 | PQ: every scenario passed with the production configuration (identical SHA-256), or deviations are closed |
| 6 | The traceability matrix shows no unverified requirement ("Unverified: 0"), and every user requirement you added is traced to a passed test |
| 7 | No open critical or major deviation; minor deviations have an approved plan |
| 8 | countersign verify on production reports the hash chain intact and all entries reproduced; the first head-hash anchor is recorded |
| 9 | SOPs are effective and the users are trained |
| 10 | Backup and restore have been tested, including verification of the restored trail |
8. Deviations
A deviation is any difference between an expected and an actual result, any step that could not be executed as written, and any change to an approved protocol during execution.
- Stop, record the actual result and mark the step failed. Do not overwrite the expected result.
- Open a deviation record: unique number, protocol and step, description, date, who found it.
- Classify: critical (data integrity, four eyes, audit trail, access control, signatures), major (a requirement not met with a workaround), minor (documentation, cosmetic, test error).
- Investigate the cause: test error, environment, configuration, software defect, requirement error.
- Decide and record the resolution; QA approves. Re-test the failed step and anything the fix could affect.
- A software defect is also reported to the project (security-relevant ones privately, see
SECURITY.md). - List every deviation in the protocol's deviation log and in the summary report.
9. Change control after release
| Change | Minimum actions |
|---|---|
| Configuration document (record types, fields, roles, permissions) | Change request; review of the new document; countersign config validate; test in the test environment; propose it in the application (or countersign config propose) with the reason, and have a second person approve it there after reviewing the listed changes and their effect on existing records (in an emergency: countersign config apply giving reason and reviewer); record the new SHA-256; update PQ evidence where the change touches a scenario; training if roles change |
| Role map or identity-provider group assignments | Change request for the map; access request for individual assignments; verification that a test user gets the intended role |
| Environment variables | Change request; repeat the affected IQ steps |
| Countersign version | Read CHANGELOG.md; impact and risk assessment; install in test; repeat OQ part A completely, parts B and C by risk, PQ by risk; repeat IQ on production; countersign verify before and after |
| Node.js, PostgreSQL, operating system, reverse proxy | Per your infrastructure change procedure; repeat the IQ version steps; run OQ part A after a major version change of Node.js or PostgreSQL |
| Database schema, triggers, roles, grants | Not expected in operation. Treat any such change as major; repeat IQ database steps and OQ part C |
| Emergency change | As above, with retrospective approval within ______ working days |
Procedures: SOP templates, sections 4 and 10.
10. Periodic review
Interval: ______ months (commonly 12; shorter in the first year of a novel system). Scope and record: see the periodic review procedure in SOP templates. The review confirms that the system is still in its validated state and decides whether revalidation is needed.
11. Training
| Group | Content | Record |
|---|---|---|
| Authors and approvers | User guide; meaning of Confirm and Approve; accountability for electronic signatures; reasons for change | |
| Audit trail reviewers | Data integrity, sections 2 and 9; the review SOP | |
| System owner, administrators | Operations, Deployment, Storage, Authentication; integrity-fault and backup SOPs | |
| Testers | This plan, section 8; good documentation practice |
12. References
| Reference | Title |
|---|---|
| Your computerised systems validation policy | |
| Your risk management procedure | |
| Applicable regulations and guidance (confirm the versions in force) | |
| CS-VAL-00 to CS-VAL-12 | This pack (README) |