memtrace 0.5.14 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace",
-  "version": "0.5.14",
+  "version": "0.6.0",
   "description": "Code intelligence graph — MCP server + AI agent skills + visualization UI",
   "keywords": [
     "mcp",
@@ -39,11 +39,11 @@
     "fs-extra": "^11.0.0"
   },
   "optionalDependencies": {
-    "@memtrace/darwin-arm64": "0.5.14",
-    "@memtrace/linux-x64": "0.5.14",
-    "@memtrace/win32-x64": "0.5.14",
-    "@memtrace/linux-x64-noavx2": "0.5.14",
-    "@memtrace/win32-x64-noavx2": "0.5.14"
+    "@memtrace/darwin-arm64": "0.6.0",
+    "@memtrace/linux-x64": "0.6.0",
+    "@memtrace/win32-x64": "0.6.0",
+    "@memtrace/linux-x64-noavx2": "0.6.0",
+    "@memtrace/win32-x64-noavx2": "0.6.0"
   },
   "engines": {
     "node": ">=18"

package/skills/commands/memtrace-fleet-publish-intent.md

@@ -0,0 +1,51 @@
+---
+name: memtrace-fleet-publish-intent
+description: "Use to declare a structural intent BEFORE editing in a fleet — what symbols you'll touch and why — so other agents on your branch coordinate around you. Triggered by: 'I'm about to edit/rename/refactor X', starting any non-trivial edit while other agents share your repo+branch. Returns the graph blast radius, overlapping live intents on your branch, and a shift-left coordination/partition hint. Do not start editing shared symbols without publishing first."
+allowed-tools:
+  - mcp__memtrace__fleet_publish_intent
+  - mcp__memtrace__fleet_preflight
+---
+
+## Overview
+
+`fleet_publish_intent` is step 1 of the fleet protocol: announce what you're about
+to touch so other agents on the **same `(repo, branch)`** coordinate around you.
+It's a typed, ~20-token declaration — not prose.
+
+## Call it
+
+```jsonc
+fleet_publish_intent({
+  repo_id: "myrepo",
+  branch:  "session/auth-revamp",      // your fleet's session branch
+  agent_id:"agent-a",
+  touched: ["auth::verify_token"],     // qualified symbol identities
+  intent:  {"refactor": {"pattern": "change_signature"}},
+  assignment: "widen verify_token signature for pagination"   // the alignment anchor
+})
+```
+
+You get back:
+- `impact_preview` — the real graph blast radius of the touched symbols.
+- `active_conflicts` — overlapping live intents **on your branch** (none from other
+  branches; coordination is branch-scoped).
+- `coordination` — a shift-left hint: `would_escalate`, a `suggested_partition`
+  (who should own a contested symbol), and advice to realign *before* you edit.
+
+## Intent kinds (JSON, snake_case, externally-tagged)
+
+- `{"refactor":{"pattern":"rename_symbol"|"change_signature"|"move_symbol"|"extract_function"|…}}`
+- `{"feature_add":{"surface":"new_symbol"|"new_endpoint"|…}}`
+- `{"bug_fix":{"defect":"logic_error"|"null_handling"|…}}`
+- `{"cleanup":{"kind":"dead_code"|"unused_import"|…}}`
+- `{"performance":{"axis":"latency"|…}}`, `{"security_fix":{"severity":"high"}}`,
+  `{"test_add":{"covers":[…]}}`, `"docs_only"`, `"exploratory"`
+
+**Destructive** kinds — `change_signature`, `move_symbol`, `cleanup/dead_code` —
+are what raise a Class C decision when they overlap another agent's work.
+
+## Rules
+
+- Always pass `branch` (your session branch) and `assignment` (your task).
+- Read-only check first? Use `fleet_preflight` (same inputs, no registration).
+- An empty `active_conflicts` is good — proceed and `fleet_record_episode` when done.

package/skills/commands/memtrace-fleet-record-episode.md

@@ -0,0 +1,48 @@
+---
+name: memtrace-fleet-record-episode
+description: "Use AFTER an edit in a fleet to record it and get its conflict class (A/B/C) against agents on your branch. Triggered by: finishing an edit, 'I just changed X', completing a refactor step while other agents share your repo+branch. Returns conflict_class + replan_hint; a Class C returns an escalation_id and mediation_request that starts the decision loop. Do not finish a coordinated edit without recording it."
+allowed-tools:
+  - mcp__memtrace__fleet_record_episode
+  - mcp__memtrace__fleet_get_escalation
+  - mcp__memtrace__fleet_query_episodes
+---
+
+## Overview
+
+`fleet_record_episode` is step 3 of the fleet protocol: record the edit you just
+made and learn whether it collided with another agent on your branch.
+
+## Call it
+
+```jsonc
+fleet_record_episode({
+  repo_id: "myrepo",
+  branch:  "session/auth-revamp",
+  agent_id:"agent-a",
+  touched: ["auth::verify_token"],
+  intent:  {"refactor": {"pattern": "change_signature"}}
+})
+```
+
+## The result: conflict_class
+
+- **A → proceed.** Additive, order-independent.
+- **B → re-read, then proceed.** Non-destructive overlap; re-read the shared
+  symbols so you build on current state.
+- **C → a decision is needed.** A destructive change overlaps another agent's
+  work. The response includes:
+  - `escalation_id` — the decision's id.
+  - `mediation_request` — the judging task (every agent's `assignment` + the
+    contested symbols). If you're asked to judge, call `fleet_submit_verdict`.
+  - `next_action` — poll `fleet_get_escalation({escalation_id, agent_id})` until
+    `your_directive` ≠ `wait`, then `proceed` / `defer` / `review`.
+
+Class is computed **only against agents on your branch**. Agents on other branches
+never make your edit a Class C.
+
+## After recording
+
+- Class A/B → continue.
+- Class C → enter the decision loop (see `memtrace-fleet-coordination`). Don't keep
+  editing the contested symbols until your directive is `proceed`.
+- Review history with `fleet_query_episodes({repo_id, node?, conflict_class?})`.

package/skills/commands/memtrace-fleet-resolve.md

@@ -0,0 +1,59 @@
+---
+name: memtrace-fleet-resolve
+description: "Use to act on a Class C decision: submit your verdict as an agent judge (fleet_submit_verdict), poll your own directive (fleet_get_escalation), see the needs-human queue (fleet_list_escalations), or record a human decision (fleet_resolve_escalation). Triggered by: 'a decision is waiting', 'who should proceed', being handed a mediation_request, acting as a mediator between two agents, or a human choosing a winner in the dashboard."
+allowed-tools:
+  - mcp__memtrace__fleet_submit_verdict
+  - mcp__memtrace__fleet_get_escalation
+  - mcp__memtrace__fleet_list_escalations
+  - mcp__memtrace__fleet_resolve_escalation
+---
+
+## Overview
+
+The tools that resolve a Class C conflict. The judging is done by the user's own
+agents (no API keys): an agent reads the bundle and submits a verdict; the daemon
+is the deterministic referee that decides the outcome and routes it back.
+
+## Submit a verdict (you are the judge)
+
+You were handed a `mediation_request` (from `fleet_record_episode`). Read **every
+agent's `assignment`** in it and decide on merit — including against your own
+change:
+
+```jsonc
+fleet_submit_verdict({
+  escalation_id: "01J…",
+  agent_id: "agent-a",
+  verdict: { "kind": "recommend", "winner": "agent-b",
+             "rationale": "wider contract; rebase the fix onto it", "confidence": 0.8 }
+})
+// kinds: reconcile {merge_plan} | recommend {winner, rationale, confidence} | defer_to_human {question}
+```
+
+The response tells you the `outcome` (`auto_apply` | `human_confirm` |
+`human_required` | `pending`) and `your_directive`.
+
+## Read your own directive (you are blocked)
+
+```jsonc
+fleet_get_escalation({ escalation_id: "01J…", agent_id: "agent-a" })
+// → your_directive: wait | proceed | defer | review
+```
+
+Poll until it's not `wait`. `proceed` = continue; `defer` = stand down and rebase
+onto the winner; `review` = read `resolution`.
+
+## Human paths
+
+- `fleet_list_escalations({repo_id})` — the per-repo "needs human" queue.
+- `fleet_resolve_escalation({escalation_id, resolution, winner})` — record a human
+  decision (pick which agent proceeds) and clear it. Prefer the agent-judge path;
+  use this for genuine human/product calls.
+
+## Safety the referee guarantees
+
+- A destructive **removal** (delete/move) is **never** auto-applied — always a human.
+- Auto-apply happens only for the clear-safe machine case or ≥2 agents agreeing on
+  a non-destructive resolution.
+- So a wrong verdict degrades to "a human reviews a suggestion," never a silent
+  bad merge.

package/skills/workflows/memtrace-fleet-coordination.md

@@ -0,0 +1,87 @@
+---
+name: memtrace-fleet-coordination
+description: "Use when you need to understand or act on fleet conflict resolution: what conflict class A/B/C means, how a Class C destructive overlap gets decided (by an agent judge or a human), how to be the judge (fleet_submit_verdict), how to read your directive after a decision, and how branch-scoping isolates fleets. Triggered by: 'two agents are changing the same thing', 'resolve this conflict', 'who should proceed', 'a decision is waiting', acting as a mediator between agents."
+allowed-tools:
+  - mcp__memtrace__fleet_record_episode
+  - mcp__memtrace__fleet_submit_verdict
+  - mcp__memtrace__fleet_get_escalation
+  - mcp__memtrace__fleet_list_escalations
+  - mcp__memtrace__fleet_resolve_escalation
+  - mcp__memtrace__fleet_get_node_state
+---
+
+# Fleet Coordination
+
+How the fleet turns overlapping edits into a safe decision. Read
+`memtrace-fleet-first` for the publish→edit→record protocol; this skill is the
+*conflict resolution* half.
+
+## Conflict classes (what `fleet_record_episode` returns)
+
+| Class | Meaning | What to do |
+|---|---|---|
+| **A** | Additive, order-independent | Proceed. |
+| **B** | Non-destructive overlap with another agent's work | Re-read the shared symbols, then proceed. |
+| **C** | A **destructive** change (signature change / move / dead-code removal) overlaps another agent's work | A decision is needed — it does NOT auto-resolve. |
+
+Class is computed **only against agents on your branch** (`(repo, branch)`).
+Agents on other branches are never conflict peers.
+
+## The Class C decision loop
+
+When `fleet_record_episode` returns class C it also returns an `escalation_id` and
+(when mediation is on) a `mediation_request`. The decision is made by an **agent
+judge**, a **human**, or — only when provably safe — the **deterministic referee**.
+
+### Being the judge (the user's own agent does the judging — no API keys)
+
+The `mediation_request` bundles **every agent's `assignment`** plus the contested
+symbols. Read the *other* agent's task and decide on merit (including against your
+own change). Submit:
+
+```jsonc
+fleet_submit_verdict({
+  escalation_id: "01J…",
+  agent_id: "agent-a",
+  verdict: { "kind": "recommend", "winner": "agent-b",
+             "rationale": "the signature change is the wider contract; rebase the fix onto it",
+             "confidence": 0.8 }
+})
+```
+
+Verdict kinds: `reconcile {merge_plan}` · `recommend {winner, rationale, confidence}`
+· `defer_to_human {question}`.
+
+The referee then decides the outcome:
+- **Auto-apply** only when safe: the clear machine case, or ≥2 independent agents
+  agree — and **never** for a destructive *removal* (delete/move), which always
+  needs a human.
+- **Human confirm** — a recommendation is surfaced for one-click confirmation.
+- **Human required** — both sides destructive, agents disagree, or an agent
+  deferred → a person decides.
+
+### Reading your directive
+
+Poll `fleet_get_escalation({escalation_id, agent_id})` until `your_directive` ≠
+`wait`: `proceed` (you continue), `defer` (stand down / rebase onto the winner),
+`review` (read `resolution`).
+
+### Resolving as a human (or on a human's behalf via the dashboard)
+
+`fleet_resolve_escalation({escalation_id, resolution, winner})` records a human
+decision and clears the queue. Prefer the agent-judge path; use this for the
+genuine human-decision cases. `fleet_list_escalations({repo_id})` shows the
+"needs human" queue.
+
+## Why branch-scoping matters here
+
+A "winner / defer" only makes sense on a shared surface. Across branches, the
+loser can't defer (its branch needs the change too), so the fleet never escalates
+cross-branch — that's a merge-time concern git already owns. Keep your fleet to
+one session branch and conflicts stay real and resolvable.
+
+## Inspecting state
+
+`fleet_get_node_state({repo_id, node})` — recent episodes, active intents, dominant
+intent, and conflict density for one symbol. Use it to understand pressure on a
+hot symbol before you pile on.

