@dug-21/unimatrix 0.5.5

package/skills/uni-store-adr/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: "uni-store-adr"
+description: "Store an architectural decision record in Unimatrix. ADRs live in Unimatrix only — no ADR files. Use after each design decision."
+---
+
+# Store ADR — Architectural Decisions in Unimatrix
+
+## What This Skill Does
+
+Stores an architectural decision record in Unimatrix as the **sole authoritative store**. ADRs are NOT written as files — Unimatrix provides search, supersession chains, and cross-feature discovery that files cannot.
+
+**Use this AFTER each design decision.** The architect is the sole ADR authority.
+
+---
+
+## How to Store a New ADR
+
+### Step 1: Search for prior ADRs in the same domain (MANDATORY)
+
+```
+mcp__unimatrix__context_search(query: "{decision domain}", category: "decision", k: 5)
+```
+
+Check if any existing ADR covers the same concern. If so, you may need to supersede it (see "How to Supersede" below).
+
+### Step 2: Store the ADR
+
+```
+mcp__unimatrix__context_store(
+  title: "ADR-NNN: {decision title}",
+  content: "## Context\n{why this decision is needed}\n\n## Decision\n{what we decided}\n\n## Consequences\n{what follows from this decision}",
+  topic: "{feature-id}",
+  category: "decision",
+  tags: ["adr", "{phase-prefix}", "{domain-tags}"],
+  source: "architect",
+  feature_cycle: "{feature-id}",
+  agent_id: "{your role name, e.g. uni-architect}"
+)
+```
+
+### Step 3: Record the entry ID
+
+Note the Unimatrix entry ID returned. Pass it to the coordinator — downstream agents and the synthesizer need ADR entry IDs to reference decisions.
+
+### Step 4: Reference in ARCHITECTURE.md
+
+In your ARCHITECTURE.md, reference ADRs by Unimatrix entry ID:
+
+```markdown
+## Decisions
+| ADR | Title | Unimatrix ID |
+|-----|-------|--------------|
+| ADR-001 | Use rmcp 0.16 with stdio | #77 |
+| ADR-002 | Additive confidence model | #85 |
+```
+
+---
+
+## How to Supersede an Existing ADR
+
+When a new decision replaces a prior one:
+
+### Step 1: Find the old ADR
+
+```
+mcp__unimatrix__context_search(query: "{domain of old decision}", category: "decision")
+```
+
+Note the old entry's ID.
+
+### Step 2: Use context_correct to supersede
+
+```
+mcp__unimatrix__context_correct(
+  original_id: {old entry ID},
+  content: "## Context\n{why the old decision is being replaced}\n\n## Decision\n{new decision}\n\n## Consequences\n{what changes}",
+  title: "ADR-NNN: {new decision title}",
+  reason: "Superseded by {feature-id}: {short explanation}"
+)
+```
+
+This automatically:
+- Deprecates the old entry
+- Creates a new entry with supersession chain
+- Preserves the old decision for historical reference
+
+---
+
+## ADR Content Guidelines
+
+**Keep ADRs to 300-800 characters.** They capture the decision, not the implementation.
+
+```
+## Context
+The briefing tool returns duties, conventions, and semantic matches.
+Duties duplicate what's already in agent definition files, consuming
+~200 tokens for zero new information.
+
+## Decision
+Remove duties from Unimatrix categories and context_briefing responses.
+Agent defs are the sole authority for role responsibilities.
+
+## Consequences
+- Briefing returns 2 sections (conventions + relevant context) instead of 3
+- ~200 tokens freed per briefing call for more useful content
+- 28 existing duty entries deprecated
+- uni-init bootstrap no longer extracts duties
+```
+
+NOT a full design document. NOT implementation details. Just: why, what, and so-what.
+
+---
+
+## Tagging Conventions
+
+| Tag Type | Examples |
+|----------|----------|
+| Always | `adr` |
+| Phase prefix | `nexus`, `vinculum`, `collective`, `cortical`, `alcove` |
+| Domain | `storage`, `serialization`, `mcp`, `embedding`, `security`, `confidence` |
+| Cross-cutting | `error-handling`, `async`, `thread-safety`, `api-design` |
+
+---
+
+## Self-Verification
+
+After storing:
+- Confirm entry ID returned
+- If **near-duplicate warning**: review existing entry — you may need to supersede rather than create
+- Record entry ID in your agent report and ARCHITECTURE.md decisions table
+
+---
+
+## What NOT to Store as ADRs
+
+| Don't Store | Why |
+|-------------|-----|
+| Draft decisions under discussion | Store only finalized decisions |
+| Implementation details (how) | ADRs capture the why — code captures the how |
+| Decisions by other agents | Architect is the sole ADR authority |
+| Coding conventions | Use `convention` category instead |
+| Step-by-step procedures | Use `/uni-store-procedure` instead |

