# Legacy Infospace Migration Guide

Date: 2026-05-14

## Purpose

Use this guide when moving an in-scope legacy MarkiTect infospace into
`infospace-bench`.

The successor split is intentionally orthogonal:

- `markitect-tool`: markdown parsing, section extraction, contracts, templates.
- `infospace-bench`: concrete infospace layout, manifests, semantic entity and
  relation models, checks, viability, evaluation history, pilots, and reports.
- `kontextual-engine`: durable assets, relationship indexes, retrieval,
  workflow runtime, permissions, and audit when file-backed operation is no
  longer enough.

## Migration Path

1. Create a successor workspace with `infospace-bench create`.
2. Copy source material into `artifacts/sources/`.
3. Register each source in `artifacts/index.yaml` with a stable artifact ID.
4. Move only in-scope generated entities and relations into
   `artifacts/entities/` and `artifacts/relations/`.
5. Add markdown contracts under `contracts/` when validation is needed, then
   point `infospace.yaml` `schemas` at those contracts.
6. Convert legacy entity evaluation files to use `artifact_id` rather than
   entity-only slugs.
7. Move metrics snapshots into `output/metrics/history.yaml` and current values
   into `output/metrics/metrics.yaml`.
8. Express generation or review work as explicit workflow declarations in
   `infospace.yaml`.
9. Use `infospace-bench engine plan-sync` to check the optional engine asset
   boundary before applying any durable sync.
10. Write a migration report under `reports/` that names replaced, delegated,
    deferred, and retired behavior.

## Verification Commands

```bash
infospace-bench status <root>
infospace-bench validate <root>
infospace-bench entities <root>
infospace-bench relations <root>
infospace-bench check <root>
infospace-bench viability <root>
infospace-bench history <root>
infospace-bench graph <root> --format mermaid
infospace-bench engine plan-sync <root>
```

## What Moves Where

| Legacy concern | Successor home | Migration note |
| --- | --- | --- |
| Markdown headings, frontmatter, contract checks | `markitect-tool` | Keep access through `infospace_bench.markdown_adapter`. |
| Entity and relation semantics | `infospace-bench` | Keep domain concepts in file-backed artifacts and manifests. |
| Evaluation files and metrics history | `infospace-bench` | Preserve history with `artifact_id` and deterministic metrics. |
| LLM prompt execution | `infospace-bench` workflow boundary plus adapters | Plans must be dry-runnable; provider calls require explicit adapters. |
| Durable asset identity and graph indexes | `kontextual-engine` | Use `engine plan-sync` and `engine sync --apply` when needed. |
| Retrieval, permissions, audit | `kontextual-engine` | Do not recreate these inside `infospace-bench`. |

## Non-Goals

- Migrating every legacy generated file just because it exists.
- Preserving legacy output directory names when manifest IDs are clearer.
- Rebuilding provider-specific LLM wiring inside `infospace-bench`.
- Recreating prompt/runtime infrastructure that belongs to `kontextual-engine`.
- Treating `infospace-bench` as a markdown parser library.

## Pilot Pattern

The `infospaces/wealth-vsm-legacy-slice/` pilot is the reference pattern for a
small legacy migration. It keeps a pruned source excerpt, two entities, one
relation, one migrated evaluation, metrics/history fixtures, validation
contracts, and a report that explains what was intentionally left behind.