# SCRIMED Persistent Agent Workspace v1 Brief

Status: persistent-agent-workspace-v1-ready
Boundary: Persistent Agent Workspace v1 coordinates tenant-scoped synthetic work orders, saved state contracts, Trust Cards, audit timelines, reviewer checkpoints, and proof packets. It does not authorize live PHI ingestion, autonomous clinical decisions, payer submission, patient outreach, medical-record mutation, or production connector execution.

## Foundation
- Protected workspace: protected-pilot-infrastructure-configured (/pilot-workspace)
- AgentOS: synthetic-agent-platform-ready (/agents)
- TrustOS: executable-synthetic-governance-ready (/trust-os)
- Atlas: continuous-validation-operating-layer (/atlas)
- Tenant isolation: Postgres row-level security - Every workspace, session, and audit query is constrained by authenticated membership policies.
- Durable store: Supabase Postgres - Synthetic sessions and audit events persist in tenant-scoped tables; no service-role key is used by runtime APIs.
- Work-order mutation route: /api/agent-workspaces/{workspaceSlug}/work-orders
- Work-order detail route: /api/agent-workspaces/{workspaceSlug}/work-orders/{workOrderId}
- Work-order proof-packet route: /api/agent-workspaces/{workspaceSlug}/work-orders/{workOrderId}/proof-packet
- Governance ledger route: /api/agent-workspaces/{workspaceSlug}/governance-ledger
- Incident export route: /api/agent-workspaces/{workspaceSlug}/governance-ledger/incident-export
- Governance packs route: /governance-packs
- Governance packs API: /api/agent-workspace/governance-packs
- Work-order dashboard filters: state, workOrderType, assignedReviewerId, minRetryCount, governanceStatus
- Work-order states: 9
- Work-order event types: 8
- Governance action types: 4
- Incident severity levels: 5
- Governance workflow packs: 5

## Workspace Capabilities
- Tenant-scoped workspace context (active-control): Builds on protected pilot workspaces, Supabase Auth, tenant memberships, and Postgres row-level security. Gate: Customer SSO, reviewer authority, purpose-of-use, consent, and deployment-specific access review before PHI.
- Saved work-order state (active-control): Adds dedicated RLS-backed work-order and event tables with RPC-only protected mutation contracts for create, resume, transition, retry, review, and close states. Gate: Database migration, RLS verification, authenticated tenant smoke test, retention policy, and advisor review are required per environment.
- Isolated agent execution (v1-ready): Every work order is bound to a sandbox, memory scopes, tool scopes, denied actions, and human checkpoints. Gate: Live tools require scoped credentials, connector approvals, timeout/retry policy, and emergency shutdown controls.
- Model-router policy decisions (v1-ready): Work orders carry task-aware provider class, fallback, PHI sensitivity, latency, cost, and denial conditions. Gate: Provider contracts, BAA/DPA posture, regional rules, telemetry, budget limits, and rollback tests.
- Human approval checkpoints (active-control): Reviewer roles and dispositions are explicit before outputs can move from synthetic proof to buyer-facing evidence. Gate: Licensed clinical, RCM, research, legal, or security reviewer authority must be approved per workflow.
- Downloadable proof packets (active-control): Workspace proof packets combine work-order plan, Trust Cards, reviewer checkpoints, audit timeline, blocked actions, limitations register, and explicit legal/privacy/security/safety boundaries. Gate: Production packets need customer branding, legal disclaimers, evidence retention policy, confidentiality controls, and legal/privacy/security review.
- Server-audited retention, legal hold, and incident export ledger (active-control): Adds an append-only tenant governance ledger for retention policies, legal holds, legal releases, and write-before-release incident exports with RLS visibility and AAL2 mutations. Gate: Customer counsel, privacy owner, incident commander, retention schedule, DPA/BAA path, and customer-specific legal hold workflow must be approved before live regulated data.
- Customer-specific governance workflow packs (active-control): Provides reusable retention, legal-review, legal-hold, incident-export, and blocked-claims workflow packs by buyer archetype for protected enterprise pilots. Gate: Each customer pack still requires buyer-specific legal, privacy, security, workflow-owner, and reviewer authority approval before production use.

