@quantile-co/factory-pi 0.0.0-stage → 0.1.0

package/skills/day-zero-deploy/references/local-state.md

@@ -0,0 +1,267 @@
+# New-installation local state
+
+This is the shared, executable-by-phase runbook for a genuinely new repository
+using Factory's `tf/modules/project/{github,gcp}` and protected reusable
+workflows. Each phase requires separate approval; do not paste the whole document
+into a shell. Inventory the repository, support projects, buckets, WIF and
+local/remote state before any mutation. If any installation exists, stop and
+adopt its state rather than bootstrap again.
+
+## 1. Identity and inputs
+
+Use the pinned direnv shell; ordinary entry is credential-free.
+Do not run protected Plan/Apply while bootstrapping: their CI inputs are not ready.
+Keep credentials in the process environment, not Nix attributes or shell history.
+Google CLI login, ADC, the operator's GitHub login and the provider PAT are distinct.
+Read the approved billing account, parent folder and bucket location from the
+concrete Terraform root. Verify access to those exact resources; do not substitute
+Factory's values for a different installation. Reusable modules still accept
+caller-selected values, but shared workflows do not supply billing/folder overrides.
+Export local `TF_DIR` from the repository task/app's mapping of the workflow's
+logical `--tf-layer`. The repository owns its directory and existing backend prefix.
+Shared YAML does not prescribe either value.
+Define reviewed `project_owners` and `project_members` locals in the concrete
+Terraform root, pairing `gcp_email` with `gh_username`; use `[]` for no members.
+Confirm each pair with its owner. Project emails into GCP and usernames into
+GitHub. There are no runtime roster overrides or Actions owner lists. Members
+receive repository write access only, with no added GCP or WIF grants. Names
+describe project roles, not direct GCP Owner grants. See the [configuration contract](../../deploy/references/configuration.md).
+
+```sh
+set -euo pipefail
+set +x
+umask 077
+
+# One-time Day Zero for the explicitly selected owner/repository. Publish the
+# reviewed repo on main first (use a PR if required); confirm its actual Check
+# status. Plan and Apply are manual-only; wait until prod is provisioned.
+# Stop if this root already has local/remote state or a support project; adopt
+# that state instead. Run in the repo's pinned direnv shell; verify project
+# creator and billing access to the selected folder/account, not assumptions
+# about a different repository's organization or credentials.
+
+# Authenticate locally and check the operator-supplied inputs.
+: "${TF_DIR:?set the reviewed repository Terraform root}"
+gcloud auth login
+gcloud auth application-default login # select the same Google account
+: "${GCP_WIF_POOL:?set the Q0 GitHub WIF pool resource path}"
+: "${GCP_WIF_PROVIDER:?set the Q0 quantile-co GitHub WIF provider path}"
+: "${GH_REPO_TOKEN:?load a repository-scoped token from a secure local source}"
+
+# Map public names to Terraform inputs; keep the GitHub token out of TF_VAR_*.
+export TF_VAR_gcp_wif_pool="$GCP_WIF_POOL"
+
+gh auth status # operator's GitHub CLI login, not the provider token
+: "${GH_REPO:?set the intended owner/repo from an approved secure context}"
+# Ignore the selector when verifying the checkout's own repository.
+repo=$(env -u GH_REPO gh repo view --json nameWithOwner --jq .nameWithOwner)
+test "$GH_REPO" = "$repo"
+REPO_NAME=${repo#*/}
+export GITHUB_TOKEN="$GH_REPO_TOKEN" # provider credential only for local Terraform
+export REST_API_BEARER="$GH_REPO_TOKEN" # REST provider uses the same runtime token
+# Verify the existing pool maps main_branch_repository_actor_id and the
+# provider accepts this repository's owner. Do not impersonate Q0 break-glass.
+
+```
+
+## 2. Local seed and imports
+
+Confirm no existing installation or backend initialization. Local file absence
+alone is not sufficient. Approve each import separately; inspect other existing
+resources before creating anything.
+
+```sh
+# Start with local state: the bucket does not exist yet.
+test ! -e "$TF_DIR/backend_override.tf"
+test ! -e "$TF_DIR/terraform.tfstate"
+unset TF_DATA_DIR TF_WORKSPACE
+printf 'terraform {\n  backend "local" {}\n}\n' > "$TF_DIR/backend_override.tf"
+tofu -chdir="$TF_DIR" init -input=false -lockfile=readonly
+
+# The repository already exists. Import it ONLY when it has no state address.
+tofu -chdir="$TF_DIR" import module.gh.github_repository.self "$REPO_NAME"
+tofu -chdir="$TF_DIR" plan
+
+# Review existing repo settings, the observed required Check context, and all changes.
+# Import any other existing resources before approving a fresh local plan.
+```
+
+After separate bootstrap Apply approval, inspect the interactive plan again
+before confirming it. This local bootstrap exception is not the ordinary CI path.
+
+```sh
+tofu -chdir="$TF_DIR" apply
+```
+
+## 2a. Out-of-band project deletion lien
+
+After the new project's approved local Apply, protect the state project from
+accidental deletion **outside Terraform**. The lien is not a Terraform resource,
+import, state address, or CI task. Use the operator's authenticated `gcloud`
+identity, which must have `resourcemanager.projects.updateLiens` on the project
+(for example, `roles/resourcemanager.lienModifier`); listing also requires
+`resourcemanager.projects.get`. Google CLI authentication is separate from the
+ADC used by Terraform. Do not grant these permissions or impersonate Q0
+break-glass as an implicit part of bootstrap. Stop for separate authorization
+if the selected identity lacks access.
+
+Obtain the project ID from the applied local state, verify it is the intended
+new project, and inspect existing liens before creating anything. If an
+appropriate deletion lien already exists, stop rather than create a duplicate.
+The read, credential choice, creation, and verification are separately approved
+operations; do not run this block as one automated script.
+
+```sh
+GCP_PROJECT_ID=$(tofu -chdir="$TF_DIR" output -raw gcp_project_id)
+: "${GCP_PROJECT_ID:?verify the new state project ID}"
+gcloud config get-value account
+# After read-only inspection is approved:
+gcloud alpha resource-manager liens list --project="$GCP_PROJECT_ID" --format=json
+# Only after separately approving creation for this exact project:
+gcloud alpha resource-manager liens create \
+  --project="$GCP_PROJECT_ID" \
+  --restrictions=resourcemanager.projects.delete \
+  --reason="Protect this project from deletion." \
+  --origin=operator
+# Verify the returned name, project, origin, reason, and restriction:
+gcloud alpha resource-manager liens list --project="$GCP_PROJECT_ID" --format=json
+```
+
+Using `--impersonate-service-account` and `--billing-project` requires separate
+approval and verified token-creation, lien-modification and quota-project
+permissions. A break-glass account is not the default bootstrap identity.
+Keep the returned lien name in private operator records, never Git or Terraform
+state. Do not remove the lien during normal state migration, CI handoff, or
+Terraform teardown. An exceptional removal requires separate approval for the
+**exact** lien name: inspect the project's liens again, then run
+`gcloud alpha resource-manager liens delete "$GCP_LIEN_NAME"` for only that
+verified name. Never bulk-delete the project's liens.
+
+## 3. State migration
+
+Authorize migration separately. Verify the output bucket and preserve the state
+backup privately. Move this same lineage; never reset state or force-copy over
+an existing backend. Stop if the post-migration plan is not clean.
+
+```sh
+# Move that same local state to its new, versioned GCS bucket.
+GCP_TF_STATE_BUCKET=$(tofu -chdir="$TF_DIR" output -raw gcp_tf_state_bucket)
+GCP_PROJECT_ID=$(tofu -chdir="$TF_DIR" output -raw gcp_project_id)
+cp "$TF_DIR/terraform.tfstate" "$TF_DIR/terraform.tfstate.pre-gcs"
+rm "$TF_DIR/backend_override.tf"
+tofu -chdir="$TF_DIR" init -migrate-state -lockfile=readonly \
+  -backend-config="bucket=$GCP_TF_STATE_BUCKET" \
+  -backend-config="prefix=repository/prod"
+tofu -chdir="$TF_DIR" state list
+tofu -chdir="$TF_DIR" plan # expect no changes; keep the ignored backup securely until verified
+unset GITHUB_TOKEN # gh run watch cannot use the Terraform fine-grained PAT
+unset REST_API_BEARER
+```
+
+## 4. CI configuration
+
+Verify main/prod restrictions, existing WIF/IAM rules and the Namespace runner.
+Confirm `CACHIX_AUTH_TOKEN` is available to the protected workflow steps; do not
+print or recreate existing secrets. Approve variable and secret changes before
+running the following commands.
+
+```sh
+# Provision nonsecret repository variables for CI.
+: "${GH_REPO:?use the same verified owner/repo as the local seed}"
+gh variable set GCP_WIF_POOL --repo "$GH_REPO" --body "$GCP_WIF_POOL"
+gh variable set GCP_WIF_PROVIDER --repo "$GH_REPO" --body "$GCP_WIF_PROVIDER"
+gh variable set GCP_PROJECT_ID --repo "$GH_REPO" --body "$GCP_PROJECT_ID"
+gh variable set GCP_TF_STATE_BUCKET --repo "$GH_REPO" --body "$GCP_TF_STATE_BUCKET"
+
+# Verify prod permits ONLY main, not tags, before adding secrets.
+printf '%s' "$GH_REPO_TOKEN" | gh secret set GH_REPO_TOKEN --repo "$GH_REPO" --env prod
+
+```
+
+## 5. CI handoff
+
+Read [Plan and Apply](../../deploy/references/plan-apply.md). The helper below
+watches a single dispatch; an ambiguous result is not permission to dispatch
+again. It forwards workflow inputs so Apply can select its saved-plan reference.
+
+```sh
+# Both workflows are published but manual-only. Dispatch only after prod is
+# protected, populated, and the remote-state plan above is clean.
+run_and_verify() {
+  output=$(gh workflow run "$@" --repo "$GH_REPO" --ref main 2>&1)
+  printf '%s\n' "$output"
+  url=$(printf '%s\n' "$output" |
+    grep -Eo 'https://github.com/[^[:space:]]+/actions/runs/[0-9]+' | head -1) || true
+  : "${url:?GitHub did not return a run URL; inspect the dispatched run manually}"
+  run_id=${url##*/}
+  gh run watch "$run_id" --repo "$GH_REPO" --exit-status
+  test "$(gh run view "$run_id" --repo "$GH_REPO" \
+    --json conclusion --jq .conclusion)" = success
+}
+
+# Review a successful CI Plan before dispatching CI Apply.
+run_and_verify plan.yaml -f tf_layer=infrastructure
+```
+
+Download and inspect the GCS plan using the deploy reference. Set `GH_PLAN_REF` to
+its complete `RUN_ID/ATTEMPT/GENERATION` value from the Plan summary, verify its
+exact producing attempt and obtain separate approval for Apply. Preserve the
+same reference after review. A successful Plan is not Apply authorization.
+
+```sh
+: "${GH_PLAN_REF:?select the exact reviewed run/attempt/generation}"
+[[ "$GH_PLAN_REF" =~ ^[1-9][0-9]*/[1-9][0-9]*/[1-9][0-9]*$ ]]
+read -r -p 'Type APPLY after reviewing the successful CI Plan: ' answer </dev/tty
+test "$answer" = APPLY
+run_and_verify apply.yaml -f tf_layer=infrastructure -f "gh_plan_ref=$GH_PLAN_REF"
+```
+
+## 6. Remove bootstrap access
+
+After successful CI handoff, verify WIF and Q0-admin recovery access, and the
+Terraform-managed plan-reader bindings derived from `project_owners[].gcp_email`.
+These grant object
+read access only under `plans/`, not state access or Owner. Verify the operator's
+Google account is included before removing bootstrap access. If read access is
+missing, stop for a separately approved Terraform change; do not retain or
+restore Owner merely to inspect plans.
+
+Inspect IAM first, then obtain separate approval to remove only the bootstrap
+human's direct, unconditional Owner grant. Preserve standing folder
+`projectCreator`, billing `billing.user`, CI/WIF and recovery grants.
+
+```sh
+# After both CI runs succeed, inspect project IAM. Remove ONLY a direct
+# roles/owner grant to the Day Zero human, if project creation gave them one;
+# keep the standing folder projectCreator and billing.user domain grants.
+creator=$(gcloud config get-value account)
+: "${creator:?use the same Google account for gcloud and Terraform ADC}"
+
+# Confirm this active gcloud account is the same human who used ADC above.
+gcloud projects get-iam-policy "$GCP_PROJECT_ID" --format=json
+```
+
+Only after the narrow IAM removal is approved:
+
+```sh
+if gcloud projects get-iam-policy "$GCP_PROJECT_ID" --format=json |
+  jq -e --arg member "user:$creator" \
+    'any(.bindings[]?; .role == "roles/owner" and (.members | index($member)))' >/dev/null; then
+  gcloud projects remove-iam-policy-binding "$GCP_PROJECT_ID" \
+    --member="user:$creator" --role=roles/owner --condition=None
+fi
+# Recheck IAM and CI Plan after handoff. Preserve approved recovery admins.
+# Never commit credentials, local state, .terraform/, or saved plans.
+```
+
+Reinspect IAM and verify private plan read access. Separately authorize a new CI
+Plan to confirm the handoff; do not infer permission to Apply it.
+
+```sh
+gcloud projects get-iam-policy "$GCP_PROJECT_ID" --format=json
+# After separate approval:
+run_and_verify plan.yaml -f tf_layer=infrastructure
+```
+
+Keep private backups until state and recovery are verified. Remove only your own
+no-longer-needed local overrides and scratch; never commit them.

