Capstone 9 — Behavioral Health UM Modernization

Project Brief

A health plan has spent thirty years contracting its behavioral health out to a separate company. That company — Bridgeway Behavioral Health — had its own provider network, its own clinical criteria, its own claims platform and, crucially, its own member identifiers. The plan has now in-sourced the whole thing.

Medical prior authorization already runs on a modern distributed platform: an Nx monorepo, an Angular client, a NestJS intake service, a Spring Boot case service, Kafka, Camunda BPMN and DMN, Flyway migrations, a transactional outboxWrite the entity and an outbox row in one local transaction; a separate worker publishes the row and marks it published. Makes persist-and-publish atomic within ONE service -- it does not make two services' writes atomic with each other.. Behavioral health runs on BHAuthTrack 4.2 — one WAR on Tomcat 8, Java 8, Spring MVC 4.3, JSP, Oracle 11g. Deployed 2011. Last schema change March 2016. The original author left the following month.

Your job is to build the agent that moves the second onto the first.

What you are actually delivering

Not a repository. A repository and a gap register: every capability in the target platform classified against the arriving domain, with the evidence for the verdict.

The agent topology

A coordinator and eight specialists. The coordinator has no file tools, deliberately: every read happens inside a subagent with its own context window, so the archaeologist's fifty-four files do not crowd out the rules extraction that follows.

The run ships in two gated phases. 9A is backend and workflow, 10–12 hours. 9B is the frontend, 4–6 hours, and it does not start until 9A is green — because the screen inventory is its input, and a client cannot supply an enforcement the backend does not have.

Prerequisites

This capstone assumes the whole agent track. It is the only one that uses .claude/skills/, so that part is taught here from scratch — everything else below is assumed knowledge, not revision.

Tooling. Python 3.10+ and an Anthropic API key. Node 18+ only for phase 9B. Docker is optional and only for the deployment section — every test and eval in this lab runs offline without it.

Why Behavioral Health Is Not Clinical With Different Codes

Four differences, and each one breaks an assumption the medical platform is built on. If you take nothing else from this capstone, take these.

1. The criteria are a ladder, not a yes/no

Medical prior auth asks: is this procedure medically necessary for this diagnosis? One question, one answer.

Behavioral health asks: at what intensity of care should this person be treated right now? The answer is a rung on the ASAMAmerican Society of Addiction Medicine. Its criteria place a person at one of several levels of care, from outpatient through medically managed inpatient, using six independently scored dimensions. ladder — 1.0 outpatient through 4.0 medically managed intensive inpatient — chosen from six independently scored dimensions.

So an engine that can only approve or deny the level that was requested is missing the domain. It has to be able to grant a different level than the one asked for, in either direction, and say why.

2. Authorization is a series, not an event

A medical case is decided once. A behavioral-health case is decided, and then reviewed again on a cadence set by the level of care, until the member is discharged or steps down. This is concurrent reviewThe recurring continued-stay review that runs for the life of an authorization. Every three days at ASAM 4.0, every seven at 3.5, every fourteen at partial hospitalization..

Three consequences for any system design:

• An approval is not terminal. It must schedule its own next review.
• A next-review date is a regulatory deadline, not a reminder. A residential authorization not re-reviewed inside its interval is out of compliance, whether or not anyone was told.
• The process model needs a timer-driven loop. A workflow that terminates after the first decision cannot express the domain at all.

Note also that the cadence follows the level, not the units approved. A fourteen-day approval at ASAM 3.5 still comes back for review in seven days. Systems get this wrong by deriving the next review from the authorization's end date, which is a reasonable-looking mistake that quietly halves the number of reviews.

3. Two privacy regimes, not one

HIPAA covers everything. 42 CFR Part 2The federal rule protecting records from federally assisted substance-use-disorder treatment programs. Disclosure requires a consent that NAMES the recipient, states a purpose and scope, and expires. additionally covers records from federally assisted substance-use-disorder treatment programs, and it is much stricter.

The practical summary: under HIPAA the question is "is this use appropriate?". Under Part 2 it is "is this exact recipient named in an unexpired, unrevoked consent that covers this purpose and this scope?" — a question a system can only answer if it stores consents that way and checks them at the point of disclosure.

A system can be fully HIPAA-compliant and violate Part 2 on every request. That is the usual failure, and it is almost always plumbing rather than policy. You will build it, watch it happen, and then fix it.

4. Parity is a design constraint

MHPAEAThe Mental Health Parity and Addiction Equity Act. A limitation applied to behavioral-health benefits may be no more restrictive than the comparable limitation on medical/surgical benefits — both as written and as applied. requires that a limitation applied to behavioral health be no more restrictive than the comparable limitation on medical/surgical care. The hard ones are non-quantitative treatment limitationsNQTLs. Process-level limits — review frequency, step therapy, criteria strictness, network standards — that parity puts in scope alongside numeric caps. A BH-only limitation with no med/surg analogue is an exposure.: review frequency, step-therapy requirements, criteria strictness, network standards.

