# Runbooks and Architecture Decision Records

## Architecture Decision Records

ADRs provide durable reasoning, not only outcomes.

### Required sections

- Context
- Decision criteria
- Options considered
- Decision
- Consequences
- Validation

### Metadata

- stable ID;
- project;
- human-readable decision number;
- status;
- decision date;
- supersedes/superseded-by;
- owner/author;
- linked page;
- tags.

### Lifecycle

- Proposed
- Accepted
- Rejected
- Superseded
- Withdrawn

An accepted ADR can be superseded only by another accepted ADR. Links are bidirectional
and cycle-free.

Editing the ADR page creates revisions. Changing lifecycle metadata is audited and
revisioned. Historical decisions remain readable.

## Runbooks

A runbook is a human-executed procedure. The platform never runs its commands.

### Required sections

1. Purpose
2. Scope
3. Prerequisites
4. Steps
5. Validation
6. Rollback
7. Risks/notes

### Metadata

- owner;
- risk: low/medium/high/critical;
- system/project tags;
- last validated time and validator;
- review due time;
- estimated duration (optional);
- maintenance-window requirement (optional);
- runbook status.

### Checklist behavior

Markdown task lists may be used as a transient execution checklist, but checking boxes in
a normal read session must not silently modify the canonical runbook.

A future “run session” can create an execution copy, but that is deferred. In v1 the UI
may provide a local/non-persistent checklist mode with an explicit warning.

### Validation

Marking a runbook validated requires:

- permission;
- current revision;
- validator;
- time;
- optional evidence/comment.

A new content revision makes prior validation stale unless the change is explicitly
classified non-procedural and policy allows it.

### Safety

- Commands render as text/code only.
- No terminal bridge.
- No secret interpolation.
- No copy button may include hidden text.
- Sensitive-value placeholders are visibly marked.
- High/critical runbooks emphasize prerequisites, validation and rollback.

## Templates

Canonical templates live in `product/templates/`. The application may seed editable
copies, but template version/provenance is retained.

## API behavior

ADRs and runbooks are retrievable through their own typed endpoints and through page
resources. The context API returns bounded summaries and stable page citations rather
than silently parsing arbitrary headings at request time.