cpflow 5.3.0 → 6.0.0

data/docs/ci-automation.md

@@ -23,7 +23,7 @@ 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.
+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.
 
@@ -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`
 
@@ -76,7 +77,7 @@ The second command writes namespaced files so they can coexist with an app's exi
 Docker base Ruby version from `.ruby-version`, `.tool-versions`, or the app's
 `Gemfile`, preserves repo-defined frontend precompile hooks such as Shakapacker
 `precompile_hook` commands or React on Rails auto bundle generation, and
-switches to persistent SQLite `db` and `storage` templates when
+switches to persistent SQLite data and Active Storage templates when
 `config/database.yml` shows SQLite in production.
 
 `cpflow github-flow-readiness` checks public RubyGems and npm registry metadata
@@ -214,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`
@@ -228,14 +230,75 @@ because they could change the target org name after normalization.
 
 Production promotion copies the exact image currently deployed on the selected
 staging workload. If that staging image is digest-pinned, the digest is used for
-the source copy while the production tag is derived from the tag portion. Tags
-with a `_<commit>` suffix keep that suffix in production; plain numeric tags are
-also valid and promote to the next plain production tag. The copy step uses
+the source copy while the production tag is derived from the tag portion. Staging tags must
+include a full lowercase 40-character Git commit SHA suffix (`_<commit>`),
+which is preserved in the new production tag. A staging image without that
+provenance stops promotion before approval. The copy step uses
 `docker buildx imagetools create --prefer-index=false --tag` with isolated
 Docker credentials, which preserves multi-architecture manifests, preserves
 single-platform manifest format when supported, and avoids pulling image layers
 onto the GitHub Actions runner.
 
+When you start production promotion, the **preview-promotion** job finishes
+before GitHub requests approval for the protected production Environment. Open
+the run summary’s **Commits ready for production** section before approving. It
+compares staging’s deployed primary-workload image with the last recorded
+successful `production-*` GitHub release. It links the full comparison, lists up
+to 100 commit subjects, and flags diverged history or staging behind production.
+Matching SHAs report no commits to promote. Release discovery checks the latest
+100 releases; missing production history or GitHub API failures produce an
+explicit availability notice. The preview uses the existing staging token and
+GitHub `contents: read` permission; it has no production token.
+
+The preview selects the primary workload from the staging app’s
+`app_workloads` configuration. `PRODUCTION_APP_NAME` and
+`CPLN_ORG_PRODUCTION` can remain production Environment variables. When staging
+and production have different primary-workload defaults, set `PRIMARY_WORKLOAD`
+as a repository variable shared by both jobs; the protected job rejects a
+workload-selection mismatch. A Control Plane read failure or invalid staging
+SHA fails the preview and prevents approval from starting.
+
+After approval, the protected job checks that staging still uses the captured
+image and, when a release baseline was available, that live production matches
+that release’s commit. A mismatch stops before copying or deploying an image;
+rerun after staging changes, or reconcile the production release record after an
+out-of-band production deployment. If production history was unavailable, the
+summary does not claim to know the production-to-staging diff.
+
+Existing repositories adopt this with
+`cpflow update-github-actions --workflows cpflow-promote-staging-to-production.yml`.
+Review and reapply downstream workflow customizations before committing the
+replacement and the refreshed local composite actions. The bare update command
+preserves existing top-level workflows.
+
+### Recover a missing or stale production release record
+
+A successful production deployment and its GitHub release are separate jobs.
+If deployment succeeded but **create-github-release** failed, open that original
+Actions run and choose **Re-run failed jobs**. This retries release publication
+at the original promoted SHA; do not rerun the whole promotion merely to repair
+the record. Confirm the resulting `production-*` release targets the live
+production image’s SHA, then start a fresh promotion preview.
+
+After an out-of-band production deploy or rollback, an app maintainer should
+first verify the healthy live primary-workload image and its full commit suffix
+with `cpln workload get <primary-workload> --gvc <production-app> --org
+<production-org> -o json`. Use that SHA to publish a fresh release record; do not
+move an existing release tag. For example, after replacing `<verified-live-sha>`:
+
+```sh
+gh release create "production-$(date -u +%Y-%m-%d-%H%M%S)-0" \
+  --target <verified-live-sha> \
+  --title "Production state reconciliation" \
+  --notes "Records the verified live production commit after a manual deployment or rollback."
+```
+
+Run this in the app repository with the maintainer’s normal GitHub credentials.
+Verify the new tag’s commit and the live image agree, then rerun promotion to
+produce a fresh preview. If the live image has no commit suffix, establish its
+provenance and use a traceable image before recording a baseline; guessing a
+branch head would make the comparison misleading.
+
 Before copying the image, production promotion compares the environment variable
 names exposed by staging and production at both the GVC level and each configured
 app workload's container level. Variables present in staging are treated as
