From e4febab61ee3447da568c5fe82576ffd2abaa75e Mon Sep 17 00:00:00 2001 From: Jeffrey Phillips Freeman Date: Thu, 12 Feb 2026 10:07:37 -0500 Subject: [PATCH] Docs: Updated the depth / detail level concept to be more extensible with additional levels as well --- docs/specification.md | 1118 +++++++++++++++++++++++++++++++---------- 1 file changed, 864 insertions(+), 254 deletions(-) diff --git a/docs/specification.md b/docs/specification.md index cd5915a64..e158192c9 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -50,13 +50,14 @@ While CleverAgents leverages LangGraph and LangChain for the underlying LLM runt * **Automation Profile**: A named set of confidence thresholds (0.0–1.0) controlling which plan operations proceed automatically vs. require human approval. Thresholds gate phase transitions, decision autonomy, self-repair, child plan spawning, and safety requirements. 0.0 = always automatic; 1.0 = always manual. Eight built-in profiles range from `manual` to `full-auto`. Custom profiles follow `[[server:]namespace/]name`. * **ULID**: Universally Unique Lexicographically Sortable Identifier. Used for plan, decision, resource, correction attempt, and validation attachment IDs. Preferred over UUID for time-sortability. Note: Projects, actions, skills, and tools do not use ULIDs — their namespaced name is their unique identifier. Resources use both: a ULID (always) and a namespaced name (for user-added resources only; auto-discovered child resources have ULID only). Validation attachments use a ULID to uniquely identify each attachment of a validation to a resource (with its optional project or plan scope). * **ACMS (Advanced Context Management System)**: The fully pluggable, strategy-driven framework for assembling context for actors. Built around the UKO, CRP, and a pluggable strategy framework with a fusion coordinator. -* **UKO (Universal Knowledge Ontology)**: An inheritance-based RDF ontology hierarchy that represents any resource (source code, documents, databases, infrastructure) at multiple levels of abstraction, with full provenance and temporal versioning. Organized in four layers: Layer 0 (universal foundation), Layer 1 (general software), Layer 2 (paradigm specializations), Layer 3 (language-specific). -* **CRP (Context Request Protocol)**: A structured vocabulary through which actors (via skills) declare what information they need, at what detail level, and with what scope, during reasoning. Uses the `builtin/context` skill with tools like `request_context`, `query_history`, and `get_context_budget`. +* **UKO (Universal Knowledge Ontology)**: An inheritance-based RDF ontology hierarchy that represents any resource (source code, documents, databases, infrastructure) at multiple levels of abstraction, with full provenance and temporal versioning. Organized in four layers: Layer 0 (universal foundation), Layer 1 (domain specializations — including general software, documents, data schemas, and infrastructure), Layer 2 (paradigm/format specializations — e.g., OO, functional, procedural for code; academic vs. technical for documents; relational vs. graph for databases), Layer 3 (technology-specific — e.g., Python, TypeScript, Markdown, PostgreSQL). The ontology is semantically aware: when processing any resource, the system infers implicit relationships (e.g., a paragraph in a document that discusses a concept covered in another section produces a `uko:references` edge even when no explicit link exists; a database view that queries columns from multiple tables produces `uko:dependsOn` edges to those tables). +* **CRP (Context Request Protocol)**: A structured vocabulary through which actors (via skills) declare what information they need, at what detail depth, and with what scope, during reasoning. Uses the `builtin/context` skill with tools like `request_context`, `query_history`, and `get_context_budget`. * **Context Strategy**: A pluggable component that searches for and assembles context fragments using a specific retrieval approach (e.g., keyword search, semantic embedding, breadth-depth graph navigation, temporal archaeology). Strategies are registered with the Strategy Coordinator and run in parallel during context assembly. * **Strategy Coordinator**: The orchestrator component within the ACMS that receives `ContextRequest` objects, selects applicable strategies, allocates budget proportionally by confidence, runs strategies in parallel, and passes results to the Fusion Engine. -* **Fusion Engine**: The ACMS component that deduplicates, merges, and orders context fragments from multiple strategies into a single budget-respecting context payload. Resolves detail-level conflicts, applies hierarchical weighting, and runs greedy knapsack packing. -* **ContextFragment**: The atomic unit of context returned by strategies. Contains a UKO node reference, rendered text, token count, detail level, relevance score, provenance, and metadata. -* **DetailLevel**: An enumeration of abstraction levels for context content: `SIGNATURE` (declarations only), `SUMMARY` (LLM-generated or docstring summaries), `STUB` (signatures + key logic), `FULL` (complete content). +* **Fusion Engine**: The ACMS component that deduplicates, merges, and orders context fragments from multiple strategies into a single budget-respecting context payload. Resolves detail-depth conflicts, applies hierarchical weighting, and runs greedy knapsack packing. +* **ContextFragment**: The atomic unit of context returned by strategies. Contains a UKO node reference, rendered text, token count, resolved integer detail depth, relevance score, provenance, and metadata. +* **DetailDepth**: A non-negative integer (0, 1, 2, ... N) representing how much detail to include when rendering a UKO information unit into context. At the universal Layer 0 of the UKO, depth is purely numeric with domain-agnostic semantics: depth 0 is the most minimal representation (just a name/identifier), and each increment reveals progressively more structure, content, and relationships. There is no fixed upper bound — the maximum meaningful depth depends on the domain and the specific information unit. Each UKO domain extension (code, documents, databases, infrastructure) registers a **DetailLevelMap** that assigns named labels to specific integer depths. For example, the source code domain (`uko-code:`) defines names like `MODULE_LISTING`, `SIGNATURES`, `STRUCTURAL_OUTLINE`, `FULL_SOURCE`, etc., each mapped to a specific integer depth. Language-specific extensions (e.g., `uko-py:`) may insert additional named levels between or beyond those defined by their parent domain. Actors and context policies can specify depth as either a raw integer or a domain-specific named level (resolved to its integer via the active DetailLevelMap). +* **DetailLevelMap**: A registry that maps named detail level labels to integer DetailDepth values for a specific UKO domain or subdomain. Each UKO vocabulary extension (e.g., `uko-code:`, `uko-doc:`, `uko-py:`) can register its own DetailLevelMap. Maps inherit from their parent domain's map: a language-specific map includes all named levels from the general code map, plus any additional levels it introduces. When a named level is requested, the system resolves it using the most specific map available for the target UKO node's type. * **ScopedBackendView**: A filtering layer that automatically restricts all backend queries (text index, vector index, graph store) to only the resources belonging to the current plan's project(s). Ensures actors never see resources outside their project scope. * **Skeleton (context)**: A compressed representation of a plan's accumulated context, produced by the skeleton compressor. Propagated from parent plans to child plans as inherited context. Controlled by the `skeleton_ratio` budget parameter. @@ -110,8 +111,8 @@ While CleverAgents leverages LangGraph and LangChain for the underlying LLM runt [--summary-max-tokens <N>] [--strategy <STRATEGY>]... [--default-breadth <N>] - [--default-depth (SIGNATURE|SUMMARY|STUB|FULL)] - [--depth-gradient <HOP:LEVEL>]... + [--default-depth <INT_OR_NAME>] + [--depth-gradient <HOP:INT_OR_NAME>]... [--skeleton-ratio <FLOAT>] [--temporal-scope (current|recent|all)] [--auto-refresh|--no-auto-refresh] @@ -121,7 +122,7 @@ While CleverAgents leverages LangGraph and LangChain for the underlying LLM runt agents project context inspect [--view (strategize|execute|apply|default)] [--strategy <STRATEGY>] [--focus <UKO_URI>]... - [--breadth <N>] [--depth (SIGNATURE|SUMMARY|STUB|FULL)] + [--breadth <N>] [--depth <INT_OR_NAME>] <PROJECT> agents project context simulate [--view (strategize|execute|apply|default)] [--budget <TOKENS>] @@ -1216,8 +1217,8 @@ Manage ACMS context policies for the hot/warm/cold tiers, per-view context selec [--summary-max-tokens <N>] [--strategy <STRATEGY>]... [--default-breadth <N>] - [--default-depth (SIGNATURE|SUMMARY|STUB|FULL)] - [--depth-gradient <HOP:LEVEL>]... + [--default-depth <INT_OR_NAME>] + [--depth-gradient <HOP:INT_OR_NAME>]... [--skeleton-ratio <FLOAT>] [--temporal-scope (current|recent|all)] [--auto-refresh|--no-auto-refresh] @@ -1244,8 +1245,8 @@ Set the context policy for a project and (optionally) a specific view. - `--summary-max-tokens N`: Token limit for generated summaries. - `--strategy STRATEGY`: ACMS context strategy to enable for this view (repeatable). Overrides the global `context.strategies.enabled` list. Built-in: `simple-keyword`, `semantic-embedding`, `breadth-depth-navigator`, `arce`, `temporal-archaeology`, `plan-decision-context`. - `--default-breadth N`: Default number of hops from focus nodes in the UKO graph. `0` = focus nodes only. Default: `2`. -- `--default-depth SIGNATURE|SUMMARY|STUB|FULL`: Default detail level for context fragments. Default: `SUMMARY`. -- `--depth-gradient HOP:LEVEL`: Per-hop detail level override (repeatable). Format: `0:FULL`, `1:SUMMARY`, `2:SIGNATURE`. Hops not specified use `--default-depth`. +- `--default-depth INT_OR_NAME`: Default detail depth for context fragments. Accepts a raw integer (e.g., `4`) or a named level from the active domain's DetailLevelMap (e.g., `SIGNATURES`, `MEMBER_SUMMARY`). Named levels are resolved to integers via the DetailLevelMap inheritance chain. Default: `3` (typically `MEMBER_SUMMARY` / `FULL_TOC` / `TYPED_COLUMNS` depending on domain). +- `--depth-gradient HOP:INT_OR_NAME`: Per-hop detail depth override (repeatable). Format: `0:9`, `1:4`, `2:0` or `0:FULL_SOURCE`, `1:SIGNATURES`, `2:MODULE_LISTING`. Hops not specified use `--default-depth`. - `--skeleton-ratio FLOAT`: Fraction of context budget reserved for inherited plan skeleton. Range: 0.0–1.0. Default: `0.15`. - `--temporal-scope current|recent|all`: Temporal scope for UKO node resolution. Default: `current`. - `--auto-refresh/--no-auto-refresh`: Enable or disable automatic context re-assembly on budget changes. @@ -1343,7 +1344,7 @@ Show the active context policy for a project. 
agents project context inspect [--view (strategize|execute|apply|default)]
                                [--strategy <STRATEGY>]
                                [--focus <UKO_URI>]...
-                               [--breadth <N>] [--depth (SIGNATURE|SUMMARY|STUB|FULL)]
+                               [--breadth <N>] [--depth <INT_OR_NAME>]
                                <PROJECT>
**Purpose** @@ -1356,7 +1357,7 @@ Inspect the current state of the ACMS context assembly for a project. Shows the - `--strategy STRATEGY`: Filter to show results from a specific strategy only. - `--focus UKO_URI`: Show the UKO subgraph rooted at these focus nodes (repeatable). When omitted, shows a summary of the full indexed graph. - `--breadth N`: Override the breadth (hop count) for the focus node expansion. Default: uses the view's `default_breadth`. -- `--depth SIGNATURE|SUMMARY|STUB|FULL`: Override the depth for the display. Default: uses the view's `default_depth`. +- `--depth INT_OR_NAME`: Override the detail depth for the display. Accepts a raw integer or a named level from the active DetailLevelMap. Default: uses the view's `default_depth`. **Examples** @@ -1367,15 +1368,15 @@ Inspect the current state of the ACMS context assembly for a project. Shows the │ Project: local/api-service │ │ View: execute │ │ Focus: uko-py:module/src.auth │ -│ Breadth: 2 hops │ Depth: SUMMARY │ +│ Breadth: 2 hops │ Depth: 3 (MEMBER_SUMMARY) │ ╰──────────────────────────────────────────────────────────────────╯ ╭─ UKO Graph (2-hop neighborhood) ─────────────────────────────────╮ -│ uko-py:module/src.auth (FULL, 1,240 tokens) │ -│ ├─ contains → uko-py:class/AuthHandler (SUMMARY, 320 tokens) │ -│ ├─ contains → uko-py:class/TokenValidator (SUMMARY, 280 tok) │ -│ ├─ imports → uko-py:module/src.db (SIGNATURE, 90 tokens) │ -│ └─ imports → uko-py:module/src.config (SIGNATURE, 60 tok) │ +│ uko-py:module/src.auth (depth 9/FULL_SOURCE, 1,240 tokens) │ +│ ├─ contains → uko-py:class/AuthHandler (depth 3, 320 tokens) │ +│ ├─ contains → uko-py:class/TokenValidator (depth 3, 280 tok) │ +│ ├─ imports → uko-py:module/src.db (depth 0, 90 tokens) │ +│ └─ imports → uko-py:module/src.config (depth 0, 60 tok) │ ╰──────────────────────────────────────────────────────────────────╯ ╭─ Active Strategies ──────────────────────────────────────────────╮ @@ -1433,17 +1434,17 @@ Simulate a context assembly run without invoking an actor. Produces a dry-run re ╭─ Strategy Results ───────────────────────────────────────────────╮ │ breadth-depth-navigator │ │ Confidence: 0.85 │ Budget: 7,200 tokens │ 12 fragments │ -│ Top: src/auth/__init__.py (FULL, 1,240t, score=0.95) │ -│ src/db/models.py (SUMMARY, 480t, score=0.88) │ +│ Top: src/auth/__init__.py (depth 9, 1,240t, score=0.95) │ +│ src/db/models.py (depth 3, 480t, score=0.88) │ │ │ │ semantic-embedding │ │ Confidence: 0.60 │ Budget: 5,600 tokens │ 8 fragments │ -│ Top: src/auth/jwt.py (SUMMARY, 380t, score=0.82) │ -│ src/middleware/auth_check.py (SUMMARY, 290t, score=0.79) │ +│ Top: src/auth/jwt.py (depth 3, 380t, score=0.82) │ +│ src/middleware/auth_check.py (depth 3, 290t, score=0.79) │ │ │ │ simple-keyword │ │ Confidence: 0.30 │ Budget: 3,200 tokens │ 5 fragments │ -│ Top: src/auth/utils.py (STUB, 210t, score=0.71) │ +│ Top: src/auth/utils.py (depth 6, 210t, score=0.71) │ ╰──────────────────────────────────────────────────────────────────╯ ╭─ Fusion Result ──────────────────────────────────────────────────╮ @@ -8023,10 +8024,10 @@ The ULID is necessary because the same validation can be attached to the same re When attaching a validation, optional arguments can be provided after the validation name: -``` -agents validation attach --project local/api-service local/api-repo local/run-tests --coverage-threshold 90 -agents validation attach --project local/staging-api local/api-repo local/run-tests --coverage-threshold 70 -``` +

