Design Markdown Import And Normalization Flow

Goal

Define how Forma inventories existing Markdown, proposes space and field mappings, and normalizes only approved files without obscuring source ownership.

Observed Baseline

forma init creates a minimal bootstrap and forma create creates one configured entry. Existing corpora require manual classification, metadata repair, reference normalization, and migration.

In Scope

• Inventory files, metadata shapes, link forms, collisions, and candidate space membership.
• Map source fields and paths to a guided workspace model with confidence and exceptions.
• Define dry-run, diff, apply, idempotency, interruption, and rollback boundaries.
• Preserve unsupported files and unknown fields unless the user chooses an explicit transformation.
• Separate generic Markdown normalization from product-specific third-party imports.

Out Of Scope

• Implementing import or normalization.
• Guaranteed compatibility with a specific knowledge application.
• Destructive bulk cleanup or silent body rewrites.
• Schema evolution after the initial mapping.

Acceptance Criteria

• The design covers discovery, mapping, conflict reporting, partial selection, apply, and verification.
• Re-running an accepted normalization plan is safe and explainable.
• Fixtures cover clean, inconsistent, ambiguous, localized, and partially unsupported corpora.
• The contract produces inputs for tasks/design-schema-evolution-migration-contract.