KYAML step 4/6 — decide KYAML scope on the evidence (owner ruling)

[hyperpolymath]

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

https://claude.ai/code/session_01WRvDivYwLSeVCJUrfjic3f

[hyperpolymath]

Evidence from steps 1–3, in one place, before the ask

step	issue	verdict	what it does and does not show
1	#1020 (closed)	GitHub Actions parses KYAML workflows	parse only. Not a scope decision (§5 gate)
2	#1021 (closed)	yq -o kyaml arm PASS on all 57 standards workflows: 2245/2245 comments preserved, 0 moved, 0 dropped, idempotent 57/57. The Y-2 yq -i arms FAIL idempotence (a comment block in tag-ruleset-canon.yml moves on the second pass)	covers exactly one rewriter: yq -p yaml -o kyaml '.'
3	#1022 → #1117 (merged df20618b)	scripts/kyaml-format.sh [--check]: 17 controls, 3 formatter mutants killed; refuses unparseable, newline-less or data-changing files	a tool, not yet a gate: nothing calls it in CI

What step 3 surfaced that bears directly on the workflow question

gh actions-lock v0.1.6 (github/gh-actions-lock) does not see uses: inside a KYAML workflow. I planted an unlocked SHA in a KYAML-converted provisioning-check-reusable.yml: --verify-local reported valid: true with no finding. The same plant in a block-YAML workflow went valid: false / stale (positive control).

Consequence: converting any workflow to KYAML today silently removes it from actions.lock verification, the gate behind the required governance / Actions lockfile verify and uses ⊆ actions.lock contexts. That is why the single-file workflow pilot was not shipped (YAML-POLICY §5 now records this).

Two ways to close that gap:

1. Upstream: gh actions-lock reads flow-style uses:. That is a third-party fix; we can only file and wait.
2. Shim (ours): a yq-based coverage check, yq '.. | select(has("uses")) | .uses' ⊆ actions.lock keys, 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?

• (Elegant long-term arm.) KYAML everywhere, workflows included. Non-workflow YAML migrates now (KYAML step 5/6 — migrate estate-authored non-bot YAML #1024). Workflows migrate (KYAML step 6/6 — workflows, only if step 4 rules them in scope #1025) only after the yq lock-coverage shim lands as a required context, so no workflow ever leaves lock verification. Upstream gh-actions-lock support is filed as well, and the shim retires when it lands.
• KYAML for non-workflow YAML only; workflows stay block YAML until upstream gh-actions-lock supports flow style (no shim).
• KYAML for non-workflow YAML only, workflows permanently out of 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]

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