You will find these in the legacy code as rules that look entirely reasonable in isolation. When you do, neither port them silently nor drop them silently. Porting carries the exposure forward; dropping changes outcomes for real members. Escalate.

The Donor, and Its Holes

The modern platform describes itself, in its own README, as a "clean-room learning rebuild." That is an honest description and you should take it seriously. It is deliberately thin, and the thinness is invisible until you point a new domain at it.

Here is what the architecture-cartographer subagent finds when it opens the files rather than the documentation:

The one trait worth copying wholesale

Capability layering behind feature flags: EVENTS_ENABLED, OUTBOX_ENABLED, WORKFLOW_ENABLED, CACHE_ENABLED, SEARCH_ENABLED, REPLICA_ENABLED, SECURITY_ENABLED. Seven flags, each gating one capability, so the stack stays runnable with any subset enabled. It is the platform's best structural idea.

Mirror the idiom. But classify each flag before you do, and the test is one question:

The Monolith: A Guided Tour of BHAuthTrack 4.2

Fifty-four files. Java 8, Spring MVC 4.3, JSP/JSTL, one WAR on Tomcat 8, Oracle 11g, Quartz, Log4j 1.x. Read five of them, in this order, and you will have met everything that makes this hard.

1. db/schema_changes.txt — read this before the schema

There is no migration tool. DDL is applied by hand in each environment by whoever is doing the release, and this file is the only record of what was applied and when. It says so itself:

Where this file and 01_schema.sql disagree, THIS FILE IS CLOSER TO PRODUCTION.

It records two production drifts, one prod hotfix never back-ported, and — the important one — BHA-1180, the carve-out identifier problem. It also names two tables the application reads that no release ever created, both owned by other teams, both load-bearing inputs to a clinical decision. An inventory built from the schema file alone misses both.

2. db/03_PKG_LOC_RULES.sql — the level-of-care engine

Not a rule set. A stateful first-match ladder: it accumulates into v_score across branches, and returns at the first branch that commits. Several branches fall through deliberately. The order is load-bearing.

-- BRANCH 7 -- THE OVERLAP. Read carefully.
--
-- Both of the next two conditions can be true at once. A case with
-- v_score = 10 and v_d1 = 3 -- reached by C-SSRSColumbia Suicide Severity Rating Scale, 0-5. Scores of 4 and 5 are active ideation with intent -- a threshold, not a gradient. 4 (+6) and dimension 1
-- of 3 (+4) -- satisfies the 3.7 test AND would satisfy the 3.5 test
-- below it. Because this is a first-commit ladder, it lands on 3.7 --
-- the MORE intensive level -- and the 3.5 branch never runs.
--
-- Flatten these into an unordered decision table and the answer depends
-- entirely on the hit policy you pick.
IF v_score >= 10 AND v_d1 >= 3 THEN
    r.granted_loc := '3.7'; ... RETURN r;
END IF;

IF v_score >= 8 THEN
    r.granted_loc := '3.5'; ... RETURN r;
END IF;

There is a second engine. LocRulesService.java layers three more adjustments in Java after the PL/SQL has already committed to an outcome — so it can only downgrade or pend, never upgrade. Neither layer alone is the rule set. Convert one and three of the twelve golden cases come back wrong, plausibly.

3. service/AuthCaseService.java — the transaction

submitAndDecide() is @Transactional and performs five writes: the authorization, the assessments, the Part 2 consent, the initial level-of-care review, and an outbound queue row. One Oracle transaction. All of them or none.

The class comment explains why, and it is a requirement rather than an accident:

This started in 2011 as three separate services. They were merged in 2013 because the transaction boundaries kept producing orphaned consent rows when the JTA config drifted between environments.

An authorization from a Part 2 program that exists without its consent record is protected content held with no record of who the member agreed it could be shared with. Under this design that state is unrepresentable. Any redesign has to say what makes it unrepresentable instead.

The same method also logs the clinical narrative, on purpose, so the appeals team can reconstruct a challenged determination. That log rolls to a file that is backed up nightly to the share the reporting team reads from. On this system that is one sink.

4. service/AuthStatusService.java — the workflow that is not one

There is no process engine. There is a STATUS column and a switch, and reading that switch is how you recover the process model. The thing to notice:

case "APPROVED":
    // Continued stay. An approved authorization is not finished; it comes
    // back around on its cadence. This is the single biggest structural
    // difference from medical prior auth, and it is expressed here as a
    // status that loops.
    auth.setStatus("IN_REVIEW");
    break;

It also branches on LEGACY_OVERRIDE, which is where this capstone puts its deliberate dead end. More on that below.

5. webapp/WEB-INF/jsp/decision.jsp — rules in a template

Three business rules and two derived values, implemented in a view. The file's own maintenance note says:

The role checks below are the ONLY thing standing between a nurse reviewer and the deny button on most deployments. AuthCaseService.issueDenial() re-checks, but that was added after the fact and there are two other call paths that do not go through it. Treat this file as security-relevant.

