[Marius Storhaug (MariusStorhaug)]

GitHub Actions guidance uses direct en-US instructions and present-tense explanations. It states the authoring rules separately from the checks that can detect violations.

This guidance-only change preserves the extraction requirement, required CI, blocking criteria, security boundaries, compatibility, commands, and examples. No workflow behavior or consumer action changes.

Fixed: Workflow authoring guidance states rules and lint coverage clearly

The standard separates long explanations into direct statements and ordered instructions. The manual pin-audit section lists its use cases, prerequisites, exclusions, and explicit failure result. Job structure, action reuse, and diagnostics retain their existing contracts.

The lint descriptions correct two factual coverage errors, not policy questions. actionlint can pass inline Bash/sh scripts to ShellCheck when the integration is enabled and the executable is available. That integration does not check PowerShell or Python; Python can have a separate optional Pyflakes integration. Standalone files provide native-language context for broader linting, formatting, type checks, security scanning, and editor features. Non-trivial scripts still require extraction into an action.

Lint results do not prove compliance with every authoring rule. The page requires review alongside the existing CI checks and points to its skipped-dependency guidance. Required CI execution and blocking/severity rules are unchanged. Only the separate-versus-colocated workflow/action-library choice remains an unresolved policy question.

Technical details

Scope and immutable sources

Only src/docs/Coding-Standards/GitHub-Actions.md changes. The complete baseline page was read (1,265 lines), followed by the complete first writing result (1,364 lines). The narrow factual correction and surrounding sections were then read against the verified upstream sources. The resulting page has 1,372 lines.

• Fixed criteria and scoped PR base: 1b0d4893c8fefabe604d04393068a8ff6f848082.
• Previous writing head: 0ba76283ef113db4eef91dda970f96486ee5a61d.
• Final reviewed and pushed candidate: 28947e5248f162cd358a0b1fc45c7587fe60aa20.
• Six logical commits are pushed. The draft opened after the first complete improvement, 6fa38a06c69261d31b314cac60976e4fb2f559a5.
• The coverage correction is one small commit: 16 added lines and eight removed lines in the owned page.

The closing Task pins the Documentation Model, Natural Language, Technical Writing Guide, Markdown, Documentation, and standard/guide templates at the fixed source. Official STEMG overview/FAQ and relevant local ASD-STE100 Issue 9 rules/dictionary were consulted. The PDF MD5 is 9c720341c350ed77943b2c73d01c716f. Reference copies stay local. Automated observations and counts do not establish full STE conformance.

Verified lint coverage and experiment limits

Official actionlint evidence is fixed at rhysd/actionlint@011a6d15e749bb3f2d771eed9c7aa0e7e3e10ee7:

• ShellCheck integration documents Bash/sh support, executable discovery, and explicit disabling.
• The dispatcher sends supported scripts to ShellCheck and skips unsupported shells.
• The official inline-script fixture and expected output show SC2086 at lines 6 and 14 for Bash, not the default Windows PowerShell step at line 12.
• Pyflakes is a separate integration. The ShellCheck limitation is not a claim that actionlint has no Python support.

Eight source/fixture consistency observations pass. No local actionlint/ShellCheck execution is claimed: neither native executable is available, the Docker Linux engine is unavailable, and its WSL distribution is stopped. No tool was installed and no runtime was started. The official sources and independent expected diagnostics establish the correction.

Concrete before and after cases

Concern	Before	After
Opening	held to the same bar as application code	Workflow authors apply the application-code standards and the supply-chain and least-privilege controls below.
Manual audit	One sentence combines the instruction and three cases.	A short instruction, three separate use cases, and separate prerequisites, exclusions, and failure handling.
Inline lint capability	Tools cannot process that script as code.	actionlint can send inline Bash and sh scripts to shellcheck when enabled and available. ShellCheck does not lint PowerShell/Python.
Standalone files	Tools can process code only when it is in a file of its own language.	Native-language/file context supports language-specific linters, formatters, type checkers, security scanners, and IDE features.
ShellCheck scope	the shell of every run: step through shellcheck	Only inline Bash/sh scripts through that integration; no implied PowerShell/Python coverage.
CI coverage	A workflow that breaks this standard fails the build.	The linters do not detect every violation of this standard. Review authoring rules and skipped dependencies as well as lint results.
Diagnostics	An action is a black box until it fails.	An action reports what it reads, decides, and produces on every run.

Exact preservation and accepted differences

All 31 fenced examples retain identical content and order after Git newline normalization. Their combined SHA-256 remains f7d2fe9b4c16bd22690553fe56a833ab0c9b4ccc19d0e86077fb434531a59214. All 38 headings/anchors, 270 inline-code spans, front matter, and uppercase normative terms (MUST, MAY, MUST NOT) remain unchanged from the fixed campaign baseline.

