From Intent to Specification

Figures, tables and listings

1 figure · 6 code listings

Reproduced in full, in the order they appear in the published chapter. The reasoning that connects them is in the book.

apiVersion: ea.codex/v1
kind: DecisionRecord
metadata:
  id: DEC-PV-001
  title: Pharmacovigilance platform as adverse-event system of record
  status: accepted
  date: "2026-02-15"
  owner: enterprise-architecture-council
spec:
  trigger:
    type: internal-strategic
    source: PRD-PV-INTAKE-001
  context: >
    INTENT-PV-001 and PRD-PV-INTAKE-001 introduce the architectural concern of
    AI-assisted adverse-event intake. The PRD requires AI-assisted intake
    across multiple channels and regions. Without an explicit authority
    decision, adverse-event case state may be fragmented across CRM, AI
    services, regional workflow tools, and document processing components.
  decision: >
    The pharmacovigilance platform is the authoritative system of record
    for all suspected adverse-event cases. CRM, regional workflow tools,
    document processing services, and AI agents may assist intake, routing,
    extraction, and summarization, but must not create persistent
    adverse-event case records outside the pharmacovigilance platform.
  rationale: >
    Regulatory traceability requires a single authoritative case record from
    the point at which a suspected adverse event is identified. AI-assisted
    intake and regional workflow coordination are acceptable only if they
    remain subordinate to validated pharmacovigilance case management.
  relatedSpecs:
    - INTENT-PV-001
    - PRD-PV-INTAKE-001
  rejectedAlternatives:
    - option: CRM as temporary adverse-event case repository
      reason: CRM is an intake channel, not a validated pharmacovigilance case system.
    - option: Regional workflow tools as local suspected-case stores
      reason: This would create fragmented case authority and inconsistent auditability.
    - option: AI triage service holding provisional case state
      reason: >
        This would give the AI layer persistent regulated case state without
        validated case-management controls.
  consequences:
    - AI agents may extract evidence and suggest triage, but may not create case records.
    - Regional workflow tools may manage work queues, but may not hold case authority.
    - Intake evidence must be linked to the authoritative case identifier.
    - Regulated case decisions must be approved by authorized pharmacovigilance reviewers.
  reviewTriggers:
    - Regional regulation prevents centralized case registration.
    - A new validated pharmacovigilance platform is introduced.
    - Repeated intake delays show that the current system-of-record boundary is too restrictive.
    - AI triage becomes part of a validated operating procedure.

Figure 8.1: Decision record DEC-PV-001.

# Canonical EA Codex v1.1.0 ArchitecturePackage.
# This object is the BMAD-shaped architecture package for a single governed architectural unit.
apiVersion: ea.codex/v1
kind: ArchitecturePackage
id: AP-PV-001
name: ai-assisted-adverse-event-intake
domain: Pharmacovigilance
status: approved-with-controls
version: "1.0"
brief:
  intent:
    outcome: >
      Accelerate adverse-event intake across regions using AI-assisted triage,
      while preserving regulatory traceability, human medical review, and
      authoritative case management in the pharmacovigilance platform.
    value: >
      Reduce average intake processing time by 40% during the controlled pilot
      without weakening the human regulated decision boundary.
  capabilityScope:
    - AdverseEventIntake
    - IntakeEvidenceExtraction
    - TriagePrioritization
    - HumanMedicalReview
  decisionObligations:
    - bind-authoritative-case-record-to-pv-platform
    - constrain-ai-action-boundary-to-decision-support
    - require-evidence-linkage-before-triage
    - require-human-approval-for-regulated-decisions
  intentRefs:
    - INTENT-PV-001
  prdRefs:
    - PRD-PV-INTAKE-001
  architecturalConcerns:
    - data-authority
    - system-of-record
    - ai-action-boundary
    - human-approval
    - regional-variation
    - audit-evidence
    - patient-data-retention
map:
  systems:
    - id: APP-PV
      name: Pharmacovigilance Platform
      role: adverse-event-system-of-record
      validationStatus: validated
    - id: APP-CRM
      name: Customer Interaction Platform
      role: intake-channel
      validationStatus: not-validated-for-case-management
    - id: APP-WF-REGIONAL
      name: Regional Workflow Tool
      role: local-work-queue
      validationStatus: not-validated-for-case-management
    - id: APP-AI-TRIAGE
      name: AI Triage Service
      role: decision-support-service
      validationStatus: controlled-pilot
  agents:
    - id: AGENT-PV-TRIAGE
      name: Adverse Event Intake Assistant
      permittedActions:
        - extract-intake-evidence
        - suggest-triage-priority
        - draft-case-summary
        - route-for-human-review
      prohibitedActions:
        - create-persistent-case-record
        - approve-seriousness-classification
        - confirm-case-validity
        - close-case
        - update-regulatory-reporting-status
  dataObjects:
    - id: DATA-AE-CASE
      name: Adverse Event Case
      authority: APP-PV
      classification: regulated
    - id: DATA-INTAKE-EVIDENCE
      name: Intake Evidence
      authority: APP-PV
      classification: regulated
    - id: DATA-AI-SUGGESTION
      name: AI Triage Suggestion
      authority: APP-PV
      classification: decision-support-evidence
  designDecisions:
    - id: DEC-PV-001
      topic: case-record-authority
      option: pharmacovigilance-platform-as-system-of-record
      rationale: >
        Persistent case state must remain in the validated PV platform; AI and
        regional workflows operate as decision support and intake channels only.
