diff --git a/3-practice/YAML-POLICY.adoc b/3-practice/YAML-POLICY.adoc index 490d9cc95..2dc98ad21 100644 --- a/3-practice/YAML-POLICY.adoc +++ b/3-practice/YAML-POLICY.adoc @@ -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 @@ -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 @@ -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"] |=== @@ -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 @@ -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. |===