superlocalmemory 3.7.8 → 3.8.0

package/plugin-src/rules/AGENTS.md

@@ -43,6 +43,16 @@ Apply automatically when context pressure builds:
 
 ---
 
+## Bounded loops
+
+When a task has a checkable acceptance condition (tests, schema, lint, reconciliation), run it as a **bounded loop**: iterate until an INDEPENDENT gate passes — never stop because the agent believes it is done. The agent's own "done" claim is advisory only; the gate is the authority.
+
+- Try it: `slm loop demo` (keyless convergence demo, records every lap to SLM).
+- Inspect: `slm loop history` / `slm loop show <run_id>` — each lap is persisted as queryable SLM memory (tag `loop:<name>`), so runs are auditable and resumable.
+- Terminal statuses: `DONE` (gate passed + approved), `HALT` (bound tripped: iterations/no-progress/budget), `PAUSE` (approval pending), `KILLED`, `ERROR`. Report the exact status — never turn HALT/PAUSE/ERROR into success. See slm-loop.
+
+---
+
 ## Session end
 
 Call `close_session(session_id)` when the work in the session is meaningfully complete. This finalises session metadata and allows the next session to find this one via `session_init`.
@@ -71,21 +81,50 @@ When the SLM MCP server is unavailable, use these CLI equivalents:
 
 ## Tool reference (core profile — 14 tools)
 
-| Tool               | Signature (key params)                                                         | Notes                              |
-|--------------------|--------------------------------------------------------------------------------|------------------------------------|
-| `remember`         | `content, tags="", project="", importance=5, session_id="", scope="personal", shared_with=""` | Store atomic fact. `scope` opt-in (personal default) |
-| `recall`           | `query, limit=10, agent_id, session_id="", fast=False, include_global, include_shared`         | Multi-channel retrieval. Scope flags off by default |
-| `search`           | `query, limit=10, profile_id=""`                                               | FTS5 BM25 keyword search           |
-| `fetch`            | `url, ...`                                                                     | Fetch remote content               |
-| `list_recent`      | `limit=20, profile_id=""`                                                      | Newest memories first              |
-| `update_memory`    | `fact_id, content, agent_id`                                                   | Correct an existing memory by id   |
-| `forget`           | `profile_id="", dry_run=True`                                                  | Decay cycle; always dry_run first  |
-| `session_init`     | `project_path="", query="", max_results=10, max_age_days=30`                   | Once per session; loads context    |
-| `close_session`    | `session_id=""`                                                                | Finalise session                   |
-| `slm_compress`     | `content, mode="auto", reversible=True, ttl_seconds=86400`                     | Returns compressed, lossy, ccr_id  |
-| `slm_retrieve`     | `ccr_id`                                                                       | Retrieve original from ccr_id      |
-| `slm_cache_set`    | `key, value, ttl_seconds=86400`                                                | KV cache set                       |
-| `slm_cache_get`    | `key`                                                                          | KV cache get; returns hit, value   |
-| `slm_optimize_stats` | `()`                                                                         | Returns compress_runs, tokens_saved_compress, cache_kv_hits |
-
-SuperLocalMemory v3.6.18 · Qualixar · AGPL-3.0-or-later
+> The MCP config ships `SLM_MCP_PROFILE=code` (24 tools): the 14 core memory tools below
+> **plus** 6 code-graph tools (`build_code_graph`, `get_blast_radius`, `query_graph`,
+> `semantic_search_code`, `get_review_context`, `detect_changes`) and `switch_profile`.
+> Use `full` (42 tools) to add mesh coordination. Use `power` (54 tools) for governance
+> and audit tools. See slm-profile for profile switching.
+
+| Tool               | Signature (key params)                                                                       | Notes                                  |
+|--------------------|----------------------------------------------------------------------------------------------|----------------------------------------|
+| `remember`         | `content, tags="", project="", importance=5, session_id="", scope="personal", shared_with=""` | Store atomic fact. `scope` opt-in (personal default). See slm-scope. |
+| `recall`           | `query, limit=10, agent_id, session_id="", fast=False, include_global, include_shared`       | Multi-channel retrieval. Scope flags off by default. See slm-scope. |
+| `search`           | `query, limit=10, profile_id=""`                                                             | FTS5 BM25 keyword search               |
+| `fetch`            | `url, ...`                                                                                   | Fetch remote content                   |
+| `list_recent`      | `limit=20, profile_id=""`                                                                    | Newest memories first                  |
+| `update_memory`    | `fact_id, content, agent_id`                                                                 | Correct an existing memory by id       |
+| `forget`           | `profile_id="", dry_run=True`                                                                | Decay cycle; always dry_run first      |
+| `session_init`     | `project_path="", query="", max_results=10, max_age_days=30`                                 | Once per session; loads context        |
+| `close_session`    | `session_id=""`                                                                              | Finalise session                       |
+| `slm_compress`     | `content, mode="auto", reversible=True, ttl_seconds=86400`                                   | Returns compressed, lossy, ccr_id      |
+| `slm_retrieve`     | `ccr_id`                                                                                     | Retrieve original from ccr_id          |
+| `slm_cache_set`    | `key, value, ttl_seconds=86400`                                                              | KV cache set                           |
+| `slm_cache_get`    | `key`                                                                                        | KV cache get; returns hit, value       |
+| `slm_optimize_stats` | `()`                                                                                       | Returns compress_runs, tokens_saved_compress, cache_kv_hits |
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| slm-recall | Multi-channel memory retrieval |
+| slm-remember | Store durable facts and decisions |
+| slm-session | Session lifecycle (init + close) |
+| slm-status | Health check, optimize stats |
+| slm-cache | KV cache for repeated reads |
+| slm-compress | Reversible context compression |
+| slm-graph | Code graph: blast radius, callers, search (code profile) |
+| slm-loop | Bounded, gate-verified agent loops with an SLM-backed ledger |
+| slm-scope | Personal / shared / global memory scoping |
+| slm-profile | Workspace isolation and profile switching |
+| slm-governance | Enterprise roles, retention, audit, GDPR |
+| slm-mesh | Cross-session peer coordination (full/mesh profile) |
+
+## Subagents
+
+- **slm-memory-advisor** — memory decisions, session hygiene, scope and profile guidance
+- **slm-optimize-advisor** — context compression and KV cache
+- **slm-governance-advisor** — scope/role compliance, retention policies, GDPR
+
+SuperLocalMemory v3.8.0 · Qualixar · AGPL-3.0-or-later

