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

Add scope intent reconciliation workplan

Browse Source
This commit is contained in:
Bernd Worsch
2026-06-05 01:00:43 +02:00
parent 9e1d964f4b
commit 6018c4a2b3
2 changed files with 254 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
SCOPE.md
View File

@@ -7,45 +7,69 @@
## One-liner
Application-layer workspace and service for building, evaluating, inspecting,
and evolving concrete structured knowledge spaces.
File-backed application workspace and CLI for building, evaluating, inspecting,
generating, routing, budgeting, archiving, and iterating concrete structured
knowledge spaces.
---
## Core Idea
`infospace-bench` turns the infospace ideas that emerged in `markitect-main`
into a focused successor project. It should host real infospaces, their
configuration, evaluation runs, inspection outputs, workflow traces, and export
experiments.
into a focused successor project. It hosts real infospaces, their manifests,
profiles, workflow declarations, deterministic fixtures, generation runs,
inspection outputs, budget records, archive records, and pilot reports.
The repo is intentionally above the lower layers:
- `markitect-tool` owns markdown syntax and document transformation primitives.
- `kontextual-engine` owns persistence, orchestration, and runtime system
concerns.
- `markitect-tool` owns markdown syntax, structured markdown validation, and
reusable Markitect contracts.
- `kontextual-engine` owns durable persistence, orchestration, permissions,
retrieval, and runtime system concerns.
- `artifact-store` owns durable content-addressed package identity, storage,
retention, and archive backend concerns.
- `llm-connect` owns reusable provider routing primitives and quality-ledger
policy mechanics.
- `infospace-bench` owns concrete applied knowledge spaces and their lifecycle.
The default operating mode is file-backed and inspectable. Optional integrations
are explicit, reviewable adapters rather than hidden infrastructure drift.
---
## In Scope
- Defining infospaces as first-class, inspectable project artifacts
- Populating infospaces from real sources and domain-specific configurations
- Evaluating entity quality, collection quality, structure, and viability
- Inspecting relationships, provenance, metrics history, and workflow outputs
- Running application-level generation, transformation, and analysis workflows
- Capturing reusable patterns that may later move into lower-layer repos
- Defining infospaces as first-class, manifest-backed project artifacts
- Populating infospaces from local sources, EPUB-like inputs, profiles, and
domain-specific workflow templates
- Running deterministic fixture workflows and explicit live provider workflows
for generation, extraction, relation mapping, evaluation, and reports
- Evaluating entity quality, collection quality, viability thresholds, metrics
history, and plan-vs-actual generation behavior
- Inspecting entities, relations, artifact graphs, provenance, workflow runs,
provider metadata, budget records, and archive records
- Capturing reusable applied patterns that may later move into lower-layer repos
- Maintaining reference pilots that make abstract infospace concepts concrete
- Planning and recording one-way syncs from file-backed artifacts into an engine
adapter while keeping the local manifest authoritative
- Archiving reviewed infospace snapshots through `artifact-store` without making
archives a substitute for the working folder or git
---
## Out of Scope
- Low-level markdown parsing, schema syntax primitives, or rendering engines
- Generic persistence infrastructure or workflow orchestration platforms
- Generic persistence infrastructure, retrieval systems, permissions, audit, or
workflow orchestration platforms
- Artifact storage backends, retention-policy implementation, replication, or
backup operations
- General content management, publishing, or WYSIWYG editing
- Reusable libraries that belong in `markitect-tool` or `kontextual-engine`
- Reusable provider-routing policy engines or cross-repo LLM infrastructure
- Secret management for provider keys, archive backends, or engine deployments
- Silent coupling to a single LLM vendor or runtime
- Final ownership of production domain artifacts once a dedicated domain repo
should take over
---
@@ -53,37 +77,90 @@ The repo is intentionally above the lower layers:
- A real corpus, book, project, or organization needs an explicit infospace
- Knowledge artifacts need systematic evaluation and iteration history
- Relationship structure and quality metrics need to be inspected over time
- Relationship structure, provenance, and quality metrics need inspection over
time
- Agent-assisted knowledge development needs scoped project context
- A MarkiTect infospace experiment needs to be migrated or reimplemented
- A MarkiTect infospace experiment needs to be migrated, pruned, compared, or
reimplemented
- Generation work needs deterministic fixture runs, guarded live model runs,
routing observations, and budget evidence in one inspectable workspace
- A reviewed infospace milestone needs a content-addressed archive package
---
## Not Relevant When
- The work is only markdown syntax manipulation
- The work is engine/runtime infrastructure
- The work is engine/runtime infrastructure or durable memory persistence
- The work is only artifact-store backend, retention, or storage operations
- A finalized domain repository should own the production artifact
- A few simple documents only need ordinary editing
- A live provider run is being attempted without budget planning, review gates,
and explicit secrets supplied outside the repo
---
## Current State
- Status: newly bootstrapped successor repo
- Source intent: `INTENT.md`, PRD, and FRS in `wiki/`
- Upstream comparison target: `/home/worsch/markitect-main`
- State Hub registration: `infospace-bench` under the `markitect` domain
- First workplans: lifecycle scaffold, MarkiTect migration triage, evaluation
framework, and reference infospace pilot
- Status: implemented application-layer workspace with a Python CLI, test suite,
reference docs, committed pilots, and deterministic fixtures
- Package entry point: `infospace-bench` / `python3 -m infospace_bench`
- Current CLI surface: lifecycle, artifact add/export/validate, readiness
status, entity and relation listing, metrics/checks, history diffs, viability,
graph export, workflow inspect/plan/run, source generation, routing ledger
summaries, budget rollups, archive/restore, and engine sync planning
- Current infospaces:
- `bootstrap-pilot`
- `wealth-vsm-legacy-slice`
- `wealth-vsm-generation-pilot`
- `agentic-memory-profile-pilot`
- `lefevre-reminiscences-of-a-stock-operator`
- `patterns-of-it-securita-architecture`
- Current profiles: bundled `general-knowledge` and `trading-literature`, with
the Lefevre infospace carrying a checked-in trading-literature profile copy
- Current provider posture: fixture runs are deterministic by default;
OpenRouter and routed live runs are explicit, budget-aware, and guarded by
environment-provided credentials
- Current archive posture: `infospace-bench archive`, `archive-list`, and
`restore` integrate with `artifact-store` for reviewed snapshots
- Current engine posture: local file-backed manifests remain authoritative;
engine sync is dry-run by default and currently uses an inspectable local
adapter store
---
## Important Boundaries
- `artifacts/index.yaml` is the authoritative manifest for an infospace in this
repo.
- Generated outputs, budget records, metrics, workflow runs, and reports are
evidence for review; they do not silently become durable engine state.
- Live LLM output is review material. Scaling from a one-chapter or bounded run
to a larger corpus requires explicit planning and human review.
- Archives are immutable evidence packages. Use git for in-flight working state
and artifact-store archives for milestone preservation.
- Successful applied patterns may inform `markitect-tool`, `kontextual-engine`,
`artifact-store`, or `llm-connect`, but this repo should not absorb their
reusable infrastructure responsibilities.
---
## Getting Oriented
- Start with: `INTENT.md`, `wiki/ProductRequirementsDocument.md`,
- Start with: `README.md`, `INTENT.md`, and this file
- Product framing: `wiki/ProductRequirementsDocument.md`,
`wiki/FunctionalRequirementsSpecification.md`
- Migration assessment: `docs/markitect-main-scope-assessment.md`
- Archive integration with `artifact-store`: `docs/archive-integration.md`
- Layout and lifecycle: `docs/infospace-layout.md`,
`docs/evaluation-and-inspection.md`, `docs/entity-relation-model.md`
- Generation and pilots: `docs/generic-source-generator.md`,
`docs/wealth-vsm-generation-pipeline.md`,
`docs/agentic-memory-profile-pilot.md`, `docs/lefevre-readiness.md`
- Integrations and boundaries: `docs/markitect-tool-adapter.md`,
`docs/kontextual-engine-boundary.md`, `docs/archive-integration.md`,
`docs/routing-config.md`, `docs/replacement-readiness-decision.md`
- Code map: `src/infospace_bench/`
- Pilots: `infospaces/`
- Tests: `tests/`
- Workplans: `workplans/`
- State Hub rules: `CLAUDE.md` and `.claude/rules/`
- State Hub and session rules: `AGENTS.md`, `CLAUDE.md`, and
`.claude/rules/`