+$ agents validation attach --project local/api-service local/api-repo local/run-tests --coverage-threshold 90
+$ agents validation attach --project local/staging-api local/api-repo local/run-tests --coverage-threshold 70
+
These arguments are stored with the attachment and passed to the validation tool's `input_schema` at execution time. This enables a single validation definition to be reused across scopes with different thresholds or configurations. If no arguments are provided, the validation uses its `input_schema` defaults. @@ -8090,12 +8091,12 @@ When a **required** validation returns `"passed": false` during Execute: The flow can be summarized as: -``` -validate → fail → fix → re-validate → fail → fix → re-validate → ... → retry limit - → request strategy revision → re-strategize → re-execute → validate - → still failing → escalate to user → user provides guidance → resume - → still failing → plan fails -``` +

+validate → fail → fix → re-validate → fail → fix → re-validate → ... → retry limit
+  → request strategy revision → re-strategize → re-execute → validate
+  → still failing → escalate to user → user provides guidance → resume
+  → still failing → plan fails
+
##### Informational Validation Failure @@ -10156,7 +10157,7 @@ The Advanced Context Management System (ACMS) is CleverAgents' fully pluggable, 3. **A Pluggable Strategy Framework** with a **Fusion Coordinator** -- multiple independent context strategies can be registered, each working with different data backends and different abstraction levels of the UKO. A coordinator merges their contributions into a single, budget-respecting, deduplicated context payload. -The system is designed around the hierarchical nature of plans: parent plans see wide, shallow context (breadth); child plans see narrow, deep context (depth). Context inheritance flows parent-to-child with progressive focusing, and every context assembly respects a dynamically-changing token budget. +The system is designed around the hierarchical nature of plans: parent plans see wide, shallow context (breadth); child plans see narrow, deep context (depth). Context inheritance flows parent-to-child with progressive focusing, and every context assembly respects a dynamically-changing token budget. This architecture is domain-agnostic: the same breadth/depth/DetailDepth mechanics work identically whether the underlying resources are source code repositories, technical documents, database schemas, or infrastructure configurations. **Critical Design Decision**: All indexing happens immediately when resources are added to projects or when code changes. There is no "on-demand" indexing during agent execution. This ensures that agents always have instant access to search capabilities without any indexing delays. The computational cost is paid once upfront, not repeatedly during agent operations. @@ -10166,16 +10167,135 @@ The system is designed around the hierarchical nature of plans: parent plans see The ACMS defines several data types that are used throughout the system by actors, skills, strategies, and the plan lifecycle. -##### DetailLevel +##### DetailDepth and DetailLevelMap -```python -class DetailLevel(Enum): - """How much content to include for each item in context.""" - SIGNATURE = "signature" # Declarations only (name, type, parameters) - SUMMARY = "summary" # LLM-generated or docstring condensation - STUB = "stub" # Signatures + key logic (control flow, returns) - FULL = "full" # Complete source content -``` +At the most general level (UKO Layer 0), detail depth is simply a **non-negative integer** — 0 being the most minimal representation and each increment revealing more. There is no fixed upper bound; the maximum meaningful depth depends on the domain and the complexity of the information unit. This is the `DetailDepth` type. + +Each UKO domain extension then registers a **DetailLevelMap** — a table of named labels mapped to specific integer depths. This allows domain users to work with meaningful names (like `MODULE_LISTING` or `TABLE_OF_CONTENTS`) rather than raw integers, while the underlying system always operates on the universal integer scale. Maps are inherited: a language-specific map includes all levels from its parent paradigm map, which includes all levels from the general code map. + +

+DetailDepth = int  # Non-negative integer, 0 = most minimal, no upper bound
+
+@dataclass
+class DetailLevelMap:
+    """Maps named detail levels to integer depths for a UKO domain.
+    Inherited: a child map includes all entries from its parent map,
+    and may insert additional levels at any integer position."""
+    domain: str                          # UKO namespace (e.g., "uko-code:", "uko-py:")
+    parent: DetailLevelMap | None         # Parent map to inherit from
+    levels: dict[str, int]               # Named level -> integer depth
+    max_depth: int                       # Maximum meaningful depth for this domain
+
+    def resolve(self, depth: int | str) -> int:
+        """Resolve a named level or integer to an integer depth."""
+        if isinstance(depth, int):
+            return min(depth, self.max_depth)
+        # Look up named level in this map, then parent maps
+        if depth in self.levels:
+            return self.levels[depth]
+        if self.parent:
+            return self.parent.resolve(depth)
+        raise ValueError(f"Unknown detail level: {depth}")
+
+ +**Universal (Layer 0) Semantics:** + +At the universal level, each integer depth has a domain-agnostic meaning. The principle is that depth 0 answers *"what exists?"*, and each subsequent depth answers progressively more detailed questions: + +| Depth | Universal Question Answered | What Gets Included | +|-------|-----------------------------|--------------------| +| 0 | *What exists?* | Just the name/identifier of the information unit. | +| 1 | *How is it organized?* | Names of immediate children (structural skeleton). | +| 2 | *What are the key relationships?* | Children + dependency/reference edges to other units. | +| 3 | *What is each thing's purpose?* | + Short descriptions/summaries for each child. | +| 4 | *What is the structural shape?* | + Type information, size/count metadata, categories. | +| 5+ | *How does it work? What does it say?* | Progressively more content, up to complete verbatim content at max depth. | +| max | *Everything.* | Complete content — nothing omitted. | + +The exact number of meaningful depths varies by domain (source code may have 12+ levels, a flat config file may only have 4). The system never forces content into a fixed number of buckets. + +**Source Code DetailLevelMap (`uko-code:`, extended by `uko-oo:`, `uko-py:`, etc.):** + +The general software domain defines a base set of named levels. Paradigm-specific and language-specific extensions insert additional levels where their semantics provide meaningful distinctions. + +| Depth | `uko-code:` Name | Content Shown | +|-------|-------------------|---------------| +| 0 | `MODULE_LISTING` | Module/package names only, no internal structure. | +| 1 | `MODULE_GRAPH` | Module names + inter-module dependency edges (imports graph). | +| 2 | `MEMBER_LISTING` | + Names of top-level members within each module (classes, functions, constants) — no signatures. | +| 3 | `MEMBER_SUMMARY` | + One-line docstring or LLM-generated summary for each member. | +| 4 | `SIGNATURES` | + Full type signatures (parameter names, types, return types) for all callables and type definitions. | +| 5 | `SIGNATURES_WITH_DOCS` | + Complete docstrings/comments attached to each member. | +| 6 | `STRUCTURAL_OUTLINE` | + Control flow structure within callable bodies (branches, loops, try/except) shown as outline, no expressions. | +| 7 | `KEY_LOGIC` | + Key expressions: return statements, assertions, assignments to important variables. | +| 8 | `NEAR_COMPLETE` | + All statements except comments, logging, and boilerplate (imports, `__all__`, etc.). | +| 9 | `FULL_SOURCE` | Complete source code — nothing omitted. | + +*Object-Oriented extension (`uko-oo:`) inserts:* + +| Depth | `uko-oo:` Name | Content Added | +|-------|-----------------|---------------| +| 2.5 → 3 | `CLASS_HIERARCHY` | Inheritance chains and interface implementation relationships between classes (inserted between `MEMBER_LISTING` and `MEMBER_SUMMARY`, shifting subsequent depths). | +| 5.5 → 6 | `VISIBILITY_ANNOTATED` | Public/protected/private modifiers on all members + abstract/final markers (inserted between `SIGNATURES_WITH_DOCS` and `STRUCTURAL_OUTLINE`). | + +*Python-specific extension (`uko-py:`) inserts:* + +| Depth | `uko-py:` Name | Content Added | +|-------|-----------------|---------------| +| 5.5 → 6 | `DECORATED_SIGNATURES` | `@property`, `@staticmethod`, `@classmethod`, custom decorator chains shown on each member. | +| 7.5 → 8 | `TYPE_STUBS` | Type annotations from `.pyi` stub files merged with source, `typing` module usage. | +| 10 | `WITH_TESTS` | Full source + associated test cases for each callable (from `uko-code:testsCallable` edges). | + +> **Note on fractional depths**: Fractional values like "2.5" are notational only — they indicate that the extension inserts a new named level between two existing levels, which shifts the integer assignments. The actual registered map uses consecutive integers. For example, when `uko-oo:` is active, what `uko-code:` calls depth 3 (`MEMBER_SUMMARY`) becomes depth 4 in the effective map because `CLASS_HIERARCHY` is inserted at depth 3. + +**Document DetailLevelMap (`uko-doc:`):** + +| Depth | `uko-doc:` Name | Content Shown | +|-------|-------------------|---------------| +| 0 | `TITLE_ONLY` | Document title / section heading only. | +| 1 | `TABLE_OF_CONTENTS_L1` | Title + top-level (depth-1) section/chapter headings. | +| 2 | `TABLE_OF_CONTENTS_L2` | + Second-level subsection headings. | +| 3 | `FULL_TOC` | Complete table of contents to all heading depths. | +| 4 | `TOC_WITH_SUMMARIES` | Full TOC + one-sentence abstract per section (LLM-generated or extracted from first paragraph). | +| 5 | `SECTION_OVERVIEWS` | + Topic keywords per section + cross-reference targets (which other sections this section discusses). | +| 6 | `TOPIC_SENTENCES` | + First sentence of every paragraph within each section. | +| 7 | `PARAGRAPH_SUMMARIES` | + LLM-generated summary for each paragraph (2-3 sentences compressed to 1). | +| 8 | `STRUCTURAL_DETAIL` | + All figure/table captions + code block headers + list item first lines + blockquote sources. | +| 9 | `NEAR_COMPLETE` | + Full paragraph text, but with inline formatting stripped and code blocks truncated to first/last 3 lines. | +| 10 | `FULL_CONTENT` | Complete document content — all text, formatting, code blocks, figures, footnotes. | + +**Database DetailLevelMap (`uko-data:`):** + +| Depth | `uko-data:` Name | Content Shown | +|-------|-------------------|---------------| +| 0 | `SCHEMA_LISTING` | Schema/database names only. | +| 1 | `TABLE_LISTING` | + Table and view names within each schema. | +| 2 | `COLUMN_LISTING` | + Column names within each table (no types). | +| 3 | `TYPED_COLUMNS` | + Column data types + nullability. | +| 4 | `CONSTRAINTS` | + Primary keys, unique constraints, check constraints, defaults. | +| 5 | `RELATIONSHIPS` | + Foreign key relationships (full referential graph between tables). | +| 6 | `INDEXES_AND_STATS` | + Index definitions + estimated row counts + basic statistics (cardinality, avg row size). | +| 7 | `DDL` | Full CREATE TABLE / CREATE VIEW DDL (reconstructed from metadata). | +| 8 | `DDL_WITH_TRIGGERS` | + Trigger definitions + stored procedure signatures that reference each table. | +| 9 | `FULL_PROCEDURES` | + Complete stored procedure and function bodies. | +| 10 | `WITH_SAMPLE_DATA` | + Sample rows (configurable N, default 5) for each table. | +| 11 | `FULL_CATALOG` | Complete catalog: DDL + all procedure bodies + triggers + sample data + value distribution histograms + query plan statistics. | + +**Infrastructure DetailLevelMap (`uko-infra:`):** + +| Depth | `uko-infra:` Name | Content Shown | +|-------|---------------------|---------------| +| 0 | `SERVICE_LISTING` | Service/component names only. | +| 1 | `SERVICE_GRAPH` | + Service dependency edges (which services connect to which). | +| 2 | `ENDPOINT_LISTING` | + Endpoint paths/ports for each service. | +| 3 | `ENDPOINT_DETAIL` | + HTTP methods, parameters, authentication requirements per endpoint. | +| 4 | `CONFIG_KEYS` | + Configuration key names and their sections. | +| 5 | `CONFIG_VALUES` | + Configuration values (with secrets masked). | +| 6 | `RESOURCE_LIMITS` | + Resource allocations (CPU, memory, replicas, storage). | +| 7 | `FULL_CONFIG` | Complete configuration files for each service. | +| 8 | `WITH_DEPLOYMENT` | + Deployment descriptors (Dockerfiles, Kubernetes manifests, Compose files). | + +**How depth resolution works in practice**: When a context request specifies `depth="SIGNATURES"` and the target node is a `uko-py:Module`, the system looks up `SIGNATURES` in the `uko-py:` DetailLevelMap first. If found, it uses that integer. If not, it walks up to `uko-oo:`, then `uko-code:`, then `uko:` until it finds a match. If the request specifies `depth=4` (a raw integer), it is used directly — the system renders the target node at integer depth 4 regardless of what named level that corresponds to. ##### ContextRequest @@ -10198,8 +10318,10 @@ class ContextRequest: breadth: int = 2 # How many hops outward in the dependency/reference graph. - depth: DetailLevel = DetailLevel.SUMMARY + depth: int | str = 3 # How much detail to include for each item found. + # May be a raw integer (0-N) or a named level string (e.g., "SIGNATURES") + # resolved via the active DetailLevelMap for the target node's UKO type. # === Focus depth gradient === depth_gradient: bool = True @@ -10230,7 +10352,7 @@ class ContextFragment: """A single piece of context assembled by a strategy.""" uko_node: str # UKO URI of the source node content: str # Rendered text content - detail_level: DetailLevel # Level of detail in this fragment + detail_depth: int # Resolved integer depth of this fragment token_count: int # Token count of content relevance_score: float # 0.0-1.0 relevance to the request provenance: FragmentProvenance # Trace back to resource + location @@ -10285,9 +10407,9 @@ skill: description: "Specific files, classes, or functions to focus on" } breadth: { type: integer, default: 2, description: "How many dependency hops outward (0-5)" } - depth: { type: string, enum: ["signature", "summary", "stub", "full"], - default: "summary", - description: "How much detail for each item" } + depth: { oneOf: [{ type: integer, minimum: 0 }, { type: string }], + default: 3, + description: "Detail depth — integer (0-N) or named level from the active DetailLevelMap (e.g., 'SIGNATURES', 'FULL_SOURCE')" } purpose: { type: string, description: "Why do you need this context?" } required: [purpose] @@ -10380,98 +10502,184 @@ enabled = ["simple-keyword", "semantic-embedding", "arce", "breadth-depth-naviga #### Hierarchical Plan Context -In a plan hierarchy, each level sees a different slice of the codebase. Context inheritance flows parent-to-child with progressive focusing: +In a plan hierarchy, each level sees a different slice of the project's resources. Context inheritance flows parent-to-child with progressive focusing. This applies universally across all UKO domains — the same breadth/depth mechanics work for codebases, documents, databases, and infrastructure. + +**Source Code Example:** | Level | Breadth | Depth | Example Content | |-------|---------|-------|-----------------| -| Root | Entire project | SIGNATURE | Module names, class headers, dependency map | -| Subplan A | `src/auth/` module + direct deps | SUMMARY | Function signatures with descriptions, key type definitions | -| Sub-subplan A1 | `AuthManager` class + 2-hop deps | FULL | Complete function bodies, all parameters, all call sites | +| Root | Entire project | 0 (`MODULE_LISTING`) | Module names, dependency graph edges | +| Subplan A | `src/auth/` module + direct deps | 4 (`SIGNATURES`) | Function signatures with types, class inheritance chains | +| Sub-subplan A1 | `AuthManager` class + 2-hop deps | 9 (`FULL_SOURCE`) | Complete function bodies, all parameters, all call sites | -The **skeleton** is a compact, SIGNATURE-level representation of the parent's context window that is passed to every child. This ensures children always have the "big picture" available, even though they focus on a narrow area. The skeleton typically consumes 5-15% of the child's token budget (controlled by `skeleton_ratio`). +**Document Example** (e.g., a technical specification): + +| Level | Breadth | Depth | Example Content | +|-------|---------|-------|-----------------| +| Root | Entire document | 1 (`TABLE_OF_CONTENTS_L1`) | Document title + top-level chapter headings | +| Subplan A | "Architecture" chapter + sections that `discussesTopic` it | 5 (`SECTION_OVERVIEWS`) | Section headings + topic keywords + cross-reference targets + one-sentence abstracts | +| Sub-subplan A1 | "ACMS Architecture" section + 2-hop topic references | 10 (`FULL_CONTENT`) | Complete section text with all paragraphs, figures, code blocks | + +**Database Example** (e.g., schema migration planning): + +| Level | Breadth | Depth | Example Content | +|-------|---------|-------|-----------------| +| Root | Entire database | 1 (`TABLE_LISTING`) | Schema names + table and view names | +| Subplan A | `auth` schema + tables with foreign keys into it | 5 (`RELATIONSHIPS`) | Table names + typed columns + constraints + foreign key graph | +| Sub-subplan A1 | `users` table + dependent views and stored procedures | 9 (`FULL_PROCEDURES`) | Complete DDL + triggers + stored procedure bodies + sample data | + +The **skeleton** is a compact, low-depth representation (typically depth 0-1) of the parent's context window that is passed to every child. This ensures children always have the "big picture" available, even though they focus on a narrow area. The skeleton typically consumes 5-15% of the child's token budget (controlled by `skeleton_ratio`). For a source code resource, the skeleton is a `MODULE_LISTING` (depth 0) — just module names. For a document resource, the skeleton is a `TABLE_OF_CONTENTS_L1` (depth 1) — the table of contents. For a database resource, it is a `TABLE_LISTING` (depth 1) — schema and table names. #### Depth/Breadth Projection The depth/breadth projection system allows fine-grained control over how much of the knowledge graph is materialized into context. It operates on the UKO graph structure. - **Breadth** (integer, 0-N): How many hops in the `uko:references` / `uko:dependsOn` / `uko:contains^-1` graph to traverse from the focus items. -- **Depth** (DetailLevel): How much content to include for each item found. +- **Depth** (integer or named level): How much content to include for each item found. Specified as a raw integer or a named level resolved via the active DetailLevelMap. - **Depth gradient**: When enabled, detail decreases with distance from focus. -``` -Request: focus=["class://AuthManager"], breadth=2, depth=FULL, gradient=True +**Source Code Projection Example:** -Result (token costs approximate): +

