diff --git a/SCOPE.md b/SCOPE.md index e50159b..15c1d6e 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -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/` diff --git a/workplans/IB-WP-0021-scope-intent-reconciliation.md b/workplans/IB-WP-0021-scope-intent-reconciliation.md new file mode 100644 index 0000000..aa80277 --- /dev/null +++ b/workplans/IB-WP-0021-scope-intent-reconciliation.md @@ -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.