memtrace-skills 0.7.10

package/plugins/memtrace-skills/skills/memtrace-style-fingerprint/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: memtrace-style-fingerprint
+description: "Always use before writing or editing source code in an indexed repo when choosing between competing idioms (ternary vs if-else, arrow vs function declaration, const vs let, await vs .then, early-return vs nested-return). Pull the codebase's empirical style norm from Memtrace and match it instead of re-deriving style from training priors. Do not maintain a markdown style guide for the project; the fingerprint is sampled live from the actual code."
+---
+
+## Overview
+
+Every indexed Memtrace repository carries an empirical **style fingerprint** — descriptive histograms of competing AST idioms (ternary vs if-else, arrow vs function declaration, const vs let, await vs `.then`, early-return vs nested-return depth) computed at parse time and rolled up to Repository + Community level. This workflow tells you when and how to consult it so your edits match the codebase's existing idioms instead of drifting on stylistic choices the linter doesn't catch.
+
+The fingerprint is **descriptive, not prescriptive**. It reports what the codebase actually does, not what a style guide says it should do. If the codebase deviates from a popular convention for some reason, the fingerprint captures the deviation and you should match the deviation — that's the whole point. For prescriptive bug/security/perf rules, use `find_code_review_issues` instead.
+
+## When to use this workflow
+
+| Situation | Action |
+|---|---|
+| About to write new code (function, component, module) in an indexed repo | Step 1 + Step 2 with `file_path=<the file you'll create>` |
+| About to edit an existing file | Step 1 + Step 2 with `file_path=<that file>` |
+| Asked "what's the convention here for X?" | Step 1 only — repo-mode fingerprint answers it |
+| Deciding between two equivalent idioms (ternary vs if, arrow vs fn-decl, await vs then) | Step 2 with `file_path` — `delta_from_codebase_norm` tells you which idiom matches the norm |
+| Reviewing a diff | Step 2 on each modified file — flag any new idioms that diverge from the file's language norm |
+| Session start in a multi-day project | Read the `style:` line in `get_codebase_briefing` (auto-included) |
+
+If the repo is not indexed in Memtrace, this workflow does not apply — fall back to your default behavior.
+
+## Steps
+
+### 1. Get the codebase's overall norm
+
+Call `get_style_fingerprint(repo_id)` with no `file_path`. The response includes:
+
+- `histogram` — raw counts (e.g. `ternary_count: 1005, if_stmt_count: 8087`)
+- `ratios` — computed shares for each competing pair (e.g. `ternary_share: 0.11`)
+- `dominant_idioms` — top-3 dimensions sorted by `|ratio - 0.5|` (strongest preferences first), each with a `dimension`, `ratio`, and human-readable `interpretation`
+- `function_count` — sample size at the repo level
+- `sample_threshold` — minimum observations before a ratio is committed (currently 20)
+
+A `ratio` of `null` means the codebase doesn't have enough observations for that dimension to commit a norm — treat it as "no signal", do not assume one.
+
+### 2. Get the file's deviation from the norm (when about to edit a specific file)
+
+Call `get_style_fingerprint(repo_id, file_path=<file>)`. The response adds:
+
+- `file_fingerprint` — the same shape as `histogram`/`ratios`/`function_count` but computed over just the functions in that file
+- `codebase_fingerprint` — repo aggregate for comparison
+- `delta_from_codebase_norm` — array of dimensions where the file diverges ≥0.15 from the codebase, sorted by absolute delta, capped at top 5. Each entry has `dimension`, `file_ratio`, `codebase_ratio`, `abs_delta`, and a `note` describing the direction
+
+**Match the file's `language_fingerprint`, not the repo aggregate.** In file mode the response carries `language` (the file's language), `language_fingerprint` (that language's slice — the primary comparator), and `delta_from_language_norm` (divergence vs the language, not the repo). Per-language slicing prevents cross-applying Python norms to JS code or vice versa — read the `language_fingerprint`. (`delta_from_codebase_norm` is retained as a deprecated alias and is removed in 0.5.14.)
+
+If `delta_from_language_norm` is empty, the file is already aligned — proceed without style adjustments. If it has entries, your edits should not amplify the divergence (e.g. don't add more ternaries to a file that's already above the language's ternary norm).
+
+### 3. Read the briefing line at session start (passive)
+
+`get_codebase_briefing(repo_id)` auto-includes a `style:` line in its summary when the sample threshold is met and at least one ratio is outside the 0.4..0.6 no-preference band. Format:
+
+```
+style: <interpretation 1> (<%>); <interpretation 2> (<%>); <interpretation 3> (<%>)
+```
+
+Example on a TS/JS-heavy codebase:
+
+```
+style: strongly prefers arrow functions (98%); strongly prefers async/await over .then chains (88%); strongly prefers const over let (94%)
+```
+
+You should already be reading the briefing at session start (per `memtrace-codebase-exploration`). The `style:` line lands in your context for free — no extra call needed.
+
+## Decision points
+
+| Condition | Action |
+|---|---|
+| `dominant_idioms[0].ratio >= 0.85` or `<= 0.15` | Treat as a hard preference — match it unless there's a specific structural reason not to |
+| `dominant_idioms[0].ratio` in `0.65..0.85` or `0.15..0.35` | Treat as a soft preference — match it for new code, leave existing patterns alone |
+| `ratio` in `0.4..0.6` | No clear preference — use your own judgment, match local file context |
+| `ratio` is `null` (below sample threshold) | No signal — don't assume a norm; pick the idiom that fits the immediate context |
+| `delta_from_codebase_norm` shows your target file already diverges from the norm | Don't amplify the divergence with your edits — match the codebase, not the outlier file |
+| `file_fingerprint` is empty (file has no functions yet, or is a config file) | Use the language slice or repo aggregate; this is creation territory |
+
+## Anti-patterns — do not do these
+
+- **Reading the repo aggregate when editing a single-language file.** If the codebase is 70% TS / 30% Python, the repo aggregate mixes both. The `language_fingerprint` (when available) or `codebase_fingerprint.ratios` filtered by the file's language is what you should match. Cross-applying TS norms to a Python file is the failure mode this whole tool exists to prevent.
+- **Treating the fingerprint as prescriptive.** It tells you what the codebase does. If the codebase consistently does something unusual, match that — don't override with "this isn't best practice" arguments. The whole point is to stop drifting from the codebase's own choices.
+- **Calling `get_style_fingerprint` for every line of code.** Once per file at the start of an edit session is enough. The norm doesn't change between your edits within the same session.
+- **Ignoring the briefing line.** It auto-loads into your context. If you act on style choices in an edit session without reading it first, you're spending tool calls to re-derive something you already had.
+- **Adding a markdown style guide to the project.** The fingerprint is the style guide. It refreshes on every reindex. A markdown file would either duplicate it or contradict it.
+
+## Naming-case dimensions (shipped in 0.5.13)
+
+Beyond the AST idioms, the fingerprint also reports identifier **naming-case** per scope, across all 13 source languages:
+
+- **Variables / functions / types / constants / files** — the share of camelCase / snake_case / PascalCase / SCREAMING_SNAKE / kebab. Read e.g. `ratios.naming_variables_snake_share` or the `dominant_idioms` entry that names the scope's winning case ("vars are snake_case (89%)").
+- **Config keys** for YAML / JSON / TOML / HCL / SQL — `ratios.config_keys_*_share`.
+- **Enforcement-aware:** languages that compiler-enforce a scope return `null` for it (Rust vars/fns/types/consts, Ruby constants). A `null` there means "the compiler decides, not the codebase" — don't try to match a non-signal.
+- **Go** reports `go_exported_share` (PascalCase = exported) instead of per-case naming, because case encodes visibility in Go.
+
+When editing, match the naming case the file's `language_fingerprint` reports for the scope you're touching — same per-language rule as the idiom dimensions.
+
+## What this workflow does NOT cover
+
+- **Security / bug / performance rules** — use `find_code_review_issues` (prescriptive deterministic review).
+- **Comment / docstring style** — not in scope; use file-local examples.
+- **Architecture / module-organization decisions** — see `memtrace-codebase-exploration` and `memtrace-refactoring-guide`.
+
+## Why this exists
+
+Without this workflow, LLM editors drift session-to-session on style choices that aren't enforced by linters — one session uses ternaries, the next doesn't; one uses arrow functions, the next uses `function`. The fix isn't a manually-maintained style guide (stale by week 2). The fix is sampling the codebase's actual idioms at parse time and reading them before each edit. The fingerprint is computed in the same parse pass as cyclomatic + cognitive complexity at sub-1% overhead, so the cost of providing the answer is near zero.

package/skills/commands/memtrace-api-topology.md

@@ -0,0 +1,65 @@
+---
+name: memtrace-api-topology
+description: "Always use for API endpoint, HTTP route, fetch/client call, REST surface, service dependency, cross-repo dependency, or API topology questions in source code. Do not use Grep, Glob, rg, find, or manual file search for routes or HTTP calls; Memtrace maps endpoints and call edges from the indexed AST graph."
+allowed-tools:
+  - mcp__memtrace__get_api_topology
+  - mcp__memtrace__find_api_endpoints
+  - mcp__memtrace__find_api_calls
+  - mcp__memtrace__get_symbol_context
+  - mcp__memtrace__link_repositories
+user-invocable: true
+---
+
+## Overview
+
+Map the HTTP API surface of a codebase — exposed endpoints, outbound HTTP calls, and cross-repo service-to-service dependency graphs. Supports auto-detection for Express, Encore, NestJS, Axum, FastAPI, Flask, Gin, Spring Boot, and more.
+
+## Quick Reference
+
+| Tool | Purpose |
+|------|---------|
+| `find_api_endpoints` | All exposed HTTP endpoints (GET /users, POST /orders, etc.) |
+| `find_api_calls` | All outbound HTTP calls (fetch, axios, reqwest, etc.) |
+| `get_api_topology` | Cross-repo call graph: which service calls which endpoint |
+| `link_repositories` | Manually link repos for cross-repo edge detection |
+
+> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `depth`, `min_size`, `last_n`, etc.) must be JSON numbers — not strings. Use `limit: 20`, never `limit: "20"`. Passing a string yields `MCP error -32602: invalid type: string, expected usize`.
+
+
+## Steps
+
+### 1. Discover endpoints
+
+Use `find_api_endpoints`:
+- `repo_id` — required
+- Returns: method, path, handler function, framework detected
+
+### 2. Discover outbound calls
+
+Use `find_api_calls`:
+- `repo_id` — required
+- Returns: target URL/path, HTTP method, calling function, library used (fetch, axios, reqwest, etc.)
+
+### 3. Map service topology
+
+Use `get_api_topology` to see the cross-repo HTTP call graph:
+- Which services call which endpoints
+- Confidence scores for each detected link
+- Service-to-service dependency direction
+
+**Prerequisite:** Multiple repos must be indexed. If cross-repo links aren't appearing, use `link_repositories` to explicitly connect them.
+
+### 4. Deep-dive into an endpoint
+
+For any specific endpoint, use `get_symbol_context` with the endpoint's symbol ID to see:
+- Which internal functions handle the request
+- Which processes (execution flows) include this endpoint
+- Which external services call this endpoint
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Expecting cross-repo links with only one repo indexed | Index ALL related services first; cross-repo HTTP edges are linked automatically after indexing |
+| Missing endpoints from custom frameworks | Memtrace auto-detects major frameworks; for custom routers, the endpoints may appear as regular functions |
+| Not using `link_repositories` | If auto-linking missed a connection, use this to manually establish cross-repo edges |

package/skills/commands/memtrace-cochange.md

@@ -0,0 +1,76 @@
+---
+name: memtrace-cochange
+description: "Always use for historical coupling, co-change, what changes with this, hidden dependency, or what else needs to move questions for source code. Do not use git log, git diff, Grep, or manual file search to correlate changes; Memtrace queries co-change and temporal graph data directly."
+allowed-tools:
+  - mcp__memtrace__get_cochange_context
+  - mcp__memtrace__find_symbol
+  - mcp__memtrace__get_impact
+user-invocable: true
+---
+
+## Overview
+
+Find symbols that historically co-change with a target symbol — ranked by co-occurrence frequency across all episodes. This surfaces **behavioral coupling** that the static call graph cannot see.
+
+`get_impact` answers "who calls this?" (structural).
+`get_cochange_context` answers "what always moves when this moves?" (historical).
+
+They are complementary. A symbol with no direct callers can still have strong cochange partners if it's always modified alongside another in every commit.
+
+> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `depth`, `min_size`, `last_n`, etc.) must be JSON numbers — not strings. Use `limit: 20`, never `limit: "20"`. Passing a string yields `MCP error -32602: invalid type: string, expected usize`.
+
+
+## Steps
+
+### 1. Identify the target symbol
+
+Use `find_symbol` if you need the exact name. The tool matches by `name` field.
+
+### 2. Call `get_cochange_context`
+
+```
+get_cochange_context(
+  repo_id: "...",
+  symbol: "execute",    // exact symbol name
+  limit: 20             // default 20, increase for broader view
+)
+```
+
+### 3. Interpret results
+
+The response contains `cochanges[]`, each with:
+- `name` — symbol name
+- `kind` — Function / Method / Class / Struct
+- `file_path` — where it lives
+- `cochange_count` — how many episodes it shared with the target
+
+```
+High cochange_count = strong historical coupling
+→ If you modify the target, you will likely need to touch this too
+→ Or it may be the real root cause you should investigate first
+```
+
+### 4. Cross-reference with call graph
+
+For the top cochange partners, optionally run `get_impact` to see if the coupling is also structural:
+
+| Structural coupling | Historical coupling | Interpretation |
+|---|---|---|
+| Yes | Yes | Core architectural dependency — highest risk |
+| No | Yes | Hidden coupling — only visible through history |
+| Yes | No | Called frequently but changed independently — lower risk |
+
+## When to Use
+
+- **Before modifying a symbol** — get blast awareness beyond what `get_impact` shows
+- **Incident investigation** — when `get_impact` doesn't explain the blast radius, check cochange history
+- **Code review** — verify that a PR touched all historically-coupled partners
+- **Refactoring** — discover implicit coupling before extracting a module
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Only using `get_impact` for blast radius | Structural coupling misses behavioral coupling — always pair with cochange |
+| Ignoring low-`in_degree` cochange partners | A rarely-called utility with high cochange_count is a strong coupling signal |
+| Using cochange as a dependency map | It's not a dependency graph — it's a change correlation. Two symbols can cochange without any direct relationship. |

