Safety and Evidence Model

Safety & Evidence Model

Diátaxis Docs is built to be trusted with a repository. That trust rests on a small number of hard rules, each of them tested.

Read-only by default, approval before writes

Diagnosis commands (doctor, check, map, context, audit, classify) write nothing — not documentation, not .diataxis/ state. Structural commands (init, migrate, cleanup) always produce an exact preview first and mutate nothing until you approve that exact preview. A request to "diagnose and fix" in one message does not skip the gate: the diagnosis is still read-only, and the fix still waits for approval.

Skill invocation is explicit-only, repository handling is prompt-injection-resistant, and a dirty worktree is preserved — the product works around your uncommitted changes rather than through them.

Findings have identity

Every finding carries a content-derived DOC-* ID and a full SHA-256 fingerprint computed from its normalized semantic identity. Moving a line or re-running the checker does not change the identity; changing what the finding actually means does. Approvals name exact IDs and full fingerprints, and the executing command revalidates both against fresh evidence before writing — so the thing you approved is provably the thing that runs. If the evidence changed in between, the old approval is refused and a new proposal is required.

Destructive changes carry a manifest

Any transformation that moves or removes documentation ships a complete disposition manifest: every removed file and every unique removed section appears exactly once, tagged MIGRATED, DEDUPLICATED, ARCHIVED, or DISCARDED, bound to its current content digest and a recovery boundary. Approval must name the manifest. There is no "trust me, it's handled."

Protected surfaces stay put

Public entrances — the README, legal and community files, release and automation files, package manifests, documentation-site declarations — keep their established paths and semantics by default. Local-only knowledge (.diataxis/local-map.json) stays local and is mechanically verified as Git-ignored; it never leaks into shared state.

Failure fails closed

Corrupt, incomplete, or conflicting operational state is a diagnosed condition, not an excuse to guess: the engine reports it, refuses to grant treatment authority from it, and offers a deterministic, zero-write recovery preview that itself requires exact approval. Failed verification becomes a rollback or an explicit conflict — never a silent success event.

The checker can't phone home

The deterministic checker is Python standard library only: no network, no dependencies, no execution of repository content. MDX is parsed as inert text. All paths are confined to the repository, with symlink, junction, and reparse-point defenses on every route.

The evidence behind the claims

• 700+ deterministic tests across Windows and Linux CI, including full public-journey lifecycle regressions.
• Canonical-versus-generated parity checks on every adapter, enforced in CI.
• Web prompt bundles are measured per command; the generator's size-regression guard is a documented packaging tripwire with recorded headroom — not a product or health threshold.
• Sanitized, reproducible evaluation fixtures; see Evaluation & Benchmarks for what has and hasn't been run.