@dug-21/unimatrix 0.6.3 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dug-21/unimatrix",
-  "version": "0.6.3",
+  "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.3",
-    "@dug-21/unimatrix-linux-arm64": "0.6.3"
+    "@dug-21/unimatrix-linux-x64": "0.7.0",
+    "@dug-21/unimatrix-linux-arm64": "0.7.0"
   },
   "files": [
     "bin/",

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/unimatrix-init/SKILL.md

@@ -1,171 +0,0 @@
----
-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.
-```

package/skills/unimatrix-seed/SKILL.md

@@ -1,271 +0,0 @@
----
-name: "unimatrix-seed"
-description: "Populate Unimatrix with foundational repository knowledge through human-directed, gated exploration."
----
-
-# /unimatrix-seed — Knowledge Base Seeding
-
-## Prerequisites
-
-Before running this skill:
-
-1. **MCP server running**: The Unimatrix MCP server (`unimatrix-server`) must be running and wired in your Claude Code `settings.json`. This skill calls `context_status`, `context_search`, and `context_store` — all require an operational MCP server.
-2. **Recommended**: Run `/unimatrix-init` first to set up the CLAUDE.md knowledge block. Seeding works without it, but the CLAUDE.md block provides ongoing awareness.
-
-If `context_status` fails at startup, the MCP server is not available. Consult the installation documentation for wiring setup.
-
----
-
-## What This Skill Does
-
-Guides you through populating Unimatrix with foundational knowledge about your repository. The skill explores your repo structure in bounded levels, proposes knowledge entries, and stores only what you approve.
-
-**Depth limit**: Level 0 (automatic) + up to 2 opt-in levels. No deeper. You control how far to go.
-
-**Categories used**: Only `convention`, `pattern`, and `procedure`. Categories like `decision`, `outcome`, and `lesson-learned` are excluded from seeding — they emerge from real feature work, not initial exploration.
-
----
-
-## Entry Quality Rules
-
-Every proposed entry must pass this quality gate before being shown to you. Entries that fail are silently discarded — you only see quality entries.
-
-| Field | Rule |
-|-------|------|
-| **What** | One sentence, max 200 characters. Describes the knowledge. |
-| **Why** | Min 10 characters. Explains the consequence or motivation — what goes wrong without this knowledge. Must not be tautological (restating "what" without adding value). |
-| **Scope** | Where this applies — component, module, or workflow context. Must be present. |
-
----
-
-## Execution Steps
-
-Follow these steps in strict order. At every gate marked with **STOP**, halt and wait for the human to respond before proceeding. Do not auto-advance.
-
-### Step 1: Pre-flight — MCP Availability Check
-
-**This must be the very first action. Do not read any files before this step.**
-
-Call `context_status()`.
-
-- **If the call fails or returns an error**: Print the following and halt immediately. Do not proceed to any further steps.
-  ```
-  Unimatrix MCP is not available.
-  Ensure unimatrix-server is running and wired in your Claude settings.json.
-  See installation documentation for setup instructions.
-  ```
-
-- **If the response is healthy** (no error indicators, returns system status): Continue to Step 2.
-
----
-
-### Step 2: Existing-Entries Check
-
-Check whether seed entries already exist to avoid near-duplicates.
-
-Call `context_search` for each seeding category:
-- `context_search(query: "repository", category: "convention", k: 5)`
-- `context_search(query: "repository", category: "pattern", k: 5)`
-- `context_search(query: "repository", category: "procedure", k: 5)`
-
-Count the total results across all three searches.
-
-**If 3 or more entries found**:
-
-Print:
-```
-Found {count} existing entries in seeding categories (convention/pattern/procedure).
-Re-seeding may create near-duplicates. You can save tokens by skipping if the knowledge base already has a good foundation.
-
-Options:
-  supplement — continue and add new knowledge alongside existing entries
-  skip — exit without changes
-```
-
-**STOP. Wait for human response before proceeding.**
-
-- If the human says **skip**: Print "No changes made." and halt.
-- If the human says **supplement**: Continue to Step 3.
-
-**If fewer than 3 entries found**: Continue to Step 3 (clean first run).
-
----
-
-### Step 3: Level 0 — Automatic Foundational Exploration
-
-Read the following files without requiring human confirmation. Skip any that do not exist:
-
-- `README.md`
-- `CLAUDE.md`
-- `Cargo.toml` (Rust)
-- `package.json` (Node.js)
-- `pyproject.toml` (Python)
-- `go.mod` (Go)
-- List the `.claude/` directory structure (if present) — directory listing only, not deep file reads
-
-From what you read, generate 2 to 4 high-level foundational entries. Typical entries cover:
-
-- **Repository purpose**: What this project does and why it exists
-- **Technology stack**: Primary language, framework, key dependencies
-- **Project structure**: How the codebase is organized (monorepo, workspace, key directories)
-- **Key conventions**: Any obvious conventions visible in top-level config (naming, formatting, etc.)
-
-Apply the quality gate (What/Why/Scope) to each candidate. Silently discard any that fail. If fewer than 2 entries pass the gate, include only what passes — do not pad with low-quality entries.
-
-If 0 entries pass the quality gate:
-```
-Could not generate quality entries from available files. Consider adding a README.md with project context, then re-run /unimatrix-seed.
-```
-Skip to the Done summary.
-
----
-
-### Step 4: Gate 0 — Batch Approval
-
-Present all Level 0 entries as a batch:
-
-```
-Level 0 — Foundational Knowledge
-=================================
-Proposed entries (approve or reject as a batch):
-
-  1. [convention] {what}
-     Why: {why}
-     Scope: {scope}
-
-  2. [pattern] {what}
-     Why: {why}
-     Scope: {scope}
-
-  ...
-
-Approve all entries? (approve / reject)
-```
-
-**STOP. Wait for human response before proceeding.**
-
-- **If approved**: Store each entry via `context_store`:
-  ```
-  context_store(
-    title: "{what}",
-    content: "What: {what}\nWhy: {why}\nScope: {scope}",
-    topic: "{repo name or top-level context}",
-    category: "{convention|pattern|procedure}",
-    tags: ["seed", "level-0"],
-    agent_id: "unimatrix-seed"
-  )
-  ```
-  Report success or failure for each entry individually. If a `context_store` call fails, report which entry failed and continue storing the remaining entries.
-
-  Print: "Stored {count} entries."
-
-- **If rejected**: Print "0 entries stored. Re-invoke /unimatrix-seed with more specific guidance if needed." and skip to the Done summary.
-
-After storing (or rejecting), present the Level 1 exploration menu:
-
-```
-Would you like to explore deeper? Options:
-  a) Module structure — explore source directories and key modules
-  b) Conventions — look for coding standards, linting, formatting config
-  c) Build & test — explore build system, test framework, CI config
-  d) Done — stop here
-```
-
-**STOP. Wait for human response before proceeding.**
-
-- If the human selects one or more options (a, b, c, or combinations): Continue to Step 5 with those selections.
-- If the human selects **d (Done)**: Skip to the Done summary.
-
----
-
-### Step 5: Level 1 — Category Exploration (Opt-in)
-
-For each category the human selected, explore relevant files:
-
-- **Module structure**: Read `src/` or `lib/` directory listings, key module entry points, workspace member crates
-- **Conventions**: Read `.editorconfig`, `.eslintrc`, `rustfmt.toml`, `.clippy.toml`, `.prettierrc`, similar config files
-- **Build & test**: Read CI config (`.github/workflows/`, `Makefile`, `justfile`), test directory structure, build scripts
-
-For each entry generated from exploration, apply the quality gate. For entries that pass, present them **individually** (not as a batch):
-
-```
-Proposed entry:
-  [{category}] {what}
-  Why: {why}
-  Scope: {scope}
-
-Store this entry? (yes / no)
-```
-
-**STOP. Wait for human response before proceeding.**
-
-- **yes**: Store via `context_store` with tags `["seed", "level-1"]`. Report success or failure.
-- **no**: Skip this entry.
-
-Continue until all Level 1 entries have been presented.
-
----
-
-### Step 6: Gate 1 — Level 2 Decision
-
-```
-Level 1 complete. Stored {count} new entries.
-
-Level 2 is the final exploration level. Would you like to go deeper into any area?
-  a) {list deeper explorations based on Level 1 selections — e.g., "specific module internals", "test patterns", "CI pipeline details"}
-  b) Done — stop here
-```
-
-**STOP. Wait for human response before proceeding.**
-
-- If the human selects a deeper exploration: Continue to Step 7.
-- If the human selects **Done**: Skip to the Done summary.
-
----
-
-### Step 7: Level 2 — Deep Exploration (Final Level)
-
-Explore the selected areas in greater depth. Read specific files within the directories explored at Level 1.
-
-For each entry generated, apply the quality gate and present individually (same as Level 1):
-
-```
-Proposed entry:
-  [{category}] {what}
-  Why: {why}
-  Scope: {scope}
-
-Store this entry? (yes / no)
-```
-
-**STOP. Wait for human response before proceeding.**
-
-Store approved entries with tags `["seed", "level-2"]`.
-
----
-
-### Step 8: Gate 2 — Terminal
-
-After Level 2 entries are processed:
-
-```
-Level 2 complete. This is the final exploration level. No further levels are available.
-```
-
-Proceed directly to the Done summary. **Do not offer a Level 3 option. Level 2 is the terminal level.**
-
----
-
-### Done Summary
-
-```
-Seed Summary
-============
-Total entries stored: {total}
-  Level 0: {l0_count}
-  Level 1: {l1_count}
-  Level 2: {l2_count}
-
-Knowledge base is ready. Future context_briefing calls will return these entries
-to agents working in this repository.
-```