omnius 1.0.591 → 1.0.592

package/docs/HANDOFF-crl-encoder-decoder-fix.md

@@ -0,0 +1,129 @@
+# HANDOFF: CRL Encoder/Decoder Bidirectional Fix
+
+**Date:** 2026-04-22
+**Status:** Needs Implementation
+**Failing Test:** `packages/memory/tests/crl-converter.test.ts` - "should validate roundtrip accuracy"
+
+## Problem Summary
+
+The CRL (Concept Relational Language) bidirectional conversion is failing with **0 episodes passing** (expected >50%). The encoder and decoder are asymmetric.
+
+## Root Cause Analysis
+
+### Encoder (`packages/memory/src/crl/index.ts:632-779`)
+
+```typescript
+encode(text: string): string {
+  let result = this.compress(text);        // Simple text replacement
+  const concepts = this.extractConcepts(result);
+  const relations = this.extractRelations(result, concepts);
+  
+  if (relations.length > 0) {
+    return this.buildExpression(concepts, relations);  // Produces: "[A] → [B]"
+  }
+  return result;  // Returns compressed text
+}
+```
+
+**Problem:** Encoder produces simple text like `[ConceptA] → [ConceptB]` but this is NOT valid structured CRL that the parser can parse.
+
+### Decoder (`packages/memory/src/crl/index.ts:784-955`)
+
+```typescript
+decode(crl: string): string {
+  const parser = new CRLParser();
+  const ast = parser.parse(crl);  // Expects structured CRL
+  return this.renderStatement(ast);
+}
+```
+
+**Problem:** Decoder uses CRLParser which expects structured CRL syntax, but encoder output is not parseable.
+
+### CRLParser (`packages/memory/src/crl/index.ts:369-631`)
+
+The parser expects structured CRL with:
+- Proper node types (concept, relation, quantifier, etc.)
+- Position tracking
+- Nested structures
+
+## The Fix Required
+
+### Option A: Make Encoder Produce Structured CRL
+
+The encoder needs to output CRL that the parser can understand. Looking at the parser's expected format:
+
+1. **Concepts** should be: `[name]` with optional properties
+2. **Relations** should be: `[from] operator [to]` with proper spacing
+3. **Statements** should be newline-separated
+
+The encoder's `buildExpression()` method (lines 723-748) already produces this format, but the parser may have different expectations.
+
+### Option B: Make Decoder Handle Encoder Output Directly
+
+Instead of parsing, the decoder could:
+1. Check if input is already structured CRL → use parser
+2. If input is encoder output → use direct expansion
+
+### Recommended Approach
+
+**Fix the encoder to produce parseable CRL:**
+
+1. Ensure `buildExpression()` output matches what `CRLParser.parseNode()` expects
+2. The parser's `parseConcept()` (line 424) expects `[name]` format
+3. The parser's `parseOperator()` (line 591) expects specific operators
+
+**Key mismatch to investigate:**
+- Encoder produces: `[A] → [B]`
+- Parser's `parseNode()` (line 396) may expect different structure
+
+## Files to Modify
+
+1. `packages/memory/src/crl/index.ts`:
+   - Lines 632-779: `CRLEncoder` class
+   - Lines 723-748: `buildExpression()` method
+   - Lines 784-955: `CRLDecoder` class
+
+2. `packages/memory/tests/crl-converter.test.ts`:
+   - Lines 30-255: Test expectations
+
+## Test Command
+
+```bash
+cd packages/memory && pnpm test tests/crl-converter.test.ts
+```
+
+## Validation Criteria
+
+After fix:
+- Roundtrip test should pass >50% of episodes
+- Encoder output should be parseable by CRLParser
+- Decoder should reconstruct original meaning with acceptable fidelity
+
+## Additional Context
+
+From session diary (2026-04-22 15:50):
+- Test result: 0 episodes passed (expected >50%)
+- Root cause: Encoder/Decoder asymmetry
+- Encoder does simple text replacement
+- Decoder expects structured CRL AST
+
+## Next Steps for Implementer
+
+1. Read `CRLParser.parse()` and `parseNode()` methods (lines 369-631)
+2. Understand what AST structure the parser produces
+3. Modify `CRLEncoder.buildExpression()` to produce parseable output
+4. OR modify `CRLDecoder.decode()` to handle both structured and simple formats
+5. Run test: `pnpm test tests/crl-converter.test.ts`
+6. Iterate until >50% pass rate
+
+## Research Basis
+
+CRL is based on:
+- SymbCoT (ACL 2024): Symbolic Chain-of-Thought
+- Aristotle (ACL 2025): Logic-complete framework
+- LogicReward (ICLR 2026): Step-wise logical supervision
+- MuSLR (NeurIPS 2025): Multimodal symbolic reasoning
+
+---
+
+**Handoff complete. Next agent: implement the fix described above.**

package/docs/agent-memory/INDEX.md

@@ -11,16 +11,20 @@ Omnius documentation is exposed to agents through project-local AIWG-style bundl
 
 ## Agent Use Pattern
 
-1. Use `skill_list` or `/skills` with a focused filter.
-2. Load the matching docs skill.
-3. Open the index named by that skill.
-4. Read only the relevant guide or reference page.
+1. Run `omnius discover "<need>"` or search `GET /v1/discovery`.
+2. Expand the stable result with `omnius show <id>`.
+3. Use `skill_list` or `/skills` when the entry points to a skill.
+4. Open only the referenced guide or endpoint family.
 5. Treat source files and live OpenAPI as canonical when docs conflict with code.
 
 ## Skills
 
 ```text
 omnius-docs
+omnius-inference-docs
+omnius-tools-docs
+omnius-integration-docs
+omnius-version-compatibility-docs
 omnius-realtime-docs
 omnius-sponsor-docs
 omnius-telegram-docs
@@ -33,6 +37,7 @@ omnius-rest-docs
 When adding a major feature, add:
 
 - a human guide or reference page
+- a curated discovery override when aliases, relationships, or invocation mode need explanation
 - an entry in README if it affects first-run understanding
 - a docs skill or trigger if agents should discover it
 - validation coverage if the feature has a machine-readable surface

package/docs/agent-memory/index.md

@@ -6,9 +6,16 @@ Use the Omnius docs skills when an agent needs to explore the documentation corp
 | --- | --- |
 | `omnius-docs` | Product overview, setup, guides, operations, and architecture |
 | `omnius-rest-docs` | REST endpoint families, auth, examples, OpenAPI drift checks |
+| `omnius-inference-docs` | Provider protocols, keys, Claude Messages, Gemini compatibility, custom endpoints |
+| `omnius-tools-docs` | Tool discovery, direct calls, agent-bound web search, external tools, and MCP |
+| `omnius-integration-docs` | Agent/service adapters, discovery, auth, and version compatibility |
+| `omnius-version-compatibility-docs` | Stale daemon detection and execution version preconditions |
 | `omnius-sponsor-docs` | Sponsor, COHERE, peer sharing, usage, and media sharing |
 | `omnius-telegram-docs` | Telegram bridge setup, scope, preferences, and failure feedback |
 | `omnius-realtime-docs` | Short spoken dialogue mode and ASR/TTS client loops |
 | `omnius-ops-docs` | Security, runtime hygiene, update/install triage |
 
 The source index for installed agent discovery remains `docs/agent-memory/INDEX.md`.
+
+For capability-first lookup, start with `docs/DISCOVERY.json`,
+`omnius discover`, or `GET /v1/discovery`.