@squadrules/mcp 5.11.0 → 5.12.0

package/dist/embed-docs/mem/README.md

@@ -1,11 +1,11 @@
-# Bundled meta-protocols
+# Bundled meta-adapters
 
 This directory contains the bundled SQUADRULES-internal adapters and policy
 documents that are injected into the Squadrules app space at boot.
 
-<!-- squadrules-doc-keep: directory-local authority for the shipped meta-protocol bundle (slugs, versions, chain-linking rules); source of truth for these files, not a restatement of wiki Core Concepts -->
+<!-- squadrules-doc-keep: directory-local authority for the shipped meta-adapter bundle (slugs, versions, chain-linking rules); source of truth for these files, not a restatement of wiki Core Concepts -->
 
-Version: **4.3.0**
+Version: **5.0.0**
 
 ## Philosophy
 
@@ -23,17 +23,32 @@ adapters resolve intent from context, run critic-loop in a loop until it returns
 approve or acknowledge. Human escalation is reserved for genuinely ambiguous intent
 or a hard blocker (a required tool/auth that cannot be established automatically).
 
-Bundled mem resources that intentionally use **protocol** and **adapter** as
-synonyms. Prefer **adapter** in new copy when you are not mirroring user-facing trigger phrases.
+**Verification ladder (hard enforcement).** Every contract must use the strongest
+observable verification available:
 
-## Protocols
+1. `shell` — for file/state/command verification. **`interpreter` is REQUIRED**
+   (allowed: `bash`, `sh`, `python3`, `python`, `node`).
+2. `mcp` — **forward-links only**. Must use `tool_name: "forward"` with
+   `arguments.uri` matching `squadrules://adapter/<slug>`. Bare tool-name-only
+   mcp contracts are not valid.
+3. `subagent` — for delegated work that requires multi-step reasoning or tool
+   orchestration by another agent.
+4. `user_input` — only for genuine human decisions.
+5. `comment` — last resort. Max 1 per adapter, only as closing ACK for
+   knowledge/reference adapters.
+
+Bundled mem resources intentionally use **adapter** and **workflow** as preferred
+terms. Avoid bare "protocol" in new copy.
+
+## Adapters
 
 | File | Slug | Purpose |
 |------|------|---------|
-| [author-adapter.md](author-adapter.md) | `author-adapter` | Authoring adapter — create, review, or refactor SQUADRULES protocols |
+| [author-adapter.md](author-adapter.md) | `author-adapter` | Authoring adapter — create, review, or update SQUADRULES adapters |
 | [refine-search.md](refine-search.md) | `refine-search` | Refine search — recover user intent after failed `activate` |
 | [critic-loop.md](critic-loop.md) | `critic-loop` | Phase-boundary adversarial review — verify claims against evidence |
 | [adapter-migration.md](adapter-migration.md) | `adapter-migration` | Batch structural migration — update all adapters to latest scheme |
+| [bulk-insert-adapters-via-cli.md](bulk-insert-adapters-via-cli.md) | `bulk-insert-adapters-via-cli` | Bulk train adapters from a local directory via CLI |
 
 ### Linked authoring flow
 
