cpflow 6.0.0.rc.0 → 6.0.0

data/docs/ci-automation.md

@@ -77,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
@@ -230,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
@@ -425,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:
 
@@ -570,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:
 
@@ -797,11 +884,88 @@ bundle exec cpflow update-github-actions
 bin/test-cpflow-github-flow bundle exec cpflow
 ```
 
-`cpflow update-github-actions` regenerates the workflow wrappers, local
-composite actions, and helper files from the installed gem, pins the wrapper
-`uses:` refs to `v<gem-version>`, and preserves a single custom staging branch
-from the existing generated staging workflow. Pass `--staging-branch BRANCH`
-when changing or restoring a custom staging branch explicitly.
+`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:
@@ -849,14 +1013,14 @@ releasing it. Use an immutable commit SHA from the upstream PR branch:
 
    ```sh
    ruby /path/to/control-plane-flow/bin/cpflow update-github-actions
-   bin/pin-cpflow-github-ref <upstream-pr-sha>
+   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
    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
+   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.
 
@@ -961,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:**
 
@@ -1005,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`

data/docs/commands.md

@@ -30,6 +30,7 @@ cpflow ai-github-flow-prompt
 - Picks templates from the `.controlplane/templates` directory
 - Templates are ordinary Control Plane templates but with variable preprocessing
 - Use `--preserve-existing-runtime` to retain each workload container's configured app image, even when the workload is unready, and skip existing secret resources entirely while applying other template changes
+- Use `--exclude-secret-template NAME` and `--exclude-policy-template NAME` to exclude exact named templates without changing workload image handling
 - Missing or invalid workload images use only an unambiguous app image from ready workloads; refresh fails before applying templates when no safe fallback exists
 
 **Preprocessed template variables:**
@@ -135,6 +136,7 @@ cpflow copy-image-from-upstream -a $APP_NAME --upstream-token $UPSTREAM_TOKEN --
 - Deletes the whole app (GVC with all workloads, all volumesets and all images) or a specific workload
 - Also unbinds the app from the secrets policy and any configured `shared_secret_grants` policies, as long as both the identity and each policy exist (and are bound)
 - For the app-specific secrets policy, removes every permission held by the app identity; for `shared_secret_grants`, removes only `reveal`
+- Removes a marked per-app dictionary and exact-target unbound policy for generated review credentials, including after the opt-in is removed from a dynamically matched review-app entry
 - Will ask for explicit user confirmation
 - Runs a pre-deletion hook before the app is deleted if `hooks.pre_deletion` is specified in the `.controlplane/controlplane.yml` file
 - If the hook exits with a non-zero code, the command will stop executing and also exit with a non-zero code
@@ -217,7 +219,7 @@ Creates base Control Plane config and template files for a Rails project:
 - infers the app prefix from the current directory and wires staging, review, and production entries
 - infers the Docker base Ruby version from `.ruby-version`, `.tool-versions`, or the app's `Gemfile`
 - preserves repo-defined asset precompile hooks, including React on Rails auto bundle generation
-- detects SQLite in `config/database.yml` and generates persistent `db` and `storage` volume templates instead of the default Postgres workload
+- detects SQLite in `config/database.yml` and generates persistent `/app/data` and `/app/storage` volume templates without hiding image migrations under `/app/db`
 
 ```sh
 # Creates .controlplane directory with Control Plane config and starter templates
@@ -558,13 +560,14 @@ cpflow run -a $APP_NAME --entrypoint /app/alternative-entrypoint.sh -- rails db:
 - Configures app to have org-level secrets with default name `"{APP_PREFIX}-secrets"`
   using org-level policy with default name `"{APP_PREFIX}-secrets-policy"` (names can be customized, see docs)
 - Creates identity for secrets if it does not exist
+- For dynamically named review apps with `generated_review_secret_keys`, checks an existing policy before writing credentials, creates a per-app dictionary, skips its secret template during initial setup, and fills missing disposable keys without printing or rotating values
 - Binds the app identity to any configured `shared_secret_grants` policies as part of the secrets setup flow; skipped when `--skip-secrets-setup` or `--skip-secret-access-binding` is provided, or `skip_secrets_setup` is set
 - Use `--skip-secrets-setup` to prevent the automatic setup of secrets,
   or set it through `skip_secrets_setup` in the `.controlplane/controlplane.yml` file
 - Runs a post-creation hook after the app is created if `hooks.post_creation` is specified in the `.controlplane/controlplane.yml` file
 - If the hook exits with a non-zero code, the command will stop executing and also exit with a non-zero code
 - Use `--skip-post-creation-hook` to skip the hook if specified in `controlplane.yml`
-- Use `--refresh-templates` to apply configured templates noninteractively to an existing app while preserving each workload's configured app image even when workloads are unready or use mixed image versions, skipping existing secret resources entirely, repairing secrets access bindings, and skipping the post-creation hook
+- Use `--refresh-templates` to apply configured templates noninteractively to an existing app while preserving each workload's configured app image even when workloads are unready or use mixed image versions, skipping existing secret templates (but filling missing opt-in generated review keys), repairing secrets access bindings, and skipping the post-creation hook
 
 ```sh
 cpflow setup-app -a $APP_NAME
@@ -588,25 +591,35 @@ cpflow terraform import
 
 ### `update-github-actions`
 
