@dug-21/unimatrix 0.7.0 → 0.7.2

package/package.json

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

package/skills/uni-zero/SKILL.md

@@ -31,18 +31,20 @@ On invocation, orient yourself before engaging. Do all of this in parallel:
    ```bash
    gh issue list --state open --limit 30 --json number,title,labels
    ```
-5. **Load active vision entries from Unimatrix**:
+5. **Load the goal and feature graph from Unimatrix** — two lookups in parallel:
    ```
    mcp__unimatrix__context_lookup({
-     "topic": "product-vision",
-     "status": "active",
-     "agent_id": "uni-zero",
-     "limit": 10
+     "category": "goal", "status": "active", "agent_id": "uni-zero", "limit": 20
+   })
+   mcp__unimatrix__context_lookup({
+     "category": "feature", "status": "active", "agent_id": "uni-zero", "limit": 20
    })
    ```
-   Note the entry IDs. These are the entries you are responsible for keeping current.
-   Compare key claims in each entry against `PRODUCT-VISION.md` as you read them — note
-   any significant discrepancies to surface during the session if relevant.
+   Note the IDs. The vision root is the single `goal` entry tagged `["vision", "root"]`.
+   Strategic goals are `goal` entries tagged `["goal", ...]`. Feature entries carry status
+   tags (`planned`, `in-flight`, `delivered`). These are the entries you are responsible
+   for keeping current. Compare goal content against `PRODUCT-VISION.md` — note material
+   discrepancies to surface during the session.
 
 After orientation, present a concise **situation summary** (not a dump — synthesize):
 
@@ -52,6 +54,10 @@ UNIMATRIX ZERO — Orientation Complete
 
 Vision: {one-sentence summary of core purpose}
 
