cpflow 5.2.0 → 6.0.0.rc.0

data/docs/ci-automation.md

@@ -23,8 +23,8 @@ End-to-end rollout in one view:
 
 1. `cpflow github-flow-readiness` — exits non-zero if the repo is not ready to deploy.
 2. `cpflow generate` — creates `.controlplane/` if missing.
-3. `cpflow generate-github-actions` — adds `cpflow-*` workflow wrappers. Review-app, staging, cleanup, and helper workflows call upstream reusable workflows; production promotion is a normal caller-repo job so it can own the protected production Environment.
-4. Configure the GitHub [repository secrets and variables](#required-github-repository-settings) the workflows expect.
+3. `cpflow generate-github-actions` — adds `cpflow-*` workflow wrappers and `.github/actions/cpflow-*` composite actions. Review-app, staging, cleanup, and helper workflows call upstream reusable workflows; production promotion is a normal caller-repo job so it can own the protected production Environment.
+4. Configure the [GitHub Actions secrets and variables](#github-actions-secrets-and-variables) the workflows expect.
 5. Push the branch, then comment `+review-app-deploy` on a PR to spin up a review environment.
 
 AI rollout: copy the [AI rollout prompt](./ai-github-flow-prompt.md) when you want an agent to run this setup. The prompt works whether `cpflow` is already installed or the agent needs to install it first. If `cpflow` is already available in the target repo, `cpflow ai-github-flow-prompt` prints the same prompt with the default app prefix filled in.
@@ -69,6 +69,7 @@ The second command writes namespaced files so they can coexist with an app's exi
 - `.github/workflows/cpflow-deploy-staging.yml`
 - `.github/workflows/cpflow-promote-staging-to-production.yml`
 - `.github/workflows/cpflow-cleanup-stale-review-apps.yml`
+- `.github/actions/cpflow-*` (the local composite actions used by those workflows)
 - `bin/pin-cpflow-github-ref`
 - `bin/test-cpflow-github-flow`
 
@@ -170,15 +171,18 @@ Important points:
   fixed replica count. See
   [Enable Capacity AI for Demo and Starter Staging Apps](tips.md#enable-capacity-ai-for-demo-and-starter-staging-apps).
 
-## Required GitHub Repository Settings
+## GitHub Actions Secrets and Variables
 
-For a normal generated review-app setup, configure one repository secret:
+### GitHub Actions Secrets
 
-- `CPLN_TOKEN_STAGING`: token for the staging/review Control Plane org. Generate it from a Control Plane service account
-  whose policies only allow review/staging CI operations; it must not read production secrets or manage production
-  workloads.
+For a normal generated review-app setup, configure one GitHub Actions secret:
 
-No GitHub repository variables are required for review apps when `.controlplane/controlplane.yml`
+- `CPLN_TOKEN_STAGING`: service-account token scoped to the staging Control Plane org on controlplane.com. Its policies
+  should allow only review/staging CI operations; it must not read production secrets or manage production workloads.
+
+### GitHub Actions Variables
+
+No GitHub Actions variables are required for review apps when `.controlplane/controlplane.yml`
 has exactly one review app entry with `match_if_app_name_starts_with: true` and
 that entry has a `cpln_org`. The inferred values come from that config file:
 the review-app prefix is the app key with `match_if_app_name_starts_with: true`,
@@ -187,7 +191,7 @@ when you need to test a fork or clone against a different Control Plane org,
 choose a different review-app prefix, expose a different public workload, or
 disambiguate generated review-app config:
 
-- `CPLN_ORG_STAGING`: override the staging/review org inferred from `cpln_org`, for example `company-staging`
+- `CPLN_ORG_STAGING`: Control Plane org on controlplane.com for staging and review apps. Overrides the org inferred from `cpln_org`, for example `company-staging`
 - `REVIEW_APP_PREFIX`: override the inferred review-app prefix; required only when multiple review app prefixes exist in `controlplane.yml`
 - `PRIMARY_WORKLOAD`: override the public workload used to discover the public endpoint and do review/production health checks; defaults to `rails`
 - `REVIEW_APP_HEALTH_CHECK_RETRIES`: override review-app health polling attempts; defaults to `24`
@@ -211,7 +215,8 @@ For production promotion, also configure:
 - a GitHub Environment named `production`
 - required reviewers on that environment, limited to the people or team allowed to promote production
 - "Prevent self-review" on that environment, so the person who starts the promotion cannot approve it
-- optionally disable administrator bypass and restrict deployment branches/tags to your protected release branch
+- disable administrator bypass if your organization requires two-person control
+- restrict deployment branches/tags to your protected release branch
 - `CPLN_TOKEN_PRODUCTION` as an environment secret on `production`, not as a repository or organization secret
 - `CPLN_ORG_PRODUCTION` as a production environment variable, for example `company-production`
 - `PRODUCTION_APP_NAME` as a production environment variable, for example `my-app-production`
@@ -324,6 +329,20 @@ the run early instead of deploying an image that cannot boot.
 
 Review apps are different: the generated `+review-app-deploy` workflow creates
 temporary PR apps as needed, including the identity and secret policy binding.
+For an existing review app, each deployment runs
+`cpflow setup-app --refresh-templates` before building and deploying the new
+image. Refresh mode reapplies the configured `setup_app_templates` without
+deleting the GVC or running `hooks.post_creation`, answers template replacement
+prompts noninteractively, preserves each matching workload container's exact
+configured app-image reference even when the app is unhealthy or workloads use
+different image versions, and repairs the configured app and shared-secret
+policy bindings. A missing or invalid workload image uses only an unambiguous
+app image from ready workloads; refresh fails closed rather than selecting the
+registry's newest image. Preserving image references keeps release-phase and
+ordered-deploy gates in control of image rollout; a template failure stops the
+workflow before the image build or deployment. Existing secret templates are skipped
+as whole resources, so refresh neither changes existing values nor adds newly templated
+keys; provision required new keys separately before deployment.
 You still need the shared review-app runtime secret values described by your
 templates, and the staging token must have access to create and update
 review-app GVCs, workloads, images, identities, policies, and secrets in the
@@ -331,12 +350,13 @@ staging org.
 
 If review apps share an existing staging database or another existing secret,
 declare it with `shared_secret_grants` on the review app config entry. The
-deploy workflow runs `setup-app` for new review apps and `deploy-image` for
-image updates; those commands bind or repair the review app identity's `reveal`
-permission on each configured shared policy. The delete and cleanup workflows
-call `cpflow delete`, which removes those bindings as review apps go away. This
-lets one shared database or license secret serve many short-lived review apps
-without granting every review identity access to unrelated app secrets.
+deploy workflow runs `setup-app` for new review apps, refreshes templates for
+existing review apps, and then runs `deploy-image`; those commands bind or
+repair the review app identity's `reveal` permission on each configured shared
+policy. The delete and cleanup workflows call `cpflow delete`, which removes
+those bindings as review apps go away. This lets one shared database or license
+secret serve many short-lived review apps without granting every review
+identity access to unrelated app secrets.
 
 ```yaml
 apps:
@@ -376,7 +396,11 @@ The standard path is:
    references are copied by digest, commit-suffixed tags keep the commit suffix,
    and plain numeric tags remain valid.
 11. Expect production health and rollback readiness polling to require Control
-   Plane `status.ready` and `status.readyLatest` before checking the endpoint.
+   Plane `status.ready` and `status.readyLatest` before checking the standard
+   workload endpoint. If that endpoint is unavailable, as it can be on BYOK
+   locations, the health check waits until every reported deployment location
+   is ready and not deploying, then tries their endpoints sequentially. Each
+   additional location can add up to `curl_max_time` to an attempt.
 
 GitHub only exposes environment secrets to jobs that reference the environment
 after configured protection rules pass. GitHub does not allow a caller job that
@@ -440,18 +464,29 @@ service-account token must remain disposable and scoped to minimum permissions.
 The generated flow uses these defaults:
 
 - same-repository pull requests can update existing review apps automatically on each push; creating the first review app
-  requires either a `+review-app-deploy` comment from a trusted commenter (`OWNER`, `MEMBER`, or `COLLABORATOR`
-  association, regardless of permission level) or a manual workflow dispatch by a repository collaborator with write
-  access. The trusted-commenter gate applies to every `+review-app-deploy` comment, whether or not a review app already
-  exists. Later pushes to a base-repository branch PR redeploy automatically without another approval because the
-  auto-push path (`pull_request` event) has no trusted-commenter check; only the `issue_comment` path does;
+  requires either a `+review-app-deploy` comment from someone whose current repository permission is `write`, `maintain`,
+  or `admin`, or a manual workflow dispatch by a repository collaborator with write access. GitHub's
+  collaborator-permission API resolves comment permissions when the command runs; `read` and `triage` access are not
+  sufficient, and an API lookup failure denies the command. Accepted triggers are recorded in a hidden, bot-authored
+  intent comment before queue admission. The mutating job authenticates the newest marker against its originating
+  Actions run and successful POST-only recording step, then rechecks the manual actor's current permission after it
+  acquires the per-PR queue. Editing or deleting
+  the original command comment therefore cannot reorder accepted work, and a permission revoked while the job waits
+  makes the newest intent fail closed instead of falling back to an older operation. This permission gate applies to every
+  `+review-app-deploy` comment, whether or not a review app already exists. Later pushes to a base-repository branch PR
+  redeploy automatically without another approval because the auto-push path (`pull_request` event) does not use the
+  comment permission gate. The reusable deploy workflow loads generated local actions through `actions/checkout`'s
+  default with no `ref:` override, which resolves to the commit GitHub recorded for the triggering event: the
+  pull-request merge revision for automatic same-repository deploys, the selected ref for manual dispatch, or the
+  default-branch revision for comment triggers. This keeps the wrapper and generated actions synchronized during an
+  upgrade or first-installation PR. Preserve the same-repository caller guard because pull-request workflow and action
+  code run with staging/review credentials;
 - fork pull requests cannot deploy via the generated `pull_request` path because the caller workflow's job-level `if:`
-  condition explicitly skips fork-originated runs. For `issue_comment` events, the caller `if:` restricts commands to
-  trusted author associations (`OWNER`, `MEMBER`, `COLLABORATOR`) but does not check fork status; the fork check for
-  comment events is enforced inside the reusable workflow's source-validation step. These complementary guards cover
-  different axes, so preserve both. A trusted commenter can comment on a fork PR and pass the caller's
-  `author_association` check; the reusable workflow's source-validation step is what blocks that fork head from being
-  deployed. Removing the source-validation guard opens a path to deploy untrusted code with repository-secret access,
+  condition explicitly skips fork-originated runs. For `issue_comment` events, the caller `if:` restricts invocation to
+  the exact command shape; the reusable workflow resolves repository permission before its deploy job runs, then its
+  source-validation step checks fork status before checking out or building PR code. These complementary guards cover
+  different axes, so preserve both. Even a write-authorized comment on a fork PR cannot deploy that fork head.
+  Removing the source-validation guard opens a path to deploy untrusted code with repository-secret access,
   because `issue_comment` events execute with base-repository secret access. Removing the `pull_request` guard still
   lets untrusted fork code into the staging environment even though GitHub withholds repository secrets from fork
   `pull_request` runs. Keep both workflow guards in place because the workflow builds Docker images with repository
@@ -459,13 +494,17 @@ The generated flow uses these defaults:
 - review apps are also deleted automatically when the pull request closes; that PR-close path uses `pull_request_target`
   so it runs in the base-repository context and has repository-secret access for teardown. That is also why you must
   never check out PR or fork code in this job; see the customization guidance below. The PR-close path does not require a
-  trusted commenter. The generated `cpflow-delete-review-app.yml` pins `GITHUB_TOKEN` permissions to the minimum it needs
-  (`contents: read`, `issues: write`, `pull-requests: write`); if you customize this workflow, preserve that
-  `permissions:` block because omitting it can fall back to broader repository defaults;
+  comment permission check. The generated `cpflow-delete-review-app.yml` pins `GITHUB_TOKEN` permissions to the minimum it needs
+  (`actions: write`, `contents: read`, `deployments: write`, `issues: write`, `pull-requests: write`). `actions: write` is used
+  only to redispatch the newest accepted deploy/delete operation when GitHub replaces the corresponding pending run;
+  if you customize this workflow, preserve that `permissions:` block because omitting it can fall back to broader
+  repository defaults;
 - manual workflow dispatch by a repository collaborator can also delete a review app without a `+review-app-delete`
-  comment, and does not require a trusted commenter;
-- trusted comments on fork PRs still do not deploy the fork head; the workflow posts no PR comment in this case. The
-  commenter receives a rocket reaction and the skip appears only in the Actions step summary. Review the fork code
+  comment. It is recorded in the same intent order as comment and automatic triggers, and the actor's current repository
+  permission is rechecked after queue admission;
+- write-authorized comments on fork PRs still do not deploy the fork head; the workflow posts no PR comment or command
+  reaction in this case. The authorization job records no accepted intent, and the skip appears in its
+  `Prepare accepted review app intent` log. Review the fork code
   carefully, then move the change to a branch in the base repository if it needs a generated review app. That build will
   run with repository-secret access;
 - production promotion is manual and uses production environment secrets separately from review and staging.
@@ -478,13 +517,16 @@ generated staging/review org and make that token disposable and unable to access
 The PR-close teardown workflow runs trusted base-branch workflow code with repository secret access so it can delete fork
 PR review apps. The generated `cpflow-delete-control-plane-app` composite action script refuses to call `cpflow delete`
 on any app whose name does not match the review-app prefix. This shell-level guard is effective because the generated
-delete workflow checks out base/default-branch code, not PR or fork code: its repository checkout has no `ref:` override,
-so `pull_request_target` runs use the base branch. If you customize this workflow, never check out PR or fork code in the
-same job as the delete step; doing so could let a PR replace the guard script itself and would also make
-`hooks.pre_deletion` come from the PR's `controlplane.yml`. This is still not a token policy, so use a scoped staging
-service account limited to review/staging operations. A configured `hooks.pre_deletion` command still runs through the
-latest PR-built image on all delete paths: PR-close teardown, `+review-app-delete` comments, manual dispatch, and
-scheduled cleanup. Review-app credentials must remain disposable even during deletion.
+delete workflow loads generated actions through `actions/checkout`'s default with no `ref:` override, which resolves to
+the commit GitHub recorded for the triggering event (`GITHUB_SHA`, the base-branch tip under `pull_request_target`). Its
+separate app checkout has no `ref:` override either, so `pull_request_target` teardown uses base-branch code for both
+paths rather than PR or fork code. If you customize this
+workflow, never check out PR or fork code in the same job as the delete step; doing so could let a PR replace the guard
+script itself and would also make `hooks.pre_deletion` come from the PR's `controlplane.yml`. This is still not a token
+policy, so use a scoped staging service account limited to review/staging operations. A configured
+`hooks.pre_deletion` command still runs through the latest PR-built image on all delete paths: PR-close teardown,
+`+review-app-delete` comments, manual dispatch, and scheduled cleanup. Review-app credentials must remain disposable
+even during deletion.
 
 If you customize the generated `pull_request_target` workflow, never pass `github.event.pull_request.head.sha` or another
 fork-controlled ref to `actions/checkout`, `git fetch`, `git merge`, `git cherry-pick`, or any other step that fetches,
@@ -545,6 +587,18 @@ deploy key scoped to the minimum private dependency access, and never use a pers
 
 ## Generated Workflow Behavior
 
+The deploy and delete workflows share a per-PR concurrency group, but GitHub keeps at most one running and one pending
+member of a group and may replace the pending member without FIFO ordering. Each authorized trigger therefore records a
+hidden `github-actions[bot]` intent marker containing its operation and originating workflow-run identity before it joins
+the queue. Whichever job survives reads the complete marker ledger, authenticates the newest marker against the Actions
+run API and the source run's successful POST-only recording step, revalidates a manual actor's current permission, and either performs that operation or redispatches the matching
+generated workflow on the default branch. Internal redispatches reuse the existing marker only through a bot-owned
+handoff bound to the returned workflow-run ID and the exact successful source dispatch step; the superseded source job
+then stops before mutable work, and values entered manually in the internal handoff field are rejected. This convergence
+covers automatic PR events, manual dispatches, mixed-case comment admission, authorization
+completion in a different order from event creation, and edits or deletion of the original command comment. Invalid,
+forged, missing, or permission-revoked newest intents fail closed and never fall back to older work.
+
 `cpflow-review-app-help.yml`
 
 - Posts a quick reference when a pull request opens, including on fork-based PRs.
@@ -563,26 +617,47 @@ deploy key scoped to the minimum private dependency access, and never use a pers
 - For manual dispatch, provide the PR number; the workflow rejects fork PRs at runtime because it builds Docker images
   with repository secrets.
 - Redeploys an existing review app automatically on later PR pushes.
-- Creates a GitHub deployment and comments with the review URL and logs.
+- Creates a transient, non-production GitHub deployment and comments with the review URL and logs.
 - Leaves PR pushes alone until the first review app is explicitly requested, which keeps demo-app costs down.
+- When that no-app PR path succeeds without building or deploying, writes a prominent `Docker image not built` job
+  summary and returns the reusable-workflow output `image_built=false`. A downstream job can inspect
+  `needs.deploy.outputs.image_built`; a green deploy job with `false` is not Docker-image validation.
+- Repositories that require production-image validation before merge should add a separate required build job when
+  Dockerfile, runtime-version, or dependency files change. The cost-saving review-app path intentionally does not create
+  an app or build an image until `+review-app-deploy` is requested.
 - Supports cost-conscious review apps when paired with one warm replica, Capacity AI, and a disabled autoscaling
   metric for public demos, starter staging apps, and long-lived review apps; see
   [Enable Capacity AI for Demo and Starter Staging Apps](tips.md#enable-capacity-ai-for-demo-and-starter-staging-apps).
-- Accepts `+review-app-deploy` only from trusted commenters (`OWNER`, `MEMBER`, or `COLLABORATOR`).
-- Skips fork-based PR deploys because the workflow builds Docker images with repository secrets. A trusted comment on a
-  fork PR still does not deploy the fork head, and manual dispatch must use a base-repository PR number; dispatching with
-  a fork PR number causes a hard workflow failure. To give a fork PR a review app, review the code carefully first, then
+- Accepts `+review-app-deploy` only when GitHub reports the commenter has `write`, `maintain`, or `admin` repository
+  permission. `read` and `triage` are denied, permission is checked again after queue admission, and lookup failures fail
+  closed. Manual dispatch follows the same post-queue permission rule.
+- Skips fork-based PR deploys because the workflow builds Docker images with repository secrets. An authorized comment on a
+  fork PR still does not deploy the fork head, and manual dispatch must use a base-repository PR number. A fork-targeted
+  request records no accepted intent and skips the mutating job. To give a fork PR a review app, review the code carefully first, then
   move the change to a branch in the base repository. The build will then run with repository-secret access.
+- Rejects comment, manual, and internal deploy requests for a closed pull request before recording a durable intent, then
+  rechecks that the pull request is still open after queue admission. A doomed deploy therefore cannot supersede the
+  automatic close-triggered deletion that cleans up an existing review app.
 
 `cpflow-delete-review-app.yml`
 
 - Deletes the review app on `+review-app-delete`.
-- Also supports manual workflow dispatch by a repository collaborator without requiring a trusted-commenter command.
+- Also supports manual workflow dispatch by a repository collaborator. The comment-time permission gate does not apply,
+  but the dispatching actor's repository permission is rechecked after queue admission.
 - Also deletes it automatically when the pull request closes through a `pull_request_target` event, so repository secrets
   are available for teardown; `hooks.pre_deletion` still executes through the latest PR-built image on this path, so
   review-app credentials must remain disposable.
-- Accepts `+review-app-delete` only from trusted commenters (`OWNER`, `MEMBER`, or `COLLABORATOR`); manual dispatch and
-  automatic PR-close teardown do not require a trusted commenter.
+- After Control Plane deletion succeeds, marks every GitHub deployment for the exact `review/<app-name>` environment
+  inactive so the repository does not retain a stale active review deployment, while skipping deployments whose latest
+  status is already inactive so repeated teardown is idempotent. Deploy and delete workflows share one per-PR
+  concurrency queue; the accepted-intent reconciliation described above compensates for GitHub replacing pending runs,
+  ensuring the newest accepted operation eventually wins and an older deploy cannot publish the final state after a
+  newer deletion. If GitHub deployment cleanup fails after Control Plane deletion, the workflow reports
+  that partial outcome accurately and still fails so the cleanup can be retried.
+- Accepts `+review-app-delete` only when GitHub reports the commenter has `write`, `maintain`, or `admin` repository
+  permission. `read` and `triage` are denied, permission is checked again after queue admission, and lookup failures fail
+  closed. Manual dispatch uses the same post-queue actor check; automatic PR-close teardown does not use a manual actor
+  permission check.
 
 `cpflow-deploy-staging.yml`
 
@@ -633,11 +708,13 @@ wrapper-level `if:` guard shown in that file, for example
 ## Upstream Workflows And Actions
 
 Most generated workflows are intentionally small wrappers. The deployment
-logic, comment formatting, Control Plane CLI setup, Docker image build, and
-cleanup helpers live in upstream reusable workflows and composite actions in
-this repository. Production promotion is expanded into the caller repository so
-it can own `environment: production`, but it still checks out the same upstream
-ref for shared composite actions.
+logic and comment formatting live in upstream reusable workflows. The canonical
+composite actions live in this repository and the gem copies them into each
+downstream repository at `.github/actions/cpflow-*`; the reusable workflows use
+those regular local action paths. They separately check out the matching
+upstream ref at `.cpflow` for the `cpflow` runtime source. Production promotion
+is expanded into the caller repository so it can own `environment: production`,
+but follows the same local-action and `.cpflow` source split.
 
 - `cpflow-setup-environment`: installs Ruby, the Control Plane CLI, and `cpflow`, then logs into the target org. By default it builds `cpflow` from the checked-out upstream `control-plane-flow` ref; set the `CPFLOW_VERSION` repository variable only when you want to force a published RubyGems release.
 - `cpflow-build-docker-image`: builds and pushes the app image with the desired commit SHA
@@ -662,37 +739,51 @@ reusable-workflow wrappers should not pass `control_plane_flow_ref`; if you see
 that input outside the production promotion setup step, regenerate with a newer
 `cpflow`.
 
-There are two locks, and they protect different things:
+There are two coordinated inputs, and they protect different things:
 
-- The GitHub ref locks the reusable workflow and composite action code that
-  GitHub runs.
-- The RubyGems version locks the `cpflow` CLI/runtime code only when you install
-  or run that gem. It does not make GitHub load reusable workflow YAML from the
-  gem.
+- The GitHub ref locks the reusable workflow and the `.cpflow` runtime source
+  checkout that GitHub runs.
+- The installed Ruby gem supplies the generated local composite actions and
+  wrappers. `CPFLOW_VERSION`, when configured, separately locks the published
+  `cpflow` runtime installed by the setup action.
 
 That means a downstream app cannot rely on the gem alone for GitHub Actions
 behavior. The safe stable path is still gem-driven for generation, but
-developers must commit generated wrappers that reference the matching upstream
-release tag:
+developers must commit the generated wrappers and local actions from the gem
+that matches the upstream release tag:
 
 1. Publish a `cpflow` gem.
 2. Install or bundle that released gem in the downstream project.
 3. Run `cpflow generate-github-actions`.
-4. Commit the generated wrappers that point to the matching upstream release tag
-   such as `v5.0.0`.
+4. Commit the generated wrappers and `.github/actions/cpflow-*` files; the
+   wrappers should point to the matching upstream release tag such as `v5.0.0`.
 
 That release tag should point to the same source that produced the RubyGems
 release. Downstream production automation should use release tags, not `main` or
 feature-branch refs.
 
+Generated cross-repository reusable-workflow calls deliberately use an exact
+release tag such as `v5.0.0`. This is the intentional downstream exception to
+the repository's full-SHA external-action policy: it keeps the installed gem,
+generated wrappers, generated local actions, and upstream workflow on one
+reviewed release update contract. It does not extend to external actions inside
+those workflows, which remain pinned to full commit SHAs with readable release
+comments. Unreleased downstream validation temporarily replaces the exact tag
+with the upstream PR's full commit SHA as described below; moving version
+aliases and branches remain forbidden.
+
 ## Updating Generated GitHub Actions After Gem Updates
 
-Whenever a downstream repo updates the `cpflow` gem, update the checked-in
-GitHub Actions wrappers in the same PR. The gem version does not make GitHub load
-new reusable workflow YAML by itself; GitHub loads the `uses:` ref committed in
-`.github/workflows/cpflow-*.yml`.
+Whenever a downstream repo updates the `cpflow` gem, update all checked-in
+GitHub Actions files in the same PR. The gem version does not make GitHub load
+new reusable workflow YAML or local action files by itself; GitHub uses the
+workflow ref and `.github/actions/cpflow-*` files committed in the repository.
+
+For a new repository that does not have generated wrappers yet, run
+`cpflow generate-github-actions` first. Use the update command below for later
+gem upgrades.
 
-Use the installed gem to refresh the generated wrappers:
+Use the installed gem to refresh the generated workflows and actions:
 
 ```sh
 cpflow update-github-actions
@@ -706,11 +797,11 @@ bundle exec cpflow update-github-actions
 bin/test-cpflow-github-flow bundle exec cpflow
 ```
 
-`cpflow update-github-actions` regenerates the generated wrapper and helper
-files from the installed gem, pins the wrapper `uses:` refs to `v<gem-version>`,
-and preserves a single custom staging branch from the existing generated staging
-workflow. Pass `--staging-branch BRANCH` when changing or restoring a custom
-staging branch explicitly.
+`cpflow update-github-actions` regenerates the workflow wrappers, local
+composite actions, and helper files from the installed gem, pins the wrapper
+`uses:` refs to `v<gem-version>`, and preserves a single custom staging branch
+from the existing generated staging workflow. Pass `--staging-branch BRANCH`
+when changing or restoring a custom staging branch explicitly.
 
 When keeping `cpflow` in an app Gemfile, leave a comment next to the gem entry
 so future dependency bumps include the wrapper update:
@@ -744,7 +835,8 @@ action commit, so a moving branch named like `v5.0.0` cannot be used with
 runners that cannot reach GitHub should leave `CPFLOW_VERSION` unset and build
 `cpflow` from the checked-out ref instead. When testing an unreleased upstream
 commit SHA, leave `CPFLOW_VERSION` unset so the workflow builds `cpflow` from the
-same source that supplies the reusable workflow and composite actions.
+same source that supplies the reusable workflow. Refresh the generated local
+actions from that checkout before testing as described below.
 
 ## Testing Unreleased Upstream Changes Downstream
 
@@ -752,24 +844,26 @@ You can test a `control-plane-flow` PR in a downstream app before merging or
 releasing it. Use an immutable commit SHA from the upstream PR branch:
 
 1. Push the upstream PR branch and copy its full 40-character head SHA.
-2. In a downstream test branch, run:
+2. In a downstream test branch, regenerate from the upstream checkout and then
+   pin the wrappers to its exact SHA:
 
    ```sh
+   ruby /path/to/control-plane-flow/bin/cpflow update-github-actions
    bin/pin-cpflow-github-ref <upstream-pr-sha>
    ```
 
-   The helper updates every generated reusable-workflow `uses:` ref plus the
-   production workflow's pinned `control-plane-flow` checkout and setup
-   validation ref. It accepts release tags and full commit SHAs by default,
-   rejects branch names such as `main` or `feature/foo`, and requires
-   `--allow-moving-ref` for short-lived local experiments that should not be
-   committed.
-
-3. Keep `CPFLOW_VERSION` unset so the workflow builds `cpflow` from the same
-   upstream SHA that supplies the reusable workflow and composite actions. If
-   `CPFLOW_VERSION` is set while the wrapper is pinned to a SHA, the setup
-   action fails before deployment because the gem and action code cannot be
-   proven to match.
+   The update command copies the PR checkout's canonical composite actions into
+   `.github/actions/cpflow-*`. The pin helper then updates every generated
+   reusable-workflow `uses:` ref plus the production workflow's pinned
+   `control-plane-flow` checkout and setup validation ref. It accepts release
+   tags and full commit SHAs by default, rejects branch names such as `main` or
+   `feature/foo`, and requires `--allow-moving-ref` for short-lived local
+   experiments that should not be committed.
+
+3. Keep `CPFLOW_VERSION` unset so the workflow builds `cpflow` from the pinned
+   upstream SHA. If `CPFLOW_VERSION` is set while the wrapper is pinned to a
+   SHA, the setup action fails before deployment because the published gem and
+   upstream source cannot be proven to match.
 4. Run:
 
    ```sh
@@ -783,25 +877,48 @@ releasing it. Use an immutable commit SHA from the upstream PR branch:
    bin/test-cpflow-github-flow ruby /path/to/control-plane-flow/bin/cpflow
    ```
 
-5. Open a downstream PR and trigger the real review app with a comment whose body
-   is exactly:
+5. Push the downstream test branch, then choose the remote validation path that
+   matches the repository's installation state.
+
+   For an existing installation, where `cpflow-deploy-review-app.yml` is already
+   present on the default branch, dispatch the workflow definition and generated
+   local actions from the unmerged downstream test branch against a suitable open
+   base-repository PR:
+
+   ```sh
+   gh workflow run cpflow-deploy-review-app.yml --ref <downstream-test-branch> -f pr_number=<pr-number>
+   ```
+
+   The `--ref` selects the downstream wrapper and local-action commit under test;
+   `pr_number` selects the application source to deploy. Do not use a
+   `+review-app-deploy` comment for this pre-merge validation: `issue_comment`
+   always loads the workflow definition from the default branch, so it cannot
+   validate unmerged wrappers or local actions.
+
+   For a first installation, GitHub will not dispatch a workflow that does not
+   yet exist on the default branch, even when `--ref` names the installation
+   branch. Treat the rollout as staged: run the local contract before merging,
+   review the generated diff, merge it, and dispatch the merged workflow
+   immediately afterward against a suitable open base-repository PR:
 
-   ```text
-   +review-app-deploy
+   ```sh
+   gh workflow run cpflow-deploy-review-app.yml --ref <default-branch> -f pr_number=<pr-number>
    ```
 
-6. Verify the deploy logs show the expected upstream commit SHA, the setup step
-   prints the expected `cpflow` source/version, and the review app URL returns
-   HTTP 200.
+6. Verify the dispatched deploy logs show the expected upstream commit SHA, the
+   setup step prints the expected `cpflow` source/version, and the review app URL
+   returns HTTP 200. After merge, `+review-app-deploy` remains the normal
+   maintainer-facing trigger for subsequent review apps.
 7. After the upstream PR merges and a gem is released, regenerate the downstream
    wrappers from that released gem and commit the release tag. Use
    `bin/pin-cpflow-github-ref vX.Y.Z` only for a ref-only update when the
    generated templates are already current.
 
-This tests the real reusable workflows, the production workflow's checked-out
-shared composite actions, and the source-built `cpflow` gem from one immutable
-upstream commit. It avoids merging upstream blind and avoids running production
-automation against a moving branch.
+For an existing installation, this tests the real reusable workflows, the
+unmerged regenerated local composite actions, and the source-built `cpflow` gem
+against one immutable upstream commit. A first installation gets the same remote
+proof immediately after its locally validated files reach the default branch.
+Both paths avoid testing against a moving upstream branch.
 
 ## Local Generated-Flow Checks
 

data/docs/commands.md

@@ -29,6 +29,8 @@ cpflow ai-github-flow-prompt
 - Publishes (creates or updates) those at Control Plane infrastructure
 - Picks templates from the `.controlplane/templates` directory
 - Templates are ordinary Control Plane templates but with variable preprocessing
+- Use `--preserve-existing-runtime` to retain each workload container's configured app image, even when the workload is unready, and skip existing secret resources entirely while applying other template changes
+- Missing or invalid workload images use only an unambiguous app image from ready workloads; refresh fails before applying templates when no safe fallback exists
 
 **Preprocessed template variables:**
 
@@ -83,7 +85,7 @@ cpflow cleanup-images -a $APP_NAME
 
 - Acts on stale apps based on the creation date of the latest image, or the GVC if no images exist
 - With `--mode=delete` (default): deletes the whole app (GVC with all workloads, all volumesets and all images), and unbinds the app from the secrets policy and any configured `shared_secret_grants` policies as long as both the identity and each policy exist (and are bound)
-- With `--mode=stop`: suspends all workloads via `cpflow ps:stop` — no GVC, volumeset, or image is removed; resume with `cpflow ps:start`
+- With `--mode=stop`: suspends configured workloads that exist in the live GVC through Control Plane — no GVC, volumeset, or image is removed; resume with `cpflow ps:start`
 - `--mode=stop` only suspends workloads listed in `app_workloads` + `additional_workloads`; workloads present in the live GVC but missing from the config are skipped silently
 - `--mode=stop` returns once each workload is marked suspended; it does not wait for the workload to reach a not-ready state
 - Specify the amount of days after an app should be considered stale through `stale_app_image_deployed_days` in the `.controlplane/controlplane.yml` file
@@ -230,6 +232,9 @@ Creates GitHub Actions templates for a Heroku Flow style Control Plane pipeline:
 - manual promotion from staging to production
 - nightly cleanup and PR help workflows
 
+It also copies cpflow's composite actions into `.github/actions/cpflow-*`
+so every local `uses:` target is checked in and can be audited directly.
+
 Pass `--staging-branch BRANCH` when staging should auto-deploy from a branch
 other than `main` or `master`; the generator will bake that branch into the
 GitHub Actions push trigger and use it as the default STAGING_APP_BRANCH.
@@ -238,13 +243,13 @@ Pass `--force` to overwrite existing generated files. Prefer
 repo.
 
 ```sh
-# Creates thin .github/workflows wrappers for the Control Plane flow
+# Creates workflow wrappers, local composite actions, and validation helpers
 cpflow generate-github-actions
 
 # Creates the flow with staging deploys triggered from develop
 cpflow generate-github-actions --staging-branch develop
 
-# Overwrites existing generated wrappers from the installed cpflow gem
+# Overwrites existing generated GitHub Actions files from the installed cpflow gem
 cpflow generate-github-actions --force
 ```
 
@@ -479,8 +484,27 @@ timeout 300 cpflow ps:wait -a $APP_NAME
   and also overridden per job through `--cpu` and `--memory`)
 - By default, the job is stopped if it takes longer than 6 hours to finish
   (can be configured though `runner_job_timeout` in `controlplane.yml`)
+- Waiting for a runner replica is limited to the smaller of `runner_job_timeout` and 1000 seconds.
+  A terminal cron status fails immediately, and reaching the observation deadline reports the last safe status
+- With non-interactive log methods 2 and 3, after a command prints its completion marker, Control Plane
+  has up to 20 minutes to reconcile the cron job to a terminal status. This can be configured through
+  `runner_job_status_reconciliation_timeout` in `controlplane.yml`; timing out exits nonzero and reports
+  the job, replica, and last observed status
+- Log method 1 does not emit a completion marker, so its job-status polling is not covered by the
+  post-command reconciliation timeout
 - Non-interactive jobs return the Control Plane cron job status even when the job finishes before
   Control Plane exposes a runner replica to attach logs to
+- Injects `CPFLOW_GVC_ID` and `CPFLOW_GVC_CREATED` into the job, exposing the app's immutable GVC
+  identity, so that a command such as a release script can tell which GVC incarnation it is running in.
+  These change when a GVC is deleted and recreated under the same name, and only then, unlike
+  `CPLN_GVC_ALIAS`, which is also embedded in mutable derived values such as the app domain and so
+  cannot be attributed to recreation alone
+- `CPFLOW_GVC_CREATED` is the GVC's creation timestamp as returned by the Control Plane API and passed
+  through unmodified, currently an ISO 8601 UTC timestamp with millisecond precision and a `Z` suffix
+  (e.g. `2026-08-28T00:54:48.648Z`)
+- Both variables are always set, and are empty when the GVC cannot be read, so that a consumer can
+  fail closed. They are never omitted, because the runner inherits the original workload's
+  environment and an omitted variable could otherwise expose a stale inherited value
 
 ```sh
 # Opens shell (bash by default).
@@ -504,7 +528,8 @@ cpflow run -a $APP_NAME -- rails db:migrate
 # - stop the job
 cpflow run -a $APP_NAME --detached -- rails db:migrate
 
-# The command needs to be quoted if setting an env variable or passing args.
+# Quote the whole command to intentionally opt into shell syntax such as an env assignment.
+# Separately supplied command arguments are passed literally.
 cpflow run -a $APP_NAME -- 'SOME_ENV_VAR=some_value rails db:migrate'
 
 # Uses a different image (which may not be promoted yet).
@@ -539,6 +564,7 @@ cpflow run -a $APP_NAME --entrypoint /app/alternative-entrypoint.sh -- rails db:
 - Runs a post-creation hook after the app is created if `hooks.post_creation` is specified in the `.controlplane/controlplane.yml` file
 - If the hook exits with a non-zero code, the command will stop executing and also exit with a non-zero code
 - Use `--skip-post-creation-hook` to skip the hook if specified in `controlplane.yml`
+- Use `--refresh-templates` to apply configured templates noninteractively to an existing app while preserving each workload's configured app image even when workloads are unready or use mixed image versions, skipping existing secret resources entirely, repairing secrets access bindings, and skipping the post-creation hook
 
 ```sh
 cpflow setup-app -a $APP_NAME
@@ -562,17 +588,18 @@ cpflow terraform import
 
 ### `update-github-actions`
 
-Regenerates the generated cpflow GitHub Actions wrappers and helper files
-from the currently installed cpflow gem. Use this after updating the
-cpflow gem so checked-in workflow wrappers move to the matching upstream
-release tag, for example `v5.1.1`.
+Regenerates the cpflow workflow wrappers, local composite actions, and
+helper files from the currently installed cpflow gem. Use this after
+updating the cpflow gem so checked-in workflow wrappers move to the
+matching upstream release tag, for example `v5.3.0`, and the
+generated action implementations move with them.
 
 If the existing generated staging workflow uses a custom single staging
 branch, the command preserves it. Pass `--staging-branch BRANCH` to set or
 replace the generated staging branch explicitly.
 
 ```sh
-# After updating the cpflow gem, refresh generated GitHub Actions wrappers
+# After updating the cpflow gem, refresh every generated GitHub Actions file
 cpflow update-github-actions
 
 # When running cpflow through Bundler