Sense 60: The Doctor

Sense 60 · Forming · Last touched 2026-07-27

• last_verified: 2026-07-27

Synced from docs/design/sense_60_the_doctor.md in the engine repo — that’s the source; this page is a build-time mirror.

Status: proposed — sketch, on the agenda (not yet specced to build) Date: 2026-07-15 Origin: a conversation with Mig about self-observation — the system noticing its own configuration problems before they cause impact. The insight underneath: the operational wisdom about how AFSes and tenants go wrong currently lives in Claude’s memory and in people’s heads. It should be reified into the running product as an advisory layer, so it helps every operator on every tenant — not only when a human (or Claude) happens to be in the loop. Companion Sense docs: Sense — Subject Matter (the sibling: knowledge about the data; the Doctor is knowledge about the framework) · Sense 21 The Heartbeat (rhythm; the Doctor rides a beat) · Bell (health delivery channel) · Sense 59 The Double Circle (the Doctor observes both circles from outside) Working name: The Doctor, after jin doctor — a check-up for a tenant. Final naming is Mig’s.

Claim

jinflow already runs instruments on data. The Doctor runs instruments on the framework itself — the system observing the system. It answers a question no validator asks:

“This is perfectly valid and it compiles clean — but I’ve seen this shape go wrong. Are you sure?”

It is a check-up: a read-only pass over a tenant’s AFS, config cascade, KLS, and build history that emits graded, self-explaining advisories — “I observe X; here’s why it might be a problem; here’s the fix.” Never blocking. Never a gate. A second opinion.

The one distinction that makes or breaks it

The Doctor is not another validator. We already have six (signalcheck, typologycheck, verdictcheck, jin inspect --check, …). Those answer “is this well-formed / will it compile?” — binary, blocking, correctness.

The Doctor answers “is this likely wrong even though it’s valid?” — graded, advisory, health.

	Validators	The Doctor
Question	will it compile?	will it behave as you expect?
Verdict	pass / fail	info / warning (graded)
Blocking	yes — a gate	never — a second opinion
Catches	malformed YAML, contract violations	dead overrides, stale KLS, null-column signals, silent smells

The boundary is load-bearing. The moment a Doctor advisory blocks a build, it becomes a validator, and people route around it. Health stays advisory; correctness stays blocking. (This is infra gates, not user gates applied to observation.)

Sibling to Subject Matter — not the same

The Doctor is the framework-facing sibling of Subject Matter:

• Subject Matter — attributed expert knowledge about the tenant’s data: process workarounds, mapping quirks, historical events. Its L1 “Check” runs SQL against Gold.
• The Doctor — accumulated operational knowledge about the framework: config-cascade traps, staleness, dead artefacts, coverage gaps. Its check runs against the AFS / config / system-DB / KLS metadata, not (only) SQL on Gold.

Same primitive shape — a testable assertion that carries its why (the field that separates knowledge from noise) — different substrate. The Doctor borrows Subject Matter’s philosophy wholesale: the reason is the point. A check that cannot explain itself does not ship.

Its findings can ring the Bell — health already has a delivery channel — and its verdicts read like the diamond’s: observe → find → explain → recommend, pointed at the framework.

The check primitive

A Doctor check is declarative — data, not hardcoded Python. The engine ships a base set; packs and tenants add their own. (A hardcoded doctor rots; a declarative one grows every time we learn something — Form follows Data.)

Each check carries, at minimum:

Field	Meaning
id	check slug
observes	what it looks at (AFS artefact class, config path, KLS metadata, build journal)
level	info | warning (no error — that’s a validator’s word)
assertion	the smell test — declarative or a bounded query over the observed surface
why	required — why this shape has bitten us before
fix	the concrete next action
confidence	optional — how sure; low-confidence checks whisper, they don’t shout

An advisory is one check firing on one tenant: {check_id, tenant, subject, level, why, fix, observed_at}.

The base check-set already exists

The first checks are sitting in memory’s Known Issues / Traps / Feedback — and two exist already, hand-rolled, proving the pattern:

• KLS stale > N days — already live in the /admin/system cockpit; the Doctor generalizes it.
• Note with a self-pack/self-tenant absolute path — jin make already warns; the Doctor absorbs that one-off into the layer.
• Signal references a Gold column that is 100% null in this tenant (valid, dead).
• Config override byte-identical to the level below it (a dead override that reads as intent).
• Typology coverage below threshold; KLS built against a different engine version than current.
• A signal that has produced 0 findings across the last K builds (a candidate dead instrument).
• Extractor SHA drift against pipeline.yml (today jin inspect --check; the Doctor surfaces it as advisory, not just CI exit code).

The work is not inventing a mechanism — it is generalizing the warnings we already write into a layer that carries its own reasons.

Two homes

• Per-tenant — jin doctor <tenant> (read-only CLI) + a Bench panel showing the tenant’s current advisories.
• Cross-tenant — the /admin/system cockpit rolls up every tenant’s advisories behind system:admin: “3 tenants stale, 1 dead signal, 2 coverage gaps.” This is exactly what that page is for; the Doctor gives it something to say.

When it runs

• On demand — jin doctor, always read-only, safe to run anytime.
• As a post-make advisory pass — continue_on_error, the way typologycompile bakes (Sense 54): observe after the build, write advisories to the system DB / a meta table, never abort the build. One beat of the Heartbeat.

The frontier — the Doctor that learns

The base set is hand-authored from what we already know. The ambitious version: the system proposes new checks from patterns it observes — evolve, but for the framework. When a tenant repeatedly hits a shape that later needed fixing, the Doctor drafts a candidate check (with a why) for a human to accept. That closes the loop this Sense opens: operational learning flowing into the product continuously, not only when we hand-write a rule. Named here, not built — a phase beyond the first.

Non-goals (for now)

• Not a validator, not a gate. It never fails a build. If a condition should block, it belongs in a *check.py validator, not the Doctor.
• Not the Bell, not the Heartbeat. It feeds the Bell and rides a Heartbeat beat; it is neither. The Doctor is what is observed; those are how it’s announced and the rhythm.
• Not cross-tenant snooping. Per-tenant checks stay scoped to their tenant (the AI-isolation discipline); only the system:admin rollup sees across, and it sees advisories, never tenant data.
• Not specced to build. This is a sketch to put it on the agenda. The build spec (check schema, base-set authoring, the two homes, the make hook) comes later, spec-first.

Vocabulary this Sense proposes

• The Doctor — the advisory self-observation layer: read-only checks over the framework (AFS, config, KLS metadata, build history) emitting graded, self-explaining advisories. Sibling to Subject Matter. Platform term (proposed).
• Advisory — one Doctor check firing on one tenant: a warning-level observation carrying its own why and fix. Distinct from a validator’s pass/fail and from a signal’s finding. Proposed.
• Check-up — a full Doctor pass over a tenant (jin doctor <tenant>). Proposed.

---

Numerical neighbors: ← Sense 59: The Double Circle · Sense 61 — The Private OPS (bring your own operational store) →