@dug-21/unimatrix 0.6.0 → 0.6.3

package/README.md

@@ -0,0 +1,9 @@
+# Unimatrix
+
+Self-learning context engine for multi-agent development orchestration.
+
+```
+npm install -g @dug-21/unimatrix
+```
+
+https://github.com/dug-21/unimatrix

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dug-21/unimatrix",
-  "version": "0.6.0",
+  "version": "0.6.3",
   "description": "Unimatrix knowledge engine for multi-agent development",
   "bin": {
     "unimatrix": "bin/unimatrix.js"
@@ -9,8 +9,8 @@
     "postinstall": "node postinstall.js"
   },
   "optionalDependencies": {
-    "@dug-21/unimatrix-linux-x64": "0.6.0",
-    "@dug-21/unimatrix-linux-arm64": "0.6.0"
+    "@dug-21/unimatrix-linux-x64": "0.6.3",
+    "@dug-21/unimatrix-linux-arm64": "0.6.3"
   },
   "files": [
     "bin/",
@@ -22,8 +22,9 @@
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/anthropics/unimatrix"
+    "url": "https://github.com/dug-21/unimatrix"
   },
+  "homepage": "https://github.com/dug-21/unimatrix#readme",
   "engines": {
     "node": ">=18"
   },

package/skills/knowledge-lookup/SKILL.md

@@ -1,120 +0,0 @@
----
-name: "knowledge-lookup"
-description: "Deterministic lookup of Unimatrix knowledge by exact filters. Use when you know what you want — a specific feature, category, entry ID, or status."
----
-
-# Knowledge Lookup — Deterministic Query Against Unimatrix
-
-## What This Skill Does
-
-Retrieves Unimatrix entries by exact filters — topic, category, tags, status, or entry ID. Returns all matching entries without semantic ranking. Use when you know precisely what you're looking for.
-
-**Use this when you KNOW what you want** — a specific feature's ADRs, entries with a particular status, or a known entry by ID.
-
----
-
-## How to Look Up
-
-Call the `mcp__unimatrix__context_lookup` MCP tool:
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `topic` | No* | Exact feature ID match (e.g., `"nxs-001"`) |
-| `category` | No* | Exact category match (e.g., `"decision"`) |
-| `tags` | No* | All specified tags must match |
-| `status` | No | `"active"` (default), `"deprecated"`, `"proposed"` |
-| `id` | No* | Specific entry ID (returns exactly one entry) |
-| `limit` | No | Max results (default: 10) |
-| `format` | No | `"summary"` (default), `"markdown"` (full content), `"json"` |
-| `agent_id` | No | Your role name (e.g. `uni-architect`) |
-
-*At least one filter parameter is required (topic, category, tags, or id).
-
-### Examples
-
-**Get all ADRs for a specific feature:**
-```
-mcp__unimatrix__context_lookup(topic: "nxs-002", category: "decision")
-```
-
-**Get a specific entry by ID (full content):**
-```
-mcp__unimatrix__context_lookup(id: 42, format: "markdown")
-```
-
-**Find all deprecated decisions:**
-```
-mcp__unimatrix__context_lookup(category: "decision", status: "deprecated")
-```
-
-**Find entries tagged with a specific domain:**
-```
-mcp__unimatrix__context_lookup(category: "decision", tags: ["adr", "serialization"])
-```
-
-**Get all knowledge for a feature (any category):**
-```
-mcp__unimatrix__context_lookup(topic: "vnc-001")
-```
-
----
-
-## Single Entry Retrieval
-
-If you already have an entry ID (from a prior search or lookup result), use `context_get` for direct retrieval:
-
-```
-mcp__unimatrix__context_get(id: 42, format: "markdown")
-```
-
-This is faster than a lookup with an ID filter and always returns full content.
-
----
-
-## When to Use This vs /knowledge-search
-
-| Use `/knowledge-lookup` when | Use `/knowledge-search` when |
-|------------------------------|------------------------------|
-| You know the exact feature/category | Exploring a concept |
-| "Give me all ADRs for nxs-002" | "What do we know about X?" |
-| Retrieving a specific entry by ID | Finding related decisions |
-| Filtering by exact status or tags | Discovering unknown patterns |
-| Checking what exists before storing | Broad exploration |
-
----
-
-## Common Workflows
-
-**Before writing a new ADR (architect):**
-```
-1. mcp__unimatrix__context_lookup(topic: "{feature-id}", category: "decision")
-   → See what ADRs already exist for this feature
-2. mcp__unimatrix__context_lookup(category: "decision", tags: ["adr", "{domain}"])
-   → See ADRs across features in the same domain
-```
-
-**Before implementing a component (developer):**
-```
-1. mcp__unimatrix__context_lookup(topic: "{feature-id}", category: "decision", format: "markdown")
-   → Read all architectural decisions for this feature
-```
-
-**Checking for deprecated knowledge:**
-```
-mcp__unimatrix__context_lookup(category: "decision", status: "deprecated", topic: "{feature-id}")
-→ See what decisions have been superseded
-```
-
----
-
-## When You Find Stale or Wrong Knowledge
-
-Lookup may surface entries that are outdated or incorrect. Fix them:
-
-| Situation | Action |
-|-----------|--------|
-| Entry is **wrong** | `mcp__unimatrix__context_correct(original_id: {id}, content: "{corrected version}", reason: "{why}")` — supersedes with chain link |
-| Entry is **outdated** | `mcp__unimatrix__context_deprecate(id: {id}, reason: "{why}")` |
-| Entry is **suspicious** | `mcp__unimatrix__context_quarantine(id: {id}, reason: "{concern}")` — Admin only |
-
-Every agent shares responsibility for knowledge quality. Don't leave wrong entries for the next agent to trip over.