package/plugin-src/rules/CLAUDE.md.fragment

@@ -1,4 +1,4 @@
-<!-- BEGIN SuperLocalMemory v3.6.18 -->
+<!-- BEGIN SuperLocalMemory v3.8.0 -->
 
 ## SuperLocalMemory (SLM) — Agent Rules
 
@@ -24,6 +24,9 @@ Call `session_init(project_path, query)` ONCE per fresh session before any recal
 - NEVER compress/cache: code-for-edit, JSON-to-parse, secrets, ccr_ids, <500 chars.
 - If ok:false → continue with original; never block the task.
 
+### Bounded loops
+For a task with a checkable gate (tests/schema/lint), run a bounded loop: iterate until the INDEPENDENT gate passes, never on the agent's own "done" claim. `slm loop demo` to try; `slm loop history`/`slm loop show <run_id>` to inspect (laps persisted to SLM, tag `loop:<name>`). Statuses DONE/HALT/PAUSE/KILLED/ERROR — report exactly. See slm-loop.
+
 ### Session end
 `close_session(session_id)` when work is meaningfully complete.
 
@@ -31,14 +34,11 @@ Call `session_init(project_path, query)` ONCE per fresh session before any recal
 `slm recall "<q>" --limit N` · `slm search "<q>"` · `slm remember "<c>" --tags t` · `slm list --limit N` · `slm forget` (preview first) · `slm status` · `slm optimize status`
 
 ### Skills
-slm-recall · slm-remember · slm-session · slm-status · slm-cache · slm-compress · slm-graph
-
-### Commands
-/superlocalmemory:slm-recall · /superlocalmemory:slm-remember · /superlocalmemory:slm-session · /superlocalmemory:slm-status · /superlocalmemory:slm-cache · /superlocalmemory:slm-compress · /superlocalmemory:slm-graph
+slm-recall · slm-remember · slm-session · slm-status · slm-cache · slm-compress · slm-graph · slm-loop · slm-scope · slm-profile · slm-governance · slm-mesh
 
 ### Subagents
