Spec Template

---
id: layer.topic # required
layer: core|sugar|emit|std|toolchain # required
title: Your Title # required
authors: ['your-handle'] # required
updated: YYYY-MM-DD # required
status: draft|proposed|accepted|deprecated # required
version: 0.0.0 # optional; include when status is accepted
---

# Spec Template

## Front Matter

- id: Unique identifier for the spec - layer.topic
- layer: The layer this spec belongs to - core, sugar, emit, std, toolchain
- title: Title of the spec
- authors: List of authors
- updated: Date of last update
- status: Status of the spec - draft, proposed, accepted, deprecated
- version: release version when this spec was accepted - only valid for `accepted` specs

## Specification Guidelines

> Pre-release Note: During the pre-release phase, specs record only the current canonical state. Do not add migration notes, deprecation guidance, or legacy syntax. When behavior changes, replace the content outright. Historical context may be kept separately outside the spec tree if needed.


- Only documents with status `accepted` are considered authoritative with regard to syntax. For other statuses, the
document is informative only, and will be aligned with the canonical spec upon acceptance.
- Specs should be as concise as possible while still being clear.
- Specs should include examples.
- Specs should avoid redundancy with other specs; if a concept is defined elsewhere, link to it.
- Prefer specification of syntax by example rather than formal grammar where possible.
- New specs begin as status `draft`, then move to `proposed` when ready for review, and finally to `accepted` when
approved.
- `Proposed` specs should use canonical syntax, but may include non-normative discussion of alternatives. If the
proposal is a syntax change, the spec should include before-and-after examples.
- `Accepted` specs should avoid discussion of alternatives, and negative examples (what is not allowed).
- `Accepted` specs must include a version number indicating the release in which the spec was accepted.
- Specs with status `deprecated` are no longer authoritative, but remain for historical reference.
- Non-canonical references must always remain status `draft`.
- See `spec/template.md` for a spec template.