Liking cljdoc? Tell your friends :D

Omission decisions as design documentation

A decision to defer, waive, or accept risk is a human governance decision. Record its rationale in the project's normal design-decision mechanism—such as an ADR, RFC, risk register, or subsystem design document—not as Bridge runtime state.

Bridge does not define or validate an omission-decision-record artifact. A document describing an omission does not discharge an obligation, make missing evidence pass, or change convergence. Bridge continues to report the obligation until executable evidence or configuration resolves it.

What to document

An omission decision should make review possible without implying automated enforcement. Include:

  • the omitted work or evidence and its scope;
  • the decision status and date;
  • rationale and alternatives considered;
  • owner and explicit approvers, when applicable;
  • affected requirements, subsystems, and risks;
  • compensating controls and their executable evidence;
  • expiry, review trigger, or condition for reversal;
  • links to related issues, code, policy, and evidence.

Use the repository's established approval and ownership process. Git history records revisions to the decision.

Bridge integration

Bridge's verification policy should express evidence that is required, recommended, optional, or forbidden. Canonical commands and fresh evidence receipts establish what ran and passed. If project governance permits a true machine-enforced waiver in the future, it should be implemented as an explicit obligation-resolution model with scope, approval, expiry, and provenance—not inferred from the presence of prose.

A design document can be included in subsystem docs-globs so documentation changes participate in change classification, but it remains documentation rather than evidence or authoritative Bridge state.

Can you improve this documentation?Edit on GitHub

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
Move to previous article
Move to next article
Ctrl+/Jump to the search field
× close