# External Artifact Import Bridge

Open Orchestra can import optional external workflow artifacts without making the
runtime depend on product-specific setup flows.

## Command Surface

This bridge should be exposed through a neutral import command before it becomes
part of public user documentation.

The expected machine-readable report includes imported, skipped, and conflicted
profiles, tasks, evidence references, and handoff references.

## Supported Inputs

The importer reads compatible profile, task, evidence, and handoff records from
the configured source directory. Task records may use either sparse legacy fields
or enriched delivery fields.

Supported task fields include:

- `id`, `title`, `summary`
- `owner`, `ownerRole`, `role`, `profile`, `profileId`
- `backlogItem`, `backlog`
- `userStory`, `goal`, `scope`
- `acceptanceCriteria`
- `definitionOfReady`, `definitionOfDone`
- `dependencies`, `dependsOn`
- `risks`, `assumptions`, `paths`, `files`
- `testStrategy`
- `contractVersion`
- `acceptanceStatus`, `acceptedBy`
- `evidenceIds`, `evidence`
- `handoffIds`, `handoffs`

## Mapping Rules

Profile role mappings are read from the external profile metadata when present.
External role IDs are normalized to Orchestra role IDs such as `qa`,
`developer`, `product_owner`, and `product_manager`. Unknown owner roles are
treated as conflicts during profile import and fall back to `developer` for
sparse task records.

Imported tasks preserve external metadata under an implementation-specific
external reference object. Evidence and handoff IDs are stored as references
there; the importer does not copy or mutate the original external artifacts.

## Idempotency And Conflicts

Re-running the import does not duplicate tasks. If an existing task has the
same ID, title, and owner role, the task is reported as skipped. If the ID
matches but title or owner differs, the importer reports a conflict and leaves
the existing Orchestra task unchanged.

Each import records an import event with summary counts so the
story-to-evidence trail remains auditable.