docs(adr): seed ADR home + propose ADR-0001 (CD primitives) and ADR-0002 (auth/secrets) (#167)

[ChrisonSimtian]

Summary

Seeds docs/adr/ as the home for Architecture Decision Records and lands the first two ADRs that frame the v13 CD work — both Proposed, dated 2026-05-24.

File	What
docs/adr/README.md	Locks MADR-lite format, status lifecycle (Proposed → Accepted / Superseded), NNNN-kebab-case-title.md filename convention, and the rule that ADRs are history (corrections happen via new ADRs, not in-place edits).
docs/adr/0001-cd-primitives-attributes-vs-tasks.md	Two-pattern split for CD primitives: attribute → file writer (state in git) vs tasks → REST (state in an external DB), with a sparingly-used hybrid for stable config that lives in an external DB. Validated against GitHub Releases/Environments, Octopus 2019, and the RFC #113 deployment agent.
docs/adr/0002-cross-provider-auth-and-secret-conventions.md	Shared auth/secret convention across providers: canonical SCREAMING_SNAKE from PascalCase field names, [Secret] as the trust marker, plugins receive resolved values only (never raw stores), documented resolution chain (CLI > env var > provider secret > encrypted parameters > Keychain > prompt).

Status

Both ADRs land as Proposed. This PR's review is the vehicle that promotes them to Accepted (or supersedes either with a follow-up ADR) — per the convention codified in the new docs/adr/README.md.

Review checklist (from #167)

ADR-0001 — the two patterns split

• Is the file-shaped vs API-shaped split the right cut? Alternative: collapse everything to tasks, lose the declarative environment story.
• Hybrid attribute ([GitHubEnvironment], [OctopusProject]) capped at stable config, dynamic stuff in tasks — defensible line, or do we need a sharper rule?
• Monorepo fan-out sketch (12 agents + 3 UIs + N libraries) — does the inventory-in-static-fields pattern hold up at that scale?
• Octopus-as-v12-sample-plugin placement — agreed it's the right validation vehicle for the plugin SDK?

ADR-0002 — the resolution chain + naming

• Canonical SCREAMING_SNAKE from PascalCase field name — locking this in across all providers?
• Plugins receive resolved values, never raw stores — agreed this is the right trust boundary for v12 SDK?
• Log masking — ADR flags that no explicit RegisterSensitiveValue / output scrubber appears to be wired to [Secret]. Needs verification before either ADR can move to Accepted. If missing, follow-up framework PR; if present, ADR should cite the file.
• Windows / Linux CredentialStore — macOS-only today. Non-blocking; surface as a separate issue before plugin authors hit it.
• Naming escape hatch ([Parameter("custom_name")]) — sufficient for the cases that matter, or do we need provider-side mapping dictionaries?

Cross-cutting

• Are there CD shapes not sketched that would invalidate either ADR? Specifically: K8s-native (Helm releases, ArgoCD applications), serverless (AWS Lambda, Cloudflare Workers), package-manager promotion (NuGet → public feed gates).

Outcome

• Either ADR → status Accepted via this PR's review, with the date updated.
• Or one/both → status Superseded by NNNN, with the replacing ADR explaining the divergence.

Test plan

• docs/adr/README.md renders on GitHub with the index table pointing at the right files.
• Internal cross-link from ADR-0002 → ADR-0001 resolves to the relative path.
• Reviewer confirms the status flip (Proposed → Accepted, or supersedes).

Closes

• Review ADR-0001 / ADR-0002 — CD primitive patterns + secret conventions #167 (review pass)

🤖 Generated with Claude Code