ci: repo-governance - Add workflow validation checks #240

Current delivery and branch audit — 24 October 2026

This current snapshot supersedes conflicting earlier branch instructions and implementation-status claims below. Earlier dated notes remain historical evidence, not current acceptance. No status, hierarchy, native PR association or repository change is proposed by this description patch.

• Outcome: Validate GitHub Actions syntax/static requirements with negative-case evidence.
• Recorded status: In Progress. Accepted whole-child completion is not established.
• Verified implementation position: workflow-lint.yml now exists and uses a strict PyYAML loader rejecting duplicate mapping keys. The old claim that no dedicated validator exists is stale. YAML parsing alone does not establish full Actions-schema or expression validation.
• Outstanding acceptance: Agree minimum Actions/static coverage and inventory; demonstrate valid/invalid fixtures, fork handling and no production-secret dependency.

Branch instructions

• Repository: lightspeedwp/ThisOneTimeOnAcidCom
• Implementing issue(s): this existing child; GitHub sync counterpart ci: repo-governance - Add workflow validation checks #240 in the same repository. Linear GitHub-sync mapping retrieved; GitHub issue body/parent not independently re-read in this audit. Do not use a closing/development association until independently verified.
• Parent epic context: native parent verified; coordination only. No implementation branch/file plan belongs to the epic itself.
• Allowed closing target(s): none now. Whole-child acceptance and independent GitHub/Linear mapping/association review are required before proposing a closing target; never the parent.
• Branch state: proposed new branch
• Branch: ci/governance-workflow-validation
• Base: develop, verified at 3f583002482d80ffd1910676bcf7c63e13989b20; refresh before separately authorised implementation
• Naming policy: target instructions, contributor guide, validator, local branch guide, organisation strategy. Classification rationale: ci is the candidate code/documentation class; authorised prefix is checked independently of the Linear title. Exact proposed name passed node scripts/validate-branch-name.js --branch ci/governance-workflow-validation in this read-only audit. It is not created or approved for creation.
• Pull request template: shared pr_ci.md — explicitly read/use its sections; do not add a repository-local copy
• PR association safeguard: No parent identifier/link in a future branch name, PR title/body, coding prompt, development link or closing directive. Association/status automation settings remain unverified; do not assume “Related to” text or a hyperlink is harmless. Child references in this description are not proposed PR text.
• Constraints: preserve unrelated work; do not create/switch/rename/delete branches, force-push, merge, deploy, change settings or close records under this draft. Shared locked configuration/templates require human review. Residual protected-file declarations remain relevant despite absent guard workflow; do not equate absent automated enforcement with permission. Workflow ownership conflicts require controller/owner resolution, not local edits to managed dependency workflows.
• Conflicts or missing evidence: Choose static tooling and fixture harness; no fixture or workflow execution performed.

Expected file changes

Plan status: provisional bounded proposal, not an approved or exhaustive implementation manifest; conditional rows are not permission to act.

• Out of scope: New model calls, credentials, AI-feedback enablement, managed-workflow edits, required-check activation.
• Remaining discovery: Choose static tooling and fixture harness; no fixture or workflow execution performed.
• Scope-change gate: stop for revised exact scope and approval before adding materially different paths or operations. No unbounded “other files as needed”. Protected-file approval never overrides a prohibition on routine agent edits.

Evidence and handoff packet