@@ -423,9 +486,11 @@ Recommended org layout:
   review/staging CI operations; use a dedicated review-app org only if you also customize the generated
   workflow/configuration to target that org separately
 
-Optional repository secret for private dependency builds:
+Optional repository secrets for Docker builds:
 
 - `DOCKER_BUILD_SSH_KEY`: private SSH key used when the Dockerfile needs `RUN --mount=type=ssh` to fetch private GitHub dependencies during image build
+- `DOCKER_BUILD_SECRETS`: staging build credentials as newline-delimited `id=value` entries supplied through BuildKit secret mounts. Values must be single-line; spaces and additional `=` characters are preserved. IDs may contain letters, digits, underscores, and hyphens, and must start with a letter or digit. Empty values and duplicate IDs are rejected. Leave this secret unset when the build does not need credentials.
+- `REVIEW_APP_DOCKER_BUILD_SECRETS`: separate credentials for review-app builds, using the same format. The generated review-app caller uses only this secret; it does not fall back to `DOCKER_BUILD_SECRETS`. Leave it unset to supply no BuildKit secrets to review apps.
 
 Optional repository variables for private dependency builds:
 
@@ -473,7 +538,12 @@ The generated flow uses these defaults:
   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;
+  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 invocation to
   the exact command shape; the reusable workflow resolves repository permission before its deploy job runs, then its
@@ -510,13 +580,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,
@@ -560,6 +633,30 @@ The generated `cpflow-build-docker-image` action supports this without hardcodin
 - set `DOCKER_BUILD_SSH_KEY` if the Docker build needs SSH access to GitHub
 - optionally set `DOCKER_BUILD_SSH_KNOWN_HOSTS` when the SSH build host is not GitHub.com or you need custom host entries
 - set `DOCKER_BUILD_EXTRA_ARGS` when you need extra `docker build` flags
+- set `DOCKER_BUILD_SECRETS` for staging builds that need credentials such as a private package token or a source-map upload token
+- set `REVIEW_APP_DOCKER_BUILD_SECRETS` separately if review-app builds need credentials
+
+For example, store the following as the **value** of the `DOCKER_BUILD_SECRETS` GitHub Actions secret:
+
+```text
+sentry_auth_token=<source-map upload token>
+npm_token=<private package token>
+```
+
+The generated staging caller forwards `DOCKER_BUILD_SECRETS`. The review-app caller forwards `REVIEW_APP_DOCKER_BUILD_SECRETS`, the only build-secret parameter the reusable review-app workflow accepts, so review builds never receive the staging secret. The build action writes each value to a private temporary file, passes only its path through `--secret=id=...,src=...`, and removes the files on success or failure. Values are not passed as build arguments or persisted through `GITHUB_ENV`.
+
+A Dockerfile can consume a token only for the command that needs it:
+
+```dockerfile
+# syntax=docker/dockerfile:1
+ARG SENTRY_UPLOAD=false
+RUN --mount=type=secret,id=sentry_auth_token,env=SENTRY_AUTH_TOKEN \
+    SENTRY_UPLOAD=${SENTRY_UPLOAD} npm run build
+```
+
+If the application's build requires an explicit upload opt-in, pass `docker_build_extra_args: --build-arg=SENTRY_UPLOAD=true` in the caller workflow's `with` block, or add that token to `DOCKER_BUILD_EXTRA_ARGS`. The optional workflow input is appended after the repository variable, retaining existing build arguments. Token availability alone need not enable uploads. BuildKit secret values do not invalidate build caches; force the relevant build step to run again when rotating a credential requires repeating an upload.
+
+Every secret supplied to a review build is accessible to the PR-controlled Dockerfile, which can read and transmit it. Automatic rebuilds of an existing review app also receive these secrets; approval to create the app does not approve later commits. Configure only credentials whose access can be entrusted to anyone able to change the deployed branch, scoped to the minimum review-build permissions. Separate secret names reduce accidental sharing but do not prevent the Dockerfile from accessing supplied credentials. If a credential cannot be entrusted to branch authors, omit it from review builds or use a customized approval gate that approves each deployed commit. Apply the review-app security guidance above.
 
 For example, a repo that installs private dependencies from GitHub during Docker build can set:
 