act:
  rules:
    - id: RULE-PV-001
      name: Authoritative case record
      statement: >
        Persistent adverse-event case records must be created and stored only
        in systems whose role is adverse-event-system-of-record.
      derivedFrom: DEC-PV-001
      evidenceSources:
        - application-inventory
        - integration-catalog
        - pharmacovigilance-case-log
        - data-lineage-register
    - id: RULE-PV-002
      name: AI action boundary
      statement: >
        AI agents must not create persistent case records, approve seriousness
        classification, confirm case validity, close cases, or update regulatory
        reporting status.
      derivedFrom: DEC-PV-001
      evidenceSources:
        - agent-permission-registry
        - agent-action-log
        - workflow-audit-log
    - id: RULE-PV-003
      name: Human regulated decision
      statement: >
        Seriousness classification, case validity confirmation, and regulatory
        reporting readiness must be approved by an authorized pharmacovigilance
        reviewer.
      derivedFrom: DEC-PV-001
      evidenceSources:
        - workflow-audit-log
        - identity-and-access-management-log
        - pharmacovigilance-case-log
    - id: RULE-PV-004
      name: Evidence linkage
      statement: >
        AI-extracted intake evidence must be linked to the authoritative
        adverse-event case identifier before it is used in triage or review.
      derivedFrom: DEC-PV-001
      evidenceSources:
        - document-processing-log
        - evidence-store
        - pharmacovigilance-case-log
  variation:
    allowed:
      - type: regulatory-localization
        authority: regional-compliance-architecture
        condition: >
          Localized intake requirements may vary by region if authoritative
          case state remains in APP-PV.
      - type: language-processing-localization
        authority: ai-governance-lead
        condition: >
          Region-specific extraction prompts or models may vary if extracted
          evidence remains linked to the authoritative case identifier.
      - type: intake-channel-localization
        authority: pharmacovigilance-process-owner
        condition: >
          Regional intake channels may vary if they do not persist
          adverse-event case state outside APP-PV.
    prohibited:
      - local-case-record-store
      - autonomous-seriousness-approval
      - autonomous-case-closure
      - patient-data-retention-in-agent-memory
      - regional-workflow-as-case-authority
  governance:
    primaryAuthority: enterprise-architecture-council
    escalationTriggers:
      - AI agent requests a prohibited action.
      - Region proposes persistent local case state.
      - Workflow variation affects seriousness classification.
      - Evidence cannot be linked to the authoritative case identifier.
      - Repeated exceptions suggest the global intake model is incomplete.
  scenarioPackRefs:
    - SCN-PV-INTAKE-V1
doubleCheck:
  monitoredSignals:
    - intake-latency
    - evidence-completeness-rate
    - ai-triage-override-rate
    - blocked-agent-action-count
    - unlinked-evidence-count
    - regional-exception-count
  reviewCadence: monthly-during-pilot
  evidence:
    - conformance: principle-compliance-runs
    - validation: scenario-pack-results
    - approval: ea-council-signoff

Figure 8.2: Architecture package AP-PV-001 (ai-assisted-adverse-event-intake).

package pv_intake.agent_permissions
import future.keywords.if
import future.keywords.in
import future.keywords.contains
default allow := false
required_architecture_package := "AP-PV-001"
required_decision := "DEC-PV-001"
prohibited_actions := {
  "create-persistent-case-record",
  "approve-seriousness-classification",
  "confirm-case-validity",
  "close-case",
  "update-regulatory-reporting-status"
}
allow if {
  input.agent.architecturePackageId == required_architecture_package
  input.agent.decisionId == required_decision
  no_prohibited_actions
  evidence_logging_configured
  human_review_route_configured
}
no_prohibited_actions if {
  every action in input.agent.requestedActions {
    not action in prohibited_actions
  }
}
evidence_logging_configured if {
  input.agent.controls.evidenceLogging == true
  input.agent.controls.actionLogTarget == "pharmacovigilance-case-log"
}
human_review_route_configured if {
  input.agent.controls.humanReviewRoute.required == true
  input.agent.controls.humanReviewRoute.role == "pharmacovigilance-reviewer"
}
deny_reasons contains msg if {
  some action in input.agent.requestedActions
  action in prohibited_actions
  msg := sprintf(
    "Action '%s' is prohibited by %s and governed by %s",
    [action, required_architecture_package, required_decision]
  )
}
deny_reasons contains "Agent actions must be logged to the pharmacovigilance case log" if {
  input.agent.controls.actionLogTarget != "pharmacovigilance-case-log"
}
deny_reasons contains "Human pharmacovigilance review route is required" if {
  not human_review_route_configured
}
result := {
  "allowed": allow,
  "agent": input.agent.id,
  "architecturePackage": input.agent.architecturePackageId,
  "decision": input.agent.decisionId,
  "denyReasons": deny_reasons
}

