Intent and specification files

2026-05-03 19:25:29 +02:00
parent 4886256995
commit 49940a6583
3 changed files with 609 additions and 0 deletions
--- a/INTENT.md
+++ b/INTENT.md
@@ -0,0 +1,110 @@
+# INTENT
+
+## Purpose
+
+This repository exists to provide a **workspace and service for creating, developing, evaluating, and inspecting structured knowledge spaces (“infospaces”)**.
+
+It enables the practical exploration and application of structured knowledge systems in concrete domains such as books, projects, research corpora, and organizational knowledge.
+
+---
+
+## Primary Utility
+
+The repository provides an environment that:
+
+* Defines and manages **explicit infospaces as first-class artifacts**
+* Supports iterative development of structured knowledge collections
+* Enables evaluation, inspection, and refinement of knowledge quality and structure
+* Applies transformation, generation, and analysis workflows to real-world content
+* Serves as a testbed for methods, patterns, and tooling in knowledge engineering
+
+It turns abstract knowledge tooling into **concrete, inspectable knowledge systems**.
+
+---
+
+## Intended Users
+
+* Knowledge engineers and developers working on structured content systems
+* Researchers and practitioners organizing and analyzing domain knowledge
+* Automation systems (`atm`) executing knowledge workflows within a defined scope
+* LLM agents (`agt`) contributing to the generation and refinement of infospaces
+
+---
+
+## Strategic Role in the System
+
+This repository is part of a layered knowledge system with clearly separated responsibilities:
+
+- markitect-tool     → makes markdown structured and manipulable
+- kontextual-engine  → makes knowledge persistent and operable
+- **infospace-bench**    → makes knowledge concrete and meaningful
+
+These layers correspond to a deliberate separation of concerns:
+
+* **Syntax layer** — structuring and transforming semi-structured data (markdown)
+* **System layer** — operating, persisting, and orchestrating knowledge
+* **Application layer** — applying knowledge systems to real-world contexts
+
+This repository occupies the **application layer** and should maintain **clear boundaries** to the others.
+
+This repository acts as the **project and experimentation layer**:
+
+* It sits above the knowledge engine (`kontextual-engine`)
+* It uses tooling primitives (e.g. `markitect-tool`) via the engine or directly
+* It defines **real-world instances of structured knowledge systems**
+* It provides a space to **validate approaches, workflows, and abstractions**
+
+It is where knowledge systems are **applied, tested, and evolved in context**.
+
+---
+
+## Strategic Boundaries
+
+This repository is **not** intended to:
+
+* Provide low-level tooling for markdown or structured content manipulation
+* Act as a general-purpose knowledge engine or runtime platform
+* Define reusable infrastructure primitives or core system contracts
+* Replace domain-specific repositories for finalized artifacts
+
+Its responsibility is limited to **working with concrete infospaces and their lifecycle**.
+
+---
+
+## Design Principles
+
+* **Concrete over abstract**
+  Focus on real, inspectable knowledge artifacts rather than generic capabilities
+
+* **Exploration and iteration**
+  Infospaces evolve through experimentation, evaluation, and refinement
+
+* **Separation from infrastructure**
+  Tooling and engine concerns remain outside this repository
+
+* **Traceability and inspectability**
+  All knowledge transformations and evaluations should be observable
+
+* **Reusability of patterns**
+  Successful approaches can be extracted into lower layers or reused across infospaces
+
+---
+
+## Maturity Target
+
+A mature version of this repository should:
+
+* Support the **full lifecycle of infospaces** from creation to evaluation and export
+* Provide **clear visibility into structure, quality, and relationships** within knowledge spaces
+* Enable efficient **AI-assisted development and refinement of knowledge artifacts**
+* Serve as a **reference environment for best practices in knowledge engineering**
+* Produce reusable insights and patterns that inform lower-layer systems
+
+---
+
+## Stability Note
+
+Changes to this file represent a **deliberate shift in how infospaces are defined, developed, or used** within the system.
+
+Such changes should be made with explicit intent, as they influence the direction of knowledge engineering practices across the ecosystem.
+
--- a/wiki/FunctionalRequirementsSpecification.md
+++ b/wiki/FunctionalRequirementsSpecification.md
@@ -0,0 +1,273 @@
+# Infospace Bench Functional Requirements Specification V0.1
+
+## infospace-bench
+
+---
+
+## 1. System Overview
+
+infospace-bench is a **workspace and service** that enables users and systems to **create, develop, evaluate, inspect, and export structured knowledge spaces (“infospaces”)**.
+
+This FRS defines the **externally observable functional behavior** of the system.
+
+---
+
+## 2. Actors and Interfaces
+
+### 2.1 Primary Actors
+
+* **User (Human Operator)** working on knowledge projects
+* **Automation System (`atm`)** executing workflows on infospaces
+* **LLM Agent (`agt`)** contributing to knowledge generation and evaluation
+* **External Systems** consuming outputs or interacting with infospaces
+
+---
+
+### 2.2 System Interfaces
+
+* Workspace/project interface (CLI and/or service interface)
+* Programmatic API
+* File system and/or service-backed storage (abstracted)
+
+---
+
+## 3. Functional Requirements
+
+---
+
+## 3.1 Infospace Lifecycle Management
+
+### FR-001: Create Infospace
+
+**Description:**
+The system must allow creation of a new infospace.
+
+**Input:**
+
+* Infospace definition (name, configuration, initial parameters)
+
+**Output:**
+
+* Initialized infospace with identifier
+
+---
+
+### FR-002: Load Infospace
+
+The system must allow loading an existing infospace for interaction.
+
+---
+
+### FR-003: Update Infospace
+
+The system must allow modification of infospace configuration and content.
+
+---
+
+### FR-004: Delete Infospace
+
+The system must allow removal of an infospace.
+
+---
+
+## 3.2 Knowledge Population
+
+### FR-010: Add Knowledge Artifacts
+
+The system must allow adding knowledge artifacts (documents, entities, or content) to an infospace.
+
+---
+
+### FR-011: Modify Knowledge Artifacts
+
+The system must allow modification of existing artifacts within an infospace.
+
+---
+
+### FR-012: Remove Knowledge Artifacts
+
+The system must allow removal of artifacts from an infospace.
+
+---
+
+## 3.3 Structure and Organization
+
+### FR-020: Organize Knowledge
+
+The system must allow organizing artifacts within an infospace.
+
+---
+
+### FR-021: Maintain Relationships
+
+The system must allow defining and retrieving relationships between artifacts within an infospace.
+
+---
+
+## 3.4 Evaluation and Quality Assessment
+
+### FR-030: Evaluate Infospace
+
+The system must allow evaluation of an infospace.
+
+**Output:**
+
+* Evaluation results (e.g. quality indicators, scores, or assessments)
+
+---
+
+### FR-031: Evaluate Individual Artifacts
+
+The system must allow evaluation of individual artifacts within an infospace.
+
+---
+
+### FR-032: Provide Evaluation Results
+
+The system must provide structured evaluation outputs that can be inspected and reused.
+
+---
+
+## 3.5 Inspection and Exploration
+
+### FR-040: Inspect Infospace Structure
+
+The system must allow inspection of:
+
+* Structure
+* Relationships
+* Organization
+
+---
+
+### FR-041: Explore Knowledge Artifacts
+
+The system must allow exploration of artifacts and their connections.
+
+---
+
+### FR-042: Visualize Relationships
+
+The system must provide representations of relationships between artifacts.
+
+---
+
+## 3.6 Transformation and Generation
+
+### FR-050: Apply Transformations
+
+The system must allow applying transformations to infospace content.
+
+---
+
+### FR-051: Generate Knowledge Artifacts
+
+The system must allow generating new artifacts based on:
+
+* Existing content
+* Rules/templates
+* AI-assisted processes
+
+---
+
+### FR-052: Apply Batch Operations
+
+The system must allow transformations and generation across multiple artifacts.
+
+---
+
+## 3.7 Workflow Execution
+
+### FR-060: Execute Infospace Workflows
+
+The system must allow execution of workflows specific to an infospace.
+
+---
+
+### FR-061: Provide Workflow Results
+
+The system must provide outputs and results of workflow execution.
+
+---
+
+## 3.8 Export and Output
+
+### FR-070: Export Infospace
+
+The system must allow exporting an infospace.
+
+---
+
+### FR-071: Export Derived Artifacts
+
+The system must allow exporting generated or transformed outputs.
+
+---
+
+## 3.9 AI Interaction
+
+### FR-080: Support AI-Assisted Operations
+
+The system must allow AI agents to:
+
+* Generate content
+* Evaluate knowledge
+* Suggest modifications
+
+---
+
+### FR-081: Provide Context to AI
+
+The system must provide sufficient context for AI-assisted operations within an infospace.
+
+---
+
+## 3.10 Error Handling
+
+### FR-090: Provide Structured Errors
+
+The system must return structured error information for invalid operations.
+
+---
+
+### FR-091: Avoid Silent Failures
+
+The system must not silently ignore errors affecting results.
+
+---
+
+## 4. Functional Constraints
+
+* All operations must be scoped to a defined infospace
+* Functions must operate on structured knowledge artifacts
+* AI-assisted operations must be optional
+* System must not assume ownership of lower-level tooling or system infrastructure
+
+---
+
+## 5. Traceability
+
+| PRD Concept                 | FRS Coverage  |
+| --------------------------- | ------------- |
+| Infospace lifecycle         | FR-001–FR-004 |
+| Knowledge population        | FR-010–FR-012 |
+| Structure & relationships   | FR-020–FR-021 |
+| Evaluation & quality        | FR-030–FR-032 |
+| Inspection & visualization  | FR-040–FR-042 |
+| Transformation & generation | FR-050–FR-052 |
+| Workflow execution          | FR-060–FR-061 |
+| Export                      | FR-070–FR-071 |
+| AI interaction              | FR-080–FR-081 |
+
+---
+
+## 6. Acceptance Perspective
+
+The system satisfies this FRS when:
+
+* Infospaces can be created, modified, and inspected
+* Knowledge artifacts can be added, transformed, and evaluated
+* Relationships and structure are observable
+* Workflows produce reproducible outputs
+* AI-assisted operations function with appropriate context
+* Errors are explicit and traceable
--- a/wiki/ProductRequirementsDocument.md
+++ b/wiki/ProductRequirementsDocument.md
@@ -0,0 +1,226 @@
+# Infospace Bench Product Requirements Document V0.1
+
+## infospace-bench
+
+---
+
+## 1. Product Overview
+
+### 1.1 Product Name
+
+**infospace-bench**
+
+---
+
+### 1.2 Product Definition
+
+infospace-bench is a **workspace and service for creating, developing, evaluating, and inspecting structured knowledge spaces (“infospaces”)**.
+
+It provides an environment for applying structured knowledge methods to real-world domains such as books, research corpora, projects, and organizational knowledge systems.
+
+---
+
+## 2. Product Intent
+
+### 2.1 Problem Statement
+
+While tools and systems for structured knowledge exist:
+
+* There is no consistent way to **develop and evaluate knowledge spaces in practice**
+* Knowledge engineering approaches remain abstract and hard to validate
+* Real-world knowledge artifacts lack **structured inspection and quality evaluation**
+* Iterative refinement of knowledge systems is often ad-hoc and untraceable
+
+This results in a gap between **knowledge theory and applied knowledge systems**.
+
+---
+
+### 2.2 Intended Outcomes
+
+infospace-bench enables:
+
+* Creation of **explicit, structured knowledge spaces** as first-class artifacts
+* Iterative **development, evaluation, and refinement** of knowledge collections
+* Inspection of **structure, quality, and relationships** within knowledge
+* Application of AI-assisted workflows to real-world knowledge problems
+* Generation of reusable patterns and insights for knowledge engineering
+
+---
+
+### 2.3 Success Criteria
+
+The product is successful when:
+
+* Infospaces can be **created, evolved, and inspected systematically**
+* Knowledge quality can be **evaluated and improved over time**
+* Real-world use cases (books, domains, projects) can be modeled effectively
+* AI agents can contribute meaningfully to **knowledge development workflows**
+* Insights from infospaces inform improvements in lower-layer systems
+
+---
+
+## 3. Scope Definition
+
+### 3.1 In Scope
+
+* Definition and management of infospaces as structured knowledge collections
+* Lifecycle management: creation, population, evaluation, refinement, export
+* Inspection tools for structure, relationships, and quality
+* Application of workflows (generation, transformation, analysis) to infospaces
+* AI-assisted development and evaluation of knowledge artifacts
+* Use-case-specific configurations and project setups
+
+---
+
+### 3.2 Out of Scope
+
+* Low-level markdown processing or transformation primitives
+* Persistent system infrastructure or orchestration engines
+* Generic multi-format content management systems
+* Reusable tooling libraries or platform-level abstractions
+* Final production publishing platforms (outside knowledge development context)
+
+---
+
+### 3.3 Boundary Clarification
+
+infospace-bench provides **application-level usage**, not infrastructure:
+
+* Tooling primitives → `markitect-tool`
+* System/runtime orchestration → `kontextual-engine`
+
+---
+
+## 4. Functional Expectations
+
+### 4.1 Core Capabilities
+
+The product must support:
+
+* **Infospace Definition**
+  Create structured knowledge collections with clear boundaries
+
+* **Population & Development**
+  Add, modify, and organize knowledge artifacts
+
+* **Evaluation & Quality Assessment**
+  Measure structure, consistency, and completeness
+
+* **Inspection & Visualization**
+  Explore relationships, dependencies, and structure
+
+* **Transformation & Generation**
+  Apply workflows to evolve knowledge artifacts
+
+* **Export & Representation**
+  Produce outputs (documents, reports, derived artifacts)
+
+---
+
+### 4.2 Interaction Modes
+
+* Project/workspace-based interaction
+* CLI and/or service interfaces
+* Agent-assisted workflows
+
+---
+
+## 5. Non-Functional Expectations
+
+### 5.1 Performance
+
+* Efficient handling of medium-to-large knowledge collections
+* Reasonable responsiveness for interactive inspection and iteration
+
+---
+
+### 5.2 Reliability
+
+* Consistent behavior in evaluation and transformation workflows
+* Traceable changes and reproducible results
+
+---
+
+### 5.3 Extensibility
+
+* Ability to incorporate new workflows and evaluation methods
+* Flexible configuration for different domains and use cases
+
+---
+
+### 5.4 Usability
+
+* Clear structure for organizing knowledge projects
+* Intuitive workflows for iteration and refinement
+* Transparency of system behavior and results
+
+---
+
+## 6. Assumptions and Dependencies
+
+### 6.1 Assumptions
+
+* Knowledge engineering benefits from iterative, project-based development
+* AI agents can assist in generating and refining knowledge
+* Structured knowledge systems require evaluation and inspection
+
+---
+
+### 6.2 Dependencies
+
+* kontextual-engine for persistence and orchestration
+* markitect-tool for markdown-based structuring and transformation
+* llm-connect (or equivalent) for AI-assisted workflows
+
+---
+
+## 7. Constraints
+
+* Must remain focused on **concrete infospaces**, not abstract infrastructure
+* Must avoid duplication of tooling or system-level responsibilities
+* Must support both human and AI-driven workflows
+* Must maintain clear traceability of knowledge evolution
+
+---
+
+## 8. Risks
+
+* Drifting into general-purpose platform or CMS functionality
+* Over-complex evaluation frameworks reducing usability
+* Tight coupling to specific tools or formats
+* Loss of clarity between experimentation and production usage
+
+---
+
+## 9. Related Systems
+
+* **markitect-tool** – syntax layer (markdown primitives)
+* **kontextual-engine** – system layer (persistence and orchestration)
+* **llm-connect** – LLM abstraction layer
+
+---
+
+## 10. Ecosystem Context
+
+This product is part of a layered knowledge system:
+
+```text id="k2pz7m"
+markitect-tool     → makes markdown structured and manipulable
+kontextual-engine  → makes knowledge persistent and operable
+infospace-bench    → makes knowledge concrete and meaningful
+```
+
+Layers:
+
+* **Syntax layer** → markitect-tool
+* **System layer** → kontextual-engine
+* **Application layer** → infospace-bench
+
+---
+
+## 11. PRD Type
+
+**Hybrid / Boundary PRD**
+
+This PRD defines application-level intent and usage boundaries while allowing flexibility for experimentation and iterative development.
+