STATE.md

Current verified state

Diátaxis Docs 0.1.8 is the current public-alpha release. The canonical source is skills/docs/; Codex, Claude, static, and web packages are generated from it and parity-checked.

Warning

Bounded daily-driver trial. Use 0.1.8 in a Git-backed repository, inspect every proposed diff, and keep the approval boundary intact. The engine emits shared classification and readiness facts, but the installed presentation still shows transitional legacy health and does not render the engine-owned map ledger. Those presentation gaps and two confirmed fail-closed syntax limits are recorded in known issues.

The repaired selection defect

Default command routes used to measure different documentation. Reproduced on this repository at commit da02ba2, with no repository changes between runs:

Route	Command	Result then	Result now
Checker default	check.py . --json --agent	boundary docs — 2 maintained documents, 100%, clean, 0 findings	boundary . — legacy rubric v2: 61 measured documents, 89%, needs-attention, 7 findings
Human override	check.py . --json --agent --scope .	boundary . — 89%, needs-attention, 27 findings	unchanged boundary, now identical to the default
Doctor first-contact baseline	check.py . --json --agent --doctor-baseline	unavailable — two candidate roots, no boundary, no score	boundary . — same documentation/readiness result; provisional entry candidate with no treatment authority

Rows 1 and 3 were the two default routes — no boundary was supplied to either, and they disagreed about whether the repository had any documentation problem. Row 2 was a human override, shown because it revealed what row 1 hid. The measurement function was deterministic; the files handed to it were not.

All three routes now measure the same boundary and manifest identity. Doctor still labels this uninitialized repository a provisional existing-entry-candidate, recommends Map, and withholds treatment authority. Removing that extra step without guessing the document's purpose remains the Doctor-independence work in product constitution gap 11.

One engine-owned selection policy now answers the question once per repository snapshot: which boundary is measured, which document is its map, which route a reader enters from, and which routes the map declares as current truth. Map, Check, Doctor, Audit, and Init consume that answer. An omitted boundary is the repository, not docs/. Only an explicit human request narrows it, and that result reports itself as a partial component view. Recorded Init state contributes adopted intent, which is reported beside the measurement rather than replacing it, so an initialized repository and a fresh clone of the same documentation produce one manifest identity. Each of those results carries that identity, the selected routes, and whether the accounting behind it is complete.

Earlier documentation claimed that Doctor, Map, Check, Audit, and Init share one deterministic documentation measurement. The claim as written was wrong — the commands shared a measurement function, not a selection — and it has been replaced everywhere it shipped, including skills/docs/SKILL.md, its references/ contracts, and the generated adapter copies. The historical 0.1.3 entry in CHANGELOG.md still records the claim as it was believed then; a dated changelog entry is not rewritten.

The shared result now carries the ordered documentation ledger, independent role/never-edit/repository-status facts, policy provenance, deterministic groups, unresolved cards, and readiness v3. What remains: the installed Map contract does not render that ledger; the envelope still carries the legacy rubric-v2 percentage beside readiness v3; a link out of an explicitly narrowed component boundary can still validate while its target stays outside that measurement; and context, write, and update still lack matching deterministic engine entrypoints. The full gap list is in the product constitution.

What is verified today

• Doctor's first pass is read-only and requires exact treatment approval before any write.

• Initialized repositories bind Doctor to their recorded map, boundary, findings, and event history.

• A genuinely uninitialized repository may close out an approved Doctor treatment statelessly. Verification does not create .diataxis/; Init remains a separate choice.

• Non-transactional .diataxis corruption returns one bounded, zero-write recovery action instead of leaving the user at action: none. Doctor never performs that operator action automatically.

• Partial, malformed, stale, or conflicting operational controls fail closed.

• Markdown destinations wrapped in angle brackets can contain spaces without becoming false broken-link findings.

