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

# _pending-conflict.md Schema

Canonical path: `specs/<spec-id>/_pending-conflict.md`

The underscore prefix marks the file as ephemeral hand-off, not versioned spec content.
The file MUST NOT live under `details/` or any path that would be parsed as a spec detail file.

## Lifecycle

**State**: ephemeral — non-versioned, non-authoritative.

- **Written by**: refiner on R3 axis-1/2/3 block (fr-rf-015).
- **Read by**: brainstorming Phase 0 iterate-branch auto-entry (fr-bs-008).
- **Deleted by**: brainstorming on successful new-design write.

Per A.1's narrowed Iron Law, this is the explicit ephemeral exception to "no
authoritative state on block". Validators MUST treat persistence across a completed
conflict cycle as ERROR: `"a prior conflict cycle did not complete cleanly"`.

## Required Fields

All four fields MUST be present. Missing any one field is an ERROR.

| Field | Type | Description |
|---|---|---|
| `axis_fired` | enum (`"1"`, `"2"`, `"3"`) | Which contradiction axis fired (1, 2, or 3 per fr-rf-015 / A.2). |
| `conflict_description` | string | Specific design line ranges and Q&A row q_ids involved in the contradiction. Must cite exact sources so brainstorming Phase 0 can mechanically address them. |
| `candidate_resolutions` | list, length 1–3 | 1-3 candidate resolutions, each phrased as a concrete action the user can pick. Zero resolutions is an ERROR: "_pending-conflict.md MUST contain at least one candidate resolution". |
| `user_action_prompt` | string | Directs the user to run /arc-brainstorming iterate <spec-id> to resolve the conflict. Must be present so the user knows how to proceed after reading the conflict file. |

## Examples

### Valid example

Axis 1 fired, two candidate resolutions are present, and the user-action prompt tells the user exactly what to choose.

```yaml
axis_fired: "1"
conflict_description: "REQ-A says export is CSV-only, but the new design asks for JSON as the default."
candidate_resolutions:
  - "Keep CSV-only and reject JSON default."
  - "Change REQ-A to allow JSON default and record the compatibility impact."
user_action_prompt: "Choose one candidate resolution, or provide a new explicit requirement."
```

### Invalid example

No candidate resolutions are present. Error: "_pending-conflict.md MUST contain at least one candidate resolution".

```yaml
axis_fired: "1"
conflict_description: "Existing spec and new design disagree about the export format."
candidate_resolutions: []
user_action_prompt: "Please resolve the conflict."
```

## Enforcement Authority

`scripts/lib/sdd-rules.js` — `PENDING_CONFLICT_RULES` is the canonical source of truth
(re-exported via `scripts/lib/sdd-utils.js` for facade access). Validators built in
`fr-sd-014` read from that constant. If this document disagrees with the constant,
the constant wins and this document is wrong (file a bug).
