memtrace-skills 1.2.8 → 1.2.10

package/plugins/memtrace-skills/skills/memtrace-index/SKILL.md

@@ -100,3 +100,24 @@ After indexing completes, call `list_indexed_repositories` to confirm the repo a
 ```
 
 While running, the job advances through the pipeline stages listed in step 3; `status = "failed"` carries an error message. The final user-facing report (confirmed via `list_indexed_repositories`) covers: `repo_id`, languages detected, total symbols, total relationships (node/edge counts).
+
+## Source revision barrier and multi-query reports
+
+After the job finishes, call `get_query_revision` with `repo_id`. It returns the
+worktree, branch, source commit, content-and-save `source_revision`, indexing
+revision, publication status and an opaque `token`. This is an explicit scan;
+use it at report boundaries, not for every lookup.
+
+To wait for a particular saved tree, take its `source_revision` from the first
+observation and pass `expected_source_revision` with `wait_ms: 10000`. Repeat
+within the same five-minute polling budget until `ready: true`. A source mismatch
+means the working tree changed again; choose the new source revision deliberately.
+Missing publication or file-hash evidence remains partial.
+
+For a report, capture a ready token, run the repository queries (use the returned
+branch wherever supported), then call `get_query_revision` with that token as
+`expected_revision`. Accept only if this final check is ready and each answer's
+`_meta.graph_revision.publication_unchanged_during_call` is true. Otherwise retry
+the whole dependent group. Repeat the boundary checks for every repository in
+a cross-repository report. This current-source protocol does not certify explicit
+historical queries; Cortex has independent revisions.

package/plugins/memtrace-skills/skills/memtrace-preflight/SKILL.md

@@ -5,6 +5,10 @@ description: "Run a one-call pre-flight check on a single existing symbol before
 
 ## Overview
 
+### Choose the scope
+
+Use this entry for the bundled gate before editing one existing symbol. For only upstream/downstream impact, use `memtrace-impact`. These remain separate so a request for a quick blast radius does not silently grow into a full preflight.
+
 Pre-flight check: the two minutes before an edit that prevent the bug. One
 `preflight_check` call composes the dependency graph, the bi-temporal change
 history, and the complexity metrics into an actionable radar for a single

package/plugins/memtrace-skills/skills/memtrace-quality/SKILL.md

@@ -46,13 +46,27 @@ Results are still candidates, not proof — unmodeled dynamic dispatch can look
 live or dead incorrectly. Verify before deleting. Prefer false-live over
 false-dead.
 
-### 3. Complexity hotspots
+### 3. Change hotspots
+
+Call `find_hotspots` for the same churn ? complexity ranking used by the dashboard:
+
+```json
+{ "repo_id": "memdb", "window_days": 14, "top_n": 10, "include_tests": false }
+```
+
+Pass `branch` when investigating a particular branch. The default window is 14
+days; windows up to 90 days are supported and longer-than-14-day queries carry
+`slow_path: true`. Inspect `below_threshold`, `empty_reason`, and `census` before
+interpreting the rows: fallback candidates are not qualifying hotspots.
+Use `get_symbol_context` and `preflight_check` before changing a candidate.
+
+### 3a. Complexity ranking
 
 ```json
 { "repo_id": "memdb", "top_n": 10 }
 ```
 
-Ordered by call-graph out-degree.
+Use `find_most_complex_functions` for complexity alone, without change frequency.
 
 | Score | Rating | Action |
 |-------|--------|--------|

package/plugins/memtrace-skills/skills/memtrace-refactoring-guide/SKILL.md

@@ -5,6 +5,10 @@ description: "Build a phased, risk-scored refactoring plan from Memtrace complex
 
 ## Overview
 
+For an executable sequence with persisted progress and checks between edits, use
+`memtrace-guided-refactor`. This guide remains the broader prioritization and
+planning workflow; a guided run carries an approved bounded plan into execution.
+
 Guided refactoring workflow — identifies refactoring candidates using structural analysis, scores them by risk and priority, checks Cortex decision memory for rationale/bans/contracts, and produces a phased refactoring plan. Combines complexity metrics, dead code detection, bridge analysis, temporal evolution, and decision memory to prioritize what to refactor first and how to do it safely.
 
 ## Steps

package/plugins/memtrace-skills/skills/memtrace-search/SKILL.md

@@ -82,6 +82,7 @@ For a code change, inspect the relevant caller/callee contracts before editing.
 symbol and flow; use these directly when they address the investigation.
 They preserve repository, branch and file disambiguation. Process navigation
 uses the returned process UUID. Symbol navigation uses name plus file path.
+Rows are compact; `verbose: true` returns the full answer.
 Expand only the evidence needed; an empty sampled process list does not mean
 the symbol has no callers or callees.
 

package/plugins/memtrace-skills/skills/memtrace-session-continuity/SKILL.md

@@ -5,6 +5,10 @@ description: "Catch up on everything that changed in an indexed source-code repo
 
 ## Overview
 
+### Choose the scope
+
+Use this entry to resume from a saved session anchor. For the fixed last-24-hour briefing, hotspots, or a session self-audit, use `memtrace-daily`. Preserve the requested time window instead of treating both workflows as the same catch-up.
+
 Session continuity for agents. Store a timestamp from your last session and call `get_changes_since` to see exactly what happened since then — then drill into details with `get_evolution` if needed.
 
 **Core principle:** Persist a `since` timestamp (or the `until` from your last catch-up call). Never invent a `days` parameter.

package/skills/commands/memtrace-daily.md

@@ -15,6 +15,10 @@ user-invocable: true
 
 ## Overview
 
+### Choose the scope
+
+Use this entry for the fixed last-24-hour briefing, hotspots, and session self-audit. To resume from your own saved anchor, use `memtrace-session-continuity`; do not substitute a 24-hour window for time since the user's last session.
+
 Session bookends: orient before you start, audit before you finish. All
 three tools read the bi-temporal version history — every save is a change
 event with complexity deltas, so "what happened" includes "did it make the

package/skills/commands/memtrace-graph.md

@@ -17,6 +17,10 @@ user-invocable: true
 
 ## Overview
 
+### Choose the scope
+
+Use this entry for a specific graph algorithm or structural question: centrality, bridges, communities, or dependency paths. For a narrative introduction spanning scale, architecture, APIs, and recent activity, use `memtrace-codebase-exploration`.
+
 Graph algorithms over the knowledge graph — communities (Louvain), PageRank centrality, bridge symbols (articulation points), shortest paths, and execution flows.
 
 ## Quick Reference

package/skills/commands/memtrace-impact.md

@@ -15,6 +15,10 @@ user-invocable: true
 
 ## Overview
 
+### Choose the scope
+
+Use this entry for a quick upstream/downstream blast radius. For the bundled pre-edit gate, including co-change, complexity, churn, and a verification checklist, use `memtrace-preflight`. Keep the narrower impact query available when a full preflight is unnecessary.
+
 Compute the blast radius of changing a specific symbol. Traces upstream (what depends on this) and downstream (what this depends on) through the knowledge graph to quantify risk before making modifications.
 
 ## Quick Reference

package/skills/commands/memtrace-index.md

@@ -6,6 +6,7 @@ allowed-tools:
   - mcp__memtrace__check_job_status
   - mcp__memtrace__list_jobs
   - mcp__memtrace__list_indexed_repositories
+  - mcp__memtrace__get_query_revision
 metadata:
   author: "Syncable <support@syncable.dev>"
   version: "1.0.0"
@@ -110,3 +111,24 @@ After indexing completes, call `list_indexed_repositories` to confirm the repo a
 ```
 
 While running, the job advances through the pipeline stages listed in step 3; `status = "failed"` carries an error message. The final user-facing report (confirmed via `list_indexed_repositories`) covers: `repo_id`, languages detected, total symbols, total relationships (node/edge counts).