package/skills/deploy/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: deploy
+description: Plan, privately review, apply or troubleshoot existing Factory-module infrastructure through protected reusable workflows and an exact saved-plan GCS generation. Not a new-installation bootstrap.
+---
+
+# Deploy
+
+Read [the configuration contract](references/configuration.md) and
+[the full Plan and Apply procedure](references/plan-apply.md). Work from
+the consuming repository root in its pinned direnv shell. Read `AGENTS.md`,
+`.pi/memory/MEMORY.md`, the current Terraform root, its Factory module
+references, the consumer's shell and task scripts, and the pinned caller **and** called workflows.
+Use the repository task/app's mapping of the workflow's logical `--tf-layer` as
+the reviewed `TF_DIR` for local inspection. Directory and backend-prefix mappings
+belong to the repository, not the shared workflow.
+
+Before planning, review the concrete root's source-owned repository identity,
+paired owners/members, billing account, parent folder and bucket location. Adjust
+source only for the intended installation or explicitly reviewed change; runtime
+variables do not override these values. Existing-installation edits may change
+access or replace resources, so inspect those effects rather than copying defaults.
+
+Skill invocation, a source merge, a green Check or a successful Plan is not
+authorization to Apply. Obtain separate approval for each dispatch, credential
+operation, state repair or retry. Preserve main/prod restrictions, WIF,
+backend locks, shared production concurrency and deletion protection.
+
+Never reseed existing infrastructure or use local Apply to bypass CI. For a
+confirmed new installation use [Day Zero](../day-zero-deploy/SKILL.md). Keep
+credentials, state, plans and provider payloads out of Git and public logs.
+
+On failure inspect the exact run and affected state before recovery. A failed
+or timed-out Apply may have changed resources. Do not replay uncertain writes,
+disable locking, cancel another operator's job or widen permissions.

