Skip to content

docs(yaml): record KYAML scope rulings D280/D307 in §3.4 #1177

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hyperpolymath merged 1 commit into from
Oct 6, 2026
Merged

docs(yaml): record KYAML scope rulings D280/D307 in §3.4 #1177

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 39 additions & 10 deletions 3-practice/YAML-POLICY.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -223,13 +223,32 @@ preference.
— see §4.
|===

=== 3.4 Scope is deliberately undecided
=== 3.4 Scope: KYAML everywhere, `.kyaml` where the tool allows

The owner considered mandating KYAML estate-wide including workflows, and
chose instead to *probe workflows first and decide after*, with estate-wide
adoption booked as ordered issues. Accordingly this document does **not**
mandate KYAML anywhere yet. Nothing in the estate is out of compliance with
Y-3 today, because Y-3 imposes nothing today.
The owner decided scope once the step 1 probe had landed (§5 step 4):

* *Content.* KYAML is the authoring dialect for every estate-owned YAML file,
workflows included (D280, `hyperpolymath/standards#1023`, 2026-10-01).
* *Extension.* Estate-owned configuration uses the `.kyaml` extension (D307,
2026-10-06). `.yml` or `.yaml` stays only where a tool fixes the file name or
extension: GitHub workflows (`.github/workflows/*.yml`), `action.yml`,
`dependabot.yml`, and any other file a third-party tool finds by name.
Lockfiles remain tool-owned (§6).
* *Parsers.* No Python YAML or KYAML parser is carried into a repository to
support this (D293). Formatting goes through `scripts/kyaml-format.sh`.

What is enforceable today:

* `scripts/kyaml-format.sh --check` gates the files already converted (the
step 3 ratchet list in Self Test). It handles the `.kyaml` extension: on
2026-10-06 a flow-style `.kyaml` file passed and a block-style `.kyaml` file
was refused with exit 2.
* There is no estate-wide gate. An existing YAML file that has not been
converted is migration backlog under steps 5 and 6
(`hyperpolymath/standards#1024`, `#1025`), not a violation. Workflows convert
under step 6 only, once its lock-coverage precondition holds.

New estate-owned configuration is written as `.kyaml` with KYAML content.

== 4. One proof obligation sits under two rules

Expand Down Expand Up @@ -258,6 +277,7 @@ These issues are now booked, in this dependency order:
an executed-step marker on both the KYAML arm and its plain-YAML control.
This settles the *parser* dimension only.
* Step 2 — `hyperpolymath/standards#1021` — comment-preservation proof.
_Closed._
* Step 3 — `hyperpolymath/standards#1022` — formatter/linter for arbitrary YAML:
`scripts/kyaml-format.sh [--check] FILE...`. It runs `yq -o kyaml` verbatim,
the one rewriter step 2's proof covers, and it refuses (exit 2) a file that
Expand All @@ -274,11 +294,12 @@ These issues are now booked, in this dependency order:
`.githooks/validate-actions-lock.sh` checks lock membership across the whole
file, not per workflow (standards#1025).
* Step 4 — `hyperpolymath/standards#1023` — owner ruling on scope.
_Closed:_ D280, refined by D307. See §3.4.
* Step 5 — `hyperpolymath/standards#1024` — migrate non-bot estate YAML.
* Step 6 — `hyperpolymath/standards#1025` — workflows, if step 4 rules them in.
* Step 6 — `hyperpolymath/standards#1025` — workflows. Step 4 ruled them in (D280).

Step 1 closing does *not* advance the scope question. Step 4 remains an owner
ruling and §5 explicitly forbids inferring scope from the probe.
Step 1 closing did *not* settle scope by itself. Step 4 was settled by an
owner ruling (§3.4), not inferred from the probe.

[cols="1,6,6",options="header"]
|===
Expand Down Expand Up @@ -315,7 +336,8 @@ ruling and §5 explicitly forbids inferring scope from the probe.
== 6. What this document does not rule

* It does not ban YAML. KYAML *is* YAML.
* It does not require reformatting anything today.
* It does not require reformatting an existing file outside its migration
step (§5). New files follow §3.4.
* It does not apply to lockfiles (`pnpm-lock.yaml` and friends), which are
tool-owned artefacts and must never be hand-edited or reformatted.
* It does not change `LANGUAGE-POLICY.adoc`. YAML is a data format here, not a
Expand Down Expand Up @@ -358,4 +380,11 @@ ruling and §5 explicitly forbids inferring scope from the probe.
Self Test. Step 5 batch 1 in this repo: `_shared/container/.gatekeeper.yaml`.
The remaining 73 non-workflow YAML files here are bot-read, vendored
satellite copies, or the proof's own fixtures.

| 2026-10-06
| Owner rulings D307, D293
| §3.4 rewritten: it still said scope was undecided after D280 had decided it.
Adds the `.kyaml` extension rule (D307) and the no-Python-parser rule
(D293). §6 now limits "no reformatting" to files outside their migration
step.
|===
Loading