command parity and migration guide

docs/legacy-command-parity.md

@@ -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
+```
+