Tracker: `GOVERNANCE.md > Workflow YAML Conventions`

[ptr727]

Tracker for GOVERNANCE.md > Workflow YAML Conventions. Filed under #1315's roll-up of the open prose backlog: every finding a bundle issue enumerated against this unit is listed here once, one line each, naming the issue it came from, and the bundle is closed as a duplicate of this tracker so the finding is not lost and the bundle stops being a unit of work. A new pre-existing finding on this unit gathers here per pr-review-conduct's Merge Gate, numbering continuing this list. This tracker closes when the unit is rewritten and each line below is settled or superseded.

1. The boolean-input contract is stated for the wrong context: a workflow_dispatch boolean stays boolean in inputs and only stringifies in github.event.inputs. (19 Carried-Content Defects From Downstream PR Reviews (guard, resync, drive-pr, git-commit, pr-review, promotion recipe, AUDIT.md, GOVERNANCE.md, merge-bot stub) #1113)
2. The Boolean input rule is stated too broadly: only github.event.inputs.foo stringifies, while the inputs context preserves the declared type. (Three Findings Against Carried AUDIT.md and GOVERNANCE.md, Raised on a Downstream Promotion #1197)
3. The concurrency exception describes publish-release.yml as publishing shared ref-independent artifacts on schedule, which this repo's dispatch-only file does none of. (Seven GOVERNANCE.md and carried-skill claims the shipped workflows falsify #1202)
4. cancel-in-progress: false does not deliver run-to-completion in arrival order: GitHub cancels the previously pending run when a newer one queues. (Seven GOVERNANCE.md and carried-skill claims the shipped workflows falsify #1202)
5. The step-name rule says there is no un-suffixed exception, while validate-task.yml:316 carries a trailing parenthetical and nothing enforces it mechanically. (Seven GOVERNANCE.md and carried-skill claims the shipped workflows falsify #1202)
6. The multi-image buildcache bullet names an "inline cache" mechanism nothing in the repo demonstrates, and says per-image tag where the task varies the repository. (Seven GOVERNANCE.md and carried-skill claims the shipped workflows falsify #1202)
7. The trigger enumeration omits pull_request_target, and the pinning and naming rules say nothing about composite actions under .github/actions/**. (Seven GOVERNANCE.md and carried-skill claims the shipped workflows falsify #1202)
8. The "every bash surface" set -Eeuo pipefail rule cannot be followed by .husky/pre-commit (#!/bin/sh) or the catalog pre-commit snippet; WORKFLOW.md section 2 repeats it. (Seven GOVERNANCE.md and carried-skill claims the shipped workflows falsify #1202)

[ptr727]

Appended from the class 6 whole-unit read of this section (#1388), numbering continuing the list above.

9. The Conditionals bullet's reason, "Literal block (if: |) is wrong because it embeds newlines inside the boolean expression", states a tool fact that does not hold, since the expression lexer skips whitespace, newlines included, so the folded-scalar preference stands as house style without the reason the bullet gives. [GOVERNANCE.md > Workflow YAML Conventions] (Cut WORKFLOW.md Section 2 to a Pointer at Workflow YAML Conventions #1388)
10. The Filename bullet gives a workflow triggered by both workflow_call and workflow_dispatch, the shape the Boolean inputs bullet governs, two incompatible instructions, reusable so -task.yml and entry-point so not, and says a -task.yml is never triggered directly, which such a file is by construction. [GOVERNANCE.md > Workflow YAML Conventions] (Cut WORKFLOW.md Section 2 to a Pointer at Workflow YAML Conventions #1388)
11. The Artifact retention bullet's reason for deleting pypi-build-<branch> on a failed push, that a durable copy lives on the release or the registry, is false for that artifact, since a PyPI hook uploads no release asset and a failed push leaves the registry without a copy, so the delete removes the only built package and the unit gives no other justification. [GOVERNANCE.md > Workflow YAML Conventions] (Cut WORKFLOW.md Section 2 to a Pointer at Workflow YAML Conventions #1388)

[ptr727]

Three more from the class 6 whole-unit read of this section on #1388, run at the opus tier, numbering continuing the list in the comment above.

12. The allowlist bullet offers always() and !failure() && !cancelled() as interchangeable status-check functions, and they are not: always() returns true on a cancelled run and on a failed sibling needs: job, readmitting the cancelled case the bullet's own opening sentence names as the bug, while the hub's own build-release-task.yml uses only the second form with an inline comment that the function must fail closed on a real failure. [GOVERNANCE.md > Workflow YAML Conventions] (Cut WORKFLOW.md Section 2 to a Pointer at Workflow YAML Conventions #1388)
13. The validate-at-entry bullet's "a dedicated entry validation step/job that the downstream jobs needs:" cannot be followed in its step form, since needs: accepts job ids only, and the bullet's own docker-readme example is a step inside a job that also resolves the repository list, so a consumer needs the containing job rather than the validation. [GOVERNANCE.md > Workflow YAML Conventions] (Cut WORKFLOW.md Section 2 to a Pointer at Workflow YAML Conventions #1388)
14. The Docker layer cache bullet states neither the push gate on cache-to nor the both-branch cache-from read that WORKFLOW.md D9.4 requires and that build-docker-task.yml implements, so a carrier implementing only this bullet writes a symmetric single-tag cache whose smoke build attempts a registry write it has no credential for. Raised against this section's own "keeps the full rules" sentence, which Cut WORKFLOW.md Section 2 to a Pointer at Workflow YAML Conventions #1388 rewrote when WORKFLOW.md section 2 stopped restating these rules, though the bullet's gap against D9.4 is untouched text and predates that change. [GOVERNANCE.md > Workflow YAML Conventions] (Cut WORKFLOW.md Section 2 to a Pointer at Workflow YAML Conventions #1388)

[ptr727]

Seven more from a #1311 second-round pass (complete-brief whole-unit read, opus tier, no PR — read-only) over this section, numbering continuing the list above. The reviewer confirmed items 9-14 all still present as worded without re-deriving any of them.

15. The Workflow name: bullet's rename-in-lockstep instruction ("updating in lockstep with the job name: every surface whose staleness breaks enforcement, never one without the others") lists five surfaces, four of which — the hub's repo-config/ payloads, spec/files.json, catalog/, and docs/reusable-workflows.md — exist only in the hub, not in a carrying repo. A downstream reader following this carried section is instructed to edit files it does not have checked out, and "never one without the others" makes literal compliance impossible for a rename made in a downstream repo. The section is otherwise scrupulous about flagging hub-only paths (its own workflow-ci-contract cross-reference two bullets earlier does exactly this), which is what makes the omission visible from inside the unit. [GOVERNANCE.md > Workflow YAML Conventions] (Why the Backlog Grows: Prose Review Has No Fixed Point, and a Plan to Keep the Rigor Without It #1311 second round)
16. The artifact-retention bullet's opening premise ("workflow artifacts ... must not survive the run and accumulate against the small account-wide artifact-storage quota") is contradicted by its own scope: the surgical delete targets named transfer artifacts, the blanket-delete ban exists specifically to protect auto-emitted build-records (docker/build-push-action's .dockerbuild), and the retention-days: 1 backstop is scoped to explicit upload-artifact steps, which an action-emitted record is not. The one artifact class the bullet protects from deletion is the one class with no bounded retention under any of its three stated mechanisms. [GOVERNANCE.md > Workflow YAML Conventions] (Why the Backlog Grows: Prose Review Has No Fixed Point, and a Plan to Keep the Rigor Without It #1311 second round)
17. The Workflow name: bullet's stated reason ("The displayed action name in the GitHub Actions UI tells you at a glance whether you're looking at an orchestrator or a callee") does not hold for the reusable half: a called reusable workflow's jobs appear nested inside the caller's own run under <caller job> / <callee job>, and the runs list shows the caller's workflow name, not the callee's top-level name:. The "task"/"action" suffix convention pays off reading source files, not reading the Actions UI at the moment this bullet says it does. Same shape of defect as item 9. [GOVERNANCE.md > Workflow YAML Conventions] (Why the Backlog Grows: Prose Review Has No Fixed Point, and a Plan to Keep the Rigor Without It #1311 second round)
18. The dual-trigger contradiction item 10 raises against the Filename bullet is replicated on the adjacent Workflow name: bullet: line 233's Boolean-inputs bullet establishes that a workflow can be triggered by both workflow_call and workflow_dispatch, and the name: bullet partitions names into "reusable -> task" / "entry-point -> action" with no rule for a file that is both. Fixing the Filename bullet alone leaves this one standing. [GOVERNANCE.md > Workflow YAML Conventions] (Why the Backlog Grows: Prose Review Has No Fixed Point, and a Plan to Keep the Rigor Without It #1311 second round)
19. The Concurrency bullet mixes a repo-relative Markdown link for one documented exception ([merge-bot-pull-request.yml](./.github/workflows/merge-bot-pull-request.yml)) and a plain, unlinked path for the other (.github/workflows/publish-release.yml) in the same sentence. In a carried GOVERNANCE.md`, the link resolves only in a repository that happens to hold a merge-bot workflow at that exact path; the plain-path form degrades gracefully everywhere. [GOVERNANCE.md > Workflow YAML Conventions] (Why the Backlog Grows: Prose Review Has No Fixed Point, and a Plan to Keep the Rigor Without It #1311 second round)
20. The Docker layer-cache bullet introduces "inline cache" in "the base image's own tag and inline cache" with no definition or scope anywhere in the unit — the bullet's own vocabulary elsewhere is type=registry versus type=gha, and type=inline is not named. A reader cannot tell whether it is a further cache-to entry, a property of the base image's tag, or part of the base build. Adjacent to, but distinct from, item 14's two gaps. [GOVERNANCE.md > Workflow YAML Conventions] (Why the Backlog Grows: Prose Review Has No Fixed Point, and a Plan to Keep the Rigor Without It #1311 second round)
21. The Reusable-workflows bullet's validate-release example is quoted and suffixed like a step name: ("publish-docker-readme-task.yml's "Validate inputs step""), while the Workflow name: bullet states "There is no un-suffixed exception" for job/step names and the same example is elsewhere referenced by bare, unsuffixed job id (validate-release). The unit never states that it refers to jobs by id and steps by name:, so the mixed example reads as the exception the other bullet says does not exist. [GOVERNANCE.md > Workflow YAML Conventions] (Why the Backlog Grows: Prose Review Has No Fixed Point, and a Plan to Keep the Rigor Without It #1311 second round)

Also worth recording against item 9 rather than as a new number: the Conditionals bullet's positive reason is independently wrong in the same way as its negative one — a folded scalar (if: >-) folds line breaks into spaces, it does not "preserve whitespace correctly." Both the stated reason for the preference and the stated reason against the alternative are inaccurate, which item 9's own framing ("the folded-scalar preference has no valid stated reason") already covers without a new item.

[ptr727]

New finding: this section's bullets bind at D2, D4, D5 and D7, not only D9

Raised by a whole-unit review during #1390. No surface in the tree states this mapping, and PR
6 of the #1311 sequence needs it.

WORKFLOW.md section 2 and its skill counterpart both route to this section as "the style
rules", and WORKFLOW.md D9 is titled "Style / Static", so the natural reading is that this
section's contents bind at D9. That is true for only five of the thirteen bullets. The rest are
substantive control-flow rules that bind elsewhere in section 4:

Bullet	Binds at
Action pinning	D9.1
Filename, workflow, job and step name suffixes	D9.2
Shells, set -Eeuo pipefail, if: >-	D9.3
Docker layer cache	D9.4
Line endings	D9.5
Validate input/state consistency at entry	D2.1
Tag pinning	D4.2
Artifact retention, consume-then-delete, blanket-delete ban	D5.1, D5.2, D5.4
Concurrency	D7.1
Reusable-workflow permissions: before if:	D7.2
Boolean inputs	D7.3
Allowlist success and skipped explicitly	D7.4

Consequences a reader hits today. An auditor told "D9 is where they bind" looks for the
concurrency, permissions, retention and validate-at-entry conventions under D9 and finds
nothing there. And WORKFLOW.md section 2's "necessary but not sufficient (a perfectly styled
workflow can still violate section 4)" frames style and contract as disjoint spaces when
several of these bullets are D2, D4, D5 and D7 items.

Decision affecting this section

The maintainer settled two questions on #1206, both of which land here.

1. D9 binds exactly as D1 through D8 do. This section's opening, "These conventions
   describe the target state. New and modified workflows must respect them. The rest of the
   repo is expected to be brought up to the same standard", narrows to mean when a repo
   fixes an unswept workflow, never whether the violation counts. As written it gave an
   unswept workflow the opposite verdict to section 4's preamble.
2. An overlap resolves by subject rather than by blanket precedence. This section keeps
   the style conventions and wins there. WORKFLOW.md wins on the architecture, the contract
   and the test methodology. This matters for item 12 above: this section's boolean-inputs
   bullet requires comparing against both forms, while D7.3 requires 'true' alone for a
   github.event.inputs read and explains the == true half "can never fire". Under the old
   blanket rule an auditor failed a D7.3-conforming workflow and mandated dead YAML.

[ptr727]

This section is swept in #1395, and this comment records what that change settled, what it
attempted and withdrew, and the one tree gap it opens.

Settled

Items 1, 2 and 12's live instance (the boolean-inputs bullet against D7.3) are settled by stating
the inputs and github.event.inputs contexts separately and carrying D7.3's NaN mechanism as
the rationale, with D7.3 named as the contract that wins. Items 3, 4, 5, 6, 7, 9, 10, 11, 13, 15,
16, 17, 18, 19, 20 and 21 are settled in the bullets themselves. Item 8's impossibility is settled
by admitting a POSIX #!/bin/sh surface and giving it set -eu. Item 14's gap against D9.4 is
settled by stating the push gate on cache-to and the both-branch cache-from read.

Attempted and withdrawn: the D-item mapping this issue's own comment supplies

The mapping in comment 5560786190 is correct and useful, and restating it in prose is not the way
to keep it. #1395 added it to this section's opening and to WORKFLOW.md section 2, and a review
round found it wrong four ways: this section carries no line-endings bullet at all (that policy
lives in "Documentation Style Conventions" and the comment's table lists a bullet that does not
exist), D7.1 covers only the concurrency exception rather than the bullet's actual rule, D5.5
was omitted although the blanket-delete ban is stated here in full, and the Shells bullet governs
committed .sh scripts and git hooks, which are not workflows and cannot be "not operational". The
two copies had also already drifted from each other inside the round that wrote them. Both were
deleted on the maintainer's call, and the opening now states the binding qualitatively and routes a
reader to section 4 for which rule binds where.

So the consequence this issue names, an auditor told "D9 is where they bind" looking under D9 and
finding nothing, is addressed by removing the false "D9" claim rather than by publishing a mapping
this section then has to keep in sync. If a mechanized mapping is wanted, spec/ is where it would
have to live to be checkable.

One tree gap this sweep opens

22. The Shells bullet now reads "A deliberately POSIX #!/bin/sh surface ... takes set -eu",
    which is correct (-u is a POSIX set option). Neither of this repository's two #!/bin/sh
    surfaces satisfies it: .husky/pre-commit carries set -e, and catalog/snippets/husky/pre-commit,
    the adopter-facing reference hook, carries no set line at all. This is the section's own
    target-state framing working as intended rather than a defect in the rule, and the hooks were
    left alone rather than changed blind, since adding -u to a live hook can break it on an unset
    variable. [GOVERNANCE.md > Workflow YAML Conventions]

[ptr727]

Update to item 22, from #1395's round 3.

The live half is fixed: .husky/pre-commit carries set -eu as of 11804dd. My original filing reasoned that adding -u to a live hook risks breaking it on an unset variable, and that was caution standing in for a measurement. The file references no variable at all and deliberately does not source the generated _/husky.sh, so -u adds no failure path, and the commit that made the change exercised the hook under it.

What remains of item 22 is catalog/snippets/husky/pre-commit, the adopter-facing reference hook, which carries no set line at all. That one does source _/husky.sh, which is generated, gitignored and absent at lint time, so set -u there would be asserted against content this repository cannot inspect. Every command in the snippet already ends || exit 1, so set -e would add little and set -u is the part that needs a decision from someone who can see a generated husky.sh.

So item 22 narrows to the snippet rather than closing.