dds

# The risks we manage (the spine)

> 🚧 **dds-stub** — a scaffold awaiting human work; the holes (`TODO`,
> `needs-ratification`, `⚠`) are the worklist. Remove this line when none
> remain.

This is the **spine**: the set of concern-classes for which this product
must hold a deliberate strategy. It is not a catalog of data, and it is
not itself a strategy — a *strategy is an ADR*. This register indexes
*what must be decided*; each risk resolves to the ADR(s) that decide it,
and (where one exists) the external-register projection that validates
the decision against reality (see [`../registers.md`](../registers.md)).

**One file per risk.** Each `docs/risks/<id>.md` in this directory is one
risk; the filename stem is the risk id. The ids are the join keys every
risk reference resolves against — an ADR's `Risk:` trailer, an external
register's `Implicates` edge — so renaming a file is a repo- and
register-wide edit.

Read the register as a yardstick. For each risk the question is binary
and auditable: **is there a strategy, and does reality conform to it?** A
risk with no strategy is a finding, not a silence.

## How a risk is described

Each risk file carries four sections:

- **Stake** — the harm, in its own currency (what *goes wrong*, not the
  topic).
- **Currency** — what is at risk. This keeps the risk *distinct* from
  its neighbours; two risks with the same currency are one risk.
- **No strategy looks like** — the absence condition: the harm's
  SIGNATURE, so a gap is detectable rather than a matter of taste.

Deliberately absent: a "validation question" or any requirement-shaped
text. **Risk files name harms; ADRs make demands.** Whether a risk is
managed is COMPUTED, not authored here: "is there a strategy" is the
coverage table (`Risk:` trailers → Accepted ADRs — `/dds-check`'s hard
tier), and "does reality conform" is judged conformance of each
covering ADR's OWN Rule against the witnessed facts — the Rule is the
yardstick, written where the decision lives, unable to drift from the
strategy because it IS the strategy. A hand-authored per-risk question
is a second yardstick that shadows the ADRs and pulls decision-shaped
content (which control, which legal ground) into the harm-shaped file
— the two-worlds line, crossed. (Adequacy of a covering ADR to its
risk is judged at ratification, by the improve pass, and by the
conformance judge reading stake against Rule — the stake itself is
that judge's input.)

A fifth section, **Current state**, records the honest answer today, with
its strategy ADR or its gap.

The file ends with its structured trailers, in this order:

- **`Class: <name>`** — zero or more lines, one per fact class this
  risk covers, from the five-name vocabulary (`gating` · `erasure` ·
  `audit` · `surface` · `credential`). This is the ONE binding between
  the risk (and, through `Risk:` trailers, its covering ADRs) and the
  coverage table's rows — ratified content, verdicted by the check (an
  unknown name is a structural finding). A risk outside the witnessed
  classes simply carries none.
- **`Addressed by: <adr-stem>, <adr-stem>`** — exactly one line, bare
  stems (no backticks), comma-separated — the machine-readable
  risk→strategy link; present only where a covering ADR exists (files
  with a GAP carry no `Addressed by:` line). Each stem must resolve to
  a `docs/adr/` file, and the named ADR's `Risk:` trailer must point
  back (coverage closure, checked in both directions).

## Residuals — the ledger of known gaps

A **residual** is a known, specific, still-unmitigated gap: the named
remainder after the strategies are applied. Residuals are the unit
hardening status is counted in — "what exactly is still exposed, which
of it have we consciously accepted, and is the open count going down."
They live in a structured `## Residuals` section of the risk file, one
line each:

```
## Residuals
- `res.audit-view-unpoliced` · open · the audit_log_entries view
  re-exposes full version history with no policies block
  [lib/teamology/utils/resources/audit_log_entry.ex | "use Ash.Resource,"]
- `res.oban-args-emails` · accepted 2026-07-14 (bound-data-retention) ·
  rendered emails with student names sit in oban_jobs.args until the
  retention rule lands
  [lib/teamology/workers/email_sender.ex | "Oban.Worker"]
```

The shape, per line:

- **id** — `res.<kebab-slug>`, unique across the whole corpus. One gap,
  one identity: an ADR or another risk that mentions the same gap
  writes `see res.<id>` instead of re-describing it.
- **state** — `open` · `accepted <YYYY-MM-DD> (<by-or-adr>)` ·
  `closed <sha7>`. `accepted` means consciously carried, with the
  decision (or deciding ADR) named; `closed` keeps the line as history.