-Regenerates the cpflow workflow wrappers, local composite actions, and
-helper files from the currently installed cpflow gem. Use this after
-updating the cpflow gem so checked-in workflow wrappers move to the
-matching upstream release tag, for example `v5.3.0`, and the
-generated action implementations move with them.
+Refreshes local composite actions and helper files from the installed gem.
+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;
+review and reapply any downstream customizations in the same PR.
 
-If the existing generated staging workflow uses a custom single staging
-branch, the command preserves it. Pass `--staging-branch BRANCH` to set or
-replace the generated staging branch explicitly.
+Selecting cpflow-deploy-staging.yml preserves a single existing push branch
+or the default main/master pair. Missing or ambiguous branches require
+--staging-branch BRANCH. This option requires selecting the staging workflow.
+
+A differing existing bin/test-cpflow-github-flow blocks all writes. Move
+downstream checks to executable bin/test-cpflow-github-flow-custom and
+remove or rename the old validator before updating. The generated validator
+invokes that extension after its baseline checks; the extension is never
+generated or overwritten. See docs/ci-automation.md for migration guidance.
 
 ```sh
-# After updating the cpflow gem, refresh every generated GitHub Actions file
+# Refresh actions/helpers while preserving downstream workflows
 cpflow update-github-actions
 
 # When running cpflow through Bundler
 bundle exec cpflow update-github-actions
 
-# Preserve or set a custom staging branch
-cpflow update-github-actions --staging-branch develop
+# Explicitly replace the review-app wrapper
+cpflow update-github-actions --workflows cpflow-deploy-review-app.yml
+
+# Explicitly add or replace staging deployment from develop
+cpflow update-github-actions --workflows cpflow-deploy-staging.yml --staging-branch develop
 ```
 
 ### `version`

data/docs/postgres-review-apps.md

@@ -0,0 +1,90 @@
+# PostgreSQL for disposable review apps
+
+Use the generated `.controlplane/templates/postgres.yml` for a PostgreSQL workload
+that belongs to one disposable review app. For production database migration, see
+[Migrating PostgreSQL from Heroku to RDS](./postgres.md).
+
+## Enable cleanup for new review apps
+
+The generated template marks three helper resources:
+
+| Resource | Purpose |
+| --- | --- |
+| `<APP>-pg` | Credential dictionary |
+| `<APP>-pg-script` | Initialization-script secret |
+| `<APP>-pg-access` | Policy granting access to those secrets |
+
+Each helper template carries this tag:
+
+```yaml
+tags:
+  cpflow-disposable-postgres-app: "{{APP_NAME}}"
+```
+
+`cpflow apply-template` retains the tag for dynamically named review apps and removes
+it for persistent apps. In an existing project, add the tag to all three helper
+**templates before creating new review apps**. Reapplying a marked template to an
+existing unmarked resource is refused; it does not adopt that resource.
+
+Before opting in, check that your deployment token can:
+
+- Read and delete the three helper resources.
+- Read each secret's effective access report (`viewAccessReport` on the org).
+
+A missing or incomplete access report blocks cleanup before app data is deleted.
+
+## Delete an app
+
+Run the normal app deletion command:
+
+```sh
+cpflow delete -a APP_NAME
+```
+
+Cleanup validates the helpers before deleting app data. It removes the marked
+policy and secrets before deleting the GVC. Deleting a single workload with
+`cpflow delete -a APP_NAME -w WORKLOAD_NAME` preserves the helpers.
+
+The ownership checks require:
+
+- The same app marker on every surviving helper.
+- A policy targeting exactly the two helper secrets.
+- Only `reveal` grants in that policy, for the app and PostgreSQL identities in the
+  app's GVC.
+- No helper listed in `shared_secret_grants`.
+- No effective secret access through another application policy or identity.
+
+Reapplying marked helpers with `cpflow apply-template` uses the same checks.
+
+## Understand a cleanup refusal
+
+Cleanup preserves resources when a marker, policy, or access report cannot establish
+exclusive ownership. A refusal aborts whole-app deletion before live app data is
+deleted. Fix the reported condition before retrying; do not remove a
+sharing grant until you know which applications depend on it.
+
+| Condition | Result |
+| --- | --- |
+| All helpers are unmarked legacy resources | App deletion proceeds; helpers are preserved |
+| Marked and unmarked helpers coexist | Cleanup refuses deletion |
+| A marker names another app | Cleanup refuses deletion |
+| Policy targets or principals differ from the expected app scope | Cleanup refuses deletion |
+| A helper is configured as shared | Cleanup refuses deletion |
+| Secret access reports are unavailable or incomplete | Cleanup refuses deletion |
+
+The access checks include permissions implied by `edit` or `manage`. Global `manage`
+grants to org groups, users, or service accounts count as org administration.
+Targeted or query grants, and grants to other GVC identities, block cleanup.
+
+For shared staging credentials, use the
+[shared-secret configuration guide](./secrets-and-env-values.md#shared-secrets-for-review-apps)
+instead of marking them as disposable helpers.
+
+## Recover after interruption
+
+Repeat `cpflow delete` with the same app name. Cleanup tolerates an already absent
+GVC, policy, or secret and rechecks the surviving helpers before deleting them.
+
+Unmarked legacy helpers need manual cleanup after you establish that no other app
+uses them. Rolling back to an older cpflow version leaves the tags in place but
+stops automatic helper cleanup.