From e149b1ccc8f77843a2bfe9db7ea67256cbe142f1 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 6 Oct 2026 21:22:53 +0100 Subject: [PATCH] =?UTF-8?q?docs(yaml):=20record=20KYAML=20scope=20rulings?= =?UTF-8?q?=20D280/D307=20in=20=C2=A73.4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit §3.4 still said scope was "deliberately undecided" after D280 had decided it. It now records KYAML content everywhere (D280), the .kyaml extension wherever a tool does not fix the name (D307), and no Python YAML parsers (D293), and says what is enforceable today. The §5 step statuses and §6 "no reformatting" are aligned with it. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01D6JVLvmCeSFGcY6jSNesbL --- 3-practice/YAML-POLICY.adoc | 49 +++++++++++++++++++++++++++++-------- 1 file changed, 39 insertions(+), 10 deletions(-) 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. |===