+Request: focus=["class://AuthManager"], breadth=2, depth=9 (FULL_SOURCE), gradient=True
 
-Distance 0 (FULL detail):
-  class AuthManager:                               # 800 tokens
-      """Manages user authentication..."""
-      def authenticate(self, username, password):
+Result (token costs approximate):
+
+Distance 0 — depth 9 (FULL_SOURCE):
+  class AuthManager:                               # 800 tokens
+      """Manages user authentication..."""
+      def authenticate(self, username, password):
           ...full body...
-      def validate_token(self, token):
+      def validate_token(self, token):
           ...full body...
 
-Distance 1 (STUB detail):
-  class BaseManager:                               # 120 tokens
-      def connect(self) -> Connection: ...
-      def disconnect(self) -> None: ...
-  class CryptoUtils:                               # 80 tokens
-      def hash_password(pwd: str) -> str: ...
-      def verify_hash(pwd: str, hash: str) -> bool: ...
-  class UserDB:                                    # 100 tokens
-      def find_user(username: str) -> User | None: ...
-      def create_user(user: User) -> None: ...
+Distance 1 — depth 4 (SIGNATURES):
+  class BaseManager:                               # 120 tokens
+      def connect(self) -> Connection: ...
+      def disconnect(self) -> None: ...
+  class CryptoUtils:                               # 80 tokens
+      def hash_password(pwd: str) -> str: ...
+      def verify_hash(pwd: str, hash: str) -> bool: ...
+  class UserDB:                                    # 100 tokens
+      def find_user(username: str) -> User | None: ...
+      def create_user(user: User) -> None: ...
 
-Distance 2 (SIGNATURE detail):
-  class Connection                                 # 20 tokens
-  class User                                       # 15 tokens
-  class DatabasePool                               # 15 tokens
+Distance 2 — depth 0 (MODULE_LISTING):
+  class Connection                                 # 20 tokens
+  class User                                       # 15 tokens
+  class DatabasePool                               # 15 tokens
 
-Total: ~1,150 tokens (vs ~15,000 if everything were FULL)
-```
+Total: ~1,150 tokens (vs ~15,000 if everything were depth 9)
+
+ +**Document Projection Example:** + +

+Request: focus=["uko-doc:section/security-architecture"], breadth=2, depth=10 (FULL_CONTENT), gradient=True
+
+Result (token costs approximate):
+
+Distance 0 — depth 10 (FULL_CONTENT):
+  ## 5. Security Architecture                      # 2,400 tokens
+      Complete section text including all paragraphs,
+      code examples, diagrams, and subsections:
+      5.1 Authentication Flow
+      5.2 Authorization Model
+      5.3 Token Management
+
+Distance 1 — depth 6 (TOPIC_SENTENCES — sections that discuss security topics):
+  ## 3. API Design                                  # 180 tokens
+      Section headings + first sentence of each paragraph:
+      "The API uses JWT tokens for authentication..."
+      "Rate limiting is enforced per-client..."
+  ## 8. Deployment                                   # 120 tokens
+      "TLS termination occurs at the load balancer..."
+      "Secrets are injected via Vault..."
+
+Distance 2 — depth 0 (TITLE_ONLY — sections referenced by distance-1 sections):
+  ## 2. System Overview                              # 30 tokens
+  ## 9. Monitoring                                   # 25 tokens
+  ## Appendix A: Threat Model                        # 20 tokens
+
+Total: ~2,775 tokens (vs ~18,000 if the entire document were depth 10)
+
+ +**Database Projection Example:** + +

+Request: focus=["uko-data:table/auth.users"], breadth=2, depth=11 (FULL_CATALOG), gradient=True
+
+Result (token costs approximate):
+
+Distance 0 — depth 11 (FULL_CATALOG):
+  CREATE TABLE auth.users (                        # 650 tokens
+      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+      email VARCHAR(255) UNIQUE NOT NULL,
+      password_hash VARCHAR(60) NOT NULL,
+      ...complete DDL + triggers + sample rows + statistics...
+  );
+
+Distance 1 — depth 7 (DDL — tables with foreign keys to/from users):
+  CREATE TABLE auth.sessions (                     # 180 tokens
+      id UUID PRIMARY KEY,
+      user_id UUID REFERENCES auth.users(id),
+      ...DDL with constraints...
+  );
+  CREATE TABLE auth.roles (                         # 120 tokens
+      ...DDL with constraints...
+  );
+  CREATE VIEW auth.active_users AS ...             # 90 tokens
+
+Distance 2 — depth 1 (TABLE_LISTING — tables referenced by distance-1 tables):
+  auth.permissions                                  # 20 tokens
+  auth.audit_log                                    # 15 tokens
+  public.organizations                              # 15 tokens
+
+Total: ~1,090 tokens (vs ~8,500 if the entire schema were depth 11)
+
#### Integration with Plan Lifecycle -``` -Plan Lifecycle ACMS Actions -───────────────── ──────────────────────────── -Plan created (agents plan use) ResourceScope resolved. +

+Plan Lifecycle                        ACMS Actions
+─────────────────                     ────────────────────────────
+Plan created (agents plan use)        ResourceScope resolved.
                                       ScopedBackendViews created.
 
-Strategize phase begins               InitialContextAssembler runs:
+Strategize phase begins               InitialContextAssembler runs:
                                         - Inherits parent context (if subplan)
                                         - Runs StrategyCoordinator
                                         - Produces AssembledContext
                                         - Injects into actor's system prompt
 
-Strategy actor reasons                 Actor may issue ContextRequests via
+Strategy actor reasons                 Actor may issue ContextRequests via
                                        builtin/context skill.
                                        Each request triggers re-assembly
                                        with remaining budget.
 
-Strategy actor produces decisions      Each Decision's context_snapshot
+Strategy actor produces decisions      Each Decision's context_snapshot
                                        captures AssembledContext hash +
                                        provenance map.
 
-Execute phase begins                   New InitialContextAssembler run
+Execute phase begins                   New InitialContextAssembler run
                                        with execute-phase view.
                                        Decisions from Strategize are in
                                        warm tier.
 
-Execution actor works                  Dynamic ContextRequests as needed.
+Execution actor works                  Dynamic ContextRequests as needed.
 