package/skills/commands/memtrace-evolution.md

@@ -0,0 +1,135 @@
+---
+name: memtrace-evolution
+description: "Always use for source-code change history, recent modifications, what changed since a date, symbol timeline, evolution, unexpected changes, or incident timeline questions. Do not use git log, git diff, Grep, or manual file search to reconstruct history; Memtrace has symbol-level temporal memory."
+allowed-tools:
+  - mcp__memtrace__get_evolution
+  - mcp__memtrace__get_timeline
+  - mcp__memtrace__detect_changes
+  - mcp__memtrace__list_indexed_repositories
+  - mcp__memtrace__get_changes_since
+user-invocable: true
+---
+
+## Overview
+
+Multi-mode temporal analysis engine that answers "what changed and why should I care?" across arbitrary time windows. Uses Structural Significance Budgeting (SSB) to surface the most important changes without overwhelming you with noise.
+
+This is memtrace's most powerful analytical tool. It implements six distinct scoring algorithms — choose the right one based on what the user needs.
+
+## Query Modes — Choose the Right Algorithm
+
+| Mode | Algorithm | Best For |
+|------|-----------|----------|
+| `compound` | Rank-fusion: 0.50×impact + 0.35×novel + 0.15×recent | **Default.** General-purpose "what changed?" — use when unsure |
+| `impact` | Structural Significance: `sig(n) = in_degree^0.7 × (1 + out_degree)^0.3` | "What broke?" — finds changes with the largest blast radius |
+| `novel` | Change Surprise Index: `surprise(n) = (1 + in_degree) / (1 + change_freq_90d)` | "What's unexpected?" — anomaly detection for rarely-changing code |
+| `recent` | Temporal Proximity: `impact × exp(−0.5 × Δhours)` | "What changed near the incident?" — time-weighted for root cause |
+| `directional` | Asymmetric scoring (added→out_degree, removed→in_degree, modified→impact) | "What was added vs removed?" — structural change direction |
+| `overview` | Fast module-level rollup only | Quick summary — no per-symbol scoring, just module counts |
+
+> **Parameter types:** MCP parameters are strictly typed. Numbers (`limit`, `depth`, `min_size`, `last_n`, etc.) must be JSON numbers — not strings. Use `limit: 20`, never `limit: "20"`. Passing a string yields `MCP error -32602: invalid type: string, expected usize`.
+
+
+## Steps
+
+### 1. Determine the time window
+
+Ask the user or infer:
+- `from` — ISO-8601 start timestamp (required)
+- `to` — ISO-8601 end timestamp (defaults to now)
+- `repo_id` — scope to a repo (call `list_indexed_repositories` if unknown)
+
+### 2. Choose the mode
+
+**Decision tree:**
+
+```
+User wants to know...
+├── "what changed?"           → compound (default)
+├── "what could have broken?" → impact
+├── "anything unexpected?"    → novel
+├── "what changed near X?"    → recent (set to to incident time)
+├── "what was added/removed?" → directional
+└── "quick summary?"          → overview
+```
+
+### 3. Execute the query
+
+Use the `get_evolution` MCP tool with:
+- `repo_id` — required
+- `from` / `to` — the time window
+- `mode` — one of: compound, impact, novel, recent, directional, overview
+
+### 4. Interpret results
+
+The response contains:
+
+- **`added[]`** — new symbols that appeared in the time window
+- **`removed[]`** — symbols that were deleted
+- **`modified[]`** — symbols that changed
+- **`by_module[]`** — module-level rollup (NEVER truncated — always shows all modules)
+- **`significance_coverage`** — fraction of total significance captured (target: ≥0.80)
+- **`budget_exhausted`** — if true, there were more significant changes than the budget allowed
+
+Each symbol includes: `name`, `kind`, `file_path`, `scope_path`, `in_degree`, `out_degree`, and all four scores (`impact`, `novel`, `recent`, `compound`).
+
+### 5. Drill deeper
+
+- **For a single symbol's full history:** Use `get_timeline` with the symbol name
+- **For diff-based change scope:** Use `detect_changes` when you have a specific diff/patch
+- **For blast radius of a specific change:** Use `get_impact` on high-scoring symbols
+
+## Scoring Algorithms — Detailed Reference
+
+### Impact Score (Structural Significance Budgeting)
+```
+sig(n) = in_degree^0.7 × (1 + out_degree)^0.3
+```
+- Heavily weights callers (in_degree) — symbols called by many others have high blast radius
+- Mild boost for outbound complexity (out_degree) — complex functions that changed are notable
+- SSB selects the minimum set covering ≥80% of total significance mass
+
+### Novelty Score (Change Surprise Index)
+```
+surprise(n) = (1 + in_degree) / (1 + change_freq_90d)
+```
+- High in_degree + low change frequency = **maximum surprise**
+- A core utility that hasn't changed in 90 days suddenly changing → likely worth investigating
+- Low in_degree + high frequency = routine churn, deprioritized
+
+### Recent Score (Temporal Proximity Weighting)
+```
+recent(n) = impact(n) × exp(−0.5 × |Δhours to reference|)
+```
+- Exponential decay from the reference timestamp (the `to` parameter)
+- Changes close to an incident get amplified; older changes fade
+- Best for incident timelines: set `to` to the incident timestamp
+
+### Compound Score (Rank Fusion)
+```
+compound = 0.50×rank(impact) + 0.35×rank(novel) + 0.15×rank(recent)
+```
+- Rank-based fusion avoids scale sensitivity between different score types
+- Impact-dominant but boosted by novelty and recency
+- Best default when you don't have a specific hypothesis
+
+## Auto-overview Safety
+
+If a time window produces more than 500 candidates and mode is not `overview`, the query **automatically downgrades to overview mode** and returns `auto_overview: true`. This prevents timeouts on wide windows. When you see `auto_overview: true`:
+- Narrow the window, OR
+- Switch to `get_changes_since` (which handles this automatically), OR
+- Use the `by_module` rollup to identify the specific area and query a tighter window
+
+## Session-Aware Alternative
+
+If you're resuming work after a break and don't know the right `from` timestamp, use `get_changes_since` instead — it accepts a `last_episode_id` anchor and never requires timestamp guessing.
+
+## Common Mistakes
+
+| Mistake | Reality |
+|---------|---------|
+| Using `overview` when user needs details | Overview only gives module-level counts — use `compound` for symbol-level |
+| Ignoring `budget_exhausted` flag | If true, there are more significant changes beyond what was returned — narrow the time window or use module rollup |
+| Not checking `by_module` first | Module rollup is never truncated — scan it to identify which areas changed before diving into symbol-level |
+| Using `recent` without setting `to` | The `to` timestamp is the reference point for proximity weighting — set it to the incident/event time |
+| Guessing timestamps when resuming work | Use `get_changes_since` with a stored `session_anchor` instead — exact episode boundary, no guessing |

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/commands/memtrace-graph.md

