Repository navigation
KYAML step 2/6 — comment-preservation proof (shared by Y-2 and Y-3) #1021
Description
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
Activity
docs(policy): cross-reference the six booked KYAML adoption issues
hyperpolymath commentedon Sep 30, 2026
Proof harness up: #1067 (
tools/yaml-comment-proof, implemented + tested, not wired). Measured onbd9313a6, 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.yq -i '.'(Y-2)yq -ipin bump (Y-2)yq -o kyaml(Y-3)yq -imoves a 10-line comment block intag-ruleset-canon.ymlto 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.yq -o kyamlconversion and re-emission preserve every comment at its node. It does not cover editing KYAML with plainyq -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.🤖 Generated with Claude Code
https://claude.ai/code/session_01WPSJ7fBhVAMcpSffCBWUDo
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
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 onuses:.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.
yq -i '.'(Y-2)yq -ipin bump (Y-2)yq -o kyaml(Y-3)Against the acceptance criteria:
cmp: kyaml 57/57.yq -o kyamlverbatim. feat(yaml): kyaml-format.sh, a KYAML formatter with --check (#1022) #1117'sscripts/kyaml-format.shruns exactly that, with no post-processing.The one data-equal miss is
k9-contractile.yml. It has no final newline, so the trailing\nof its lastrun: |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.ymlcomment block relocates on the secondyq -ipass) is a verdict the proof delivers, not unfinished proof work. It is recorded indev-notes/inbox/findings.mdas a Y-2 finding.🤖 Generated with Claude Code
https://claude.ai/code/session_01W5CoaksP2Bg21HpDCgFgwS
feat(yaml): kyaml-format.sh, a KYAML formatter with --check (#1022) (#…
docs(yaml): record KYAML scope rulings D280/D307 in §3.4 (#1177)