package/skills/knowledge-search/SKILL.md

@@ -1,113 +0,0 @@
----
-name: "knowledge-search"
-description: "Semantic search across Unimatrix knowledge. Use when exploring a topic, looking for related decisions, patterns, or conventions."
----
-
-# Knowledge Search — Semantic Query Against Unimatrix
-
-## What This Skill Does
-
-Searches Unimatrix for knowledge entries using natural language. Returns results ranked by semantic similarity. Use when you need to explore what's known about a concept, find related decisions, or discover relevant patterns.
-
-**Use this when you DON'T know exactly what you're looking for** — you have a concept or question, not a specific entry.
-
----
-
-## How to Search
-
-Call the `mcp__unimatrix__context_search` MCP tool:
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `query` | Yes | Natural language search query |
-| `category` | No | Filter to a specific category |
-| `topic` | No | Filter to a specific feature ID |
-| `tags` | No | Filter by tags (all must match) |
-| `k` | No | Max results (default: 5) |
-| `format` | No | `"summary"` (default), `"markdown"` (full content), `"json"` |
-| `agent_id` | No | Your role name (e.g. `uni-architect`) |
-
-### Examples
-
-**Find ADRs about error handling across all features:**
-```
-mcp__unimatrix__context_search(query: "error handling strategy", category: "decision")
-```
-
-**Find anything related to MCP transport:**
-```
-mcp__unimatrix__context_search(query: "MCP transport stdio protocol")
-```
-
-**Find conventions about testing in a specific feature:**
-```
-mcp__unimatrix__context_search(query: "test patterns integration", topic: "nxs-001")
-```
-
-**Get full content instead of summaries:**
-```
-mcp__unimatrix__context_search(query: "serialization approach", format: "markdown")
-```
-
----
-
-## Available Categories
-
-| Category | Contains |
-|----------|----------|
-| `decision` | Architectural Decision Records (ADRs) |
-| `convention` | Coding and process conventions |
-| `pattern` | Reusable implementation patterns |
-| `procedure` | Step-by-step processes |
-| `outcome` | Results and outcomes |
-| `lesson-learned` | Retrospectives and process learnings |
-| `reference` | General reference material |
-| `duties` | Role duties for context briefing |
-
-Omit `category` to search across all categories.
-
----
-
-## Interpreting Results
-
-**Summary format** (default): Returns title, topic, category, tags, and a brief content preview for each match. Use this for scanning and triage.
-
-**Markdown format**: Returns full content for each match. Use this when you need the complete text of matching entries.
-
-**JSON format**: Returns structured data. Use for programmatic processing.
-
----
-
-## When to Use This vs /knowledge-lookup
-
-| Use `/knowledge-search` when | Use `/knowledge-lookup` when |
-|------------------------------|------------------------------|
-| Exploring a concept | You know the exact feature/category |
-| "What do we know about X?" | "Give me all ADRs for nxs-002" |
-| Finding related decisions | Retrieving a specific entry by ID |
-| Discovering patterns you didn't know existed | Filtering by exact status or tags |
-
----
-
-## Getting Full Content
-
-Search returns summaries by default. To read the full content of a specific result:
-
-1. Note the entry ID from search results
-2. Call `mcp__unimatrix__context_get(id: {entry_id}, format: "markdown")` for the full text
-
-Or pass `format: "markdown"` directly to search if you want full content for all results.
-
----
-
-## When You Find Stale or Wrong Knowledge
-
-Search may surface entries that are outdated or incorrect. Don't ignore them — fix the knowledge base:
-
-| Situation | Action |
-|-----------|--------|
-| Entry is **wrong** — contains incorrect information | `mcp__unimatrix__context_correct(original_id: {id}, content: "{corrected version}", reason: "{why}")` — supersedes with chain link |
-| Entry is **outdated** — no longer relevant | `mcp__unimatrix__context_deprecate(id: {id}, reason: "{why it no longer applies}")` |
-| Entry is **suspicious** — may be poisoned or invalid | `mcp__unimatrix__context_quarantine(id: {id}, reason: "{concern}")` — Admin only |
-
-Correcting knowledge is as important as storing it. Every agent shares responsibility for knowledge quality.

