docs: establish ADR framework and ADR-001 stacked pull requests

[scottschreckengaust]

Stack position

PR 1 of 4 for #145 — Least-privilege CDK bootstrap policies as code

Prior: (none — this is the first PR in the stack)

This PR: ADR framework + ADR-001 stacked pull requests methodology

Remaining (8 PRs): ADR-002 least-privilege decision record, policies as TypeScript, bootstrap template, resource-action-map, CDK Aspect, preflight validator, CI integration, documentation updates

Summary

• Establishes docs/decisions/ as the normative location for Architecture Decision Records
• Writes ADR-001: stacked pull requests methodology (position statements, branch targeting, size guidelines, rebase discipline)
• Updates AGENTS.md routing table for agent discoverability
• Adds "Decisions" section to Starlight docs sidebar
• Wires docs/decisions/ into the sync script for automatic mirroring

Changes

File	Purpose
docs/decisions/README.md	ADR process: template, numbering, lifecycle
docs/decisions/001-stacked-pull-requests.md	ADR-001: stacked PR methodology
AGENTS.md	Routing table entry for docs/decisions/
docs/astro.config.mjs	Sidebar: "Decisions" section (collapsed, autogenerated)
docs/scripts/sync-starlight.mjs	Mirror decisions/ → Starlight
docs/src/content/docs/decisions/*	Generated mirrors (do not edit)

Test plan

• astro check — 0 errors, 0 warnings
• Pre-commit hooks pass (gitleaks, eslint, docs sync, astro check)
• CI build passes (docs sync mutation check)

Closes #129

🤖 Generated with Claude Code

[krokoko]

This is a solid first ADR — small scope, hooked into the docs pipeline the way we already do guides/design, and ADR-001 is concrete enough to actually use on stacks like #145.

What I like

Good split: docs/design/ for how the system works, docs/decisions/ for durable why / process choices.
ADR-001 is actionable (position statements, branch topology, size targets, rebase rules, blocked by / blocking, when not to stack).
Nice that review feedback landed (optional “Next”, no of {M}, parent issue as source of truth).
This PR practices what it preaches with the stack position block for #145.
Nits / follow-ups (fine in this PR or a quick follow-up right after merge):

Merge model — There’s a small tension between “PR N targets N−1’s branch, tip merges to main” and “early PRs can merge and ship while later ones are in review.” Worth one explicit paragraph on our default (classic stack vs trunk slicing) and what to do when PR1 merges early (retarget/rebase).

Infra stacks — “Deployable without breaking” is tough for multi-PR CDK/IAM (#120 / #145). Maybe call out an exception: synth + tests OK on early slices, feature flags / no-op states, or “deploy gate” on a named PR.

When to stack — “4+ files” vs “<200 lines” can disagree; a one-liner that review time / blast radius drives the call (not file count alone) would help.

Design vs ADR — Short note in docs/decisions/README.md so we don’t end up with two constitutions when ADR-003+ land: design = shape/interfaces/detail; ADR = cross-cutting choices; supersede via new ADR.

Plumbing — AGENTS.md “Common mistakes” could mention docs/decisions/; optional link from CONTRIBUTING.md.

Big picture: I’d merge this first as governance for #145 and the ADR train — just want merge semantics and infra deployability clarified before we treat this as gospel.

Happy to approve once (1) and (2) are addressed here or in an immediate follow-up.

[scottschreckengaust]

Thanks for the thorough review — addressed (1) and (2) in two separate commits just pushed:

1. Merge semantics (5cc6fe1 → rebased as e0d5ad2~1)
Added §8 Merge semantics covering:

• Default is classic stack (PR N targets N-1)
• On early-merge: retarget remaining PRs to main, rebase, verify CI
• After retarget the remaining stack is shorter, rooted on main
• Guidance for when review feedback invalidates later PRs

2. Infra-stack deployability (6e13739 → rebased as e0d5ad2)
Amended §3 "Self-contained reviewability" with an explicit infrastructure stack exception:

• Validation gate = synth + tests (not deploy)
• Introduced "deploy-gate PR" concept for the stack position block
• Acceptable intermediate states: feature flags, no-op stubs, context-gated constructs

---

Items (3)–(5) from the review are minor and can land in a follow-up or this PR — happy to add them here if you'd prefer before approving.

Update: Addressing (3)–(5) in this PR as well — incoming as a single commit.