107 lines
2.4 KiB
Markdown
107 lines
2.4 KiB
Markdown
# 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.
|