-slm-memory-advisor (memory decisions, session hygiene) · slm-optimize-advisor (context compression + KV cache)
+slm-memory-advisor (memory decisions, session hygiene, scope/profile guidance) · slm-optimize-advisor (context compression + KV cache) · slm-governance-advisor (scope/roles/compliance/GDPR)
 
-<!-- END SuperLocalMemory v3.6.18 -->
+<!-- END SuperLocalMemory v3.8.0 -->
 
-SuperLocalMemory v3.6.18 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v3.8.0 · Qualixar · AGPL-3.0-or-later

package/plugin-src/scripts/slm-launch

@@ -4,20 +4,59 @@
 # Cross-platform counterpart: slm-launch.bat (Windows)
 # Referenced by plugin/.mcp.json as the MCP server command.
 #
-# Resolves the correct venv binary for POSIX and joins the namespace daemon
+# Resolves the correct slm binary for POSIX and joins the namespace daemon
 # before opening the MCP stdio transport. This preserves one writer for all
 # parallel Claude sessions that share CLAUDE_PLUGIN_DATA.
 #
 # On Windows, Claude Code invokes slm-launch.bat instead (same-stem, .bat extension).
 #
 # Environment:
-#   CLAUDE_PLUGIN_DATA — persistent data dir where venv lives
+#   CLAUDE_PLUGIN_DATA — persistent data dir where the plugin venv lives
+#   SLM_DATA_DIR       — optional; SLM data dir (default: ~/.superlocalmemory)
+#   SLM_LAUNCHER       — optional; which slm binary to use:
+#                          plugin (default) — the plugin venv binary
+#                          system           — the system `slm` on PATH
+#                          <path>           — an explicit slm binary (leading ~ expanded)
 
-SLM_BIN="${CLAUDE_PLUGIN_DATA}/venv/bin/slm"
+_SLM_DATA="${SLM_DATA_DIR:-$HOME/.superlocalmemory}"
 
-if ! "${SLM_BIN}" serve start >&2; then
-    echo "SLM plugin: unable to start the owned daemon; refusing a direct MCP writer." >&2
-    exit 1
+# If a system daemon is already running (its pidfile points at a live process),
+# there is no need to boot the plugin's own venv daemon — we can open an MCP
+# writer against the daemon that is already up. This skips a redundant, slow
+# venv bootstrap on every session start.
+_daemon_running=0
+if [ -f "${_SLM_DATA}/daemon.pid" ] \
+   && kill -0 "$(cat "${_SLM_DATA}/daemon.pid" 2>/dev/null)" 2>/dev/null; then
+    _daemon_running=1
 fi
 
-exec "${SLM_BIN}" mcp
+case "${SLM_LAUNCHER:-plugin}" in
+    plugin)
+        SLM_BIN="${CLAUDE_PLUGIN_DATA}/venv/bin/slm"
+        # Only bootstrap the owned daemon when one is not already running.
+        if [ "${_daemon_running}" -eq 0 ]; then
+            if ! "${SLM_BIN}" serve start >&2; then
+                echo "SLM plugin: unable to start the owned daemon; refusing a direct MCP writer." >&2
+                exit 1
+            fi
+        fi
+        exec "${SLM_BIN}" mcp
+        ;;
+    system)
+        exec slm mcp
+        ;;
+    *)
+        # Explicit binary path. Expand a leading ~ to $HOME WITHOUT eval — eval
+        # on an environment value is a command-injection foot-gun. Only tilde
+        # expansion is supported here; pass an already-expanded path for $VARs.
+        case "${SLM_LAUNCHER}" in
+            "~"*) _SLM_BIN="${HOME}${SLM_LAUNCHER#\~}" ;;
+            *)    _SLM_BIN="${SLM_LAUNCHER}" ;;
+        esac
+        if [ ! -x "${_SLM_BIN}" ]; then
+            echo "SLM_LAUNCHER is not an executable slm binary: ${_SLM_BIN}" >&2
+            exit 1
+        fi
+        exec "${_SLM_BIN}" mcp
+        ;;
+esac

package/plugin-src/settings.json

@@ -4,7 +4,16 @@
       "mcp__superlocalmemory__remember",
       "mcp__superlocalmemory__recall",
       "mcp__superlocalmemory__search",
+      "mcp__superlocalmemory__fetch",
+      "mcp__superlocalmemory__list_recent",
       "mcp__superlocalmemory__session_init",