@@ -698,11 +795,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
@@ -727,37 +826,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.
 
-Use the installed gem to refresh the generated wrappers:
+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 workflows and actions:
 
 ```sh
 cpflow update-github-actions
@@ -771,11 +884,88 @@ 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` refreshes local composite actions and helpers.
+It preserves every top-level workflow by default, including refs, triggers,
+permissions, and downstream deployment ownership. It does not create staging
+or production deployment workflows when another CI system owns those deploys.
+Select the wrappers you intend to replace explicitly; see
+`cpflow update-github-actions --help` for the current interface:
+
+```sh
+bundle exec cpflow update-github-actions --workflows \
+  cpflow-deploy-review-app.yml cpflow-delete-review-app.yml \
+  cpflow-cleanup-stale-review-apps.yml cpflow-help-command.yml \
+  cpflow-review-app-help.yml
+```
+
+Each selected wrapper is replaced in full with the installed gem's template
+and release ref. Review the diff and reapply downstream changes before
+committing. Unselected wrappers keep their refs: preservation is not evidence
+that old wrappers are compatible with new local actions. Migrate wrapper
+contracts and source pins together, then run the validator in the same PR.
+For a selected staging wrapper, a single existing push branch or the default
+main/master pair can be inferred. Missing, malformed, or ambiguous branch
+configuration requires an explicit `--staging-branch BRANCH`; that option also
+requires selecting `cpflow-deploy-staging.yml`.
+
+### Preserving downstream validation
+
+The generated `bin/test-cpflow-github-flow` runs baseline checks followed by
+an optional executable `bin/test-cpflow-github-flow-custom`. The extension runs
+from the repository root with the cpflow command argv forwarded unchanged
+(for example, `bundle`, `exec`, `cpflow`), and its nonzero exit fails validation.
+The generator never creates or overwrites the custom extension. Baseline
+production checks apply when the generated production workflow exists;
+downstream-owned production workflows belong in the custom checks.
+
+An existing validator that differs from the installed template blocks the
+entire update before any writes. This includes unmodified validators from
+older releases: the updater cannot safely distinguish them from custom code.
+For a legacy installation such as HiChee's 5.3-to-6.0 RC migration:
+
+1. Save the old validator in version control and compare it with its original
+   release. Extract the downstream checks into `bin/test-cpflow-github-flow-custom`
+   and make it executable. If it is entirely downstream-specific, rename it
+   directly. Remove any call back to the generated validator to avoid recursion.
+2. Remove or rename the old `bin/test-cpflow-github-flow` after preserving those
+   checks, then run the update command with the selected wrappers. No override
+   flag bypasses this check. Do not use `generate-github-actions --force` as a
+   migration shortcut: it intentionally replaces the full generated flow.
+3. Run the new validator. Confirm that the custom checks execute and that a
+   failing custom check still fails the command. Repeating the updater with the
+   same selected workflows should produce no further diff.
+
+### Migrating trusted action allowlists
+
+Repositories using a closed `trusted_actions` policy must review these exact
+repositories used by the complete generated output:
+
+```yaml
+trusted_actions:
+  - actions/checkout
+  - docker/setup-buildx-action
+  - ruby/setup-ruby
+  - shakacode/control-plane-flow
+```
+
+Merge the needed entries into your existing policy rather than replacing it.
+`ruby/setup-ruby` is used by the generated local setup action, including in
+review-app-only installations. `actions/checkout` and `docker/setup-buildx-action`
+are used directly by the generated production wrapper;
+`shakacode/control-plane-flow` supplies the reusable wrappers. Other existing
+downstream workflows may need additional entries. Upstream reusable workflows
+also use `actions/github-script`; reviewing that upstream implementation remains
+part of trusting `shakacode/control-plane-flow`.
+
+Allowlisting does not waive immutable pin requirements. For a policy requiring
+full SHAs, resolve and independently verify the chosen upstream release tag or
+test commit, then run `bin/pin-cpflow-github-ref --version <reviewed-version-tag>
+<full-sha>`. The helper writes that version/tag beside all cpflow SHA pins and
+updates obsolete same-line comments. The label is supplied by the caller; the
+helper does not contact GitHub or certify tag-to-SHA identity. For an unreleased
+test commit, use its source version tag as context and record the exact commit
+in the PR. Review the generated diff and run your repository's action security
+scanner after updating its allowlist.
 
 When keeping `cpflow` in an app Gemfile, leave a comment next to the gem entry
 so future dependency bumps include the wrapper update:
