Skip to content

docs(instructions): correct the workflow_call input rule - #599

Merged
ss-o merged 1 commit into
mainfrom
bug-598
Sep 2, 2026
Merged

docs(instructions): correct the workflow_call input rule#599
ss-o merged 1 commit into
mainfrom
bug-598

Conversation

@ss-o

@ss-o ss-o commented Sep 2, 2026

Copy link
Copy Markdown
Member

Closes #598.

§4 required a default on every workflow_call input. Two shipped workflows
contradict that, for two different and independently correct reasons, and §4 is
a mandatory surface, so as written an agent would have edited both back into
defects.

Evidence

All 10 workflows here that declare workflow_call:

Shape Workflows Satisfies the old rule
Pure workflow_call, has inputs trunk.yml, release-prepare.yml, zsh-ci.yml Yes
Pure workflow_call, has inputs zsh-lint.yml No: 2 required inputs, 0 defaults
Dual-trigger, no inputs labels-sync-test.yml, labeler-config-audit-test.yml, repo-settings-audit-test.yml, lychee.yml Vacuously
Dual-trigger, has inputs commit-lint.yml Cannot, meaningfully

A required input cannot carry a default. zsh-lint.yml declares files
and zsh-lint-sha as required: true; the caller always supplies them, so a
default is unreachable. That is the org's flagship reusable workflow and the
subject of the #543 versioning pilot.

A dual-trigger workflow's input defaults are dead on the direct path.
GitHub's contexts documentation scopes the inputs context to "the inputs of a
reusable or manually triggered workflow". A pull_request run is neither, so
the context is empty there and workflow_call defaults are never applied. #586
removed them for that reason and moved the operative value into the job step;
#597 now asserts as a test that no such default exists. The failure this
prevents is not cosmetic: an empty pattern reaching grep -E matches every
line, flagging every commit and silently passing every branch.

The change

One bullet becomes three: type and required always; default only for
optional inputs; and for a dual-trigger workflow, the operative fallback lives
in the job step. Nothing else in the file changes, and no workflow changes,
because the workflows were already right.

Instruction impact review

Required by runbooks/instruction-update.md:

  1. Shared policy, scoped guidance, runtime-only, or enforcement? Scoped
    guidance. It narrows how workflow authors declare inputs; it creates no new
    mandatory org-wide rule.
  2. Which runtimes and repository contexts? Every runtime consuming
    .github/instructions/*, for .github/workflows/*.yml and *.yaml, which
    is this file's existing applyTo. Unchanged.
  3. Is the canonical owner still correct? Yes. This file is the canonical
    GitHub Actions convention surface and already owns §4.
  4. Does another surface now duplicate or contradict it? This resolves the
    contradiction rather than adding one. PATTERNS.md gained a
    self-triggering-reusable-workflow entry in fix(ci): run commit lint directly so the policy gate executes #586 that describes the same
    input-default trap from the pattern side; the two now agree, with PATTERNS.md
    carrying the observed idiom and this file carrying the rule.
  5. Does either manifest need a route change? No. The file's path,
    applyTo, and manifest entry are unchanged; only body text moved.
  6. Can each runtime still receive the mandatory rule without an optional hook
    or skill?
    Yes. It stays in the same routed file, delivered by path
    matching, with no hook or skill involvement.
  7. Do generated output and size limits still pass? Yes.
    validate-agent-policy.py, test_validate_agent_policy.py,
    test_validate_zsh_standard_policy.py, and trunk check all pass. Net
    change is two added lines.

Verification

All six steps Validate Agent Instructions runs pass locally, plus
scripts/test-commit-lint-policy.sh (40 checks) and trunk check.

Section 4 required a default on every workflow_call input. Two shipped
workflows contradict that for two independently correct reasons.

zsh-lint.yml declares both its inputs required, and a default on a required
input is unreachable because the caller always supplies the value.

commit-lint.yml declares workflow_call alongside pull_request. GitHub scopes
the inputs context to a reusable or manually triggered workflow, so on a
pull_request run it is empty and the declared defaults never apply. #586
removed them for that reason and moved the operative value into the job step;
#597 now asserts no such default exists.

Split the bullet into three clauses so the rule matches both shapes. This is a
mandatory surface, so as written an agent would have edited both workflows back
into defects.

Closes #598
@ss-o
ss-o requested a review from a team as a code owner September 2, 2026 21:17
@ss-o
ss-o merged commit 61a4cd1 into main Sep 2, 2026
10 checks passed
@ss-o
ss-o deleted the bug-598 branch September 2, 2026 21:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(instructions): workflow_call input rule contradicts two shipped workflows

1 participant