Figure 8.3: Rego policy pv_intake.agent_permissions.

{
  "agent": {
    "id": "AGENT-PV-TRIAGE",
    "architecturePackageId": "AP-PV-001",
    "decisionId": "DEC-PV-001",
    "requestedActions": [
      "extract-intake-evidence",
      "suggest-triage-priority",
      "draft-case-summary",
      "route-for-human-review"
    ],
    "controls": {
      "evidenceLogging": true,
      "actionLogTarget": "pharmacovigilance-case-log",
      "humanReviewRoute": {
        "required": true,
        "role": "pharmacovigilance-reviewer"
      }
    }
  }
}

Figure 8.4: Compliant agent permission request.

{
  "agent": {
    "id": "AGENT-PV-TRIAGE-V2",
    "architecturePackageId": "AP-PV-001",
    "decisionId": "DEC-PV-001",
    "requestedActions": [
      "extract-intake-evidence",
      "approve-seriousness-classification",
      "close-case"
    ],
    "controls": {
      "evidenceLogging": true,
      "actionLogTarget": "agent-local-memory",
      "humanReviewRoute": {
        "required": false,
        "role": null
      }
    }
  }
}

Figure 8.5: Non-compliant agent permission request.

# Canonical EA Codex v1.1.0 ScenarioPack.
# This object represents the validation harness bound to the architecture package and agent contract.
apiVersion: ea.codex/v1
kind: ScenarioPack
metadata:
  id: SCN-PV-INTAKE-V1
  name: pv-intake-validation-pack
  status: approved
  version: "1.0"
  domain: pharmacovigilance
  owner: pharmacovigilance-ai-governance
spec:
  scope:
    appliesTo: agent-contract
    agentContractRef: SPEC-AGENT-PV-TRIAGE-001
    capabilityRef: eatool:bc.pv.adverse-event-intake
    architecturePackageRef: AP-PV-001
  scenarios:
    - id: SCN-PV-INTAKE-001
      title: Patient reference is extracted accurately from intake source
      given: A regional adverse-event intake source from the EU, NA, or APAC ground-truth datasets is presented to the agent.
      when: The agent extracts the patient reference field.
      then: Field-level accuracy across the dataset is at least 0.95, protecting RULE-PV-004 evidence linkage.
      category: compliance
      severity: blocking
      evidenceRequired:
        - extraction-trace
        - dataset-snapshot
        - accuracy-report
    - id: SCN-PV-INTAKE-002
      title: Product name is extracted accurately from intake source
      given: A regional adverse-event intake source containing a regulated product name.
      when: The agent extracts the product name field.
      then: Field-level accuracy across the dataset is at least 0.95.
      category: compliance
      severity: blocking
      evidenceRequired:
        - extraction-trace
        - accuracy-report
    - id: SCN-PV-INTAKE-003
      title: Seriousness indicator is extracted accurately
      given: A regional adverse-event intake source containing a seriousness indicator field.
      when: The agent extracts the seriousness indicator.
      then: Field-level accuracy across the dataset is at least 0.98, protecting RULE-PV-003 human regulated decision integrity.
      category: compliance
      severity: blocking
      evidenceRequired:
        - extraction-trace
        - accuracy-report
    - id: SCN-PV-INTAKE-004
      title: Triage priority agrees with reviewer judgement
      given: An adverse-event case reviewed by a qualified pharmacovigilance reviewer.
      when: The agent suggests a triage priority on the same case.
      then: Ordinal agreement with the reviewer is at least 0.85, protecting RULE-PV-002 AI action boundary.
      category: regression
      severity: warning
      evidenceRequired:
        - reviewer-label
        - agent-suggestion-log
    - id: SCN-PV-INTAKE-005
      title: Serious adverse events are not silently missed
      given: A dataset with annotated serious adverse events.
      when: The agent processes each case in the dataset.
      then: Binary recall on serious events is 1.0, protecting RULE-PV-003 human regulated decision boundary.
      category: compliance
      severity: blocking
      evidenceRequired:
        - dataset-snapshot
        - recall-report
    - id: SCN-PV-INTAKE-006
      title: Intake processing latency stays within target
      given: A representative production-shaped intake stream.
      when: The agent processes each case end-to-end.
      then: 95th percentile end-to-end latency is at most 30 seconds, protecting PRD-PV-INTAKE-001 intake processing time target.
      category: performance
      severity: warning
      evidenceRequired:
        - latency-report
        - load-profile
  convergenceCriteria:
    metric: severity-weighted-pass-rate
    passThreshold: ">= 1.0 on blocking scenarios; >= 0.95 on warning scenarios"
    stableForRuns: 2
    blockingFailureMode: any-blocking-fail-blocks-merge

Figure 8.6: Validation scenario pack SCN-PV-INTAKE-V1 (canonical v1.1.0 ScenarioPack).

Figure 8.7: From Intent to Specification.