coulomb/infospace-bench
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs and stuff

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-14 13:47:36 +02:00
parent 577ee32841
commit 28de86f13e
6 changed files with 346 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
README.md
View File

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

88
docs/legacy-infospace-feature-inventory.md Normal file
View File

@@ -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.

6
docs/orthogonal-successor-roadmap.md
View File

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

96
docs/replacement-acceptance-matrix.md Normal file
View File

@@ -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/<slug>/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.

148
docs/successor-boundary-interface-map.md Normal file
View File

@@ -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/<slug>/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.

10
workplans/IB-WP-0005-orthogonal-successor-architecture.md
View File

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