generated from coulomb/repo-seed
167 lines
7.1 KiB
Markdown
167 lines
7.1 KiB
Markdown
# SCOPE
|
|
|
|
> This file helps humans and agents quickly understand what this repository is
|
|
> for, when it is relevant, and where its boundaries are.
|
|
|
|
---
|
|
|
|
## One-liner
|
|
|
|
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 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, 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, 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, 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 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
|
|
|
|
---
|
|
|
|
## Relevant When
|
|
|
|
- A real corpus, book, project, or organization needs an explicit infospace
|
|
- Knowledge artifacts need systematic evaluation and iteration history
|
|
- 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, 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 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: 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: `README.md`, `INTENT.md`, and this file
|
|
- Product framing: `wiki/ProductRequirementsDocument.md`,
|
|
`wiki/FunctionalRequirementsSpecification.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 and session rules: `AGENTS.md`, `CLAUDE.md`, and
|
|
`.claude/rules/`
|