Sprint: vault blast-radius tiers

Vision issues

#419 — Vault: blast-radius based approval tiers

What this enables

After this sprint, low-tier vault actions execute without waiting for a human. The dispatcher auto-approves and merges vault PRs classified as low in policy.toml. Medium and high tiers are unchanged: medium notifies and allows async review; high blocks until admin approves.

This removes the bottleneck on low-risk bookkeeping operations while preserving the hard gate on production deploys, secret operations, and agent self-modification.

What exists today

The tier infrastructure is fully built. Only the enforcement is missing.

vault/policy.toml — Maps every formula to low/medium/high. Current low tier: groom-backlog, triage, reproduce, review-pr. Medium: dev, run-planner, run-gardener, run-predictor, run-supervisor, run-architect, upgrade-dependency. High: run-publish-site, run-rent-a-human, add-rpc-method, release.
vault/classify.sh — Shell classifier called by vault-env.sh. Returns tier for a given formula.
vault/SCHEMA.md — Documents blast_radius override field (string: "low"/"medium"/"high") that vault action TOMLs can use to override policy defaults.
vault/validate.sh — Validates vault action TOML fields including blast_radius.
docker/edge/dispatcher.sh — Edge dispatcher. Polls ops repo for merged vault PRs and executes them. Currently fires ALL merged vault PRs without tier differentiation.

What's missing: the dispatcher does not read blast_radius, does not auto-approve low-tier PRs, and does not differentiate notification behavior for medium vs high tier.

Complexity

Files touched: 3

docker/edge/dispatcher.sh — read blast_radius from vault action TOML; for low tier, call Forgejo API to approve + merge the PR directly (admin token); for medium, post "pending async review" comment; for high, leave pending (existing behavior)
lib/vault.sh vault_request() — include blast_radius in the PR body so the dispatcher can read it without re-parsing the TOML
docs/VAULT.md — document the three-tier behavior for operators

Sub-issues: 3 Gluecode ratio: ~70% gluecode (dispatcher reads existing classify.sh output), ~30% new (auto-approve API call, comment logic)

Risks

Admin token for auto-approve: the dispatcher needs an admin-level Forgejo token to approve and merge PRs. Currently FORGE_TOKEN is used; branch protection has admin_enforced: true which means even admin bots are blocked from bypassing the approval gate. This is the core design fork: either (a) relax admin_enforced for low-tier PRs, or (b) use a separate Forgejo "auto-approver" account with admin rights, or (c) bypass the PR workflow entirely for low-tier actions (execute directly without a PR).
Policy drift: as new formulas are added, policy.toml must be updated. If a formula is missing, classify.sh should default to "high" (fail safe). Currently the default behavior is unknown — this needs to be hardened.
Audit trail: low-tier auto-approvals should still leave a record. Auto-approve comment ("auto-approved: low blast radius") satisfies this.

Cost — new infra to maintain

One new Forgejo account or token (if auto-approver route chosen) — needs rotation policy
policy.toml maintenance: every new formula must be classified before shipping
No new services, cron jobs, or containers

Recommendation

Worth it, but the design fork on auto-approve mechanism must be resolved before implementation begins — this is the questions step.

The cleanest approach is option (c): bypass the PR workflow for low-tier actions entirely. The dispatcher detects blast_radius=low, executes the formula immediately without creating a PR, and writes to vault/fired/ directly. This avoids the admin token problem, preserves the PR workflow for medium/high, and keeps the audit trail in git. However, it changes the blast_radius=low behavior from "PR exists but auto-merges" to "no PR, just executes" — operators need to understand the difference.

The PR route (option b) is more visible but requires a dedicated account.

4.1 KiB Raw Blame History