package/skills/uni-store-lesson/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: "uni-store-lesson"
+description: "Store a lesson learned from a failure, gate rejection, or unexpected issue. Use after bugfixes and gate failures to prevent recurrence."
+---
+
+# Store Lesson — Failure Knowledge
+
+## What This Skill Does
+
+Stores a lesson learned in Unimatrix. Lessons capture what went wrong, why, and the takeaway. They surface in future briefings and searches to prevent the same failure from recurring.
+
+**Use after:** gate failures, bug diagnoses, unexpected issues, rework cycles.
+
+---
+
+## How to Store
+
+### Step 1: Check for existing lessons in the same area
+
+```
+mcp__unimatrix__context_search(
+  query: "{what went wrong}",
+  category: "lesson-learned",
+  k: 3
+)
+```
+
+If a matching lesson already exists, go to Step 2b (supersede) instead of creating a duplicate.
+
+### Step 2a: Store NEW lesson (no prior exists)
+
+```
+mcp__unimatrix__context_store(
+  title: "{concise description of what went wrong}",
+  content: "{structured lesson content}",
+  topic: "{feature-id or crate}",
+  category: "lesson-learned",
+  tags: ["{domain}", "{failure-type}"],
+  agent_id: "{your role name, e.g. uni-architect}"
+)
+```
+
+### Step 2b: Supersede EXISTING lesson (prior exists but is incomplete or outdated)
+
+```
+mcp__unimatrix__context_correct(
+  original_id: {old entry ID},
+  content: "{updated lesson with new evidence or broader scope}",
+  reason: "Updated: {what new evidence or context was added}"
+)
+```
+
+This deprecates the old lesson and creates a corrected version with a supersession chain. Future searches return the latest version.
+
+### When to deprecate without replacing
+
+If a lesson is simply wrong or no longer applies (e.g., the underlying code was redesigned):
+
+```
+mcp__unimatrix__context_deprecate(id: {entry ID}, reason: "{why it no longer applies}")
+```
+
+---
+
+## Content Format
+
+Structure as: **What happened -> Root cause -> Takeaway** (200-500 chars):
+
+```
+Gate 3b rejected: confidence calculation used f32 intermediate values
+despite f64 pipeline decision (ADR-003). Root cause: rust-dev didn't
+read ADR before implementing. Takeaway: MANDATORY ADR read step in
+rust-dev pseudocode consumption is not optional — validator should
+check ADR compliance explicitly.
+```
+
+NOT a full incident report. NOT a narrative. Just the facts that prevent recurrence.
+
+---
+
+## Tagging Conventions
+
+| Tag type | Examples |
+|----------|----------|
+| Failure type | `gate-failure`, `bug`, `rework`, `regression`, `scope-fail` |
+| Gate | `gate-3a`, `gate-3b`, `gate-3c` |
+| Domain | `confidence`, `storage`, `mcp`, `testing` |
+| Severity | `minor`, `major`, `critical` |
+
+---
+
+## Who Stores Lessons
+
+| Agent | When |
+|-------|------|
+| uni-bug-investigator | After diagnosing root cause — store the generalizable pattern |
+| uni-validator | After gate failure — store what the gate caught and why |
+| Coordinator | After rework cycle — store what caused the rework |
+| Retrospective agents | After analyzing session data — store systemic issues |
+
+---
+
+## What Makes a Good Lesson
+
+**Generalizable** — applies beyond this one incident. "Off-by-one in loop" is not a lesson. "Boundary conditions at table scan limits not covered by unit tests" is.
+
+**Actionable** — the takeaway prevents recurrence. "Be more careful" is not actionable. "Add boundary condition tests for every table scan method" is.
+
+**Concise** — 200-500 chars. If it needs more, it's probably a procedure or a pattern, not a lesson.