-Subplan spawned                        PlanContextInheritance computes
+Subplan spawned                        PlanContextInheritance computes
                                        child context from parent.
                                        Skeleton propagation.
                                        New ResourceScope (possibly narrower).
 
-Apply phase                            Minimal context assembly
+Apply phase                            Minimal context assembly
                                        (validation results, diff summary).
 
-Plan completes                         Hot context archived to warm.
+Plan completes                         Hot context archived to warm.
                                        Warm context ages to cold based
                                        on retention policy.
-```
+
### Output Rendering Framework @@ -17581,19 +17789,22 @@ The following is the formal [JSON Schema](https://json-schema.org/) definition f "description": "Default number of hops from focus nodes in the UKO graph for context expansion. 0 = focus nodes only." }, "default_depth": { - "type": "string", - "enum": ["SIGNATURE", "SUMMARY", "STUB", "FULL"], - "default": "SUMMARY", - "description": "Default detail level for context fragments. SIGNATURE = declarations only; SUMMARY = condensed overview; STUB = signatures + key logic; FULL = complete content." + "oneOf": [ + { "type": "integer", "minimum": 0 }, + { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$" } + ], + "default": 3, + "description": "Default detail depth for context fragments. May be a non-negative integer or a named level string from the active domain's DetailLevelMap (e.g., 'SIGNATURES', 'FULL_SOURCE'). Named levels are resolved to integers via the DetailLevelMap inheritance chain. Default: 3." }, "depth_gradient": { "type": "object", - "properties": { - "0": { "type": "string", "enum": ["SIGNATURE", "SUMMARY", "STUB", "FULL"] }, - "1": { "type": "string", "enum": ["SIGNATURE", "SUMMARY", "STUB", "FULL"] }, - "2": { "type": "string", "enum": ["SIGNATURE", "SUMMARY", "STUB", "FULL"] } + "additionalProperties": { + "oneOf": [ + { "type": "integer", "minimum": 0 }, + { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$" } + ] }, - "description": "Per-hop detail level overrides. Key is the hop distance (0 = focus node), value is the DetailLevel. Hops not listed use default_depth." + "description": "Per-hop detail depth overrides. Key is the hop distance (0 = focus node), value is an integer depth or named level string. Hops not listed use default_depth." }, "skeleton_ratio": { "type": "number", @@ -17662,11 +17873,11 @@ The following annotated YAML provides an easier-to-read overview of the same sch - semantic-embedding - breadth-depth-navigator default_breadth: <integer> # Default hop count for UKO graph expansion (optional, default: 2) -default_depth: SIGNATURE | SUMMARY | STUB | FULL # Default detail level (optional, default: SUMMARY) -depth_gradient: # Per-hop detail level overrides (optional) - 0: FULL # Focus nodes get full content - 1: SUMMARY # 1-hop neighbors get summaries - 2: SIGNATURE # 2-hop neighbors get signatures only +default_depth: 3 # Default detail depth — integer or named level (optional, default: 3) +depth_gradient: # Per-hop detail depth overrides (optional) + 0: 9 # Focus nodes get depth 9 (FULL_SOURCE for code) + 1: 4 # 1-hop neighbors get depth 4 (SIGNATURES for code) + 2: 0 # 2-hop neighbors get depth 0 (MODULE_LISTING for code) skeleton_ratio: <float> # Fraction of budget for inherited plan skeleton (optional, default: 0.15) temporal_scope: current | recent | all # Temporal scope for UKO node resolution (optional, default: current) auto_refresh: true # Auto re-assemble context on budget change (optional, default: true) @@ -17694,8 +17905,8 @@ The following annotated YAML provides an easier-to-read overview of the same sch | `summary_max_tokens` | integer | No | Maximum tokens for each generated summary. Only applies when `summarize` is `true`. | | `strategy` | list | No | Ordered list of ACMS context strategies to use for this view. Overrides the global `context.strategies.enabled` list. Built-in strategies: `simple-keyword`, `semantic-embedding`, `breadth-depth-navigator`, `arce`, `temporal-archaeology`, `plan-decision-context`. | | `default_breadth` | integer | No | Default number of hops from focus nodes in the UKO graph for context expansion. `0` = focus nodes only. Default: `2`. | -| `default_depth` | string | No | Default detail level for context fragments: `SIGNATURE`, `SUMMARY`, `STUB`, or `FULL`. Default: `SUMMARY`. | -| `depth_gradient` | object | No | Per-hop detail level overrides. Keys are hop distances (0 = focus node), values are `DetailLevel` enums. Hops not listed use `default_depth`. | +| `default_depth` | integer or string | No | Default detail depth for context fragments. Accepts a non-negative integer or a named level string from the active domain's DetailLevelMap (e.g., `SIGNATURES`, `FULL_SOURCE`). Default: `3`. | +| `depth_gradient` | object | No | Per-hop detail depth overrides. Keys are hop distances (0 = focus node), values are integers or named level strings. Hops not listed use `default_depth`. | | `skeleton_ratio` | number | No | Fraction of context budget reserved for inherited plan skeleton context. Range: 0.0–1.0. Default: `0.15`. | | `temporal_scope` | string | No | Temporal scope for UKO node resolution: `current` (only `isCurrent` nodes), `recent` (current + warm retention window), `all` (include historical versions). Default: `current`. | | `auto_refresh` | boolean | No | When `true`, ACMS automatically re-assembles context when the available budget changes by more than the refresh threshold. Default: `true`. | @@ -24466,11 +24677,11 @@ Both modes share the same domain model and application layer. The infrastructure #### High-Level Component Diagram -``` +

 ┌─────────────────────────────────────────────────────────────────────────────┐
-│                          Presentation Layer                                  │
+│                          Presentation Layer                                  │
 │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌──────────────┐  ┌────────────┐  │
-│  │   CLI   │  │   TUI   │  │   Web   │  │  IDE Plugin  │  │  REST API  │  │
+│  │   CLI   │  │   TUI   │  │   Web   │  │  IDE Plugin  │  │  REST API  │  │
 │  │ (Typer) │  │(Textual)│  │(Textual │  │  (Language   │  │ (uvicorn/  │  │
 │  │         │  │         │  │  Web)   │  │   Server)    │  │  FastAPI)  │  │
 │  └────┬────┘  └────┬────┘  └────┬────┘  └──────┬───────┘  └─────┬──────┘  │
@@ -24478,9 +24689,9 @@ Both modes share the same domain model and application layer. The infrastructure
 │       └────────────┴────────────┴───────────────┴────────────────┘          │
 │                                    │                                         │
 ├────────────────────────────────────┼─────────────────────────────────────────┤
-│                          Application Layer                                   │
+│                          Application Layer                                   │
 │  ┌────────────────────┐  ┌─────────────────────┐  ┌──────────────────────┐  │
-│  │  Service Facade    │  │  Workflow Engine     │  │  Event Bus           │  │
+│  │ Service Facade    │  │ Workflow Engine     │  │ Event Bus           │  │
 │  │  ┌──────────────┐  │  │  ┌───────────────┐  │  │  ┌────────────────┐  │  │
 │  │  │PlanService   │  │  │  │PlanLifecycle  │  │  │  │StructuredLog   │  │  │
 │  │  │ProjectService│  │  │  │SessionWorkflow│  │  │  │EventEmitter    │  │  │
@@ -24493,13 +24704,13 @@ Both modes share the same domain model and application layer. The infrastructure
 │  └────────────────────┘                                                      │
 │       │                                                                      │
 │  ┌────────────────────────────────────────────────────────────────────────┐  │
-│  │  DI Container (dependency-injector DeclarativeContainer)               │  │
+│  │  DI Container (dependency-injector DeclarativeContainer)               │  │
 │  └────────────────────────────────────────────────────────────────────────┘  │
 │                                    │                                         │
 ├────────────────────────────────────┼─────────────────────────────────────────┤
-│                            Domain Layer                                      │
+│                            Domain Layer                                      │
 │  ┌──────────────────────┐  ┌─────────────────────┐  ┌────────────────────┐  │
-│  │  Domain Models       │  │  Domain Services     │  │  Domain Events     │  │
+│  │ Domain Models       │  │ Domain Services     │  │ Domain Events     │  │
 │  │  ┌────────────────┐  │  │  ┌───────────────┐  │  │  ┌──────────────┐  │  │
 │  │  │Plan            │  │  │  │InvariantEnfrc │  │  │  │PlanCreated   │  │  │
 │  │  │Decision        │  │  │  │AutonomyCtrl  │  │  │  │PhaseChanged  │  │  │
@@ -24517,9 +24728,9 @@ Both modes share the same domain model and application layer. The infrastructure
 │  └──────────────────────┘                                                    │
 │                                    │                                         │
 ├────────────────────────────────────┼─────────────────────────────────────────┤
-│                         Infrastructure Layer                                 │
+│                         Infrastructure Layer                                 │
 │  ┌──────────────┐ ┌─────────────┐ ┌──────────────┐ ┌──────────────────────┐│
-│  │  Database     │ │  Indexing    │ │  Sandbox     │ │  LLM / AI Runtime   ││
+│  │ Database     │ │ Indexing    │ │ Sandbox     │ │ LLM / AI Runtime   ││
 │  │  ┌────────┐  │ │  ┌───────┐  │ │  ┌────────┐  │ │  ┌──────────────┐   ││
 │  │  │SQLite  │  │ │  │Tantivy│  │ │  │GitWrktree│ │ │  │LangChain     │   ││
 │  │  │SQLAlch.│  │ │  │FAISS  │  │ │  │FsCopy   │  │ │  │LangGraph     │   ││
@@ -24529,7 +24740,7 @@ Both modes share the same domain model and application layer. The infrastructure
 │  └──────────────┘ │  └───────┘  │ └──────────────┘ │  └──────────────┘   ││
 │                   └─────────────┘                   └──────────────────────┘│
 │  ┌───────────────────────┐ ┌────────────────────────────────────────────┐   │
-│  │  External Integrations│ │  File System / OS                          │   │
+│  │ External Integrations│ │ File System / OS                          │   │
 │  │  ┌─────────────────┐  │ │  ┌──────────┐ ┌──────────┐ ┌───────────┐ │   │
 │  │  │MCP Servers      │  │ │  │Watchdog  │ │Git CLI   │ │OS Process │ │   │
 │  │  │Agent Skills Std │  │ │  │File I/O  │ │Subprocess│ │Signals    │ │   │
@@ -24537,7 +24748,7 @@ Both modes share the same domain model and application layer. The infrastructure
 │  │  └─────────────────┘  │ └────────────────────────────────────────────┘   │
 │  └───────────────────────┘                                                   │
 └─────────────────────────────────────────────────────────────────────────────┘
-```
+
#### Architectural Principles @@ -24555,8 +24766,8 @@ Both modes share the same domain model and application layer. The infrastructure The following diagram traces data flow through the system during a complete plan lifecycle: -``` -User CLI Application Domain Infrastructure +

+User                CLI              Application         Domain            Infrastructure
  │                   │                   │                  │                    │
  │  plan use         │                   │                  │                    │
  │──────────────────>│                   │                  │                    │
@@ -24578,7 +24789,7 @@ User                CLI              Application         Domain            Infra
  │                   │                   │  .should_proceed │                    │
  │                   │                   │─────────────────>│                    │
  │                   │                   │                  │                    │
- │                   │                   │  [if auto]       │                    │
+ │                   │                   │  [if auto]       │                    │
  │                   │                   │  StrategyActor   │                    │
  │                   │                   │  .invoke()       │                    │
  │                   │                   │─────────────────>│                    │
@@ -24603,7 +24814,7 @@ User                CLI              Application         Domain            Infra
  │                   │                   │                  │  .save_batch()     │
  │                   │                   │                  │───────────────────>│
  │                   │                   │                  │                    │
- │                   │                   │  [Execute phase] │                    │
+ │                   │                   │  [Execute phase] │                    │
  │                   │                   │  SandboxManager  │                    │
  │                   │                   │  .create()       │                    │
  │                   │                   │─────────────────>│                    │
@@ -24621,7 +24832,7 @@ User                CLI              Application         Domain            Infra
  │                   │                   │  ChangeSet       │                    │
  │                   │                   │<─────────────────│                    │
  │                   │                   │                  │                    │
- │                   │                   │  [Apply phase]   │                    │
+ │                   │                   │  [Apply phase]   │                    │
  │                   │                   │  Validation      │                    │
  │                   │                   │  .run_all()      │                    │
  │                   │                   │─────────────────>│                    │
@@ -24635,9 +24846,9 @@ User                CLI              Application         Domain            Infra
  │                   │                   │                  │  git merge         │
  │                   │                   │                  │───────────────────>│
  │                   │                   │                  │                    │
- │  ✓ OK Applied     │                  │                  │                    │
+ │  ✓ OK Applied     │                  │                  │                    │
  │<──────────────────│                   │                  │                    │
-```
+
### Technical Stack @@ -24750,17 +24961,17 @@ This section provides the complete architectural design of the Advanced Context #### Architectural Overview -``` +

                                   +-------------------------------+