+
+## Source revision barrier and multi-query reports
+
+After the job finishes, call `get_query_revision` with `repo_id`. It returns the
+worktree, branch, source commit, content-and-save `source_revision`, indexing
+revision, publication status and an opaque `token`. This is an explicit scan;
+use it at report boundaries, not for every lookup.
+
+To wait for a particular saved tree, take its `source_revision` from the first
+observation and pass `expected_source_revision` with `wait_ms: 10000`. Repeat
+within the same five-minute polling budget until `ready: true`. A source mismatch
+means the working tree changed again; choose the new source revision deliberately.
+Missing publication or file-hash evidence remains partial.
+
+For a report, capture a ready token, run the repository queries (use the returned
+branch wherever supported), then call `get_query_revision` with that token as
+`expected_revision`. Accept only if this final check is ready and each answer's
+`_meta.graph_revision.publication_unchanged_during_call` is true. Otherwise retry
+the whole dependent group. Repeat the boundary checks for every repository in
+a cross-repository report. This current-source protocol does not certify explicit
+historical queries; Cortex has independent revisions.

package/skills/commands/memtrace-preflight.md

@@ -17,6 +17,10 @@ user-invocable: true
 
 ## Overview
 
+### Choose the scope
+
+Use this entry for the bundled gate before editing one existing symbol. For only upstream/downstream impact, use `memtrace-impact`. These remain separate so a request for a quick blast radius does not silently grow into a full preflight.
+
 Pre-flight check: the two minutes before an edit that prevent the bug. One
 `preflight_check` call composes the dependency graph, the bi-temporal change
 history, and the complexity metrics into an actionable radar for a single

