cpflow 6.0.0 → 6.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2abf58d5c1099a9f57164ebe03843c014180098e23551d73822419b05191070a
-  data.tar.gz: ab7adb1a83dbea1215c5686748e1438006a3a58ce419d1797a53172a670ce86e
+  metadata.gz: 5339d75233bef2f62028093b5037a44155a56d2c4f39741efbc4861c47848e86
+  data.tar.gz: bd30c3c9da8a468b6e5cc9479ed6be3912066b70e03f021533a815498756f162
 SHA512:
-  metadata.gz: 4fcb5b12cc9b4ce2edec7afc583bdd37a62812a40e5ea478e1efc09a29e82d3d0bfe47386001b3978a11bcc3deb342044596c54d52eecc605e5a04077fa322be
-  data.tar.gz: e5f33d39830fffc5fcb66e9f22aeb5d519c1ed18b51ae1ec77fe7a65c9e26b42426bac48aeaa5e62bff5c218c6cc2f5e9f131fdfd211cd2343a9c0671afa7880
+  metadata.gz: 417be2b206c02fda8ff5f2374ba3874ebc61c05ac00af7a8ff163306f359a9f323c3af268fad415b3422603b59bb7d1572335af4e5de9b88a0a5a7e6659f485b
+  data.tar.gz: 72f2e06d1325fc09028ad8454454fda8dfd0b8fa1a0a075050b5fe997b7ed1653d1abfcb5ccc35382caa1737325b40a52b4575de11d7f4a3707ccfc8d4e9803f

data/.github/workflows/cpflow-cleanup-stale-review-apps.yml

@@ -23,13 +23,6 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
-      # No explicit ref: checkout's default resolves to this event's recorded commit
-      # (GITHUB_SHA), which is trusted base-repository code and is exempt from checkout v7's fork-PR guard.
-      - name: Checkout generated cpflow actions
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-
       - name: Checkout control-plane-flow actions
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -39,7 +32,7 @@ jobs:
           persist-credentials: false
 
       - name: Validate required secrets and variables
-        uses: ./.github/actions/cpflow-validate-config
+        uses: ./.cpflow/.github/actions/cpflow-validate-config
         env:
           CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
         with:
@@ -54,14 +47,14 @@ jobs:
 
       - name: Resolve review app config
         id: review-config
-        uses: ./.github/actions/cpflow-resolve-review-config
+        uses: ./.cpflow/.github/actions/cpflow-resolve-review-config
         with:
           working_directory: app
           configured_cpln_org_staging: ${{ vars.CPLN_ORG_STAGING }}
           configured_review_app_prefix: ${{ vars.REVIEW_APP_PREFIX }}
 
       - name: Setup environment
-        uses: ./.github/actions/cpflow-setup-environment
+        uses: ./.cpflow/.github/actions/cpflow-setup-environment
         with:
           token: ${{ secrets.CPLN_TOKEN_STAGING }}
           org: ${{ steps.review-config.outputs.cpln_org }}

data/.github/workflows/cpflow-delete-review-app.yml

@@ -563,13 +563,6 @@ jobs:
               }
             }
 
-      # No explicit ref: checkout's default resolves to this event's recorded commit
-      # (GITHUB_SHA; the base-branch tip under pull_request_target) and is exempt from checkout v7's fork-PR guard.
-      - name: Checkout generated cpflow actions
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-
       - name: Checkout control-plane-flow actions
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -580,7 +573,7 @@ jobs:
 
       - name: Validate required secrets and variables
         id: config
-        uses: ./.github/actions/cpflow-validate-config
+        uses: ./.cpflow/.github/actions/cpflow-validate-config
         env:
           CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
         with:
@@ -598,7 +591,7 @@ jobs:
       - name: Resolve review app config
         if: steps.config.outputs.ready == 'true'
         id: review-config
-        uses: ./.github/actions/cpflow-resolve-review-config
+        uses: ./.cpflow/.github/actions/cpflow-resolve-review-config
         with:
           working_directory: app
           configured_cpln_org_staging: ${{ vars.CPLN_ORG_STAGING }}
@@ -607,7 +600,7 @@ jobs:
 
       - name: Setup environment
         if: steps.config.outputs.ready == 'true'
-        uses: ./.github/actions/cpflow-setup-environment
+        uses: ./.cpflow/.github/actions/cpflow-setup-environment
         with:
           token: ${{ secrets.CPLN_TOKEN_STAGING }}
           org: ${{ steps.review-config.outputs.cpln_org }}
@@ -651,7 +644,7 @@ jobs:
       - name: Delete review app
         id: delete-app
         if: steps.config.outputs.ready == 'true'
-        uses: ./.github/actions/cpflow-delete-control-plane-app
+        uses: ./.cpflow/.github/actions/cpflow-delete-control-plane-app
         with:
           app_name: ${{ steps.review-config.outputs.app_name }}
           cpln_org: ${{ steps.review-config.outputs.cpln_org }}

data/.github/workflows/cpflow-deploy-review-app.yml

@@ -617,13 +617,6 @@ jobs:
               }
             }
 
-      # No explicit ref: checkout's default resolves to this event's recorded commit
-      # (GITHUB_SHA), which is trusted base-repository code and is exempt from checkout v7's fork-PR guard.
-      - name: Checkout generated cpflow actions
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-
       - name: Checkout control-plane-flow actions
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -634,7 +627,7 @@ jobs:
 
       - name: Validate required secrets and variables
         id: config
-        uses: ./.github/actions/cpflow-validate-config
+        uses: ./.cpflow/.github/actions/cpflow-validate-config
         env:
           CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
         with:
@@ -748,7 +741,7 @@ jobs:
       - name: Resolve review app config
         if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true'
         id: review-config
-        uses: ./.github/actions/cpflow-resolve-review-config
+        uses: ./.cpflow/.github/actions/cpflow-resolve-review-config
         with:
           working_directory: app
           configured_cpln_org_staging: ${{ vars.CPLN_ORG_STAGING }}
@@ -757,7 +750,7 @@ jobs:
 
       - name: Setup environment
         if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true'
-        uses: ./.github/actions/cpflow-setup-environment
+        uses: ./.cpflow/.github/actions/cpflow-setup-environment
         with:
           token: ${{ secrets.CPLN_TOKEN_STAGING }}
           org: ${{ steps.review-config.outputs.cpln_org }}
@@ -769,7 +762,7 @@ jobs:
       - name: Detect release phase support
         if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true'
         id: release-phase
-        uses: ./.github/actions/cpflow-detect-release-phase
+        uses: ./.cpflow/.github/actions/cpflow-detect-release-phase
         with:
           app_name: ${{ steps.review-config.outputs.app_name }}
           working_directory: app
@@ -931,7 +924,7 @@ jobs:
       - name: Build Docker image
         id: build-image
         if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
-        uses: ./.github/actions/cpflow-build-docker-image
+        uses: ./.cpflow/.github/actions/cpflow-build-docker-image
         with:
           app_name: ${{ steps.review-config.outputs.app_name }}
           org: ${{ steps.review-config.outputs.cpln_org }}
@@ -1019,7 +1012,7 @@ jobs:
       - name: Wait for deployment health
         if: steps.config.outputs.ready == 'true' && steps.source.outputs.allowed == 'true' && (steps.check-app.outputs.exists == 'true' || steps.setup-review-app.outcome == 'success')
         id: health-check
-        uses: ./.github/actions/cpflow-wait-for-health
+        uses: ./.cpflow/.github/actions/cpflow-wait-for-health
         with:
           workload_name: ${{ env.PRIMARY_WORKLOAD || 'rails' }}
           app_name: ${{ steps.review-config.outputs.app_name }}

data/.github/workflows/cpflow-deploy-staging.yml

@@ -68,12 +68,6 @@ jobs:
             echo "is_deployable=false" >> "$GITHUB_OUTPUT"
           fi
 
-      - name: Checkout generated cpflow actions
-        if: steps.check-branch.outputs.is_deployable == 'true'
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-
       - name: Checkout control-plane-flow actions
         if: steps.check-branch.outputs.is_deployable == 'true'
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -85,7 +79,7 @@ jobs:
 
       - name: Validate required secrets and variables
         if: steps.check-branch.outputs.is_deployable == 'true'
-        uses: ./.github/actions/cpflow-validate-config
+        uses: ./.cpflow/.github/actions/cpflow-validate-config
         env:
           CPLN_TOKEN_STAGING: ${{ secrets.CPLN_TOKEN_STAGING }}
           CPLN_ORG_STAGING: ${{ vars.CPLN_ORG_STAGING }}