@@ -0,0 +1,75 @@
+---
+name: memtrace-graph
+description: "Always use for source-code architecture, important symbols, centrality, PageRank, bridge functions, communities, logical modules, chokepoints, service boundaries, or dependency path questions. Do not use Glob, find, tree, or directory browsing to infer architecture; Memtrace runs graph algorithms over the AST graph."
+allowed-tools:
+  - mcp__memtrace__find_bridge_symbols
+  - mcp__memtrace__find_central_symbols
+  - mcp__memtrace__find_dependency_path
+  - mcp__memtrace__list_communities
+  - mcp__memtrace__list_processes
+  - mcp__memtrace__get_process_flow
+user-invocable: true
+---
+
+## Overview
+
+Graph algorithms that reveal the structural architecture of a codebase — community detection (Louvain), centrality ranking (PageRank), bridge symbol identification (Tarjan articulation points), shortest-path discovery, and execution flow tracing.
+
+All four algorithm tools (`find_central_symbols`, `find_bridge_symbols`, `find_dependency_path`, `list_communities`) run natively against the MemDB-backed knowledge graph — no Cypher required.
+
+## Quick Reference
+
+| Tool | Purpose |
+|------|---------|
+| `find_bridge_symbols` | Architectural chokepoints — symbols whose removal disconnects the graph (Tarjan articulation points) |
+| `find_central_symbols` | Most important symbols by **PageRank** (default) or degree centrality |
+| `find_dependency_path` | Shortest call/import path between two symbols (BFS over typed edges) |
+| `list_communities` | Louvain-detected logical modules/services |
+| `list_processes` | Execution flows: HTTP handlers, background jobs, CLI commands, event handlers |
+| `get_process_flow` | Trace a single process step-by-step |
+
+## Steps
+
+### 1. Understand the architecture
+
+Start with `list_communities` to see how the codebase is naturally partitioned into logical modules. Each community has a name, member count, and representative symbols.
+
+### 2. Find critical infrastructure
+
+Use `find_central_symbols` to identify the most important symbols:
+- `method: "pagerank"` — importance by link structure (default; same algorithm Google uses)
+- `method: "degree"` — importance by direct connection count
+- `limit` — how many to return
+
+The PageRank pass walks every CALLS / REFERENCES edge in the repo, distributes rank with the standard 0.85 damping factor, and converges on a stable ordering. The output is sorted by score descending, with each entry carrying `name`, `kind`, `file_path`, `score`, and the `in_degree`/`out_degree` it accumulated during the walk.
+
+### 3. Find architectural chokepoints
+
+Use `find_bridge_symbols` to find symbols that, if removed, would disconnect parts of the graph (Tarjan articulation points). These are:
+- **Single points of failure** — if they break, cascading failures occur
+- **Integration points** — good places for interfaces/contracts
+- **Refactoring targets** — often too much responsibility concentrated in one place
+
+### 4. Discover the path between two symbols
+
+Use `find_dependency_path` to answer "how does symbol A reach symbol B?" — returns the shortest call/import chain via BFS over typed edges. Useful for:
+- "Why does the auth handler depend on the database client?"
+- "How does this CLI command reach the logging subsystem?"
+- "Confirm symbol X actually transitively depends on Y."
+
+### 5. Trace execution flows
+
+Use `list_processes` to see all entry points (HTTP handlers, background jobs, CLI commands, event handlers).
+
+Use `get_process_flow` with a process name to trace a specific flow step-by-step — shows the full call chain from entry point through business logic to data access, ordered by the indexed `step` property on each STEP_IN_PROCESS edge.
+
+## Decision Points
+
+| Question | Tool |
+|----------|------|
+| "What are the main modules?" | `list_communities` |
+| "What are the most important functions?" | `find_central_symbols` with method=pagerank |
+| "Where are the bottlenecks?" | `find_bridge_symbols` |
+| "How does symbol A reach symbol B?" | `find_dependency_path` |
+| "How does a request flow through the system?" | `list_processes` → `get_process_flow` |
+| "What's the entry point for feature X?" | `list_processes`, then filter by name |