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

# Vision Schema

Two-tier, date-less vision artifact — outside `DESIGN_DOC_RULES.path_regex`.
LLM agents are read-only; only humans may modify these files.

## Tiers

**Product vision**: `product/vision.md`

Single file, shared across all specs. Defines north-star product principles `P-1, P-2…`.

**Spec vision**: `specs/<spec-id>/vision.md`

Per-spec scope chapter. References product principles via `principle_ref` fields.

## Principle Identifier Pattern

Product vision principles are identified by: `^(P-\d+)`

Examples: `P-1`, `P-12`. Principles appear at the start of a line (e.g. `P-1.` or `P-1:`).

## principle_ref

Field key: `principle_ref`. Per-spec decisions reference product principles using this key.

`validateVision` cross-checks that every `principle_ref` in a spec vision resolves to a `P-n` present in `product/vision.md`.

## LLM Access

`readonly` — vision files are human-written anchors.
Agents MUST NOT write to vision files. Enforcement is via write-path blocking in the harness.

## Enforcement Authority

`scripts/lib/sdd-rules.js` — `VISION_RULES` is the canonical source of truth
(re-exported via `scripts/lib/sdd-utils.js`). `validateVision` in `sdd-utils.js`
is the enforcement function. If this document disagrees with the constant,
the constant wins (file a bug).
