Repository navigation
KYAML step 4/6 — decide KYAML scope on the evidence (owner ruling) #1023
Description
Step 4 of 6 in the KYAML adoption order fixed by 3-practice/YAML-POLICY.adoc §5.
Blocked by #1022.
Work
Decide KYAML scope on the evidence from steps 1–3.
Gate (§5)
An owner ruling recorded as a decision row. Not an inference from the probe.
Why this is its own step
§3.4: the owner considered mandating KYAML estate-wide including workflows and
chose instead to probe workflows first and decide after. The policy therefore
mandates KYAML nowhere today, and nothing in the estate is out of compliance
with Y-3, because Y-3 imposes nothing yet.
⚠ Step 1 (#1020) proved only that GitHub parses KYAML. That is one input to
this decision and explicitly not the decision itself — the §5 gate rules out
inferring scope from the probe.
Acceptance criteria
- Evidence from KYAML step 1/6 — probe whether GitHub Actions parses a KYAML workflow #1020, KYAML step 2/6 — comment-preservation proof (shared by Y-2 and Y-3) #1021 and KYAML step 3/6 — a KYAML formatter/linter for arbitrary YAML #1022 summarised in one place before the ask.
- Put to the owner via the selection UI, with the most elegant/correct
long-term arm labelled as such. - Recorded as a decision row on the standing decision surface
(hyperpolymath/standards#787), appended — never renumbered. - The ruling states explicitly whether workflows are in scope, since
step 6 does not start without that.
🤖 Generated with Claude Code
Activity
docs(policy): cross-reference the six booked KYAML adoption issues (#…
proof(#1021): YAML comment-preservation proof + Debtfile paid to ceil…
ci: gates read workflows with yq (Y-1), then KYAML pilot (Y-3) (#1115)
feat(yaml): kyaml-format.sh, a KYAML formatter with --check (#1022) (#…
hyperpolymath commentedon Oct 1, 2026
Evidence from steps 1–3, in one place, before the ask
yq -o kyamlarm PASS on all 57 standards workflows: 2245/2245 comments preserved, 0 moved, 0 dropped, idempotent 57/57. The Y-2yq -iarms FAIL idempotence (a comment block intag-ruleset-canon.ymlmoves on the second pass)yq -p yaml -o kyaml '.'df20618b)scripts/kyaml-format.sh [--check]: 17 controls, 3 formatter mutants killed; refuses unparseable, newline-less or data-changing filesWhat step 3 surfaced that bears directly on the workflow question
gh actions-lockv0.1.6 (github/gh-actions-lock) does not seeuses:inside a KYAML workflow. I planted an unlocked SHA in a KYAML-convertedprovisioning-check-reusable.yml:--verify-localreportedvalid: truewith no finding. The same plant in a block-YAML workflow wentvalid: false/stale(positive control).Consequence: converting any workflow to KYAML today silently removes it from
actions.lockverification, the gate behind the requiredgovernance / Actions lockfile verifyanduses ⊆ actions.lockcontexts. That is why the single-file workflow pilot was not shipped (YAML-POLICY §5 now records this).Two ways to close that gap:
gh actions-lockreads flow-styleuses:. That is a third-party fix; we can only file and wait.yq '.. | select(has("uses")) | .uses'⊆actions.lockkeys, as a required context beside the existing one. This is the Y-1 reader shape the "remaining Y-1 readers" PR is already moving the in-repo gates to, so the shim reuses that work.Non-workflow YAML (step 5, #1024) has no such blocker: no lock tool reads it.
The question for the owner (put via the selection UI)
Is KYAML in scope, and are workflows in scope?
The ruling will be recorded as the next decision row on #787 (currently D279: max of ledger and #787 = D278).
🤖 Generated with Claude Code
https://claude.ai/code/session_01W5CoaksP2Bg21HpDCgFgwS
hyperpolymath commentedon Oct 1, 2026
Ruled: D280 on #787 (#787 (comment)). KYAML everywhere, workflows in scope, shim first. Non-workflow YAML proceeds under #1024. Workflows (#1025) wait for a yq lock-coverage check in place as a required context. All four acceptance criteria are met (evidence summary, selection UI with the elegant arm labelled, decision row, explicit workflow scope). Closing.
🤖 Generated with Claude Code
https://claude.ai/code/session_01W5CoaksP2Bg21HpDCgFgwS
docs(yaml): record KYAML scope rulings D280/D307 in §3.4 (#1177)