-                                  |        Actor / Skill          |
+                                  |     Actor / Skill          |
                                   |  (issues ContextRequests via  |
                                   |   Context Request Protocol)   |
                                   +---------------+---------------+
                                                   |
                                                   v
                                   +-------------------------------+
-                                  |     Strategy Coordinator      |
-                                  |        & Fusion Engine        |
+                                  |   Strategy Coordinator      |
+                                  |      & Fusion Engine        |
                                   |  (merges results from all     |
                                   |   active strategies, dedupes, |
                                   |   fits to token budget)       |
@@ -24770,24 +24981,24 @@ This section provides the complete architectural design of the Advanced Context
                           |                 |         |                  |
                           v                 v         v                  v
                    +-----------+    +-----------+ +-----------+  +-----------+
-                   | Strategy  |    | Strategy  | | Strategy  |  | Strategy  |
-                   |   ARCE    |    |  Simple   | | Breadth/  |  |  Custom   |
-                   | (graph-   |    | (keyword/ | | Depth     |  | (user-    |
-                   |  aware)   |    |  embed)   | | Navigator |  |  defined) |
+                   | Strategy  |    | Strategy  | | Strategy  |  | Strategy  |
+                   |   ARCE    |    |  Simple   | | Breadth/  |  |  Custom   |
+                   | (graph-   |    | (keyword/ | | Depth     |  | (user-    |
+                   |  aware)   |    |  embed)   | | Navigator |  |  defined) |
                    +-----------+    +-----------+ +-----------+  +-----------+
                           |              |             |                |
                           v              v             v                v
                    +----------------------------------------------------------+
-                   |              Backend Abstraction Layer (BAL)              |
+                   |           Backend Abstraction Layer (BAL)              |
                    |  +------------+  +------------+  +-------------------+   |
                    |  | ScopedView |  | ScopedView |  |    ScopedView     |   |
-                   |  | (Text DB)  |  | (Vector DB)|  |    (Graph DB)     |   |
+                   |  | (Text DB)  |  | (Vector DB)|  |    (Graph DB)     |   |
                    |  +-----+------+  +-----+------+  +--------+----------+  |
                    +--------|---------------|-------------------|-------------+
                             |               |                   |
                             v               v                   v
                    +----------------------------------------------------------+
-                   |               Physical Data Stores                       |
+                   |               Physical Data Stores                       |
                    |  +-----------+  +-----------+  +---------------------+   |
                    |  | Tantivy / |  | FAISS /   |  | Blazegraph / Jena / |   |
                    |  | SQLite    |  | Qdrant /  |  | Neo4j / Stardog     |   |
@@ -24797,10 +25008,10 @@ This section provides the complete architectural design of the Advanced Context
                                               |
                                               v
                    +----------------------------------------------------------+
-                   |                  Resource Registry                       |
+                   |                  Resource Registry                       |
                    |        (physical/virtual resources, DAG links)           |
                    +----------------------------------------------------------+
