Agree the Process-PSModule caller workflow structure

[MariusStorhaug]

Outcome

The Process-PSModule caller workflow structure is explicitly agreed before canonical guides, templates, or consumer repositories change. The inventory and candidate YAML provide evidence for the decision; they do not establish the standard by themselves.

Evidence

• Draft PR: ⚙️ [Maintenance]: Process-PSModule caller fleets can be audited consistently #515
• Current inventory: 60 default-branch caller workflows, with all dimensions captured in the generated fleet inventory.
• Candidate design: docs/content/reference/process-workflow-fleet-standard.md in PR ⚙️ [Maintenance]: Process-PSModule caller fleets can be audited consistently #515.
• Agreed reference policy: controlled PSModule-owned automation may use a floating major tag such as @v8; external automation remains full-SHA pinned.

Recommendations for review

These are recommendations, not decisions. The checklist below remains the approval record.

Decision	Recommended candidate	Evidence and rationale
Identity	File, workflow, and job all use Process-PSModule.	All 60 current callers use the same file and workflow identity; stable names simplify discovery and required checks.
Wrapper scope	Use the canonical workflow file exactly; repository-owned automation uses separate workflow files.	Keeps every fleet caller directly comparable.
Trigger ownership	Caller owns manual dispatch, scheduled health, default-branch push, and pull-request events.	GitHub requires caller-defined triggers; v8 stable releases depend on default-branch push while CI, prerelease, and cleanup depend on PR events.
Pull-request activities	closed, opened, reopened, synchronize, labeled, and unlabeled.	The current fleet has the first five. unlabeled is needed so label removal is evaluated instead of leaving stale release intent.
Concurrency	`${{ github.workflow }}-${{ github.event.pull_request.number
Permissions	Top-level permissions: {}; caller job grants contents: read, pages: write, and id-token: write.	Use GITHUB_TOKEN for repository-local, non-user-facing checkout and Pages operations. Use scoped GitHub App tokens when the built-in boundary is insufficient and for all user-facing comments, labels, statuses, releases, and cleanup.
Fork behavior	No caller condition. Plan classifies fork PRs as restricted read-only validation and denies privileged capabilities.	Centralizes execution policy while preserving safe fork build, lint, and test coverage.
Credentials	Explicitly map PSGALLERY_API_KEY, SHELLY_CLIENT_ID, and SHELLY_PRIVATE_KEY; optionally map TestData JSON for module-local tests.	This is the v8 producer contract, avoids unrelated inheritance, and preserves the four observed test-data callers.
Optional surface	Permit only optional TestData under secrets.	Every other field matches the canonical template exactly.

Structural decisions to approve

• Contract scope: require the complete canonical Process-PSModule.yml; repository-owned automation uses separate workflow files.
• Trigger ownership: which of manual dispatch, schedule, default-branch push, and pull-request events belong in every caller.
• Pull-request activities: whether all of closed, opened, reopened, synchronize, labeled, and unlabeled are mandatory.
• Concurrency: use workflow plus PR number or full github.ref; set cancel-in-progress to ${{ github.event_name == 'pull_request' }}.
• Permissions: default deny globally; grant the caller job contents: read, pages: write, and id-token: write; use scoped GitHub App tokens for user-facing interactions and operations beyond the built-in token boundary.
• Fork behavior: keep the caller unconditional; let Plan authorize restricted fork validation while denying App tokens, publication, deployment, cleanup, and mutations.
• Credentials: require the three explicit v8 mappings; allow optional TestData JSON with separate secrets and variables maps; do not use secrets: inherit.
• Optional surface: TestData is the only permitted variation from the canonical template.
• Identity: final file, workflow, and job names used for discovery and stable checks.

Scope

• Inventory every default-branch workflow that calls PSModule/Process-PSModule/.github/workflows/workflow.yml.
• Record workflow identity, triggers, concurrency, permissions, reference, inputs, secrets, and extra jobs.
• Compare the evidence with the v8 producer contract.
• Record each approved structural decision and its rationale.
• Update canonical documentation only after the checklist above is resolved.

Non-goals

• Do not modify caller workflows across the fleet in this task.
• Do not treat the candidate YAML as approved merely because it appears in documentation or a draft PR.
• Do not start the rollout campaign until this issue records the agreed structure.

Acceptance criteria

• The complete current repository list and workflow metadata are documented.
• GitHub and local-checkout inventory refresh paths are tested.
• Every structural decision above has an explicit outcome.
• Required elements and optional variations use the approved outcomes rather than inferred commonality.
• Canonical guides and templates are updated only after approval.
• Campaign issue ⚙️ [Maintenance]: [process-v8-major-tag] Roll the v8 caller across the fleet #438 references the approved decision record.

[MariusStorhaug]

Reusable workflow location is now confirmed: keep PSModule/Process-PSModule/.github/workflows/workflow.yml@v8. A private cross-repository experiment with provider Actions access set to user failed before job creation when the caller referenced a root-level file. GitHub returned: references to workflows must be rooted in '.github/workflows'. The workflow display name: is not part of the reference.

[MariusStorhaug]

Credential mapping is selected. The common caller maps the three v8 credentials explicitly. TestData is the only approved optional secret mapping so modules can supply the documented JSON secrets/variables envelope to module-local tests. Callers omit it when unused. with.Debug: true is not part of the conforming caller surface; Debug keeps its reusable-workflow default of false.

[MariusStorhaug]

Caller-template rule is locked: replace .github/workflows/Process-PSModule.yml with the canonical template. The only permitted difference is optional TestData under secrets. Repository-owned automation belongs in separate workflow files.