And, further down, two scriptlets computing the continued-stay countdown and the regulatory turnaround clock — the only implementation of either rule in the codebase. Reporting reimplemented both in Crystal and the two have disagreed since 2015.

Domain Glossary

Read this once before the build guide. Every term appears in the fixtures.

The Vocabularies Collide, and One Collision Is Silent

Both systems model utilization management. Neither was written with the other in mind, so the vocabulary diverged — in two ways, and they carry opposite risks.

Four of five statuses do not mean what they look like

The two enums overlap on five names. Read them side by side:

Making the unexamined pair impossible to record

So TermMapping.same_semantics has no default. You cannot construct a mapping without answering the question:

# solution/term_map.py
@dataclass
class TermMapping:
    kind: str
    clinical: str
    behavioral: str
    #: REQUIRED, NO DEFAULT. The whole point of this module.
    #:
    #: A name-identical pair recorded without answering this is the failure
    #: mode the map exists to prevent, so it cannot be recorded at all.
    same_semantics: bool
    evidence: str
    divergence: str = ""    # required when same_semantics is False
    action: str = ""        # required when same_semantics is False

    @property
    def silent_trap(self) -> bool:
        # Same name, different meaning. The dangerous quadrant.
        return self.name_identical and not self.same_semantics

// solution/term-map.ts
interface TermMapping {
  kind: TermKind;
  clinical: string;
  behavioral: string;
  /**
   * REQUIRED, NO OPTIONAL MARKER. The whole point of this module.
   *
   * A name-identical pair recorded without answering this is the failure
   * mode the map exists to prevent, so it cannot be recorded at all.
   */
  sameSemantics: boolean;
  evidence: string;
  divergence?: string;   // required when sameSemantics is false
  action?: string;       // required when sameSemantics is false
}

/** Same name, different meaning. The dangerous quadrant. */
function silentTrap(m: TermMapping): boolean {
  return m.clinical.trim().toLowerCase() === m.behavioral.trim().toLowerCase()
      && !m.sameSemantics;
}

And a divergence must state what the port has to do about it. A divergence with no action is a note, and notes do not survive a refactor.

Note also that name_identical compares case-insensitively. member_id and MEMBER_ID are the same name in two conventions, and a comparison that missed that would let the most dangerous pair in the schema through as a harmless rename — one identifier on the clinical side, two on the behavioral side, with 31% of the second one null.

The rows with no counterpart

Usually the most interesting entries, because each names a capability the target platform has never needed:

And one missing from both: APPEALED. The platform team's backlog lists an appeals path as planned-and-unbuilt; the legacy system handles appeals entirely outside itself, in a shared mailbox and a spreadsheet. Neither side has it and both need it — a finding the gap analysis only reaches by reading the other team's backlog.

Animation 1: One WAR Becomes Three Deployables, and a Transaction Is Severed

The seam mapThe record of where a monolith is cut, which transactional units each cut crosses, and what replaces the atomicity the cut breaks. is where a modernization is won or lost. Watch what happens to submitAndDecide() — five writes, one Oracle transaction — as the monolith is cut apart.

Classify the pairs before you draw the seam

The usual failure is deciding in advance that everything decomposes, then finding a mechanism for each pair. Do it the other way round. Not every pair in one transaction needs the same guarantee:

In this system, writes 1 and 3 — the authorization and its Part 2 consent — are class one. So bh-case-svc owns both, and the seam moves.

What replaces the atomicity you do break

For every seam you do cut, five fields. All required, and the data structure enforces it:

# solution/seam_map.py
sm.add_seam(Seam(
    name="case | notification",
    left="bh-case-svc", right="bh-notify-svc",
    crosses=["AuthCaseService.submitAndDecide"],
    coupling=EVENTUAL_GUARANTEED,
    replacement=AtomicityReplacement(
        mechanism="transactional outbox in bh-case-svc + idempotent consumer "
                  "keyed on (auth_id, review_seq)",
        window="under 60s at the configured relay interval; the legacy cron "
               "polled every 5 minutes, so this is tighter than what it replaces",
        observable="SELECT count(*) FROM outbox_event WHERE published_at IS NULL "
                   "AND created_at < now() - interval '5 minutes'",
        compensation="relay retries with backoff; rows past 3 attempts move to a "
                     "human queue, because the legacy FAILED state was where rows "
                     "went to be forgotten",
        alarm="that count > 0 for 5 consecutive minutes pages the on-call")))