@@ -116,7 +110,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup environment
-        uses: ./.github/actions/cpflow-setup-environment
+        uses: ./.cpflow/.github/actions/cpflow-setup-environment
         with:
           token: ${{ secrets.CPLN_TOKEN_STAGING }}
           org: ${{ vars.CPLN_ORG_STAGING }}
@@ -126,7 +120,7 @@ jobs:
           control_plane_flow_ref: ${{ job.workflow_ref }}
 
       - name: Build Docker image
-        uses: ./.github/actions/cpflow-build-docker-image
+        uses: ./.cpflow/.github/actions/cpflow-build-docker-image
         with:
           app_name: ${{ env.APP_NAME }}
           org: ${{ vars.CPLN_ORG_STAGING }}
@@ -158,7 +152,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup environment
-        uses: ./.github/actions/cpflow-setup-environment
+        uses: ./.cpflow/.github/actions/cpflow-setup-environment
         with:
           token: ${{ secrets.CPLN_TOKEN_STAGING }}
           org: ${{ vars.CPLN_ORG_STAGING }}
@@ -169,7 +163,7 @@ jobs:
 
       - name: Detect release phase support
         id: release-phase
-        uses: ./.github/actions/cpflow-detect-release-phase
+        uses: ./.cpflow/.github/actions/cpflow-detect-release-phase
         with:
           app_name: ${{ env.APP_NAME }}
 

data/.github/workflows/cpflow-promote-staging-to-production.yml

@@ -93,7 +93,7 @@ jobs:
           echo "org=$org" >> "$GITHUB_OUTPUT"
 
       - name: Setup staging environment
-        uses: ./.github/actions/cpflow-setup-environment
+        uses: ./.cpflow/.github/actions/cpflow-setup-environment
         with:
           token: ${{ secrets.CPLN_TOKEN_STAGING }}
           org: ${{ steps.staging-org.outputs.org }}
@@ -104,7 +104,7 @@ jobs:
 
       - name: Preview commits before production approval
         id: preview
-        uses: ./.github/actions/cpflow-preview-promotion
+        uses: ./.cpflow/.github/actions/cpflow-preview-promotion
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GH_REPO: ${{ github.repository }}
@@ -157,7 +157,7 @@ jobs:
           fi
 
       - name: Validate required secrets and variables
-        uses: ./.github/actions/cpflow-validate-config
+        uses: ./.cpflow/.github/actions/cpflow-validate-config
         # Pass secrets via env so the composite action checks indirect shell
         # variables instead of interpolating secret values into a run script.
         env:
@@ -224,7 +224,7 @@ jobs:
           } >> "$GITHUB_OUTPUT"
 
       - name: Setup production environment
-        uses: ./.github/actions/cpflow-setup-environment
+        uses: ./.cpflow/.github/actions/cpflow-setup-environment
         with:
           token: ${{ secrets.CPLN_TOKEN_PRODUCTION }}
           org: ${{ steps.cpln-orgs.outputs.production }}
@@ -286,7 +286,7 @@ jobs:
 
       - name: Detect release phase support
         id: release-phase
-        uses: ./.github/actions/cpflow-detect-release-phase
+        uses: ./.cpflow/.github/actions/cpflow-detect-release-phase
         with:
           app_name: ${{ vars.PRODUCTION_APP_NAME }}
 
@@ -679,7 +679,7 @@ jobs:
 
       - name: Wait for deployment health
         id: health-check
-        uses: ./.github/actions/cpflow-wait-for-health
+        uses: ./.cpflow/.github/actions/cpflow-wait-for-health
         with:
           workload_name: ${{ steps.workloads.outputs.primary }}
           app_name: ${{ vars.PRODUCTION_APP_NAME }}

data/CHANGELOG.md

@@ -12,6 +12,13 @@ In addition to the standard keepachangelog.com categories, this project uses a l
 
 ## [Unreleased]
 