## Work Orders
- RCM denial appeal generation (v1-ready): Draft a reviewable denial appeal outline from synthetic claim context, payer policy evidence, missing documentation, and reviewer disposition. Blocked actions: final coding, payer submission, reimbursement guarantee, coverage determination.
- Clinical trial matching (v1-ready): Create a reviewable eligibility work order with criteria trace, exclusion flags, missing evidence, and research-review queue. Blocked actions: patient outreach, enrollment recommendation, treatment recommendation, live record ingestion.
- Pre-visit chart review (production-gated): Prepare a synthetic chart-review work order with risk signals, missing data, agenda prompts, and clinician review boundary. Blocked actions: diagnosis, treatment recommendation, patient instruction, medical-record mutation.
- Post-visit care plan drafting (production-gated): Draft review-only follow-up and care-plan support from synthetic context while preserving clinician authorship. Blocked actions: order entry, patient outreach, final care plan, clinical advice without clinician review.
- Investor outreach tracking (v1-ready): Track investor outreach tasks, diligence artifacts, follow-up state, proof surfaces, and non-confidential messaging boundaries. Blocked actions: financial misrepresentation, unsupported medical claims, PHI disclosure, confidential buyer disclosure.
- Security scan (quality-process-replacement): Create a repeatable security-review work order that tracks headers, dependency posture, route boundaries, logs, and evidence gaps. Blocked actions: secrets capture, credential rotation without owner, claiming SOC 2/HIPAA certification, destructive remediation.
- Data transformation job (production-gated): Plan synthetic transformations across forms, tables, referrals, claims, FHIR resources, HL7 messages, and evidence packets. Blocked actions: production data movement, PHI export, record mutation, connector certification claim.

## Reviewer Checkpoints
- Clinical review: Any chart, care-plan, documentation, risk, education, or patient-facing draft. Reviewer: Licensed clinician or approved delegated clinical reviewer. Denial: Keeps the work order held and records evidence gap, unsafe claim, or review reason.
- Payer or RCM review: Prior authorization, claims, denial appeal, coding, and reimbursement-adjacent work. Reviewer: Qualified RCM, payer operations, or coding reviewer. Denial: Blocks submission-like actions and records missing policy or documentation evidence.
- Research review: Trial matching, protocol screening, cohort review, and research operations. Reviewer: Research operations reviewer, investigator delegate, or clinical research lead. Denial: Blocks outreach, enrollment language, and unsupported eligibility claims.
- Security and privacy review: Workspace persistence, data transformation, model routing, connector use, and protected data handling. Reviewer: Security, privacy, legal, or compliance owner. Denial: Blocks production data movement and records remediation tasks.
- Executive sponsor review: Commercial, investor, partnership, or enterprise expansion decisions. Reviewer: Founder, executive sponsor, or authorized business owner. Denial: Blocks public or buyer-facing release until claims and scope are corrected.

## Customer-Specific Governance Workflow Packs
Boundary: SCRIMED governance workflow packs are customer-tailored synthetic pilot operating templates. They are not legal advice, privacy advice, security certification, HIPAA certification, SOC 2 certification, FDA clearance, payer approval, reimbursement assurance, breach determination, or production authorization.
- Provider Operations Retention Review Pack (pilot-ready): Retention schedule, reviewer authority, proof packet handling, and release controls for synthetic care operations work orders. Customer inputs: Pilot sponsor, Workflow owner, Record retention preference, Clinical reviewer role, Privacy contact, Security contact.
- Payer And RCM Incident Export Pack (pilot-ready): Controls for denial-risk work orders, retention of policy evidence, incident export, and no-submission boundaries. Customer inputs: RCM owner, Payer operations owner, Policy source owner, No-submission acknowledgement, Revenue metric baseline.
- TrialCore Research Legal Hold Pack (customer-tailoring-required): Research-review controls for eligibility evidence, legal hold, protocol-source retention, and no-outreach boundaries. Customer inputs: Research operations owner, Protocol source owner, IRB or governance contact where applicable, Research reviewer role, Protocol-version handling rule.
- Public Sector Sovereign Retention Pack (external-review-required): Sovereign deployment readiness, retention controls, incident export, and jurisdiction-specific approval gates. Customer inputs: Jurisdiction, Data residency requirement, Public-sector sponsor, Procurement route, Incident commander, Regional counsel.
- Enterprise BAA/DPA Readiness Pack (customer-tailoring-required): Contract-readiness controls for BAA/DPA path, retention schedule, legal review, incident export, and human-review operating model. Customer inputs: Procurement owner, Privacy owner, Security owner, Legal owner, Workflow sponsor, Reviewer authority matrix.

## Authenticated Governance Smoke CI Contract
- Secret: SCRIMED_BEARER_TOKEN
- Optional base URL variable: SCRIMED_BASE_URL
- Optional workspace slug variable: SCRIMED_WORKSPACE_SLUG
- Required authenticated flag: SCRIMED_REQUIRE_AUTHENTICATED_SMOKE=1

