Keep caller layout as a candidate

Co-authored-by: Copilot App <[email protected]>

Author: MariusStorhaug

docs/content/get-started/repository-setup.md

@@ -65,8 +65,7 @@ permissions:
 
 jobs:
   Process-PSModule:
-    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v5
     secrets:
       PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
       GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}

docs/content/guides/calling-the-workflow.md

@@ -48,8 +48,7 @@ permissions:
 
 jobs:
   Process-PSModule:
-    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v5
     secrets:
       PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
       GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
@@ -68,15 +67,6 @@ the PowerShell Gallery, GitHub Releases, and tags, so later runs must queue rath
 The reusable workflow uses its own prefixed concurrency group, so it cannot queue behind the caller while the caller
 waits for it to finish.
 
-`Process-PSModule` is PSModule-owned automation, so callers use the controlled floating major tag (`@v8`). Compatible
-patch and minor releases move that tag through the release workflow. A breaking release publishes a new major tag and
-uses a deliberate fleet campaign rather than moving `v8` across the breaking boundary. External actions remain pinned
-to full commit SHAs.
-
-The job condition skips fork-originated pull requests because GitHub does not expose the required repository secrets to
-forks. Use a separate secret-free, read-only workflow if the repository accepts contributions from forks and requires
-fork CI.
-
 ## Passing test data
 
 The reusable workflow at `.github/workflows/workflow.yml` declares four workflow-call secrets,
@@ -104,8 +94,7 @@ changes:
 ```yaml
 jobs:
   Process-PSModule:
-    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v5
     secrets:
       PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
       GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
@@ -134,8 +123,7 @@ content lines stay at the same indentation level:
 ```yaml
 jobs:
   Process-PSModule:
-    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v5
     secrets:
       PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
       GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
@@ -247,8 +235,7 @@ You can also pass patterns via the workflow input:
 ```yaml
 jobs:
   Process:
-    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v5
     with:
       ImportantFilePatterns: |
         ^src/
@@ -261,8 +248,7 @@ To disable triggering via the workflow input, pass an explicit empty string:
 ```yaml
 jobs:
   process:
-    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v5
     with:
       ImportantFilePatterns: ''
 ```

docs/content/guides/github-app-authentication.md

@@ -23,8 +23,7 @@ names. Map the caller's secrets explicitly:
 ```yaml
 jobs:
   Process-PSModule:
-    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v5
     secrets:
       PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
       GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}

docs/content/reference/process-workflow-fleet-standard.md

@@ -1,9 +1,9 @@
 ---
-title: Process-PSModule caller workflow fleet standard
-description: Fleet research and proposed required and optional caller workflow elements for Process-PSModule consumers.
+title: Process-PSModule caller workflow candidate
+description: Fleet research and candidate required and optional caller workflow elements for Process-PSModule consumers.
 ---
 
-# Process-PSModule caller workflow fleet standard
+# Process-PSModule caller workflow candidate
 
 This page records the 2026-08-15 fleet research used to propose a common caller workflow for PowerShell module
 repositories. It is a proposal for review before the consumer repositories are changed.
@@ -81,9 +81,9 @@ Secret forwarding is the only widespread caller variation:
 
 The case difference in the old API key name is historical drift, not a supported option in the current contract.
 
-## Proposed standard
+## Candidate for discussion
 
-The standard caller should be:
+The current candidate is:
 
 ```yaml
 name: Process-PSModule
@@ -127,6 +127,21 @@ jobs:
       GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}
 ```
 
