docs: add ADR-0037 for scheduler attribution design

[bjcoombs]

Summary

• Adds ADR-0037 documenting the decision to use attributed identity for scheduler operations
• Records the rationale for using a separate actorContextKey (not UserIDContextKey) to prevent trust escalation
• Documents Phase A (attributed) vs Phase C (authenticated JWT) design, forward-compatibility, and new scheduler checklist

Changes Made

• docs/adr/0037-scheduler-attribution-design.md - New ADR

Technical Details

The ADR documents:

• Compliance context: SOC 2 CC6.1 and ISO 27001 A.5.16 requirements that motivated the change
• Trust escalation risk: GetUserIDFromContext is used as an auth gate in identity service endpoints; placing scheduler identity in UserIDContextKey would bypass those checks
• Context key separation: actorContextKey (unexported struct type) is structurally distinct from contextKey (UserIDContextKey) - no runtime collision is possible
• Actor injection pattern: Code evidence from cron.go:executeJob and catchup.go:catchUpSchedule
• Audit resolution: changed_by format system:scheduler:{name} distinguishes scheduler from human and anonymous operations
• Phase C path: JWT authentication requires only the gRPC interceptor to set Authenticated=true; no downstream changes needed

Testing

Documentation-only change. No functional changes.

Risk Assessment

Low. Documentation only.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4c973b71-dacd-4fb3-b6c2-679c9755d855

📥 Commits

Reviewing files that changed from the base of the PR and between fcb91c3 and b1a59f5.

📒 Files selected for processing (1)

• docs/adr/0037-scheduler-attribution-design.md

---

📝 Walkthrough

Walkthrough

A new Architecture Decision Record is added that documents the design for injecting scheduler attribution context into background job executions, specifying Actor properties, audit logging behavior, and implementation requirements for schedulers and workers.

Changes

Cohort / File(s)	Summary
Scheduler Attribution ADR docs/adr/0037-scheduler-attribution-design.md	New ADR documenting scheduler attribution design including Actor context injection requirements (auth.WithActor with Type=ActorTypeScheduler), audit changed_by expectations, implementation injection points for cron execution and startup catch-up, and a two-phase plan with future Phase C JWT-verified authenticated identity.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: adding a new ADR document for scheduler attribution design.
Description check	✅ Passed	The description is clearly related to the changeset, explaining the ADR's purpose, technical details, compliance context, and design decisions documented in the new file.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch per-tenant-scheduling--7--attribution-adr

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Claude Code Review

Commit: b1a59f5 | CI: running (security/lint checks passing, CodeQL and CodeRabbit still pending)

Summary

Well-structured ADR that accurately documents the scheduler attribution design implemented in PRs #2151 and #2163. All code references verified against the current codebase — the Actor struct, context key separation, injection points in executeJob/catchUpSchedule, audit fallback chain in GetUserFromContext, and identity service auth gates all match the ADR's descriptions exactly. The decision analysis is thorough and the compliance rationale (SOC 2 CC6.1, ISO 27001 A.5.16) is clearly articulated.

Cross-referenced against ADR-0009 (application-level audit logging) and ADR-0029 (settlement scheduler architecture) — no conflicts. This ADR is a natural extension of both: ADR-0009 established app-level audit, ADR-0029 established the cron scheduler pattern, and this ADR closes the attribution gap between them.

Risk Assessment

Area	Level	Detail
Blast radius	N/A	Documentation only
Rollback	Safe	Can be reverted without impact
Scale	N/A	No runtime changes
Cross-system	N/A	Documents existing implementation
Migration	N/A	No migrations

Findings

Severity	Location	Description	Status
—	—	No actionable findings	—

Questions for the Author

1. 0037-scheduler-attribution-design.md:74 — The phasing jumps from "Phase A" to "Phase C" with no Phase B mentioned. Is Phase B defined elsewhere in the project (e.g. a PRD), or is this a numbering artifact? If intentional, a brief note like "(Phase B is unrelated to scheduler identity)" would prevent confusion for future readers.

Bot Review Notes

No unresolved bot threads found on this PR.

[claude]

ADR is accurate, internally consistent, and compatible with existing ADRs (0009, 0029). All code references verified. See summary comment for details.