@@ -809,7 +999,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
 
@@ -817,24 +1008,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
-   bin/pin-cpflow-github-ref <upstream-pr-sha>
+   ruby /path/to/control-plane-flow/bin/cpflow update-github-actions
+   bin/pin-cpflow-github-ref --version <reviewed-version-tag> <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 (with a reviewed `--version` label), 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
@@ -848,25 +1041,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.
 
-   ```text
-   +review-app-deploy
+   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:
+
+   ```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
 
@@ -909,7 +1125,7 @@ In practice, porting the flow into a demo app usually follows five phases.
 
 4. Update `.controlplane/controlplane.yml` with staging, review, and production entries.
 5. Confirm that the generated Dockerfile picked a Ruby base image compatible with the app's declared Ruby requirement.
-6. For SQLite-backed apps, confirm that the generated scaffold switched to persistent `db` and `storage` volumes, mounted them into the main workload, and added a release script that runs `rails db:prepare`.
+6. For SQLite-backed apps, confirm that the generated scaffold redirects every production database file into persistent `/app/data` (or keeps it under persistent `/app/storage`) without hiding image migrations under `/app/db`, mounts Active Storage at `/app/storage`, and adds a release script that runs `rails db:prepare`.
 
 **Adapt for the app's runtime:**
 
@@ -953,7 +1169,7 @@ Expand that prompt with app-specific requirements before editing files:
 - make sure the generated Dockerfile uses a Ruby base image compatible with the app's declared Ruby requirement
 - preserve repo-defined frontend precompile hooks, such as Shakapacker `precompile_hook` commands or React on Rails `config.auto_load_bundle = true`
 - keep Node available in the final image if Rails or SSR depends on ExecJS, Yarn, or `pnpm` after the main `npm install` layer
-- if `config/database.yml` shows SQLite in production, confirm that `cpflow generate` emitted persistent `db` and `storage` volumes plus a `rails db:prepare` release script; otherwise keep the default Postgres workload
+- if `config/database.yml` shows SQLite in production, confirm that `cpflow generate` redirected every production database path into persistent `/app/data` or `/app/storage`, emitted both volumes without mounting over `/app/db`, and added a `rails db:prepare` release script; otherwise keep the default Postgres workload
 - inspect the production Dockerfile and package sources for private GitHub dependencies, and wire `DOCKER_BUILD_SSH_KEY` plus `DOCKER_BUILD_SSH_KNOWN_HOSTS` when the build uses `RUN --mount=type=ssh` against non-GitHub hosts
 - add extra `app_workloads` and template files for any runtime sidecars, workers, or renderer processes
 - make sure any sidecar process exposed to sibling workloads binds to `0.0.0.0` instead of container-local `localhost`