Architecture

Architecture

A guided tour of how Diátaxis Docs is put together. The canonical, versioned record is ARCHITECTURE.md in the repository; this page explains the same design in plain terms.

One canonical source, many installations

Everything ships from skills/docs: the skill contract (SKILL.md), the command playbooks (references/), and the checker (scripts/). The Codex plugin, the Claude plugin, and the Copilot/Cursor/Grok/web adapters are generated outputs built by tools/build_adapters.py — never hand-edited, always regenerated, and CI fails if a generated copy drifts from the source. When you install on any host, you're getting the same engine.

Each generated adapter packages the complete checker resource tree. The web prompt bundles are composed per command — a shared safety core plus that command's contract — instead of concatenating the whole playbook, and the generator enforces a measured size-regression guard on the largest composition (a packaging tripwire, not a product limit).

The deterministic checker

skills/docs/scripts/check.py is a network-free, standard-library Python tool — a thin façade over cohesive _docs_checker modules. On every run it:

• confines all paths to the repository and rejects symlink/reparse tricks;
• treats .md, .markdown, and .mdx as one inert document policy (MDX is parsed, never executed);
• selects one bounded navigation surface (your Markdown map, or a supported provider manifest);
• parses links and anchors, then reports unreachable pages and duplicate titles;
• evaluates state-declared Trust routes and content-hash freshness;
• reports map and current-state byte sizes as provenance-tagged telemetry.

The same deterministic surface result feeds Map, Check, Doctor, Audit, and Init — one measurement, many consumers. Anything malformed, unsafe, or unsupported is reported as unmeasured rather than given a made-up score. Model-generated semantic findings sit in a clearly labeled lane above these deterministic facts and can never contradict them.

The module layout

Responsibilities are deliberately one-way:

Module	Owns
discovery.py / discovery_policy.py	Bounded metadata discovery and scope selection
init_adoption.py / init_closeout.py	Deterministic, engine-owned adoption: preview, corpus accounting, receipt binding
paths.py	Confinement, normalization, reparse defense, prune rules
memory.py	Read-only inspection of committed .diataxis/ state
lifecycle.py	Pure authorization and state policy
lifecycle_io.py	Transactional filesystem writes with rollback
doctor_baseline.py / doctor_closeout.py	First-contact measurement and approval-bound treatment closeout
evidence.py	Sanitized, typed evidence receipts

The CLI façade stays thin; policy never does I/O, and I/O never invents policy.

The control plane

Committed .diataxis/ state is the product's memory: normalized routes, stable findings, verified hashes, disposition identity, and event history. It never stores document bodies, prompts, hidden reasoning, or local-only filenames. There is no database and no daemon — the repository itself carries the memory, so every session (and every collaborator's clone) starts from the same truth.

First-contact Doctor

On a repository Doctor hasn't adopted, the engine resolves what it's looking at before it measures: committed operational state is validated and measured against its maintained map; without state, a supported provider gives an authoritative measurement, a conventional entry file gives a provisional candidate, and a tracked root README gives an orientation fallback that recommends Init. Unsafe or incomplete evidence stays unmeasured. Presentation changes by situation; the scoring rubric never does.