Architecture Decision Records

Canonical, single-topic records for the architectural decisions that shape this platform. Each ADR captures one decision with enough context that a future maintainer can tell why we chose what we chose — and what they'd have to redo if they wanted to change it.

What lives here vs. elsewhere

• ADRs (docs/decisions/) — one decision per file, with a life-cycle status (Proposed / Accepted / Superseded / Deprecated). Short, self-contained, cross-linked to the originating spec or PR.
• Design specs (docs/superpowers/specs/YYYY-MM-DD-*.md) — narrative design documents for a feature or subsystem. May contain several decisions bundled together with implementation detail. Specs are the source of truth for the narrative; ADRs are the source of truth for the decision.
• Design decisions aggregate (../developers/reference/design-decisions.md) — a fast-scan one-liner list of every architectural rule of the platform. Read this to orient; drop into an ADR when you need the why.

If a decision is worth its own follow-up conversation a year from now, write an ADR. If it's a tactical choice tied to one feature's implementation, keep it in the spec.

Filename convention

NNNN-kebab-case-title.md — four-digit, zero-padded, monotonically increasing. Numbers are permanent; if an ADR is superseded, the new ADR gets the next number and the old one is marked Superseded by ADR-NNNN.

Never renumber; never delete. Deprecated ADRs stay, so the trail is intact.

Status vocabulary

Status	Meaning
Proposed	Drafted, under review. Not yet in effect.
Accepted	The decision the platform runs under today.
Superseded by ADR-NNNN	Replaced by a later ADR. Kept for history.
Deprecated	No longer applies, but not replaced by a newer ADR (e.g. the constraint the decision addressed went away).

Writing a new ADR

1. Copy _template.md to NNNN-your-title.md with the next unused number.
2. Fill it in. Keep the whole document under ~120 lines — one screenful of context beats an unread essay.
3. Add an entry to the table below.
4. Add the ADR to the sidebar in docs/.vitepress/config.ts under Developers → Reference → Architecture decisions (ADR). The predocs:build guard fails the build if you skip this.
5. Open a PR. ADRs are reviewed like code.

Index

#	Title	Status	Date	Related
0001	Tutorial HTML persists in HANA, not on disk	Accepted	2026-04-28	hugo-migration spec
0002	QA channel is a parallel srv + HDI, not a route flag	Accepted	2026-05-23	tutorials-qa spec
0003	Public Hugo with lazy XSUAA login	Accepted	2026-04-22	POC spec
0004	JWT-only identity on CAP (no SCI profile enrichment)	Accepted	2026-04-28	IMS CAP rewrite spec, authentication
0005	bootstrap vs. served route/plugin split	Accepted	2026-04-28	design-decisions §CAP runtime
0006	Authorship vs. ownership vs. contribution semantics	Accepted	2026-07-01	#862, spec

See also

• Design decisions — quick-scan list of every architectural rule the platform runs under
• Postmortems — sibling directory: what went wrong, what we changed
• Design specs — dated design documents (docs/superpowers/specs/, browsable in the repo; excluded from the VitePress build)