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

# Decision Ledger Schema

Canonical path: `specs/<spec-id>/decisions.yml`

The decision ledger is the cross-iteration strategic WHY log for a spec. It is distinct from the per-session `decision-log.yml` Q&A trace.

## Required Fields per Entry

All required fields MUST be present in every entry. Missing any one field is an ERROR.

| Field | Type | Description |
|---|---|---|
| `D-id` | string | Monotonically increasing unique decision identifier (e.g. D-001, D-002). Non-increasing or duplicate D-id within a ledger is ERROR. |
| `date` | string | ISO date when this decision was recorded (YYYY-MM-DD). |
| `spec_version` | string | Spec version (design_iteration) active when this decision was recorded. |
| `status` | string | Decision status. One of: 'proposed' (drafted, not yet ratified), 'accepted' (ratified by human via arcforge ratify), or 'superseded-by:D-NNN' (superseded by a newer entry — open-ended string form). Status transitions other than via supersede are ERROR. |
| `decision` | string | Prose description of the decision made. Once recorded, this text is immutable — editing it against HEAD is ERROR. Corrections require a superseding entry. |
| `why` | string | Rationale for the decision. Once recorded, this text is immutable — editing it against HEAD is ERROR. Corrections require a superseding entry. |
| `authorized_values` | list | Structured list of concrete values authorized by this decision (e.g. ["window=60s"]). mechanicalAuthorizationCheck compares cited trace values against this list (exact match, not substring). Required even if empty ([]) so the field is always present. |

## Optional Fields per Entry

These fields MAY appear in entries; absence is benign.

| Field | Type | Description |
|---|---|---|
| `supersedes` | string | D-id of the entry this decision supersedes (e.g. D-007). Required when status of the referenced entry is being set to superseded-by:D-NNN. |
| `ratified_by` | string | Provenance marker set by arcforge ratify: identifies who ratified and when. Required for status=accepted entries; absent on proposed entries. |
| `principle_ref` | string | Optional reference to a product-level vision principle (e.g. P-1). validateDecisionLedger does not enforce this field; validateVision cross-checks it. |

## Immutability Contract

HEAD-relative; see validateDecisionLedger for enforcement semantics.

The `decision` and `why` fields are frozen once committed. Editing them against HEAD is ERROR. Corrections require a superseding entry.

Known limitation: same-session pre-commit append-then-edit escapes the HEAD-relative check.

## D-id Monotonicity

D-ids follow the format `D-NNN` (e.g. `D-001`, `D-042`). They MUST be monotonically increasing and unique within a ledger. Non-increasing or duplicate D-id is ERROR.

## status Values

- `proposed` — drafted, awaiting attended ratification.
- `accepted` — ratified by a human via `arcforge ratify`.
- `superseded-by:D-NNN` — superseded by a newer entry (open-ended string form).

## Enforcement Authority

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