superlocalmemory 4.1.22 → 4.1.24

package/copilot-plugin/.github/prompts/slm-graph.prompt.md

@@ -0,0 +1,322 @@
+---
+name: slm-graph
+description: >
+version: "4.1.24"
+agent: agent
+tools:
+  - build_code_graph
+  - query_graph
+  - get_blast_radius
+  - semantic_search_code
+  - get_review_context
+  - detect_changes
+  - Bash
+---
+
+# slm-graph — Code Intelligence Skill
+
+Index any repo as a code knowledge graph and answer structural questions about it: callers, callees, impact radius, semantic search, and review context. These tools are only registered in the `code` MCP tool set (or with `SLM_MCP_ALL_TOOLS=1`); see "Tool set requirement" below.
+
+**Prerequisite rule:** every tool except `build_code_graph` self-guards — if the graph is not built it returns `{"success": false, "error": "Code graph not built. Run build_code_graph first."}`. Always index first.
+
+---
+
+## Tool Reference
+
+### 1. `build_code_graph` — index a repository
+
+```
+build_code_graph(
+    repo_path: str,
+    languages: str = "",
+    exclude_patterns: str = "",
+) -> {success, files_parsed, nodes, edges, flows, communities, duration_ms}
+```
+
+Parses all supported source files, extracts functions/classes/imports, builds the call graph, detects execution flows, and identifies code communities. Replaces any previous index for the same repo.
+
+- `repo_path` — absolute path to the repository root. Must exist and sit under your home directory; a path outside it is refused with `Invalid repo_path`.
+- `languages` — comma-separated language filter, e.g. `"python,typescript"`. Empty string = index all supported languages.
+- `exclude_patterns` — comma-separated glob patterns to exclude, e.g. `"**/node_modules/**,**/.venv/**"`. Empty = no exclusions.
+
+When to (re)build:
+- Before using any other graph tool for the first time on a repo.
+- After significant changes to the codebase (pull, merge, large refactor).
+- When `detect_changes` or `query_graph` returns stale/unexpected results.
+- Rebuild is safe and idempotent — it replaces the previous index atomically per file.
+
+```
+# Index the full repo
+build_code_graph(repo_path="/abs/path/to/myrepo")
+
+# Index only Python, skip tests and generated code
+build_code_graph(
+    repo_path="/abs/path/to/myrepo",
+    languages="python",
+    exclude_patterns="**/tests/**,**/generated/**"
+)
+```
+
+---
+
+### 2. `query_graph` — traverse relationships
+
+```
+query_graph(
+    pattern: str,
+    target: str = "",
+    limit: int = 20,
+) -> {success, pattern, target, results: [{qualified_name, kind, file_path, name}]}
+```
+
+Query the graph for structural relationships. `pattern` is required and must be one of the eight valid values below. `target` is a qualified name, partial name, or node ID — matched with exact-then-LIKE fallback.
+
+Valid patterns:
+
+| pattern | returns |
+|---|---|
+| `callers_of` | functions/methods that call `target` |
+| `callees_of` | functions/methods that `target` calls |
+| `imports_of` | modules/symbols that `target` imports |
+| `imported_by` | who imports `target` |
+| `tests_for` | test nodes associated with `target` |
+| `inherits_from` | base classes of `target` |
+| `inherited_by` | subclasses of `target` |
+| `contains` | symbols defined inside `target` (e.g. methods in a class) |
+
+```
+# Who calls the auth handler?
+query_graph(pattern="callers_of", target="authenticate_user")
+
+# What does the payment processor import?
+query_graph(pattern="imports_of", target="PaymentProcessor", limit=30)
+
+# What classes inherit from BaseModel?
+query_graph(pattern="inherited_by", target="BaseModel")
+```
+
+---
+
+### 3. `get_blast_radius` — impact analysis
+
+```
+get_blast_radius(
+    changed_files: str,
+    max_depth: int = 2,
+    max_nodes: int = 500,
+) -> {success, changed_nodes, impacted_nodes, impacted_files, edges, depth_reached, truncated}
+```
+
+Computes the full impact radius for one or more changed files using bidirectional BFS (callers and callees). Returns every node and file reachable within `max_depth` hops. Use this before editing to understand risk surface.
+
+- `changed_files` — comma-separated file paths relative to the repo root, e.g. `"src/auth/handler.py,src/auth/models.py"`.
+- `max_depth` — BFS depth. Default 2. Increase to 3–4 for deep call chains; lower to 1 for a quick first-degree check.
+- `max_nodes` — caps the result set. If `truncated=true` in the response, the real blast radius is larger.
+
+```
+# What breaks if I change the auth handler?
+get_blast_radius(changed_files="src/auth/handler.py")
+
+# Deeper analysis across two files
+get_blast_radius(
+    changed_files="src/payments/gateway.py,src/payments/models.py",
+    max_depth=3,
+    max_nodes=200
+)
+```
+
+If `truncated` is `true`, narrow the scope with `max_nodes` or reduce `max_depth` to get a reliable result.
+
+---
+
+### 4. `semantic_search_code` — find code by meaning
+
+```
+semantic_search_code(
+    query: str,
+    kind: str = "",
+    limit: int = 20,
+) -> {success, results: [{qualified_name, kind, file_path, score, line_start, name}]}
+```
+
+Hybrid FTS5 + vector search over all indexed code entities. Use when you know what the code *does* but not what it's *called*.
+
+- `query` — natural language description, e.g. `"retry logic for HTTP requests"` or `"parse JWT token from header"`.
+- `kind` — optional filter: `"Function"`, `"Class"`, `"File"`, or `"Test"`. Empty = all kinds. Case-insensitive match in the engine.
+- `limit` — max results. Default 20.
+
+Results include a `score` field (higher = more relevant).
+
+```
+# Find where authentication is handled
+semantic_search_code(query="authenticate user from request token")
+
+# Find only test functions that cover database writes
+semantic_search_code(query="database write transaction rollback", kind="Test")
+
+# Find the rate limiter class
+semantic_search_code(query="rate limiting middleware", kind="Class", limit=5)
+```
+
+---
+
+### 5. `get_review_context` — assemble PR review context
+
+```
+get_review_context(
+    changed_files: str,
+    include_source: bool = True,
+) -> {success, summary, review_items, test_gaps, risk_score}
+```
+
+Produces a token-optimized review package for a set of changed files: a plain-language summary, a ranked list of review items with per-node risk scores, and a list of changed symbols that have no associated test coverage.
+
+- `changed_files` — comma-separated file paths relative to the repo root.
+- `include_source` — whether to include source code snippets in the context (default `True`). Set `False` to reduce token usage when you only need the risk analysis.
+
+`risk_score` is a float 0–1 on the overall changeset. `review_items[].risk_score` is per-node.
+
+```
+# Get review context for a PR touching two files
+get_review_context(changed_files="src/auth/handler.py,src/auth/utils.py")
+
+# Risk summary only, no source snippets
+get_review_context(
+    changed_files="src/payments/gateway.py",
+    include_source=False
+)
+```
+
+---
+
+### 6. `detect_changes` — what changed since last index
+
+```
+detect_changes(
+    base: str = "HEAD~1",
+) -> {success, summary, risk_score, changed_functions, test_gaps, review_priorities}
+```
+
+Runs `git diff` against `base`, maps the changed hunks to graph nodes, and returns a risk-scored list of changed functions, test gaps, and review priorities. Requires the repo to be a git repository.
+
+- `base` — git ref to diff against. Default `"HEAD~1"` (one commit back). Any valid git ref works: `"main"`, `"v1.4.0"`, a commit SHA, etc.
+
+```
+# What changed in the last commit?
+detect_changes()
+
+# What changed since the release branch?
+detect_changes(base="release/1.4")
+
+# What changed relative to main?
+detect_changes(base="main")
+```
+
+Returns `error` if the repo root is not a git repository or if git is not available.
+
+---
+
+## Realistic Workflow
+
+### Explore an unfamiliar codebase
+
+```
+# 1. Index it
+build_code_graph(repo_path="/abs/path/to/repo")
+
+# 2. Find the entry point by meaning
+semantic_search_code(query="request router entry point", kind="Function")
+
+# 3. Trace what it calls
+query_graph(pattern="callees_of", target="handle_request")
+
+# 4. See who else calls the same core function
+query_graph(pattern="callers_of", target="authenticate_user")
+```
+
+### Before editing a function
+
+```
+# 1. Know what you are touching
+semantic_search_code(query="retry HTTP requests with backoff")
+
+# 2. Understand blast radius before making the change
+get_blast_radius(changed_files="src/http/client.py")
+
+# 3. Check test gaps
+get_review_context(changed_files="src/http/client.py")
+```
+
+### Pre-commit / PR review
+
+```
+# 1. What changed in this branch vs main?
+detect_changes(base="main")
+
+# 2. Full impact analysis for the changed files
+get_blast_radius(changed_files="src/auth/handler.py,src/auth/models.py")
+
+# 3. Assemble review context
+get_review_context(changed_files="src/auth/handler.py,src/auth/models.py")
+```
+
+---
+
+## Error Handling
+
+All tools return `{"success": false, "error": "<message>"}` on failure — they never raise.
+
+| Error message | Cause | Fix |
+|---|---|---|
+| `Code graph not built. Run build_code_graph first.` | No index exists | Call `build_code_graph(repo_path=...)` first |
+| `Repository path does not exist: <path>` | Bad `repo_path` in build | Pass an absolute path that exists |
+| `Git not available or not a git repository: ...` | `detect_changes` needs git | Only works in git repos with git installed |
+| `Invalid pattern '...'` | Wrong `pattern` in `query_graph` | Use one of the 8 valid pattern strings |
+| `No node found matching '<target>'` | Target not in index. Returned as `success: true` with an empty `results` and this `message`, not as an error | Rebuild or check the qualified name via `semantic_search_code` |
+| `Invalid repo_path: ...` | `repo_path` is outside your home directory | Index a repository under your home directory |
+
+If `build_code_graph` returns `files_parsed: 0`, no supported source files were found — check `repo_path` and `exclude_patterns`.
+
+---
+
+## Tool set requirement
+
+The six tools above are registered only when the MCP server runs the `code` tool
+set, or with `SLM_MCP_ALL_TOOLS=1` / `SLM_MCP_PROFILE=whole`, or when
+`SLM_MCP_TOOLS` names them. They are **not** in `core`, `full`, `power` or the
+no-profile default that the Claude Code and Codex plugins use, so with those
+settings the tools simply do not exist and a call fails as an unknown tool. The
+tool set is read when the server starts: set it in the host's MCP config and
+restart the host.
+
+```json
+"env": {
+  "SLM_MCP_PROFILE": "code",
+  "SLM_AGENT_ID": "claude_code"
+}
+```
+
+`switch_profile` does not change the tool set; it changes the active memory
+profile. See `slm-profile`. The `code` set leaves out the mesh and several
+administration tools, so ask the user before changing their tool set.
+
+With `SLM_MCP_ALL_TOOLS=1` more graph tools appear: `update_code_graph` (refresh
+for `changed_files` without a full rebuild), `list_graph_stats`,
+`get_architecture_overview`, `list_communities`, `get_community`, `list_flows`,
+`get_flow`, `get_affected_flows`, `find_large_functions`, `enrich_blast_radius`,
+`refactor_preview`, and the code-to-memory tools `link_memory_to_code`,
+`code_memory_search`, `code_entity_history` and `code_stale_check`. The memory
+links need `"bridge_enabled": true` in `code_graph_config.json` and a rebuild.
+All are host-only: a remote caller cannot use them.
+
+---
+
+## Related skills
+
+- `slm-profile` — memory profiles and the tool sets that decide which tools exist
+- `slm-recall` — retrieve architectural decisions before graph queries
+- `slm-status` — confirm the active profile and graph index health
+
+---
+
+SuperLocalMemory v4.1.24 · Qualixar · AGPL-3.0-or-later

