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