package/skills/uni-store-pattern/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: "uni-store-pattern"
+description: "Store a reusable implementation pattern in Unimatrix. Use when you discover a gotcha, trap, or reusable solution that future agents should know."
+---
+
+# Store Pattern — Implementation Knowledge
+
+## What This Skill Does
+
+Stores a reusable pattern in Unimatrix. Patterns capture implementation gotchas, traps, and solutions — knowledge invisible in source code that you only learn by hitting it. They surface in future `/uni-query-patterns` results so the next agent doesn't repeat the discovery.
+
+**Use when:** you discover something that compiles but breaks at runtime, a non-obvious integration requirement, a crate-specific trap, or a reusable solution to a recurring problem.
+
+---
+
+## Pattern vs Lesson vs Procedure
+
+| Type | When to use | Example |
+|------|------------|---------|
+| **Pattern** (`/uni-store-pattern`) | Reusable solution or gotcha applicable regardless of failure context | "Don't hold lock_conn() across await — deadlocks under concurrent requests" |
+| **Lesson** (`/uni-store-lesson`) | Triggered by a specific failure; takeaway is preventive | "Gate 3b failed because rust-dev didn't read ADR before implementing" |
+| **Procedure** (`/uni-store-procedure`) | Ordered steps to accomplish a task | "How to add a new MCP tool: step 1, 2, 3..." |
+
+**Decision rule:** If the knowledge was triggered by a specific failure and the takeaway is "don't do X," use `/uni-store-lesson`. If the knowledge is a reusable solution applicable regardless of failure context — "when doing X, use approach Y because Z" — use `/uni-store-pattern`.
+
+---
+
+## How to Store
+
+### Step 1: Check for existing patterns in the same area
+
+```
+mcp__unimatrix__context_search(
+  query: "{what the pattern is about}",
+  category: "pattern",
+  k: 3
+)
+```
+
+If a matching pattern already exists, go to Step 2b (supersede) instead of creating a duplicate.
+
+### Step 2a: Store NEW pattern (no prior exists)
+
+Assemble the content from three required fields:
+
+- **What**: The pattern in one sentence (max 200 chars). What to do or not do.
+- **Why**: What goes wrong without it (min 10 chars). The consequence that makes this worth knowing.
+- **Scope**: Where it applies — crate name, module, or context.
+
+```
+mcp__unimatrix__context_store(
+  title: "{concise what statement}",
+  content: "What: {what}\nWhy: {why}\nScope: {scope}",
+  topic: "{crate name or module — e.g., 'unimatrix-store'}",
+  category: "pattern",
+  tags: ["{domain}", "{feature_cycle if known}"],
+  agent_id: "{your role name, e.g. uni-rust-dev}"
+)
+```
+
+### Step 2b: Supersede EXISTING pattern (prior exists but is incomplete or outdated)
+
+```
+mcp__unimatrix__context_correct(
+  original_id: {old entry ID},
+  content: "What: {updated what}\nWhy: {updated why}\nScope: {updated scope}",
+  reason: "Updated: {what changed and why}"
+)
+```
+
+This deprecates the old pattern and creates a corrected version with a supersession chain.
+
+---
+
+## Quality Rules
+
+**Reject if:**
+- `why` is missing or under 10 characters — no motivation, no value
+- `what` exceeds 200 characters — not concise enough
+- Content is API documentation, not a gotcha — "Store has a lock_conn() method" is docs, not a pattern
+
+**Good patterns:**
+```
+What: Don't hold lock_conn() across await points
+Why: Deadlocks under concurrent MCP requests — the Store mutex is not async-aware
+Scope: unimatrix-store, any async caller
+```
+
+```
+What: Use #[serde(default)] on all new EntryRecord fields
+Why: Existing serialized records lack the field; deserialization panics without default
+Scope: unimatrix-core EntryRecord, any schema evolution
+```
+
+**Bad patterns:**
+```
+What: I used Arc::clone for shared ownership
+Why: It works
+```
+(No gotcha. No consequence. This is just Rust basics.)
+
+---
+
+## Tagging Conventions
+
+| Tag type | Examples |
+|----------|----------|
+| Crate | `store`, `server`, `vector`, `core`, `embed`, `engine` |
+| Domain | `async`, `serialization`, `migration`, `mcp`, `confidence` |
+| Feature cycle | `vnc-009`, `crt-005` (for retro traceability) |
+
+---
+
+## Who Stores Patterns
+
+| Agent | When |
+|-------|------|
+| uni-rust-dev | Implementation gotchas discovered while coding |
+| uni-tester | Test infrastructure patterns, fixture usage discoveries |
+| uni-risk-strategist | Risk patterns that recur across features |
+| uni-researcher | Technical landscape patterns from problem space exploration |
+| uni-vision-guardian | Recurring alignment variance patterns across features |
+| uni-validator | Quality patterns (cross-feature, not gate-specific) |
+| Retrospective agents | Patterns extracted from shipped feature analysis |

