<!--
  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.
-->

# Design Doc Schema

Canonical path: `docs/plans/<spec-id>/<YYYY-MM-DD>[-suffix]/design.md`
Path regex: `docs\/plans\/([^/]+)\/(\d{4}-\d{2}-\d{2}(?:-[^/]+)?)\/design\.md$`
Substantive content: at least 50 non-heading characters.

## Filesystem-determined shape (one behavior, no modes)

The refiner checks whether `specs/<spec-id>/spec.xml` exists. One of two
shapes applies — no mode selector, no branching skill; just conditional fields.

### When NO prior spec exists (`hasPriorSpec = false`)

When no prior spec exists, the design doc carries prose covering problem, solution, requirements, and scope. No mandatory section headings — refiner extracts from prose.

Required prose elements (refiner extracts from prose — no mandatory headings):

- problem / motivation
- proposed solution / architecture
- identifiable requirements (in prose)
- scope declaration (includes + excludes)

### When a prior spec exists (`hasPriorSpec = true`)

When a prior spec exists, the design doc carries Context + Change Intent sections. Refiner derives the <delta> from narrative; no pre-authored diff section is permitted.

Required section headings (matched via `section_regex` — see below):

- Context
- Change Intent

Recommended section headings:

- Architecture Impact

Forbidden section keywords (must NOT appear as top-level headings — the
refiner derives the delta itself from narrative, never from a pre-authored list):

- Added
- Modified
- Removed
- Renamed
- Delta

## Section heading regexes

Headings are detected via these patterns. They tolerate trailing suffix text
(e.g., `## Context (from spec v1)`, `## Context — 2026-04-19`) while rejecting
prefix words like `## Contextual Factors`.

- Context: `^#+\s+Context\b[^\n]*$`
- ChangeIntent: `^#+\s+Change\s+Intent\b[^\n]*$`

## Enforcement authority

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