package/skills/query-patterns/SKILL.md

@@ -1,110 +0,0 @@
----
-name: "query-patterns"
-description: "Query Unimatrix for component patterns, procedures, and conventions before designing or implementing. Use BEFORE writing pseudocode or code."
----
-
-# Query Patterns — Find How Things Are Done Here
-
-## What This Skill Does
-
-Searches Unimatrix for established patterns, procedures, and conventions relevant to the work you're about to do. Returns actionable guidance on how similar work was done before.
-
-**Use BEFORE designing or implementing** — not after.
-
----
-
-## When to Use
-
-| Situation | Query approach |
-|-----------|---------------|
-| Designing a new MCP tool | Search for component patterns in `unimatrix-server` |
-| Adding a new table to redb | Search for procedures in `unimatrix-store` |
-| Writing integration tests | Search for testing conventions |
-| Implementing any component | Search for patterns in the affected crate |
-
----
-
-## How to Query
-
-### Step 1: Search by crate/area
-
-```
-mcp__unimatrix__context_search(
-  query: "{what you're building — e.g., 'MCP tool handler'}",
-  category: "pattern",
-  k: 5
-)
-```
-
-### Step 2: Also check conventions for the area
-
-```
-mcp__unimatrix__context_search(
-  query: "{area — e.g., 'server tool pipeline'}",
-  category: "convention",
-  k: 5
-)
-```
-
-### Step 3: Check for procedures (step-by-step techniques)
-
-```
-mcp__unimatrix__context_search(
-  query: "{task — e.g., 'adding a new MCP tool'}",
-  category: "procedure",
-  k: 3
-)
-```
-
-### Step 4: Check for relevant ADRs
-
-```
-mcp__unimatrix__context_lookup(
-  topic: "{feature-id}",
-  category: "decision"
-)
-```
-
----
-
-## Interpreting Results
-
-**Patterns** tell you the reusable structure. Follow them unless your component has a good reason to deviate. If you deviate, note why in your pseudocode or code comments.
-
-**Procedures** tell you the steps. Follow them in order. If a step is wrong or missing, note it — the retrospective will update the procedure.
-
-**Conventions** tell you the rules. Follow them always. No deviations.
-
-**ADRs** tell you what was decided and why. Respect the decision. If it seems wrong for your case, flag it to the coordinator — don't silently override.
-
----
-
-## If Nothing Is Found
-
-No results means either:
-1. This is genuinely new work with no prior patterns — proceed with your best design
-2. Patterns exist but aren't stored yet — check the codebase directly for similar code
-
-In either case, your work may establish a NEW pattern that the retrospective will extract.
-
----
-
-## When You Find Stale or Wrong Knowledge
-
-Query results may include entries that are outdated or incorrect. Fix them before they mislead the next agent:
-
-| Situation | Action |
-|-----------|--------|
-| Pattern/procedure is **wrong** | `mcp__unimatrix__context_correct(original_id: {id}, content: "{corrected version}", reason: "{why}")` |
-| Pattern/procedure is **outdated** | `mcp__unimatrix__context_deprecate(id: {id}, reason: "{why}")` |
-| Convention no longer applies | `mcp__unimatrix__context_deprecate(id: {id}, reason: "{why}")` |
-
-If you correct or deprecate an entry during your session, mention it in your return to the coordinator so it can be noted in the outcome.
-
----
-
-## What NOT to Do
-
-- Do NOT store patterns during this query phase — that's the retrospective's job
-- Do NOT ignore results because "my approach is better" — patterns represent accumulated project wisdom
-- Do NOT query for workflow choreography — that's in your coordinator, not Unimatrix