-```
+
**Key Design Principles:** @@ -24822,12 +25033,12 @@ The UKO is designed around a single principle: **everything that an actor might The ontology uses an inheritance hierarchy so that: -- **Layer 0** defines universal concepts that apply to any information (code, docs, data, infra). -- **Layer 1** specializes for general software concepts (modules, callables, types). -- **Layer 2** specializes for paradigm-specific concepts (OO, functional, procedural). -- **Layer 3** specializes for language-specific concepts (Python's decorators, TypeScript's interfaces, Rust's lifetimes). +- **Layer 0** defines universal concepts that apply to any information (code, docs, data, infra). DetailDepth is defined here as a non-negative integer with domain-agnostic semantics: depth 0 is the most minimal representation (just a name/identifier), and each increment reveals progressively more structure, content, and relationships. There is no fixed upper bound — the maximum meaningful depth depends on the domain. +- **Layer 1** specializes for domain-specific concepts: general software (`uko-code:` — modules, callables, types), documents (`uko-doc:` — sections, paragraphs, citations), data schemas (`uko-data:` — tables, columns, constraints), and infrastructure (`uko-infra:` — services, endpoints, config). Each domain registers a DetailLevelMap that assigns named labels to specific integer depths (e.g., `uko-code:` maps `MODULE_LISTING` → 0, `SIGNATURES` → 4, `FULL_SOURCE` → 9). +- **Layer 2** specializes for paradigm/format-specific concepts within a domain: object-oriented (`uko-oo:`), functional (`uko-func:`), procedural (`uko-proc:`) for code. Future extensions could add academic vs. technical for documents, or relational vs. graph for databases. Each paradigm extends its parent domain's DetailLevelMap, potentially inserting new named levels between existing ones (which shifts subsequent integer assignments). +- **Layer 3** specializes for technology-specific concepts: Python (`uko-py:`), TypeScript (`uko-ts:`), Rust (`uko-rs:`), Java (`uko-java:`), and potentially Markdown, PostgreSQL, or others. Language/technology-specific DetailLevelMap extensions are added only when they provide meaningful additional semantics beyond the paradigm level. -This layering means a strategy that operates at Layer 0 can work with *any* resource, while a strategy that operates at Layer 3 can provide language-specific intelligence. The `breadth-depth-navigator` strategy typically operates at Layers 0-1 (universal graph traversal), while `arce` leverages all layers. +This layering means a strategy that operates at Layer 0 can work with *any* resource — code, documents, databases, infrastructure — while a strategy that operates at Layer 3 can provide language-specific or technology-specific intelligence. The `breadth-depth-navigator` strategy typically operates at Layers 0-1 (universal graph traversal), while `arce` leverages all layers. DetailDepth resolution follows the DetailLevelMap inheritance chain: when a named level is requested, the system looks up the name in the most specific map available for the target UKO node type (e.g., `uko-py:` first), then walks up to the parent map (`uko-oo:` → `uko-code:` → `uko:`) until a match is found. When a raw integer is specified, it is used directly. ##### Ontology Hierarchy @@ -24895,20 +25106,20 @@ uko:dependsOn a owl:ObjectProperty ; rdfs:comment "Strong dependency (e.g., import, inheritance, call)." . # ── Content Properties ──────────────────────────────────────────── -uko:hasSignature a owl:DatatypeProperty ; +uko:hasRendering a owl:DatatypeProperty ; rdfs:domain uko:InformationUnit ; rdfs:range xsd:string ; - rdfs:comment "SIGNATURE-level rendering of this node." . + rdfs:comment "A rendered text representation of this node at a specific detail depth. Multiple renderings at different depths may exist for the same node. The depth is indicated by the associated uko:renderingDepth value." . -uko:hasSummary a owl:DatatypeProperty ; +uko:renderingDepth a owl:DatatypeProperty ; rdfs:domain uko:InformationUnit ; - rdfs:range xsd:string ; - rdfs:comment "SUMMARY-level rendering of this node." . + rdfs:range xsd:nonNegativeInteger ; + rdfs:comment "The integer detail depth at which the associated uko:hasRendering was produced. Paired with uko:hasRendering via a blank node or reification." . -uko:hasContent a owl:DatatypeProperty ; +uko:hasFullContent a owl:DatatypeProperty ; rdfs:domain uko:InformationUnit ; rdfs:range xsd:string ; - rdfs:comment "FULL-level rendering of this node." . + rdfs:comment "Shorthand for the maximum-depth rendering of this node (complete, unabridged content). Equivalent to uko:hasRendering at the domain's maximum depth." . # ── Provenance ──────────────────────────────────────────────────── uko:sourceResource a owl:ObjectProperty ; @@ -25031,52 +25242,415 @@ uko-func:Monad a owl:Class ; rdfs:subClassOf uko-code:TypeDefinition . ``` -**Non-Code Domains**: +**Code DetailLevelMap Refinements by Paradigm and Language**: + +The authoritative DetailLevelMap definitions — with full integer depth assignments and named level descriptions for each domain — are specified in **Core Concepts > Advanced Context Management System (ACMS) > Core Data Types > DetailDepth and DetailLevelMap**. The tables below show how paradigm-specific (Layer 2) and language-specific (Layer 3) UKO node types map their content at selected depth levels from the parent domain's map. These are illustrative excerpts showing what content each node type contributes at key depths, not exhaustive depth-by-depth definitions. + +*General Software (`uko-code:`) — Layer 1 (per-type rendering at selected depths):* + +| Depth | Named Level | `uko-code:Module` | `uko-code:Callable` | `uko-code:TypeDefinition` | +|-------|-------------|---------------------|----------------------|----------------------------| +| 0 | `MODULE_LISTING` | Module name only | — (not individually listed) | — (not individually listed) | +| 2 | `MEMBER_LISTING` | + names of top-level members | Function name (no signature) | Type name + kind (class/struct/enum) | +| 4 | `SIGNATURES` | + all top-level signatures | Name + parameter types + return type | Name + field types + method signatures | +| 6 | `STRUCTURAL_OUTLINE` | + control flow outline of callables | Signature + control flow outline (branches, loops) | Name + all field + method signatures + inheritance | +| 9 | `FULL_SOURCE` | Complete module source | Complete function body | Complete type definition | + +*Object-Oriented (`uko-oo:`) — Layer 2 (per-type rendering at selected depths):* + +| Depth | Named Level | `uko-oo:Class` | `uko-oo:Method` | `uko-oo:Interface` | +|-------|-------------|-----------------|------------------|--------------------| +| 2 | `MEMBER_LISTING` | Class name + parent classes | Method name + visibility | Interface name | +| 3 | `CLASS_HIERARCHY` (OO-inserted) | + inheritance chain + interface implementations | — | + method signatures | +| 4 | `SIGNATURES` | + attribute types + method signatures | + params + return type + visibility | + all method signatures with param types | +| 5 | `SIGNATURES_WITH_DOCS` | + class docstring + attribute descriptions | + docstring + side effect hints | + description + implementor count | +| 9+ | `FULL_SOURCE` | Complete class definition | Complete method body | Complete interface definition | + +*Functional (`uko-func:`) — Layer 2 (per-type rendering at selected depths):* + +| Depth | Named Level | `uko-func:PureFunction` | `uko-func:TypeClass` | `uko-func:Monad` | +|-------|-------------|--------------------------|----------------------|-------------------| +| 2 | `MEMBER_LISTING` | Function name | Type class name | Monad name | +| 4 | `SIGNATURES` | Name + type signature + purity annotation | Name + associated types | Name + bind/return types | +| 6 | `STRUCTURAL_OUTLINE` | + pattern match structure + guard conditions | + all method signatures + laws | + bind/return implementations | +| 9 | `FULL_SOURCE` | Complete function definition | Complete type class definition | Complete monad definition | + +*Procedural (`uko-proc:`) — Layer 2 (rendering at selected depths):* + +| Depth | Named Level | Procedural Specifics | +|-------|-------------|---------------------| +| 2 | `MEMBER_LISTING` | Function names + global variable names (no types) | +| 4 | `SIGNATURES` | Function declarations + global variable types + header file exports | +| 5 | `SIGNATURES_WITH_DOCS` | + function descriptions + global variable purposes + header summaries | +| 6 | `STRUCTURAL_OUTLINE` | + function signatures with parameter names + struct definitions + macro signatures | +| 9 | `FULL_SOURCE` | Complete source including all function bodies, macros, and inline assembly | + +*Language-Specific (Layer 3) DetailLevelMap insertions — examples:* + +Each language extension may insert additional named levels into its parent paradigm's map (see the fractional-depth insertion mechanism described in Core Data Types). The table below summarizes the key additions: + +| Language | Inserted Levels | Additional Content at Those Depths | +|----------|----------------|------------------------------------| +| **Python** (`uko-py:`) | `DECORATED_SIGNATURES` (between SIGNATURES_WITH_DOCS and STRUCTURAL_OUTLINE), `TYPE_STUBS` (between KEY_LOGIC and NEAR_COMPLETE), `WITH_TESTS` (beyond FULL_SOURCE) | Decorator chains (`@property`, `@staticmethod`, custom), `.pyi` stub type annotations, associated test cases | +| **TypeScript** (`uko-ts:`) | (extends at SIGNATURES level) | `export`/`default export` markers, `declare` ambient types, generic type parameters, mapped/conditional types | +| **Rust** (`uko-rs:`) | (extends at SIGNATURES level) | Visibility modifiers (`pub`, `pub(crate)`), lifetime parameters, trait bounds, `unsafe` markers, `#[derive]` macros, `#[must_use]` annotations | +| **Java** (`uko-java:`) | (extends at SIGNATURES level) | Package visibility, `final`/`abstract`/`sealed` modifiers, annotation lists (`@Override`, `@Deprecated`), checked exceptions | + +Not every language requires a Layer 3 extension. If a language's semantics are fully captured by the Layer 1 (`uko-code:`) and Layer 2 (paradigm) maps, no Layer 3 extension is needed. The system falls back to the nearest parent layer's DetailLevelMap. + +**Documents (`uko-doc:`)**: + +The document ontology represents structured and semi-structured documents (articles, technical papers, documentation, reports) as a hierarchy of containers and atoms. A key design principle is **semantic awareness**: when the system processes a document, it does not merely parse the structural hierarchy (sections, subsections, paragraphs) — it also analyzes the *content* of each text unit to infer implicit relationships. If a paragraph discusses a concept that is the subject of another section (even without an explicit hyperlink or mention by name), the RDF graph captures that relationship via `uko:references` or `uko-doc:discussesTopic` edges. This enables strategies to surface related content that a purely structural traversal would miss. ```turtle -# Documents @prefix uko-doc: . -uko-doc:Document a owl:Class ; rdfs:subClassOf uko:Container . -uko-doc:Section a owl:Class ; rdfs:subClassOf uko:Container . -uko-doc:Paragraph a owl:Class ; rdfs:subClassOf uko:Atom . -uko-doc:CodeBlock a owl:Class ; rdfs:subClassOf uko:Atom . +# ── Container Classes ────────────────────────────────────────────── +uko-doc:Document a owl:Class ; + rdfs:subClassOf uko:Container ; + rdfs:comment "A complete document (article, report, manual, specification)." . -# Data Schemas +uko-doc:Part a owl:Class ; + rdfs:subClassOf uko:Container ; + rdfs:comment "A top-level division of a document (e.g., Part I, Part II)." . + +uko-doc:Chapter a owl:Class ; + rdfs:subClassOf uko:Container ; + rdfs:comment "A chapter within a document or part." . + +uko-doc:Section a owl:Class ; + rdfs:subClassOf uko:Container ; + rdfs:comment "A numbered or titled section within a chapter." . + +uko-doc:Subsection a owl:Class ; + rdfs:subClassOf uko-doc:Section ; + rdfs:comment "A subsection nested within a section (arbitrary depth)." . + +# ── Atom Classes ─────────────────────────────────────────────────── +uko-doc:Paragraph a owl:Class ; + rdfs:subClassOf uko:Atom ; + rdfs:comment "A paragraph of prose text." . + +uko-doc:CodeBlock a owl:Class ; + rdfs:subClassOf uko:Atom ; + rdfs:comment "An inline code listing or example within a document." . + +uko-doc:Figure a owl:Class ; + rdfs:subClassOf uko:Atom ; + rdfs:comment "A figure, diagram, or image with an optional caption." . + +uko-doc:Table a owl:Class ; + rdfs:subClassOf uko:Atom ; + rdfs:comment "A tabular data element within a document." . + +uko-doc:BlockQuote a owl:Class ; + rdfs:subClassOf uko:Atom ; + rdfs:comment "A quoted passage from another source." . + +uko-doc:ListBlock a owl:Class ; + rdfs:subClassOf uko:Atom ; + rdfs:comment "An ordered or unordered list." . + +# ── Annotation Classes ───────────────────────────────────────────── +uko-doc:Footnote a owl:Class ; + rdfs:subClassOf uko:Annotation ; + rdfs:comment "A footnote or endnote." . + +uko-doc:Citation a owl:Class ; + rdfs:subClassOf uko:Annotation ; + rdfs:comment "A bibliographic citation or reference." . + +uko-doc:Comment a owl:Class ; + rdfs:subClassOf uko:Annotation ; + rdfs:comment "An editorial comment or annotation (e.g., HTML comment, review note)." . + +# ── Boundary Classes ─────────────────────────────────────────────── +uko-doc:TableOfContents a owl:Class ; + rdfs:subClassOf uko:Boundary ; + rdfs:comment "The document's table of contents — an interface into the document's structure." . + +uko-doc:Index a owl:Class ; + rdfs:subClassOf uko:Boundary ; + rdfs:comment "A back-of-book index or keyword index." . + +uko-doc:Glossary a owl:Class ; + rdfs:subClassOf uko:Boundary ; + rdfs:comment "A glossary of terms defined in the document." . + +# ── Document-Specific Relationships ──────────────────────────────── +uko-doc:discussesTopic a owl:ObjectProperty ; + rdfs:subPropertyOf uko:references ; + rdfs:domain uko:InformationUnit ; + rdfs:range uko:InformationUnit ; + rdfs:comment "Semantic relationship: this unit discusses a topic that is the subject of another unit. Inferred by the document analyzer even when no explicit link exists." . + +uko-doc:cites a owl:ObjectProperty ; + rdfs:subPropertyOf uko:references ; + rdfs:domain uko:InformationUnit ; + rdfs:range uko-doc:Citation ; + rdfs:comment "This unit cites a bibliographic reference." . + +uko-doc:crossReferences a owl:ObjectProperty ; + rdfs:subPropertyOf uko:references ; + rdfs:domain uko:InformationUnit ; + rdfs:range uko:InformationUnit ; + rdfs:comment "Explicit cross-reference (e.g., 'see Section 3.2')." . + +uko-doc:precedes a owl:ObjectProperty ; + rdfs:domain uko:InformationUnit ; + rdfs:range uko:InformationUnit ; + rdfs:comment "Reading order: this unit comes before the target unit." . + +# ── Document-Specific Properties ─────────────────────────────────── +uko-doc:headingLevel a owl:DatatypeProperty ; + rdfs:domain uko-doc:Section ; + rdfs:range xsd:integer ; + rdfs:comment "The nesting depth of this section (1 = top-level, 2 = subsection, etc.)." . + +uko-doc:headingText a owl:DatatypeProperty ; + rdfs:domain uko-doc:Section ; + rdfs:range xsd:string ; + rdfs:comment "The title/heading text of this section." . + +uko-doc:wordCount a owl:DatatypeProperty ; + rdfs:domain uko:InformationUnit ; + rdfs:range xsd:integer ; + rdfs:comment "Word count of the text content in this unit." . + +uko-doc:language a owl:DatatypeProperty ; + rdfs:domain uko-doc:Document ; + rdfs:range xsd:string ; + rdfs:comment "Natural language of the document (e.g., 'en', 'fr')." . + +uko-doc:topicKeywords a owl:DatatypeProperty ; + rdfs:domain uko:InformationUnit ; + rdfs:range xsd:string ; + rdfs:comment "JSON-encoded list of topic keywords extracted from this unit." . +``` + +**Semantic Inference for Documents**: When the document analyzer processes a document, it performs semantic analysis beyond pure structural parsing: + +1. **Topic extraction**: Each paragraph, section, and subsection is analyzed for key topics. These become `uko-doc:topicKeywords` properties. +2. **Implicit cross-references**: If Paragraph A in Section 2 discusses "authentication flow" and Section 5 is titled "Authentication Architecture", the analyzer creates a `uko-doc:discussesTopic` edge from Paragraph A to Section 5 — even though no explicit link exists in the source document. +3. **Citation resolution**: Bibliographic citations are linked to the paragraphs that cite them. +4. **Concept clustering**: Paragraphs discussing related concepts across different sections are linked via `uko:references`, enabling strategies to pull in contextually relevant content from distant parts of a document. + +This semantic awareness means that a `breadth-depth-navigator` strategy operating on a document resource can follow not just the structural containment hierarchy but also the semantic topic graph, surfacing related sections that an author would need to consider when modifying any part of the document. + +**Document DetailLevelMap Refinements** (per-type rendering at selected depths — see Core Data Types for the authoritative `uko-doc:` depth map): + +| Depth | Named Level | `uko-doc:Document` | `uko-doc:Section` | `uko-doc:Paragraph` | +|-------|-------------|---------------------|--------------------|-----------------------| +| 0 | `TITLE_ONLY` | Document title only | Heading text only | — (not individually listed) | +| 1 | `TABLE_OF_CONTENTS_L1` | Title + top-level section headings | Heading + child section headings | First sentence only | +| 4 | `TOC_WITH_SUMMARIES` | All headings + one-sentence abstract per section | Heading + paragraph count + topic keywords + abstract | First two sentences + topic keywords | +| 8 | `STRUCTURAL_DETAIL` | Full TOC + figure/table captions + list item headers | Heading + first sentence of each paragraph + all captions | Full text with inline code and links preserved | +| 10 | `FULL_CONTENT` | Complete document content | Complete section content including all children | Complete paragraph text with all formatting | + +**Data Schemas (`uko-data:`)**: + +The data schema ontology represents databases, data warehouses, and structured data stores. It models the schema structure (schemas, tables, columns, constraints) and captures query-time relationships (views referencing tables, foreign keys, stored procedures accessing tables). Like the document ontology, the system performs semantic analysis: when a stored procedure references columns from multiple tables, those dependency edges are created automatically. + +```turtle @prefix uko-data: . -uko-data:Schema a owl:Class ; rdfs:subClassOf uko:Container . -uko-data:Table a owl:Class ; rdfs:subClassOf uko:Container . -uko-data:Column a owl:Class ; rdfs:subClassOf uko:Atom . -uko-data:Constraint a owl:Class ; rdfs:subClassOf uko:Annotation . +# ── Container Classes ────────────────────────────────────────────── +uko-data:Database a owl:Class ; + rdfs:subClassOf uko:Container ; + rdfs:comment "A database instance containing schemas." . -# Infrastructure +uko-data:Schema a owl:Class ; + rdfs:subClassOf uko:Container ; + rdfs:comment "A database schema (namespace for tables, views, etc.)." . + +uko-data:Table a owl:Class ; + rdfs:subClassOf uko:Container ; + rdfs:comment "A database table containing columns." . + +uko-data:View a owl:Class ; + rdfs:subClassOf uko:Container ; + rdfs:comment "A database view (virtual table defined by a query)." . + +# ── Atom Classes ─────────────────────────────────────────────────── +uko-data:Column a owl:Class ; + rdfs:subClassOf uko:Atom ; + rdfs:comment "A column within a table or view." . + +uko-data:StoredProcedure a owl:Class ; + rdfs:subClassOf uko:Atom ; + rdfs:comment "A stored procedure or function in the database." . + +uko-data:Trigger a owl:Class ; + rdfs:subClassOf uko:Atom ; + rdfs:comment "A database trigger." . + +uko-data:Migration a owl:Class ; + rdfs:subClassOf uko:Atom ; + rdfs:comment "A schema migration (DDL change script)." . + +# ── Annotation Classes ───────────────────────────────────────────── +uko-data:Constraint a owl:Class ; + rdfs:subClassOf uko:Annotation ; + rdfs:comment "A column or table constraint (NOT NULL, UNIQUE, CHECK, etc.)." . + +uko-data:Index a owl:Class ; + rdfs:subClassOf uko:Annotation ; + rdfs:comment "A database index on one or more columns." . + +uko-data:ColumnComment a owl:Class ; + rdfs:subClassOf uko:Annotation ; + rdfs:comment "A COMMENT ON COLUMN annotation in the database." . + +# ── Boundary Classes ─────────────────────────────────────────────── +uko-data:ForeignKey a owl:Class ; + rdfs:subClassOf uko:Boundary ; + rdfs:comment "A foreign key constraint — an interface point between tables." . + +uko-data:APIEndpoint a owl:Class ; + rdfs:subClassOf uko:Boundary ; + rdfs:comment "A database-level API endpoint (e.g., PostgREST, GraphQL)." . + +# ── Data-Specific Relationships ──────────────────────────────────── +uko-data:foreignKeyTo a owl:ObjectProperty ; + rdfs:subPropertyOf uko:dependsOn ; + rdfs:domain uko-data:Column ; + rdfs:range uko-data:Column ; + rdfs:comment "Foreign key relationship from this column to a column in another table." . + +uko-data:viewReferences a owl:ObjectProperty ; + rdfs:subPropertyOf uko:dependsOn ; + rdfs:domain uko-data:View ; + rdfs:range uko-data:Table ; + rdfs:comment "This view's query references columns from the target table." . + +uko-data:procedureAccesses a owl:ObjectProperty ; + rdfs:subPropertyOf uko:dependsOn ; + rdfs:domain uko-data:StoredProcedure ; + rdfs:range uko-data:Table ; + rdfs:comment "This stored procedure reads from or writes to the target table." . + +uko-data:triggerFires a owl:ObjectProperty ; + rdfs:subPropertyOf uko:dependsOn ; + rdfs:domain uko-data:Trigger ; + rdfs:range uko-data:Table ; + rdfs:comment "This trigger fires on events on the target table." . + +uko-data:migrationAlters a owl:ObjectProperty ; + rdfs:subPropertyOf uko:dependsOn ; + rdfs:domain uko-data:Migration ; + rdfs:range uko-data:Table ; + rdfs:comment "This migration modifies the schema of the target table." . + +# ── Data-Specific Properties ────────────────────────────────────── +uko-data:dataType a owl:DatatypeProperty ; + rdfs:domain uko-data:Column ; + rdfs:range xsd:string ; + rdfs:comment "SQL data type (e.g., 'VARCHAR(255)', 'INTEGER', 'JSONB')." . + +uko-data:isNullable a owl:DatatypeProperty ; + rdfs:domain uko-data:Column ; + rdfs:range xsd:boolean . + +uko-data:isPrimaryKey a owl:DatatypeProperty ; + rdfs:domain uko-data:Column ; + rdfs:range xsd:boolean . + +uko-data:rowEstimate a owl:DatatypeProperty ; + rdfs:domain uko-data:Table ; + rdfs:range xsd:long ; + rdfs:comment "Estimated row count from database statistics." . + +uko-data:viewDefinition a owl:DatatypeProperty ; + rdfs:domain uko-data:View ; + rdfs:range xsd:string ; + rdfs:comment "The SQL query that defines this view." . + +uko-data:procedureBody a owl:DatatypeProperty ; + rdfs:domain uko-data:StoredProcedure ; + rdfs:range xsd:string ; + rdfs:comment "The SQL/PL body of the stored procedure." . +``` + +**Database DetailLevelMap Refinements** (per-type rendering at selected depths — see Core Data Types for the authoritative `uko-data:` depth map): + +| Depth | Named Level | `uko-data:Database` | `uko-data:Table` | `uko-data:Column` | +|-------|-------------|----------------------|-------------------|--------------------| +| 0 | `SCHEMA_LISTING` | Schema names only | — (not individually listed) | — | +| 1 | `TABLE_LISTING` | Schema names + table/view names | Table name only | — | +| 3 | `TYPED_COLUMNS` | + column types + nullability | Column names + types + nullability | Name + type + nullable | +| 5 | `RELATIONSHIPS` | + foreign key graph + row estimates | + primary key + foreign key targets + row estimate | + FK references + constraints | +| 7 | `DDL` | Full CREATE TABLE DDL with constraints | Full CREATE TABLE DDL + index definitions | Full column DDL + all constraints | +| 11 | `FULL_CATALOG` | Complete DDL + views + procedures + sample data | Full DDL + triggers + sample rows + statistics | Full DDL + value distribution + sample values | + +**Infrastructure (`uko-infra:`)**: + +```turtle @prefix uko-infra: . -uko-infra:Service a owl:Class ; rdfs:subClassOf uko:Container . -uko-infra:Endpoint a owl:Class ; rdfs:subClassOf uko:Boundary . -uko-infra:ConfigBlock a owl:Class ; rdfs:subClassOf uko:Container . -uko-infra:ConfigKey a owl:Class ; rdfs:subClassOf uko:Atom . +# ── Container Classes ────────────────────────────────────────────── +uko-infra:Service a owl:Class ; + rdfs:subClassOf uko:Container ; + rdfs:comment "A deployable service or application." . + +uko-infra:ConfigBlock a owl:Class ; + rdfs:subClassOf uko:Container ; + rdfs:comment "A configuration block or section (e.g., a YAML map, TOML table)." . + +uko-infra:DeploymentUnit a owl:Class ; + rdfs:subClassOf uko:Container ; + rdfs:comment "A deployment unit (e.g., Kubernetes Deployment, Docker Compose service)." . + +# ── Atom Classes ─────────────────────────────────────────────────── +uko-infra:ConfigKey a owl:Class ; + rdfs:subClassOf uko:Atom ; + rdfs:comment "A configuration key-value pair." . + +uko-infra:EnvironmentVariable a owl:Class ; + rdfs:subClassOf uko:Atom ; + rdfs:comment "An environment variable definition." . + +# ── Boundary Classes ─────────────────────────────────────────────── +uko-infra:Endpoint a owl:Class ; + rdfs:subClassOf uko:Boundary ; + rdfs:comment "A network endpoint (HTTP route, gRPC service, message queue)." . + +uko-infra:Port a owl:Class ; + rdfs:subClassOf uko:Boundary ; + rdfs:comment "A network port binding." . + +# ── Infrastructure-Specific Relationships ────────────────────────── +uko-infra:connectsTo a owl:ObjectProperty ; + rdfs:subPropertyOf uko:dependsOn ; + rdfs:domain uko-infra:Service ; + rdfs:range uko-infra:Service ; + rdfs:comment "This service connects to or depends on the target service." . + +uko-infra:exposes a owl:ObjectProperty ; + rdfs:domain uko-infra:Service ; + rdfs:range uko-infra:Endpoint ; + rdfs:comment "This service exposes the target endpoint." . ``` ##### The Universal View Guarantee -Because every language-specific class ultimately inherits from Layer 0 (`uko:InformationUnit`, `uko:Container`, etc.), any strategy or query written against Layer 0 automatically works across all languages. For example: +Because every domain-specific class ultimately inherits from Layer 0 (`uko:InformationUnit`, `uko:Container`, etc.), any strategy or query written against Layer 0 automatically works across all domains — not just different programming languages, but across code, documents, databases, and infrastructure alike. For example: ```sparql # "Find all containers that depend on this atom" — works for Python classes, -# TypeScript modules, Rust crates, or SQL tables. +# TypeScript modules, Rust crates, SQL tables, document sections, or config blocks. SELECT ?container WHERE { ?container a uko:Container . ?container uko:dependsOn . } ``` +Similarly, a DetailDepth request at Layer 0 is resolved by the most specific DetailLevelMap available in the inheritance chain. A request for depth 3 of a `uko:Container` will produce a member summary with one-line docstrings for a Python module (`MEMBER_SUMMARY`), a full table of contents for a document chapter (`FULL_TOC`), or typed column definitions for a database table (`TYPED_COLUMNS`) — all through the same universal integer-depth interface, with each domain mapping the integer to its domain-appropriate rendering. + ##### Provenance Contract Every UKO node carries provenance back to the originating resource: -``` +```turtle uko-py:class/AuthManager uko:sourceResource uko:sourcePath "src/auth/manager.py" @@ -25278,10 +25852,10 @@ class StrategyCoordinator: The fusion engine merges fragments from multiple strategies: 1. **Deduplicate**: Same UKO node / same location -- keep highest relevance score. -2. **Resolve detail conflicts**: Same item at different detail levels -- keep highest detail that fits budget. +2. **Resolve detail conflicts**: Same item at different detail depths -- keep the highest depth rendering that fits budget. 3. **Apply hierarchical weighting**: Items closer to the plan's focus area get higher weight. 4. **Rank by composite score**: `relevance_score * strategy_quality * hierarchy_weight`. -5. **Greedy knapsack**: Fit within budget. If an item doesn't fit at FULL, try SUMMARY, then SIGNATURE. +5. **Greedy knapsack**: Fit within budget. If an item doesn't fit at its requested depth, progressively reduce depth (e.g., from 9 to 4 to 0) until it fits or is excluded. 6. **Order for coherence**: Group by resource, order by containment depth then position. 7. **Generate preamble**: Provenance summary, structure map. @@ -25346,30 +25920,30 @@ class PlanContextInheritance: ##### Skeleton Context Propagation -The **skeleton** is a compact, SIGNATURE-level representation of the parent's context window that is passed to every child. This ensures children always have the "big picture" available, even though they focus on a narrow area. The skeleton typically consumes 5-15% of the child's token budget. +The **skeleton** is a compact, low-depth representation (depth 0-1) of the parent's context window that is passed to every child. This ensures children always have the "big picture" available, even though they focus on a narrow area. The skeleton typically consumes 5-15% of the child's token budget. -``` -Parent's hot context (32K tokens): - ┌─ Module: src/auth/ [SUMMARY: 2K tokens] - ├─ Module: src/core/ [SUMMARY: 2K tokens] - ├─ Module: src/api/ [SUMMARY: 2K tokens] - ├─ Module: src/services/ [SUMMARY: 2K tokens] - └─ ... 12 more modules [SUMMARY: 24K tokens] +

