Jurisdiction Setup Agent — what it needs, and what it must never do

The architecture of agent-assisted jurisdiction configuration: the three-way split of what is knowable, the four-phase loop, and the one boundary that is enforced in code rather than documented in prose.

Live vs demonstrated: Live — real, API-backed platform logic (wired end-to-end today) Demonstrated — representative control surface with seeded data / illustrative UI mock-up

1 · The premise

Most of a jurisdiction configuration is a published fact. NHS Number is ten digits with a Modulus 11 check. CQC regulates care in England under the Single Assessment Framework. FOIA runs twenty working days. These have citable sources. Asking a customer to type them into a wizard wastes their time and introduces transcription error into a governance artefact.

So the agent proposes what is knowable and asks only about what is not. In practice that is roughly twelve questions instead of sixty.

2 · The three-way split

A · Knowable

Identifier formats and check digits · regulators and inspection frameworks · background-check schemes · professional registers · coding systems · data-protection law and supervisory authority · statutory clocks · ISO 4217 currency.

Agent proposes, with a citation.

B · Discoverable

Existing jurisdictions as templates · the 14 Profile domains and which are mandatory · the real role matrix · enabled features · and critically the platform's own identifier validators.

Agent reads from the running system.

C · Customer-only

Edition and modules · organisation hierarchy and codes · local vocabulary · named accountable people · integration endpoints · payers and funding model.

Agent must ask. There is no external source.

Why the split matters. An interview that asks about category A is asking the customer to do the agent's homework, and every answer is a chance to introduce an error into a value that has a definitive published source. An agent that guesses at category C is inventing organisational fact. The split is the design.

3 · The four-phase loop

Phase	Endpoint	What happens
1 · Know	`GET /jurisdiction-agent/knowledge`	Exposes the reference corpus — every jurisdiction it covers, the source for each, and the six things it will never know. An agent whose knowledge cannot be reviewed cannot be trusted with a governance artefact.
2 · Propose	`POST /jurisdiction-agent/propose`	Drafts the wizard config and the Profile entries without writing anything. Every value carries a citation. Returns the customer-only questions alongside.
3 · Apply	`POST /jurisdiction-agent/apply`	Writes the jurisdiction and the Profile entries at `assurance_status = "sourced"`. Idempotent — re-running never duplicates. Audited.
4 · Verify	`GET /jurisdiction-agent/verify/{jid}`	The agent checking its own work: runs the platform's real identifier validators over its proposed formats, confirms every value is cited, confirms nothing was signed off, and reports the deployability board honestly.

Phase 4 is the one that distinguishes this from a template generator. The agent does not assert that its NHS Number format is right — it runs a sample through _JP_IDENTIFIER_VALIDATORS, the same Modulus 11 implementation the platform uses at runtime, and reports the result.

4 · The boundary — enforced, not documented

The agent writes sourced. It can never write signed_off. Not by convention, and not only when asked nicely: the field is forced in the apply handler regardless of what the caller sends, and two tests assert it — one that a normal apply never signs off, and one that an apply explicitly passing assurance_status: "signed_off" is overridden.

The reason is that sign-off is not a data value. It is a named person accepting accountability for a jurisdictional fact, and the Jurisdiction Profile already gates deployability on it:

JP_MANDATORY_DOMAINS = ["identifiers", "terminology", "data_protection",
                       "clinical_safety", "consent_capacity"]

deployable = all(domain signed_off and unexpired for domain in JP_MANDATORY_DOMAINS)

So an agent-configured jurisdiction is correctly not deployable the moment the agent finishes. That is not a limitation to engineer around — it is the control working. The output of the agent is not a finished configuration; it is a configured system plus a signature queue.

5 · Fail-safe, not fail-sideways

For a jurisdiction outside the corpus, the agent produces an empty skeleton with every value listed as unknown. It does not reach for the nearest neighbour.

Behaviour	Known jurisdiction	Unknown jurisdiction
Profile values drafted	17	0
Patient identifiers	Proposed, with check-digit rule	None — must be supplied
Regulator	Proposed, with statutory source	null — explicitly not defaulted
Questions for the customer	6	12

A test asserts that an unknown jurisdiction's output contains no trace of CQC, nhs_number or DBS. This mirrors Jurisdiction Profile PRD §4.6: a missing value must never resolve to another jurisdiction's — a plausible-looking wrong regulator is more dangerous than an honest blank, because nobody checks it.

6 · What the agent is deliberately not given

Secrets. Every credential is server-side environment only. The agent never sees an API key, and the API exposes only a secret_present boolean.
Sign-off authority. Covered above.
Activation. Applied jurisdictions are written active: false. Turning one on is a human act.
Module selection. A commercial decision, always asked.

7 · Where it sits

Component	Location
Reference corpus	`_JA_KNOWLEDGE` — five jurisdictions, every value cited
Customer-only decisions	`_JA_CUSTOMER_ONLY` — six, always asked
Profile mapping	`_ja_profile_entries()` — corpus → the 14 domains
Setup surface	`/jurisdiction-agent`, under Administration
Downstream	`/jurisdiction-wizard` · `/jurisdiction-profile` (sign-off) · `/regulatory-engine`
Tests	`tests/test_jurisdiction_agent.py` — 13, including the two forgery tests

8 · Extending the corpus

Adding a jurisdiction is a data change, not a code change. Add an entry to _JA_KNOWLEDGE with:

aliases the customer might type;
identifiers with the exact format including the check-digit rule — "10 digits" is not sufficient;
regulator, inspection framework, background-check scheme and registers, each with the statute that establishes them;
statutory clocks with the working-versus-calendar basis stated explicitly;
currency with the correct decimalDigits — note the three-decimal currencies (OMR, KWD, BHD, JOD).

The rule for the corpus. If you cannot cite it, do not add it. An uncited value is not deployable under the Profile standard anyway, so putting one in the corpus only moves the failure later — to the point where someone is asked to sign their name against it.

Every environment variable, wizard step, endpoint and role named in this guide was read from the codebase, not recalled. Non-SaMD administrative documentation.
© 2026 Commvita Digital Health Solutions Ltd. All rights reserved.