+      "mcp__superlocalmemory__close_session",
+      "mcp__superlocalmemory__build_code_graph",
+      "mcp__superlocalmemory__get_blast_radius",
+      "mcp__superlocalmemory__query_graph",
+      "mcp__superlocalmemory__semantic_search_code",
+      "mcp__superlocalmemory__get_review_context",
+      "mcp__superlocalmemory__detect_changes",
       "mcp__superlocalmemory__slm_compress",
       "mcp__superlocalmemory__slm_retrieve",
       "mcp__superlocalmemory__slm_cache_get",

package/plugin-src/skills/slm-cache/SKILL.md

@@ -137,4 +137,12 @@ These subcommands control daemon-level cache settings. They do not read or write
 
 ---
 
-SuperLocalMemory v3.6.18 · Qualixar · AGPL-3.0-or-later
+## Related skills
+
+- `slm-compress` — for large content reduction; cache and compress work together
+- `slm-status` — view `cache_kv_hits`/`cache_kv_misses` counters from `slm_optimize_stats`
+- `slm-profile` — cache entries are namespaced per profile; switching profiles gives a fresh cache namespace
+
+---
+
+SuperLocalMemory v3.8.0 · Qualixar · AGPL-3.0-or-later

package/plugin-src/skills/slm-compress/SKILL.md

@@ -140,4 +140,11 @@ Content over 1 MB (1 000 000 bytes UTF-8) is processed but `reversible` is force
 
 ---
 
-SuperLocalMemory v3.6.18 · Qualixar · AGPL-3.0-or-later
+## Related skills
+
+- `slm-cache` — for repeated reads; use cache-aside before compressing a frequently re-read result
+- `slm-status` — check `tokens_saved_compress` and `compress_runs` from `slm_optimize_stats`
+
+---
+
+SuperLocalMemory v3.8.0 · Qualixar · AGPL-3.0-or-later