## Known Limitations Resolution
No known limitation is left vague: each is either controlled by an active boundary, replaced with a safer synthetic quality process, or marked as an external approval gate that cannot be honestly resolved in code alone.
- Live PHI ingestion is not enabled. Status: quality-process-replacement. Replacement: Use synthetic fixtures, no-PHI buyer intake, protected pilot sessions, TrustOS decisions, and metadata-only evidence packets. Remaining gate: BAA/DPA, privacy notice, consent, retention, security review, and customer authorization.
- Autonomous clinical decisions remain prohibited. Status: active-control. Replacement: Every clinical-adjacent work order is held behind TrustQA, Clinical Guardian, reviewer checkpoints, blocked actions, and proof packet boundaries. Remaining gate: Licensed clinician validation and regulatory intended-use review before clinical decision-support claims.
- Clinical correctness and safety scores are not externally validated. Status: external-approval-required. Replacement: Expose completeness, source attribution, evidence trail, confidence, reviewer status, and audit fields while marking clinical scoring as clinician-validation required. Remaining gate: Clinician rubric, validation study, data-quality review, and governance sign-off.
- Dedicated long-running work-order persistence requires per-environment migration verification. Status: active-control. Replacement: Use dedicated agent workspace work-order tables, append-only work-order events, explicit authenticated grants, and RPC-only mutations with route-level AAL2 and rate-limit checks. Remaining gate: Apply migration, verify RLS with an authenticated tenant, run database advisors, and approve customer-specific retention/legal-hold policy.
- Production model routing across vendors is not active. Status: quality-process-replacement. Replacement: Attach provider-class, fallback, PHI sensitivity, denial conditions, and human escalation to every work-order template. Remaining gate: Vendor contracts, BAA/DPA path, regional rules, telemetry, cost limits, and rollback tests.
- Live EHR, payer, imaging, and device connectors remain blocked. Status: active-control. Replacement: Use interoperability standards registry, synthetic conformance kits, fixture validation, and connector-readiness gates. Remaining gate: Customer connector approval, security review, consent, audit, monitoring, and partner acceptance.
- Sovereign deployment is not implemented. Status: external-approval-required. Replacement: Define managed cloud, private cloud, hospital-controlled, government/sovereign, and edge/on-prem profiles with required controls. Remaining gate: Customer architecture review, regional compliance mapping, private networking, and local audit design.
- Legal, HIPAA, SOC 2, regulatory, and reimbursement claims require external review. Status: external-approval-required. Replacement: Keep claims register, Trust Center, diligence brief, prohibited-claims controls, and buyer-facing boundary language active. Remaining gate: Qualified counsel, security assessor, privacy owner, regulatory reviewer, and payer/reimbursement expert review.

## API Contracts
- GET /agent-workspace (v1-ready): Inspect Persistent Agent Workspace v1 work orders, state machine, limitations resolution, and proof routes.
- GET /api/agent-workspace (v1-ready): Return the typed workspace summary for investor, buyer, and internal product diligence.
- GET /api/agent-workspace/brief (v1-ready): Download the workspace architecture and limitation-resolution brief.
- GET /api/agent-workspace/proof-packet (v1-ready): Download a preview proof packet for a deterministic synthetic Persistent Agent Workspace.
- GET / POST /api/pilot-workspaces/{workspaceSlug}/sessions (active-control): Persist synthetic evaluation sessions that can anchor workspace work-order evidence.
- GET / POST /api/pilot-workspaces/{workspaceSlug}/trustos-decisions (active-control): Commit TrustOS decisions and model-route governance evidence to the tenant ledger.
- GET / POST /api/agent-workspaces/{workspaceSlug}/work-orders (active-control): List, filter, summarize, and create persistent synthetic work orders through dedicated RLS-backed tables and RPC-only mutations.
- GET / PATCH /api/agent-workspaces/{workspaceSlug}/work-orders/{workOrderId} (active-control): Inspect a work order with its event trail or transition state for review, retry, assignment, proof readiness, blocking, or closure.
- GET /api/agent-workspaces/{workspaceSlug}/work-orders/{workOrderId}/proof-packet (active-control): Download an audited Markdown proof packet for one persistent synthetic work order with Trust Card, event trail, reviewer checkpoints, blocked actions, and safety boundaries.
- GET / POST /api/agent-workspaces/{workspaceSlug}/governance-ledger (active-control): List and record append-only retention, legal-hold, legal-release, and incident-export governance evidence for a protected pilot workspace.
- POST /api/agent-workspaces/{workspaceSlug}/governance-ledger/incident-export (active-control): Download a server-audited incident export packet only after the governance-ledger incident-export event is committed.
- GET /api/agent-workspace/governance-packs (active-control): Return customer-tailorable governance workflow packs for retention, legal review, legal hold, incident export, evidence artifacts, and blocked claims.
- GET /api/agent-workspace/governance-packs/brief (active-control): Download a Markdown brief describing the governance workflow packs and authenticated smoke CI secret contract.

## Next Implementation Step
Promote selected governance pack slugs from routed buyer intake into protected workspace activation metadata, then make authenticated governance-ledger smoke required once the approved AAL2 tenant secret is stored in GitHub Actions.