@squadrules/mcp 5.9.8 → 5.10.1

package/dist/embed-docs/mem/adapter-migration.md

@@ -1,5 +1,5 @@
 ---
-version: "5.9.8"
+version: "5.10.1"
 slug: adapter-migration
 title: Adapter Migration Protocol
 ---

package/dist/embed-docs/mem/author-adapter.md

@@ -1,6 +1,6 @@
 ---
 slug: author-adapter
-version: "5.9.8"
+version: "5.10.1"
 title: Author Adapter (Create / Review / Refactor)
 ---
 
@@ -188,6 +188,26 @@ Summarise gathered requirements or findings.
 
 ## Draft Markdown
 
+### MCP / Local-Filesystem Boundary
+
+The MCP database and the local repo/filesystem are **independent environments**.
+
+- A personal adapter stored in MCP **cannot** reference local files
+  (`.qoder/rules/`, `src/`, etc.) — those files do not exist inside the MCP
+  execution context.
+- A personal adapter **cannot** use `mcp forward` contracts with
+  `squadrules://adapter/` URIs pointing to other personal adapters — the target
+  may not exist in every user's space.
+- Only **system adapters** (bundled in the server) can chain to other system
+  adapters via `forward`.
+- Personal adapters must be **self-contained**. If guidance text references a
+  local constraint file, it is prose-only context for the drafting agent, not a
+  runtime dependency.
+- When a shell contract needs a reusable script, attach it as an **artifact**
+  via `train` (with `mime`, `artifact_name`, `adapter_uri`) rather than
+  inlining it in the contract JSON. At execution time, reference it via
+  `export` with `squadrules://artifact/{uuid}`.
+
 ### For `create` — draft new adapter markdown
 
 Draft the full markdown for `train`.

package/dist/embed-docs/mem/bulk-insert-adapters-via-cli.md

@@ -1,6 +1,6 @@
 ---
 slug: bulk-insert-adapters-via-cli
-version: "5.9.8"
+version: "5.10.1"
 title: Bulk Insert Adapters via SQUADRULES CLI
 ---
 

package/dist/embed-docs/mem/challenge-type-guide.md

@@ -1,5 +1,5 @@
 ---
-version: "5.9.8"
+version: "5.10.1"
 slug: challenge-type-guide
 title: Challenge Type Selection Guide
 ---
@@ -51,6 +51,7 @@ code — use `shell` or `mcp` instead.
 - **clarify / approve** → `user_input`
 - **call a SQUADRULES / MCP tool** → `mcp`
 - **execute or verify local state** → `shell`
+- **delegate to another agent** → `subagent`
 - **pure reasoning with no observable artifact** → `comment`
 
 ### Decision Tree
@@ -64,7 +65,9 @@ Does the step call an MCP tool?
           ├─ YES → "shell"
           └─ NO → Does the step require human approval or choice?
                    ├─ YES → "user_input"
-                   └─ NO → "comment" only if there is no stronger observable contract
+                   └─ NO → Does the step delegate work to another agent?
+                            ├─ YES → "subagent" with optional context
+                            └─ NO → "comment" only if there is no stronger observable contract
 ```
 
 ### Challenge JSON Formats
@@ -99,6 +102,15 @@ proving the agent called the correct target — not just any `forward` call.
 {"contract":{"type":"comment","comment":{"min_length":50},"required":true}}
 ```
 
+**subagent**
+```json
+{"contract":{"type":"subagent","subagent":{"context":"<task description>"},"required":true}}
+```
+
+Use `subagent` when a step delegates work to another agent (human or AI) rather
+than executing it directly. The optional `context` field provides task-specific
+guidance. Evidence of completion is collected via the anti-cheat evidence gate.
+
 ### Solution JSON Formats
 
 Every solution, regardless of type, follows the same envelope:
@@ -163,12 +175,18 @@ Every solution, regardless of type, follows the same envelope:
 }
 ```
 
-### Compatibility
-
-The server also accepts older solution shapes where data is placed directly
-under the type key (e.g. `{ "type": "shell", "shell": { "exit_code": 0 } }`)
-instead of inside an `evidence` envelope. Always use the unified envelope with
-`outcome` and `evidence` for new protocols.
+**subagent solution**
+```json
+{
+  "type": "subagent",
+  "outcome": "success",
+  "evidence": {
+    "agent_id": "agent-uuid-or-name",
+    "artifacts": ["path/to/output"],
+    "summary": "Task completed successfully"
+  }
+}
+```
 
 ## Interpreter Selection
 
@@ -206,6 +224,61 @@ to avoid collisions between parallel sessions.
 - Reward Signal cleans it up
 - never write credentials or secrets to files
 
+### Resolving `project://` and `user://` URI hints
+
+The server returns relative URI hints — it never names an absolute path on its
+own filesystem. Resolve on your machine:
+
+| Scheme | Resolution | Example |
+|--------|-----------|--------|
+| `project://<rel>` | `<IDE project root>/<rel>` | `project://.local/squadrules/work` → `/home/user/repos/my-project/.local/squadrules/work` |
+| `user://<rel>` | `<$XDG_CONFIG_HOME or $HOME>/<rel>` | `user://.config/squadrules/work` → `/home/user/.config/squadrules/work` |
+
+When your session spans multiple projects, prefer `user://` to avoid ambiguity
+about which project root applies. When you have exactly one project context,
+`project://` is fine.
+
+### Worktree placement (for task-isolation adapters)
+
+When an adapter requires a git worktree for isolation, the worktree path MUST
+be **outside** every existing checkout. A common mistake is placing the worktree
+inside `$REPO_ROOT` (e.g. `$REPO_ROOT/.mcp.worktrees/...`), which the setup
+script correctly rejects.
+
+**Correct placement — absolute path examples:**
+
+```
+REPO_ROOT=/home/user/repos/my-project
+# RIGHT: sibling of the repo, not inside it
+WT=/home/user/repos/mcp.worktrees/<task-id>
+
+# WRONG: inside the checkout (rejected by setup script)
+# WT=/home/user/repos/my-project/.mcp.worktrees/<task-id>
+```
+
+**Common mistakes:**
+- `$REPO_ROOT/.mcp.worktrees/...` — inside checkout, rejected
+- `./mcp.worktrees/...` — relative path resolves inside checkout
+- `$REPO_ROOT/../mcp.worktrees/...` — correct only if `..` actually exits the repo
+
+**Rule of thumb:** `$(dirname "$REPO_ROOT")/mcp.worktrees/<task-id>`
+
+### IDE worktree access limitations
+
+Most IDE file tools (Write, Read, Edit) scope operations to the open project
+root. They **cannot** reach worktrees placed outside `$REPO_ROOT`. When working
+in an IDE:
+
+1. Use the **terminal/shell tool** (not IDE file tools) to read/write files in
+   external worktrees.
+2. Shell commands: `cat`, `tee`, `cp`, or your editor's CLI mode work on any
+   absolute path.
+3. If you need to edit a worktree file with IDE assistance, open the worktree
+   as a separate project window or use `code <worktree-path>` to add it to the
+   workspace.
+4. The `squadrules export` MCP tool can retrieve adapter content without
+   filesystem access to the worktree.
+
 ```json
 {"contract":{"type":"comment","comment":{"min_length":30},"required":true}}
 ```