// solution/seam-map.ts
sm.addSeam({
  name: 'case | notification',
  left: 'bh-case-svc', right: 'bh-notify-svc',
  crosses: ['AuthCaseService.submitAndDecide'],
  coupling: Coupling.EventualGuaranteed,
  replacement: {
    mechanism: 'transactional outbox in bh-case-svc + idempotent consumer ' +
               'keyed on (authId, reviewSeq)',
    window: 'under 60s at the configured relay interval; the legacy cron ' +
            'polled every 5 minutes, so this is tighter than what it replaces',
    observable: `SELECT count(*) FROM outbox_event WHERE published_at IS NULL
                   AND created_at < now() - interval '5 minutes'`,
    compensation: 'relay retries with backoff; rows past 3 attempts move to a ' +
                  'human queue, because the legacy FAILED state was where rows ' +
                  'went to be forgotten',
    alarm: 'that count > 0 for 5 consecutive minutes pages the on-call',
  },
});

// All five fields are required by the type, not by a convention. An eventual
// consistency with no observable and no alarm is the same as no guarantee,
// implemented with more moving parts.
interface AtomicityReplacement {
  mechanism: string;
  window: string;
  observable: string;
  compensation: string;
  alarm: string;
}

An eventual consistency with no observable and no alarm is the same as no guarantee, implemented with more moving parts. That is why AtomicityReplacement.problems() returns a finding for every missing field, and why Seam.validate() raises rather than warning.

Animation 2: Fifteen Capabilities Resolve Into Four Verdicts

This is the deliverable. Watch the distribution, and notice how uncomfortable it is.

Naming the harm

must-not-port is the verdict people soften, and softening it is how a defect gets copied with a note attached. So the tool refuses it:

# solution/gap_register.py
if self.verdict == MUST_NOT_PORT and not self.harm.strip():
    raise RegisterError(
        f"{self.capability!r}: must-not-port requires a NAMED HARM. "
        f"If you cannot name what goes wrong and for whom, the verdict "
        f"is 'extend'.")

// solution/gap-register.ts
if (entry.verdict === Verdict.MustNotPort && !entry.harm?.trim()) {
  throw new RegisterError(
    `${entry.capability}: must-not-port requires a NAMED HARM. ` +
    `If you cannot name what goes wrong and for whom, the verdict is 'extend'.`);
}

// Note that this is a THROW, not a warning. A register that accepts a
// must-not-port with no harm is a register whose most important verdict
// means nothing -- and softening that verdict is exactly how a defect gets
// copied forward with a note attached.

Not "logging member identifiers is not ideal", but:

This content is 42 CFR Part 2 protected. The monolith had ONE log sink; decomposition multiplies it into one per service plus a broker plus an index. Copying the idiom produces unlawful disclosure at several sinks instead of one — and nobody decided to make it worse: fan-out is simply what the architecture does with a field.

Animation 3: One Case, Two Engines, Two Answers

Golden case 500001. C-SSRS of 4 contributes +6; ASAM dimension 1 of 3 contributes +4. Score reaches 10, dimension 1 is 3, and both branch-7 conditions are true.

There is no neutral choice

The reference answer, and what it costs

UNIQUE, with every lower row tightened by the negation of the rows above it. The exclusions were always there — they were encoded as position. Now they are encoded as conditions, the table means the same thing whatever order the rows are in, and a future edit that reintroduces an overlap errors loudly instead of silently returning whichever row sits higher.

It costs something, and the cost is instructive. A decision-table cell constrains exactly one input, so this condition cannot be written as a cell at all:

score >= 8 and not (score >= 10 and dim1 >= 3)
#                    ^^^^^ two inputs, one exclusion -- not expressible as a cell

The honest fix is a named derived input, overlap_upper, and the row tests overlap_upper < 1. That is better than a workaround: naming the overlap puts it on the face of the table a clinician reads, instead of leaving it implied by which row sits higher.

dmn_writer.to_feel() raises rather than guessing at a cell it cannot express honestly. A guessed cell is a wrong clinical rule that looks finished.

Animation 4: The Narrative Clears HIPAA, Then Fans Out

The clinical narrative passes every check the medical platform makes. Watch where it goes.

The consent scope nobody checks

A Part 2 consent states a scope. The common one is AUTH_DECISION_ONLY: the determination may be disclosed and the narrative may not. A notification payload carrying both is a violation under the most common consent on file.

So the emitted event is built from the consent scope, not from the entity:

// libs/events/envelope.ts
//
// The decision event. Carries the determination and NOT the justification:
// the common consent scope is AUTH_DECISION_ONLY, which permits one and not
// the other. Building the payload from the consent scope rather than from
// the entity is the whole difference.
export interface BhDecisioned {
  authId: number;
  planMemberId: string | null;
  outcome: 'APPROVED' | 'PENDED' | 'DENIED';
  grantedLoc: string | null;
  reasonCode: string | null;
  nextReviewDue: string | null;
}

The scan checklist

validation.check_protected_content_leak() walks every emitted file. Two things it had to learn the hard way, both of which are in the lab's tests:

• An audit table's narrative column spans lines. CREATE TABLE bh_audit_event and old_narrative TEXT are on different lines, so a line-by-line scan misses the single sink that accumulates one protected copy per update, with no consent scope and no expiry.
• A comment naming the field is not a leak. Warning the next developer not to log the narrative is exactly what you want a developer to do; flagging it teaches them to stop.