package/plugin-src/skills/slm-governance/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: slm-governance
+description: Enterprise compliance and governed workspace behavior for SuperLocalMemory. Covers role-based access (admin/member/viewer), retention policies, audit trail, GDPR data export/erase, and how agents must behave when operating under workspace governance. Requires power MCP profile for audit/retention tools. Agents must never bypass governance controls.
+when_to_use: |
+  - "What can I do in this workspace?" (role check)
+  - "Set a 90-day retention policy on this memory"
+  - "Show the audit trail for recent memory operations"
+  - "Export my data for GDPR compliance"
+  - "Delete all memories for user X (right to erasure)"
+  - "Configure require-login for this workspace"
+  - Enterprise deployment with multi-team shared SLM
+  - Compliance, audit, or data governance task
+allowed-tools: audit_trail, set_retention_policy, get_retention_stats, get_lifecycle_status, recall, search, remember, Bash
+---
+
+# slm-governance — Enterprise Compliance and Governed Workspace Behavior
+
+SuperLocalMemory supports enterprise deployments with role-based access control,
+retention policies, audit logging, and GDPR compliance tooling. This skill
+documents how agents must behave when operating in a governed workspace and how
+to use the governance MCP tools (available in the `power` profile).
+
+---
+
+## Role model
+
+Governed workspaces have three roles:
+
+| Role | Read | Write personal | Write shared/global | Admin operations |
+|------|------|---------------|---------------------|-----------------|
+| `viewer` | Yes | No | No | No |
+| `member` | Yes | Yes | Yes (within access list) | No |
+| `admin` | Yes | Yes | Yes (unrestricted) | Yes |
+
+**Agent behavior by role:**
+
+- **Viewer**: Only call `recall`, `search`, `fetch`, `list_recent`. Never call
+  `remember`, `update_memory`, `forget`, or any write tool. If a write is
+  attempted, fail gracefully: "This workspace is read-only in viewer mode."
+- **Member**: May write personal facts and shared facts with permitted profiles.
+  May NOT write `scope="global"` facts without explicit admin authorization.
+  May NOT call `set_retention_policy`, `audit_trail`, or `compact_memories`.
+- **Admin**: Full access including governance tools in the `power` profile.
+
+An agent operating in a governed workspace must check its role before any write
+operation. Role information is visible in workspace configuration or via
+`slm status --json` (the `role` field, if present).
+
+---
+
+## Retention policies
+
+Retention policies control how long facts are stored before they become eligible
+for decay. Available in the `power` MCP profile.
+
+### Set a retention policy
+
+```
+set_retention_policy(
+  profile_id: str = "",   # "" = active profile
+  days: int = 90,         # facts older than this become decay-eligible
+  zone: str = "default",  # retention zone name
+)
+```
+
+Retention zones let you apply different policies to different fact categories:
+
+```
+# Standard facts: 90-day retention
+set_retention_policy(profile_id="", days=90, zone="default")
+
+# Security findings: 365-day retention (compliance requirement)
+set_retention_policy(profile_id="", days=365, zone="security")
+```
+
+Tag your facts with the zone name to route them to the right policy:
+```
+remember(content="Critical auth bypass in v2.1", tags="security,cve,finding", ...)
+```
+
+### Check retention statistics
+
+```
+get_retention_stats()
+```
+
+Returns zone distribution, average fact age, and decay-eligible counts. Use this
+to verify policies are working as expected.
+
+### Check lifecycle status
+
+```
+get_lifecycle_status()
+```
+
+Reports the state of the retention and decay subsystem — whether decay cycles are
+running, when the next cycle runs, and any backlog.
+
+---
+
+## Audit trail
+
+`audit_trail` is available in the `power` profile. It returns a structured log of
+recent memory operations (writes, reads, profile switches, policy changes).
+
+```
+audit_trail(
+  limit: int = 50,          # number of entries to return
+  operation: str = "",      # filter by operation type (e.g. "remember", "forget")
+  profile_id: str = "",     # filter by profile; "" = active profile
+)
+```
+
+Use this for:
+- Compliance reviews ("what data was written in the last 30 days?")
+- Investigating unexpected memory changes
+- Generating audit reports for data controllers
+
+The audit trail covers MCP and CLI operations. It does not record the content of
+facts by default — only operation type, timestamp, agent ID, and fact ID.
+
+---
+
+## GDPR compliance
+
+### Data export
+
+SLM does not have a dedicated MCP export tool. For GDPR data subject access
+requests, use the CLI:
+
+```bash
+# Export all memories in a profile to JSON
+slm status --json     # confirm active profile
+slm list --limit 9999 --json > export.json
+```
+
+For a complete export including entity graph data, run:
+```bash
+slm status --json
+```
+
+Contact your workspace admin to arrange a full database-level export if the CLI
+output is insufficient for compliance purposes.
+
+### Right to erasure
+
+To erase all memories for a subject or project:
+
+```bash
+# Step 1: preview what will be deleted (ALWAYS do this first)
+slm forget "<subject or project name>" --dry-run --json
+
+# Step 2: review the preview, then execute
+slm forget "<subject or project name>" --yes --json
+```
+
+For targeted deletion by fact ID:
+```bash
+slm delete <fact_id> --yes --json
+```
+
+For data reconstruction prevention: after erasure, confirm the fact is gone by
+running `slm recall "<content>"`. A successful erasure returns no results. Never
+attempt to re-derive erased content from other stored facts.
+
+---
+
+## require-login
+
+When `require_login` is enabled in workspace configuration, agents must
+authenticate before any memory operation. SLM handles authentication at the
+daemon level — agents do not need to pass credentials in tool calls. If an
+agent receives an authentication error from any MCP tool, it must:
+
+1. Stop the current operation immediately.
+2. Report the authentication requirement to the user.
+3. Never cache, retry, or work around the authentication block.
+
+---
+
+## Scope enforcement in governed workspaces
+
+In a governed workspace, scope restrictions are enforced server-side:
+- **Viewers** cannot write any fact regardless of `scope` parameter.
+- **Members** cannot write `scope="global"` unless their access list includes
+  the global scope — attempts return a permission error.
+- **Admins** can write any scope.
+
+Agents must not attempt to work around scope restrictions by splitting a global
+fact into multiple shared facts to accumulate equivalent visibility.
+
+---
+
+## Compact memories (admin-only)
+
+`compact_memories` deduplicates and consolidates stored memories. This is an
+admin operation — it can change fact IDs and remove content.
+
+```
+compact_memories(
+  profile_id: str = "",   # "" = active profile
+  dry_run: bool = True,   # ALWAYS true first — inspect before running
+)
+```
+
+Always run with `dry_run=True` first and review the impact report. Never run
+compaction without admin authorization.
+
+---
+
+## Consistency check (admin-only)
+
+```
+consistency_check(profile_id: str = "")
+```
+
+Verifies data integrity of the memory store — checks for orphaned entities,
+broken references, and index-database mismatches. Use after migrations or
+unexpected shutdowns. Returns a structured report.
+
+---
+
+## Agent checklist for governed workspaces
+
+Before each write operation:
+- [ ] Confirm my role allows writes (viewer → skip; member/admin → proceed)
+- [ ] Confirm scope is appropriate for my role (member → no global)
+- [ ] Set correct tags including zone name if retention policy applies
+- [ ] Pass `session_id` for full audit attribution
+
+Before running any destructive operation (`forget`, `compact_memories`):
+- [ ] Admin authorization confirmed
+- [ ] Ran with `dry_run=True` and reviewed output
+- [ ] GDPR: confirmed the subject or controller authorized the erasure
+
+---
+
+## Related skills
+
+- `slm-scope` — scope model details (personal/shared/global)
+- `slm-profile` — workspace isolation and profile switching
+- `slm-remember` — fact storage reference (includes scope parameters)
+- `slm-recall` — retrieval reference (includes scope read flags)
+- `slm-mesh` — mesh tools (full/power profiles)
+
+---
+
+*SuperLocalMemory v3.8.0 · Qualixar · AGPL-3.0-or-later*

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