@@ -265,6 +338,31 @@ to avoid collisions between parallel sessions.
 {"contract":{"type":"comment","comment":{"min_length":30},"required":true}}
 ```
 
+## Artifacts for Shell Contracts
+
+When a shell contract needs a reusable script (Python guard, validation logic,
+setup helper), **attach it as an artifact** rather than inlining it in the
+contract JSON:
+
+1. Write the script file.
+2. `train` with `mime: "text/x-python"`, `artifact_name: "isolation-guard.py"`,
+   `adapter_uri: "squadrules://adapter/my-adapter"`, and the script content in
+   `content`.
+3. In the shell contract, reference it via `export` with
+   `squadrules://artifact/{uuid}` at execution time.
+
+This keeps adapter markdown clean, makes scripts independently versionable,
+and avoids bloating contract JSON with large inline scripts.
+
+**Interpreter restriction:** The `interpreter` field in shell contracts accepts
+only: `bash`, `sh`, `python3`, `python`, `node`. Build tools (`terraform`,
+`docker`, `npm`, etc.) are **not** interpreters — wrap them in a `bash -c`
+command instead.
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":30},"required":true}}
+```
+
 ## Reward Signal
 
 Only reachable after all prior steps are solved.

package/dist/embed-docs/mem/create-new-protocol.md

@@ -1,5 +1,5 @@
 ---
-version: "5.9.8"
+version: "5.10.1"
 slug: create-new-protocol
 title: Create New Protocol (Redirect to Author Adapter)
 ---

package/dist/embed-docs/mem/critic-loop-guide.md

@@ -1,5 +1,5 @@
 ---
-version: "5.9.8"
+version: "5.10.1"
 slug: critic-loop-guide
 title: Critic Loop Integration and Mutation Gate Guide
 ---

package/dist/embed-docs/mem/critic-loop.md

@@ -1,5 +1,5 @@
 ---
-version: "5.9.8"
+version: "5.10.1"
 slug: critic-loop
 title: Critic Loop
 ---

package/dist/embed-docs/mem/phase-critic-guide.md

@@ -1,5 +1,5 @@
 ---
-version: "5.9.8"
+version: "5.10.1"
 slug: phase-critic-guide
 title: Phase Critic Guide (Redirect to Critic Loop Guide)
 ---

package/dist/embed-docs/mem/phase-critic.md

@@ -1,5 +1,5 @@
 ---
-version: "5.9.8"
+version: "5.10.1"
 slug: phase-critic
 title: Phase Critic (Redirect to Critic Loop)
 ---

package/dist/embed-docs/mem/protocol-linking-guide.md

@@ -1,5 +1,5 @@
 ---
-version: "5.9.8"
+version: "5.10.1"
 slug: protocol-linking-guide
 title: Protocol Linking Guide
 ---
@@ -217,6 +217,23 @@ calls that bypass `activate`.
 {"contract":{"type":"comment","comment":{"min_length":30},"required":true}}
 ```
 
+## Personal vs System Adapter Linking
+
+| Adapter type | Can `forward` to | Can be `forward`'d from |
+|---|---|---|
+| System adapter (bundled) | Other system adapters (slug guaranteed to exist) | System or personal adapters |
+| Personal adapter (MCP database) | **Nothing** — must be self-contained | Only via `activate` (runtime discovery) |
+
+Personal adapters use `comment` contracts to describe what the agent should do
+next (e.g. "activate a TDD execution adapter"), not `mcp forward` contracts to
+other personal adapters. A personal adapter that chains to
+`squadrules://adapter/some-personal-slug` will fail at runtime when that slug
+does not exist in the caller's MCP database.
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":30},"required":true}}
+```
+
 ## Reward Signal
 
 Only reachable after all prior steps are solved.

package/dist/embed-docs/mem/refine-search.md

@@ -1,5 +1,5 @@
 ---
-version: "5.9.8"
+version: "5.10.1"
 slug: refine-search
 title: Get help refining your search
 ---

package/dist/embed-docs/mem/skill-format-guide.md

@@ -1,5 +1,5 @@
 ---
-version: "5.9.8"
+version: "5.10.1"
 slug: skill-format-guide
 title: Skill Format and Local Authoring Guide
 ---