package/copilot-plugin/.github/prompts/slm-loop.prompt.md

@@ -0,0 +1,159 @@
+---
+name: slm-loop
+description: Gate-verified bounded loops with SuperLocalMemory as the durable ledger. Use when a task has a checkable acceptance condition and you must iterate until an INDEPENDENT gate passes — never stopping because the agent believes it is done. `slm_loop_run` (MCP) waits, under hard bounds, for a recall gate to pass; `slm loop demo` shows the control flow keyless; `slm loop history` and `slm loop show <run_id>` (or `slm_loop_history` / `slm_loop_show`) inspect past runs, whose every lap is stored as queryable SLM memory (tag `loop:<name>`). Terminal statuses are DONE / HALT / PAUSE / KILLED / ERROR — report them exactly, never converting HALT/PAUSE/ERROR into success.
+version: "4.1.24"
+agent: agent
+tools:
+  - slm_loop_run
+  - slm_loop_history
+  - slm_loop_show
+  - recall
+  - Bash
+---
+
+# slm-loop — Bounded, gate-verified agent loops
+
+## The one rule
+
+A bounded loop is complete **only when an independent gate passes** — not when
+the agent claims it is finished. The agent's own "I'm done" signal is recorded
+for audit and is *never* used to terminate the loop. If you take one thing from
+this skill: **the gate is the authority.**
+
+Use a bounded loop whenever the goal has a mechanical, checkable contract: a
+test suite, a JSON schema, a linter, a reconciliation rule, a citation checker,
+a security scan. When the goal is subjective, keep a human approval gate.
+
+## What SLM runs, and what you run
+
+SLM's loop engine runs the laps, enforces the bounds, calls the gate and writes
+the ledger. It does **not** start your tests or linters: it carries no
+subprocess or sandbox machinery. What each surface gives you:
+
+| Surface | What it does |
+|---|---|
+| `slm_loop_run` (MCP) | A *watcher*: each lap is a recall of `gate_query`; the loop ends when a confident match appears, or a bound trips. Use it to wait for a verification or coordination memory another agent will write (for example "build passed"). |
+| `slm loop demo` (CLI) | A keyless convergence demo: a stub proposer, a deterministic gate that passes on lap 3, every lap recorded. Proves the engine and ledger work end to end. |
+| `slm loop history`, `slm loop show` / `slm_loop_history`, `slm_loop_show` | Read the ledger of past runs. |
+| `superlocalmemory.loops.run_bounded_loop` (Python) | The engine itself, for code that supplies its own runner and gate callables. |
+
+For a task whose gate is a command (`pytest -q`, a schema validation), you run
+that command yourself each lap with Bash and read its exit code; the discipline
+below still applies, but SLM is not recording those laps. For graph runs with
+receipts, use the separate Bounded Loops product; SLM can take a read-only
+snapshot of its finished runs with `observe_bounded_loop_evidence(workspace)`
+(an absolute path), which records observations only and never changes recall or
+ranking.
+
+## What SLM adds
+
+Every lap SLM runs is written as a durable, queryable memory (tagged `loop:<name>`,
+session `loop:<run_id>`). That makes a run:
+
+- **auditable** — inspect the decision, gate verdict and budget for each lap;
+- **historical** — a run's ledger survives across sessions;
+- **discoverable** — visible via `slm recall`, the dashboard, and any
+  SLM-integrated tool, alongside everything else the agent remembers.
+
+## MCP: `slm_loop_run`
+
+```
+slm_loop_run(
+  name: str,                    # 1–128 chars; also the memory tag
+  gate_query: str,              # the recall the gate checks each lap (up to 2000 chars)
+  gate_min_score: float = 0.0,  # minimum top-result score to pass
+  max_iterations: int = 20,     # hard lap cap, 1–200
+  max_wallclock_s: float = 15.0,# hard time cap; 0 disables; never more than 120
+  poll_interval_s: float = 1.0, # wait between laps; at least 0.25
+  max_tokens: int = 0,          # optional token budget; 0 disables
+  no_progress_window: int = 0,  # halt after N no-change laps; leave 0 for a watcher
+  require_support: bool = False,# pass only if the answer check ran and judged it sufficient
+)
+```
+
+The call **blocks** until the gate passes or a bound trips, then returns
+`{ok, status, reason, passed, laps, run_id, ledger: [{lap, decision, passed, detail}]}`.
+The gate recalls at most three memories per lap and ignores the loop's own
+ledger entries, so only a memory written by someone else can satisfy it. A
+recall the answer check judged insufficient never passes, even with a high
+score; with `require_support=True` an unchecked recall (check off, busy,
+loading, out of time) does not pass either. When the answer check is on, each
+lap asks it once about those memories; with the online check that is a request
+to the provider and may be billed. `slm_loop_run` is not available to remote
+callers.
+
+```
+slm_loop_history(name, limit=20)   # runs recorded under a loop name
+slm_loop_show(run_id, limit=200)   # every lap of one run, in order
+```
+
+## CLI
+
+```bash
+slm loop demo [--iterations N] [--json]   # keyless convergence demo
+slm loop history [--name NAME] [--json]   # list recorded runs
+slm loop show <run_id> [--json]           # every lap of one run
+```
+
+There is no `slm loop run`.
+
+## The bounds
+
+A loop runs inside a safety envelope. Any bound tripping ends the run with
+`HALT` (never a success):
+
+- **max_iterations** — a hard lap cap.
+- **no_progress_window** — consecutive no-change laps before halting a spinning
+  agent.
+- **token budget / wall-clock** — cumulative ceilings, checked again after each
+  lap, so an overshooting lap halts even if its gate would pass.
+- **kill switch** — a non-empty `SLM_LOOP_KILL` in the loop's process
+  environment stops it before the next lap, with status `KILLED`.
+- **approval rung** — L1 (report), L2 (assisted, pauses for approval), L3
+  (unattended). L2 and L3 require approval before a passing gate is accepted as
+  DONE unless approval is explicitly configured off. `slm_loop_run` and the demo
+  run at L1, so `PAUSE` arises only from code that sets a higher rung.
+
+## Terminal statuses — report exactly
+
+| Status   | Meaning |
+|----------|---------|
+| `DONE`   | The independent gate passed **and** approval was granted or not required. |
+| `HALT`   | A bound tripped (iterations, no-progress, token, or wall-clock). |
+| `PAUSE`  | The gate passed but required approval is not yet granted. |
+| `KILLED` | The external kill switch tripped between laps. |
+| `ERROR`  | The runner or gate failed to execute; inspect the lap detail. |
+
+Say `DONE` only when the status is exactly `DONE`. Never describe `HALT`,
+`PAUSE`, or `ERROR` as success. When halted, name which bound tripped; when
+paused, name the approval needed; when errored, quote the short detail.
+
+## Reporting workflow
+
+1. Run or resume the loop.
+2. Read back the ledger with `slm_loop_show` or `slm loop show <run_id>` (or
+   `slm recall` on tag `loop:<name>`).
+3. Report the exact terminal status, the lap count, and the gate's final
+   verdict. Include the `run_id` so the run can be re-inspected later.
+
+## Gate discipline
+
+- The gate verifies; the runner only proposes. They are separate.
+- Prefer a typed, parseable gate (a test exit code, a schema validation, a
+  scanner report) over a vague check. A missing tool, an empty report, or a
+  crashed scanner is **not** a clean pass — fail closed.
+- Never use "an LLM decides it looks good" as the gate. That reintroduces the
+  exact failure mode bounded loops exist to remove.
+
+---
+
+## Related skills
+
+- `slm-status` — confirm SLM is healthy before relying on the ledger.
+- `slm-recall` — query a loop's laps directly (`loop:<name>` tag), and the
+  answer-check fields the recall gate depends on.
+- `slm-session` — session lifecycle around a longer loop run.
+
+---
+
+SuperLocalMemory v4.1.24 · Qualixar · AGPL-3.0-or-later