+Parent's hot context (32K tokens):
+  ┌─ Module: src/auth/          [depth 3/MEMBER_SUMMARY: 2K tokens]
+  ├─ Module: src/core/          [depth 3/MEMBER_SUMMARY: 2K tokens]
+  ├─ Module: src/api/           [depth 3/MEMBER_SUMMARY: 2K tokens]
+  ├─ Module: src/services/      [depth 3/MEMBER_SUMMARY: 2K tokens]
+  └─ ... 12 more modules        [depth 3/MEMBER_SUMMARY: 24K tokens]
 
-Child's hot context (32K tokens):
-  ┌─ [SKELETON from parent]     [SIGNATURE: 3K tokens]
-  │   Module: src/auth/         [just header + method list]
-  │   Module: src/core/         [just header + method list]
-  │   Module: src/api/          [just header + method list]
+Child's hot context (32K tokens):
+  ┌─ [SKELETON from parent]     [depth 0/MODULE_LISTING: 3K tokens]
+  │   Module: src/auth/         [just name + member names]
+  │   Module: src/core/         [just name + member names]
+  │   Module: src/api/          [just name + member names]
   │   ... etc.
-  ├─ [CHILD FOCUS AREA]         [FULL: 25K tokens]
-  │   Class: AuthManager        [FULL: all methods with bodies]
-  │   Class: TokenValidator     [FULL: referenced by AuthManager]
-  │   Class: User               [STUB: used as parameter type]
-  └─ [INHERITED DECISIONS]      [4K tokens]
-      Decision: "Use async patterns for all auth operations"
-      Decision: "Maintain backward compat with sync callers"
-```
+  ├─ [CHILD FOCUS AREA]         [depth 9/FULL_SOURCE: 25K tokens]
+  │   Class: AuthManager        [depth 9: all methods with bodies]
+  │   Class: TokenValidator     [depth 9: referenced by AuthManager]
+  │   Class: User               [depth 4/SIGNATURES: used as parameter type]
+  └─ [INHERITED DECISIONS]      [4K tokens]
+      Decision: "Use async patterns for all auth operations"
+      Decision: "Maintain backward compat with sync callers"
+
#### Dynamic Context Window Adaptation @@ -25401,8 +25975,8 @@ class ContextBudgetCalculator: When the budget changes between context assembly cycles: -1. **Budget increase**: The coordinator re-runs strategies with the expanded budget. Fragments previously compressed to SIGNATURE may be expanded to SUMMARY or FULL. -2. **Budget decrease**: The fusion engine re-applies the knapsack with the new budget, potentially compressing fragments or dropping low-relevance items. +1. **Budget increase**: The coordinator re-runs strategies with the expanded budget. Fragments previously rendered at a low depth (e.g., depth 0) may be re-rendered at a higher depth (e.g., depth 4 or 9). +2. **Budget decrease**: The fusion engine re-applies the knapsack with the new budget, potentially reducing fragment depths or dropping low-relevance items. 3. **Strategies are stateless**: Each assembly cycle is independent. Strategies receive the current budget and must respect it. ##### Progressive Refinement Within a Session @@ -25423,7 +25997,7 @@ Vector similarity search. Finds semantically related content even without exact ##### Strategy: `breadth-depth-navigator` -The graph-aware strategy that uses the depth/breadth projection system. Works with the UKO graph to provide structurally-aware context at any detail level. Supports focus items, hop traversal, and detail gradients. This is the primary strategy for code-aware context. Quality score: 0.85. +The graph-aware strategy that uses the depth/breadth projection system. Works with the UKO graph to provide structurally-aware context at any detail depth. Supports focus items, hop traversal, and detail depth gradients. This is the primary strategy for code-aware context. Quality score: 0.85. ##### Strategy: `arce` (Analyze, Retrieve, Contextualize, Execute) @@ -25447,11 +26021,14 @@ Retrieves context from parent and ancestor plan decisions. This is how child pla The system is designed for extensibility at every level: -##### Language-Specific Analyzers +##### Domain and Language-Specific Analyzers + +Analyzers are pluggable components that parse resources and produce UKO triples. They are organized by domain (code, documents, data, infrastructure) and then by specific technology within each domain: ```yaml PluginSystem: analyzers: + # --- Source Code Analyzers (Layer 1: uko-code + Layer 2/3) --- python: class: "PythonAnalyzer" features: [AST parsing, Type inference via mypy, Import resolution, Docstring extraction] @@ -25466,6 +26043,36 @@ PluginSystem: config: grammar: "path/to/grammar.peg" semantic_rules: "path/to/rules.yaml" + + # --- Document Analyzers (Layer 1: uko-doc) --- + markdown: + class: "MarkdownAnalyzer" + features: [Heading hierarchy, Link extraction, Code block detection, Topic inference, Cross-reference resolution] + restructuredtext: + class: "ReStructuredTextAnalyzer" + features: [Directive parsing, Role resolution, Cross-reference resolution, Index extraction] + html: + class: "HTMLDocumentAnalyzer" + features: [Semantic HTML parsing, Heading extraction, Link graph, Readability scoring] + + # --- Data Schema Analyzers (Layer 1: uko-data) --- + postgresql: + class: "PostgreSQLAnalyzer" + features: [Schema introspection, DDL extraction, Foreign key graph, View dependency analysis, Stored procedure parsing, Statistics collection] + mysql: + class: "MySQLAnalyzer" + features: [Schema introspection, DDL extraction, Foreign key graph, Trigger parsing] + sqlite: + class: "SQLiteAnalyzer" + features: [Schema introspection, DDL extraction, Virtual table detection] + + # --- Infrastructure Analyzers (Layer 1: uko-infra) --- + docker_compose: + class: "DockerComposeAnalyzer" + features: [Service graph, Port mapping, Volume resolution, Environment variable extraction] + kubernetes: + class: "KubernetesAnalyzer" + features: [Resource parsing, Service dependency graph, ConfigMap/Secret references, Ingress routing] ``` ##### Index Backend Providers @@ -25637,13 +26244,13 @@ This section defines the complete storage strategy for every persistent concept CleverAgents uses a **hybrid storage model** combining a relational database for structured data, the filesystem for configuration files and artifacts, and specialized indexes for search operations. The storage layer is accessed exclusively through repository interfaces defined in the domain layer, ensuring that storage backends can be swapped without affecting application logic. -``` +

 ┌─────────────────────────────────────────────────────────────┐