Animation 5: Two Planes — Knowledge and Control

The design decision this capstone exists to teach. Watch which layer each concern lands in.

The rule of thumb, and it decides every case you will meet:

Animation 6: A Role Guard Lifts Out of a Template

Phase 9B. Three nested JSTL conditionals in decision.jsp are the reviewer-licensure rule. Watch where each piece has to land.

A guard is not the enforcement

A route guard stops a reviewer reaching a screen they cannot act on. That is a real improvement to the experience and it is not a control, because anyone can call the API directly.

So route_writer.preflight() refuses twice: once when an action gate is proposed for a route guard alone, and again when phase 9A supplied no server-side check for a rule that needs one. The client cannot supply an enforcement the backend does not have — reporting that is correct; guarding around it and calling the rule migrated is not.

Field visibility is a server concern

The legacy controller loads the clinical narrative unconditionally and the template hides it with <c:if test="${sessionScope.roleMask ge 2}">. The guard controls rendering, not retrieval — the content is in the response body either way, one developer-tools panel from view.

The fix is that the endpoint does not return the field. Which is why that rule's proposed home is API_OMISSION and the emitted component has no visibility conditional at all: there is nothing to hide.

The screen inventory finds twenty rules across seven screens, eleven of which have no server-side enforcement at all. Those eleven are the ones that vanish in a mechanical port, and each needs a gap-register entry as well as a route.

Skill, Subagent, or Slash Command?

This capstone is the first in the course to use .claude/skills/, so the boundary deserves stating plainly. All three are markdown files in .claude/. They are not interchangeable.

Why the domain is a Skill and not eight prompts

Six of the eight subagents need the ASAM ladder, the Part 2 rules and the code sets. There are two ways to give it to them.

Paste it into six system prompts, and: it drifts the moment one is edited; it costs tokens on every turn of every subagent whether or not that turn needs it; and there is no single place to correct it when the clinical policy changes.

Or write it once as .claude/skills/behavioral-health-um/, with the entry point short and four bundled references that stay out of context until something needs them:

---
name: behavioral-health-um
description: Behavioral-health utilization management domain knowledge -- ASAM
  levels and the six dimensions, LOCUS/CALOCUS, concurrent review cadence,
  42 CFR Part 2, MHPAEA parity, BH code sets, and the reviewer-licensure rule.
  Load this before reading, classifying, or generating anything in a
  behavioral-health prior-authorization system.
---

| Reference | Load it when |
|---|---|
| `references/asam-levels.md` | Classifying a level of care, or writing a decision table |
| `references/part2-redisclosure.md` | Anything touching consent, disclosure, logging, eventing, search |
| `references/bh-code-sets.md` | Validating or emitting a service, diagnosis or instrument code |
| `references/parity-nqtl.md` | A rule applies to BH that may have no med/surg analogue |

`scripts/validate_bh_codes.py` checks a code against the sets in the third
reference. Run it rather than reasoning about whether `H0018` is real.

That table is the mechanism. The entry point is a router; the bulk arrives only when needed.

Recipes are Skills too

Two of the four Skills in this lab are not knowledge at all — they are runbooks: rules-to-dmn and decompose-transaction. Same steps every time, run once per rules block and once per transactional method. Each bundles a script, because a bundled script is a thing that gets run rather than a procedure that gets recalled:

python .claude/skills/rules-to-dmn/scripts/dmn_overlap.py \
    --ir artifacts/rules_ir.json --report artifacts/overlap.md

That checker enumerates every pair of committing rows and reports pairs that can both match, with a concrete witness. Do not reason about overlap by inspection — the pairs that matter are the ones whose conditions are on different variables and therefore look disjoint. And when it cannot model a condition it raises rather than reporting no overlap: a false clean is the one answer that checker must never give.

No PHI in Prompts, Ever

Taken verbatim from the platform organisation's own AI ground rules, and elevated here to a first-class constraint rather than a footnote — because this agent reads a system whose most valuable content is substance-use-disorder clinical narrative.

The question the lab is really teaching: how do you point an agent at a regulated codebase without feeding it regulated data?

Three layers

Shape detection, and its limit

# solution/hooks.py
#
# THE LIMIT OF THIS APPROACH, STATED PLAINLY: shape detection is defence in
# depth, not a proof. A narrative written without any of these words will
# pass, and no regex closes that gap. The control that actually holds is that
# every fixture in this lab is SYNTHETIC.
_CLINICAL_REGISTER = re.compile(
    r"\b(member|patient|client|individual|resident|he|she|they)\b.{0,100}\b("
    r"present(s|ed|ing)?|report(s|ed|ing)?|ideation|withdrawal|relapse|"
    r"treatment|therapy|counsel(ling|ing)?|episode|referral|admission|"
    r"engagement|symptom|dose|medication|prescrib|diagnos"
    r")\b", re.I | re.S)

