# Spec: ADR Migration

## Purpose

Defines how existing ADR-like content in a project is migrated into the standard `os-adr` format: mechanical shape detection with a safe fallback, a strict mechanical/LLM field-mapping boundary, a single uncertainty-flagging mechanism, non-destructive dual-existence conversion, and a pilot gate before broad rollout.

## Requirements

### Requirement: Shape detection with a fallback
The migration tooling SHALL mechanically detect existing ADR-like content and classify it into
the surveyed shapes — numbered per-file directories, dated single files, monolithic
multi-decision files, prose embedded in other docs — plus an `unrecognized` fallback
classification. Unrecognized content SHALL be reported for manual handling, never auto-converted.

#### Scenario: Known shape detected
- **WHEN** detection runs on a project with a monolithic multi-decision file
- **THEN** the file is classified as monolithic and its individual decisions are enumerated as
  migration units

#### Scenario: Unknown shape falls back safely
- **WHEN** detection encounters ADR-like content matching no known shape
- **THEN** it is classified `unrecognized` and listed in the report without any conversion
  attempt

### Requirement: Mechanical/LLM field-mapping boundary
During conversion, fields that are structurally unambiguous in the source (Status and Date from
frontmatter or clear headings; title; ID assignment; source provenance) SHALL be filled
mechanically. Only interpretive fields (Consequences, Alternatives rejected, monolithic-file
decision splitting) MAY be LLM-filled, and every LLM-filled field SHALL be flagged. The
migration SHALL never invent a Decision or Context field absent from the source — such fields
SHALL carry an explicit not-stated-in-source marker and lower the file's confidence.

#### Scenario: Unambiguous field filled mechanically
- **WHEN** a source ADR has a `Status: Accepted` heading and a date
- **THEN** the converted file's `status` and `date` are set without any LLM call

#### Scenario: Missing core field is not invented
- **WHEN** a source decision has no discernible Context
- **THEN** the converted Context section contains a not-stated-in-source marker and the file is
  flagged low-confidence

### Requirement: Single uncertainty-flagging mechanism
Migration uncertainty SHALL be surfaced through exactly one mechanism: a
`migration_confidence: low|medium|high` frontmatter field per converted file, plus one
migration report file (`docs/adr/migration-report.md`) summarizing per-file confidence, the
source-to-new mapping, and the overall low-confidence flag rate. Scattered inline uncertainty
comments SHALL NOT be used.

#### Scenario: Report aggregates confidence
- **WHEN** a migration completes
- **THEN** the report lists every converted file with its confidence, its source location, and
  the overall flag rate

### Requirement: Non-destructive, dual-existence conversion
Migration SHALL only write new files under `docs/adr/`; existing ADR content SHALL never be
deleted, moved, or edited by the migration. Removal of the old system SHALL happen only as an
explicit, separate, user-approved step offered after the migration report exists.

#### Scenario: Old system untouched
- **WHEN** a migration run completes
- **THEN** every pre-existing ADR source file is byte-identical to its pre-migration state

#### Scenario: Deletion requires explicit approval
- **WHEN** the user has not explicitly approved old-system removal
- **THEN** no tooling path deletes the old content, and the removal offer appears only after the
  report is available for review

### Requirement: Pilot gate before broad rollout
The migration SHALL be piloted on 2–3 real surveyed projects, and the low-confidence flag rate
SHALL be measured against an explicit threshold recorded at pilot time before the heuristics are
treated as good enough for wider rollout.

#### Scenario: High flag rate blocks rollout
- **WHEN** a pilot run's low-confidence rate exceeds the recorded threshold
- **THEN** the heuristics are tightened and the pilot re-run before migrating further projects