infospace-bench/docs/legacy-infospace-migration-guide.md

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

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.