• Recipient and request: originating issue-management audit; read-only exact existing-record preview for approval, not a new intake or implicit specialist invocation.
• Selected record: this existing child description, separate from the coordination parent; no writes performed.
• Implementing targets and criteria: this child’s existing outcome and acceptance criteria remain in force. Validate GitHub Actions syntax/static requirements with negative-case evidence. Outstanding gates: Agree minimum Actions/static coverage and inventory; demonstrate valid/invalid fixtures, fork handling and no production-secret dependency.
• Sources checked: current Linear description/status/native parent/relations/explicit pullRequests and GitHub sync metadata; target instructions, contributor guide, validator, local branch guide, organisation strategy; the exact source paths/revisions above and current repository inventory. Shared template config checked at 47aee0722033f65d4d9d57429b410b518646b817. Some path evidence is inventory-only and is labelled as such; it is not full content/behaviour validation.
• Branch/PR evidence: Current remote inventory includes historical epic/repo-governance-lightspeedwp/ThisOneTimeOnAcidCom#237 and broad governance/testing branches; scope/base/diff fit was not verified, so none is recommended for reuse. An open application-instrumentation pull request overlaps shared configuration; refresh its head, changed paths and scope before choosing a branch or editing shared files. No reuse is approved. No native linked PR was returned for this child; descriptive/historical references are not native associations.
• Association and closing rationale: Linear GitHub-sync mapping retrieved; GitHub issue body/parent not independently re-read in this audit. Do not use a closing/development association until independently verified. No complete-child acceptance or closing target established. Linear GitHub documentation lookup identified the integration article but did not expose its detailed association content; current workspace linking/status rules remain unverified. No parent identifier/link in a future branch name, PR title/body, coding prompt, development link or closing directive. Association/status automation settings remain unverified; do not assume “Related to” text or a hyperlink is harmless. Child references in this description are not proposed PR text.
• Unresolved points and exclusions: Choose static tooling and fixture harness; no fixture or workflow execution performed. New model calls, credentials, AI-feedback enablement, managed-workflow edits, required-check activation.
• Approval state: draft only. Exact description-preview approval is still required; repository edits/branch actions/PRs/settings/native associations retain separate boundaries. Existing GitHub issue sync is active, so approved description changes may propagate externally; no duplicate GitHub body write is proposed.

CI Summary

Add .github/workflows/workflow-validation.yml to validate applicable GitHub Actions files. Select the minimum required tooling and permissions rather than copying shared workflow dependencies wholesale.

Linked Stories/Tasks/PRs/Epic

Parent: #237. No existing child or PR relationships proposed.

Milestones & Timeline

No dates or milestones assigned. Complete the listed dependencies before implementation.

Steps / Checklist

• Task is clearly defined and actionable
• Automation/scripts referenced if applicable
• Documentation/changelog updated
• PR uses correct branch prefix (ci/)
• PR description updated with relevant details
• Changelog entry prepared for PR (if applicable)
• Labels/types match org standards

Acceptance Criteria

• Solution implemented and documented
• CI/CD passes and is stable
• No regressions in build/deploy processes
• Branch prefix is correct (ci/)
• Branch deleted/merged
• Workflow syntax/static checks pass
• A deliberately invalid fixture is detected
• Validation needs no production secrets
• Centrally managed dependency workflows are not edited
• Any findings against centrally managed dependency workflows are reported separately

Additional Context

Target: book repository. Reference: shared workflows.

Dependencies: approved workflow inventory and validation-tool selection.

The workflow filename is a proposal, not an existing file. Read target-repository instructions before implementation; template branch wording does not override those instructions.

Definition of Ready (DoR)

• Build/CI goal and scope defined
• Checklist prepared
• Estimate added

Definition of Done (DoD)

• Issue is fixed and tested
• All checklist and acceptance criteria completed
• Documentation/changelog updated if needed
• Approved by at least one maintainer
• PR uses correct branch prefix (ci/)
• Branch deleted after merge
• Linked issue(s) updated with latest status and closed after merge
• The related epic should not be closed, instead updated with a comment to reflect the closed issue

The template’s future epic-comment requirement does not authorise posting a comment during creation.

Source-note references and scope

Implementation reference: workflow-lint.yml.

Evaluation references: validate-specifications.yml, claude-guard-tests.yml, ai-feedback-validation.yml and ai-feedback.yml.

This issue owns syntax/static validation, not automatic implementation of every referenced workflow. Record applicability, dependencies, permission boundaries and proposed ownership for evaluated workflows in the Spec Kit plan. Coordinate specification behaviour with #250 and hook tests with #256/#261. Do not add model calls, credentials, metadata writes or required checks through this reference repair.

Current implementation and remaining acceptance — 19 October 2026

Reviewed against develop revision 4ecdb26d9655a48bf000a7c89da2f70383edce87. No tests, interface submissions, settings changes or metadata mutations were performed during this review. Merged changes are partial evidence, not automatic completion.

Delivered: #319 and #334 contributed workflow inventory/reference auditing. No dedicated general syntax/static validator was found.

Remaining acceptance: approve applicable inventory/tooling; demonstrate valid workflows and a deliberately invalid fixture without production secrets. Preserve managed workflows and report their findings separately.

Validation gap: inventory checks are not syntax-validation evidence.