@@ -285,7 +285,8 @@ If `build_code_graph` returns `files_parsed: 0`, no supported source files were
 
 ## Profile Requirement
 
-This skill uses graph tools that are only active under the `code` MCP profile. Your plugin `.mcp.json` must include:
+This skill uses graph tools that are only active under the `code` MCP profile
+(or `full` / `power`). Your plugin `.mcp.json` must include:
 
 ```json
 "env": {
@@ -293,8 +294,21 @@ This skill uses graph tools that are only active under the `code` MCP profile. Y
 }
 ```
 
-Without this, the six graph tools are not registered and will appear as unknown tools. Run `slm status` to confirm the active profile.
+Without this, the six graph tools are not registered and will appear as unknown
+tools. Run `slm status` to confirm the active profile.
+
+**Switching profiles at runtime (v3.8.0+):** Use `switch_profile("code")` via
+MCP to activate the code profile in a session that started with a different
+profile. See `slm-profile` for the full profile switching workflow.
+
+---
+
+## Related skills
+
+- `slm-profile` — workspace isolation and profile switching (required for code tools)
+- `slm-recall` — retrieve architectural decisions before graph queries
+- `slm-status` — confirm the active profile and graph index health
 
 ---
 
-SuperLocalMemory v3.6.18 · Qualixar · AGPL-3.0-or-later
+SuperLocalMemory v3.8.0 · Qualixar · AGPL-3.0-or-later

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

@@ -0,0 +1,99 @@
+---
+name: slm-loop
+description: Run gate-verified bounded loops with SuperLocalMemory as the durable ledger. Use when a task has a checkable acceptance condition (tests, schema, lint, reconciliation) and you must iterate until an INDEPENDENT gate passes — never stopping just because the agent believes it is done. `slm loop demo` runs a keyless convergence demo; `slm loop history` and `slm loop show <run_id>` inspect past runs whose every lap is persisted 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, resume a loop"
+allowed-tools: Bash, slm_recall
+---
+
+# 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 (see
+rungs below).
+
+## What SLM adds
+
+Every lap is written to SuperLocalMemory as a durable, queryable memory (tagged
+`loop:<name>`, session `loop:<run_id>`). That makes a run:
+
+- **auditable** — inspect the decision + gate verdict + budget for each lap;
+- **resumable / 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.
+
+## 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
+```
+
+`slm loop demo` proposes a fix, checks it against a deterministic gate that
+passes on lap 3, and records the run — a zero-setup way to see the control flow
+and confirm the SLM-backed ledger works end to end.
+
+## 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.
+- **kill switch** — set `SLM_LOOP_KILL` to stop before the next lap.
+- **approval rung** — L1 (report), L2 (assisted, pauses for approval), L3
+  (unattended). L2/L3 require approval before a passing gate is accepted as
+  DONE unless approval is explicitly configured off.
+
+## 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 <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).
+- `slm-session` — session lifecycle around a longer loop run.
+
+---
+
+SuperLocalMemory v3.8.0 · Qualixar · AGPL-3.0-or-later