package/skills/deploy/references/configuration.md

@@ -0,0 +1,138 @@
+# Project configuration contract
+
+## Operator settings
+
+Use the consuming repository's pinned shell and deployment procedures. These
+settings describe the current Factory contract; verify the consumer's configuration.
+A source change, successful Check or Plan never authorizes a deployment.
+
+| Setting | Value and purpose |
+| --- | --- |
+| `GH_REPO` | Verified `owner/repo` for the GitHub CLI; not a basename or numeric ID. |
+| `TF_DIR` | Reviewed Terraform root path: `tf/infrastructure` for Factory, or the consumer's selected root. |
+| `TF_LAYER` | Offered workflow layer: `infrastructure` or `application`; passed as `tf_layer`. |
+| `GCP_WIF_POOL` | Trusted `projects/NUMBER/locations/global/workloadIdentityPools/POOL` resource path. |
+| `GCP_WIF_PROVIDER` | Trusted pool path followed by `/providers/PROVIDER`, used by CI authentication. |
+| `GH_PLAN_REF` | One complete `RUN_ID/ATTEMPT/GENERATION` value from the successful Plan summary; three positive decimal integers without leading zeros. |
+
+The concrete Terraform root owns reviewed `project_owners` and `project_members`
+locals. They are source configuration, not CLI/environment inputs or Actions
+owner rosters. WIF values remain Actions configuration variables; Day Zero supplies
+WIF at runtime before CI exists. `GH_REPO`, `TF_DIR`, `TF_LAYER` and `GH_PLAN_REF`
+are procedure inputs, not additional standing repository variables. The workflow
+bridges `gh_plan_ref` through a step-local `GH_PLAN_REF` variable before passing
+it as a quoted `--gh-plan-ref` argument. Trusted repository variables go directly
+to `--gcp-tf-state-bucket` and `--gcp-wif-pool`. Only the credential uses Commander
+`.env()`; the plan-reference bridge keeps input data out of shell source. Native Actions repository/run/attempt IDs,
+runner scratch and summary paths are read directly, not repeated as CLI flags.
+Shared templates offer both layer jobs; `tf_layer` selects one per dispatch and
+is passed as `--tf-layer` to the repository's pnpm task/app. That repository maps
+the layer internally to its directory and existing backend prefix. Shared YAML
+contains neither directory nor backend-prefix arguments. Set
+`github.workflows.layers` to the supported subset. Factory selects Infrastructure
+only, mapped by its app to `tf/infrastructure` and `repository/prod`. Retain each
+consumer's existing state identity. Plan and Apply must select the same layer.
+
+A synthetic owner-roster example, not identities to deploy:
+
+```json
+[{"gcp_email":"owner@example.com","gh_username":"example-owner"}]
+```
+
+Confirm every pairing. Emails and usernames must each be unique across owners
+and members, ignoring case. Do not infer usernames from emails. Preserve spelling
+for existing Terraform instance keys.
+
+### Credentials stay separate
+
+`GH_REPO_TOKEN` is the repository-scoped provider credential. Use this same name
+for the protected environment secret, workflow environment and Commander `.env()`
+option (`--gh-repo-token`). Workflows prefer environment-based credentials; users
+may choose flags. Only the provider subprocess receives the internal native
+`GITHUB_TOKEN` and `REST_API_BEARER` mappings. The storage subprocess receives
+neither. Keep organization credentials distinct as `GH_ORG_TOKEN` or an
+organization-qualified name such as `GH_QUANTILE_CO_ORG_TOKEN`; do not combine
+privileges to standardize names. The operator's GitHub CLI login remains separate.
+`CACHIX_AUTH_TOKEN` remains a separate workflow secret. Google CLI login, ADC
+and CI WIF are distinct authentication contexts. Keep credentials out of Git,
+Terraform inputs, Nix values and public logs.
+
+### Concrete values are not overrides
+
+Factory's `tf/infrastructure/main.tf` holds its approved billing account, parent
+folder and bucket location. Billing/folder IDs identify resources; they do not
+authorize access or charges. Publishing them still reveals account/hierarchy
+metadata. Verify the deployed values and approve publication for each concrete
+root; never copy private consumer configuration into public Factory.
+
+Shared workflows and Day Zero do not supply billing/folder environment
+variables. Reusable GCP module parameters `billing_account`, `folder_id` and
+`tf_state_location` remain configurable for other roots. A new repository chooses
+its own approved values; it does not inherit Factory's installation identity.
+
+## Generated identifiers
+
+Do not invent new identifiers for an existing installation. Record generated
+project/bucket values as CI variables only after verifying the intended resources.
+
+| Source | Consumer or meaning |
+| --- | --- |
+| `module.gcp.project_id` → root `gcp_project_id` | `GCP_PROJECT_ID` for CI authentication. |
+| `module.gcp.project_number` | Numeric GCP project identity; distinct from its string project ID. |
+| `module.gcp.tf_state_bucket` → root `gcp_tf_state_bucket` | `GCP_TF_STATE_BUCKET`, the existing backend and saved-plan bucket. |
+| `module.gh.repo_id` → root `gh_repo_id` | Immutable numeric GitHub ID, also passed to GCP as `gh_repo_id`. |
+| `module.gh.repo_name` | Repository basename within the configured provider owner. |
+| `module.gh.owner_ids` | Owner usernames mapped to immutable GitHub actor IDs. |
+
+`repo_name` is also the GitHub module's basename input. It is not `GH_REPO`.
+Retain `tf_state` on the bucket: it identifies purpose, not a transport mechanism.
+Keep role qualifiers where multiple projects coexist; do not collapse distinct
+project identities merely to shorten names.
+
+## Platform roles and native adapters
+
+The Terraform root owns `local.project_owners` and `local.project_members`. It directly
+projects emails into the GCP module and usernames into the GitHub module; there
+is no intermediary identity module. Each platform module owns its permissions:
+
+- GitHub owners are looked up for `owner_ids`; the lookup itself grants no
+  repository or organization membership. Members receive repository write
+  access (`push`), not administration.
+- GCP owners receive object-read access only under `plans/`, not state access.
+  `gh_repo_id` and `gh_owner_ids` retain main/repository/actor-scoped WIF.
+  There is no direct human project Owner grant.
+- Members receive no added GCP or WIF grants.
+  Platform modules reject overlap between owner and member identities.
+
+The workflow CLI neither reads nor forwards owner/member rosters. Terraform
+projects the source records directly into its platform modules. YAML has no owner
+or triggering-actor list checks; dispatch access follows repository/environment
+policy, while the existing WIF/IAM configuration restricts GCP access. Review parses
+`GH_PLAN_REF` internally and selects its exact GCS generation; Apply receives the
+same reference without replanning. Review and Apply require separate approval.
+
+These grants do not revoke inherited organization, team or GCP permissions.
+Review effective access, including collaborator removal when a member leaves
+or changes roles. Repository writers remain within the existing branch-protection
+and trusted-workflow model.
+
+Use `GH_` / `gh_` and `GCP_` / `gcp_` for unscoped Quantile-owned names. Keep
+`TF_VAR_*`, backend arguments and local plan paths inside adapters or exceptional
+procedures. Preserve native provider/SDK attributes and variables, including
+`repository_id`, `GITHUB_*`, `REST_API_BEARER` and
+`GOOGLE_APPLICATION_CREDENTIALS`. Keep `GH_REPO` unset during independent checkout
+verification, and explicit repository targets on mutations.
+
+Same-named `STRIPE_API_KEY` or `RESEND_API_KEY` inputs in isolated contexts need
+not have equal values or privileges. Qualify credentials only when they coexist;
+never combine privileges to simplify names. There is no member GCP/admin-role
+override or supported local-production Apply shortcut.
+
+## Tool configuration files
+
+Actionlint, clang-format and clang-tidy use native configuration discovery.
+Other wrappers retain explicit paths where they inspect settings or change
+working roots. Retained selectors use `<TOOL>_CONFIG_FILE`; upstream-native
+names stay unchanged. `PREK_CONFIG_FILE` is shared by the Prek and keep-sorted
+adapters. Nix `configFile` options select native templates, not a second policy
+registry. Materialize files into their native locations, not runtime `etc/` paths.