All 42 original link destinations remain. Only two references are added: official ShellCheck integration documentation and the existing skipped-job section anchor, for 44 total destinations. No existing heading or anchor changes.

The complete non-trivial-script extraction bullet, required push/PR CI execution statement, blocking/severity rules, and both repository-layout policy sections are exactly unchanged from 0ba76283ef113db4eef91dda970f96486ee5a61d. Manual review preserves lower-case obligations, owned-major exceptions, external SHA requirements, compatibility, permissions/token scope, OIDC, untrusted-input controls, GHES exclusions, cancellation/result checks, and explicit failure behavior.

Direct imperatives, technical terms, native YAML/PowerShell, placeholders, comments, historical example evidence, and stable headings remain accepted differences. This includes behaviour in a heading/anchor and the time-dependent concurrent-step title. Other standards, navigation, generated indexes, workflows, scripts/tests, configuration, dependencies, and #240 surfaces are untouched.

Final-head validation

The initial writing observations had seven expected failures. For this factual revision, six observations fail at the previous head before editing; all 24 final temporary assertions pass. No repository prose-policy tests or new tooling are added.

Check	Result at 28947e5
Existing Markdown configuration	Pass: one owned page, zero issues
Relative links and anchors	Pass: 130 files
Scoped cross-repository links	Pass: one link in the owned page
Existing Pester runner	Pass: 66 tests across six suites, zero failures or skips; existing installation only
Exact examples/requirements comparison	Pass: all 24 observations, including extraction/CI/severity/layout-policy guards
Docs CI	Pass at the exact final head
Cross-Repository Links CI	Pass at the exact final head
Pinned site build	Build job passed; logs confirm installation of Zensical 0.0.59 and No issues found
Actual CI site output	Artifact 13325290117 passes ten render observations: all 31 examples match source, corrected claims and extraction requirement render, both new references render, false descriptions are absent, and checked stable anchors remain
New explicitly requested review	Approved at the exact final head, zero new inline comments; review-loop exit 0
Remote and worktree	Remote head matches the candidate; worktree is clean

Earlier local site checks at 0ba7628 remain historical evidence, not proof for this head. The existing final-head CI build and its downloaded artifact provide the new pinned-site evidence without local tooling or runtime changes. The temporary downloaded site artifact was removed after inspection. Source/fixture, comparison, render, build-log, and review evidence remain local and are summarized here and in the Task.

Changed surface	Standards checked	Framework docs checked	Result
GitHub Actions standard prose	Fixed documentation/writing standards and templates; official STE sources; immutable actionlint documentation/source/fixtures	None (no framework-specific docs)	Fixed in this PR

The two false coverage descriptions are corrected in this PR. They are no longer deferred as policy. The remaining layout question contrasts the separate-repositories/self-checkout-last-resort guidance with the colocated-action/self-checkout-required guidance. Those sections remain unchanged for an owner decision.

All assigned writing, source verification, preservation comparisons, final-head validation, and automated review are complete. No writing or validation blocker remains. The live local ShellCheck experiment was unavailable and is not claimed. The prior scoped convergence search found this Task and #242, which excludes this page; no extra closing reference applies.

Delivery boundary: Leave the PR DRAFT. No ready, merge, auto-merge, or Agent merge action was taken. The Task stays open for later review and merge.

Related references

• Resolves [documentation-writing-alignment] Clarify the GitHub Actions authoring standard #243
• References [documentation-writing-alignment] Clarify shared coding and writing standards #242
• References Keep documentation tooling tests focused on supported behavior #240 for excluded code/test ownership

[Copilot]

🟢 Approved

No active review issues are recorded for this documentation-only clarification of the GitHub Actions authoring guidance.

No open issues 🎉

What changed in this PR

This documentation-only PR rewrites the GitHub Actions authoring standard in direct language, making workflow requirements easier to follow without changing policy, commands, examples, or workflow behavior.

Changes:

• Replaces idioms and dense prose with shorter statements and direct instructions throughout the page.
• Separates manual pin-audit use cases, prerequisites, exclusions, and failure behavior.
• Preserves existing headings, links, examples, and the acknowledged policy contradiction about colocated actions.

File	Description
src/​docs/​Coding-Standards/​GitHub-Actions.md	Clarifies workflow-authoring guidance and manual pin-audit instructions.

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues are reported for this documentation-only clarification of GitHub Actions authoring guidance.

No open issues 🎉

_{Review effort: Balanced}