cc-os/openspec/specs/adr-migration/spec.md

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