Feature request: specter migrate command for non-Specter spec dialects

[remyluslosius]

Pain

specter reverse extracts drafts from source code, which throws away hand-written spec content. For teams adopting Specter on a codebase that already has specs in a different YAML dialect, the only current path is a hand-rolled transform script. JWTMS had ~1,900 passing ACs, ~515 constraints, and ~470 changelog entries — valuable content that specter reverse would ignore.

Proposed

A specter migrate --from=<dialect> [--config=map.yaml] [--to=<target-dir>] command that takes YAML-to-YAML transforms declaratively:

# specter-migrate.yaml
source_dir: specs.legacy
output_dir: specs
field_map:
  spec.name: spec.title
  spec.status:
    Active: approved
    ACTIVE: approved
  constraints[].rule: spec.constraints[].description
  spec.changelog[].notes: spec.changelog[].description
  spec.source_files[0]: spec.generated_from.source_file
  spec.test_files: spec.generated_from.test_files
id_derivation: path # or "name"
tier_rules:
  - prefix: specs/app/api/payments/
    tier: 1
  - default: 2
normalize:
  - type: zero_pad_ids
    prefix: C
    min_width: 2
  - type: zero_pad_ids
    prefix: AC
    min_width: 2
  - type: wrap_string_as_object
    field: spec.acceptance_criteria[].inputs
    wrap_key: description

Built-in dialect presets (jwtms, gherkin, etc.) for common cases. Custom YAML paths for edge cases.

Why it belongs in Specter

Every team adopting Specter against an existing spec dialect hits the same three challenges: field renames, ID pattern normalization, and tier assignment. Right now each team solves it once with a bespoke script that nobody else benefits from. A config-driven specter migrate makes adoption linear-cost instead of per-team-reinvention.

What specter reverse can't cover

• status mapping (Active → approved) is project-specific, not derivable from code
• Tier assignment is policy, not code
• Changelog history lives only in existing specs, not in git
• Hand-written approval_gate / approval_date metadata
• Constraints with custom validation rules

Context

JWTMS migration: 249 specs, hand-rolled migration script ran once and was discarded. Pattern recurs for any project moving from pre-existing structured specs.

[remyluslosius]

Acknowledged. specter migrate for non-Specter spec dialects is a substantial feature and a strong candidate for v0.13 (after the v0.12 doctor / Python adoption / settings hardening landings). The JWTMS migration story (1,900 ACs / 515 constraints) is exactly the adoption case this would unlock. Triaging for the BACKLOG. The design will need:

1. A pluggable --from=<dialect> registry (Cucumber / Gherkin / hand-rolled YAML / etc.).
2. A map.yaml config for field mapping (their assertion → our acceptance_criteria).
3. Reuse of reverse's pattern-analysis for unmappable shapes.

Out of v0.12 scope (the v0.12 plan is already full with strictness exit-code refinement + Python adoption + M-tier security hardening). Will track in BACKLOG and revisit.