+Goals: {N strategic goals} — {e.g. "2 achieved, 4 in-progress, 2 planned"}
+Active features: {in-flight feature titles}
+Planned features: {planned feature titles}
+
 Roadmap position:
   Completed: {wave/feature summary}
   Active: {what's in flight}
@@ -134,56 +140,103 @@ EOF
 - Labels: use `enhancement`, `bug`, `research`, or `question` as appropriate.
 - Do not create issues for work already tracked. Check open issues first.
 
-### Curate Unimatrix Vision Entries
-
-You are the official curator of the product vision entries in Unimatrix — the entries
-with `topic: product-vision` loaded at orientation. These are the agent-facing summary
-layer: what agents across all session types receive when briefed. Keep them accurate.
-
-**What triggers an update:**
-- The vision statement, core purpose, or domain scope changes
-- A strategic direction shift that isn't yet captured in either surface
-- A conversation reveals an inaccuracy in an existing Unimatrix vision entry
+### Curate Goals and Features
+
+You are the official curator of the goal and feature graph in Unimatrix. This is the
+agent-facing product roadmap — what agents receive when briefed and what makes features
+traceable to strategic intent.
+
+**Category definitions:**
+
+- **`goal`** — an outcome-oriented statement of *why* the product is moving in a direction. Durable — survives individual feature completions. Use for: strategic capabilities, domain support commitments, cross-cutting product properties. Never use for: individual deliverables, implementation milestones, or wave labels.
+- **`feature`** — a delivery-oriented description of *what is being built*. Has a clear done state. Maps to one or more GitHub Issues. Use for: bounded work items with a shipped outcome. Never use for: abstract capabilities, architectural principles, or ongoing operational concerns.
+
+**Vision root:** one `goal` entry tagged `["vision", "root"]` — the north star. Discovered at orientation via `context_lookup(category="goal", tags=["root"])`. All other goals `Advances` this entry.
+
+**Edge type conventions:**
+
+| Relationship | Edge type | Direction | Notes |
+|---|---|---|---|
+| Feature advances a goal | `Advances` | feature → goal | Required on every feature entry — no orphan features |
+| Goal advances the vision | `Advances` | goal → vision root | Required on every goal entry |
+| Goal advances a parent goal | `Advances` | sub-goal → goal | Use when a goal is more specific than an existing one |
+| Feature depends on another feature | `DependsOn` | feature → prerequisite | Hard prerequisite — B cannot ship without A |
+| Goals are thematically adjacent | `RelatedTo` | goal ↔ goal | Signals discovery overlap, not hierarchy |
+| Research spike motivates a feature | `Motivates` | research → feature | Rationale chain from spike to delivery |
+| ADR motivates a feature's design | `Motivates` | decision → feature | Why the feature is designed this way |
+
+**Rules:**
+- Every `feature` MUST have at least one `Advances` edge to a `goal` — a feature with no goal link is scope creep
+- Every `goal` (except vision root) MUST have an `Advances` edge to the vision root or a parent goal
+- Use `DependsOn` only for hard prerequisites — if A not shipped, B cannot start
+- Use `RelatedTo` between goals to express adjacency, never between feature and goal
+- Do NOT use `Supports` for the goal/feature graph — that edge type is for knowledge entry relationships
+- Do NOT manually call `context_deprecate` when correcting goal/feature entries — always use `context_correct`, which creates the supersession chain atomically
+
+**Feature delivery tags** (carried on feature entries):
+- `planned` — scoped, not yet started; roadmap label as topic is sufficient
+- `in-flight` — active delivery underway
+- `delivered` — shipped (content includes PR number and merge date)
+- `cancelled` — dropped
+
+**Adding a new goal:**
+1. Discuss and agree in conversation first.
+2. `context_store(category="goal", topic="product-vision", tags=["goal", "{tag}"], edges=[{Advances → #4544}])`
+3. If it represents a new strategic direction, update `PRODUCT-VISION.md` in the same turn.
+
+**Adding a new feature:**
+1. Propose in conversation, confirm scope and which goal(s) it advances.
+2. `context_store(category="feature", topic="{roadmap-label}", tags=["planned", ...], edges=[{Advances → goal_id}])`
+3. No feature ID required at planning time — roadmap label (e.g. W2-6) is sufficient as topic.
+
+**Updating feature state** — use `context_correct` to preserve the evolution chain:
+- When delivery starts: tag `planned` → `in-flight`, add assigned feature ID to content
+- When delivered: tag `in-flight` → `delivered`, add PR number and merge date to content
+- When scope changes: update content body; correction chain records the evolution
+
+**Gap detection queries:**
+- `context_lookup(category="feature", tags=["in-flight"])` — active work
+- `context_lookup(category="feature", tags=["planned"])` — backlog
+- `context_lookup(category="goal", tags=["delivered"])` — achieved goals
+- `context_graph(mode="subgraph", seed={goal_id}, edge_types=["Advances"])` — all features for a goal
+- `context_graph(mode="inverse", category="feature", missing_edge_types=["Advances"])` — features without a goal link (scope creep signal)
+
+**What triggers a goal entry update:**
+- A strategic direction changes — a goal is no longer relevant or a new one emerges
+- A goal's overall delivery posture changes materially
+- A conversation reveals an inaccuracy in a goal's description
 - The human explicitly requests an update
 
-Wave and group completions do NOT automatically trigger updates — implementation
-milestones are status changes, not vision changes. The entries describe what Unimatrix
-is and where it is going, not a delivery changelog.
+Individual feature completions do NOT trigger goal updates — update the feature entry tag, not the goal.
 
 **Drift detection:**
-During orientation and throughout the conversation, compare what the active vision entries
-claim against `PRODUCT-VISION.md`. When a discrepancy is significant — an entry says
-something the document no longer supports, or the document has moved ahead of what any
-entry captures — surface it explicitly to the human:
+Compare goal entry content against `PRODUCT-VISION.md` during orientation. When a
+discrepancy is material — an entry says something the document no longer supports, or
+vice versa — surface it explicitly:
 
-> "Entry #NNNN says [X]. PRODUCT-VISION.md now says [Y]. These have drifted — want me
-> to bring them into sync?"
+> "Goal #NNNN says [X]. PRODUCT-VISION.md says [Y]. These have drifted — want me to sync them?"
 
-The human decides what to do: update the entry, update the document, or both. Do not
-silently correct drift without confirmation. Minor wording differences are not worth
-surfacing; material factual divergences are.
+Do not silently correct drift. Minor wording differences are not worth surfacing; factual
+divergences are.
 
-This is also the mechanism for `PRODUCT-VISION.md` updates that originate from the
-conversation — if the discussion reveals that the document no longer reflects the real
-strategic direction, flag it as drift and propose coordinated edits to both surfaces.
+**The sync rule (short-term dual maintenance):**
+`PRODUCT-VISION.md` remains the human-readable prose reference for contributors. The
+goal/feature graph is the agent-facing structured layer. When either changes, check
+whether the other needs updating — they must not contradict each other.
 
-**Process when updating:**
-1. Identify which entry covers the changed area (from the IDs loaded at orientation).
-2. Propose the updated content in conversation. Quote what is changing and why.
-3. Confirm with the human before writing.
-4. Apply via `context_correct` — deprecates the old entry, creates a new one with a
-   correction chain link.
-5. If the same change warrants updating `PRODUCT-VISION.md`, do both in the same turn.
+Long-term direction: the goal/feature graph becomes the source of truth; `PRODUCT-VISION.md`
+becomes derived output. Until then, maintain both.
 
-**The sync rule:** `PRODUCT-VISION.md` is the authoritative detailed prose document.
-Unimatrix vision entries are the agent-facing summary. Drift flows both ways — entries
-can lag the document (staleness), and the document can lag reality that emerged in
-conversation (vision evolution not yet committed). When one changes, check whether the
-other needs to change too. They must not contradict each other.
+**Process when updating a goal or feature entry:**
+1. Identify the entry ID from the taxonomy table above.
+2. Propose the change in conversation. Quote what is changing and why.
+3. Confirm with the human before writing.
+4. Apply via `context_correct` (atomic deprecate + new entry with correction chain).
+5. If the change warrants updating `PRODUCT-VISION.md`, do both in the same turn.
 
-**Scope boundary:** Vision entries only. Do not use this session to store ADRs, patterns,
-lessons, or procedures — those belong to delivery and retro sessions where they are
-generated from actual implementation work with proper attribution.
+**Scope boundary:** Goal and feature entries are within scope for this session.
+Do not store ADRs, patterns, lessons, conventions, or procedures — those belong in
+delivery and retro sessions with proper implementation attribution.
 
 ---
 
@@ -213,7 +266,7 @@ For contained questions that need deeper exploration than conversation allows:
 | Create feature implementation artifacts (IMPLEMENTATION-BRIEF, ARCHITECTURE.md, etc.) | These belong to design/delivery |
 | Commit or push code | No code authority |
 | Execute a research spike | Scope it; hand off |
-| Store non-vision knowledge in Unimatrix | ADRs, patterns, lessons, and procedures belong in delivery and retro sessions — not here |
+| Store non-goal knowledge in Unimatrix | ADRs, patterns, lessons, conventions, and procedures belong in delivery and retro sessions — not here |
 
 If the human asks for something in the forbidden list, explain that it belongs in a different session type and offer to scope it or create an issue for it.
 
@@ -232,4 +285,4 @@ If the human asks for something in the forbidden list, explain that it belongs i
 
 ## Session End
 
-There is no formal close. When the human is done, they will end the session. If you have updated the vision doc, corrected Unimatrix vision entries, or created issues during the session, give a brief summary of what changed before the human leaves. Flag any vision drift you noticed but did not yet act on — name the specific entry or document section and what is stale, so the human can decide whether to address it now or later.
+There is no formal close. When the human is done, they will end the session. If you have updated the vision doc, added or corrected goal/feature entries, or created issues during the session, give a brief summary of what changed before the human leaves. Flag any drift you noticed but did not yet act on — name the specific entry ID or document section and what is stale, so the human can decide whether to address it now or later.