generated from coulomb/repo-seed
command parity and migration guide
This commit is contained in:
89
docs/legacy-command-parity.md
Normal file
89
docs/legacy-command-parity.md
Normal file
@@ -0,0 +1,89 @@
|
||||
# Legacy Command Parity
|
||||
|
||||
Date: 2026-05-14
|
||||
|
||||
## Purpose
|
||||
|
||||
This guide maps the legacy `markitect infospace` command surface to the
|
||||
successor shape in `infospace-bench`, `markitect-tool`, and
|
||||
`kontextual-engine`.
|
||||
|
||||
The goal is replacement readiness for in-scope infospace work, not a
|
||||
name-for-name CLI clone. `infospace-bench` keeps concrete infospaces,
|
||||
application semantics, evaluation history, and file-backed workflow fixtures.
|
||||
`markitect-tool` owns markdown parsing and validation primitives.
|
||||
`kontextual-engine` owns durable asset, graph, retrieval, audit, and workflow
|
||||
runtime concerns when those move beyond file-backed operation.
|
||||
|
||||
## Status Values
|
||||
|
||||
- `replaced`: use the successor command directly.
|
||||
- `reframed`: the behavior exists, but the user flow has a cleaner successor
|
||||
shape.
|
||||
- `delegated`: the behavior belongs in a sibling repo and is consumed through
|
||||
an adapter or contract.
|
||||
- `deferred`: still in scope, but not required for the current replacement
|
||||
gate.
|
||||
- `retired`: the legacy behavior should not be rebuilt.
|
||||
|
||||
## Command Map
|
||||
|
||||
| Legacy command | Status | Successor command or API | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| `markitect infospace init` | replaced | `infospace-bench create <workspace> <slug> --name "<name>" --topic-domain "<domain>"` | Creates the file-backed `infospaces/<slug>/` layout and manifest. |
|
||||
| `markitect infospace status` | replaced | `infospace-bench status <root>` | JSON summary of config, artifact counts, parsed entities/relations, metrics, viability, history, and graph counts. |
|
||||
| `markitect infospace entities` | replaced | `infospace-bench entities <root>` or `infospace_bench.semantics.list_entities(root)` | Entity semantics are bench-owned and markdown parsing is delegated to `markitect-tool`. |
|
||||
| `markitect infospace chapters` | reframed | `infospace-bench export <root>` plus workflow/source artifact inspection | The successor tracks sources as manifest artifacts instead of a chapter-only table. A richer source triage command is deferred. |
|
||||
| `markitect infospace evaluate` | reframed | `infospace-bench workflow plan <root> <workflow_id>` and explicit assisted adapters | Provider-specific LLM calls are no longer hidden in the app CLI. Assisted stages are auditable and require an explicit adapter. |
|
||||
| `markitect infospace eval-summary` | reframed | `infospace-bench history <root> --metric per_artifact_mean` and `infospace-bench status <root>` | Evaluation results are structured artifacts plus metrics history, not a one-off text table. |
|
||||
| `markitect infospace relations` | replaced | `infospace-bench relations <root>` | Relation triplets resolve endpoints against parsed entity artifacts. |
|
||||
| `markitect infospace classify` | deferred | `infospace-bench workflow plan/run <root> <classification_workflow>` | Classification remains in scope as an explicit workflow, but provider execution is not part of this readiness gate. |
|
||||
| `markitect infospace viability` | replaced | `infospace-bench viability <root>` | Evaluates configured thresholds from persisted metrics. |
|
||||
| `markitect infospace check` | replaced | `infospace-bench check <root>` | Runs deterministic collection checks, persists metrics, appends history, and writes viability output. |
|
||||
| `markitect infospace history` | replaced | `infospace-bench history <root>` or `infospace-bench history <root> --metric <name>` | Reads file-backed metric snapshots. |
|
||||
| `markitect infospace history-diff` | replaced | `infospace-bench history-diff <root> <before> <after>` | Diffs snapshots by ID or date reference. |
|
||||
| `markitect infospace bind-discipline` | deferred | Edit `infospace.yaml` `disciplines` or add a later composition command | The config model supports discipline bindings; operational composition checks are a follow-up in `infospace-bench`. |
|
||||
| `markitect infospace process` | reframed | `infospace-bench workflow inspect|plan|run <root> <workflow_id>` | Workflows are explicit declarations with deterministic template stages and auditable assisted stages. |
|
||||
| `markitect infospace stale-mappings` | deferred | Future workflow/engine provenance comparison | Digest and provenance data now exist; stale mapping policy needs a dedicated follow-up. |
|
||||
| `markitect infospace graph` | replaced | `infospace-bench graph <root> --format json` or `--format mermaid` | Exports the artifact relationship graph from manifest relationships. |
|
||||
|
||||
## Retired Legacy Shapes
|
||||
|
||||
- Direct provider-specific LLM execution hidden behind a generic app command.
|
||||
- Automatic git commits from infospace processing commands.
|
||||
- Legacy output-directory conventions that bypass the artifact manifest.
|
||||
- Parser and schema code duplicated inside the application repo.
|
||||
|
||||
## Replacement Examples
|
||||
|
||||
Create and inspect an infospace:
|
||||
|
||||
```bash
|
||||
infospace-bench create . wealth-vsm --name "Wealth through VSM" --topic-domain "Classical Economics"
|
||||
infospace-bench status infospaces/wealth-vsm
|
||||
```
|
||||
|
||||
Validate, check, and view viability:
|
||||
|
||||
```bash
|
||||
infospace-bench validate infospaces/wealth-vsm-legacy-slice
|
||||
infospace-bench check infospaces/wealth-vsm-legacy-slice
|
||||
infospace-bench viability infospaces/wealth-vsm-legacy-slice
|
||||
```
|
||||
|
||||
Inspect semantic artifacts and graph:
|
||||
|
||||
```bash
|
||||
infospace-bench entities infospaces/wealth-vsm-legacy-slice
|
||||
infospace-bench relations infospaces/wealth-vsm-legacy-slice
|
||||
infospace-bench graph infospaces/wealth-vsm-legacy-slice --format mermaid
|
||||
```
|
||||
|
||||
Run explicit workflows:
|
||||
|
||||
```bash
|
||||
infospace-bench workflow inspect infospaces/bootstrap-pilot
|
||||
infospace-bench workflow plan infospaces/bootstrap-pilot bootstrap-readiness
|
||||
infospace-bench workflow run infospaces/bootstrap-pilot bootstrap-readiness
|
||||
```
|
||||
|
||||
78
docs/legacy-infospace-migration-guide.md
Normal file
78
docs/legacy-infospace-migration-guide.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# 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.
|
||||
|
||||
@@ -29,7 +29,7 @@ considered a replacement for each in-scope legacy infospace behavior from
|
||||
| Track stale outputs | Digest/provenance comparison | Tests after workflow provenance exists | `IB-WP-0009` | deferred |
|
||||
| Persist durable assets | Optional engine-backed repository adapter | Dry-run sync tests and integration design | `IB-WP-0010` | boundary done |
|
||||
| Run a legacy-derived pilot | Pruned `infospace-with-history` migration | Pilot corpus, migration report, parity comparison | `IB-WP-0011` | done |
|
||||
| Provide command migration path | Legacy command parity guide | Command table and examples | `IB-WP-0012` | planned |
|
||||
| Provide command migration path | Legacy command parity guide | Command table, examples, migration guide, decision record, acceptance tests | `IB-WP-0012` | done |
|
||||
|
||||
## Replacement Gates
|
||||
|
||||
@@ -91,6 +91,7 @@ Required workplans:
|
||||
|
||||
## Readiness Statement
|
||||
|
||||
`infospace-bench` is a replacement candidate today, not a full replacement. It
|
||||
becomes replacement-ready only after the gates above produce committed tests,
|
||||
docs, pilots, and State Hub decisions.
|
||||
`infospace-bench` is replacement-ready for new in-scope infospace work. It is
|
||||
not a name-for-name clone of the old `markitect infospace` CLI; remaining gaps
|
||||
are explicitly owned by `infospace-bench`, `markitect-tool`, or
|
||||
`kontextual-engine` in `docs/replacement-readiness-decision.md`.
|
||||
|
||||
52
docs/replacement-readiness-decision.md
Normal file
52
docs/replacement-readiness-decision.md
Normal file
@@ -0,0 +1,52 @@
|
||||
---
|
||||
id: IB-DR-0012
|
||||
title: Replacement Readiness Decision
|
||||
date: "2026-05-14"
|
||||
decision: replacement-ready-for-new-in-scope-infospace-work
|
||||
status: accepted
|
||||
workplan: IB-WP-0012
|
||||
---
|
||||
|
||||
# Replacement Readiness Decision
|
||||
|
||||
## Decision
|
||||
|
||||
`infospace-bench` is replacement-ready for new in-scope infospace work that was
|
||||
previously attempted inside `markitect-project` / `markitect-main`.
|
||||
|
||||
Not a name-for-name CLI clone: replacement readiness means the successor stack
|
||||
has an evidence-backed migration path, tests, pilots, and explicit ownership for
|
||||
remaining gaps.
|
||||
|
||||
## Evidence
|
||||
|
||||
- Lifecycle, manifest, validation, entity/relation parsing, checks, viability,
|
||||
history, workflows, engine sync planning, and CLI behavior are covered by the
|
||||
test suite.
|
||||
- `infospaces/bootstrap-pilot/` proves the repo-native lifecycle and workflow
|
||||
baseline.
|
||||
- `infospaces/wealth-vsm-legacy-slice/` proves a pruned legacy migration from
|
||||
the old Wealth/VSM experiment.
|
||||
- `docs/legacy-command-parity.md` gives users a command and API migration path.
|
||||
- `docs/legacy-infospace-migration-guide.md` gives a repeatable migration
|
||||
process.
|
||||
|
||||
## Residual Gaps And Owners
|
||||
|
||||
| Gap | Owner | Decision |
|
||||
| --- | --- | --- |
|
||||
| Rich source/chapter triage view | `infospace-bench` | Deferred; use manifest export and workflows meanwhile. |
|
||||
| Classification workflow fixtures | `infospace-bench` | Deferred; implement as explicit workflows, not hidden provider calls. |
|
||||
| Discipline composition command | `infospace-bench` | Deferred; config support exists, operational checks need a focused follow-up. |
|
||||
| Stale mapping detection | `infospace-bench` + `kontextual-engine` | Deferred until provenance policy and durable asset comparison are settled. |
|
||||
| Durable graph/retrieval/runtime | `kontextual-engine` | Delegated by design. |
|
||||
| Markdown parser/schema engine | `markitect-tool` | Delegated by design. |
|
||||
|
||||
## Consequences
|
||||
|
||||
- New in-scope infospace work should start in `infospace-bench`.
|
||||
- Low-level markdown behavior should be added to `markitect-tool`.
|
||||
- Durable runtime concerns should be integrated through `kontextual-engine`
|
||||
boundaries rather than built into this repo.
|
||||
- Legacy bulk generated output should be migrated only when it has a current,
|
||||
scoped use and can be covered by tests.
|
||||
Reference in New Issue
Block a user