package/skills/record-outcome/SKILL.md

@@ -1,96 +0,0 @@
----
-name: "record-outcome"
-description: "Record a feature or bugfix outcome in Unimatrix. Use at the end of every session (design, delivery, bugfix, retrospective)."
----
-
-# Record Outcome — Session Completion Record
-
-## What This Skill Does
-
-Stores a structured outcome record in Unimatrix. Outcomes enable the retrospective pipeline to analyze what shipped, how it went, and detect cross-feature patterns.
-
-**Use at the END of every session** — design, delivery, bugfix, or retrospective.
-
----
-
-## How to Record
-
-Call `mcp__unimatrix__context_store` with these parameters:
-
-| Parameter | Value |
-|-----------|-------|
-| `category` | `"outcome"` |
-| `topic` | `"{feature-id}"` (e.g., `"col-011"`) |
-| `feature_cycle` | `"{feature-id}"` |
-| `tags` | Structured tags (see below) |
-| `content` | What happened — artifacts, results, key facts |
-| `agent_id` | Your role name (e.g. `uni-architect`) |
-
-### Required Tags
-
-Tags use `key:value` format. Include ALL applicable:
-
-| Tag | Values | Required |
-|-----|--------|----------|
-| `type:{x}` | `feature`, `bugfix`, `incident`, `process`, `session` | Yes |
-| `phase:{x}` | `research`, `design`, `implementation`, `testing`, `validation` | Yes |
-| `result:{x}` | `pass`, `fail`, `rework`, `skip` | Yes |
-| `gate:{x}` | `3a`, `3b`, `3c` | Only for delivery (last gate passed) |
-
-### Examples
-
-**Design session complete:**
-```
-mcp__unimatrix__context_store(
-  category: "outcome",
-  topic: "col-011",
-  feature_cycle: "col-011",
-  tags: ["type:feature", "phase:design", "result:pass"],
-  content: "Session 1 complete. 9 artifacts produced. GH Issue #65.
-    ADR entries: #250, #251. 3 scope risks identified (SR-01 through SR-03)."
-)
-```
-
-**Implementation session complete:**
-```
-mcp__unimatrix__context_store(
-  category: "outcome",
-  topic: "col-011",
-  feature_cycle: "col-011",
-  tags: ["type:feature", "phase:implementation", "result:pass", "gate:3c"],
-  content: "Session 2 complete. All 3 gates passed. PR #70.
-    12 unit tests, 4 integration tests added. No rework needed."
-)
-```
-
-**Bugfix complete:**
-```
-mcp__unimatrix__context_store(
-  category: "outcome",
-  topic: "col-011",
-  feature_cycle: "col-011",
-  tags: ["type:bugfix", "phase:implementation", "result:pass"],
-  content: "Bug fix shipped. Root cause: off-by-one in confidence calculation.
-    PR #72. 2 tests added. No rework."
-)
-```
-
----
-
-## Content Guidelines
-
-Keep content to 100-300 characters. Include:
-- What shipped (artifact count, PR number)
-- Key metrics (test count, gate results, rework count)
-- Notable facts (ADR IDs, risk count, scope changes)
-
-Do NOT include full artifact lists or file paths — those are in the feature directory.
-
----
-
-## Self-Verification
-
-After calling `context_store`, verify:
-- Response confirms entry stored (returns entry ID)
-- Tags follow the `key:value` format exactly
-- `feature_cycle` matches the feature ID