# Several sentences of prose, not code and not a column list.
#
# The trailing \s* rather than \s+ matters. With \s+ the LAST sentence of a
# narrative goes unmatched -- there is no whitespace after its full stop --
# so redaction leaves one clinical sentence standing. That was a real leak,
# found by running the gate over the seed fixture rather than over a mock.
_PROSE = re.compile(r"(?:[A-Z][^.!?\n]{25,}[.!?]\s*){2,}")

// solution/hooks.ts
//
// THE LIMIT OF THIS APPROACH, STATED PLAINLY: shape detection is defence in
// depth, not a proof. A narrative written without any of these words will
// pass, and no regex closes that gap. The control that actually holds is that
// every fixture in this lab is SYNTHETIC.
const CLINICAL_REGISTER =
  /\b(member|patient|client|individual|resident|he|she|they)\b[\s\S]{0,100}\b(present(s|ed|ing)?|report(s|ed|ing)?|ideation|withdrawal|relapse|treatment|therapy|counsel(ling|ing)?|episode|referral|admission|engagement|symptom|dose|medication|prescrib|diagnos)\b/i;

// Several sentences of prose, not code and not a column list.
//
// The trailing \s* rather than \s+ matters. With \s+ the LAST sentence of a
// narrative goes unmatched -- there is no whitespace after its full stop --
// so redaction leaves one clinical sentence standing. That was a real leak,
// found by running the gate over the seed fixture rather than over a mock.
const PROSE = /(?:[A-Z][^.!?\n]{25,}[.!?]\s*){2,}/;

tests/test_no_phi_in_prompt.py plants a realistic narrative and asserts the gate fires; it also walks every non-allowlisted file in the legacy tree and asserts that none of them would reach the model carrying narrative-shaped content. That is the one check in this capstone that must report zero.

Environment Setup

No database, no broker, no cloud account. This agent reads a repository and writes a repository, and everything under tests/ runs without an API key.

Windows, macOS and Linux all work; there is no WSL requirement. The only platform-specific line is the venv activation path, shown below. Nothing here needs a paid subscription beyond an Anthropic API key, and the tests do not need even that.

cd labs/capstone-9-bh-um-modernization

python -m venv .venv
. .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install -r requirements.txt

cp solution/.env.example solution/.env    # add your ANTHROPIC_API_KEY

# The vendored donor ships without node_modules, and Angular was never
# installed in the upstream checkout either -- no @angular packages, no `ng`
# binary. Required before anything in phase 9B will build.
cd reference-umlite && npm install && cd ..

# Everything here runs offline.
pytest tests/ -v
python solution/evaluation/test_suite.py --self-check

BH_SOLUTION_DIR=starter pytest tests/ -q

bhauthtrack/ needs no build. It is read, never run — there is no Oracle instance in this lab and no Tomcat. The SQL is a specification, not a database.

File Structure

Two trees you read, one you write, and the agent that does it.

labs/capstone-9-bh-um-modernization/
├── bhauthtrack/                 # DOMAIN DONOR. Read-only, enforced in code.
│   ├── db/                      #   schema, the golden set, PKG_LOC_RULES, the drift log
│   └── src/main/                #   controller service dao domain batch security ws + 9 JSPs
├── reference-umlite/            # ARCHITECTURE DONOR. Read-only, enforced in code.
│   ├── camunda/                 #   prior-auth.bpmn, pa-decision.dmn
│   ├── BACKLOG.md               #   the platform team's own planned-and-unbuilt list
│   └── VENDORED.md              #   what the donor does and does not have
├── spec/agent-spec.md           # the 12-section contract
├── solution/                    # THE AGENT
│   ├── .claude/
│   │   ├── skills/              #   behavioral-health-um, umlite-architecture,
│   │   │                        #   rules-to-dmn, decompose-transaction
│   │   ├── agents/              #   the eight specialists
│   │   ├── commands/            #   modernize, validate, report
│   │   └── settings.json        #   five hooks, six matcher groups
│   ├── rules_ir.py              #   BOTH engines + the divergence diff
│   ├── gap_register.py          #   the deliverable, with its constraints in code
│   ├── seam_map.py              #   and its refusals
│   ├── hooks.py  hooks_cli.py   #   five guards, one implementation, two entry points
│   ├── tools_reference.py       #   6 read-only tools
│   ├── tools_legacy.py          #   7 read-only tools
│   ├── tools_emit.py            #   5 tools that produce output
│   ├── dmn_writer.py            #   refuses to emit a table that would be wrong
│   ├── bpmn_writer.py           #   refuses a process that cannot express the domain
│   ├── screen_inventory.py      #   phase 9B
│   ├── route_writer.py          #   phase 9B
│   ├── validation.py            #   the nine parity checks, as pure functions
│   ├── coordinator.py           #   sequences; has NO file tools
│   └── evaluation/              #   golden cases, reference IR, 22 scenarios
├── starter/                     # same tree, 31 numbered TODOs. Generated.
├── tests/                       # 219 tests, all offline
├── expected_output/             # the reference run. Generated, not hand-written.
├── appendix/manual-loop.py      # the only messages.create() in the capstone
└── deploy/{local,gcp,aws}/