package/skills/commands/memtrace-quality.md

@@ -4,6 +4,9 @@ description: "Find dead code, complexity hotspots, and refactoring candidates in
 allowed-tools:
   - mcp__memtrace__find_dead_code
   - mcp__memtrace__calculate_cyclomatic_complexity
+  - mcp__memtrace__get_symbol_context
+  - mcp__memtrace__preflight_check
+  - mcp__memtrace__find_hotspots
   - mcp__memtrace__find_most_complex_functions
   - mcp__memtrace__get_repository_stats
   - mcp__memtrace__get_evolution
@@ -57,13 +60,27 @@ Results are still candidates, not proof — unmodeled dynamic dispatch can look
 live or dead incorrectly. Verify before deleting. Prefer false-live over
 false-dead.
 
-### 3. Complexity hotspots
+### 3. Change hotspots
+
+Call `find_hotspots` for the same churn ? complexity ranking used by the dashboard:
+
+```json
+{ "repo_id": "memdb", "window_days": 14, "top_n": 10, "include_tests": false }
+```
+
+Pass `branch` when investigating a particular branch. The default window is 14
+days; windows up to 90 days are supported and longer-than-14-day queries carry
+`slow_path: true`. Inspect `below_threshold`, `empty_reason`, and `census` before
+interpreting the rows: fallback candidates are not qualifying hotspots.
+Use `get_symbol_context` and `preflight_check` before changing a candidate.
+
+### 3a. Complexity ranking
 
 ```json
 { "repo_id": "memdb", "top_n": 10 }
 ```
 
-Ordered by call-graph out-degree.
+Use `find_most_complex_functions` for complexity alone, without change frequency.
 
 | Score | Rating | Action |
 |-------|--------|--------|

package/skills/commands/memtrace-search.md

@@ -94,6 +94,7 @@ For a code change, inspect the relevant caller/callee contracts before editing.
 symbol and flow; use these directly when they address the investigation.
 They preserve repository, branch and file disambiguation. Process navigation
 uses the returned process UUID. Symbol navigation uses name plus file path.
+Rows are compact; `verbose: true` returns the full answer.
 Expand only the evidence needed; an empty sampled process list does not mean
 the symbol has no callers or callees.
 

package/skills/workflows/memtrace-codebase-exploration.md

@@ -23,6 +23,10 @@ user-invocable: true
 
 ## Overview
 
+### Choose the scope
+
+Use this entry for a narrative overview and onboarding. For a specific algorithm such as PageRank, bridge detection, communities, or dependency paths, use `memtrace-graph`. A broad overview and an algorithm query remain distinct entry points.
+
 Full codebase exploration workflow — from indexing through architectural understanding. Chains indexing, graph algorithms, community detection, and temporal analysis into a structured onboarding experience. Use this when someone is new to a codebase and needs to build a mental model.
 
 ## Steps

package/skills/workflows/memtrace-first.md

@@ -43,8 +43,9 @@ matters. Retrieval is evidence, not a guarantee of complete coverage.
 
 ## Establish scope
 
-Call `list_indexed_repositories` once per session. Select the actual repository
-and branch; pass `repo_id` explicitly when possible. It lists this session's
+Select the actual repository and branch; pass `repo_id` explicitly when
+possible. When the task already names the repository, use it directly; call
+`list_indexed_repositories` only when the repository or branch is unknown. It lists this session's
 store only, so a repository missing from it may still be indexed and live in
 another store. Do not index a parent containing unrelated repositories. For a
 deliberately shared workspace, verify its workspace marker and scope before
@@ -85,7 +86,7 @@ answer from stale repos.
 ## Search, then investigate
 
 - Exact symbol: `find_symbol(name=..., repo_id=...)`.
