--- gxpmd_version: "3.0.0" project: name: "YOUR_PROJECT_NAME" id: "YOUR_PROJECT_ID" version: "0.1.0" owner: "YOUR_NAME " contact: "quality@YOUR_ORG.com" regulatory: profile: pharma-standard # pharma-standard | medical-device | clinical-trial | laboratory jurisdictions: [FDA, EMA] frameworks: - "21 CFR Part 11" - "EU Annex 11" gamp_category: 5 # 1=Infrastructure, 3=COTS, 4=Configured, 5=Custom risk: overall: HIGH # HIGH | MEDIUM | LOW matrix: HIGH: coverage_threshold: 95 required_tiers: [IQ, OQ, PQ] signing_required: false review_required: true MEDIUM: coverage_threshold: 80 required_tiers: [OQ, PQ] signing_required: false review_required: false LOW: coverage_threshold: 60 required_tiers: [OQ] signing_required: false review_required: false annotations: schema_version: "2.0" required_tags: source: ["@gxp-satisfies", "@gxp-implements", "@gxp-risk"] test: ["@gxp-verifies", "@test-type", "@gxp-risk"] edge_tags: ["@gxp-satisfies", "@gxp-implements", "@gxp-verifies", "@gxp-derives-from"] format: block_comment # block_comment | decorator | companion_file artifacts: directory: .gxp engine: none # rosie | custom | none formal_artifacts: optional # required | optional | none traceability_enforcement: strict # strict | warn | off gates: pre_commit: [annotations_valid, no_untagged_gxp_code] pre_merge: [all_tests_pass, coverage_meets_threshold, review_complete_if_required, no_orphan_annotations] per_release: [harden_sweep_complete, traceability_matrix_current, evidence_packages_complete, compliance_status_generated, risk_assessment_current] harden: frequency: per_sprint # per_sprint | per_release | manual outputs: [traceability_matrix, compliance_status_report, evidence_packages, gap_analysis] agent: mode: risk_proportionate # strict | risk_proportionate | advisory --- # GxP.MD -- Compliance Instructions for AI Coding Agents (v3) **This file is the compliance contract for this project.** An AI agent reading only this file has everything it needs to operate compliantly. Traceability lives in code annotations. Compliance is enforced at gates. No external documentation dependency. --- ## 1. Session Start Protocol When you begin a session on this project: 1. **Read this file.** Parse the YAML frontmatter for risk matrix, annotation requirements, and gate definitions. 2. **Read `.gxp/system_context.md`** if it exists, to understand system boundaries and intended use. 3. **Determine the risk level** of the area being modified by checking existing `@gxp-risk` annotations in the relevant source files and the risk matrix above. If resuming work on an existing project, scan for existing annotation IDs (e.g., `grep -r "@gxp-satisfies" src/`) to understand current traceability state and avoid ID conflicts. Report noteworthy findings (HIGH risk components in scope, incomplete annotation chains) to the human operator before proceeding. The session start is intentionally minimal -- no full codebase scan required. --- ## 2. Annotation Schema Annotations are the source of truth for traceability. They live in code, move with code, and are reviewed with code. Traceability is a directed acyclic graph (DAG) built via edge tags, not a hierarchy encoded in IDs. Separate `.gxp/` artifact files are optional depth, not mandatory overhead. ### What Is GxP-Relevant Code? Code is GxP-relevant if it processes, stores, or transmits regulated data, implements logic affecting product quality, safety, or efficacy, or enforces access controls or audit trails. Configuration files, build scripts, and presentation-only UI components are generally NOT GxP-relevant unless they directly affect regulated data flow. When uncertain, annotate — false positives cost less than false negatives. ### Source File Annotations Every source file implementing GxP-relevant logic MUST include: | Tag | Format | Purpose | |-----|--------|---------| | `@gxp-satisfies` | `@gxp-satisfies REQ-NNN "description"` | Requirement(s) this code satisfies | | `@gxp-implements` | `@gxp-implements SPEC-NNN "description"` | Specification(s) this code implements | | `@gxp-risk` | `@gxp-risk HIGH\|MEDIUM\|LOW` | Risk classification | Example (TypeScript): ```typescript /** * @gxp-satisfies REQ-001 "System shall authenticate users via secure credential exchange" * @gxp-implements SPEC-001 "OAuth2 PKCE flow implementation" * @gxp-risk HIGH */ export async function authenticateUser(credentials: LoginCredentials): Promise { // implementation } ``` **Multiple Edges**: A single source file or function may satisfy multiple requirements or implement multiple specifications. Use multiple tags on the same block comment: ```typescript /** * @gxp-satisfies REQ-001 REQ-003 "Dual-requirement compliance" * @gxp-implements SPEC-001 SPEC-002 "Dual implementation" * @gxp-risk HIGH */ ``` ### Test File Annotations Every test file verifying GxP-relevant functionality MUST include: | Tag | Format | Purpose | |-----|--------|---------| | `@gxp-verifies` | `@gxp-verifies SPEC-NNN` | Specification being verified | | `@test-type` | `@test-type IQ\|OQ\|PQ` | Verification tier | | `@gxp-risk` | `@gxp-risk HIGH\|MEDIUM\|LOW` | Risk level of tested component | Example (Vitest): ```typescript /** * @gxp-verifies SPEC-001 * @test-type OQ * @gxp-risk HIGH */ describe("User authentication - OAuth2 PKCE login flow", () => { it("should reject invalid credentials with 401", () => { /* ... */ }); it("should issue access token on valid credentials", () => { /* ... */ }); }); ``` ### Placement Rules - Tags MUST appear in a block comment at file top or immediately preceding the function/class/describe block they govern. - A single file MAY contain multiple annotation blocks governing different sections. - Tags MUST use exact format. Invalid syntax fails the pre-commit gate. - Description strings in `@gxp-satisfies` and `@gxp-implements` are RECOMMENDED but not required. ### How the Chain Works (DAG Model) In v3, traceability is a directed acyclic graph where nodes are artifacts (REQ, US, SPEC, source code, tests) and edges are defined by tags. IDs are opaque — no parent encoding. The chain is built at test/harden time by resolving edge tags: ``` REQ-001 ─@gxp-satisfies→ US-001 REQ-001 ─@gxp-satisfies→ US-002 US-001 ─@gxp-implements→ SPEC-001 US-001 ─@gxp-implements→ SPEC-002 SPEC-001 ─implemented by→ src/auth/login.ts src/auth/login.ts ─@gxp-verifies→ tests/oq/auth/login.test.ts ``` Source annotations declare `@gxp-satisfies` (links to REQ) and `@gxp-implements` (links to SPEC). Test annotations declare `@gxp-verifies` (links to SPEC). Formal artifact files (REQ-NNN.md, US-NNN.md, SPEC-NNN.md) may reference these edges via YAML frontmatter (`satisfies`, `implements` fields) for explicit documentation. The graph is validated and rendered during harden mode. ### Assigning New IDs IDs are opaque and non-hierarchical. To assign a new ID, scan existing annotations across the codebase for the highest sequence number and increment. For example: - If the highest existing requirement is `REQ-012`, the next is `REQ-013` - If the highest existing user story is `US-005`, the next is `US-006` - If the highest existing spec is `SPEC-008`, the next is `SPEC-009` Always verify by searching: `grep -rn "@gxp-satisfies\|@gxp-implements\|@gxp-verifies" src/ tests/` Do NOT encode the parent ID into the child ID. Use edge tags to express relationships instead. --- ## 3. Develop Mode Develop mode is the day-to-day operating mode. It is lightweight and annotation-driven. ### Writing Code 1. **Annotate.** Add `@gxp-satisfies`, `@gxp-implements`, and `@gxp-risk` to every source file with GxP-relevant logic. Annotations MAY be added during coding or immediately after, as long as they are present before commit. 2. **Risk-assess.** Determine HIGH/MEDIUM/LOW for the component. Apply enforcement rules from the risk matrix. 3. **Preserve annotations.** Do NOT remove or modify existing annotations unless the traceability mapping has genuinely changed. 4. **Log new risks.** If the change introduces a new risk vector (new external dependency, PHI data flow, auth changes), add an entry to `.gxp/risk_assessment.log` using this format: ``` ## RISK-{NNN}: {Title} - **Date:** YYYY-MM-DD - **Author:** author@example.com - **Component:** path/to/affected/code - **Risk Level:** HIGH | MEDIUM | LOW - **Description:** What risk was identified. - **Impact:** What could go wrong if the risk materializes. - **Mitigation:** Controls in place to reduce the risk. - **Status:** open | mitigated | accepted | closed ``` Assign the next sequential `RISK-NNN` ID by checking the existing log. Entries are append-only and chronological. You are NOT required to create separate artifact files in `.gxp/` before writing code. Annotations are sufficient for gate passage. You MAY code first, plan first, or use any workflow -- gates enforce compliance, not process. ### Writing Tests Organize tests by verification tier: ``` tests/ iq/ # Installation Qualification: dependencies, health checks, migrations oq/ # Operational Qualification: unit, integration, API contract tests pq/ # Performance Qualification: e2e, user workflows, load tests ``` All test files for GxP-relevant functionality MUST include the three required test annotations. Evidence capture is CI-native during develop mode -- the test runner produces output, CI captures it. Do NOT manually create evidence packages during development. --- ## 4. Harden Mode Harden mode formalizes the compliance state. It runs at the cadence set by `harden.frequency` (default: `per_sprint`). There is no separate audit mode -- harden IS audit-readiness. The compliance sweep can be executed via the `gxpmd-harden.py` tool from the GxP.MD repository, or manually by following the steps below. For projects with more than ~50 source files, tooling is strongly recommended over manual agent execution. ### Per-Sprint Compliance Sweep Execute these steps at every sprint boundary: **Step 1 -- Annotation Validation.** Parse all source and test files. Validate format, resolve all IDs, flag orphans, confirm risk consistency between source and test files. **Step 2 -- Build Traceability DAG.** Walk all edge tags (`@gxp-satisfies`, `@gxp-implements`, `@gxp-verifies`, `@gxp-derives-from`) in annotations and formal artifact files. Construct the directed graph. Detect cycles (invalid) and orphaned nodes (warnings). Output to `.gxp/traceability-matrix.json`. **Step 3 -- Coverage Analysis.** Verify test coverage meets the threshold for each component's risk level. Verify all required tiers have corresponding test files. **Step 4 -- Evidence Formalization.** Collect CI test outputs from the current sprint. Organize into evidence packages in `.gxp/evidence/` with `metadata.json`, `environment.json`, `test-output.log`, and `manifest.json`. **Step 5 -- Artifact Stub Generation.** For each requirement and specification found in annotations that has no corresponding formal file in `.gxp/`, generate a stub `REQ-NNN.md` or `SPEC-NNN.md` with annotation-derived metadata and `validation_status: draft`. Existing formal files are never overwritten. **Step 6 -- Gap Analysis.** Report: missing annotations, incomplete chains, coverage shortfalls, missing evidence, stale annotations. **Step 7 -- Compliance Status Report.** Generate `.gxp/compliance-status.md` with metrics, open gaps, risk status, and sign-off section (completed by humans, not agents). ### Why Per-Sprint ALCOA Contemporaneous requires records at the time of the activity. The work happens during the sprint; the compliance record MUST also be produced during the sprint. If an auditor arrives on any given day, the last harden output IS the compliance record. --- ## 5. Risk-Level Behavior ### Classification Criteria Assign risk levels based on impact: - **HIGH**: Patient safety, regulatory submission data, authentication/authorization, audit trails, data integrity mechanisms — failure could cause patient harm or regulatory violation. - **MEDIUM**: Business logic, data processing, API endpoints, external integrations, reporting — failure causes incorrect results but not direct safety impact. - **LOW**: Utilities, formatting, configuration, UI presentation, developer tooling, logging — failure causes inconvenience, not data integrity or safety issues. When uncertain, classify one level higher and consult the human operator. ### Flagging Risk Disagreements If you believe an existing risk classification is incorrect (e.g., a component marked MEDIUM should be HIGH), do NOT change the `@gxp-risk` tag. Instead: 1. Add a comment in the source file: `// @gxp-risk-concern "Recommend HIGH — handles PHI data flow"` 2. Add an entry to `.gxp/risk_assessment.log` with status `review_requested`. 3. Report the concern to the human operator. The `@gxp-risk-concern` tag is informational only — it does not affect gate enforcement. The human operator reviews the concern and either upgrades the risk level or acknowledges it. ### HIGH Risk **MUST:** Complete annotation coverage (`@gxp-satisfies`, `@gxp-implements`, `@gxp-risk HIGH` on source; `@gxp-verifies`, `@test-type`, `@gxp-risk HIGH` on tests). Coverage >= threshold (default 95%). All three tiers (IQ, OQ, PQ). Peer review before merge. Update risk assessment log for behavioral changes. **SHOULD:** Create formal artifact files (`REQ-NNN.md`, `SPEC-NNN.md`) in `.gxp/` for complex regulatory justification. **MUST NOT:** Skip tests to pass gates. Modify evidence after generation. Merge without review. Change risk levels without human authorization. ### MEDIUM Risk **MUST:** `@gxp-implements` and `@gxp-risk MEDIUM` on source and test files. Coverage >= threshold (default 80%). OQ and PQ tiers. **MAY:** Omit IQ if infrastructure unchanged. Proceed without peer review if automated gates pass. Omit formal artifact files. ### LOW Risk **SHOULD:** `@gxp-implements` and `@gxp-risk LOW` on source files. Coverage >= threshold (default 60%). OQ-tier tests. **MAY:** Omit IQ and PQ tiers. Omit `@gxp-satisfies` and `@gxp-verifies`. Omit formal artifact files entirely. --- ## 6. Quality Gates ### Pre-Commit | Check | Rule | |-------|------| | `annotations_valid` | All `@gxp-*`, `@test-type` annotations in modified files conform to Section 2 format. | | `no_untagged_gxp_code` | All modified source files with GxP-relevant logic include at minimum `@gxp-implements` and `@gxp-risk`. | ### Pre-Merge | Check | Rule | |-------|------| | `all_tests_pass` | All tests for affected components pass across all required tiers. Zero failures. | | `coverage_meets_threshold` | Coverage meets or exceeds the risk-level threshold for every modified component. | | `review_complete_if_required` | Peer review approved where `review_required: true` for the component's risk level. | | `no_orphan_annotations` | All annotation IDs resolve to a corresponding annotation in another file or a formal artifact. | ### Per-Release (Harden) | Check | Rule | |-------|------| | `harden_sweep_complete` | Compliance sweep (Section 4) executed for this sprint/release. | | `traceability_matrix_current` | `.gxp/traceability-matrix.json` reflects current annotation state and DAG. | | `evidence_packages_complete` | Evidence packages exist for all test executions in the current cycle. | | `compliance_status_generated` | `.gxp/compliance-status.md` generated with current metrics and gaps. | | `risk_assessment_current` | `.gxp/risk_assessment.log` reflects current risk landscape. | If any gate fails, do NOT proceed. Identify the failure, fix the issue, and re-attempt. --- ## 7. Evidence Capture Evidence is CI-native during develop mode and formalized during harden mode. ### Evidence Package Structure ``` .gxp/evidence/{TIER}-{SPEC_ID}-{TIMESTAMP}/ metadata.json # spec_id, tier, risk, timestamp, result, counts, coverage, state_hash environment.json # OS, runtime, node version, git commit, branch, CI info test-output.log # Complete, unedited test runner output manifest.json # SHA-256 hashes of all files in this package signature.jws # Optional: ES256 signature over manifest.json ``` ### Evidence Integrity Rules - Evidence packages MUST NOT be modified after generation. - Failed test runs MUST be preserved. Selective deletion of failure evidence violates ALCOA+. - `test-output.log` MUST contain complete, unedited runner output. No truncation. - Timestamps MUST reflect actual execution time. No backdating. - Both failing and passing evidence MUST be retained when tests are re-run. --- ## 8. Artifact Directory Structure ``` .gxp/ system_context.md # System description, boundaries, intended use (manual) risk_assessment.log # Risk register, chronological entries (manual) requirements/ # OPTIONAL: REQ-NNN.md formal requirement docs user_stories/ # OPTIONAL: US-NNN.md formal user story docs specs/ # OPTIONAL: SPEC-NNN.md formal specification docs adr/ # OPTIONAL: Architecture Decision Records evidence/ # Evidence packages (generated during harden) traceability-matrix.json # Traceability DAG (generated during harden) compliance-status.md # Compliance report with metrics (generated during harden) ``` Initialize with: ```bash mkdir -p .gxp/requirements .gxp/user_stories .gxp/specs .gxp/evidence .gxp/adr ``` Formal artifact files are OPTIONAL. Annotations in source and test files provide baseline traceability. Formal files provide additional depth for complex or HIGH risk components. During harden, the compliance sweep generates stub artifact files (`REQ-NNN.md`, `SPEC-NNN.md`) from annotation descriptions when separate files do not exist. These stubs contain the annotation-derived metadata and are marked `draft` — the team can flesh them out if additional depth is needed. ### Artifact ID Conventions | Artifact | Format | Example | |----------|--------|---------| | Requirement | `REQ-{NNN}` | `REQ-001` | | User Story | `US-{NNN}` | `US-001` | | Specification | `SPEC-{NNN}` | `SPEC-001` | | Evidence | `{TIER}-{SPEC}-{TIMESTAMP}` | `OQ-SPEC-001-20260207T143000Z` | | Risk Entry | `RISK-{NNN}` | `RISK-001` | **Key Change in v3**: IDs are opaque. No hierarchical encoding (e.g., `US-001-001` or `SPEC-001-001`). Relationships are expressed via edge tags in YAML or code annotations, creating a DAG model instead of a tree. --- ## Project-Specific Rules