Note what solution/ and bh-um-lite/ are not: the agent's own subagents and skills are not part of its output. An agent that emits its own configuration into the workspace it is modernizing has confused the tool with the product, and confine_writes denies it.

Phase 9A: Backend and Workflow

Ten to twelve hours. Thirty-three numbered TODOs live in starter/; list them with grep -rn "TODO [0-9]" starter/. The order matters — TODOs 1–6 are the two rule engines, because until both engines run you cannot tell a correct conversion from a lucky one, and everything after depends on being able to tell.

Phase 9B: Frontend

Four to six hours, TODOs 28–31, and it is gated on 9A being green. The coordinator refuses to start it otherwise:

# solution/coordinator.py
elif args.phase == "9b":
    # 9B is gated on 9A. Run it against a red 9A and the client ends up
    # guarding around enforcement the backend does not have -- which looks
    # like the rule was migrated and is not.
    missing = [p for p in config.PHASES_9A if not session.is_complete(p)]
    if missing:
        print(f"9B is gated on 9A being green. Not complete: {', '.join(missing)}")
        return 1

Track 2: Build It Twice, Then Diff

The brief asked a question you should now be able to answer for yourself: migrate the repo, or generate a new one? Do both and compare.

# Track 1 -- modernize. Reads both trees.
cd solution && python coordinator.py --phase all

# Track 2 -- generate. Reads the spec only.
/generate-from-spec spec/agent-spec.md          # writes to generated/

diff -r bh-um-lite/ generated/

Guardrails and the Human Gate

Five hooks, wired as six matcher groups in .claude/settings.json. Four are can_use_tool denials — they run before the tool, so the call never happens.

The protected-content gate matches every tool deliberately. Scoping it to the legacy server would miss content arriving by any other path — a file read, a shell command, a tool added next month.

The agent cannot approve its own work

finalize_modernization denies unless BH_FINALIZATION_APPROVED is set. The agent reads that variable and has no code path by which it writes one. That asymmetry is the entire gate; the briefing it returns is presentation.

FINALIZATION REQUIRES HUMAN APPROVAL.

GAP REGISTER: port-as-is 2, extend 4, must-build-new 6, must-not-port 3
  MUST-NOT-PORT  cleartext PHI in logs, events and search
                 harm: decomposition multiplies one log sink into several...
  MUST-NOT-PORT  consent enforcement as a feature flag
                 harm: a week of CONSENT_ENABLED=false is unlawful disclosure...
  must-build-new concurrent review
  must-build-new 42 CFR Part 2 consent model
  ...

PARITY: READY FOR REVIEW
  [1] rules divergence: 0
  [2] protected-content leak: 0
  ...

QUEUED FOR HUMAN DECISION: 5
  BH_AUTH.LEGACY_OVERRIDE: ticket body reads, in full, "per DM request"
  LocRulesService adjustment B: the 2016 parity note, never actioned
  ...

A person must read artifacts/modernization_report.html and re-run:
    python coordinator.py --phase finalize --approve

The denial is the successful end of the run. The briefing is assembled from the artifacts, not from the agent's summary of them — the agent's account of its own work is the thing under review.

Validation and Evals

Ten checks, written as pure functions so they are testable without an agent run. A check nobody has ever seen fire is not a check — every one has a test that plants the flaw and asserts the check finds it.

Twenty-four scenarios

The tests cover mechanics. The evaluation suite scores judgement: did the run notice the overlap, did it refuse to guess at the undocumented flag, did it name the harm, did it flag the silent term collisions.

python solution/evaluation/test_suite.py --phase 9a    # >= 20 / 22
python solution/evaluation/test_suite.py              # >= 22 / 24

Several scenarios score a refusal. Scenario 4 — REFUSES to interpret LEGACY_OVERRIDE — scores zero for a confident interpretation however reasonable it sounds, because nobody at Bridgeway can check the answer and the cost of being wrong is a changed determination for a real person.

Deployment

Three tiers. Tier 1 is the lab and needs only Docker — there is no database and no broker, because this agent reads a repository and writes a repository.

cp solution/.env.example solution/.env      # add your ANTHROPIC_API_KEY
docker compose up --build

# Read artifacts/modernization_report.html, then:
docker compose run --rm agent python coordinator.py --phase finalize --approve

Six phases run for minutes to hours and then finish. That is a job, not a request handler — behind an HTTP endpoint you fight a 60-minute Cloud Run ceiling for no benefit. Cloud Run jobs and ECS tasks have no such limit.

Docker Desktop is not required. Rancher Desktop with the dockerd runtime works unchanged — both source mounts are :ro, which is second-layer enforcement behind the hooks, and a guardrail that exists in exactly one place is one refactor from gone.

HIPAA and 42 CFR Part 2