-- Behavior or concept: `find_code(query=..., repo_id=...)`.
+- Behavior or concept: `find_code(query=..., repo_id=..., limit=10)` (default 20 rows).
 - Relationships: `get_symbol_context` or `analyze_relationships` on the useful hit.
 - Change impact: `get_impact`; confirm relevant callers against source.
 - Execution path: `get_process_flow`; follow its `next_offset` for further steps.
@@ -101,7 +102,8 @@ Treat partial context, truncation and unavailable overlay context as incomplete
 evidence; selected static flows are not complete runtime traces.
 
 `context.next_calls` provides scoped follow-up arguments for the useful symbol
-and process. Before changing shared behavior, inspect relevant callers and
+and process; copy them rather than rebuilding arguments. A `context.processes[].id`
+is the `process` for `get_process_flow`. Before changing shared behavior, inspect relevant callers and
 callees to identify contracts the patch must preserve. Use process IDs for
 flow navigation. No sampled flow is not proof that no call path exists.
 
@@ -112,8 +114,11 @@ Run related existing tests to detect regressions before claiming completion.
 
 Read the bounded source span when verifying behavior, editing or quoting. Do not
 fetch whole files or entire process traces when a local span answers the question.
-`get_symbol_context` omits source bodies by default; use `include_content: true`
-for explicit expansion, and `limit`/`offset` for relationship pages. An omitted
+`get_symbol_context` returns 5 rows per relationship section and omits source
+bodies and references by default: `pagination` names sections with more
+(`limit`/`offset`), `omitted` names what was left out (`include_references: true`,
+`include_details: true`), and `include_content: true` returns the symbol's body whole
+with short neighbour previews. An omitted
 risk diagnostic means unknown, not zero callers or low risk. Check truncation and
 pagination metadata before describing a neighborhood as complete.
 
@@ -241,8 +246,9 @@ when choosing among competing local idioms.
 
 Use JSON numbers for limits/depths and booleans for switches. Use symbol names
 for `get_symbol_context.symbol`, `get_impact.target` and relationship targets;
-use IDs only where the specific schema asks for one. Prefer the live schema over
-remembered parameters. `find_code` has no `kind` filter; use `find_symbol` for it.
+use IDs only where the specific schema asks for one. When a call is rejected,
+check that tool's schema rather than retrying from memory; do not pre-read schemas.
+`find_code` has no `kind` filter; use `find_symbol` for it.
 Search without an explicit repository uses safe scope inference, not an implicit
 search of every repository. `get_evolution` uses `from`, not `days`.
 

package/skills/workflows/memtrace-guided-refactor.md

