<!--
  AUTO-GENERATED from scripts/lib/sdd-utils.js (DESIGN_DOC_RULES, SPEC_HEADER_RULES)
  and scripts/lib/sdd-rules.js (DECISION_LOG_RULES, PENDING_CONFLICT_RULES,
  VISION_RULES, DECISION_LEDGER_RULES).
  Do NOT edit this file by hand. To change the schema, edit the source constant in
  the corresponding module and regenerate:

    node scripts/lib/print-schema.js design            --markdown > scripts/lib/sdd-schemas/design.md
    node scripts/lib/print-schema.js spec              --markdown > scripts/lib/sdd-schemas/spec.md
    node scripts/lib/print-schema.js decision-log      --markdown > scripts/lib/sdd-schemas/decision-log.md
    node scripts/lib/print-schema.js pending-conflict  --markdown > scripts/lib/sdd-schemas/pending-conflict.md
    node scripts/lib/print-schema.js vision            --markdown > scripts/lib/sdd-schemas/vision.md
    node scripts/lib/print-schema.js decision-ledger   --markdown > scripts/lib/sdd-schemas/decision-ledger.md

  tests/scripts/sdd-schemas-fresh.test.js asserts this file stays in sync with the
  source — a stale copy will fail CI.
-->

# Spec Identity Header Schema

Canonical path: `specs/<spec-id>/spec.xml`
`design_iteration` regex: `^\d{4}-\d{2}-\d{2}(-.+)?$`
`supersedes` regex: `^[a-z0-9-]+:v\d+$`

## Always-required fields (missing any → ERROR)

| Field | Type |
|---|---|
| `spec_version` | positive integer |
| `status` | enum (allowed: ["active"]) |
| `title` | string |
| `source/design_path` | existing file path |
| `source/design_iteration` | YYYY-MM-DD[-suffix] |

## Conditionally-required fields

| Field | Condition | Format |
|---|---|---|
| `supersedes` | spec_version > 1 | `<spec-id>:v<N>` |

## Scope element (always present inside `<overview>`)

- `includes` — required; list of <feature id="..."> elements (empty = WARNING)
- `excludes` — recommended; list of <reason> elements

## Delta element (wiki-style accumulation)

- Required when: spec_version > 1
- Placement: children of <overview>, appended each iteration, never overwritten
- Ordering: ascending by version attribute, strictly unique

Last `<delta>` invariants:

- `version` — MUST equal current spec_version
- `iteration` — MUST equal current source/design_iteration

Per-child rules:

- `<added>` — ref MUST correspond to a current <requirement id>
- `<modified>` — ref MUST correspond to a current <requirement id>
- `<removed>` — ref refers to a now-deleted requirement; MUST include <reason> child; optional <migration>
- `<renamed>` — MUST have both ref_old and ref_new attributes; body unchanged (semantic changes use removed+added)

## Enforcement authority

`scripts/lib/sdd-utils.js` — `parseSpecHeader` + `validateSpecHeader` are the sole
enforcement. If this printed schema disagrees with the validator, the validator
wins and this tool is wrong (file a bug).
