@dug-21/unimatrix 0.6.2 → 0.7.0

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.2",
+  "version": "0.7.0",
   "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.2",
-    "@dug-21/unimatrix-linux-arm64": "0.6.2"
+    "@dug-21/unimatrix-linux-x64": "0.7.0",
+    "@dug-21/unimatrix-linux-arm64": "0.7.0"
   },
   "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/protocols/uni-bugfix-protocol.md

@@ -311,7 +311,13 @@ Task(subagent_type: "uni-validator",
     - Integration smoke tests passed
     - Any xfail markers added have corresponding GH Issues
     - If bug was discovered by integration test, that test's xfail marker was removed
-    - Knowledge stewardship: investigator and rust-dev reports contain ## Knowledge Stewardship block with Queried/Stored/Declined entries
+    - Knowledge stewardship: investigator, architect, and rust-dev phase comments each contain
+      a ## Knowledge Stewardship block with Queried/Stored/Declined entries
+
+    To verify Knowledge Stewardship:
+      Run: gh issue view {issue-number} --comments
+      Read all phase comments. Verify each of the three agents has a ## Knowledge Stewardship
+      block. Missing block = REWORKABLE FAIL. Present with no reason after "nothing novel" = WARN.
 
     Bug report: {bug description}
     Root cause diagnosis: {from approved diagnosis}
@@ -406,7 +412,7 @@ Human action required: Review PR and approve merge.
 ```
 
 On human approval to merge, the Bugfix Manager:
-1. Merges the PR with `gh pr merge --rebase` (if human requests it)
+1. Merges the PR with `gh pr merge --squash --delete-branch` (if human requests it) — squash preferred: one commit = one revert target if backout is needed
 2. Closes the GH Issue with reference to the PR (if applicable)
 
 ---
@@ -539,9 +545,10 @@ Then use Unimatrix skills as applicable:
 
 ### Stewardship Compliance
 
-The bugfix gate validator checks stewardship compliance for investigator and rust-dev agents:
-- Investigator report must include `## Knowledge Stewardship` with `Queried:` and `Stored:`/`Declined:` entries
-- Rust-dev report must include `## Knowledge Stewardship` with `Queried:` and `Stored:`/`Declined:` entries
+The bugfix gate validator checks stewardship compliance for all three agents via `gh issue view --comments`:
+- Investigator phase comment must include `## Knowledge Stewardship` with `Queried:` and `Stored:`/`Declined:` entries
+- Architect phase comment must include `## Knowledge Stewardship` with `Queried:` and `Stored:`/`Declined:` entries
+- Rust-dev phase comment must include `## Knowledge Stewardship` with `Queried:` and `Stored:`/`Declined:` entries
 - Missing stewardship block = REWORKABLE FAIL
 
 All phase outputs (diagnosis, fix summary, gate results, security review) are posted as **GH Issue comments** — never written to the filesystem.

package/protocols/uni-delivery-protocol.md

@@ -42,6 +42,7 @@ Phase 4: Delivery
 - Max 2 rework iterations per gate — protects context window
 - Cargo output truncated to first error + summary line
 - The three source documents (Architecture, Specification, Risk Strategy) are sacred — all work traces back to them
+- **Artifact hierarchy**: Architecture, Specification, and Risk Strategy are the technical ground truth. The Implementation Brief is a coordination artifact — it routes and summarizes but does not override source documents. If the brief and a source document conflict, the source document is authoritative; resolve before Stage 3a begins.
 
 ---
 
@@ -281,11 +282,13 @@ Task(subagent_type: "uni-validator",
     - Does implementation align with approved Architecture?
     - Are component interfaces implemented as specified?
     - Do test cases match component test plans?
+    - Do test cases cover risks from the Risk-Based Test Strategy?
     - Does code compile? Are there stubs or placeholders?
 
     Source documents:
     - product/features/{id}/architecture/ARCHITECTURE.md
     - product/features/{id}/specification/SPECIFICATION.md
+    - product/features/{id}/RISK-TEST-STRATEGY.md
     - product/features/{id}/pseudocode/ (all files)
     - product/features/{id}/test-plan/ (all files)
 

package/protocols/uni-design-protocol.md

@@ -44,6 +44,7 @@ Each message batches ALL related operations of the same type:
 - NO code changes. NO file edits outside `product/features/`
 - NO launching delivery agents (uni-rust-dev, uni-pseudocode, uni-tester)
 - Agents return: artifact paths + key decisions + open questions (NOT full file contents)
+- **Artifact hierarchy**: Architecture, Specification, and Risk Strategy are the technical ground truth. The Implementation Brief is a coordination artifact derived from them — technical decisions live in source documents, the brief routes and summarizes.
 
 ### No Git Operations in Design
 
@@ -322,6 +323,10 @@ Open questions: {list or "none"}
 Human action required: Review design artifacts. Then start Session 2 to deliver.
 ```
 
+**Handling human-requested changes**: If the human requests changes after reviewing artifacts:
+- **Technical changes** (architecture decisions, requirements, risk coverage) → update the relevant source document(s) first, then re-run the synthesizer to regenerate the Implementation Brief and Acceptance Map from the updated sources.
+- **Coordination changes only** (wave ordering, component naming, delivery notes) → update the Implementation Brief directly.
+
 **Session 1 ends here.** No branch, no commit, no PR — artifacts sit untracked in `product/features/{feature-id}/` until Session 2 picks them up.
 
 ---

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