@@ -45,22 +60,11 @@ author-adapter (Author) → forward(squadrules://adapter/critic-loop) → critic
 
 | File | Slug | Purpose |
 |------|------|---------|
-| [challenge-type-guide.md](challenge-type-guide.md) | `challenge-type-guide` | Challenge type selection, interpreter choice, and stronger verification patterns |
-| [protocol-linking-guide.md](protocol-linking-guide.md) | `protocol-linking-guide` | Layers vs chains, `activate` vs `forward` + slug, chaining back/forward, multi-layer conductor vs extension URI, chain-root collapsing, MCP argument validation |
+| [challenge-type-guide.md](challenge-type-guide.md) | `challenge-type-guide` | Challenge type selection, interpreter choice, and verification patterns |
+| [protocol-linking-guide.md](protocol-linking-guide.md) | `protocol-linking-guide` | Layers vs chains, `activate` vs `forward` + slug, chain-root collapsing, MCP forward-link validation |
 | [critic-loop-guide.md](critic-loop-guide.md) | `critic-loop-guide` | Critic-loop integration rules, mutation gates, solution check vs critic decision table |
 
-## Redirect tombstones
-
-Retired slugs kept as thin one-layer redirects so stored adapters that still
-reference them resolve instead of dangling (see ADR 0012):
-
-| File | Slug | Redirects to |
-|------|------|--------------|
-| [phase-critic.md](phase-critic.md) | `phase-critic` | `critic-loop` |
-| [phase-critic-guide.md](phase-critic-guide.md) | `phase-critic-guide` | `critic-loop-guide` |
-| [create-new-protocol.md](create-new-protocol.md) | `create-new-protocol` | `author-adapter` |
-
-## Cross-Protocol Linking
+## Cross-Adapter Linking
 
 ### Layers vs chains
 
@@ -75,7 +79,7 @@ cohesive concern.
 - runtime routing to different adapters is needed (Router pattern)
 - a step is reusable across multiple parent adapters (e.g. `critic-loop`)
 
-Chaining is NOT a replacement for layers. A 6-step protocol that fits in 350
+Chaining is NOT a replacement for layers. A 6-step adapter that fits in 350
 lines should stay as one adapter with 6 H2 layers.
 
 ### How forward + slug works
@@ -90,15 +94,9 @@ call forward with squadrules://adapter/implement-terraform and no solution to st
 Slugs are globally unique (enforced by `train`), so resolution is
 deterministic — no scoring, no ambiguity.
 
-### Verifying chain links with MCP argument checks
-
-A bare `mcp` contract checks only the tool name:
-
-```json
-{"contract":{"type":"mcp","mcp":{"tool_name":"forward"},"required":true}}
-```
+### MCP forward-link contracts
 
-An `mcp` contract **with `arguments`** verifies the exact target:
+All `mcp` contracts must be forward-links with arguments:
 
 ```json
 {"contract":{"type":"mcp","mcp":{"tool_name":"forward","arguments":{"uri":"squadrules://adapter/code-review-policy"}},"required":true}}
@@ -116,7 +114,7 @@ called `forward` with the correct slug, not just any `forward` call.
 | Target adapter is known at authoring time | `forward` + slug |
 | Target depends on runtime classification the current adapter cannot resolve | `activate` |
 | Linking to the next adapter in a chain | `forward` + slug |
-| Reusable sub-protocol invoked by multiple parents | `forward` + slug |
+| Reusable sub-adapter invoked by multiple parents | `forward` + slug |
 
 Never call `activate` just to get a slug you already know — it wastes a
 round-trip and introduces non-determinism.
@@ -125,7 +123,7 @@ round-trip and introduces non-determinism.
 
 When a chain has multiple adapters, `activate` might match a mid-chain adapter
 directly. Without protection, the agent would start at the wrong step, missing
-prerequisite context gathered by earlier phases.
+prerequisite context gathered by earlier steps.
 
 **`chain_root` frontmatter field** solves this at the server level. Add it to
 every mid-chain adapter:
@@ -144,11 +142,10 @@ choice's `uri` and `next_action` to point there. Multiple mid-chain matches
 from the same chain are deduplicated to a single entry. The agent always
 starts at the chain entry point.
 
-**Defense in depth — protocol-level safeguards:** In addition to server-side
-collapsing, each mid-chain adapter should include a **Prerequisites** paragraph
-in its Activation Patterns section that lists required inputs from earlier
-phases and directs the agent to start from the chain root if those inputs are
-missing. This catches direct `forward` calls that bypass `activate`.
+**Defense in depth:** Each mid-chain adapter should include a **Prerequisites**
+paragraph in its Activation Patterns section that lists required inputs from
+earlier steps and directs the agent to start from the chain root if those inputs
+are missing.
 
 **Rules:**
 

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

@@ -1,32 +1,31 @@
 ---
-version: "5.11.0"
+version: "5.12.0"
 slug: adapter-migration
-title: Adapter Migration Protocol
+title: Adapter Migration Workflow
 ---
 
-# Adapter Migration Protocol
+# Adapter Migration Workflow
 
 Batch-migrate all adapters in a space to the current structural scheme. Exports
 every adapter, applies conservative structural transformations, reports changes
 per adapter, and re-trains the conforming subset autonomously.
 
-This protocol handles structural migrations only — it preserves semantic content
+This workflow handles structural migrations only — it preserves semantic content
 (steps, intent, examples) while updating format, headings, and contract shapes
 to match the latest SQUADRULES requirements.
 
 ## Activation Patterns
 
-**Run this protocol when the user says ANY of:**
+**Run this workflow when the user says ANY of:**
 
 - "migrate all adapters" / "batch update adapters"
 - "update adapters to latest scheme" / "update adapter structure"
-- "run structural migration" / "migrate protocols"
+- "run structural migration" / "migrate adapters"
 - "update all my adapters" / "fix adapter structure"
 - "apply latest adapter format" / "restructure adapters"
-- "run adapter migration" / "migrate to new format"
 
 **Trigger pattern:** **migrate** / **batch update** / **structural migration** /
-**update format** + (adapters | protocols | all | space).
+**update format** + (adapters | all | space).
 
 **Must Never:**
 - Alter semantic content (step text, trigger phrases, examples, intent).
@@ -43,9 +42,8 @@ to match the latest SQUADRULES requirements.
 - Preserve the adapter's slug, version, and chain_root fields.
 
 **Good trigger examples:**
-- "migrate all my personal adapters to the latest format" → run this protocol
-- "update all adapters in the team space" → run this protocol
-- "we changed the solution scheme, update all adapters" → run this protocol
+- "migrate all my personal adapters to the latest format" → run this workflow
+- "update all adapters in the team space" → run this workflow
 
 **Bad trigger examples:**
 - "update this one adapter" → use `author-adapter` with `fix` operation
@@ -65,7 +63,7 @@ If any tool is unavailable, stop and report the connection blocker with
 remediation guidance.
 
 ```json
-{"contract":{"type":"comment","comment":{"min_length":80},"required":true}}
+{"contract":{"type":"shell","shell":{"cmd":"echo 'preflight: migration tools verified'","interpreter":"bash","timeout_seconds":10},"required":true}}
 ```
 
 ## Export All Adapters
@@ -80,7 +78,7 @@ Export every adapter from the target space using bulk export:
 If the space has no adapters, report this and stop.
 
 ```json
-{"contract":{"type":"mcp","mcp":{"tool_name":"export","arguments":{"all_adapters":true,"space_name":"<space>","format":"skill_tree"}},"required":true}}
+{"contract":{"type":"subagent","subagent":{"instruction":"Export all adapters from the target space using the export tool with all_adapters: true. Record the total count and extract slug, URI, and content for each adapter."},"required":true}}
 ```
 
 ## Analyze and Transform
@@ -93,24 +91,21 @@ For each exported adapter, perform structural analysis and apply migrations.
    `Reward Signal`. If missing or out of order, flag for restructuring.
 2. **Contract fences** — all contract JSON blocks must use ` ```json ` (not
    plain ` ``` `). If plain fences contain contract JSON, convert them.
-3. **Field rename** — any `"challenge":` key inside contract JSON blocks must
-   become `"contract":`. Apply globally within JSON fences.
-4. **Frontmatter** — must include `slug`. Add `version` if missing. Preserve
+3. **Frontmatter** — must include `slug`. Add `version` if missing. Preserve
    existing `chain_root` when present.
-5. **Line count** — adapters exceeding 350 lines must be flagged for splitting
+4. **Line count** — adapters exceeding 350 lines must be flagged for splitting
    (do NOT auto-split; report as manual review needed).
-6. **Critic-loop integration** — check whether the adapter includes at least
-   one `critic-loop` chain link. If not, add a recommendation (do NOT
-   auto-add; report as suggestion).
+5. **Shell interpreter** — every shell contract must include `"interpreter"`
+   field with an allowed value (`bash`, `sh`, `python3`, `python`, `node`).
+6. **MCP forward-link** — every mcp contract must use `tool_name: "forward"`
+   with `arguments.uri` matching `squadrules://adapter/<slug>`.
 
 ### Transformation rules
 
 - **Conservative only:** If a transformation might change meaning, skip it and
   flag for manual review.
-- **Reversible:** Every change must be expressible as a diff so it is auditable
-  and reversible.
-- **Idempotent:** Running migration twice on the same adapter produces no
-  additional changes.
+- **Reversible:** Every change must be expressible as a diff.
+- **Idempotent:** Running migration twice produces no additional changes.
 
 For each adapter, produce:
 - `status`: `needs_changes` | `up_to_date` | `needs_manual_review`
@@ -119,33 +114,28 @@ For each adapter, produce:
 - `transformed_content`: the full updated markdown (when `needs_changes`)
 
 ```json
-{"contract":{"type":"comment","comment":{"min_length":120},"required":true}}
+{"contract":{"type":"subagent","subagent":{"instruction":"Analyze each exported adapter against structural checks (heading order, contract fences, frontmatter, line count, shell interpreter, mcp forward-link). Apply conservative transformations and produce per-adapter status, changes, warnings, and transformed content."},"required":true}}
 ```
 
 ## Report Changes
 
-Record a summary table:
+Write the migration report to `$MIGRATION_REPORT_FILE` (absolute path under
+`$SQUADRULES_LOCAL_ARTIFACT_DIR`). Record a summary table:
 
 | Adapter slug | Status | Changes | Warnings |
 |-------------|--------|---------|----------|
 | example-adapter | needs_changes | 3 structural fixes | 0 |
 | another-adapter | up_to_date | 0 | 0 |
-| complex-adapter | needs_manual_review | 1 fix | line count exceeds 350 |
-
-For each adapter with `needs_changes`, show the specific transformations:
-- What was changed (before/after for the affected lines).
-- Why (which structural rule it satisfies).
 
-For each adapter with `needs_manual_review`, explain what needs human
-attention and why the protocol cannot auto-fix it.
+For each adapter with `needs_changes`, show the specific transformations.
+For each `needs_manual_review`, explain what needs human attention.
 
 Apply the migration autonomously:
 - **Apply all** `needs_changes` adapters.
-- **Leave untouched** every `needs_manual_review` adapter and report it with the
-  reason it cannot be auto-fixed.
+- **Leave untouched** every `needs_manual_review` adapter.
 
 ```json
-{"contract":{"type":"comment","comment":{"min_length":120},"required":true}}
+{"contract":{"type":"shell","shell":{"cmd":"test -f \"$MIGRATION_REPORT_FILE\" && grep -c '|' \"$MIGRATION_REPORT_FILE\" | test $(cat) -gt 1","interpreter":"bash","timeout_seconds":10},"required":true}}
 ```
 
 ## Execute Migration
@@ -153,8 +143,8 @@ Apply the migration autonomously:
 For each `needs_changes` adapter, apply the structural changes:
 
 1. For adapters needing only content-level fixes (heading reorder, fence
-   conversion, field rename): use `tune` with the transformed content and
-   the adapter's URI.
+   conversion, interpreter addition): use `tune` with the transformed content
+   and the adapter's URI.
 2. For adapters needing structural changes that alter layer count or identity:
    use `train` with `force_update: true` and the transformed content.
 3. Record the outcome (success or failure) for each adapter.
@@ -162,7 +152,7 @@ For each `needs_changes` adapter, apply the structural changes:
 Do NOT change the adapter's space assignment during migration.
 
 ```json
-{"contract":{"type":"comment","comment":{"min_length":120},"required":true}}
+{"contract":{"type":"subagent","subagent":{"instruction":"Execute the migration: for each needs_changes adapter, call tune (content-level fixes) or train with force_update (structural changes). Record success/failure per adapter."},"required":true}}
 ```
 
 ## Verify and Report
@@ -196,7 +186,8 @@ The adapter library in the target space now conforms to the current structural
 scheme. Every adapter has:
 - Correct heading order (Activation Patterns first, Reward Signal last).
 - Proper ` ```json ` contract fences.
-- Current field names (`contract`, not `challenge`).
+- Shell contracts with `interpreter` field.
+- MCP contracts as forward-links with `arguments.uri`.
 - Valid frontmatter with `slug` and optional `version`.
 - Been verified post-migration for structural compliance.