The checklist for any component you generate

• Does any log statement interpolate the clinical free-text field? Check string concatenation and structured-logging fields.
• Does any event payload carry it? Check every event, not just the obvious one.
• Is it mapped into a search index? An index is a second copy with its own retention.
• Does the audit trail store it? A before/after copy on every update accumulates copies with no expiry and no consent scope.
• Is the transport authenticated and encrypted? A plaintext broker on an internal network is still a disclosure to whoever can read the topic.
• Is there a free-text search over it, and does it check a role and a consent? A careful guard on a detail screen is undone by an unguarded search over the same field.
• Does an error path leak it — an exception message, a stack trace, a request body echoed into a log?

When to escalate rather than decide

Four things in this lab are questions for a compliance officer, not an architect. The agent queues them and stops:

• The Part 2 program flag was backfilled from a spreadsheet in 2014 and its accuracy has never been audited — yet it gates the entire regime.
• Two independent code paths fabricate a consent on the submitter's behalf. Most requests arrive by one of them. Who consents when a machine submits?
• The audit table holds protected content because the appeals team asked for it in 2012 and privacy never reviewed it.
• A frequency-based pend with no med/surg analogue, flagged by compliance in 2016 and never actioned.

That last one is worth dwelling on. An unactioned compliance note is evidence — it means someone already reached this conclusion and the organisation lost track of it. That is a far stronger signal than one an agent inferred, and it belongs in the register with the note quoted verbatim and its date.

Troubleshooting

📂 Get the files: labs/capstone-9-bh-um-modernization on GitHub — or clone the course once: git clone https://github.com/varasrinivas/agenticai-course.git

Going Further [ALL OPTIONAL]

None of these is required. Each is a real piece of work that the lab deliberately left open.

1. The appeals path. The platform team's backlog item #7, and the one gap our analysis missed. Behavioral-health denials are appealed at least as often as medical ones; the legacy system handles them in a shared mailbox and a spreadsheet. Design the sub-process, then ask what it does to the turnaround clock.
2. LOCUS/CALOCUS alongside ASAM. The lab models substance-use placement. Psychiatric placement uses a different framework, chosen by diagnosis rather than by member. Add a second rules IR and a router, and watch the hit-policy question reappear one level up.
3. Make the parity analysis a first-class artifact. Right now the three NQTL findings go to the manual-review queue. Produce the comparative analysis document a plan would actually need to have on file.
4. Run the agent against the OTHER donor. Point it at a platform you have and see how much of the gap register is really about behavioral health versus about the specific thinness of this donor. That is the honest test of whether the analysis generalises.
5. Idempotency for the EDI path. The X12 278 importer has no idempotency key and a duplicate guard that drops legitimate same-day requests. Design a real one — and notice that the transaction carries no identifier suitable for the job.
6. A disclosure-accounting UI. The lab builds the bh_disclosure table. Nobody can read it. What does a Part 2 accounting of disclosures look like to a member who asks for one?

What You Built

A coordinator and eight subagents that read a 2011 monolith and a modern platform neither of them wrote, and produced a third repository plus an argument about it. Concretely:

You also used .claude/skills/ for the first time in this course, and drew the line this capstone exists to teach: Skills carry knowledge and recipes; agents carry control flow and safety. Six subagents shared one behavioral-health ontology instead of six drifting copies of it.

References & Resources

In the lab

• spec/agent-spec.md — the twelve-section contract
• bhauthtrack/README.md — "where to start reading" and "things that will bite you"
• bhauthtrack/db/02_seed.sql — the golden set, with each case's expected outcome and the branch it exercises
• reference-umlite/VENDORED.md — what the donor does and does not have, with the build state verified
• reference-umlite/BACKLOG.md — the platform team's own planned-and-unbuilt list
• expected_output/ — the reference run: gap register, seam map, term map, screen inventory, rules divergence, the approval prompt
• appendix/manual-loop.py — the loop the SDK runs for you, and where the guardrails have to go without it

The four Skills

• behavioral-health-um — the domain, plus four bundled references and a code validator
• umlite-architecture — the target's house style, and an explicit "do not mirror" table
• rules-to-dmn — the seven-step runbook, plus the overlap checker
• decompose-transaction — classify the pairs before drawing the seam

Elsewhere in the course

• M26 — Hooks, Sessions & the Agent SDK — the mechanics of can_use_tool and HookMatcher
• M14 — Multi-Agent Systems — coordinator/specialist topologies and context isolation
• M17 — Output Guardrails & HITL — the approval-gate pattern
• Capstone 8 — Oracle to PostgreSQL — the same shape, one layer down: schema and data rather than architecture and domain

External

• ASAM Criteria — the placement framework this lab models in simplified form
• 42 CFR Part 2 — the substance-use-disorder confidentiality regulation
• MHPAEA — mental health parity, and the NQTL comparative analysis requirement
• DMN 1.3 specification — hit policies, and what each one does on an overlapping table