feat(yaml): kyaml-format.sh, a KYAML formatter with --check (#1022)

[hyperpolymath]

KYAML adoption step 3 (3-practice/YAML-POLICY.adoc §5). Closes #1022.

What

scripts/kyaml-format.sh [--check] FILE...

• The rewriter is yq -p yaml -o kyaml '.', verbatim. That is the one rewriter KYAML step 2/6 — comment-preservation proof (shared by Y-2 and Y-3) #1021's proof covers, so nothing is post-processed.
• --check exits 1 on drift and rewrites nothing.
• Refuses (exit 2), never clean: an unparseable file, a file with no final newline, a rewrite that would change the parsed data, a missing file, or no arguments.

#1022 acceptance criteria

criterion	evidence
formats arbitrary YAML without kubectl	yq v4.53.3 only. Run over a copy of all 57 workflows on main: 56 rewritten; then --check → all 56 KYAML
--check exits non-zero on drift	suite: block YAML → 1; hand-mangled KYAML → 1; mixed set → 1
passes the step-2 proof on the pin-comment corpus	bun prove.js .github/workflows/*.yml on 13b872c1: kyaml arm PASS: 2245/2245 comments preserved, 0 moved, 0 dropped, idempotent 57/57
reads with yq, never grep (Y-1)	data equality is checked with yq -o json 'sort_keys(..)'
third-party pinned	N/A: no new action, and no new dependency beyond yq
non-vacuity	17 controls, each accepting case with a rejecting twin. Three formatter mutants killed: never-drift (3 red), refusal-not-counted (4 red), final-newline guard removed (1 red)

Two findings this surfaced

1. gh actions-lock v0.1.6 (github/gh-actions-lock) does not see uses: inside a KYAML workflow. I planted the unlocked SHA 1111… in KYAML provisioning-check-reusable.yml: --verify-local stayed valid: true with no finding. The same plant in block readme-derive-reusable.yml gave valid: false, stale (positive control). Converting a workflow would therefore silently drop it from lock verification. The single-file workflow pilot is not shipped, and YAML-POLICY now records why. This bears directly on the KYAML step 4/6 — decide KYAML scope on the evidence (owner ruling) #1023 scope question for workflows.
2. A file with no final newline is ambiguous. In k9-contractile.yml the last run: | body ends at EOF with no line break. go-yaml (yq) and eemeli/yaml disagree on its trailing \n; that is the one data-equal 56/57 in the proof. The formatter refuses such files rather than pick a reading.

Every tests/*.sh and scripts/tests/*.sh passes locally (67/67). Docstring scan: 5/5 functions documented.

🤖 Generated with Claude Code

https://claude.ai/code/session_01W5CoaksP2Bg21HpDCgFgwS

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 59 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: d7e47470-7475-4035-ab7f-d1cb7f1c6789

📥 Commits

Reviewing files that changed from the base of the PR and between 13b872c and 19c4526.

📒 Files selected for processing (3)

• 3-practice/YAML-POLICY.adoc
• scripts/kyaml-format.sh
• scripts/tests/kyaml-format-test.sh

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}