Initial curated itworx-knowledge-hub source from 3b1751d0d9dee551aa6994eee0093704dc334817

docs/16-runbooks-and-adrs.md

@@ -0,0 +1,106 @@
+# 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.