package/skills/uni-store-procedure/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: "uni-store-procedure"
+description: "Store or update a technical procedure (how-to) in Unimatrix. Use during retrospectives when a technique has evolved or been discovered."
+---
+
+# Store Procedure — Technical How-To Knowledge
+
+## What This Skill Does
+
+Stores a step-by-step technical procedure in Unimatrix. Procedures describe HOW to accomplish specific tasks in this project. They evolve as the project evolves.
+
+**Use during retrospectives** — not while implementing. Procedures are extracted from evidence, not guessed mid-session.
+
+---
+
+## Procedure vs Convention vs Pattern
+
+| Type | What it is | Example |
+|------|-----------|---------|
+| **Procedure** | Ordered steps to accomplish a task | "How to add a new MCP tool: step 1, 2, 3..." |
+| **Convention** | A rule or standard | "No .unwrap() in non-test code" |
+| **Pattern** | A reusable solution to a recurring problem | "Fresh context for unbiased review" |
+
+If it has **numbered steps**, it's a procedure. If it's a **rule**, it's a convention. If it's a **when/why/how solution**, it's a pattern.
+
+---
+
+## How to Store a New Procedure
+
+### Step 1: Check for existing procedure
+
+```
+mcp__unimatrix__context_search(
+  query: "{what the procedure covers}",
+  category: "procedure",
+  k: 3
+)
+```
+
+If an existing procedure covers the same task, use Step 2 (Update) instead.
+
+### Step 2a: Store NEW procedure
+
+```
+mcp__unimatrix__context_store(
+  title: "How to {task description}",
+  content: "{step-by-step content}",
+  topic: "{crate or area — e.g., 'unimatrix-server'}",
+  category: "procedure",
+  tags: ["{domain}", "{consuming-roles}"],
+  agent_id: "{your role name, e.g. uni-architect}"
+)
+```
+
+### Step 2b: UPDATE existing procedure (supersedes old version)
+
+```
+mcp__unimatrix__context_correct(
+  original_id: {old entry ID},
+  content: "{updated step-by-step content}",
+  reason: "Updated: {what changed and why}"
+)
+```
+
+This deprecates the old entry and creates a new one with a supersession chain. Agents querying later will get the latest version.
+
+---
+
+## Content Format
+
+Procedures should be **concise and actionable** (200-500 chars):
+
+```
+How to add a new MCP tool:
+1. Add validate_{tool}_params fn in validation.rs (pure, no I/O)
+2. Add format_{tool}_success fn in response.rs (summary + markdown + json)
+3. Add handler block in tools.rs match arm
+4. Add AuditEvent variant in audit.rs
+5. Add tool schema in server registration
+6. Add integration test in product/test/infra-001/
+```
+
+NOT:
+```
+When you want to add a new MCP tool to the server, you should first consider
+the validation requirements. The validation module in validation.rs contains
+pure functions that validate input parameters...
+```
+
+---
+
+## Tagging Conventions
+
+| Tag type | Examples |
+|----------|----------|
+| Crate/area | `server`, `store`, `vector`, `core`, `embed` |
+| Consuming roles | `rust-dev`, `pseudocode`, `architect` |
+| Domain | `mcp-tool`, `schema`, `testing`, `integration` |
+
+Always include at least one consuming-role tag so `/uni-query-patterns` can filter by who needs it.
+
+---
+
+## When to Store vs When to Skip
+
+**Store when:**
+- A multi-step technique was used across 2+ features
+- An existing procedure was wrong and needed correction
+- A developer had to figure out steps that should have been documented
+
+**Skip when:**
+- The technique was used once and may not recur
+- The steps are obvious to any Rust developer (not project-specific)
+- The procedure is workflow choreography (that stays in coordinator agent defs)