• Markdown and MDX are scanned as inert text. Unsupported navigation providers are unmeasured rather than guessed. The tested evidence subset is not a claim of complete CommonMark or arbitrary MDX conformance.

• An additive engine-owned documentation manifest accounts for every in-policy repository document exactly once — tracked, untracked, and ignored or excluded — with ignored bodies unread and named exclusions. Its identity binds normalized content for inspected bodies, so a real documentation change moves it while line-ending, Unicode-composition, or path-case spelling differences do not, and it survives a fresh clone.

• One engine-owned documentation result publishes that manifest's ordered path ledger. Every document has an evidence-bounded role, independent user-owned never_edit fact, independent repository status, write eligibility, and the reason for any exclusion. The selected map and declared current-truth routes are maintained evidence; ordinary links and filename or folder hints cannot silently assign a role. Invalid or conflicting docs:policy input fails closed.

• The selected readable entry's current working-tree docs:policy bytes are authoritative for the current snapshot. When a provider uses a separate machine-readable authority, policy provenance and approved writes stay bound to the entry whose bytes were parsed. The result separately reports whether those bytes match Git and are therefore durable; a non-Git repository receives the honest no-saved-version notice. Exact-file policy rules override directory rules, including explicit never-edit opt-outs, and rendering preserves the existing line order while touching only edited entries.

• Readiness v3 is the unweighted fraction of eligible maintained documents whose reachability, internal links and anchors, title identity, and confinement all pass. It exists only for a complete measurement with a valid selected map, names every failed fact, and never consumes Trust or compares itself with stored rubric-v2 state.

• Unresolved nonignored documents receive deterministic individual or directory-group cards. A resolution previews one exact map-policy diff behind a stateless, snapshot-bound DOCS-R- approval; preview and apply can cross a process boundary, while changed map bytes, changed supplied decisions, or immediate reuse after a successful apply refuses without writing. If those exact bytes and decisions are deliberately restored, the same code is current for that restored snapshot. Init persists approved never-edit choices into the map, and treatment policy keeps never-edit, ignored, unresolved, and non-maintained reasons separate from readiness.

• One Windows-visible behavior change came with it. Repository-relative path validation rejected a rooted path such as /docs/README.md on POSIX but accepted it on Windows, where a rooted path carries no drive letter. It is now rejected on both. A rooted --map or --hot argument therefore returns one clean input error on Windows instead of the previous wrong answer — a missing-map finding for a file that exists, or a silently discarded hot path. A rooted --scope was already refused and is unchanged.

• Map, Check, Doctor, Audit, and Init consume one engine-owned selection. On one unchanged snapshot the default checker route, the first-contact Doctor baseline, and an initialized Doctor produce the same measured boundary and the same manifest identity, and a component request is reported as partial. Selection reads directory listings and the one repository inventory the manifest already needs, so a command inventories the repository once rather than twice.

Each item above is proven for the route that owns it.

On this working copy, the repository checker accounts for 94 documentation paths: 3 maintained, 20 generator-declared outputs, and 71 unresolved, including 32 ignored or excluded paths whose bodies stay unread. A fresh checkout accounts for 62 paths: the same 3 maintained and 20 generated documents beside 39 nonignored unresolved documents. Readiness v3 reports 3 of 3 eligible maintained documents ready. That 100% is only the eligible fraction beside those unresolved documents; it is not whole-repository health. The transitional legacy rubric remains separately visible until the presentation work removes it.

The same ownership gap also affects context, write, and update: the current routes do not have matching deterministic engine entrypoints for evidence selection or mutation planning. Until those entrypoints exist, the model can be asked to choose work that the product constitution assigns to the engine.

The latest measured results and remaining coverage are in BENCHMARK.md. Release history is in CHANGELOG.md, host support is in COMPATIBILITY.md, and confirmed release limits are in KNOWN_ISSUES.md.

This page is the hot path. Generated adapter internals, private local material, historical evaluations, and Git history stay cold until needed.