IDs & frontmatter

ID conventions

• FEAT-0001 — features. Hierarchy via sub_feature_of, never encoded in the ID (no FEAT-0001.2 schemes).
• DEC-0001 — decisions.
• ARCH-0001 — architecture notes, deferred until the build phase begins.
• IDs are permanent, unique, and greppable. They are the index an AI maintainer would otherwise have to reconstruct every session.

Feature frontmatter

Carried by marketing pages and doc pages (validated in src/content.config.ts):

id: FEAT-0012
title: Usage-based billing
version: mvp            # version this FIRST ships in (a fact, set once)
status: proposed        # proposed | resolved | built
sub_feature_of: FEAT-0003   # optional
depends_on: [FEAT-0007]     # optional
decisions: [DEC-0004, DEC-0009]
screens: [BillingOverview, InvoiceDetail]
# implemented_in: GENERATED by gen-manifest.mjs — never hand-written

Status semantics

Status	Meaning	Lint requirement
proposed	dreamed, not committed	none
resolved	specced and underway	ID tagged in code
built	shipped	ID in code and tests

Decision frontmatter

id: DEC-0004
title: Auth provider choice
status: open            # open | resolved | superseded
resolve_by: mvp         # mvp | v1 | v2 | ... — the tiering that enables dreaming
affects: [FEAT-0012]
private: true           # true = excluded from production build
anchor:                 # optional; set when it originated as an annotation
  source: src/screens/Onboarding.astro:38
  selector: '...'

private: true pages (unresolved decisions, cut features) render in dev and strip from production builds.

States & edge cases

• Missing edge target — any depends_on / decisions / affects / sub_feature_of / superseded_by pointing at a nonexistent ID fails CI.
• Duplicate declaration — the same ID declared twice within one collection fails CI. One feature ID may appear on at most one marketing page and one docs page.
• Version is set once — previewing other versions never edits frontmatter; the slider is client-side state.