Favor long-lived data formats (markdown + frontmatter)
State: open/published
Summary
Section titled “Summary”- The substrate is plain text under git: markdown with YAML frontmatter.
- Text under git is the only source of truth: no database behind the corpus, no bidirectional sync. Markdown plus frontmatter is canonical for an entity’s semantic state; a run’s execution state lives in its lease ref (D-S30G-task-state-plane-split), which is JSON in git and still text under git.
- Authoring usually goes through an API wrapper with code-based validators; direct edits are also allowed.
Statement
Section titled “Statement”The substrate of SDLC’s data model is text under git: markdown with YAML frontmatter. Schemas layer over that substrate, validators enforce structure, and tooling queries and indexes it. The file itself stays a plain text document a human or an LLM can read directly.
Scope: SDLC’s entity corpus and the lease substrate that coordinates work on it. A product store outside that corpus (the suspenders skill store, D-A27T-suspenders-skill-experience-module) is not governed here; what it publishes into the corpus is.
Tool churn is constant and the data outlives the tool. Bespoke binary formats, database schemas, and SaaS-shaped state couple the data to one runtime; plain text under git is the longest-lived substrate short of paper.
Text under git also:
- allows evolutionary progression from loose narrative to tightly defined structure through frontmatter schemas
- is easy for tooling, down to shell scripts
- gets a free review and editing UI (Obsidian) during early high-churn phases
- lives with and complements the existing SDLC tools, git and GitHub
How it applies
Section titled “How it applies”- Every entity’s semantic state is a markdown file with YAML frontmatter. A run’s execution state (who has it, what phase, what was verified) is a lease ref, never a database.
- Caches, indices, and rendered views are derived from the markdown.
- No database behind the corpus, no bidirectional syncing.
- Authoring usually goes through an API wrapper with code-based validators; direct edits are also allowed.
- Non-markdown views (JSON projections, indices, caches) are produced by the API wrapper on demand and never checked in as a second source of truth.
- Body structure is validated the same way frontmatter is: when a section becomes load-bearing, add it to the entity’s schema and validator rather than relying on convention.
Examples
Section titled “Examples”sdlc entities validatereads markdown directly; no database, no parallel cache to keep in sync.docs/dashboard.baseis a thin YAML view config over the markdown corpus; Obsidian computes the table at open time.- GitHub PRs review individual markdown files; there is no proprietary review format to translate.
Implications
Section titled “Implications”Connects to P-0005-schema-over-prose: loose narrative in the body is where unstructured data starts. As the schema solidifies, body validations land and frontmatter fields expand through migrations.
This principle derives from P-0003-pragmatic-architecture. Where product needs dictate, it may be deprecated.