fix(ce-compound): quote YAML array items starting with reserved indicators (#613)

Co-authored-by: Nathan Vale <hi@nathanvale.com>

plugins/compound-engineering/skills/ce-compound-refresh/SKILL.md

@@ -516,7 +516,7 @@ Do not let replacement subagents invent frontmatter fields, enum values, or sect
    - A summary of the investigation evidence (what changed, what the current code does, why the old guidance is misleading)
    - The target path and category (same category as the old learning unless the category itself changed)
    - The relevant contents of the three support files listed above
-2. The subagent writes the new learning using the support files as the source of truth: `references/schema.yaml` for frontmatter fields and enum values, `references/yaml-schema.md` for category mapping, and `assets/resolution-template.md` for section order. It should use dedicated file search and read tools if it needs additional context beyond what was passed.
+2. The subagent writes the new learning using the support files as the source of truth: `references/schema.yaml` for frontmatter fields and enum values, `references/yaml-schema.md` for category mapping and YAML-safety rules for array items, and `assets/resolution-template.md` for section order. It should use dedicated file search and read tools if it needs additional context beyond what was passed.
 3. After the subagent completes, the orchestrator deletes the old learning file. The new learning's frontmatter may include `supersedes: [old learning filename]` for traceability, but this is optional — the git history and commit message provide the same information.
 
 **When evidence is insufficient:**

plugins/compound-engineering/skills/ce-compound-refresh/assets/resolution-template.md

@@ -8,6 +8,8 @@ Choose the template matching the problem_type track (see `references/schema.yaml
 
 Use for: `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error`
 
+<!-- YAML safety: array items (symptoms, applies_when, tags, related_components) starting with ` [ * & ! | > % @ ? or containing ": " must be wrapped in double quotes. See references/yaml-schema.md > "YAML Safety Rules". -->
+
 ```markdown
 ---
 title: [Clear problem title]
@@ -54,6 +56,8 @@ tags: [keyword-one, keyword-two]
 
 Use for: `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience`
 
+<!-- YAML safety: array items (symptoms, applies_when, tags, related_components) starting with ` [ * & ! | > % @ ? or containing ": " must be wrapped in double quotes. See references/yaml-schema.md > "YAML Safety Rules". -->
+
 ```markdown
 ---
 title: [Clear, descriptive title]

plugins/compound-engineering/skills/ce-compound-refresh/references/schema.yaml

@@ -228,3 +228,4 @@ validation_rules:
   - "date must match YYYY-MM-DD format"
   - "rails_version, if provided, must match X.Y.Z format and only applies to bug-track docs"
   - "tags should be lowercase and hyphen-separated"
+  - "Array-of-strings frontmatter items (symptoms, applies_when, tags, related_components, or any future array field) must be wrapped in double quotes when the value starts with a YAML reserved indicator (`, [, *, &, !, |, >, %, @, ?) or contains the substring `: ` — otherwise strict YAML parsers reject the file"

plugins/compound-engineering/skills/ce-compound-refresh/references/yaml-schema.md

@@ -89,3 +89,30 @@ Docs created before the track system may have `symptoms`/`root_cause`/`resolutio
 7. Array fields must respect min/max item counts.
 8. `date` must match `YYYY-MM-DD`.
 9. `rails_version`, if present, must match `X.Y.Z` and only applies to bug-track docs.
+
+## YAML Safety Rules
+
+Strict YAML 1.2 parsers (`yq`, `js-yaml` strict, PyYAML) reject array items
+that start with a reserved indicator character as unquoted scalars. When
+writing items for any array-of-strings field (`symptoms`, `applies_when`,
+`tags`, `related_components`, or any future array field), wrap the value in
+double quotes if it starts with any of:
+
+`` ` ``, `[`, `*`, `&`, `!`, `|`, `>`, `%`, `@`, `?`
+
+Also quote if the value contains the substring `": "` — that punctuation
+confuses flow-style parsers.
+
+Example — before (breaks strict YAML):
+
+    symptoms:
+      - `sudo dscacheutil -flushcache` does not restore in-container mDNS
+
+Example — after (parses cleanly):
+
+    symptoms:
+      - "`sudo dscacheutil -flushcache` does not restore in-container mDNS"
+
+This rule applies to all array-of-strings frontmatter fields. Scalar string
+fields like `description:` have their own quoting rules (see plugin
+`AGENTS.md` under "YAML Frontmatter").

plugins/compound-engineering/skills/ce-compound/SKILL.md

@@ -216,7 +216,7 @@ The orchestrating agent (main conversation) performs these steps:
    - Tag session-sourced content with "(session history)" so its origin is clear to future readers
    - If findings are thin or "no relevant prior sessions," proceed without session context
 4. Assemble complete markdown file from the collected pieces, reading `assets/resolution-template.md` for the section structure of new docs
-5. Validate YAML frontmatter against `references/schema.yaml`
+5. Validate YAML frontmatter against `references/schema.yaml`, including the YAML-safety quoting rule for array items (see `references/yaml-schema.md` > YAML Safety Rules)
 6. Create directory if needed: `mkdir -p docs/solutions/[category]/`
 7. Write the file: either the updated existing doc or the new `docs/solutions/[category]/[filename].md`
 
@@ -340,7 +340,7 @@ The orchestrator (main conversation) performs ALL of the following in one sequen
 1. **Extract from conversation**: Identify the problem and solution from conversation history. Also scan the "user's auto-memory" block injected into your system prompt, if present (Claude Code only) -- use any relevant notes as supplementary context alongside conversation history. Tag any memory-sourced content incorporated into the final doc with "(auto memory [claude])"
 2. **Classify**: Read `references/schema.yaml` and `references/yaml-schema.md`, then determine track (bug vs knowledge), category, and filename
 3. **Write minimal doc**: Create `docs/solutions/[category]/[filename].md` using the appropriate track template from `assets/resolution-template.md`, with:
-   - YAML frontmatter with track-appropriate fields
+   - YAML frontmatter with track-appropriate fields, applying the YAML-safety quoting rule for array items (see `references/yaml-schema.md` > YAML Safety Rules)
    - Bug track: Problem, root cause, solution with key code snippets, one prevention tip
    - Knowledge track: Context, guidance with key examples, one applicability note
 4. **Skip specialized agent reviews** (Phase 3) to conserve context

plugins/compound-engineering/skills/ce-compound/assets/resolution-template.md

@@ -8,6 +8,8 @@ Choose the template matching the problem_type track (see `references/schema.yaml
 
 Use for: `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error`
 
+<!-- YAML safety: array items (symptoms, applies_when, tags, related_components) starting with ` [ * & ! | > % @ ? or containing ": " must be wrapped in double quotes. See references/yaml-schema.md > "YAML Safety Rules". -->
+
 ```markdown
 ---
 title: [Clear problem title]
@@ -54,6 +56,8 @@ tags: [keyword-one, keyword-two]
 
 Use for: `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience`
 
+<!-- YAML safety: array items (symptoms, applies_when, tags, related_components) starting with ` [ * & ! | > % @ ? or containing ": " must be wrapped in double quotes. See references/yaml-schema.md > "YAML Safety Rules". -->
+
 ```markdown
 ---
 title: [Clear, descriptive title]

plugins/compound-engineering/skills/ce-compound/references/schema.yaml

@@ -228,3 +228,4 @@ validation_rules:
   - "date must match YYYY-MM-DD format"
   - "rails_version, if provided, must match X.Y.Z format and only applies to bug-track docs"
   - "tags should be lowercase and hyphen-separated"
+  - "Array-of-strings frontmatter items (symptoms, applies_when, tags, related_components, or any future array field) must be wrapped in double quotes when the value starts with a YAML reserved indicator (`, [, *, &, !, |, >, %, @, ?) or contains the substring `: ` — otherwise strict YAML parsers reject the file"

plugins/compound-engineering/skills/ce-compound/references/yaml-schema.md

@@ -89,3 +89,30 @@ Docs created before the track system may have `symptoms`/`root_cause`/`resolutio
 7. Array fields must respect min/max item counts.
 8. `date` must match `YYYY-MM-DD`.
 9. `rails_version`, if present, must match `X.Y.Z` and only applies to bug-track docs.
+
+## YAML Safety Rules
+
+Strict YAML 1.2 parsers (`yq`, `js-yaml` strict, PyYAML) reject array items
+that start with a reserved indicator character as unquoted scalars. When
+writing items for any array-of-strings field (`symptoms`, `applies_when`,
+`tags`, `related_components`, or any future array field), wrap the value in
+double quotes if it starts with any of:
+
+`` ` ``, `[`, `*`, `&`, `!`, `|`, `>`, `%`, `@`, `?`
+
+Also quote if the value contains the substring `": "` — that punctuation
+confuses flow-style parsers.
+
+Example — before (breaks strict YAML):
+
+    symptoms:
+      - `sudo dscacheutil -flushcache` does not restore in-container mDNS
+
+Example — after (parses cleanly):
+
+    symptoms:
+      - "`sudo dscacheutil -flushcache` does not restore in-container mDNS"
+
+This rule applies to all array-of-strings frontmatter fields. Scalar string
+fields like `description:` have their own quoting rules (see plugin
+`AGENTS.md` under "YAML Frontmatter").