package/skills/deploy/references/plan-apply.md

@@ -0,0 +1,189 @@
+# Plan and Apply
+
+Read the caller's current workflows, the pinned Factory reusable workflows,
+the consumer's shell and task scripts, its Terraform root and declared Factory
+Terraform module sources, and `nix/github/workflows/default.nix` from the pinned
+Factory revision, plus its importable `packages/github` transport and thin
+`apps/github` CLI. Its package tasks run TypeScript directly with locked `tsx`,
+without a GitHub app/library build. Workflows run `pnpm install --frozen-lockfile`
+immediately before the task in the same run block. Automatic installation is
+disabled in the workspace. The credential uses
+Commander `.env("GH_REPO_TOKEN")`; other inputs are quoted CLI arguments, with
+native provider credential names mapped internally. Native Actions metadata needs no repeated
+flags. Consumers own their task implementations and dependency delivery. Export local
+`TF_DIR` for inspection/exception commands below from the repository task/app's
+mapping of the workflow's logical `--tf-layer`. The repository owns its directory
+and existing backend prefix, not the shared YAML.
+The library gives custom callbacks the exact saved-plan path directly rather than
+an ambient `TF_PLAN_FILE`.
+Changing this source directory does not change the backend bucket or prefix.
+Use the pinned direnv shell. Ordinary production changes use protected workflows,
+not local Apply. Validate source without backend access:
+
+```sh
+pnpm run check
+```
+
+## Layout changes on an existing installation
+
+For existing installations, compare the resource addresses in state with this
+repository's modules and any `moved` blocks. Obtain separate
+approval for any one-time address migration. Do not apply a plan that recreates
+or deletes existing resources because of a refactor. When the original bucket
+and existing prefix are retained, this is not a backend migration or a new
+installation. Some installations also intentionally retire resources;
+review those deletions individually. No compatibility blocks or state moves
+run automatically.
+
+## Local OpenTofu (exceptional, separately authorized)
+
+Ordinary production Plan/Apply must use protected workflows. If an operator
+explicitly authorizes a local exception, enter the pinned shell and supply
+provider credentials at runtime from an approved source. Set
+`TF_PLAN_FILE` to an absolute private path outside Git and the Nix store;
+keep its bytes restricted for review. Use the existing bucket and prefix:
+
+```sh
+set -euo pipefail; set +x; umask 077
+: "${GCP_TF_STATE_BUCKET:?Set the existing bucket}"
+: "${TF_BACKEND_PREFIX:?Set the existing prefix}"
+: "${TF_PLAN_FILE:?Set an absolute private plan path}"
+case "$TF_PLAN_FILE" in /*) ;; *) exit 1 ;; esac
+: "${TF_DIR:?Set the reviewed Terraform root}"
+tofu -chdir="$TF_DIR" init -input=false -lockfile=readonly \
+  -backend-config="bucket=$GCP_TF_STATE_BUCKET" \
+  -backend-config="prefix=$TF_BACKEND_PREFIX"
+test ! -e "$TF_PLAN_FILE"
+tofu -chdir="$TF_DIR" plan -input=false -no-color -out="$TF_PLAN_FILE"
+```
+
+A *separately approved* local Apply uses the exact reviewed saved bytes, with
+fresh runtime credentials and the same backend configuration. Never replan
+in place of Apply:
+
+```sh
+set -euo pipefail; set +x; umask 077
+: "${GCP_TF_STATE_BUCKET:?Set the reviewed bucket}"
+: "${TF_BACKEND_PREFIX:?Set the reviewed prefix}"
+: "${TF_PLAN_FILE:?Set the reviewed absolute private plan path}"
+case "$TF_PLAN_FILE" in /*) ;; *) exit 1 ;; esac
+test -s "$TF_PLAN_FILE"
+: "${TF_DIR:?Set the reviewed Terraform root}"
+tofu -chdir="$TF_DIR" init -input=false -lockfile=readonly \
+  -backend-config="bucket=$GCP_TF_STATE_BUCKET" \
+  -backend-config="prefix=$TF_BACKEND_PREFIX"
+tofu -chdir="$TF_DIR" apply -input=false "$TF_PLAN_FILE"
+```
+
+## 1. Confirm context
+
+From a clean checkout of the current protected main revision:
+
+```sh
+set -euo pipefail
+set +x
+umask 077
+: "${TF_DIR:?Set the reviewed Terraform root}"
+: "${TF_LAYER:?Select an offered infrastructure or application layer}"
+: "${GH_REPO:?Set and verify the intended owner/repo before any dispatch}"
+repo=$(env -u GH_REPO gh repo view --json nameWithOwner --jq .nameWithOwner)
+test "$GH_REPO" = "$repo"
+SHA=$(git rev-parse HEAD)
+test -z "$(git status --porcelain)"
+test "$SHA" = "$(gh api "repos/$GH_REPO/git/ref/heads/main" --jq .object.sha)"
+gh run list -R "$GH_REPO" -w check.yaml -c "$SHA" \
+  --json databaseId,headSha,status,conclusion,url
+gh run list -R "$GH_REPO" --limit 10 \
+  --json databaseId,workflowName,headSha,status,conclusion,url
+```
+
+Check may have run on the source branch before fast-forwarding main. Confirm its
+exact SHA, not just the branch label. Inspect current production activity; never
+cancel another operator's job. Verify main/prod restrictions, WIF and IAM,
+the effective state bucket and backend prefix, including caller inputs and runtime
+environment overrides. Factory defaults to `repository/prod`; consumers may retain
+another existing prefix. Check the called workflow's `factory-production`
+concurrency and any caller guard.
+The Terraform root's reviewed paired records are the source of truth for platform
+permissions, including plan-reader emails and immutable deployment actor IDs.
+Neither YAML nor the CLI reads an Actions owner roster. The YAML owner and
+triggering-actor conditions are intentionally absent; repository/environment
+policy and the existing WIF/IAM rules govern access.
+The GCP module grants humans object-read access only under `plans/`, not direct
+project Owner access. Members must not be substituted into owner grants.
+See the [configuration contract](configuration.md) for identity and role requirements.
+The operator's GitHub CLI login is separate from the provider PAT;
+do not let `GITHUB_TOKEN` or `GH_TOKEN` select the wrong credential.
+
+Plan and Apply receive provider credentials and the Cachix token only at runtime.
+Never copy those values into Terraform inputs, artifacts, source or Nix values.
+
+## 2. Plan
+
+After approval for this dispatch only:
+
+```sh
+gh workflow run plan.yaml -R "$GH_REPO" --ref main -f "tf_layer=$TF_LAYER"
+```
+
+Capture its run ID and attempt from the result; an ambiguous dispatch is not
+permission to dispatch again. Watch that exact run and require success, including
+post-steps. Set `GH_PLAN_REF` to the complete `RUN_ID/ATTEMPT/GENERATION` value
+from the Plan step summary; do not reconstruct it from separately chosen parts.
+
+No plan or diagnostic is uploaded to GitHub. The saved plan and its private
+Plan log stay in GCS under `plans/REPOSITORY_ID/RUN_ID/ATTEMPT/saved-plan/`.
+An authorized reader needs access to those objects independently of CI's WIF
+identity. Manage missing read access through the reviewed project role policy and
+a separately approved Terraform Apply, not a manual IAM grant, Owner access or
+public upload. Do not promote someone to a project owner solely to enable review.
+An existing authorized reader must inspect the initial access-grant plan; setting
+the input alone grants nothing.
+
+## 3. Inspect the plan privately
+
+Follow [the saved-plan review procedure](saved-plan-review.md) in full using
+`GH_PLAN_REF`. It parses the components internally and verifies the producing
+attempt; confirm its source and effective bucket before reviewing the plan.
+Preserve that exact reference for the separately approved Apply; review does
+not authorize it.
+
+## 4. Apply
+
+After separate approval for this exact run/attempt/generation:
+
+```sh
+: "${GH_PLAN_REF:?Set the exact reviewed run/attempt/generation}"
+[[ "$GH_PLAN_REF" =~ ^[1-9][0-9]*/[1-9][0-9]*/[1-9][0-9]*$ ]]
+gh workflow run apply.yaml -R "$GH_REPO" --ref main \
+  -f "tf_layer=$TF_LAYER" -f "gh_plan_ref=$GH_PLAN_REF"
+```
+
+Select the same layer as the reviewed Plan. Each dispatch runs only that layer's
+job, even when both jobs are available. If Infrastructure changes inputs consumed
+by Application, apply Infrastructure first, then create and review a new
+Application Plan; do not reuse the earlier Application plan.
+
+Apply downloads that exact GCS plan generation into a local file, then runs
+OpenTofu Apply without replanning. The protected Apply gate and the operator's
+review of the selected reference are the authorization boundary. OpenTofu's
+backend state locking and stale-plan checks remain active. If the source has
+changed, the plan is missing, or the state has advanced, stop and review a new
+Plan rather than applying a different object. GCS lifecycle cleanup is
+asynchronous; do not assume old objects have already been deleted.
+
+Watch the exact Apply run. A failed Plan stores a create-only `plan.log` under
+`gs://$GCP_TF_STATE_BUCKET/plans/$GITHUB_REPOSITORY_ID/$GITHUB_RUN_ID/$GITHUB_RUN_ATTEMPT/`.
+A failed Apply stores `apply.log` under
+`gs://$GCP_TF_STATE_BUCKET/plans/$GITHUB_REPOSITORY_ID/apply/$GITHUB_RUN_ID/$GITHUB_RUN_ATTEMPT/`.
+Fetch diagnostics only as an authorized reader into restricted scratch outside Git
+and the Nix store. Provider output is redirected to local private logs, not
+printed in the workflow. Diagnostic upload can
+itself fail; absence is not proof that no infrastructure changed. GCS cleanup
+follows the plans-prefix lifecycle.
+
+Failure or timeout may follow a partial write: inspect state and completed
+operations before proposing recovery. Do not rerun Day Zero, force-unlock an
+active backend, replay an uncertain Apply or run workflows solely to warm caches.
+Remove only your own private scratch after verification; preserve uncertain
+results and backups securely until recovery is understood.