+This YAML is a recommendation derived from the v8 interface and fleet evidence. It is not an approved standard.
+Issue [#514](https://github.com/PSModule/Process-PSModule/issues/514) must record agreement on the following structural
+decisions before canonical guides, templates, or consumer workflows adopt it:
+
+| Decision | Candidate | Alternatives still open |
+| --- | --- | --- |
+| Wrapper scope | Exactly one reusable-workflow job. | Permit repository-specific jobs in the same file, or define pre/post extension jobs. |
+| Trigger ownership | The caller owns manual, schedule, default-branch push, and pull-request triggers. | Move some trigger policy into separate workflows or omit selected event classes. |
+| Pull-request activities | Keep all six listed activity types. | Reduce the activity list if a v8 behavior is intentionally unsupported. |
+| Concurrency | Use the PR-number-or-ref key and never cancel a release-capable run. | Use separate groups per event class or permit cancellation for non-mutating paths. |
+| Permissions | Declare the five current scopes at workflow level. | Introduce settings-based least-privilege profiles or split read-only validation from release work. |
+| Fork behavior | Skip fork-originated pull requests in this credentialed wrapper. | Add a separate secret-free workflow or define another supported fork-validation design. |
+| Credentials | Explicitly map the three v8 credentials. | Define a narrower credential profile for repositories that cannot publish. |
+| Optional surface | Permit only documented `TestData`, workflow inputs, schedule timing, and presentation metadata. | Allow additional extension points after naming and compatibility rules are agreed. |
+
 The `v8` reference is the controlled moving major tag for this PSModule-owned workflow. On 2026-08-15, `v8`, `v8.0`,
 and the immutable `v8.0.0` release tag all resolve to commit `5a11e8e8b018faf97017e0416f136a751c026713`.
 `Release-GHRepository` creates and advances major and minor tags by default, while the organization tag ruleset prevents
@@ -147,25 +162,25 @@ to `@v8`; until then, consumers must retain immutable SHA references.
 A major tag never crosses a breaking boundary. `v8` remains on the latest compatible `8.x` release; `v9` begins a new
 fleet campaign. Branch names, `latest`, floating minor tags, and unqualified targets are not accepted pins.
 
-## Required elements
+## Candidate common elements
 
-| Element | Requirement | Reason |
+| Element | Candidate requirement | Reason |
 | --- | --- | --- |
-| Identity | Keep the standard file, workflow, and job names shown above. | Stable discovery, status checks, and fleet maintenance. |
+| Identity | Keep the candidate file, workflow, and job names shown above. | Stable discovery, status checks, and fleet maintenance. |
 | Pull requests | Target `main` and keep all six listed activity types. | CI, prerelease publication, label changes, and closed-PR cleanup depend on them. |
 | Default-branch push | Keep `push.branches: [main]`. | `v8` authorizes stable releases from the tested default-branch push. |
 | Manual dispatch | Keep `workflow_dispatch`. | Provides the documented default-branch manual release and recovery path. |
 | Schedule | Keep a scheduled health run. | Exercises current dependencies even when repository code is unchanged. |
 | Concurrency | Use the PR-number-or-ref key with `cancel-in-progress: false`. | Cleanup and stable release runs stay distinct; release mutations queue instead of being interrupted. |
 | Permissions | Declare the five documented permissions explicitly. | The called workflow cannot elevate caller permissions. |
 | Fork guard | Skip pull requests whose head repository differs from `github.repository`. | GitHub withholds the required repository secrets from fork pull requests. |
-| Reference | Use the approved internal floating major tag (`v8`). | Compatible owned releases roll out centrally; breaking releases require a new major and campaign. |
+| Reference | Use the intended internal floating major tag (`v8`) after tag governance is enforced. | Compatible owned releases roll out centrally; breaking releases require a new major and campaign. |
 | Credentials | Explicitly map the three required secrets. | Satisfies the `v7+` contract and prevents unrelated secret inheritance. |
 | Scope | Keep the caller as a single delegation job. | Repository-specific automation remains independently understandable and maintainable. |
 
-## Supported optional elements
+## Candidate optional elements
 
-Optional elements are supported contract variations, not permission to retain historical drift.
+These are evidence-based candidate variations, not approved policy.
 
 | Option | When it is appropriate | Constraint |
 | --- | --- | --- |
@@ -177,31 +192,33 @@ Optional elements are supported contract variations, not permission to retain hi
 | Schedule time | Health runs need staggering or a repository-specific maintenance window. | Keep at least one documented schedule unless the repository records why health runs are unnecessary. |
 | `run-name` | A repository needs clearer run presentation. | Presentation must not change job names or routing behavior. |
 
-## Out-of-standard variations
+## Variations requiring a decision
 
-The following are migration defects or require a documented exception:
+The following differ from the candidate. They are inventory classifications, not policy violations, until #514 records
+an approved structure:
 
 - `secrets: inherit`;
 - `APIKey` or `APIKEY` mappings from the pre-`v7` contract;
-- any Process-PSModule reference other than the approved major tag (`v8`), including a branch, `latest`, minor tag,
+- any Process-PSModule reference other than the intended major tag (`v8`), including a branch, `latest`, minor tag,
   exact patch tag, or full commit SHA;
 - missing `push` or `unlabeled` triggers;
 - `cancel-in-progress: true` or the old ref-only concurrency key;
 - trigger-level path filters that bypass Process-PSModule important-file evaluation;
 - unrelated additional jobs in the caller wrapper;
 - omitted documented permissions without a verified settings-based least-privilege profile.
 
-Fork-originated pull requests are skipped by the standard caller because reusable-workflow caller jobs cannot select a
+Fork-originated pull requests are skipped by the candidate caller because reusable-workflow caller jobs cannot select a
 GitHub Environment and repository secrets are unavailable to forks. Supporting fork CI requires a separate, secret-free,
-read-only validation workflow; removing the guard is not a supported shortcut.
+read-only validation workflow under this candidate; #514 must approve that boundary.
 
-Repository-specific automation should normally use a separate workflow file. That keeps the Process-PSModule wrapper
+The candidate keeps repository-specific automation in a separate workflow file. That keeps the Process-PSModule wrapper
 identical enough for automated comparison while allowing modules to own unrelated schedules, generation, or integration
 tasks.
 
 ## Rollout boundary
 
-This research does not change consumer repositories. The campaign should use the stable slug
+This research does not approve or change consumer repositories. If #514 approves the candidate, the campaign would use
+the stable slug
 `process-v8-major-tag`, one delivery issue, branch, and early draft pull request per repository, and these waves:
 
 | Wave | Repositories | Change profile |
@@ -214,17 +231,18 @@ This research does not change consumer repositories. The campaign should use the
 
 Before opening leaves:
 
-1. Confirm `v8` and `v8.0.0` resolve to the same tested release commit.
-2. Restrict moving major-tag updates to the controlled release identity. Do not start the consumer rollout while another
+1. Record approval of every structural decision above in #514 and update the canonical guides and template.
+2. Confirm `v8` and `v8.0.0` resolve to the same tested release commit.
+3. Restrict moving major-tag updates to the controlled release identity. Do not start the consumer rollout while another
    identity can move `v8`; retain immutable SHA references until this gate is enforced.
-3. Have an organization administrator confirm `PSGALLERY_API_KEY`, `SHELLY_CLIENT_ID`, and `SHELLY_PRIVATE_KEY` coverage
+4. Have an organization administrator confirm `PSGALLERY_API_KEY`, `SHELLY_CLIENT_ID`, and `SHELLY_PRIVATE_KEY` coverage
    in Actions and Dependabot scope. The inventory token can list repository-local secrets but receives `403` for
    organization secret visibility, so inherited coverage is currently unresolved.
-4. Refresh the inventory with `-TargetReference v8`; the starting target count should be `0/60`.
-5. Confirm workflow-only changes are not important release changes. The fleet defaults match only `src/` and
+5. Refresh the inventory with `-TargetReference v8`; the starting target count should be `0/60`.
+6. Confirm workflow-only changes are not important release changes. The fleet defaults match only `src/` and
    `README.md`; `Yaml` explicitly matches `src/`, `tests/`, and `README.md`, so this campaign should not publish modules.
 
-Each leaf applies the common caller, retains only the supported optional mappings, and proves the PR path before merge.
-Advance one wave only after the previous wave's push run completes without an unintended release. Completion requires a
-fresh inventory showing `60/60` on `v8`, the complete trigger/concurrency contract, explicit credentials, no inherited
-secrets or old API-key mappings, and no unresolved review or CI failures.
+After approval, each leaf would apply the agreed caller, retain the agreed optional mappings, and prove the PR path
+before merge. Advance one wave only after the previous wave's push run completes without an unintended release.
+Completion would require a fresh inventory showing `60/60` on `v8`, the agreed trigger and concurrency contract,
+the agreed credential mapping, and no unresolved review or CI failures.

docs/content/reference/repository-standard.md

@@ -122,23 +122,14 @@ The caller workflow declares the triggers, concurrency, and permissions for the
 ```yaml
 jobs:
   Process-PSModule:
-    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@<commit-sha> # <version tag>
     secrets:
       PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
       GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
       GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}
 ```
 
-Name the caller file `Process-PSModule.yml`, matching [`PSModule/Template-PSModule`](https://github.com/PSModule/Template-PSModule) and every existing module repository. `workflow.yml` is the reusable workflow's own filename inside `PSModule/Process-PSModule` and belongs only in the `uses:` reference.
-
-`Process-PSModule` is PSModule-owned automation. Pin it to the approved floating major tag (`v8`) so compatible patch
-and minor releases move across the fleet without one pull request per release. The release workflow owns movement of
-the major tag; an incompatible release creates a new major tag and requires a deliberate fleet campaign. Do not use a
-branch, `latest`, a floating minor tag, or an exact release/commit for the standard caller.
-
-This internal-major-tag policy does not apply to third-party actions. External actions remain pinned to their full
-immutable commit SHA with the release version in a trailing comment.
+Name the caller file `Process-PSModule.yml`, matching [`PSModule/Template-PSModule`](https://github.com/PSModule/Template-PSModule) and every existing module repository. `workflow.yml` is the reusable workflow's own filename inside `PSModule/Process-PSModule` and belongs only in the `uses:` reference. Pin the reference to a commit SHA with the version tag in a trailing comment so Dependabot can update it.
 
 ## Required common files
 
@@ -202,11 +193,7 @@ For PSModule module repositories, the requirements are:
 
 Every module repository must include `.github/dependabot.yml`. Dependabot is part of the repository supply-chain control, not an optional convenience.
 
-Configure the `github-actions` ecosystem. It keeps external SHA-pinned actions current and proposes intentional major
-updates when supported. Compatible Process-PSModule patch and minor releases arrive through its controlled major tag
-instead of a Dependabot pull request. This is what
-[`PSModule/Template-PSModule`](https://github.com/PSModule/Template-PSModule) ships, and it is the default for new
-repositories:
+Configure the `github-actions` ecosystem. It keeps the pinned actions current, including the pinned `PSModule/Process-PSModule` reference in the [caller workflow](#caller-workflow-and-reusable-workflow). This is what [`PSModule/Template-PSModule`](https://github.com/PSModule/Template-PSModule) ships, and it is the default for new repositories:
 
 ```yaml
 version: 2