MediFlow脈流

What enters the model is minimized by default; protected health information does not cross the agent-runtime boundary unless an explicit gate opens it.

A clinical assistant whose default is "ingest everything" cannot be safe by inspection. The shape of the agent's input contract becomes the safety property. Defaulting the other way means a reviewer can read what the prompt assembler is allowed to attach and see the redaction in the code, not in policy.

ADR-0004, the Operations Copilot ADR dated 2026-04-28, codifies the posture. The runtime exposes an ai_phi_enabled flag as the gate. Server-side prompt assembly composes the minimum-necessary input — patient identifiers reduced to surrogate IDs, free-text notes excluded by default, structured fields whitelisted rather than blacklisted. OpenAI's live web search is excluded from PHI workflows. Audit log entries record Operations Copilot actions without copying PHI into the log line.

ADR-0004 documents ai_phi_enabled as a required gate but leaves its shape — global per deployment, per organization, or per user — implementation-deferred. Until the shape lands, the gate is policy-by-convention rather than enforced-by-data. A redaction-test audit cadence (sample prompts before they reach the model, confirm no PHI surfaces) is on the work list, not in place.

The Operations Copilot proposes; a human commits. The agent has no path to a write that bypasses an explicit approval. AI proposes; humans commit.

An AI that can act without confirmation in a clinical context is the wrong primitive even when it is correct most of the time. The case that defines the product is the case where the agent was confident and wrong. The cost of one such case crossing the boundary unobserved is structurally higher than the cost of asking a clinician for a click.

The function fleet (patients-*, appointments-*, vitals-*, documents-*) is the canonical mutation boundary. Every patient or document write executes inside an Appwrite Function with declared scopes. The Operations Copilot runs as its own function — ai-operations-copilot — and emits proposals as structured payloads, not as mutations. The approval UI surfaces the proposed mutation in human-readable form with the affected fields highlighted. The user-context call to the mutation function is what actually writes. The copilot's runtime has no direct mutation path; it does not hold the credentials that would allow one.

The approval gate is a UX surface. A clinician under pressure who clicks through proposals without reading them turns the gate ceremonial. The mitigation lives in how the approval UI presents the proposed change — affected fields highlighted, the original value adjacent — not in the architectural claim. UX-side hardening to verify on a per-proposal-type basis.

AI calls run server-side only. The application code talks to a MediFlow-owned interface, not to OpenAI directly. Provider choice is a runtime detail, not an architectural commitment.

Browser-side AI calls leak credentials, fail to centralize logging, and tie the product to a single vendor's client library. A provider-neutral interface keeps the door open to swap the implementation — Anthropic, Vertex AI, an on-prem inference endpoint — without touching the application layer. In a regulated domain, the option to move providers is a compliance posture, not a fantasy.

The ai-operations-copilot Appwrite Function is the runtime. The current implementation uses OpenAI Agents SDK 0.8.5, but the application layer imports a MediFlow-owned interface — it does not import OpenAI types. The interface defines what a copilot can do; an adapter binds it to a specific vendor. Zod contracts at the boundary check what the agent receives and emits.

The case for staying on Appwrite over moving the AI surface to a separate Vercel deployment is captured in migrationplantovercel.md in the MediFlow repo. The investigation looked at whether splitting AI off would simplify the runtime; the decision against was about keeping the backend control surface — functions, auth, storage, audit — under one vendor. In a regulated context, splitting that surface across providers compounds the BAA-aware design work without adding capability.

Provider-neutral is a discipline today, not a verified property. Until a second adapter exists in the tree — even a stub one for tests — "the interface is portable" is a claim, not a verified property. The work to land a second adapter is queued.

Every mutation runs as an Appwrite Function with declared scopes. The scope declaration is the authorization model — there is no application-layer "permission check" layered above it.

Layering custom permission checks on top of a scoped backend invites drift. The application says yes, the backend says yes by default, and a missed scope declaration becomes a quiet escalation. Treating scope as the authoritative primitive forces every authz change to land in one place — the function definition itself.

scripts/deploy-appwrite-function.mjs declares the scopes per function. ADR-0003, dated 2026-03-27, documents the function-scopes decision alongside the org-context-truthfulness work that landed with it. authStore.ts now falls back to teams.listMemberships() when the embedded membership data from teams.list() is missing, preventing the auth store from silently downgrading a clinician with active permissions to readonly. The probe-type discipline (ADR-0003, decision #5) is the matching debugging rule: server-key probes and browser/user-context probes are not equivalent, and any debugging session against a function under regulated constraints must show both.

WorkspaceShell.tsx still renders hardcoded organization choices and names. ADR-0003 names this as UI debt. The fix is queued, not landed. Until it ships, the rendered org context in the shell cannot be used as evidence of the backend's view of org context — they can disagree.

Four layers, ESLint-enforced. The boundaries are load-bearing, not aspirational.

An agent-assisted codebase produces more code per week than a human-paced one. Boundaries that depend on developer judgment to maintain do not survive that throughput. Boundaries enforced by lint — boundary violations break the build — do. The cost of writing one ESLint rule is paid once; the cost of policing 503 source files by code review is paid every day.

ADR-0001 covers the architecture decision. The source tree is src/{domain,application,interface,infrastructure} with ESLint boundary rules on src/**. Approximate file counts at the snapshot: 10 domain, 85 application, 340 interface, 69 infrastructure. The composition root — the single allowed violation of the dependency direction — lives at src/infrastructure/bootstrap/. The Phase 0 through Phase 3 migration is narrated in commit subjects (the prefix is greppable in git log); the cutover commit is 225279a.

Phase 4 patient-mutation stabilization is in progress, not complete. Patient and document workflows verified green on live Appwrite as of 2026-03-31. Non-patient and non-document workflows are still being verified one vertical slice at a time. The discipline forbidding broad repo-wide rewrites during stabilization is named explicitly in the repo's context.md and is the reason this case study quotes a snapshot rather than a final state.

Most code in MediFlow is authored by Codex agents. Every pull request is reviewed and merged by a human. The Operations Copilot is one safe-AI surface inside the product; the agent-authored codebase is the other one, and it has the same posture: AI proposes; humans commit.

Agent-driven contribution scales the work, not the review. A clinical codebase needs a human signature at the merge boundary. The discipline lives in the human PR review, not in the agent's confidence at proposal time. Skipping that boundary turns agent throughput into a liability.

533 commits since 2026-01-24; latest 8d865f9. 104 PRs merged. Most feature branches are named codex/.... Merges attribute to the Mujadarah account, the human reviewer. 16 Superpowers plans under docs/superpowers/plans/, most tied to merged PRs and authored in advance of the work. Worktree parallelism via .worktrees/ enables three or more independent UI surfaces to evolve concurrently. AGENTS.md (203 KB) and CLAUDE.md (38 KB) at the repo root capture the operational discipline that bounds the agents.

The bottleneck shifts to review fidelity. 104 PRs in four months is roughly one to three merges per active day; sustained review at that cadence is the constraint that matters. Review-throughput against PR-creation rate is the metric to watch, not raw commit count. There is no automated check that catches a rubber-stamp merge; the discipline is human.