docs: ADR-002 least-privilege CDK bootstrap policies

[scottschreckengaust]

Stack position

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

Prior (PR 1 / #130): ADR framework + ADR-001 stacked pull requests methodology

This PR: ADR-002 recording the design decisions for the bootstrap policies work

Remaining (7 PRs): policies as TypeScript, bootstrap template, resource-action-map, CDK Aspect, preflight validator, CI integration, documentation updates

Summary

Records the "why" behind all major design choices from RFC #120:

• Why policies as code (not documentation-only)
• Why triple-layer versioning (semver + hash + action-set)
• Why two-layer preflight validation (Aspect + live validator)
• Why cdk/src/bootstrap/ (agent routing, testability, co-location)
• Why custom bootstrap template (single-command operator experience)
• Why stacked PRs for delivery (references ADR-001)

Changes

File	Purpose
docs/decisions/002-least-privilege-bootstrap-policies.md	ADR-002 source
docs/src/content/docs/decisions/002-least-privilege-bootstrap-policies.md	Generated Starlight mirror

Test plan

• astro check — 0 errors
• Playwright visual verification — page renders correctly in Starlight SPA
• Pre-commit hooks pass
• CI build passes

Closes #121

🤖 Generated with Claude Code

[scottschreckengaust]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

[scoropeza]

Nice ADR — the existing-artifact claims (PR #46, DEPLOYMENT_ROLES.md, the "7 iterations / 36 CloudTrail actions" provenance, the three policy names) all check out verbatim against the current docs, and the Starlight mirrors regenerate cleanly.

One ask before merge: a few artifacts in the Decision section are written in present indicative even though they don't exist yet on main and only land in later PRs of the stack. A reader who picks up the ADR mid-stack (or after merge but before all 8 sub-issues land) can't tell shipped state from design intent. Specifically:

• docs/decisions/002-least-privilege-bootstrap-policies.md:21 — "Policies as typed TypeScript code in cdk/src/bootstrap/" — directory doesn't exist yet.
• docs/decisions/002-least-privilege-bootstrap-policies.md:41 — "CDK Aspect (synth-time) — runs during mise //cdk:synth, visits every CfnResource, looks up required actions in a resource-action-map" — the Aspect and the resource-action-map don't exist yet.
• docs/decisions/002-least-privilege-bootstrap-policies.md:42 — "mise //cdk:preflight" — task doesn't exist in cdk/mise.toml.
• docs/decisions/002-least-privilege-bootstrap-policies.md:46 — "Operators run mise //cdk:bootstrap to provision least-privilege roles in a single command" — the task exists but today still runs vanilla npx cdk bootstrap, not the custom template.

Two options for fixing — either works:

Option A (lightest touch): add one line under Status like:

Implementation tracked in RFC #120; artifacts referenced below land progressively across the 8-PR stack and are not yet present on main.

Option B (clearer per-item): tag each forward-looking artifact with (proposed) or rephrase to "will live in" / "will run during", e.g.:

Policies as typed TypeScript code in cdk/src/bootstrap/ (proposed location, lands in PR N of #145)

Also a small process question on the ADR-001 amendment (docs/decisions/001-stacked-pull-requests.md:94-104): the README says "to change an accepted decision, write a new ADR that supersedes it — do not edit the original." This change reads as a clarification of existing intent rather than a reversal, so I think it's fine, but a sentence in the PR description noting that interpretation would close the loop for future ADR readers.

Non-blocking nit: in References, ADR-001 could be a relative link (./001-stacked-pull-requests.md) so it renders clickable in the Starlight site.

[scottschreckengaust]

Addressed in 381fb00:

Option A + B combined:

• Added **Implementation:** line under Status: "Tracked in RFC RFC: Least-privilege CDK bootstrap policies as code (with preflight validation) #120; artifacts referenced below land progressively across the 8-PR stack and are not yet present on main."
• Tagged each forward-looking artifact with its landing issue: (lands in #122), (lands in #125), etc.
• Custom bootstrap template section uses future tense ("will be generated", "will run")

ADR-001 amendment note: Covered in the commit message — this is a clarification of existing intent (the retarget/rebase protocol that was already implied by "early PRs can merge and ship"), not a reversal. Treated as additive refinement per the README lifecycle ("to change an accepted decision, write a new ADR" applies to reversals, not clarifications).

Nit fixed: ADR-001 reference is now a relative link ./001-stacked-pull-requests.md.