148
workplans/IB-WP-0021-scope-intent-reconciliation.md Normal file
View File

@@ -0,0 +1,148 @@
---
id: IB-WP-0021
type: workplan
title: "Scope and Intent Reconciliation"
domain: markitect
repo: infospace-bench
status: ready
owner: markitect
topic_slug: markitect
created: "2026-06-04"
updated: "2026-06-04"
related_workplans:
- IB-WP-0005
- IB-WP-0014
- IB-WP-0015
- IB-WP-0018
- IB-WP-0020
state_hub_workstream_id: "62ad79c9-43f6-43ef-847c-ef88e9ec9e3c"
---
# IB-WP-0021 - Scope and Intent Reconciliation
## Goal
Reconcile `SCOPE.md` with `INTENT.md` after the repo has matured from a
successor scaffold into an implemented file-backed application workspace and
CLI. The intent document remains the strategic charter; the scope document
should make that charter operational without narrowing or expanding it by
accident.
## Context
The 2026-06-04 gap analysis found that `SCOPE.md` is broadly aligned with
`INTENT.md`, but five strategic promises need clearer treatment:
- `INTENT.md` says "workspace and service"; `SCOPE.md` currently emphasizes
workspace and CLI.
- `INTENT.md` names intended users and agents; `SCOPE.md` lacks a matching
actor-facing section.
- `INTENT.md` emphasizes iterative development, refinement, and export;
`SCOPE.md` mostly makes those implicit.
- `SCOPE.md` names `artifact-store` and `llm-connect`, which are real current
integrations, but should not appear to redefine the three-layer strategic
model from `INTENT.md`.
- `INTENT.md` names best-practice reference-environment maturity; `SCOPE.md`
mentions pilots and reusable patterns but does not surface that target
directly.
## Non-Goals
- Changing the strategic direction in `INTENT.md`.
- Implementing new runtime, service, storage, routing, or engine features.
- Reopening completed pilot implementation work.
- Adding current workplan status summaries to `SCOPE.md`.
## Tasks
### T01 - Decide service wording
```task
id: IB-WP-0021-T01
status: todo
priority: high
state_hub_task_id: "860c2f5f-13e3-4f67-b4dd-6285c066a03e"
```
Decide whether "service" in `INTENT.md` is still a future maturity target or
whether the repository should now be described strictly as a workspace and CLI.
Update `SCOPE.md` to make that relationship explicit without overstating
implemented service behavior.
### T02 - Add primary actor framing
```task
id: IB-WP-0021-T02
status: todo
priority: medium
state_hub_task_id: "a17391f9-2d1d-47f4-af8b-2803a96f376d"
```
Add a concise `Primary Actors` or equivalent section to `SCOPE.md` that maps
the intended users from `INTENT.md` into operational scope: knowledge
engineers, developers, researchers, practitioners, automation systems, and LLM
agents.
### T03 - Surface refinement and export lifecycle
```task
id: IB-WP-0021-T03
status: todo
priority: medium
state_hub_task_id: "2baf36c7-47b2-42a7-8f8e-ccbd82ae5d38"
```
Make iterative review, pruning, revision, refinement, and export explicit in
`SCOPE.md`, while preserving the boundary that durable archive packages and
production domain ownership belong outside normal in-flight workspace state.
### T04 - Clarify strategic layers versus supporting integrations
```task
id: IB-WP-0021-T04
status: todo
priority: high
state_hub_task_id: "7859d62d-4a50-4146-a50b-e4ae7e65d6c0"
```
Revise the core-idea or boundary language so `markitect-tool`,
`kontextual-engine`, and `infospace-bench` remain the strategic syntax/system/
application layers from `INTENT.md`, while `artifact-store` and `llm-connect`
are presented as supporting integrations with their own ownership boundaries.
### T05 - Add reference-environment maturity target
```task
id: IB-WP-0021-T05
status: todo
priority: medium
state_hub_task_id: "55b7050f-0e3e-4649-ad23-3bc6de6bbc35"
```
Add language that ties `SCOPE.md` back to the maturity target in `INTENT.md`:
`infospace-bench` should be a reference environment for applied knowledge
engineering practice, not just a collection of pilots.
### T06 - Verify documentation consistency
```task
id: IB-WP-0021-T06
status: todo
priority: low
state_hub_task_id: "fa7a4e5c-4202-4940-aee6-acdf268a752d"
```
After the edits, review `SCOPE.md`, `INTENT.md`, and `README.md` together for
terminology drift. Run a lightweight markdown/diff check and record whether any
follow-up changes belong in `INTENT.md` rather than `SCOPE.md`.
## Acceptance
- `SCOPE.md` no longer contains dated workplan-status summaries.
- Each gap from the 2026-06-04 analysis is either resolved in `SCOPE.md` or
explicitly deferred with a reason.
- `SCOPE.md` preserves the strategic authority of `INTENT.md` while reflecting
the repo's implemented state.
- Supporting integrations are described as integrations, not as new strategic
layers.
- No implementation work outside documentation is introduced by this workplan.