package/skills/workflows/memtrace-fleet-first.md

@@ -0,0 +1,132 @@
+---
+name: memtrace-fleet-first
+description: "Always use FIRST when more than one coding agent works the same repo+branch at once (a 'fleet'), before reading code, planning a refactor, or making an edit. Triggered by: 'I'm about to edit X', 'rename Y across the codebase', joining a running fleet/session branch, coordinating with other agents, prose hand-offs. Do not grep for 'who else is touching this' and do not skip fleet_publish_intent because 'it's a small change'. Fleet coordination is branch-scoped: pass your session branch so your fleet coordinates and stays isolated from agents on other branches. Skip ONLY for genuinely solo sessions or pure docs-only edits where coordination has zero value."
+allowed-tools:
+  - mcp__memtrace__fleet_status
+  - mcp__memtrace__fleet_preflight
+  - mcp__memtrace__fleet_publish_intent
+  - mcp__memtrace__fleet_record_episode
+  - mcp__memtrace__fleet_get_escalation
+  - mcp__memtrace__fleet_submit_verdict
+---
+
+# Fleet First
+
+The coordination layer for **fleets of coding agents** working the same repo at the
+same time. It stops agents from silently clobbering each other's edits, and turns
+unsafe overlaps into a clear decision instead of a merge-time surprise.
+
+## The Iron Law
+
+```
+IN A FLEET → FLEET TOOLS BEFORE EDITS. NO EXCEPTIONS.
+  1. fleet_publish_intent   (declare what you'll touch; get blast radius + conflicts)
+  2. edit                   (your normal edit loop)
+  3. fleet_record_episode   (classify A/B/C; if C, the loop resolves it)
+```
+
+A typed intent serializes to ~20 tokens; a prose "I'm going to change X" averages
+200+. A 10-agent fleet × 100 edits = tens of thousands of tokens saved per
+fleet-turn — and zero silent overwrites — when the protocol is followed.
+
+## A fleet = agents on ONE branch (always pass it)
+
+**Coordination is branch-scoped.** Two agents only coordinate when they're on the
+**same `(repo, branch)`**. The branch name is the fleet identifier: a *session
+branch* is how a group of agents opts into one coordinating fleet.
+
+- Working a session branch (`session/auth-revamp`)? Pass `branch` on **every**
+  fleet call. Your fleet coordinates together and stays isolated from agents on
+  other branches.
+- Omit `branch` only for the shared default pool (single, unnamed fleet).
+- Agents on **different** branches never conflict — git already isolates them, and
+  whether branches merge isn't guaranteed, so the fleet never reasons across them.
+
+```jsonc
+{ "repo_id": "myrepo", "branch": "session/auth-revamp",
+  "agent_id": "agent-a", "touched": ["auth::verify_token"],
+  "intent": {"refactor": {"pattern": "change_signature"}},
+  "assignment": "widen verify_token signature for pagination" }
+```
+
+Always include **`assignment`** — your natural-language task. When a conflict
+happens, that's what the judge (another agent) or a human reads to reconcile.
+
+## Check the fleet first (once per session)
+
+```
+fleet_status()        → live_intents, active_agents, pending_escalations, mediator_mode
+```
+
+If it responds, fleet coordination is active — follow this skill for every edit.
+An empty fleet is **not** permission to skip: it just means you're the first agent
+in this window.
+
+## The protocol, step by step
+
+1. **Before editing** — `fleet_preflight({repo_id, branch, agent_id, touched, intent})`
+   (read-only) or go straight to `fleet_publish_intent(...)`. You get the blast
+   radius, any overlapping live intents on your branch, and a `coordination` block
+   that may already suggest who owns a contested symbol.
+2. **Edit** — your normal loop.
+3. **After editing** — `fleet_record_episode({repo_id, branch, agent_id, touched, intent})`.
+   It returns a `conflict_class`:
+   - **A — proceed.** Additive, order-independent. Nothing to do.
+   - **B — re-read, then proceed.** You overlap non-destructively; re-read the
+     shared symbols so you build on current state.
+   - **C — a decision is needed.** A destructive change overlaps another agent's
+     work. This does **not** auto-resolve — see below.
+
+## Class C: the decision loop (read this)
+
+A Class C means two edit paths can't both land safely. `fleet_record_episode`
+returns an `escalation_id` and a `mediation_request` (when mediation is enabled).
+What happens next depends on who judges:
+
+- **You may be asked to judge.** The `mediation_request` carries **every agent's
+  assignment** — including the other side's. Read them and submit a verdict with
+  `fleet_submit_verdict({escalation_id, agent_id, verdict})`, where `verdict` is one
+  of:
+  - `{"kind":"reconcile","merge_plan":"…"}` — the changes combine; here's how.
+  - `{"kind":"recommend","winner":"<agent_id>","rationale":"…","confidence":0.0-1.0}` —
+    one path should continue.
+  - `{"kind":"defer_to_human","question":"…"}` — a real product call; ask a human.
+- **A human may decide** in the Fleet dashboard. Either way the outcome flows back
+  to you.
+- **Close YOUR loop**: poll `fleet_get_escalation({escalation_id, agent_id})` until
+  `your_directive` is no longer `wait`:
+  - `proceed` — you were chosen; continue.
+  - `defer` — another path won; stand down and rebase your work onto it.
+  - `review` — read the free-text `resolution`.
+
+The daemon is a deterministic referee: it never auto-applies a destructive
+*removal* (delete/move) without a human, and only auto-applies when it's safe (a
+clear machine case, or independent agent consensus). So the judge being wrong
+degrades to "a human reviews a suggestion," never a silent bad merge.
+
+## Routing — what do you need?
+
+| You're about to… | Do this |
+|---|---|
+| Start any edit in a fleet | `fleet_publish_intent` (declare it) — never skip |
+| Check before declaring | `fleet_preflight` (read-only "is the coast clear?") |
+| Finish an edit | `fleet_record_episode` (get A/B/C) |
+| Got a Class C as the judge | `fleet_submit_verdict` (reconcile/recommend/defer) |
+| Blocked on a Class C | poll `fleet_get_escalation` until `your_directive ≠ wait` |
+| See who's in the fleet | `fleet_status` (active_agents, pending decisions) |
+| Inspect a symbol's coordination state | `fleet_get_node_state` |
+
+## Parameter notes
+
+- Pass `intent` as JSON (externally-tagged, snake_case):
+  `{"refactor":{"pattern":"rename_symbol"}}`, `{"bug_fix":{"defect":"logic_error"}}`.
+  Destructive kinds: `refactor/change_signature`, `refactor/move_symbol`,
+  `cleanup/dead_code` — these are what trigger Class C over shared symbols.
+- `touched` is a list of qualified symbol identities (e.g. `"module::Symbol"`).
+- Always include `branch` (your session branch) and `assignment` (your task).
+
+## When to skip
+
+Skip the protocol only for a genuinely **solo** session (you're the only agent and
+no one else shares your branch) or **pure docs-only** edits where coordination has
+zero value. Everything else in a fleet goes through the protocol.