ADR-0005 — Fail-closed sanitisation gate for published docs

Status: Accepted

Context

This documentation site is derived from the LisaOS vault — the same ground truth that records infrastructure coordinates, credentials' locations, real names, and client identities. Publishing vault content directly would leak exactly the material that must stay private. A best-effort "remember to scrub it" process is not enough: the cost of one missed coordinate is a permanent public leak, and previews often deploy in parallel with review, so "we'll catch it in review" is not a control.

Decision

Publish through a two-part pipeline with a fail-closed gate. A converter transforms vault source to site pages mechanically, applying two classes of rule: abort rules, where a forbidden coordinate stops conversion outright, and generalise rules, where a coordinate is transformed to a published-safe form and the change is recorded. A separate sanitisation check then scans the content — and, after build, the built output and search index — for any forbidden pattern.

The gate runs inside every build, before the site can be emitted, so it blocks preview deploys, production deploys, and direct pushes alike. An empty rule set or an empty scan target is itself treated as a misconfiguration and fails — a gate that scans nothing is not a gate. Coordinates are generalised or withheld by design; the architecture, protocols, and governance are what publish.

Consequences

• Positive: A forbidden coordinate cannot reach a public page through any deploy path — the control sits before emission, not after review.
• Positive: The rules are a reviewable, versioned registry. Changing what counts as forbidden is a governed change, reviewed like code.
• Positive: The gate is provably load-bearing: during the campaign it blocked a build over a class of operator personal data, forcing generalisation before the wave could proceed. (See the campaign changelog — recorded by class, never by instance.)
• Negative / accepted: Authoring for this site is more constrained than ordinary writing — even the sanitisation records must mask the coordinates they describe, or they re-trip the gate against themselves. This self-referential discipline is accepted as the cost of a gate strict enough to trust.
• Negative / accepted: Some genuinely useful specificity (exact topologies, worked examples with real identifiers) can never be published. The architecture is documentable; the coordinates are not, by design.