Checkpoint: Sentry Configuration as Code

Written 2026-08-07 for a session picking this project up cold. It records state, not design — read goal.md, design.md and decision-log.md for the project itself.

Read this first

Document	What it gives you
goal.md	Why the project exists, and the seven rules it started from
design.md	Architecture, safety properties, behaviour. §14 defines the guidance-compliance audit gate
decision-log.md	DQ-001 … DQ-030, with evidence. *The place to look for why.* Several decisions supersede earlier ones; the superseded entries carry notes rather than being rewritten

Repository context lives in infrastructure/knowledge-base/platform-architecture.md (the OperationsManagement element and the generalized IaC vocabulary) and infrastructure/CLAUDE.md.

One-paragraph orientation

Arda’s Sentry alerting was configured by hand in the UI — seven rules across two projects, with overlapping scope, one outright duplicate, and two defects nobody could see. This project makes alerting declared configuration, reconciled by a vendor-neutral engine through snapshot → plan → apply → verify. It establishes OperationsManagement, a fourth platform element for resources that observe and administer the platform rather than run it. Sentry is its first inhabitant.

The migration has already run against the live org. This is not a design-stage project.

Live state — `arda-systems` Sentry org

Eight workflows. Six declared and managed by this tooling, two deliberately untouched.

ID	Name	Notes
3818215	`arda/First seen — prod, arda-frontend [first-seen-prod-fe]`	Slack `#sentry-fe-prod`
3818216	`arda/First seen — prod, platform-be [first-seen-prod-be]`	Slack `#sentry-fe-prod`
3818217	`arda/High — arda-frontend [high-fe]`	Linear `KTLO / FE`
3818218	`arda/High — platform-be [high-be]`	Linear `KTLO / BE`
3818219	`arda/Urgent — arda-frontend [urgent-fe]`	Slack `#sre-production`
3818220	`arda/Urgent — platform-be [urgent-be]`	Slack `#sre-production`
3462179	`Operations fatal startup / uncaught exception`	Unmanaged, retained by decision
3433641	`Notify via Linear`	Unmanaged, disabled, retained by decision

Five rules were retired on 2026-08-07 — 3153115, 3426957, 3190653, 3190649, 3190652 — each verified gone by direct 404.

sentry-config.sh verify reports live state matches declared state. Confirm that before changing anything.

Where the code is


Infrastructure worktree	`projects/sentry-iac-worktrees/infrastructure`, branch `jmpicnic/sentry-iac-drivers`
Documentation worktree	`projects/sentry-iac-worktrees/documentation`, branch `jmpicnic/sentry-iac`

Both clean and pushed as of this checkpoint.

Pull requests

PR	State	Contents
infrastructure#527	Open, ready for review, 44 commits → `main`	The whole implementation
infrastructure#526	Closed	Superseded — its branch is an ancestor of #527’s. Holds the earlier Copilot review, addressed
documentation#159	Open, ready for review, 11 commits → `main`	Goal, design, decision log, Platform Operator persona

Review state on #159: Copilot’s three comments are answered and resolved. Denis Antonioli raised two points — that configuration should be data (YAML, JSON) rather than TypeScript structures, and that the prose was hard to read. The first is deferred to a design/architecture session and Miguel has replied; do not re-litigate it in the PR. The second was acted on — the design went from 1356 to 1019 lines.

Linear

PDEV-1435 — the typescript-coding skill resolves to a documentation page that has never existed. Found during this project, filed rather than fixed here.

This project has no Linear ticket of its own. Do not add ## Closes to either PR.

How to run it

scripts/sentry/sentry-config.sh plan       # read-only; exits 1 if changes pend
scripts/sentry/sentry-config.sh snapshot   # required before any apply
scripts/sentry/sentry-config.sh apply --confirm
scripts/sentry/sentry-config.sh verify

Two things that will waste your time otherwise:

ts-node needs -r tsconfig-paths/register when invoking drivers directly. misc.MultiError resolves through the arda/* path alias, and make ci cannot see the failure because jest and tsc resolve aliases themselves.
1Password biometric prompts time out often on this machine. The token resolves through the SDK as a fallback, so a timeout on op read is not necessarily fatal — check whether the command actually failed.

Pending work

Needs a decision before it can proceed

Enable the deploy workflow. .github/workflows/operations-management-deploy.yml ships disabled per DQ-025, whose two preconditions are now met — the migration has landed and plan verifies empty. Enabling is a two-step edit described in the file header. Once enabled, merge applies to production alerting with no approval step (DQ-023).
Configuration-as-data, per Denis Antonioli’s review. Would affect the whole instances/ layer, not just this project. Awaiting the design session.

Verification still owed

Urgent tier delivery to #sre-production is unproven. The Sentry Slack app is a member and the configuration is correct, but no event has fired into the channel. Sentry accepts a rule pointing at a channel its app cannot post to and then silently drops notifications — the same failure shape as rule 3190653. The probe pattern from DQ-027 settles it in a few minutes: a temporary workflow, one synthetic event, then delete.
The deploy workflow’s path filter has no test. BV-3-06 proposed one; it was not built. Recorded in design §12.

Cleanup requiring UI access

Sentry issues 7655326314 and 7657516175 — probe artifacts, both set to ignored. Deleting them needs event:admin, which the tooling token lacks.
Linear project [IAC PROBE] DQ-017 and its two canceled issues, PDEV-1421 and PDEV-1422. No MCP operation exists for project deletion.

Both are recorded in the decision log’s probe-artifact table.

Known gaps, deliberately left

A stale pinned reference has no recovery path. Identity is the tier key in the workflow name (DQ-029). If someone renames a managed workflow in the Sentry UI so its key is lost, the tool treats it as unmanaged-orphan and recreates the declared one, leaving a duplicate. Accepted: “we will trust that this kind of drift will not happen.”
Plan output shows raw detector ids, not symbolic names. Fixing it well needs a value-renderer hook on formatPlan rather than a Sentry import into the vendor-neutral engine.

Things found outside this project’s scope

Fixed here because they were one-line repairs to live safety nets, and worth knowing about:

corporate-drift and external-resources-drift could never report a failure. if: outcome == 'failure' has success() implied, so the issue-opening step was skipped in exactly the case it exists for. corporate-drift had failed twice, silently, over months.
The lint glob excluded five source files. grep -v .d.ts has an unescaped dot, so anything ending d.ts was skipped — one file carried 77 violations on main.

Conventions this project established

Worth knowing before editing, because they are enforced and non-obvious:

arda/ is a reserved namespace. A hand-made rule using the prefix and declaring no matching key will be proposed for deletion.
Tier keys are immutable. Renaming tierName is an update; changing a key means a different tier, and the old workflow is deleted.
Snapshots are committed under infrastructure/snapshots/, per DQ-006. Three exist, one per apply, and they are the rollback path.
The audit in design §14 is a gate, not a formality. It ran once and produced thirteen findings, all closed. Re-run it with fresh eyes if the branch grows substantially before merge.