+## [6.0.1] - 2026-10-10
+
+### Changed
+
+- **`cpflow ai-github-flow-prompt` prints its rollout prompt as titled sections with one instruction per bullet instead of four long paragraphs.** The instructions are unchanged. [PR 512](https://github.com/shakacode/control-plane-flow/pull/512) by [Justin Gordon](https://github.com/justin808).
+- **Generated GitHub Actions workflows load cpflow's composite actions from the pinned `shakacode/control-plane-flow` ref again, so downstream repositories no longer check in `.github/actions/cpflow-*`.** A repository carries the wrappers and one pinned ref, and action fixes arrive with the next ref bump. The actions that receive `CPLN_TOKEN_STAGING` come from that pinned commit, not from the triggering pull request's revision. `cpflow generate-github-actions` stops writing the copies. Migrating from 6.0.0: replace the wrappers and the production promotion workflow with `cpflow update-github-actions --workflows FILE...`, then delete the copies yourself; the command lists them and never deletes them, because a wrapper still pinned to 6.0.0 runs them. See [Removing cpflow 6.0.0 action copies](docs/ci-automation.md#removing-cpflow-600-action-copies). [PR 511](https://github.com/shakacode/control-plane-flow/pull/511) by [Justin Gordon](https://github.com/justin808). Fixes [issue 510](https://github.com/shakacode/control-plane-flow/issues/510).
+
 ## [6.0.0] - 2026-10-08
 
 ### Breaking Changes
@@ -511,7 +518,8 @@ Deprecated `cpl` gem. New gem is `cpflow`.
 
 First release.
 
-[Unreleased]: https://github.com/shakacode/control-plane-flow/compare/v6.0.0...HEAD
+[Unreleased]: https://github.com/shakacode/control-plane-flow/compare/v6.0.1...HEAD
+[6.0.1]: https://github.com/shakacode/control-plane-flow/compare/v6.0.0...v6.0.1
 [6.0.0]: https://github.com/shakacode/control-plane-flow/compare/v5.3.0...v6.0.0
 [5.3.0]: https://github.com/shakacode/control-plane-flow/compare/v5.2.0...v5.3.0
 [5.2.0]: https://github.com/shakacode/control-plane-flow/compare/v5.1.1...v5.2.0

data/CONTRIBUTING.md

@@ -150,10 +150,10 @@ cpflow test
 
 ## Developing the GitHub flow generator
 
-`cpflow generate-github-actions` copies workflow templates in `lib/github_flow_templates/` and canonical composite actions in `.github/actions/cpflow-*` into a target repo's `.github/` directory. To work on this feature:
+`cpflow generate-github-actions` copies workflow templates in `lib/github_flow_templates/` into a target repo's `.github/` directory. The composite actions those workflows call stay in this repository's `.github/actions/cpflow-*`; workflows load them from the pinned `.cpflow` checkout as `./.cpflow/.github/actions/cpflow-*`. To work on this feature:
 
-- **Edit each canonical source in place.** The generator does no string-mangling beyond a small set of substitutions handled in `lib/command/generate_github_actions.rb`; what you put in `lib/github_flow_templates/.github/` is (almost) exactly what ships into a generated repo. Edit composite actions in the root `.github/actions/cpflow-*` directories. Make changes in those canonical sources, not in a generated copy.
-- **Surface area to keep consistent.** A change to a PR command (e.g. `+review-app-deploy`) usually touches three places: the trigger workflow (`lib/github_flow_templates/.github/workflows/cpflow-deploy-review-app.yml`), the PR-open quick reference (`cpflow-review-app-help.yml`), and the long-form help (`lib/github_flow_templates/.github/cpflow-help.md`). The AI flow prompt (`lib/command/ai_github_flow_prompt.rb`) also names commands and should be kept in sync.
+- **Edit each canonical source in place.** The generator does no string-mangling beyond a small set of substitutions handled in `lib/command/generate_github_actions.rb`; what you put in `lib/github_flow_templates/.github/` is (almost) exactly what ships into a generated repo. Edit composite actions in the root `.github/actions/cpflow-*` directories; they are not copied downstream. Make changes in those canonical sources, not in a generated copy.
+- **Surface area to keep consistent.** A change to a PR command (e.g. `+review-app-deploy`) usually touches three places: the trigger workflow (`lib/github_flow_templates/.github/workflows/cpflow-deploy-review-app.yml`), the PR-open quick reference (`cpflow-review-app-help.yml`), and the long-form help (`lib/github_flow_templates/.github/cpflow-help.md`). The AI flow prompt (`lib/command/ai_github_flow_prompt.txt`, mirrored in `docs/ai-github-flow-prompt.md`) also names commands and should be kept in sync.
 - **Run the generator spec on every change:**
 
   ```sh

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cpflow (6.0.0)
+    cpflow (6.0.1)
       dotenv (~> 3.1)
       jwt (~> 3.1)
       psych (~> 5.2)

data/README.md

@@ -398,7 +398,7 @@ cpflow generate-github-actions
 bin/test-cpflow-github-flow
 ```
 
-`cpflow github-flow-readiness` exits non-zero when it finds blockers such as unpublished exact-pinned packages or a missing production Dockerfile, so use it as the gate before generation. Then review the generated `.controlplane/controlplane.yml` entries, adjust any app-specific workloads, and configure the GitHub repository variables and secrets described in [CI automation](./docs/ci-automation.md), including the optional Docker build settings for private GitHub dependencies and custom SSH known hosts. `cpflow generate-github-actions` checks in the local `.github/actions/cpflow-*` implementations alongside the workflows, and also writes `bin/test-cpflow-github-flow` for local validation and `bin/pin-cpflow-github-ref` for temporarily pinning downstream wrappers to an upstream commit SHA during pre-release testing. `cpflow generate` already switches to persistent `/app/data` and `/app/storage` volumes when `config/database.yml` shows SQLite in production, redirects every detected production SQLite database into persistent storage, keeps migrations visible under `/app/db`, and preserves detected frontend precompile hooks. You should still confirm that the generated Dockerfile picked a Ruby base image compatible with the app's declared Ruby requirement and that the emitted workload set matches the real app. If you want an AI agent to do this end to end, give it the [AI rollout prompt](./docs/ai-github-flow-prompt.md) rather than a vague "set up CI" request.
+`cpflow github-flow-readiness` exits non-zero when it finds blockers such as unpublished exact-pinned packages or a missing production Dockerfile, so use it as the gate before generation. Then review the generated `.controlplane/controlplane.yml` entries, adjust any app-specific workloads, and configure the GitHub repository variables and secrets described in [CI automation](./docs/ci-automation.md), including the optional Docker build settings for private GitHub dependencies and custom SSH known hosts. `cpflow generate-github-actions` writes the workflows, which load cpflow's composite actions from the pinned upstream ref, and also writes `bin/test-cpflow-github-flow` for local validation and `bin/pin-cpflow-github-ref` for temporarily pinning downstream wrappers to an upstream commit SHA during pre-release testing. `cpflow generate` already switches to persistent `/app/data` and `/app/storage` volumes when `config/database.yml` shows SQLite in production, redirects every detected production SQLite database into persistent storage, keeps migrations visible under `/app/db`, and preserves detected frontend precompile hooks. You should still confirm that the generated Dockerfile picked a Ruby base image compatible with the app's declared Ruby requirement and that the emitted workload set matches the real app. If you want an AI agent to do this end to end, give it the [AI rollout prompt](./docs/ai-github-flow-prompt.md) rather than a vague "set up CI" request.
 
 For a live example, see the [react-webpack-rails-tutorial](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/.controlplane/readme.md) repository.
 

data/docs/ai-github-flow-prompt.md

@@ -8,13 +8,109 @@ first.
 ## Recommended Prompt
 
 ```text
-Set up Control Plane GitHub Flow for this repo. First make sure the `cpflow` CLI is available: use the repo's existing `bundle exec cpflow` if present, otherwise install the published `cpflow` Ruby gem with `gem install cpflow`; if neither is possible, stop and report that blocker. Use the same `cpflow` invocation for the rest of the rollout. Start with `cpflow github-flow-readiness` and stop on any reported blockers. The repo must be deployable from a clean clone: published package versions, complete runtime scaffold, and a production Dockerfile that can build the app. If any package version is unpublished, inaccessible from CI, or requires credentials that are not already modeled in the repo or GitHub settings, stop and report the blocker instead of generating workflow files. If the repo is a legacy sample pinned to an obsolete Ruby or Bundler toolchain, if it does not even have a production Dockerfile yet, or if it is a monorepo without an already-decided single app boundary for this flow, stop and report that as a prerequisite instead of forcing the rollout.
-
-If `.controlplane/` is missing, run `cpflow generate`. Treat the generated app names as the repo-name default and rename them only if the project needs a different prefix. Then run `cpflow generate-github-actions` (or `cpflow generate-github-actions --staging-branch BRANCH` when staging should deploy from a branch other than `main`/`master`), keep review apps opt-in via `+review-app-deploy`, make sure any `STAGING_APP_BRANCH` repository variable is also present in the generated staging workflow's `on.push.branches` filter, and list the GitHub secrets and variables that must be configured. Do not hand-edit duplicated upstream refs into the generated wrappers. Keep every generated Control Plane Flow source pin synchronized at the same `vX.Y.Z`: each reusable-workflow `uses: ...@vX.Y.Z` ref, the production promotion `.cpflow` checkout ref, and its `control_plane_flow_ref` setup input. By default, `cpflow generate-github-actions` derives these values from the installed `cpflow` gem version; temporary explicit ref overrides are for unreleased testing and must keep all three values synchronized. Keep the generated `.github/actions/cpflow-*` files from that same gem unchanged; upstream reusable workflows invoke those checked-in local actions and separately check out the matching runtime source at `.cpflow`. When bumping the `cpflow` gem in a downstream repo, `cpflow update-github-actions` refreshes local actions and helpers while preserving all top-level workflows, including their refs and triggers. Use `cpflow update-github-actions --workflows FILE...` to explicitly select wrappers for replacement, then review the diff and reapply downstream customizations. A differing existing validator blocks all writes: preserve its downstream checks in executable `bin/test-cpflow-github-flow-custom`, then remove or rename the old generated validator before retrying. The generated validator invokes that preserved extension and propagates its failures. Follow `docs/ci-automation.md` for the migration procedure, keep source pins compatible with the updated actions, and run `bin/test-cpflow-github-flow` in the same PR (or `bin/test-cpflow-github-flow bundle exec cpflow` when using Bundler). Keep the normal generated review-app setup simple: review apps require only `CPLN_TOKEN_STAGING` when the generated review app config can be inferred. For public demos, starter staging apps, and long-lived review apps, keep the app workload `type: standard` with one warm replica, set its autoscaling metric to `disabled`, and enable `capacityAI: true` so Control Plane can right-size CPU and memory allocation at that fixed replica count. Shared Postgres and other stateful workloads are the usual exceptions and should stay manually sized; Capacity AI is for supported stateless app/service workloads. If true idle scale-to-zero is explicitly required, create a separate `serverless` workload before first deploy or plan a delete/recreate migration because Control Plane will not change an existing `standard` workload to `serverless` in place. For shared review-app resources such as one staging database, use `shared_secret_grants` and `{{SHARED_SECRET_DATABASE}}` placeholders instead of hardcoding the base app secret name; this keeps review-app policy binding and cleanup automatic while avoiding per-PR database cost. Document the one-time Control Plane bootstrap command for persistent staging and production apps with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates, document `cpflow apply-template` and the need for the app identity to have `reveal` on the app secret policy. Do not imply the staging deploy or promotion workflows create those persistent GVCs. For production promotion, document a protected `production` GitHub Environment with required reviewers, prevent self-review, and `CPLN_TOKEN_PRODUCTION` stored as an environment secret, not as a repository or organization secret.
-
-Keep Node available in the final image if asset compilation or SSR depends on ExecJS, Yarn, `pnpm`, or npm after the main install layer. Make sure the generated Dockerfile uses a Ruby base image compatible with the app's declared Ruby requirement. Preserve repo-defined frontend build hooks: if `config/shakapacker.yml` defines a `precompile_hook`, or React on Rails enables `config.auto_load_bundle = true`, confirm the generated Dockerfile runs that codegen step before `rails assets:precompile`. If `config/database.yml` shows SQLite in production, confirm that the generated scaffold redirects every production database file into persistent `/app/data` (or keeps it under persistent `/app/storage`) without mounting over the image's `/app/db` migrations, stores Active Storage under `/app/storage`, and runs `rails db:prepare`; otherwise keep the default Postgres workload. If the public workload is not named `rails`, set `PRIMARY_WORKLOAD` or adjust the generated workflows. Inspect the Dockerfile and package sources for private GitHub dependencies or `RUN --mount=type=ssh`; if present, wire `DOCKER_BUILD_SSH_KEY`, optionally set `DOCKER_BUILD_SSH_KNOWN_HOSTS` for non-GitHub SSH hosts, and keep `DOCKER_BUILD_EXTRA_ARGS` to newline-delimited single tokens such as `--build-arg=FOO=bar`.
-
-Run the real local validations you can: Docker build if feasible, repo tests or smoke checks, YAML validation, and any CI-equivalent build steps. Push the branch and check the GitHub Actions results. Only stop early for a real external blocker or a product decision that changes scope.
+Set up Control Plane GitHub Flow for this repo.
+
+Before generating anything:
+- First make sure the `cpflow` CLI is available: use the repo's existing `bundle exec cpflow` if
+  present, otherwise install the published `cpflow` Ruby gem with `gem install cpflow`; if neither
+  is possible, stop and report that blocker.
+- Use the same `cpflow` invocation for the rest of the rollout.
+- Start with `cpflow github-flow-readiness` and stop on any reported blockers.
+- The repo must be deployable from a clean clone: published package versions, complete runtime
+  scaffold, and a production Dockerfile that can build the app.
+- If any package version is unpublished, inaccessible from CI, or requires credentials that are not
+  already modeled in the repo or GitHub settings, stop and report the blocker instead of generating
+  workflow files.
+- If the repo is a legacy sample pinned to an obsolete Ruby or Bundler toolchain, if it does not
+  even have a production Dockerfile yet, or if it is a monorepo without an already-decided single
+  app boundary for this flow, stop and report that as a prerequisite instead of forcing the rollout.
+
+Generate the flow:
+- If `.controlplane/` is missing, run `cpflow generate`.
+- Treat the generated app names as the repo-name default and rename them only if the
+  project needs a different prefix.
+- Then run `cpflow generate-github-actions` (or `cpflow generate-github-actions --staging-branch
+  BRANCH` when staging should deploy from a branch other than `main`/`master`).
+- Keep review apps opt-in via `+review-app-deploy`.
+- Make sure any `STAGING_APP_BRANCH` repository variable is also present in the generated staging
+  workflow's `on.push.branches` filter.
+- List the GitHub secrets and variables that must be configured.
+
+Keep the Control Plane Flow source pins together:
+- Do not hand-edit duplicated upstream refs into the generated wrappers.
+- Keep every generated Control Plane Flow source pin synchronized at the same `vX.Y.Z`: each
+  reusable-workflow `uses: ...@vX.Y.Z` ref, the production promotion `.cpflow` checkout ref, and its
+  `control_plane_flow_ref` setup input.
+- By default, `cpflow generate-github-actions` derives these values from the installed `cpflow` gem
+  version; temporary explicit ref overrides are for unreleased testing and must keep all three
+  values synchronized.
+- Do not add `.github/actions/cpflow-*` copies; the workflows load cpflow's composite actions and
+  runtime source from the pinned `.cpflow` checkout.
+
+When bumping the `cpflow` gem in a downstream repo:
+- `cpflow update-github-actions` refreshes helpers while preserving all top-level workflows,
+  including their refs and triggers.
+- It reports `.github/actions/cpflow-*` copies left by cpflow 6.0.0; delete them once no workflow is
+  pinned to 6.0.0 or names one.
+- Use `cpflow update-github-actions --workflows FILE...` to explicitly select wrappers for
+  replacement, then review the diff and reapply downstream customizations.
+- A differing existing validator blocks all writes: preserve its downstream checks in executable
+  `bin/test-cpflow-github-flow-custom`, then remove or rename the old generated validator before
+  retrying.
+- The generated validator invokes that preserved extension and propagates its failures.
+- Follow `docs/ci-automation.md` for the migration procedure, keep source pins compatible with the
+  updated actions, and run `bin/test-cpflow-github-flow` in the same PR (or
+  `bin/test-cpflow-github-flow bundle exec cpflow` when using Bundler).
+
+Review apps and workload sizing:
+- Keep the normal generated review-app setup simple: review apps require only `CPLN_TOKEN_STAGING`
+  when the generated review app config can be inferred.
+- For public demos, starter staging apps, and long-lived review apps, keep the app workload `type:
+  standard` with one warm replica, set its autoscaling metric to `disabled`, and enable `capacityAI:
+  true` so Control Plane can right-size CPU and memory allocation at that fixed replica count.
+- Shared Postgres and other stateful workloads are the usual exceptions and should stay manually
+  sized; Capacity AI is for supported stateless app/service workloads.
+- If true idle scale-to-zero is explicitly required, create a separate `serverless` workload before
+  first deploy or plan a delete/recreate migration because Control Plane will not change an existing
+  `standard` workload to `serverless` in place.
+- For shared review-app resources such as one staging database, use `shared_secret_grants` and
+  `{{SHARED_SECRET_DATABASE}}` placeholders instead of hardcoding the base app secret name; this
+  keeps review-app policy binding and cleanup automatic while avoiding per-PR database cost.
+
+Staging and production:
+- Document the one-time Control Plane bootstrap command for persistent staging and production apps
+  with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates,
+  document `cpflow apply-template` and the need for the app identity to have `reveal` on the app
+  secret policy.
+- Do not imply the staging deploy or promotion workflows create those persistent GVCs.
+- For production promotion, document a protected `production` GitHub Environment with required
+  reviewers, prevent self-review, and `CPLN_TOKEN_PRODUCTION` stored as an environment secret, not
+  as a repository or organization secret.
+
+Docker image and runtime:
+- Keep Node available in the final image if asset compilation or SSR depends on ExecJS, Yarn,
+  `pnpm`, or npm after the main install layer.
+- Make sure the generated Dockerfile uses a Ruby base image compatible with the app's declared Ruby
+  requirement.
+- Preserve repo-defined frontend build hooks: if `config/shakapacker.yml` defines a
+  `precompile_hook`, or React on Rails enables `config.auto_load_bundle = true`, confirm the
+  generated Dockerfile runs that codegen step before `rails assets:precompile`.
+- If `config/database.yml` shows SQLite in production, confirm that the generated scaffold redirects
+  every production database file into persistent `/app/data` (or keeps it under persistent
+  `/app/storage`) without mounting over the image's `/app/db` migrations, stores Active Storage
+  under `/app/storage`, and runs `rails db:prepare`; otherwise keep the default Postgres workload.
+- If the public workload is not named `rails`, set `PRIMARY_WORKLOAD` or adjust the generated
+  workflows.
+- Inspect the Dockerfile and package sources for private GitHub dependencies or `RUN
+  --mount=type=ssh`; if present, wire `DOCKER_BUILD_SSH_KEY`, optionally set
+  `DOCKER_BUILD_SSH_KNOWN_HOSTS` for non-GitHub SSH hosts, and keep `DOCKER_BUILD_EXTRA_ARGS` to
+  newline-delimited single tokens such as `--build-arg=FOO=bar`.
+
+Validate and finish:
+- Run the real local validations you can: Docker build if feasible, repo tests or smoke checks, YAML
+  validation, and any CI-equivalent build steps.
+- Push the branch and check the GitHub Actions results.
+- Only stop early for a real external blocker or a product decision that changes scope.
 ```
 
 ## Local Shortcut
@@ -46,7 +142,7 @@ Stop and report the blocker instead of generating `cpflow-*` workflow files when
 The rollout is done when all of the following are true:
 
 - `.controlplane/` exists and matches the actual app shape
-- `.github/cpflow-help.md`, `.github/workflows/cpflow-*`, and `.github/actions/cpflow-*` are in place
+- `.github/cpflow-help.md` and `.github/workflows/cpflow-*` are in place, with no `.github/actions/cpflow-*` copies
 - review apps are opt-in, staging auto-deploys from one branch, and production promotion is manual
 - required GitHub secrets and variables are documented for the repo
 - the production image build path is validated for the real app

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 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.
+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 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,7 +69,6 @@ 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`
 
@@ -268,8 +267,7 @@ 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.
+replacement. The bare update command preserves existing top-level workflows.
 
 ### Recover a missing or stale production release record
 
@@ -538,12 +536,11 @@ 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. 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;
+  comment permission gate. The reusable deploy workflow loads its composite actions from `shakacode/control-plane-flow`
+  at the commit the wrapper pins, never from the pull request's revision; see
+  [Where the actions run from](#where-the-actions-run-from). Preserve the same-repository caller guard because a
+  same-repository pull request can still change the wrapper and the application code that 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
@@ -579,11 +576,10 @@ 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 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
+on any app whose name does not match the review-app prefix. This shell-level guard is effective because the delete
+workflow loads that action from the wrapper-pinned `.cpflow` commit. Its separate app checkout has no `ref:` override,
+which resolves to the commit GitHub recorded for the triggering event (`GITHUB_SHA`, the base-branch tip under
+`pull_request_target`), so teardown reads base-branch configuration 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
@@ -795,18 +791,36 @@ wrapper-level `if:` guard shown in that file, for example
 ## Upstream Workflows And Actions
 
 Most generated workflows are intentionally small wrappers. The deployment
-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.
+logic and comment formatting live in upstream reusable workflows, and the
+composite actions they call live in this repository. Each job checks out
+`shakacode/control-plane-flow` at the pinned ref into `.cpflow`, then runs the
+actions as `./.cpflow/.github/actions/cpflow-*` and builds the `cpflow` runtime
+from the same checkout. A downstream repository carries the wrappers and one
+pinned ref, with no copies of the actions. Production promotion is expanded
+into the caller repository so it can own `environment: production`; it pins the
+same source in its own `.cpflow` checkout.
 
 - `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
 - `cpflow-delete-control-plane-app`: safely deletes temporary apps and refuses to touch names outside the configured review-app prefix
 
+### Where the actions run from
+
+The actions that receive `CPLN_TOKEN_STAGING` come from
+`shakacode/control-plane-flow` at the commit the calling wrapper pins. For a
+reusable workflow that is `job.workflow_sha`; for production promotion it is the
+`ref:` of the `Checkout control-plane-flow actions` step.
+
+A same-repository pull request can change the wrapper, including its pinned
+ref, and the application code and `.controlplane/` configuration that the
+deployment builds. It cannot change the action code without changing that pin,
+so reviewing the pin reviews the actions. The review-app jobs check out caller
+files only under `app/`, and never at the workspace root.
+
+cpflow 6.0.0 instead ran copies of the actions from the caller repository at
+the triggering revision. See
+[Removing cpflow 6.0.0 action copies](#removing-cpflow-600-action-copies).
+
 ## Version Pins: GitHub Ref vs RubyGems
 
 Generated `cpflow-*` workflow files pin `shakacode/control-plane-flow` from
@@ -828,22 +842,22 @@ that input outside the production promotion setup step, regenerate with a newer
 
 There are two coordinated inputs, and they protect different things:
 
-- 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.
+- The GitHub ref locks the reusable workflow, its composite actions, and the
+  `.cpflow` runtime source checkout that GitHub runs.
+- The installed Ruby gem supplies the generated 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 the generated wrappers and local actions from the gem
-that matches the upstream release tag:
+developers must commit the generated wrappers 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 and `.github/actions/cpflow-*` files; the
-   wrappers should point to the matching upstream release tag such as `v5.0.0`.
+4. Commit the generated wrappers; they 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
@@ -852,8 +866,8 @@ 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
+generated wrappers, 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
@@ -863,14 +877,14 @@ aliases and branches remain forbidden.
 
 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.
+new reusable workflow YAML by itself; GitHub uses the workflow ref 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 workflows and actions:
+Use the installed gem to refresh the generated files:
 
 ```sh
 cpflow update-github-actions
@@ -884,7 +898,7 @@ bundle exec cpflow update-github-actions
 bin/test-cpflow-github-flow bundle exec cpflow
 ```
 
-`cpflow update-github-actions` refreshes local composite actions and helpers.
+`cpflow update-github-actions` refreshes the generated 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.
@@ -901,13 +915,36 @@ bundle exec cpflow update-github-actions --workflows \
 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
+that old wrappers are compatible with the new release. 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`.
 
+### Removing cpflow 6.0.0 action copies
+
+cpflow 6.0.0 generated `.github/actions/cpflow-*` and ran those copies. Later
+releases load the actions from the pinned ref, so the copies are unused once
+every workflow has moved off 6.0.0:
+
+1. Update the gem, then replace the wrappers and the production promotion
+   workflow with `cpflow update-github-actions --workflows FILE...`. Reapply
+   downstream customizations.
+2. Confirm that no workflow is still pinned to cpflow 6.0.0 and that none has a
+   `uses: ./.github/actions/cpflow-*` line. In a workflow you maintain by hand,
+   change each such line to `uses: ./.cpflow/.github/actions/cpflow-*`.
+3. Delete the copies with `git rm -r .github/actions/cpflow-*`, delete any
+   downstream check that compares them with the gem, and run
+   `bin/test-cpflow-github-flow`.
+
+`cpflow update-github-actions` lists the copies it finds and never deletes
+them. A wrapper pinned to 6.0.0 runs them without naming them, and a full-SHA
+pin does not say which release it is, so the command cannot prove a copy is
+unused. Until step 3 the copies are harmless: a wrapper pinned to a later
+release never reads them. The validator fails when a workflow names a copy
+that is not checked in.
+
 ### Preserving downstream validation
 
 The generated `bin/test-cpflow-github-flow` runs baseline checks followed by
@@ -949,7 +986,7 @@ trusted_actions:
 ```
 
 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
+`ruby/setup-ruby` is used by cpflow's 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
@@ -999,8 +1036,7 @@ 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. Refresh the generated local
-actions from that checkout before testing as described below.
+same source that supplies the reusable workflow and its actions.
 
 ## Testing Unreleased Upstream Changes Downstream
 
@@ -1016,8 +1052,7 @@ releasing it. Use an immutable commit SHA from the upstream PR branch:
    bin/pin-cpflow-github-ref --version <reviewed-version-tag> <upstream-pr-sha>
    ```
 
-   The update command copies the PR checkout's canonical composite actions into
-   `.github/actions/cpflow-*`. The pin helper then updates every generated
+   The pin 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 (with a reviewed `--version` label), rejects branch names such as `main` or
@@ -1045,19 +1080,18 @@ releasing it. Use an immutable commit SHA from the upstream PR branch:
    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:
+   present on the default branch, dispatch the workflow definition 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;
+   The `--ref` selects the downstream wrapper 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.
+   validate unmerged wrappers.
 
    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
@@ -1078,9 +1112,9 @@ releasing it. Use an immutable commit SHA from the upstream PR branch:
    `bin/pin-cpflow-github-ref vX.Y.Z` only for a ref-only update when the
    generated templates are already current.
 
-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
+For an existing installation, this tests the real reusable workflows, their
+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.
 

data/docs/commands.md

@@ -234,8 +234,8 @@ 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.
+The workflows load cpflow's composite actions from this gem's repository at
+the ref each workflow pins, so no `.github/actions/cpflow-*` copies are generated.
 
 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
@@ -245,7 +245,7 @@ Pass `--force` to overwrite existing generated files. Prefer
 repo.
 
 ```sh
-# Creates workflow wrappers, local composite actions, and validation helpers
+# Creates workflow wrappers and validation helpers
 cpflow generate-github-actions
 
 # Creates the flow with staging deploys triggered from develop
@@ -591,11 +591,14 @@ cpflow terraform import
 
 ### `update-github-actions`
 
-Refreshes local composite actions and helper files from the installed gem.
+Refreshes helper files from the installed gem. Workflows load cpflow's
+composite actions from the pinned cpflow ref, so the command reports any
+`.github/actions/cpflow-*` copies left by cpflow 6.0.0 for you to delete
+once no workflow is pinned to 6.0.0. It never deletes them itself.
 All top-level workflows are preserved by default, including their refs,
 triggers, permissions, and deployment ownership. Use --workflows FILE...
 to explicitly add or replace named generated workflows. Replacement resets
-each selected workflow to its template and matching v6.0.0 ref;
+each selected workflow to its template and matching v6.0.1 ref;
 review and reapply any downstream customizations in the same PR.
 
 Selecting cpflow-deploy-staging.yml preserves a single existing push branch
@@ -609,7 +612,7 @@ invokes that extension after its baseline checks; the extension is never
 generated or overwritten. See docs/ci-automation.md for migration guidance.
 
 ```sh
-# Refresh actions/helpers while preserving downstream workflows
+# Refresh helpers while preserving downstream workflows
 cpflow update-github-actions
 
 # When running cpflow through Bundler

data/lib/command/ai_github_flow_prompt.rb

@@ -22,24 +22,21 @@ module Command
     VALIDATIONS = [].freeze
     REQUIRES_STARTUP_CHECKS = false
 
+    # The prompt lives in its own file with one instruction per bullet, so a person can read it and
+    # a change shows as a small diff. docs/ai-github-flow-prompt.md carries the same text with no app
+    # prefix; a spec keeps the two equal.
+    PROMPT_PATH = File.expand_path("ai_github_flow_prompt.txt", __dir__)
+
+    def self.text(app_prefix: nil)
+      format(File.read(PROMPT_PATH), prefix_note: app_prefix ? " (`#{app_prefix}`)" : "")
+    end
+
     def call
-      puts prompt
+      puts self.class.text(app_prefix: inferred_app_prefix)
     end
 
     private
 
-    def prompt
-      <<~PROMPT
-        Set up Control Plane GitHub Flow for this repo. First make sure the `cpflow` CLI is available: use the repo's existing `bundle exec cpflow` if present, otherwise install the published `cpflow` Ruby gem with `gem install cpflow`; if neither is possible, stop and report that blocker. Use the same `cpflow` invocation for the rest of the rollout. Start with `cpflow github-flow-readiness` and stop on any reported blockers. The repo must be deployable from a clean clone: published package versions, complete runtime scaffold, and a production Dockerfile that can build the app. If any package version is unpublished, inaccessible from CI, or requires credentials that are not already modeled in the repo or GitHub settings, stop and report the blocker instead of generating workflow files. If the repo is a legacy sample pinned to an obsolete Ruby or Bundler toolchain, if it does not even have a production Dockerfile yet, or if it is a monorepo without an already-decided single app boundary for this flow, stop and report that as a prerequisite instead of forcing the rollout.
-
-        If `.controlplane/` is missing, run `cpflow generate`. Treat the generated app names as the repo-name default (`#{inferred_app_prefix}`) and rename them only if the project needs a different prefix. Then run `cpflow generate-github-actions` (or `cpflow generate-github-actions --staging-branch BRANCH` when staging should deploy from a branch other than `main`/`master`), keep review apps opt-in via `+review-app-deploy`, make sure any `STAGING_APP_BRANCH` repository variable is also present in the generated staging workflow's `on.push.branches` filter, and list the GitHub secrets and variables that must be configured. Do not hand-edit duplicated upstream refs into the generated wrappers. Keep every generated Control Plane Flow source pin synchronized at the same `vX.Y.Z`: each reusable-workflow `uses: ...@vX.Y.Z` ref, the production promotion `.cpflow` checkout ref, and its `control_plane_flow_ref` setup input. By default, `cpflow generate-github-actions` derives these values from the installed `cpflow` gem version; temporary explicit ref overrides are for unreleased testing and must keep all three values synchronized. Keep the generated `.github/actions/cpflow-*` files from that same gem unchanged; upstream reusable workflows invoke those checked-in local actions and separately check out the matching runtime source at `.cpflow`. When bumping the `cpflow` gem in a downstream repo, `cpflow update-github-actions` refreshes local actions and helpers while preserving all top-level workflows, including their refs and triggers. Use `cpflow update-github-actions --workflows FILE...` to explicitly select wrappers for replacement, then review the diff and reapply downstream customizations. A differing existing validator blocks all writes: preserve its downstream checks in executable `bin/test-cpflow-github-flow-custom`, then remove or rename the old generated validator before retrying. The generated validator invokes that preserved extension and propagates its failures. Follow `docs/ci-automation.md` for the migration procedure, keep source pins compatible with the updated actions, and run `bin/test-cpflow-github-flow` in the same PR (or `bin/test-cpflow-github-flow bundle exec cpflow` when using Bundler). Keep the normal generated review-app setup simple: review apps require only `CPLN_TOKEN_STAGING` when the generated review app config can be inferred. For public demos, starter staging apps, and long-lived review apps, keep the app workload `type: standard` with one warm replica, set its autoscaling metric to `disabled`, and enable `capacityAI: true` so Control Plane can right-size CPU and memory allocation at that fixed replica count. Shared Postgres and other stateful workloads are the usual exceptions and should stay manually sized; Capacity AI is for supported stateless app/service workloads. If true idle scale-to-zero is explicitly required, create a separate `serverless` workload before first deploy or plan a delete/recreate migration because Control Plane will not change an existing `standard` workload to `serverless` in place. For shared review-app resources such as one staging database, use `shared_secret_grants` and `{{SHARED_SECRET_DATABASE}}` placeholders instead of hardcoding the base app secret name; this keeps review-app policy binding and cleanup automatic while avoiding per-PR database cost. Document the one-time Control Plane bootstrap command for persistent staging and production apps with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates, document `cpflow apply-template` and the need for the app identity to have `reveal` on the app secret policy. Do not imply the staging deploy or promotion workflows create those persistent GVCs. For production promotion, document a protected `production` GitHub Environment with required reviewers, prevent self-review, and `CPLN_TOKEN_PRODUCTION` stored as an environment secret, not as a repository or organization secret.
-
-        Keep Node available in the final image if asset compilation or SSR depends on ExecJS, Yarn, `pnpm`, or npm after the main install layer. Make sure the generated Dockerfile uses a Ruby base image compatible with the app's declared Ruby requirement. Preserve repo-defined frontend build hooks: if `config/shakapacker.yml` defines a `precompile_hook`, or React on Rails enables `config.auto_load_bundle = true`, confirm the generated Dockerfile runs that codegen step before `rails assets:precompile`. If `config/database.yml` shows SQLite in production, confirm that the generated scaffold redirects every production database file into persistent `/app/data` (or keeps it under persistent `/app/storage`) without mounting over the image's `/app/db` migrations, stores Active Storage under `/app/storage`, and runs `rails db:prepare`; otherwise keep the default Postgres workload. If the public workload is not named `rails`, set `PRIMARY_WORKLOAD` or adjust the generated workflows. Inspect the Dockerfile and package sources for private GitHub dependencies or `RUN --mount=type=ssh`; if present, wire `DOCKER_BUILD_SSH_KEY`, optionally set `DOCKER_BUILD_SSH_KNOWN_HOSTS` for non-GitHub SSH hosts, and keep `DOCKER_BUILD_EXTRA_ARGS` to newline-delimited single tokens such as `--build-arg=FOO=bar`.
-
-        Run the real local validations you can: Docker build if feasible, repo tests or smoke checks, YAML validation, and any CI-equivalent build steps. Push the branch and check the GitHub Actions results. Only stop early for a real external blocker or a product decision that changes scope.
-      PROMPT
-    end
-
     def inferred_app_prefix
       RepoIntrospection.inferred_app_prefix(Dir.pwd)
     end

data/lib/command/ai_github_flow_prompt.txt

@@ -0,0 +1,103 @@
+Set up Control Plane GitHub Flow for this repo.
+
+Before generating anything:
+- First make sure the `cpflow` CLI is available: use the repo's existing `bundle exec cpflow` if
+  present, otherwise install the published `cpflow` Ruby gem with `gem install cpflow`; if neither
+  is possible, stop and report that blocker.
+- Use the same `cpflow` invocation for the rest of the rollout.
+- Start with `cpflow github-flow-readiness` and stop on any reported blockers.
+- The repo must be deployable from a clean clone: published package versions, complete runtime
+  scaffold, and a production Dockerfile that can build the app.
+- If any package version is unpublished, inaccessible from CI, or requires credentials that are not
+  already modeled in the repo or GitHub settings, stop and report the blocker instead of generating
+  workflow files.
+- If the repo is a legacy sample pinned to an obsolete Ruby or Bundler toolchain, if it does not
+  even have a production Dockerfile yet, or if it is a monorepo without an already-decided single
+  app boundary for this flow, stop and report that as a prerequisite instead of forcing the rollout.
+
+Generate the flow:
+- If `.controlplane/` is missing, run `cpflow generate`.
+- Treat the generated app names as the repo-name default%<prefix_note>s and rename them only if the
+  project needs a different prefix.
+- Then run `cpflow generate-github-actions` (or `cpflow generate-github-actions --staging-branch
+  BRANCH` when staging should deploy from a branch other than `main`/`master`).
+- Keep review apps opt-in via `+review-app-deploy`.
+- Make sure any `STAGING_APP_BRANCH` repository variable is also present in the generated staging
+  workflow's `on.push.branches` filter.
+- List the GitHub secrets and variables that must be configured.
+
+Keep the Control Plane Flow source pins together:
+- Do not hand-edit duplicated upstream refs into the generated wrappers.
+- Keep every generated Control Plane Flow source pin synchronized at the same `vX.Y.Z`: each
+  reusable-workflow `uses: ...@vX.Y.Z` ref, the production promotion `.cpflow` checkout ref, and its
+  `control_plane_flow_ref` setup input.
+- By default, `cpflow generate-github-actions` derives these values from the installed `cpflow` gem
+  version; temporary explicit ref overrides are for unreleased testing and must keep all three
+  values synchronized.
+- Do not add `.github/actions/cpflow-*` copies; the workflows load cpflow's composite actions and
+  runtime source from the pinned `.cpflow` checkout.
+
+When bumping the `cpflow` gem in a downstream repo:
+- `cpflow update-github-actions` refreshes helpers while preserving all top-level workflows,
+  including their refs and triggers.
+- It reports `.github/actions/cpflow-*` copies left by cpflow 6.0.0; delete them once no workflow is
+  pinned to 6.0.0 or names one.
+- Use `cpflow update-github-actions --workflows FILE...` to explicitly select wrappers for
+  replacement, then review the diff and reapply downstream customizations.
+- A differing existing validator blocks all writes: preserve its downstream checks in executable
+  `bin/test-cpflow-github-flow-custom`, then remove or rename the old generated validator before
+  retrying.
+- The generated validator invokes that preserved extension and propagates its failures.
+- Follow `docs/ci-automation.md` for the migration procedure, keep source pins compatible with the
+  updated actions, and run `bin/test-cpflow-github-flow` in the same PR (or
+  `bin/test-cpflow-github-flow bundle exec cpflow` when using Bundler).
+
+Review apps and workload sizing:
+- Keep the normal generated review-app setup simple: review apps require only `CPLN_TOKEN_STAGING`
+  when the generated review app config can be inferred.
+- For public demos, starter staging apps, and long-lived review apps, keep the app workload `type:
+  standard` with one warm replica, set its autoscaling metric to `disabled`, and enable `capacityAI:
+  true` so Control Plane can right-size CPU and memory allocation at that fixed replica count.
+- Shared Postgres and other stateful workloads are the usual exceptions and should stay manually
+  sized; Capacity AI is for supported stateless app/service workloads.
+- If true idle scale-to-zero is explicitly required, create a separate `serverless` workload before
+  first deploy or plan a delete/recreate migration because Control Plane will not change an existing
+  `standard` workload to `serverless` in place.
+- For shared review-app resources such as one staging database, use `shared_secret_grants` and
+  `{{SHARED_SECRET_DATABASE}}` placeholders instead of hardcoding the base app secret name; this
+  keeps review-app policy binding and cleanup automatic while avoiding per-PR database cost.
+
+Staging and production:
+- Document the one-time Control Plane bootstrap command for persistent staging and production apps
+  with `cpflow setup-app --skip-post-creation-hook`; for existing apps or later template updates,
+  document `cpflow apply-template` and the need for the app identity to have `reveal` on the app
+  secret policy.
+- Do not imply the staging deploy or promotion workflows create those persistent GVCs.
+- For production promotion, document a protected `production` GitHub Environment with required
+  reviewers, prevent self-review, and `CPLN_TOKEN_PRODUCTION` stored as an environment secret, not
+  as a repository or organization secret.
+
+Docker image and runtime:
+- Keep Node available in the final image if asset compilation or SSR depends on ExecJS, Yarn,
+  `pnpm`, or npm after the main install layer.
+- Make sure the generated Dockerfile uses a Ruby base image compatible with the app's declared Ruby
+  requirement.
+- Preserve repo-defined frontend build hooks: if `config/shakapacker.yml` defines a
+  `precompile_hook`, or React on Rails enables `config.auto_load_bundle = true`, confirm the
+  generated Dockerfile runs that codegen step before `rails assets:precompile`.
+- If `config/database.yml` shows SQLite in production, confirm that the generated scaffold redirects
+  every production database file into persistent `/app/data` (or keeps it under persistent
+  `/app/storage`) without mounting over the image's `/app/db` migrations, stores Active Storage
+  under `/app/storage`, and runs `rails db:prepare`; otherwise keep the default Postgres workload.
+- If the public workload is not named `rails`, set `PRIMARY_WORKLOAD` or adjust the generated
+  workflows.
+- Inspect the Dockerfile and package sources for private GitHub dependencies or `RUN
+  --mount=type=ssh`; if present, wire `DOCKER_BUILD_SSH_KEY`, optionally set
+  `DOCKER_BUILD_SSH_KNOWN_HOSTS` for non-GitHub SSH hosts, and keep `DOCKER_BUILD_EXTRA_ARGS` to
+  newline-delimited single tokens such as `--build-arg=FOO=bar`.
+
+Validate and finish:
+- Run the real local validations you can: Docker build if feasible, repo tests or smoke checks, YAML
+  validation, and any CI-equivalent build steps.
+- Push the branch and check the GitHub Actions results.
+- Only stop early for a real external blocker or a product decision that changes scope.

data/lib/command/generate_github_actions.rb

@@ -105,8 +105,8 @@ module Command
       - 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.
+      The workflows load cpflow's composite actions from this gem's repository at
+      the ref each workflow pins, so no `.github/actions/cpflow-*` copies are generated.
 
       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
@@ -117,7 +117,7 @@ module Command
     DESC
     EXAMPLES = <<~EX
       ```sh
-      # Creates workflow wrappers, local composite actions, and validation helpers
+      # Creates workflow wrappers and validation helpers
       cpflow generate-github-actions
 
       # Creates the flow with staging deploys triggered from develop
@@ -131,23 +131,16 @@ module Command
     VALIDATIONS = [].freeze
     REQUIRES_STARTUP_CHECKS = false
 
-    # Resolve source roots from __dir__ rather than Cpflow.root_path because this file is
+    # Resolve the source root from __dir__ rather than Cpflow.root_path because this file is
     # loaded before `module Cpflow` finishes defining its class methods.
-    REPOSITORY_ROOT = Pathname.new(File.expand_path("../..", __dir__))
     TEMPLATE_ROOT = Pathname.new(File.expand_path("../github_flow_templates", __dir__))
-    ACTIONS_ROOT = REPOSITORY_ROOT.join(".github/actions")
 
     def self.generated_file_sources
       ensure_template_root!
 
-      template_sources = files_beneath(TEMPLATE_ROOT).to_h do |source|
+      files_beneath(TEMPLATE_ROOT).to_h do |source|
         [source.relative_path_from(TEMPLATE_ROOT).to_s, source]
-      end
-      action_sources = files_beneath(ACTIONS_ROOT, "cpflow-*/**/*").to_h do |source|
-        [source.relative_path_from(REPOSITORY_ROOT).to_s, source]
-      end
-
-      template_sources.merge(action_sources).sort.to_h.freeze
+      end.sort.to_h.freeze
     end
 
     def self.generated_files
@@ -160,11 +153,10 @@ module Command
 
     def self.ensure_template_root!
       raise "cpflow template directory not found: #{TEMPLATE_ROOT}" unless TEMPLATE_ROOT.directory?
-      raise "cpflow action directory not found: #{ACTIONS_ROOT}" unless ACTIONS_ROOT.directory?
     end
 
-    def self.files_beneath(root, pattern = "**/*")
-      Dir.glob(root.join(pattern).to_s, File::FNM_DOTMATCH)
+    def self.files_beneath(root)
+      Dir.glob(root.join("**/*").to_s, File::FNM_DOTMATCH)
          .select { |path| File.file?(path) }
          .map { |path| Pathname.new(path) }
          .sort

data/lib/command/update_github_actions.rb

@@ -18,7 +18,10 @@ module Command
     }].freeze
     DESCRIPTION = "Regenerates GitHub Actions files for the installed cpflow version"
     LONG_DESCRIPTION = <<~DESC.freeze
-      Refreshes local composite actions and helper files from the installed gem.
+      Refreshes helper files from the installed gem. Workflows load cpflow's
+      composite actions from the pinned cpflow ref, so the command reports any
+      `.github/actions/cpflow-*` copies left by cpflow 6.0.0 for you to delete
+      once no workflow is pinned to 6.0.0. It never deletes them itself.
       All top-level workflows are preserved by default, including their refs,
       triggers, permissions, and deployment ownership. Use --workflows FILE...
       to explicitly add or replace named generated workflows. Replacement resets
@@ -37,7 +40,7 @@ module Command
     DESC
     EXAMPLES = <<~EX
       ```sh
-      # Refresh actions/helpers while preserving downstream workflows
+      # Refresh helpers while preserving downstream workflows
       cpflow update-github-actions
 
       # When running cpflow through Bundler
@@ -64,6 +67,7 @@ module Command
       branch = selected_staging_branch(workflows)
       abort_if_custom_validator!
       GithubActionsGenerator.new([branch].compact, workflows: workflows).invoke_all
+      report_vendored_actions
 
       print_post_update_message
     end
@@ -102,6 +106,7 @@ module Command
 
     def abort_if_no_generated_files!
       return if GenerateGithubActions.generated_files.any? { |path| File.exist?(path) }
+      return if vendored_action_directories.any?
 
       Shell.abort(<<~MESSAGE)
         No generated cpflow GitHub Actions files found in this repository.
@@ -110,6 +115,27 @@ module Command
       MESSAGE
     end
 
+    # cpflow 6.0.0 copied its composite actions here. Scan the caller's tree rather than this
+    # gem's action names, so a copy is still found after an action is renamed or removed.
+    def vendored_action_directories
+      Dir.glob(".github/actions/cpflow-*").select { |path| File.directory?(path) }.sort
+    end
+
+    # Whether a copy is still needed depends on the cpflow release each wrapper pins, which a
+    # full-SHA pin does not reveal, so deletion stays a reviewed human step.
+    def report_vendored_actions
+      directories = vendored_action_directories
+      return if directories.empty?
+
+      Shell.warn(<<~MESSAGE)
+        cpflow no longer generates or updates these local action copies:
+        #{directories.map { |path| "- #{path}" }.join("\n")}
+        A workflow pinned to cpflow 6.0.0 still runs them. Delete them once every cpflow workflow
+        in this repository is pinned to a later release and none has a
+        `uses: ./.github/actions/cpflow-*` line. See docs/ci-automation.md.
+      MESSAGE
+    end
+
     def print_post_update_message
       Shell.info("")
       Shell.info("Updated cpflow GitHub Actions files for cpflow #{Cpflow::VERSION}.")

data/lib/cpflow/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Cpflow
-  VERSION = "6.0.0"
+  VERSION = "6.0.1"
   MIN_CPLN_VERSION = "3.1.0"
 end

data/lib/github_flow_templates/.github/cpflow-help.md

@@ -152,8 +152,8 @@ validator, first preserve its downstream checks in executable
 `bin/test-cpflow-github-flow-custom`, then remove or rename the old generated
 validator before retrying the update.
 
-After updating the `cpflow` gem in this repo, refresh the generated local
-actions and validation helpers in the same PR. The default command
+After updating the `cpflow` gem in this repo, refresh the generated
+validation helpers in the same PR. The default command
 preserves every top-level workflow, including its refs, triggers, permissions, and
 downstream customizations:
 

data/lib/github_flow_templates/.github/workflows/cpflow-promote-staging-to-production.yml

@@ -85,7 +85,7 @@ jobs:
           echo "org=$org" >> "$GITHUB_OUTPUT"
 
       - name: Setup staging environment
-        uses: ./.github/actions/cpflow-setup-environment
+        uses: ./.cpflow/.github/actions/cpflow-setup-environment
         with:
           token: ${{ secrets.CPLN_TOKEN_STAGING }}
           org: ${{ steps.staging-org.outputs.org }}
@@ -97,7 +97,7 @@ jobs:
 
       - name: Preview commits before production approval
         id: preview
-        uses: ./.github/actions/cpflow-preview-promotion
+        uses: ./.cpflow/.github/actions/cpflow-preview-promotion
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GH_REPO: ${{ github.repository }}
@@ -156,7 +156,7 @@ jobs:
           fi
 
       - name: Validate required secrets and variables
-        uses: ./.github/actions/cpflow-validate-config
+        uses: ./.cpflow/.github/actions/cpflow-validate-config
         # Pass secrets via env so the composite action checks indirect shell
         # variables instead of interpolating secret values into a run script.
         env:
@@ -237,7 +237,7 @@ jobs:
           } >> "$GITHUB_OUTPUT"
 
       - name: Setup production environment
-        uses: ./.github/actions/cpflow-setup-environment
+        uses: ./.cpflow/.github/actions/cpflow-setup-environment
         with:
           token: ${{ secrets.CPLN_TOKEN_PRODUCTION }}
           org: ${{ steps.cpln-orgs.outputs.production }}
@@ -303,7 +303,7 @@ jobs:
 
       - name: Detect release phase support
         id: release-phase
-        uses: ./.github/actions/cpflow-detect-release-phase
+        uses: ./.cpflow/.github/actions/cpflow-detect-release-phase
         with:
           app_name: ${{ vars.PRODUCTION_APP_NAME }}
 
@@ -698,7 +698,7 @@ jobs:
 
       - name: Wait for deployment health
         id: health-check
-        uses: ./.github/actions/cpflow-wait-for-health
+        uses: ./.cpflow/.github/actions/cpflow-wait-for-health
         with:
           workload_name: ${{ steps.workloads.outputs.primary }}
           app_name: ${{ vars.PRODUCTION_APP_NAME }}

data/lib/github_flow_templates/bin/test-cpflow-github-flow

@@ -29,7 +29,11 @@ documents.each_key do |path|
   puts "parsed #{path}"
 end
 
-generated_local_action_pattern = %r{\A\./(?<directory>\.github/actions/cpflow-[a-z0-9]+(?:-[a-z0-9]+)*)\z}
+# Current workflows load cpflow actions from the pinned `.cpflow` checkout, which exists
+# only at run time. Caller-owned `.github/actions/cpflow-*` copies are the cpflow 6.0.0
+# layout; a workflow that still references one needs that copy checked in.
+generated_local_action_pattern =
+  %r{\A\./(?<checkout>\.cpflow/)?(?<directory>\.github/actions/cpflow-[a-z0-9]+(?:-[a-z0-9]+)*)\z}
 local_action_references = []
 invalid_local_action_references = []
 visited_container_ids = {}
@@ -43,10 +47,10 @@ walk = lambda do |node, source_path|
   case node
   when Hash
     uses = node["uses"]
-    if uses.is_a?(String) && uses.start_with?("./.github/actions/cpflow-")
+    if uses.is_a?(String) && uses.start_with?("./.github/actions/cpflow-", "./.cpflow/")
       match = uses.match(generated_local_action_pattern)
       if match
-        local_action_references << [source_path, match[:directory]]
+        local_action_references << [source_path, match[:directory]] unless match[:checkout]
       else
         invalid_local_action_references <<
           "#{source_path} has invalid generated local action reference #{uses}"
@@ -61,6 +65,24 @@ documents.each { |path, document| walk.call(document, path) }
 
 abort invalid_local_action_references.uniq.join("\n") unless invalid_local_action_references.empty?
 
+# `.cpflow` exists only after a job checks it out, so each job must do that before its first cpflow action.
+missing_checkouts = documents.flat_map do |path, document|
+  jobs = document.is_a?(Hash) && document["jobs"].is_a?(Hash) ? document["jobs"] : {}
+  jobs.filter_map do |job_name, job|
+    steps = job.is_a?(Hash) && job["steps"].is_a?(Array) ? job["steps"].grep(Hash) : []
+    first_action = steps.index { |step| step["uses"].to_s.start_with?("./.cpflow/") }
+    next unless first_action
+
+    checked_out = steps.take(first_action).any? do |step|
+      step["uses"].to_s.start_with?("actions/checkout@") &&
+        step["with"].is_a?(Hash) && step["with"]["path"] == ".cpflow" && !step["with"]["ref"].to_s.strip.empty?
+    end
+    "#{path}:#{job_name} must check out a pinned ref into .cpflow before its first cpflow action" unless checked_out
+  end
+end
+
+abort missing_checkouts.join("\n") unless missing_checkouts.empty?
+
 missing_actions = local_action_references.uniq.filter_map do |source_path, action_directory|
   directory_is_local = begin
     File.lstat(action_directory).directory?
@@ -79,7 +101,7 @@ missing_actions = local_action_references.uniq.filter_map do |source_path, actio
 end
 
 abort missing_actions.join("\n") unless missing_actions.empty?
-puts "all referenced local actions have checked-in descriptors"
+puts "all cpflow action references use the pinned checkout or a checked-in descriptor"
 RUBY
 
 echo "==> check composite action input descriptions"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cpflow
 version: !ruby/object:Gem::Version
-  version: 6.0.0
+  version: 6.0.1
 platform: ruby
 authors:
 - Justin Gordon
@@ -184,6 +184,7 @@ files:
 - examples/circleci.yml
 - examples/controlplane.yml
 - lib/command/ai_github_flow_prompt.rb
+- lib/command/ai_github_flow_prompt.txt
 - lib/command/apply_template.rb
 - lib/command/base.rb
 - lib/command/base_sub_command.rb
@@ -317,7 +318,7 @@ licenses:
 metadata:
   rubygems_mfa_required: 'true'
 post_install_message: |
-  cpflow 6.0.0 installed.
+  cpflow 6.0.1 installed.
   Generated GitHub Actions users: run `cpflow update-github-actions` after upgrading.
   Docs: https://github.com/shakacode/control-plane-flow/blob/main/docs/ci-automation.md#updating-generated-github-actions-after-gem-updates
 rdoc_options: []