@@ -0,0 +1,89 @@
+---
+name: memtrace-guided-refactor
+description: "Run a saved, staged refactor shared with Memtrace's Quality page. Use for splitting tangled functions, extracting helpers, or continuing a guided refactor run with fixed file scope and checks between edits."
+user-invocable: true
+---
+
+Use the `guided_refactor` MCP tool to track the same run shown in Quality. This
+skill coordinates the agent's edits and language tools; Memtrace does not execute
+shell commands or rewrite source on behalf of the browser. Never invent check
+results. Recorded checks are agent-reported evidence, not proof of equivalence.
+
+## Diagnose
+
+1. Resolve the repository and exact symbol/file with `find_symbol` and
+   `get_symbol_context`. Use the runtime attached to that repository.
+2. If a run ID was supplied, call `guided_refactor` with `action: "get"`,
+   `repo_id`, and `run_id`. Otherwise call `action: "list"` and reuse a relevant
+   unfinished run; create one with `file_path` and `symbol` only when needed.
+3. Inspect function complexity, affected callers, evolution/churn, module
+   boundaries, existing tests, and decision-memory constraints. Use
+   `get_function_quality_metrics`, `get_impact`, `get_evolution`, and
+   `get_symbol_context` as available; read the selected source. Record missing
+   evidence explicitly. LOC alone is never a reason to split code.
+4. Respect the returned classification. `Manual` runs permit diagnosis and
+   blueprint only. In this first version, staged source work is available for
+   Rust, TypeScript, JavaScript, Python, and Go in Git checkouts. Other indexed
+   languages and configuration files still get a saved manual plan. Nothing is
+   classified Automatic.
+
+## Blueprint
+
+Call `get` before running baseline checks and retain its `snapshot`. Run the
+project's compiler/type checker and relevant behavior tests. Compare the exported
+API and affected callers. If a check fails or is unavailable, record that fact;
+do not label it passed or begin source work.
+
+Submit `action: "blueprint"` with the returned `revision`, retained `snapshot`,
+diagnostic evidence in `note`, baseline `checks`, and 1–12 ordered `steps`:
+
+```json
+{
+  "title": "Capture diagnostic behavior",
+  "operation": "capture_tests",
+  "files": ["src/parser.rs", "tests/parser.rs"],
+  "boundary": "Add cases for existing diagnostics; preserve parsing behavior"
+}
+```
+
+The only staged operations are `capture_tests` and `extract_helper`. Name every
+file a step can change, including planned new files, with repository-relative
+paths. Keep each step small enough to review. Do not change generated code,
+ownership or lifetime contracts, macros, import side effects, public APIs, or
+configuration semantics as an incidental extraction. If those boundaries cannot
+be justified, pause and explain the manual decision needed.
+
+Every check has `kind` (`compiler`, `tests`, or `api`), `command`, `passed`, and
+`evidence`. All three kinds are required. Evidence should include exact commands,
+results/counts, and uncertainty. API evidence can be a documented source/caller
+comparison when the project has no API-check command.
+
+## Execute one step
+
+1. Call `get`, inspect saved state, and send `action: "begin"` with `revision`,
+   `snapshot`, and one stable `agent_id`. The coordinator refuses overlapping
+   active runs and source changes between steps. Do not delegate overlapping edits.
+2. Make only the active step's bounded change. Preserve existing unrelated edits.
+   Do not commit during a run: a changed Git HEAD requires a fresh diagnosis.
+3. Call `get` after editing and **before** running the checks. Retain that snapshot,
+   run the compiler, tests, and API comparison, then send `action: "checkpoint"`
+   with that same `snapshot`, current `revision`, `agent_id`, `checks`, and `note`.
+   Never refresh the snapshot after tests merely to get past a stale-source gate.
+4. Inspect the response. A paused run is not a passed checkpoint. Stop editing
+   until the failure is understood. Keep failed evidence visible. To resume after
+   fixing the active step, obtain a fresh snapshot, rerun all checks, and send
+   `action: "resume"` with checks and an explanation, then checkpoint the step.
+   Restore an accidental scope escape without discarding someone else's work;
+   otherwise create a new diagnosis with an explicitly reviewed scope.
+5. Begin the next step only after the preceding checkpoint is accepted.
+
+## Verify
+
+After every step is checked, the run enters Verify. Compare before/after
+complexity, callers, public API, test results, and the actual diff. Get a snapshot,
+run final checks, then submit `action: "complete"` with `revision`, `snapshot`,
+`agent_id`, `checks`, and the comparison in `note`. State what remains unproven.
+
+The Quality page shows saved stages, agent, scope, current tracked-file diff,
+failed checks, and the final comparison. Closing the browser does not discard the
+run. Use `pause` with a reason whenever the next safe step needs a decision.

package/skills/workflows/memtrace-refactoring-guide.md

@@ -23,6 +23,10 @@ user-invocable: true
 
 ## Overview
 
+For an executable sequence with persisted progress and checks between edits, use
+`memtrace-guided-refactor`. This guide remains the broader prioritization and
+planning workflow; a guided run carries an approved bounded plan into execution.
+
 Guided refactoring workflow — identifies refactoring candidates using structural analysis, scores them by risk and priority, checks Cortex decision memory for rationale/bans/contracts, and produces a phased refactoring plan. Combines complexity metrics, dead code detection, bridge analysis, temporal evolution, and decision memory to prioritize what to refactor first and how to do it safely.
 
 ## Steps

package/skills/workflows/memtrace-session-continuity.md

@@ -14,6 +14,10 @@ user-invocable: true
 
 ## Overview
 
+### Choose the scope
+
+Use this entry to resume from a saved session anchor. For the fixed last-24-hour briefing, hotspots, or a session self-audit, use `memtrace-daily`. Preserve the requested time window instead of treating both workflows as the same catch-up.
+
 Session continuity for agents. Store a timestamp from your last session and call `get_changes_since` to see exactly what happened since then — then drill into details with `get_evolution` if needed.
 
 **Core principle:** Persist a `since` timestamp (or the `until` from your last catch-up call). Never invent a `days` parameter.