generated from coulomb/repo-seed
79 lines
3.4 KiB
Markdown
79 lines
3.4 KiB
Markdown
# 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.
|
|
|