release-coordinator (`rc`)¶

Fleet-wide, per-app release serialization and provenance enforcement daemon/CLI for Cloud Run & GCP surfaces.

Mission¶

release-coordinator guarantees atomic deployment serialization, provenance verification, environment isolation, and artifact attribution across the fleet. It prevents deployment races, unverified image promotions, silent configuration striping, and unattributed production revisions.

Quickstart¶

# 1. Install release-coordinator CLI and PreToolUse hook
powershell -File .\install.ps1

# 2. Claim release lock for target app and environment (e.g. qa, prod)
rc claim my-app --env qa --intent deploy --ticket FLT-182

# 3. Record build provenance
rc build my-app --env qa

# 4. Deploy candidate SHA to environment
rc deploy my-app --env qa --sha abc1234

# 5. Promote candidate from QA to Prod (full DeployGate checks against Prod)
rc claim my-app --env prod --intent deploy --ticket FLT-182
rc promote my-app --from qa --to prod

# 6. Release lock when finished
rc release my-app --env prod

Two-Layer Enforcement Architecture¶

Primary Security Layer: GCP IAM & Deployer-SA Impersonation
Per-app deployer service accounts enforce zero-trust identity boundaries (ww-deployer@nifty-condition-503506-j1.iam.gserviceaccount.com for WorkWingman rungs).
Every gcloud invocation issued by rc (Cloud Run, Cloud Build, Cloud Storage, Artifact Registry) executes strictly via --impersonate-service-account=<sa>.
If a rung declares a deployer service account and impersonation cannot be applied or fails, rc fails closed immediately rather than falling back to human developer credentials.
Cloud IAM roles restrict direct service mutation (roles/run.admin, roles/storage.admin, etc.), and execution identities are logged in executedAs provenance/deploy records.
Ergonomic Guardrail Layer: PreToolUse Client Hook (rc hook-pretool)
Intercepts local developer/agent CLI calls (gcloud run deploy, gcloud storage rsync, gcloud artifacts docker tags, docker push, git push).
Demands an active rc claim token; fails-closed if unverified or missing.

Verb Reference¶

Command	Usage / Description
`rc claim`	Acquire lease claim for an app & environment (`--env`, `--intent`, `--ticket`, `--ttl-min`)
`rc release`	Release active claim on `(app, env)`
`rc heartbeat`	Renew active claim TTL
`rc accept`	Accept claim handoff when advancing from queue head
`rc queue`	View current claim holder and queue depth for `(app, env)`
`rc build`	Record build provenance record in `state/builds/<app>/<env>/<sha>.json`
`rc deploy`	Execute full DeployGate (claim check, provenance, ancestry, config diff, post-verify)
`rc promote`	Promote serving digest from `--from` env to `--to` env with full DeployGate validation
`rc publish`	Gated Cloud Storage bucket publish with pre/post generation capturing
`rc tag`	Gated Artifact Registry tagging (refuses mutable non-sha tags on `--add`)
`rc traffic`	Update Cloud Run service traffic splitting (requires attributed target revision)
`rc rollback`	Roll back service to previous known-good revision
`rc status`	Display service status and claim state for `(app, env)`
`rc whose`	Resolve worktree/ticket attribution for a revision
`rc audit`	Audit service for mutable tag pins or unattributed revisions
`rc incident`	Report manual incident or near-miss record
`rc init-state-repo`	Bootstrap git-backed release-coordinator state repository
`rc waive`	Create a config-removal or break-glass waiver
`rc ack-waiver`	Acknowledge pending waiver from a second worktree session

Known-Open Residual Surface List (B1–B8)¶

Surface ID	Surface Description	Primary Mitigation / Control
B1	Direct GCP Console / Web UI Deployments	GCP IAM restrictions (`roles/run.admin`) & Audit Logging
B2	Custom `gcloud` API calls via `curl` / `Invoke-RestMethod`	Service Account OAuth scope boundaries
B3	Out-of-band Docker registry pushes via non-standard tools	Artifact Registry IAM write permissions
B4	Environment variable mutation via Cloud Console	Post-deploy config-diff verification (`rc deploy`)
B5	Unclaimed concurrent deployments across unmanaged tools	LeaseStore RMW state verification
B6	Direct bucket modification via Third-Party S3/GCS tools	Storage IAM policy & ContentPublishRecord tracking
B7	Force-pushing git tracking branches directly	Protected branch rules & GitStateTransport verification
B8	Indirect script-host execution via launchers outside app repos	HookGuard script-host in-repo path detection & GCP IAM boundaries

Team Legend¶

Teammate	AI it runs on	Usual role
Clahadore Jones-Gaffney	Claude (Claude Code)	planning, orchestration, review, hard calls
Cedric "Cody" Jones-Gaffney	Codex / ChatGPT	implementation, second-opinion review
Jenny Jones-Gaffney	Gemini	implementation, research, review
Gronktayvius "Gronk" Jones-Gaffney	Grok	adversarial review, red-teaming

release-coordinator (rc)¶