- **one sentence** — the gap, concretely.
- **witness** — `[<file> | "<verbatim quote>"]`, quote-verified by the
  check exactly like a witness fact: a residual whose quote no longer
  verifies is reported *stale — close or re-witness?*, so an
  acknowledgment can never outlive the code it describes. (Only
  `closed` residuals may omit the witness.)

Residuals are AUTHORED BY HUMANS and ratified by merge — the check
DISCOVERS candidates (its findings are proto-residuals) but never
writes them; a checker that can acknowledge its own findings can
absolve itself. Every check finding has exactly three exits, all
through a PR:

1. **fix the code** — the finding vanishes on the next run;
2. **ratify a residual** — the gap is real and consciously carried;
3. **sharpen the claim** — the finding was noise because an ADR was too
   vague: the ADR gains the missing scope boundary or named exception,
   and the finding dissolves because the demand, properly stated, never
   covered the case.

There is deliberately NO fourth exit — no suppression list, no dismiss
channel, no known-issues config. Its absence is load-bearing: every
false positive is forced to become a permanent sharpening of the
claims corpus instead of a tombstone in a config file.

## Signals — witnessed evidence a class is live here

A **signal** is a witnessed, finding-shaped fact the schema-level
derivations can't see (e.g. "impersonation grants are Logger-only") —
evidence that a fact class is PRESENT in this codebase, feeding the
coverage table's presence column. Signals live in a `## Signals`
section of the risk that covers them, one line each, and bind to
classes through that risk's `Class:` declarations:

```
## Signals
- impersonation grants are Logger-only
  [lib/app/grants.ex | "Logger.info("]
```

The shape, per line: the fact in one sentence, then the witness
`[<file> | "<verbatim quote>"]`, quote-verified exactly like a
residual's — a signal whose quote no longer verifies is reported
*stale — re-witness or remove*. Signals are authored by `/dds-sync`'s
witnessing pass and ratified by merge; the check never invents one. A
signal in a risk with no `Class:` declaration is a structural finding
— a signal needs a class home, and a class no risk declares forces the
risk into existence.

What residuals may and may not acknowledge: a residual acknowledges a
SPECIFIC finding (a structural, cube, or judged gap at a named
artifact). It cannot acknowledge an uncovered fact class — the hard
tier's floor. An uncovered class needs an ADR (an
`Accepted (interim, …)` acceptance is fine); coverage is the one thing
that may never be residualized away.

## How the spine is derived (do not pattern-match a checklist)

Derive bottom-up: tag every load-bearing thing the codebase does with its
*stake*, then cluster the stakes by **currency**. The clusters are the
risks. A top-down, regulation-shaped list reliably *misses* the stakes
that are not its frame — integrity of the core output, cost, auditability,
availability — and a coverage yardstick with those holes certifies "all
managed" while real concerns sit off the chart.

A risk earns its place when its stake is distinct in currency from its
neighbours; a candidate that shares another's currency collapses into it,
and a candidate that is a single decision (not a churning class) is an
ADR, not a risk.

## How coverage closes

An ADR that is a strategy for a risk carries one trailer line **per risk
it genuinely addresses** — repeat the line; do not pad:

```
Risk: <risk-id>
```

and the risk file names its strategies back (`Addressed by:`, above).
A strategy that is `Accepted` but carries `Conformance: partial` /
`pending` (see [`../conventions.md` §1](../conventions.md)) covers the
risk **in design only** — the risk file's Current state names the
realization gap, and the risk is not yet covered in practice.
Coverage is then computable in both directions: a risk whose `Current
state` names no covering ADR is a **GAP**, and where an external register
projects `Implicates` edges onto these ids, an implicated risk with no
strategy is a gap the register can surface. An ADR often *touches*
several risks while being a real strategy for only one — claim the one;
the others **remain gaps** until a strategy exists for each. That is the
model working, not a defect: never claim a risk an ADR does not actually
address just to silence the gap.

## The risks

> TODO — derived from this product's code by `/dds-sync`, ratified by
> the relevant authority. The set commonly includes some of:
> confidentiality of subject data · authorization & authentication ·
> authority to process · data across trust boundaries · secrets &
> credentials · integrity/correctness of the core output · accountability
> & auditability · cost & resource governance · availability. Derive the
> actual set; do not adopt this list.

## Excluded — and why

Record the exclusions so the next reader does not re-litigate them
(e.g. privileged capabilities are *things* that implicate risks, not a
concern-class; routes are code-sourced with nothing governed; the docs
themselves are the *why* layer). TODO per this product.

Codified-by: TODO — the code surfaces from which the risks were derived.