YAML in HTML Comment question

[ckelsoe]

I am getting started with Spec-Kit. I noticed that the constitution file has YAML data embedded in an HTML comment. This isn't very clear to me, considering that Markdown supports YAML natively, and Markdown editors like Obsidian support YAML front matter, which is highly machine-readable. What is the thought process of the current method of embedded YAML in an HTML comment block?

[raulduk3]

Hello, I am not certain if this will answer your question completely, but I believe this addition is to track required changes to template files to align with the constitution as introduced by commit 2f043ef five days ago. I think YAML is easily ready by CI integrations, perhaps?

Currently if you look inside /prompts/constitution.prompt.md on lines 42 to 48, you can see that it says:

5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
   - Version change: old → new
   - List of modified principles (old title → new title if renamed)
   - Added sections
   - Removed sections
   - Templates requiring updates (✅ updated / ⚠ pending) with file paths
   - Follow-up TODOs if any placeholders intentionally deferred.

[ckelsoe]

@raulduk3 I agree with your assessment. I do not understand the need to embed the YAML in an HTML comment. That adds a layer of complexity vs just straight YAML, which machine code can handle very well, as well as editors like Obsidian and other Markdown tools can handle natively. The example below is from the constitution as pure YAML frontmatter. It does not need to be wrapped in HTML, forcing the tools to extract the YAML to work with it.

  title: "Sync Impact Report"
  version_change: "2.1.1 → 3.0.0 (MAJOR: Complete governance restructure with 9 core
  principles)"

  modified_principles:
    - "Complete replacement of template with 9 concrete principles from production learnings"

  added_sections:
    - "Development Standards (Code Quality, Testing, Documentation, State Management, Error
  Handling)"
    - "Architectural Standards (Module Organization, Dependency Rules, API Design)"
    - "Process Governance (Code Review, Version Control, CI)"
    - "Compliance Verification (Pre-Commit, Pull Request checks)"
    - "Enforcement (Violation Consequences)"

  removed_sections:
    - "Generic template placeholders"

  templates_requiring_updates:
    - "✅ updated: .specify/templates/plan-template.md (constitution version and gates
  updated)"
    - "⚠ pending: .specify/templates/spec-template.md (no changes needed - spec is
  business-focused)"
    - "⚠ pending: .specify/templates/tasks-template.md (no changes needed - follows TDD
  principle)"
    - "⚠ pending: .specify/templates/commands/*.md (to be reviewed)"

  follow_up_todos:
    - "None (all values concretely defined)"

[raulduk3]

It might be the case that one of the prompts/commands is explicitly written to ignore this initial HTML comment encapsulating the template change log.