Skill: Add a user grant

Turn an access request into a reviewable Pulumi change. Every human principal is
KMS-encrypted, including IAP viewers on Cloud Run services. The change is never
applied here — a second person runs the
review-grant skill, merges, and runs pulumi up.

Read first:

• infra/pulumi/README.md — the marin-iac stacks, the KMS key, and the
  pulumi up prerequisites.
• infra/pulumi/src/iac/gcp/iam_data.yaml header — why human user: principals
  are encrypted and this file is public.

Grant surfaces

Decide which one the request needs before editing anything. A single request can
touch both.

1. Shared project / resource GCP IAM — a role on the hai-gcp-models project, the
   KMS key, a Secret Manager secret, a GCS bucket, an Artifact Registry repo, or
   a service account (who may impersonate it). Lives in
   infra/pulumi/src/iac/gcp/iam_data.yaml, applied by the marin stack in
   infra/pulumi. Each human user:<email> principal is KMS-encrypted once in
   the principals registry; grants reference its opaque human-NNN ID.
   Service accounts, groups, and domains stay plain strings.

2. Deploy-target IAM — runtime, secret, repository, KMS, and IAP grants for
   Echo, EvalDash, Grafana, or Loom. Lives in that target's Python module under
   infra/pulumi/src/iac/gcp/ and is composed into the marin stack.
   Human grants reference the encrypted principal registry by opaque ID.

If you are unsure which surface a request means (e.g. "give Alice access to eval
results" could be an IAP viewer on evaldash, a roles/storage.objectViewer
grant on the record bucket, or both), ask before editing.

Collect the request

You need, per grant:

• Principal — an email for a person, or a serviceAccount:/group:/domain:
  member for automation. Only personal emails get encrypted.
• What they need access to — the specific resource, stated as a capability
  ("read the eval record bucket", "impersonate the ray autoscaler SA") rather
  than a raw role when the requester does not know GCP roles.
• Why / for how long — a one-line justification. If the access is temporary,
  note it; GcpIamCondition can scope a grant with a CEL expiry, but prefer a
  follow-up removal PR unless the requester asks for an expiry.

Translate a capability into the narrowest role that satisfies it. Reuse a role
already present in the relevant shared or deploy-target declaration for the same
resource class before reaching for a broader built-in role. If the request is vague or over-broad, ask for
specifics instead of guessing — an IAM grant is hard to walk back once applied.

Running against a GitHub issue

When invoked to respond to an issue rather than a local prompt:

• Fetch it with gh issue view <n> --repo marin-community/marin --json title,body,comments.
• If the issue is missing a principal, the target resource, or a justification,
  do not guess — post one comment (prefixed 🤖) listing exactly what you
  need, and stop. Do not open a half-specified PR.
• If the request is complete, build the change and open a PR (below), then
  comment on the issue linking the PR.

Register and grant the principal

For project-level roles, update the principal registry and every requested role
in one command:

uv run --package marin-iac --extra deploy \
  python infra/pulumi/iam_principal.py grant alice@openathena.ai \
    --project-role roles/logging.viewer \
    --project-role roles/monitoring.viewer

The command decrypts existing registry entries locally to find and reuse the
person's opaque ID. It encrypts and registers the email once when the person is
new, then writes deterministic YAML. Encryption and lookup need
roles/cloudkms.cryptoKeyEncrypterDecrypter on the marin-iac key (the same
access pulumi up needs).

For a KMS key, secret, bucket, Artifact Registry repository, or service-account
grant, register the principal first:

uv run --package marin-iac --extra deploy \
  python infra/pulumi/iam_principal.py register alice@openathena.ai

The command prints the existing or new human-NNN ID. Add
principal: human-NNN to a shared resource grant or
principals["human-NNN"] to a deploy-target module. Never write a personal
email in plaintext into either declaration, a commit message, or the PR body —
the repo is public.

Make the edit

Project / resource IAM — update iam_data.yaml:

• Find the grant for the target role and resource, or add one. Project
  roles go in project_grants; a bucket/secret/repo/service-account grant goes
  under that resource's entry in buckets / secrets /
  artifact_repositories / service_accounts (add the resource entry if it is
  not there yet).
• Project-role requests are already complete after iam_principal.py grant.
  For other resource grants, add the registered principal: human-NNN
  reference. Add a plain member string for service accounts, groups, domains,
  workload identities, or other automation.

Deploy-target or IAP grant — add the registered principals["human-NNN"]
reference to the target's iam_grants() declaration under
infra/pulumi/src/iac/gcp/. Plain service-account, group, and domain members can
be added directly.

Verify and open the PR

• ./infra/pre-commit.py --files <edited files> (or --changed-files), fixing
  anything it reports. git add a new file before linting so it is scoped in.

• Do not run pulumi preview/up — a local preview decrypts and prints the
  real emails, and applying is the reviewer's step. CI runs a redacted preview on
  the PR.

• Follow the commit skill to commit, push, and open the PR against main. Add
  the agent-generated label. Title the PR for the capability, not the person:
  [iac] Grant eval-bucket read to a new operator, never the email. The body
  states the resource, the role, and the one-line justification — no personal
  emails. Note in the body that a reviewer should run review-grant, then
  pulumi up on the marin stack.

• Assign the PR to the grant approvers so one of them picks up review-grant:

  gh pr edit <n> --repo marin-community/marin \
    --add-assignee yonromai,ravwojdyla,rjpower