<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/configuration/yaml-libraries/">
  <id>https://docs.spec-kitty.ai/configuration/yaml-libraries/</id>
  <title>YAML library choice: ruamel.yaml vs PyYAML</title>
  <updated>2026-10-08T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/configuration/yaml-libraries/"/>
  <summary>When Spec Kitty uses ruamel.yaml versus PyYAML: the round-trip-vs-read-only deciding criterion and the named codebase sites that currently deviate from it.</summary>
  <content type="html">&lt;span id=&quot;yaml-library-choice-ruamelyaml-vs-pyyaml&quot;&gt;&lt;/span&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Document status: current-state with known violations.&lt;/strong&gt;
This document describes the &lt;em&gt;actual&lt;/em&gt; usage patterns found in the codebase as of
2026-06-23. It also states the &lt;em&gt;intended&lt;/em&gt; deciding criterion. Where usage deviates
from the criterion, the contradiction sites are named explicitly in
§3 — they are not hidden by asserting a clean invariant.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;hr&gt;
&lt;h2 id=&quot;1-the-deciding-criterion&quot;&gt;1. The deciding criterion&lt;/h2&gt;

















&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Criterion&lt;/th&gt;&lt;th&gt;Library&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Round-trip read/write&lt;/strong&gt; — file must be rewritten while preserving quotes, comments, indentation, and original formatting (e.g., frontmatter, &lt;code dir=&quot;auto&quot;&gt;config.yaml&lt;/code&gt;, Charter Packs)&lt;/td&gt;&lt;td&gt;&lt;strong&gt;ruamel.yaml&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Read-only simple data&lt;/strong&gt; — file is only ever consumed (never rewritten by Spec Kitty), contains no user-authored comments or formatting worth preserving, and the data is flat/simple&lt;/td&gt;&lt;td&gt;&lt;strong&gt;PyYAML &lt;code dir=&quot;auto&quot;&gt;safe_load&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;why-ruamelyaml-for-round-trip&quot;&gt;Why ruamel.yaml for round-trip&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;ruamel.yaml&lt;/code&gt; exposes the &lt;code dir=&quot;auto&quot;&gt;YAML(typ=&apos;rt&apos;)&lt;/code&gt; (round-trip) parser and the &lt;code dir=&quot;auto&quot;&gt;CommentedMap&lt;/code&gt; type, which preserve:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;inline and end-of-line comments&lt;/li&gt;
&lt;li&gt;quoted-string style (single vs double quotes, block scalars)&lt;/li&gt;
&lt;li&gt;mapping key order and indentation&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Spec Kitty rewrites &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;, WP frontmatter files, and Charter Pack YAMLs in-place. Without round-trip parsing, every write would destroy user comments and reformat the file — which breaks diff readability and silently corrupts user customization.&lt;/p&gt;
&lt;h3 id=&quot;why-pyyaml-safe_load-for-read-only-data&quot;&gt;Why PyYAML &lt;code dir=&quot;auto&quot;&gt;safe_load&lt;/code&gt; for read-only data&lt;/h3&gt;
&lt;p&gt;PyYAML’s &lt;code dir=&quot;auto&quot;&gt;yaml.safe_load&lt;/code&gt; is a single-call read with no write path. It is appropriate when:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;The file is generated (e.g., &lt;code dir=&quot;auto&quot;&gt;graph.yaml&lt;/code&gt;, migration fragments, DRG fragments) and has no user-authored comments.&lt;/li&gt;
&lt;li&gt;The caller only inspects the data and never writes it back.&lt;/li&gt;
&lt;li&gt;A lightweight, stdlib-style call is sufficient and no formatting invariants exist.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;safe_load&lt;/code&gt; is &lt;em&gt;not&lt;/em&gt; appropriate for any write-back path — calling &lt;code dir=&quot;auto&quot;&gt;yaml.dump&lt;/code&gt; after a &lt;code dir=&quot;auto&quot;&gt;safe_load&lt;/code&gt; will discard all comments and reformulate quoting.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;2-verified-call-sites&quot;&gt;2. Verified call sites&lt;/h2&gt;
&lt;h3 id=&quot;21-ruamelyaml-sites-round-trip-read-write&quot;&gt;2.1 ruamel.yaml sites (round-trip, read-write)&lt;/h3&gt;















































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Site&lt;/th&gt;&lt;th&gt;Line&lt;/th&gt;&lt;th&gt;Pattern&lt;/th&gt;&lt;th&gt;Purpose&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/drg/org_pack_config.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;216–218&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;_yaml()&lt;/code&gt; factory: &lt;code dir=&quot;auto&quot;&gt;YAML(); yaml.preserve_quotes = True&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Read and write &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; — the operator-facing pack registry&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/frontmatter.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;16–18&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;from ruamel.yaml import YAML, CommentedMap&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;FrontmatterManager&lt;/code&gt; — read and write WP frontmatter files in place (rule 1: always use ruamel.yaml; rule 4: preserve comments)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/yaml_utils.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;21&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;from ruamel.yaml import YAML&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;canonical_yaml()&lt;/code&gt; — deterministic sorted-key serializer for hashing; uses ruamel for consistent output&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/drg/loader.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;12–13&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;from ruamel.yaml import YAML, YAMLError&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Doctrine relationship graph (DRG) loader — round-trip parse&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/activation/pack_manager.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;453–454&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;YAML(); yaml.preserve_quotes = True&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;_load_config()&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;_save_config()&lt;/code&gt; — read + write &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;ActiveCharterManager&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/review/artifacts.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;20&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;from ruamel.yaml import YAML&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Review artifact serialization — preserve existing frontmatter style&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;22-pyyaml-safe_load-sites-read-only&quot;&gt;2.2 PyYAML &lt;code dir=&quot;auto&quot;&gt;safe_load&lt;/code&gt; sites (read-only)&lt;/h3&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Site&lt;/th&gt;&lt;th&gt;Line&lt;/th&gt;&lt;th&gt;What is read&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/drg/org_pack_loader.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;504&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;fragment.yaml&lt;/code&gt; from an org pack’s &lt;code dir=&quot;auto&quot;&gt;drg/&lt;/code&gt; subdirectory — generated, no comments&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/drg/org_pack_loader.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;617&lt;/td&gt;&lt;td&gt;Individual doctrine artifact YAML files — read-only inspection of &lt;code dir=&quot;auto&quot;&gt;id&lt;/code&gt; key&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/drg/override_policy.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;130&lt;/td&gt;&lt;td&gt;Override policy file — read-only load&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/packs/pack_assembler.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;667–669&lt;/td&gt;&lt;td&gt;Generated graph fragment and &lt;code dir=&quot;auto&quot;&gt;org-charter.yaml&lt;/code&gt; — write path uses &lt;code dir=&quot;auto&quot;&gt;pyyaml.safe_dump&lt;/code&gt;, not round-trip&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;src/runtime/next/_internal_runtime/discovery.py&lt;/code&gt;&lt;/td&gt;&lt;td&gt;128, 191&lt;/td&gt;&lt;td&gt;Runtime discovery config files — read-only&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;hr&gt;
&lt;h2 id=&quot;3-known-mixed-usage--to-reconcile&quot;&gt;3. Known mixed-usage / to-reconcile&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;This section names sites where the &lt;strong&gt;same conceptual file&lt;/strong&gt; (or file class) is read
via different libraries in different callers. These are the contradiction sites — not
a clean invariant.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h3 id=&quot;31-primary-contradiction-kittifyconfigyaml&quot;&gt;3.1 Primary contradiction: &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;The same &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; data is read via two different libraries:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/drg/org_pack_config.py&lt;/code&gt; (line 216–218): uses &lt;strong&gt;ruamel.yaml&lt;/strong&gt; with &lt;code dir=&quot;auto&quot;&gt;preserve_quotes=True&lt;/code&gt;. This is the &lt;strong&gt;write&lt;/strong&gt; path — &lt;code dir=&quot;auto&quot;&gt;save_pack_registry()&lt;/code&gt; writes back via the same ruamel instance.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/activation/pack_manager.py&lt;/code&gt; (line 447–476): uses &lt;strong&gt;ruamel.yaml&lt;/strong&gt; for reads &lt;em&gt;and&lt;/em&gt; writes (&lt;code dir=&quot;auto&quot;&gt;_load_config()&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;_save_config()&lt;/code&gt;). This is consistent with the criterion.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;However, several &lt;em&gt;other&lt;/em&gt; callers read &lt;code dir=&quot;auto&quot;&gt;config.yaml&lt;/code&gt;-class data via PyYAML &lt;code dir=&quot;auto&quot;&gt;safe_load&lt;/code&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/agent_utils/status.py&lt;/code&gt; (line 134): &lt;code dir=&quot;auto&quot;&gt;_yaml.safe_load(config_file.read_text())&lt;/code&gt; reads a config file that is the same shape as &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/cli/commands/agent/tasks_status_cmd.py&lt;/code&gt; (line 910): &lt;code dir=&quot;auto&quot;&gt;yaml.safe_load(config_file...)&lt;/code&gt; reads &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; for the &lt;code dir=&quot;auto&quot;&gt;agent tasks&lt;/code&gt; command. (Two former callers — the sync runtime’s config read and an older &lt;code dir=&quot;auto&quot;&gt;agent tasks&lt;/code&gt; call site — were deleted or moved with the sync transport’s retirement, Convergence #3881.)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;These callers are read-only (no write-back) so PyYAML &lt;code dir=&quot;auto&quot;&gt;safe_load&lt;/code&gt; does not corrupt the file; however they are inconsistent with the pattern in the canonical write paths. If any of these callers were extended to perform writes, they would need to be converted to ruamel.yaml to avoid formatting loss.&lt;/p&gt;
&lt;h3 id=&quot;32-secondary-pack_assemblerpy-dual-use&quot;&gt;3.2 Secondary: &lt;code dir=&quot;auto&quot;&gt;pack_assembler.py&lt;/code&gt; dual-use&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;src/charter/offering/packs/pack_assembler.py&lt;/code&gt; imports both ruamel (top-level, line 38) for the main assembly pipeline and PyYAML (&lt;code dir=&quot;auto&quot;&gt;import yaml as pyyaml&lt;/code&gt;, lines 667–669) for write-back of generated &lt;code dir=&quot;auto&quot;&gt;graph.yaml&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;org-charter.yaml&lt;/code&gt;. The generated files have no user-authored comments, so &lt;code dir=&quot;auto&quot;&gt;safe_dump&lt;/code&gt; is acceptable. (A former &lt;code dir=&quot;auto&quot;&gt;# ruamel.yaml or pyyaml&lt;/code&gt; ambiguity in the local dashboard’s glossary handler went away when the bundled dashboard was removed.)&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;4-aspirational-rule-not-yet-enforced&quot;&gt;4. Aspirational rule (not yet enforced)&lt;/h2&gt;
&lt;p&gt;The criterion in §1 is the &lt;strong&gt;intended&lt;/strong&gt; long-term rule. The following enforcement gaps exist in the current codebase:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;No lint guard&lt;/strong&gt; enforces the criterion. A developer can add a &lt;code dir=&quot;auto&quot;&gt;yaml.safe_load&lt;/code&gt; call to a write-path module without any automated warning.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Several read-only callers of &lt;code dir=&quot;auto&quot;&gt;config.yaml&lt;/code&gt;&lt;/strong&gt; use &lt;code dir=&quot;auto&quot;&gt;safe_load&lt;/code&gt; (§3.1). These are safe today but diverge from the pattern and risk write-back misuse.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;pack_assembler.py&lt;/code&gt;&lt;/strong&gt; holds both libraries in the same file without a documented rationale explaining why the fallback to PyYAML is intentional.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;A future hardening step (tracked upstream) would:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Add a ruff or import-guard rule banning &lt;code dir=&quot;auto&quot;&gt;import yaml&lt;/code&gt; (PyYAML) in modules that contain any ruamel import.&lt;/li&gt;
&lt;li&gt;Consolidate all &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; reads through &lt;code dir=&quot;auto&quot;&gt;org_pack_config.load_pack_registry()&lt;/code&gt; so the library choice is centralised.&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;5-quick-reference&quot;&gt;5. Quick reference&lt;/h2&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Need to READ AND WRITE a file?&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;→ ruamel.yaml (YAML(); yaml.preserve_quotes = True)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Need to READ ONLY a generated/simple file?&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;→ PyYAML: yaml.safe_load(path.read_text(encoding=&quot;utf-8&quot;))&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;Unsure?&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;→ Default to ruamel.yaml. It is always safe; PyYAML `safe_load` is an&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;optimisation for callers with no write-back path.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;hr&gt;
&lt;p&gt;&lt;em&gt;See also:&lt;/em&gt; &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/docs/archive/plans/3-2-doc-publication/3-2-information-architecture.md&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/development/3-2-information-architecture.md&lt;/code&gt;&lt;/a&gt; — documentation IA index for the &lt;code dir=&quot;auto&quot;&gt;docs/development/&lt;/code&gt; tree.&lt;/p&gt;</content>
</entry>
