From 28de86f13ef416d936ced95f420c63a335d6774c Mon Sep 17 00:00:00 2001 From: tegwick Date: Thu, 14 May 2026 13:47:36 +0200 Subject: [PATCH] docs and stuff --- README.md | 3 + docs/legacy-infospace-feature-inventory.md | 88 +++++++++++ docs/orthogonal-successor-roadmap.md | 6 + docs/replacement-acceptance-matrix.md | 96 ++++++++++++ docs/successor-boundary-interface-map.md | 148 ++++++++++++++++++ ...-0005-orthogonal-successor-architecture.md | 10 +- 6 files changed, 346 insertions(+), 5 deletions(-) create mode 100644 docs/legacy-infospace-feature-inventory.md create mode 100644 docs/replacement-acceptance-matrix.md create mode 100644 docs/successor-boundary-interface-map.md diff --git a/README.md b/README.md index 9f0dfcb..1fb861c 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,9 @@ Start with: - `docs/reference-pilot-decision.md` - `docs/markitect-main-scope-assessment.md` - `docs/orthogonal-successor-roadmap.md` +- `docs/legacy-infospace-feature-inventory.md` +- `docs/successor-boundary-interface-map.md` +- `docs/replacement-acceptance-matrix.md` - `infospaces/bootstrap-pilot/` - `workplans/` diff --git a/docs/legacy-infospace-feature-inventory.md b/docs/legacy-infospace-feature-inventory.md new file mode 100644 index 0000000..730690a --- /dev/null +++ b/docs/legacy-infospace-feature-inventory.md @@ -0,0 +1,88 @@ +# Legacy Infospace Feature Inventory + +Date: 2026-05-14 + +## Purpose + +This inventory records the in-scope infospace functionality from the original +`markitect-project` / `markitect-main` and assigns each feature to its successor +home across the three orthogonal repos: + +- `markitect-tool`: Markdown syntax and structured document primitives +- `kontextual-engine`: durable knowledge operations engine +- `infospace-bench`: concrete applied infospaces and evaluation methodology + +## Classification Values + +- **migrate**: bring the behavior into `infospace-bench` as application logic +- **delegate**: consume the behavior from `markitect-tool` or + `kontextual-engine` +- **reimplement**: rebuild the behavior with cleaner boundaries +- **defer**: keep out of the first replacement pass +- **retire**: do not preserve as a successor feature + +## Module Inventory + +| Legacy area | Main behavior | Classification | Successor home | Notes | +| --- | --- | --- | --- | --- | +| `markitect/infospace/config.py` | `infospace.yaml`, topic, disciplines, schemas, viability, pipeline dirs | migrate | `infospace-bench` | Application project model. Keep syntax simple and file-backed first. | +| `markitect/infospace/entity_parser.py` | Parse entity Markdown into entity metadata | reimplement + delegate | `infospace-bench` + `markitect-tool` | Bench owns entity semantics; tool owns Markdown parsing. | +| `markitect/infospace/relation_parser.py` | Parse relation triplet Markdown | reimplement + delegate | `infospace-bench` + `markitect-tool` | Same split as entities. | +| `markitect/infospace/schema.py` | Entity schema shape | delegate + migrate configs | `markitect-tool` + `infospace-bench` | Generic validation belongs in tool; selected schemas/contracts belong in bench pilots. | +| `markitect/infospace/validator.py` | Entity compliance diagnostics | reimplement + delegate | `infospace-bench` + `markitect-tool` | Tool emits diagnostics; bench maps them to infospace artifacts. | +| `markitect/infospace/evaluation.py` | Score/evaluation/snapshot/diff models | migrate | `infospace-bench` | Already started in baseline. | +| `markitect/infospace/evaluation_io.py` | Read/write evaluations, snapshots, history | migrate | `infospace-bench` | Next parity step. | +| `markitect/infospace/evaluate.py` | LLM evaluation prompts and batch execution | reimplement | `infospace-bench` + provider adapter | Bench owns evaluation contract; provider calls stay optional and auditable. | +| `markitect/infospace/checks/*` | Redundancy, coverage, coherence, consistency, granularity | reimplement | `infospace-bench` | Bench owns methodology; can use tool/engine data. | +| `markitect/infospace/history.py` | Metrics file, history snapshots, trends | migrate | `infospace-bench` | File-backed first, engine-backed later. | +| `markitect/infospace/state.py` | Computed infospace state and viability | migrate | `infospace-bench` | Application-level state summary. | +| `markitect/infospace/composition.py` | Bind one infospace as a discipline/lens | migrate | `infospace-bench` | Concrete infospace composition. | +| `markitect/infospace/classification*` | Entity typing, VSM system labels, classification summaries | reimplement | `infospace-bench` | Application semantics, especially for reference pilots. | +| `markitect/infospace/relation_models.py` | Relation metadata model | migrate | `infospace-bench` | Application graph semantics. | +| `markitect/infospace/graph_export.py` | Entity/relation graph, Mermaid/DOT exports, filters | reimplement | `infospace-bench` | Bench owns semantic graph; output can remain file-backed. | +| `markitect/infospace/pipeline.py` | Source-to-output processing stages and follow-ups | reimplement + delegate | all three | Bench defines workflows, tool transforms Markdown, engine eventually orchestrates/persists runs. | +| `examples/infospace-with-history` | Wealth of Nations/VSM reference experiment | migrate pruned slice | `infospace-bench` | Full generated bulk is deferred; representative fixture comes first. | + +## Legacy CLI Inventory + +| Legacy command | Behavior | Classification | Target replacement | +| --- | --- | --- | --- | +| `infospace init` | Create a config file | migrate | `infospace-bench create` plus richer template support | +| `infospace status` | Summarize config, entities, domains, evaluations | reimplement | `infospace-bench inspect/status` | +| `infospace entities` | List parsed entities | reimplement | `IB-WP-0007` entity listing | +| `infospace chapters` | Source/chapter triage | reimplement | `IB-WP-0009` workflow/source status | +| `infospace evaluate` | Run per-entity LLM evaluation | reimplement | `IB-WP-0008`/`IB-WP-0009` evaluation workflow | +| `infospace eval-summary` | Summarize evaluation scores | reimplement | `IB-WP-0008` metrics/evaluation report | +| `infospace relations` | List and filter relations | reimplement | `IB-WP-0007` relation listing | +| `infospace classify` | Classify entities | reimplement | `IB-WP-0007`/later classifier workflow | +| `infospace classify-summary` | Summarize classifications | reimplement | `IB-WP-0007`/`IB-WP-0008` reports | +| `infospace classify-links` | Assisted relation/classification linking | defer | Keep until entity/relation parity exists | +| `infospace viability` | Check metrics against thresholds | migrate | Already started; expand in `IB-WP-0008` | +| `infospace check` | Run collection checks | reimplement | Already started; expand in `IB-WP-0008` | +| `infospace history` | Show metric history/trends | migrate | `IB-WP-0008` | +| `infospace history-diff` | Diff snapshots | migrate | `IB-WP-0008` | +| `infospace bind-discipline` | Bind reusable discipline infospace | migrate | `IB-WP-0007`/composition follow-up | +| `infospace process` | Run source processing pipeline | reimplement + delegate | `IB-WP-0009` | +| `infospace stale-mappings` | Identify stale generated mappings | defer | After workflow provenance and digests exist | +| `infospace graph` | Export filtered semantic graph | reimplement | `IB-WP-0007`/`IB-WP-0008` | + +## Example And Output Inventory + +| Legacy artifact | Classification | Target | +| --- | --- | --- | +| `examples/infospace-with-history/infospace.yaml` | migrate pruned | `IB-WP-0011` | +| Source chapter Markdown files | migrate pruned | `IB-WP-0011` | +| Entity, relation, mapping, analysis schemas | delegate + migrate fixtures | `IB-WP-0006`, `IB-WP-0011` | +| Prompt templates | reimplement | `IB-WP-0009` | +| Generated analyses/entities/classifications | migrate minimal fixtures | `IB-WP-0011` | +| Processing logs | reimplement | `IB-WP-0009` | +| Metrics history | migrate minimal fixtures | `IB-WP-0008`, `IB-WP-0011` | +| Tutorial/methodology docs | migrate selectively | `IB-WP-0011`, `IB-WP-0012` | + +## Retired Or Explicitly Not First-Pass + +- Legacy imports of `markitect.core.*` inside infospace modules. +- Direct provider-specific LLM wiring inside application code. +- Bulk generated output from the large reference experiment. +- Any database-backed lifecycle behavior that belongs in `kontextual-engine`. +- Rendering/plugin/asset subsystems unrelated to infospace evaluation. diff --git a/docs/orthogonal-successor-roadmap.md b/docs/orthogonal-successor-roadmap.md index 01aeb27..4efd59a 100644 --- a/docs/orthogonal-successor-roadmap.md +++ b/docs/orthogonal-successor-roadmap.md @@ -60,6 +60,12 @@ The following `infospace-bench` workplans establish the path: 7. `IB-WP-0011` — Pruned legacy reference pilot migration 8. `IB-WP-0012` — Replacement readiness and CLI parity gate +Supporting architecture artifacts: + +- `docs/legacy-infospace-feature-inventory.md` +- `docs/successor-boundary-interface-map.md` +- `docs/replacement-acceptance-matrix.md` + ## Sequencing ```text diff --git a/docs/replacement-acceptance-matrix.md b/docs/replacement-acceptance-matrix.md new file mode 100644 index 0000000..2e5980d --- /dev/null +++ b/docs/replacement-acceptance-matrix.md @@ -0,0 +1,96 @@ +# Replacement Acceptance Matrix + +Date: 2026-05-14 + +## Purpose + +This matrix defines what evidence is required before `infospace-bench` can be +considered a replacement for each in-scope legacy infospace behavior from +`markitect-project`. + +## Matrix + +| Legacy behavior | Successor behavior | Evidence required | Workplan | Status | +| --- | --- | --- | --- | --- | +| Create an infospace config | File-backed `infospaces//infospace.yaml` and manifest | Lifecycle tests, CLI create/inspect docs | `IB-WP-0002` | baseline done | +| Load and inspect an infospace | Structured config/artifact model and JSON CLI | Tests for load, missing config, structured errors | `IB-WP-0002` | baseline done | +| Add/list artifacts | Manifest-backed artifact registration | Tests for add, duplicate rejection, inspect output | `IB-WP-0002` | baseline done | +| Parse entity Markdown | Entity parser built on `markitect-tool` document sections | Entity fixture tests, diagnostics for missing sections | `IB-WP-0006`, `IB-WP-0007` | planned | +| Validate entity/relation shape | Contract/schema validation through `markitect-tool` | Valid/invalid fixture tests, diagnostic mapping | `IB-WP-0006`, `IB-WP-0007` | planned | +| List entities | Entity listing from parsed artifact model | CLI/API example and fixture tests | `IB-WP-0007` | planned | +| Parse and list relations | Relation triplet model and endpoint checks | Relation fixture tests, graph edge tests | `IB-WP-0007` | planned | +| Export semantic graph | Infospace graph model with Mermaid/DOT output | Graph output tests and pilot report | `IB-WP-0007`, `IB-WP-0008` | partial baseline | +| Run collection checks | Methodology-owned metrics in `infospace-bench` | Deterministic metric tests and fixture output | `IB-WP-0008` | partial baseline | +| Check viability | Threshold report from metrics | Viability tests and CLI/report output | `IB-WP-0008` | partial baseline | +| Write evaluation results | Evaluation files with structured metadata | Round-trip tests and pilot fixture | `IB-WP-0008` | planned | +| Maintain metrics history | Snapshot history append/read/diff | History and history-diff tests | `IB-WP-0008` | planned | +| Evaluate with LLM assistance | Provider-neutral assisted evaluation workflow | Dry-run plan, adapter contract, audited output | `IB-WP-0009` | planned | +| Process source chapters | Explicit infospace workflow stages | Deterministic runner tests, generated artifact provenance | `IB-WP-0009` | planned | +| 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` | planned | +| Run a legacy-derived pilot | Pruned `infospace-with-history` migration | Pilot corpus, migration report, parity comparison | `IB-WP-0011` | planned | +| Provide command migration path | Legacy command parity guide | Command table and examples | `IB-WP-0012` | planned | + +## Replacement Gates + +### Gate A: Syntax Delegation + +Passes when all Markdown parsing and validation in `infospace-bench` goes +through the `markitect-tool` adapter. + +Required workplans: + +- `IB-WP-0006` + +### Gate B: Application Semantics + +Passes when entities, relations, metrics, viability, evaluation history, and +graphs work over real fixtures. + +Required workplans: + +- `IB-WP-0007` +- `IB-WP-0008` + +### Gate C: Workflow Parity + +Passes when deterministic source-to-output workflows replace the old `process` +command shape and assisted stages are explicit, dry-runnable, and auditable. + +Required workplans: + +- `IB-WP-0009` + +### Gate D: Engine Boundary + +Passes when file-backed operation remains the default and `kontextual-engine` +integration is available through an explicit adapter contract. + +Required workplans: + +- `IB-WP-0010` + +### Gate E: Legacy Pilot Proof + +Passes when a pruned legacy pilot demonstrates the successor stack on migrated +content. + +Required workplans: + +- `IB-WP-0011` +- `IB-WP-0012` + +## Non-Goals + +- Full CLI name-for-name compatibility with legacy `markitect infospace`. +- Moving low-level Markdown parser code into `infospace-bench`. +- Recreating legacy prompt/provider code directly. +- Committing the full generated Wealth of Nations/VSM output tree as the first + pilot. +- Building a database or workflow engine inside `infospace-bench`. + +## 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. diff --git a/docs/successor-boundary-interface-map.md b/docs/successor-boundary-interface-map.md new file mode 100644 index 0000000..90e804e --- /dev/null +++ b/docs/successor-boundary-interface-map.md @@ -0,0 +1,148 @@ +# Successor Boundary And Interface Map + +Date: 2026-05-14 + +## Purpose + +This document defines the operational boundary between `infospace-bench`, +`markitect-tool`, and `kontextual-engine` for the infospace successor effort. + +## Direction Of Dependency + +```text +infospace-bench + uses markitect-tool for Markdown syntax capabilities + optionally uses kontextual-engine for durable operational state + +markitect-tool + does not depend on infospace-bench + does not depend on kontextual-engine for core syntax behavior + +kontextual-engine + may call syntax adapters such as markitect-tool for Markdown ingestion + does not depend on infospace-bench for engine identity +``` + +## What `infospace-bench` Expects From `markitect-tool` + +`infospace-bench` should consume a narrow adapter over `markitect-tool`. + +Required capabilities: + +- Parse Markdown files into structured document objects. +- Expose headings, sections, frontmatter, source locations, and blocks. +- Validate Markdown files against schemas/contracts. +- Return structured diagnostics with source locations. +- Resolve references and deterministic transformations where workflows need + Markdown-native composition. +- Provide stable CLI/library behavior that can be used in tests and agents. + +`infospace-bench` should not: + +- Reimplement Markdown tokenization or section-tree parsing. +- Re-export the entire `markitect-tool` API. +- Add infospace-specific concepts to `markitect-tool`. + +## What `infospace-bench` Expects From `kontextual-engine` + +`kontextual-engine` is optional at first. File-backed behavior remains the +default until engine integration is explicitly implemented. + +Expected future capabilities: + +- Durable asset identity for source and generated artifacts. +- Metadata and provenance storage. +- Relationship storage and retrieval. +- Search, filtering, and query access over knowledge assets. +- Workflow run records and operational audit trails. +- Permission and review gates for agent-safe operations. +- Transform records that link inputs, configuration, actor, and outputs. + +`infospace-bench` should not: + +- Become a persistence engine. +- Build its own general retrieval platform. +- Own generic permissions, audit, or workflow orchestration primitives. + +## What Remains File-Backed In `infospace-bench` + +File-backed behavior is part of the application contract and should remain +first-class: + +- `infospaces//infospace.yaml` +- `artifacts/index.yaml` +- source and generated artifact fixtures +- evaluation files +- metrics and history files +- inspection reports +- exports +- reference pilot corpora + +The file-backed implementation is the testable baseline. Engine-backed +operation should behave like a durable backend for the same application model, +not a replacement for inspectable project artifacts. + +## Adapter Boundaries + +### Markdown Adapter + +Planned module: + +```text +src/infospace_bench/markdown_adapter.py +``` + +Responsibilities: + +- call `markitect_tool.parse_markdown_file` +- extract named sections by heading +- call `markitect_tool` validation APIs +- normalize diagnostics into `infospace-bench` result/error objects + +### Repository Adapter + +Planned module: + +```text +src/infospace_bench/repository.py +``` + +Responsibilities: + +- provide local file-backed artifact reads/writes +- later provide `kontextual-engine` backed asset lookup/sync +- expose dry-run sync plans before mutation +- keep provenance and digest handling explicit + +### Workflow Adapter + +Planned module: + +```text +src/infospace_bench/workflow.py +``` + +Responsibilities: + +- load workflow definitions from `infospace.yaml` +- run deterministic file-backed stages +- delegate Markdown operations to `markitect-tool` +- define assisted-stage contracts without binding to a provider +- later submit or mirror workflow runs to `kontextual-engine` + +## Cross-Repo Non-Goals + +- `markitect-tool` should not learn about concrete infospaces. +- `kontextual-engine` should not become a Markdown-specific runtime. +- `infospace-bench` should not become a general platform or engine. +- No repo should reproduce the old `markitect-project` monolith by accretion. + +## First Integration Slice + +The first implementation slice after this architecture workplan is +`IB-WP-0006`: + +1. Add `markitect-tool` as a local dependency. +2. Add a narrow Markdown adapter. +3. Validate real infospace artifacts through `markitect-tool`. +4. Keep all tests deterministic and file-backed. diff --git a/workplans/IB-WP-0005-orthogonal-successor-architecture.md b/workplans/IB-WP-0005-orthogonal-successor-architecture.md index 21b200a..6ace80a 100644 --- a/workplans/IB-WP-0005-orthogonal-successor-architecture.md +++ b/workplans/IB-WP-0005-orthogonal-successor-architecture.md @@ -4,7 +4,7 @@ type: workplan title: "Orthogonal Successor Architecture" domain: markitect repo: infospace-bench -status: planned +status: done owner: markitect topic_slug: markitect created: "2026-05-14" @@ -39,7 +39,7 @@ those boundaries. ```task id: IB-WP-0005-T01 -status: in_progress +status: done priority: high state_hub_task_id: "10b456fa-fc07-43cc-8a83-7382cfab57a9" ``` @@ -52,7 +52,7 @@ state_hub_task_id: "10b456fa-fc07-43cc-8a83-7382cfab57a9" ```task id: IB-WP-0005-T02 -status: todo +status: done priority: high state_hub_task_id: "f5a57259-97a1-4690-b448-c1d15668a1b9" ``` @@ -65,7 +65,7 @@ state_hub_task_id: "f5a57259-97a1-4690-b448-c1d15668a1b9" ```task id: IB-WP-0005-T03 -status: todo +status: done priority: high state_hub_task_id: "0a4f35b4-377a-421d-8d6e-80dee467e1aa" ``` @@ -78,7 +78,7 @@ state_hub_task_id: "0a4f35b4-377a-421d-8d6e-80dee467e1aa" ```task id: IB-WP-0005-T04 -status: todo +status: done priority: medium state_hub_task_id: "5e9f9889-b50c-4353-986f-c5b473fa9fc5" ```