-│                    Storage Architecture                       │
+│                    Storage Architecture                       │
 │                                                               │
 │  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐ │
-│  │  Relational   │  │  Filesystem  │  │  Search Indexes    │ │
-│  │  Database     │  │              │  │                    │ │
+│  │  Relational   │  │  Filesystem  │  │  Search Indexes    │ │
+│  │  Database     │  │              │  │                    │ │
 │  │  ┌──────────┐ │  │  ┌────────┐ │  │  ┌──────────────┐ │ │
 │  │  │Plans     │ │  │  │Config  │ │  │  │Text (Tantivy)│ │ │
 │  │  │Decisions │ │  │  │YAML    │ │  │  │Vector (FAISS)│ │ │
@@ -25660,7 +26267,7 @@ CleverAgents uses a **hybrid storage model** combining a relational database for
 │  │  └──────────┘ │  └──────────────┘  └────────────────────┘ │
 │  └──────────────┘                                             │
 └─────────────────────────────────────────────────────────────┘
-```
+
#### Entity Storage Map @@ -25863,47 +26470,47 @@ CREATE INDEX idx_audit_created ON audit_log(created_at); The data directory follows a deterministic layout. All paths are relative to `core.data-dir` (default: `~/.cleveragents`): -``` -~/.cleveragents/ -├── config.toml # Global configuration -├── cleveragents.db # SQLite database (WAL mode) -├── cleveragents.db-wal # WAL file (auto-managed by SQLite) -├── cleveragents.db-shm # Shared memory file (auto-managed) -├── logs/ -│ ├── cleveragents.log # Current log file (structured JSON) -│ ├── cleveragents.log.1 # Rotated log files +

+~/.cleveragents/
+├── config.toml                    # Global configuration
+├── cleveragents.db                # SQLite database (WAL mode)
+├── cleveragents.db-wal            # WAL file (auto-managed by SQLite)
+├── cleveragents.db-shm            # Shared memory file (auto-managed)
+├── logs/
+│   ├── cleveragents.log           # Current log file (structured JSON)
+│   ├── cleveragents.log.1         # Rotated log files
 │   └── ...
-├── cache/
-│   ├── models/                    # Cached model artifacts
-│   ├── tools/                     # Cached tool downloads
-│   └── templates/                 # Compiled Jinja2 templates
-├── backups/
-│   ├── 2026-02-08T12-30-00/       # Timestamped backup snapshots
+├── cache/
+│   ├── models/                    # Cached model artifacts
+│   ├── tools/                     # Cached tool downloads
+│   └── templates/                 # Compiled Jinja2 templates
+├── backups/
+│   ├── 2026-02-08T12-30-00/       # Timestamped backup snapshots
 │   └── ...
-├── checkpoints/
-│   ├── 01HXR1C1D2E3F4G5H6I7.../  # Per-plan checkpoint directories
-│   │   ├── chk_01HXR1E1.tar.gz   # Compressed checkpoint snapshots
+├── checkpoints/
+│   ├── 01HXR1C1D2E3F4G5H6I7.../  # Per-plan checkpoint directories
+│   │   ├── chk_01HXR1E1.tar.gz   # Compressed checkpoint snapshots
 │   │   └── ...
 │   └── ...
-├── artifacts/
-│   ├── 01HXR1C1D2E3F4G5H6I7.../  # Per-plan artifact directories
-│   │   ├── src/routes/health.py   # Generated/modified artifacts
+├── artifacts/
+│   ├── 01HXR1C1D2E3F4G5H6I7.../  # Per-plan artifact directories
+│   │   ├── src/routes/health.py   # Generated/modified artifacts
 │   │   └── ...
 │   └── ...
-├── index/
-│   ├── text/
-│   │   ├── local_api-service/     # Per-project Tantivy indexes
+├── index/
+│   ├── text/
+│   │   ├── local_api-service/     # Per-project Tantivy indexes
 │   │   └── ...
-│   ├── vector/
-│   │   ├── local_api-service/     # Per-project FAISS indexes
+│   ├── vector/
+│   │   ├── local_api-service/     # Per-project FAISS indexes
 │   │   └── ...
-│   └── graph/
-│       └── ...                     # rdflib stores or Neo4j connection info
-├── sessions/
-│   └── ...                         # Session state files (if needed beyond DB)
-└── contexts/
-    └── ...                         # Exported/cached context snapshots
-```
+│   └── graph/
+│       └── ...                     # rdflib stores or Neo4j connection info
+├── sessions/
+│   └── ...                         # Session state files (if needed beyond DB)
+└── contexts/
+    └── ...                         # Exported/cached context snapshots
+
#### Data Lifecycle and Retention @@ -26236,34 +26843,34 @@ CleverAgents is designed as an extensible platform where every major subsystem s #### Plugin Architecture Overview -``` +

 ┌────────────────────────────────────────────────────────┐
-│                   Extension Points                      │
+│                   Extension Points                      │
 │                                                         │
 │  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐ │
-│  │ Custom Tools │  │ Custom Skills│  │ Custom Actors │ │
+│  │ Custom Tools │  │ Custom Skills│  │ Custom Actors │ │
 │  │ (YAML/Python)│  │ (YAML)       │  │ (YAML/Graph) │ │
 │  └──────┬──────┘  └──────┬───────┘  └───────┬───────┘ │
 │         │                │                   │          │
 │  ┌──────┴──────┐  ┌──────┴───────┐  ┌───────┴───────┐ │
-│  │ MCP Servers │  │ Agent Skills │  │ Custom LLM    │ │
+│  │ MCP Servers │  │ Agent Skills │  │ Custom LLM    │ │
 │  │ (stdio/SSE) │  │ Standard     │  │ Providers     │ │
 │  └──────┬──────┘  └──────┬───────┘  └───────┬───────┘ │
 │         │                │                   │          │
 │  ┌──────┴────────────────┴───────────────────┴───────┐ │
-│  │              Tool Registry                         │ │
-│  │              Skill Registry                        │ │
-│  │              Actor Registry                        │ │
-│  │              Provider Registry                     │ │
+│  │              Tool Registry                         │ │
+│  │              Skill Registry                        │ │
+│  │              Actor Registry                        │ │
+│  │              Provider Registry                     │ │
 │  └──────────────────────┬────────────────────────────┘ │
 │                         │                               │
 │  ┌──────────────────────┴────────────────────────────┐ │
-│  │  Custom Resource    │  Custom Sandbox  │  Custom  │ │
+│  │  Custom Resource    │  Custom Sandbox  │  Custom  │ │
 │  │  Types (YAML)       │  Strategies     │  Index   │ │
 │  │                     │  (Python)       │  Backends│ │
 │  └─────────────────────┴─────────────────┴──────────┘ │
 └────────────────────────────────────────────────────────┘
-```
+
#### Tool Extensibility @@ -26638,9 +27245,12 @@ Current context is limited to a few hundred characters from a few files. Large c #### Implementation Steps 1. **Universal Knowledge Ontology (UKO) Foundation** - - Implement the four-layer UKO ontology hierarchy (Layer 0: universal, Layer 1: general software, Layer 2: paradigm, Layer 3: language-specific) - - Build language-specific analyzers for Python, TypeScript, Rust, Java (extract UKO nodes from source code) - - Implement non-code domain analyzers: `uko-doc:` (documents), `uko-data:` (schemas), `uko-infra:` (infrastructure) + - Implement the four-layer UKO ontology hierarchy (Layer 0: universal foundation, Layer 1: domain specializations, Layer 2: paradigm/format specializations, Layer 3: technology-specific) + - Implement the DetailDepth / DetailLevelMap system with inheritance-based resolution (Layer 0 universal integer semantics, per-domain named level maps at Layer 1, paradigm refinements at Layer 2, language-specific insertions at Layer 3) + - Build source code analyzers for Python, TypeScript, Rust, Java (extract UKO nodes from source code via `uko-code:`, `uko-oo:`, `uko-func:`, `uko-py:`, etc.) + - Implement document analyzers for Markdown, reStructuredText, HTML (`uko-doc:`) with semantic awareness (topic extraction, implicit cross-reference inference via `uko-doc:discussesTopic`, citation resolution) + - Implement data schema analyzers for PostgreSQL, MySQL, SQLite (`uko-data:`) with schema introspection, foreign key graph construction, view dependency analysis, and stored procedure parsing + - Implement infrastructure analyzers for Docker Compose, Kubernetes (`uko-infra:`) with service dependency graph construction and config reference resolution - Implement temporal versioning (`validFrom`, `validUntil`, `isCurrent`, `isRevisionOf`) - Integrate eager indexing on resource add via the Resource Registry lifecycle hooks @@ -26956,11 +27566,11 @@ This allows the system to remain functional during development while progressive ### Q: How does CleverAgents handle persistent repository knowledge beyond ephemeral context windows? -**What exists today architecturally**: The specification defines the Advanced Context Management System (ACMS) — a sophisticated, pluggable, strategy-driven framework that goes far beyond ephemeral context windows. At its core are three innovations: (1) the Universal Knowledge Ontology (UKO), an inheritance-based RDF ontology that represents any resource at multiple abstraction levels with full provenance and temporal versioning; (2) the Context Request Protocol (CRP), through which actors dynamically declare what information they need at what detail level; and (3) a pluggable Strategy Framework with a Fusion Coordinator that runs multiple retrieval strategies in parallel and merges their results into a budget-respecting context payload. Underlying this is the Decision Tree structure which provides a durable, queryable record of every choice made during planning. +**What exists today architecturally**: The specification defines the Advanced Context Management System (ACMS) — a sophisticated, pluggable, strategy-driven framework that goes far beyond ephemeral context windows. At its core are three innovations: (1) the Universal Knowledge Ontology (UKO), an inheritance-based RDF ontology that represents any resource at multiple abstraction levels with full provenance and temporal versioning; (2) the Context Request Protocol (CRP), through which actors dynamically declare what information they need at what detail depth; and (3) a pluggable Strategy Framework with a Fusion Coordinator that runs multiple retrieval strategies in parallel and merges their results into a budget-respecting context payload. Underlying this is the Decision Tree structure which provides a durable, queryable record of every choice made during planning. **How the persistent model works in practice**: -When a strategy actor analyzes a codebase during the Strategize phase, the ACMS assembles context dynamically using the CRP. The actor issues `request_context` calls specifying focus nodes (UKO URIs), breadth (hop count), depth (SIGNATURE/SUMMARY/STUB/FULL), and optional depth gradients. The Strategy Coordinator runs applicable strategies (e.g., `breadth-depth-navigator` for graph traversal, `semantic-embedding` for similarity search, `plan-decision-context` for historical decisions) in parallel, and the Fusion Engine deduplicates, resolves detail conflicts, and packs the results into the available budget. +When a strategy actor analyzes a codebase during the Strategize phase, the ACMS assembles context dynamically using the CRP. The actor issues `request_context` calls specifying focus nodes (UKO URIs), breadth (hop count), depth (an integer or named level like `SIGNATURES`, `FULL_SOURCE`), and optional depth gradients. The Strategy Coordinator runs applicable strategies (e.g., `breadth-depth-navigator` for graph traversal, `semantic-embedding` for similarity search, `plan-decision-context` for historical decisions) in parallel, and the Fusion Engine deduplicates, resolves detail conflicts, and packs the results into the available budget. Each decision creates a comprehensive Decision record that includes: @@ -26976,7 +27586,7 @@ Each decision creates a comprehensive Decision record that includes: This means when the system decides "refactor the authentication module to use async patterns," it permanently records: - Which UKO nodes (files, classes, functions) were the focus of context assembly -- Which strategies retrieved context and at what detail levels +- Which strategies retrieved context and at what detail depths - What symbols and dependencies were traced via UKO graph traversal - The exact code state that was analyzed (with temporal versioning via `validFrom`/`validUntil`) - The reasoning chain that led to this choice @@ -26989,7 +27599,7 @@ This means when the system decides "refactor the authentication module to use as 3. **Cold tier**: Historical decisions from past plans on this codebase — queryable via `temporal-archaeology` strategy, retained for `context.tiers.cold.retention-days` (default: 90 days) When working on a 50,000 file codebase, the system doesn't need to hold all files in memory. Instead: -- Hot context focuses on the immediate task via demand-driven CRP requests (e.g., `request_context` with focus on 10-20 UKO nodes, breadth=2, depth_gradient={0:FULL, 1:SUMMARY, 2:SIGNATURE}) +- Hot context focuses on the immediate task via demand-driven CRP requests (e.g., `request_context` with focus on 10-20 UKO nodes, breadth=2, depth_gradient={0:9, 1:4, 2:0}) - Warm context maintains the decision chain via the `plan-decision-context` strategy, with skeleton compression propagating parent plan context to child plans - Cold context provides historical patterns via the `temporal-archaeology` strategy ("last time we refactored auth, we also had to update these services")