# MuseHub Roadmap

**Program:** Knowtation domain — vault-native VCS intelligence for agent knowledge systems.

**Authority:** This document governs work in the **MUSE_HUB workspace** (`gabriel-muse`, `musehub`, and related repos). It is **separate** from Scooling's `docs/ROADMAP.md`. Scooling consumes Knowtation via REST/MCP adapters in parallel; it does not block this track.

**Source spec:** [gabriel/muse issue #2](https://staging.musehub.ai/gabriel/muse/issues/2) (frozen phase order — each phase unlocks the next for *new* work; local code may span multiple phases).

**Handover relay:** `docs/MUSEHUB-OVERSEER-HANDOVER.md` — paste the **NEXT SESSION** block into a fresh chat.

---

## Phase Model Key

| Label | Meaning |
| --- | --- |
| **Thinking** | Contract, architecture, open-question resolution, test matrix — freeze spec before build |
| **Auto** | Mechanical implementation against a frozen spec; run tests; Muse commit on feature branch |
| **Thinking → Auto** | Split into `{step}a` (Thinking) then `{step}b` (Auto) in the handover doc |
| **Operator + Auto** | Tier 3 human authorization for staging push / live gate; Auto for implementation |

**Handover rule:** Every next-step table and paste block **must** include **`Model:`**.

---

## Next step at a glance (2026-07-10)

| Item | Status |
| --- | --- |
| **Active track** | Knowtation domain — open questions (KD-OQ) |
| **Plugin code (Phases 1–4, 7)** | **DONE locally** — `gabriel-muse/muse/plugins/knowtation/` (26 modules, 27 test files) |
| **Staging plugin repo** | **DONE** — `aaronrene/gabriel-muse` @ `sha256:660fcac1…` (2026-06-21) |
| **Marketplace registration** | **DONE** — `@aaronrene/knowtation` on staging (2026-07-05); `viewer_type: generic` (optional fix) |
| **Vault activation smoke** | **DONE** — `knowtation-vault-smoke` (5 PASS / 3 PARTIAL — see handover matrix) |
| **NEXT** | **KD-OQ** — resolve issue #2 open questions (Thinking) |
| **Parked** | KD-5a/b (MCP), KD-6 (Hub UI) — after KD-OQ |
| **Parallel (Scooling)** | Phase 9A overseer gates — independent |

---

## Build status table

| ID | Phase | Repo(s) | Model | Status |
| --- | --- | --- | --- | --- |
| **KD-0** | Recovery + rc14 re-baseline | gabriel-muse | Auto | **DONE** (2026-06-20) — corrupt rc3 history discarded; code intact; 1570 tests green |
| **KD-SD8-PUSH** | Push plugin to staging | gabriel-muse | Auto (Tier 3) | **DONE** (2026-06-21) — `aaronrene/gabriel-muse` @ `660fcac1…` |
| **KD-SD8-REG** | Marketplace registration | musehub (API) | Auto (Tier 3) | **DONE** (2026-07-05) — `@aaronrene/knowtation`; `viewer_type: generic` (fix optional) |
| **KD-1** | Domain foundation (detector, parser, plugin, symbols, domain-info) | gabriel-muse | Auto | **DONE** — proven on vault smoke (domain-info PASS; symbols CLI PARTIAL) |
| **KD-2** | Semantic diff & harmony merge | gabriel-muse | Auto | **DONE** — differ/merger API proven; CLI merge/diff PARTIAL (see handover) |
| **KD-3** | Code intelligence (deps, impact, hotspots, dead, clones, entangle, velocity) | gabriel-muse | Auto | **DONE** — deps/impact/hotspots/dead PASS on test vault |
| **KD-4** | Memory timeline (event schema, symbol-log, consolidation hook, prime) | gabriel-muse | Auto | **DONE** — log event_type PASS; prime_context API PASS (no CLI hook) |
| **KD-7** | Attestation & ICP push hook | gabriel-muse | Auto | **DONE** (local; attestation smoke post-activation) |
| **KD-ACTIVATE** | Vault activation + Phase 1–4 smoke | gabriel-muse + test vault | **Auto** | **DONE** (2026-07-10) — `knowtation-vault-smoke`; 5 PASS / 3 PARTIAL |
| **KD-OQ** | Resolve issue #2 open questions (5 items) | gabriel-muse + musehub | **Thinking** | **NEXT** — gate for KD-5a |
| **KD-5a** | MCP domain surface — contract + test matrix | gabriel-muse + musehub | **Thinking → Auto** | **TODO** — blocked on KD-OQ |
| **KD-5b** | MCP domain surface — implementation (9 tools, 8 resources, 3 prompts) | gabriel-muse + musehub | Auto | **TODO** |
| **KD-6a** | MuseHub vault UI — contract + test matrix | musehub | **Thinking → Auto** | **TODO** — blocked on KD-1 smoke + KD-2 diff UI needs |
| **KD-6b** | MuseHub vault UI — implementation | musehub | Auto | **TODO** |

---

## Repo boundaries

| Repo | Role in this program | VCS |
| --- | --- | --- |
| **gabriel-muse** | Canonical home of `muse/plugins/knowtation/` — detector, parser, merger, code intel, attestation | Muse; staging remote `aaronrene/gabriel-muse` |
| **musehub** | Marketplace API, domain registration, Phase 6 vault-centric UI, MCP server mount | Muse / git per repo convention |
| **knowtation** (product) | Vault store, Hub API, MCP — **not** the Muse domain plugin | Separate; Scooling adapter target |
| **knowtation-vault-smoke** | KD-ACTIVATE test vault — **not** product repo | Local Muse repo; `domain=knowtation` |
| **scooling** | Consumer UI — parallel track; wires domain features **after** KD-5/KD-6 land | See Scooling governance docs |

**Important:** The Knowtation **product repo** (`.museattributes` → `domain = "code"`) is not a vault repo. Activation uses a **vault repo** — Markdown notes with Knowtation frontmatter (`source_type`, `source_id`, `project`, `tags`, `entity`).

---

## Phase detail (frozen from issue #2)

### KD-1 — Domain Foundation

**Goal:** Muse recognises Knowtation vault files as a distinct domain and introspects them structurally.

**Deliverables (verified in tree):**

- `detector.py`, `parser.py`, `plugin.py`, `symbols.py`, `stats.py`
- `defaults.museattributes` snippet
- `muse domain-info --json` shape; `muse code symbols --file note.md`

**Exit criteria:** KD-ACTIVATE smoke PASS on a real vault repo — **MET** (domain-info PASS; symbols CLI routes through code AST — gap recorded).

---

### KD-2 — Semantic Diff & Harmony Merge

**Goal:** Section-aware diff; policy-based merge for tags, entities, source_id conflicts.

**Deliverables (verified in tree):**

- `differ.py`, `merger.py`, `policies.py`, `strategies.py`, `rerere.py`
- Harmony policies for tag union, entity union, prefer-newer-date, §Summary escalation

**Exit criteria:** `muse merge` resolves tag/entity conflicts without raw-text panics — **PARTIAL** (`merge_notes` union PASS; `muse merge` CLI file-conflict on tag-only divergence).

---

### KD-3 — Code Intelligence

**Goal:** `muse code deps`, `impact`, `hotspots`, `gravity`, `dead`, `clones`, `entangle`, `velocity` on vault repos.

**Deliverables (verified in tree):**

- `link_index.py`, `code_intel.py`, `note_metrics.py`, `cli_hooks.py`

**Exit criteria:** All six commands return meaningful JSON on test vault — **MET** (deps, impact, hotspots, dead verified).

---

### KD-4 — Memory Timeline

**Goal:** Memory event types in commit metadata; symbol-log as memory replay; prime bootstrap from commit graph.

**Deliverables (verified in tree):**

- `events.py` (15 event kinds, schema locked v1.0.0)
- `hooks.py` (consolidation pre-merge)
- `prime_context.py` (`knowtation://prime` from commit graph)

**Exit criteria:** `muse log --json` surfaces `event_type`; prime JSON smoke PASS — **MET** (log PASS; prime via `build_prime_context` API, no CLI).

---

### KD-5 — MCP Domain Surface (not started)

**Goal:** Knowtation domain ops via Muse MCP (`knowtation/search`, `get-note`, `history`, `impact`, `dead`, `prime`, `propose`, `attest` + resources + prompts).

**Entry criteria:** KD-ACTIVATE PASS; KD-OQ resolved.

**Model:** Thinking → Auto (split in handover when NEXT).

---

### KD-6 — MuseHub UI for Vault Repos (not started)

**Goal:** Domain-aware repo landing, note detail page, knowledge proposals UI, vault search.

**Entry criteria:** KD-1 symbols + KD-2 diff available on staging vault; KD-5 tools optional but recommended.

**Repo:** `musehub/` primarily.

**Model:** Thinking → Auto.

---

### KD-7 — Attestation (done locally, verification pending)

**Goal:** HMAC attestation, ICP push hook, verify-commit --attest, provenance strip on Hub.

**Deliverables (verified in tree):** `attestation.py`, `icp_push_hook.py`, `quorum.py`

**Exit criteria:** Attestation smoke on staging vault with `--attest` flag (post KD-ACTIVATE).

---

## Open questions (issue #2 — resolve in KD-OQ)

Record decisions here when KD-OQ closes; do not guess during build.

| # | Question | Options (summary) | Decision |
| --- | --- | --- | --- |
| 1 | Vault detection boundary | Frontmatter-only vs require `.knowtation` / `config/local.yaml` marker | **TBD** |
| 2 | Vector index ownership | Muse parallel index vs query Knowtation `data/` index directly | **TBD** |
| 3 | Consolidation daemon coupling | `muse merge --consolidate` pre-hook vs async watcher | **TBD** |
| 4 | ICP canister reuse | Knowtation Motoko canister vs generic Muse attestation interface | **TBD** |
| 5 | SKILL.md agent discovery | Merge into Muse `agent.md` vs keep separate | **TBD** |

---

## Cross-repo coordination (read-only pointers)

| Document | Repo | Purpose |
| --- | --- | --- |
| `docs/CROSS-REPO-COORDINATION.md` | scooling | SD-8 namespace decision; canonical-first ordering |
| `docs/KNOWTATION-MUSEHUB-WIRING.md` | scooling | How Scooling will consume domain features long-term |
| `docs/VERIFICATION-MATRIX.md` | scooling | Source-backed facts on plugin manifest |
| `musehub/docs/issues/custom-domain-registration.md` | musehub | Marketplace URL + author-identity hardening notes |

Scooling **Phase 1 rule:** must not require live MuseHub or production Knowtation Domain. Domain activation does not block Scooling Phase 9A.

---

## Governance hygiene (manual until orchestrator is live)

At **session end** for any KD phase:

1. Update **this file** — build status table, "Next step at a glance", phase Status lines.
2. Update **`docs/MUSEHUB-OVERSEER-HANDOVER.md`** — rotate NEXT SESSION, verified snapshot, VCS table, change log, paste-ready prompt.
3. Muse commit on feature branch (Tier 1); staging push / merge to `main` only with Tier 3 authorization.
4. Run test suite for touched areas before commit.

A session that ends without both governance docs updated is **incomplete**.

**Orchestrator:** The cross-workspace overseer orchestrator (Scooling session) is **not required** for this track yet. Use these two docs manually until that tooling ships.

---

## Verified snapshot (2026-07-10)

| Fact | Source |
| --- | --- |
| Plugin path | `~/MUSE_HUB/gabriel-muse/muse/plugins/knowtation/` — 26 `.py` files |
| Test files | `~/MUSE_HUB/gabriel-muse/tests/test_knowtation_*.py` — 27 files |
| Last full-suite count | 1570 passed, 0 failed (2026-06-20 recovery) |
| Staging plugin repo | `https://staging.musehub.ai/aaronrene/gabriel-muse` — HTTP 200 |
| Marketplace listing | `@aaronrene/knowtation` — version 1.0.0, 6 dimensions, `install_count: 0` |
| Test vault | `~/MUSE_HUB/knowtation-vault-smoke` — 3 notes, `domain=knowtation`, Harmony policies |
| Issue tracker | [gabriel/muse #2](https://staging.musehub.ai/gabriel/muse/issues/2) — assigned aaronrene |

---

## Change log

- **2026-07-10** — **KD-ACTIVATE DONE.** Vault `knowtation-vault-smoke` activated; smoke 5 PASS / 3 PARTIAL. NEXT → KD-OQ. CLI gaps documented (merge dispatch, symbols routing, diff granularity).
- **2026-07-10** — Initial MuseHub Roadmap created. Phases 1–4 + 7 marked DONE (local); KD-ACTIVATE set as NEXT.