KYAML step 2/6 — comment-preservation proof (shared by Y-2 and Y-3)

[hyperpolymath]

Step 2 of 6 in the KYAML adoption order fixed by 3-practice/YAML-POLICY.adoc §5.
Blocked by #1020 (landed ✅).

Work

The comment-preservation proof of §4 — shared by Y-2 (yq for writing) and
Y-3 (KYAML). Per §4 this proof is written once and satisfies both rules:
"Whichever of Y-2 or Y-3 reaches it first pays for it; the other inherits it.
Do not commission two proofs."

Gate (§5)

Round trip preserves every comment and its line association; idempotent under
cmp; a dropped-comment mutant dies.

Why this is the load-bearing step

§2.1: the pin comment is load-bearing. A rewrite that emits valid, running,
comment-stripped workflows has failed — §4 is explicit that parse-clean is
not the bar. KEP-5295 itself warns that automated reformatting is lossy, because
go-yaml "does not always handle comments properly", so comments may be "formatted
wrongly, or lost entirely".

Acceptance criteria

• Round-trip over the estate's real pin-comment corpus, not a toy fixture.
• Every comment survives with its line association — a comment that
  survives but migrates to another key is a failure, not a pass.
• Idempotent: a second pass is byte-identical under cmp.
• A dropped-comment mutant dies. A green proof with no dead mutant is
  not evidence; assert the mutation was actually applied, and that the
  mutant parses, before believing its red.
• The proof states which rewriter it covers (yq -i, a KYAML formatter, or
  both) — it does not generalise for free to a rewriter it never ran.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01WRvDivYwLSeVCJUrfjic3f

[hyperpolymath]

Proof harness up: #1067 (tools/yaml-comment-proof, implemented + tested, not wired). Measured on bd9313a6, 56 workflows, yq v4.53.3 — 2186 comments, 183 trailing pin comments (matches the grep count). Calibration pair and both corpus mutants (dropped pin, moved pin) are detected before any arm is read.

arm	preserved	moved	dropped	pass-2 drift	idempotent	verdict
yq -i '.' (Y-2)	2186/2186	0	0	10	55/56	FAIL
yq -i pin bump (Y-2)	2186/2186	0	0	10	55/56	FAIL
yq -o kyaml (Y-3)	2186/2186	0	0	0	56/56	PASS

• Y-2: not idempotent — a second yq -i moves a 10-line comment block in tag-ruleset-canon.yml to a different node. Filed as yq -i is not idempotent: a second run moves a comment block (tag-ruleset-canon.yml) #1068. Y-2 stays NOT IN FORCE.
• Y-3: evidence that yq -o kyaml conversion and re-emission preserve every comment at its node. It does not cover editing KYAML with plain yq -i, nor KEP-5295 conformance of yq's dialect (no ---; EOF comment pulled inside the brace) — KYAML step 3/6 — a KYAML formatter/linter for arbitrary YAML #1022. Scope remains KYAML step 4/6 — decide KYAML scope on the evidence (owner ruling) #1023's ruling.
• Not covered: kubectl's KYAML printer. Blank-line loss (567 / 813) is reported, not failed on.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WPSJ7fBhVAMcpSffCBWUDo

[hyperpolymath]

Re-run on 13b872c1 (main after #1115): bun prove.js .github/workflows/*.yml, yq v4.53.3, 57 files, 2245 comments, 192 trailing pin comments on uses:.

Controls first: the calibration pair is 9/9 PRESERVED; the moved and dropped controls are red; the corpus dropped-pin and moved-pin mutants are both killed, each naming file and path.

arm	preserved	moved	dropped	pass-2 drift	idempotent	data-equal	verdict
yq -i '.' (Y-2)	2245/2245	0	0	10	56/57	56/57	FAIL
yq -i pin bump (Y-2)	2245/2245	0	0	10	56/57	n/a	FAIL
yq -o kyaml (Y-3)	2245/2245	0	0	0	57/57	56/57	PASS

Against the acceptance criteria:

• Real corpus: yes, all 57 workflows on main.
• Line association: yes. MOVED counts as a failure, and the kyaml arm has 0 moved.
• Idempotent under cmp: kyaml 57/57.
• Dropped-comment mutant dies: yes, and it was asserted as applied first.
• States which rewriter it covers: yq -o kyaml verbatim. feat(yaml): kyaml-format.sh, a KYAML formatter with --check (#1022) #1117's scripts/kyaml-format.sh runs exactly that, with no post-processing.

The one data-equal miss is k9-contractile.yml. It has no final newline, so the trailing \n of its last run: | body depends on which parser reads it (go-yaml vs eemeli/yaml). #1117 refuses such files rather than choose a reading.

Closing: the proof exists, runs, and its kyaml verdict is PASS. The Y-2 arms' FAIL (the tag-ruleset-canon.yml comment block relocates on the second yq -i pass) is a verdict the proof delivers, not unfinished proof work. It is recorded in dev-notes/inbox/findings.md as a Y-2 finding.

🤖 Generated with Claude Code

https://claude.ai/code/session_01W5CoaksP2Bg21HpDCgFgwS