package/skills/unimatrix-init/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: "unimatrix-init"
+description: "Initialize Unimatrix in a repository: append knowledge block to CLAUDE.md and produce agent orientation recommendations."
+---
+
+# /unimatrix-init — Repository Initialization
+
+## Prerequisites
+
+Before running this skill:
+
+1. **Skill files installed**: Both `unimatrix-init/SKILL.md` and `unimatrix-seed/SKILL.md` must be present in `.claude/skills/` in the target repository.
+2. **MCP server wired** (for `/unimatrix-seed`): The Unimatrix MCP server (`unimatrix-server`) must be running and configured in your Claude Code `settings.json`. This skill (`/unimatrix-init`) does not require MCP, but `/unimatrix-seed` does.
+
+If you need to install the Unimatrix server or wire MCP, consult the installation documentation.
+
+---
+
+## What This Skill Does
+
+Sets up Unimatrix awareness in a repository by:
+1. Checking if Unimatrix is already initialized (idempotency guard)
+2. Scanning agent definitions for orientation gaps (read-only)
+3. Appending a self-contained Unimatrix knowledge block to CLAUDE.md
+
+**This is different from the `uni-init` agent** (`.claude/agents/uni/uni-init.md`). The `uni-init` agent performs brownfield bootstrap — it extracts knowledge from existing `.claude/agents/` and `.claude/protocols/` files into Unimatrix entries. Use `/unimatrix-init` for new repository setup (CLAUDE.md + recommendations). Use the `uni-init` agent when you already have agent definitions and want to populate Unimatrix from them.
+
+---
+
+## Arguments
+
+- **No arguments**: Run the full initialization (sentinel check, agent scan, CLAUDE.md append).
+- **`--dry-run`**: Print what would happen without modifying any files.
+
+---
+
+## Execution Steps
+
+Follow these phases in strict order. Do not skip or reorder.
+
+### Phase 1: Pre-flight — Idempotency Check
+
+**Check for `--dry-run` argument first.** If the user invoked `/unimatrix-init --dry-run`, set dry-run mode. In dry-run mode, no files will be created or modified — only terminal output.
+
+1. Check if `CLAUDE.md` exists in the repository root.
+
+2. **If CLAUDE.md exists**, read the entire file and search for this exact sentinel string:
+   ```
+   <!-- unimatrix-init v1: DO NOT REMOVE THIS LINE -->
+   ```
+
+3. **Head-check fallback for large files**: If `CLAUDE.md` has more than 200 lines, also explicitly read the last 30 lines of the file and check for the sentinel there. This catches cases where the sentinel is at the end of a large file.
+
+4. **If the sentinel is found** (in either check): Print the following and stop immediately. Do not proceed to Phase 2 or Phase 3.
+   ```
+   Already initialized. Unimatrix block found in CLAUDE.md.
+   ```
+
+5. **If CLAUDE.md does not exist**: Note this — CLAUDE.md will be created in Phase 3. Continue to Phase 2.
+
+6. **If CLAUDE.md exists but sentinel is not found**: Continue to Phase 2.
+
+---
+
+### Phase 2: Agent Scan (Read-Only)
+
+This phase produces a terminal-only recommendation report. **Do not write any files. Do not modify any agent files.**
+
+1. Glob for agent definition files: `.claude/agents/**/*.md`
+
+2. **If no agent files are found**: Print the following and continue to Phase 3.
+   ```
+   No agent files found at .claude/agents/. Skipping agent scan.
+   ```
+
+3. **For each agent file found**, read its content and check for the presence of these three patterns:
+
+   - **context_briefing**: Does the file contain `context_briefing`? (This indicates the agent calls the Unimatrix briefing tool at session start.)
+   - **Outcome reporting**: Does the file contain `/record-outcome` or reference `context_store` with `category: "outcome"`? (This indicates the agent records session outcomes.)
+   - **unimatrix-\* skill reference**: Does the file contain any reference to `unimatrix-` prefixed skills (e.g., `/unimatrix-init`, `/unimatrix-seed`)?
+
+4. **Print the Agent Orientation Report** to the terminal:
+
+   ```
+   Agent Orientation Report
+   ========================
+   Agent                          | Missing                          | Suggested Addition
+   -------------------------------|----------------------------------|------------------------------------------
+   ```
+
+   For each agent file, print a row:
+   - **Agent**: the filename (without path prefix)
+   - **Missing**: which of the three patterns are absent
+   - **Suggested Addition**: concrete, skill-level recommendation. Examples:
+     - Missing context_briefing: "Add orientation section: call context_briefing at session start for relevant knowledge"
+     - Missing outcome reporting: "Add session end: invoke /record-outcome to capture what was learned"
+     - Missing unimatrix-* skills: "Reference /unimatrix-init and /unimatrix-seed for onboarding new repos"
+     - All present: "fully wired" / "none"
+
+5. **If all agents have all three patterns**: Print after the table:
+   ```
+   All agents fully wired.
+   ```
+
+---
+
+### Phase 3: CLAUDE.md Append
+
+**If in dry-run mode**: Print the following, then print the full Unimatrix block content below, and stop. Do not create or modify any files.
+```
+DRY RUN -- the following block would be appended to CLAUDE.md:
+```
+Print the block, then:
+```
+No files were modified.
+```
+
+**If NOT in dry-run mode**:
+
+The exact block to append is:
+
+```markdown
+
+<!-- unimatrix-init v1: DO NOT REMOVE THIS LINE -->
+## Unimatrix
+
+Knowledge engine (MCP server). Makes agent expertise searchable, trustworthy, and self-improving.
+
+### Available Skills
+
+| Skill | When to Use |
+|-------|-------------|
+| `/unimatrix-init` | First-time setup: wire CLAUDE.md and get agent recommendations |
+| `/unimatrix-seed` | Populate Unimatrix with foundational repo knowledge |
+
+### Knowledge Categories
+
+| Category | What Goes Here |
+|----------|---------------|
+| `decision` | Architectural decisions (ADRs) — use `/store-adr` |
+| `pattern` | Reusable implementation patterns — use `/store-pattern` |
+| `procedure` | Step-by-step workflows — use `/store-procedure` |
+| `convention` | Project-wide coding/process standards |
+| `lesson-learned` | Post-failure takeaways — use `/store-lesson` |
+
+### When to Invoke
+
+- Before implementing anything new → search knowledge base
+- After each architectural decision → store ADR
+- After each shipped feature → run retrospective
+- When a technique evolves → update procedure
+<!-- end unimatrix-init v1 -->
+```
+
+**If CLAUDE.md exists**: Append the block to the end of the existing file. Use Edit/append semantics — do NOT overwrite the file. Preserve all existing content. Add a blank line before the block if the file does not already end with a blank line.
+
+**If CLAUDE.md does not exist**: Create CLAUDE.md with the block as its only content (without the leading blank line).
+
+After writing, confirm:
+```
+Unimatrix block appended to CLAUDE.md.
+```
+Or if created:
+```
+Created CLAUDE.md with Unimatrix block.
+```
+
+Finally, print:
+```
+Initialization complete. Run /unimatrix-seed next to populate the knowledge base.
+```