superlocalmemory 4.1.21 → 4.1.23

package/codex-plugin/skills/slm-graph/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: slm-graph
+description: >
+  Index and query a codebase as a structural graph — build the code graph, trace blast radius of a
+  change, find callers/callees/inheritors, semantic code search by meaning, assemble PR review
+  context, and detect what changed since last index. Use when the user asks how code connects, what
+  breaks if X changes, what calls a function, what a class inherits from, how to navigate an
+  unfamiliar codebase, or to understand risk before editing.
+when_to_use: |
+  - what calls X
+  - what breaks if I change Y
+  - what does Z inherit from
+  - find code that handles authentication
+  - impact analysis before editing
+  - code navigation in unfamiliar repos
+  - blast radius before a PR
+  - pre-commit change detection
+allowed-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": "codex"
+}
+```
+
+`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.23 · Qualixar · AGPL-3.0-or-later

package/codex-plugin/skills/slm-loop/SKILL.md

@@ -0,0 +1,153 @@
+---
+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.
+when_to_use: "run a bounded loop, gate-verified task, iterate until tests pass, verify against an independent gate, don't trust the agent's own done claim, slm loop, convergence loop, loop until green, loop ledger, wait for another agent's result"
+allowed-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.23 · Qualixar · AGPL-3.0-or-later