@squadrules/mcp 5.10.1 → 5.12.0

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

@@ -1,94 +1,74 @@
 ---
 slug: author-adapter
-version: "5.10.1"
+version: "5.12.0"
 title: Author Adapter (Create / Review / Refactor)
 ---
 
-
-
 # Author Adapter (Create / Review / Refactor)
 
-> **Note to the agent:** SQUADRULES protocols are interfaces for AI agents — you
-> are the primary user. When you author a protocol, you design behaviour for
+> **Note to the agent:** SQUADRULES adapters are interfaces for AI agents — you
+> are the primary user. When you author an adapter, you design behaviour for
 > yourself and others. Write for them: single source of truth (never duplicate
 > rules), explicit over implicit (agents fill ambiguity with hallucination),
-> phases teach modes (each step teaches its cognitive mode), truth over fluency
-> (a protocol that reads well but causes wrong behaviour is worse than one that
+> steps teach modes (each step teaches its cognitive mode), truth over fluency
+> (an adapter that reads well but causes wrong behaviour is worse than one that
 > reads rough but executes correctly).
 
 ## Activation Patterns
 
-Preferred entry URI: `squadrules://adapter/author-adapter`. The retired
-`create-new-protocol` slug is a redirect tombstone (see phase-critic pattern).
+Preferred entry URI: `squadrules://adapter/author-adapter`.
 If `forward.authoring` is present, use its operation and target throughout this
 run. Do not reinterpret update as create or change the target mid-run. This
 context describes the requested work; it does not override host permissions.
 
-SQUADRULES authoring lifecycle — create, review, or update adapters / protocols / workflows.
-In this context, those words refer to the same stored artifact and can be treated
-as synonyms. Supports three operations:
-- **create** — draft and train a new adapter / protocol from scratch.
+SQUADRULES authoring lifecycle — create, review, or update adapters / workflows.
+Supports three operations:
+- **create** — draft and train a new adapter from scratch.
 - **review** — audit an existing adapter, family, or bundle for structural issues,
   missing cross-references, chaining gaps, DRY violations, stale guidance, or
   agent-hostile ambiguity. Read-only.
-- **update** — apply specific corrections to an existing adapter / protocol and
+- **update** — apply specific corrections to an existing adapter and
   save the correction. Also triggered by: edit, fix, modify, change, improve, patch, refactor.
-**Run this protocol when the user says ANY of:**
-- "create a new SQUADRULES protocol" / "create new protocol adapter"
-- "register personal SQUADRULES adapter" / "register a personal adapter"
-- "train adapter into personal" / "train protocol into personal"
-- "train a workflow" / "register a new adapter" / "create a new workflow"
-- "review protocol" / "audit adapters" / "check protocol families for gaps"
-- "update adapter" / "edit adapter" / "fix protocol" / "modify adapter"
-- "patch protocol" / "refactor protocol" / "change adapter" / "improve adapter"
-- "create new protocol" (when `activate` found no match and user confirms)
+
+**Run this adapter when the user says ANY of:**
+- "create a new SQUADRULES adapter" / "register a personal adapter"
+- "train adapter into personal" / "train a workflow"
+- "review adapter" / "audit adapters" / "check adapter families for gaps"
+- "update adapter" / "edit adapter" / "fix adapter" / "modify adapter"
+- "patch adapter" / "refactor adapter" / "change adapter" / "improve adapter"
+
 **Trigger pattern:** **create** / **train** / **register** / **review** /
 **audit** / **fix** / **update** / **edit** / **modify** / **change** /
 **improve** / **patch** / **refactor** / **correct** +
-(protocol / adapter / workflow).
+(adapter / workflow).
+
 **Must Never:**
-- Run when the user only asked to execute an existing protocol.
+- Run when the user only asked to execute an existing adapter.
 - Mutate adapters during a `review` operation.
-- Optimise only for pretty wording; this protocol designs agent behaviour.
+- Optimise only for pretty wording; this adapter designs agent behaviour.
 - Treat "update", "edit", or "modify an existing adapter" as **create**.
+
 **Must Always:**
 - Infer `{operation}` from trigger: create / review / update.
-  When the user says "update", "edit", "modify", or "fix" → operation is **update**.
 - Optimise for truth, low ambiguity, explicit sequencing, and user-need alignment.
-- Design or review phase transitions explicitly: discovery, clarification,
-  ideation, planning, execution, validation, review, handoff.
 - Include Activation Patterns as the first H2 and Reward Signal as the last H2
   in any newly drafted adapter.
 - Enforce the 350-line limit per file.
-**Good trigger examples:**
-- "Create a new SQUADRULES protocol for code review" → run this protocol (create)
-- "No match found; I want to create a new protocol" → run this protocol (create)
-- "Review all v4 protocol families for missing cross-references" → run this protocol (review)
-- "Update the MR adapter to include a review step" → run this protocol (update)
-- "Edit the critic-loop adapter triggers" → run this protocol (update)
-- "Refactor the MR adapter to be less ambiguous" → run this protocol (update)
-**Bad trigger examples:**
-- "Run the standardise project protocol" → use activate / forward
-- "Search for deployment protocol" → use activate
-- "Create an MR" → use the MR adapter, not this protocol
 
 ## Preflight Dependencies
 
-Before running authoring actions, verify dependency and auth readiness for this
-run:
-1. Required MCP tools are available and reachable: `activate`, `forward`,
-   `reward`, and the operation-dependent tool (`train`, `export`, or `tune`).
+Before running authoring actions, verify dependency and auth readiness:
+1. Required MCP tools are available: `activate`, `forward`, `reward`, and the
+   operation-dependent tool (`train`, `export`, or `tune`).
 2. Required CLI tools for planned shell steps are installed and callable.
 3. Required auth/session state is valid for the target MCP server.
 
-If any check fails, attempt AI-assisted remediation automatically (install or
-configure the missing tool, refresh auth/session), then re-run preflight. Only
-hard-stop when a required tool or auth genuinely cannot be established
-autonomously; report the concrete blocker and the remediation already attempted.
-Do not continue to intent resolution until preflight passes.
+If any check fails, attempt AI-assisted remediation automatically, then re-run
+preflight. Only hard-stop when a required tool or auth genuinely cannot be
+established autonomously.
 
 ```json
-{"contract":{"type":"comment","comment":{"min_length":80},"required":true}}
+{"contract":{"type":"shell","shell":{"cmd":"echo 'preflight: ok'","interpreter":"bash","timeout_seconds":10},"required":true}}
 ```
 
 ## Resolve Intent Autonomously
@@ -100,198 +80,101 @@ Use structured `authoring` when provided. For original calls without it, infer
 |---|---|
 | "create", "new", "train", no match from activate | **create** |
 | "review", "audit", "check", "gaps", "cross-references" | **review** |
-| "update", "edit", "fix", "modify", "change", "improve", "patch", "refactor", "add missing", "correct" | **update** |
+| "update", "edit", "fix", "modify", "change", "improve", "patch", "refactor" | **update** |
 
-Resolve the target from context without a confirmation prompt: for `create`,
-proceed to author a new adapter; for `review`, select the adapter(s), family, or
-bundle named or implied by the request; for `update`, select the adapter and the
-specific issue. Record the inferred operation and target, then continue. Escalate
-to the user only when the request is genuinely ambiguous and no reasonable default
-exists.
+Resolve the target from context without a confirmation prompt. Record the
+inferred operation and target, then continue. Escalate to the user only when
+the request is genuinely ambiguous and no reasonable default exists.
 
 ```json
-{"contract":{"type":"comment","comment":{"min_length":80},"required":true}}
+{"contract":{"type":"subagent","subagent":{"instruction":"Resolve the authoring operation (create/review/update) and target adapter from user context. Record the decision."},"required":true}}
 ```
 
 ## Gather Requirements
 
-### For `create` — collect details for a new protocol
+### For `create` — collect details for a new adapter
+
 **1. Determine the pattern:**
 
 | Signal | Pattern |
 |---|---|
-| One workflow, no variants | **Standalone** — one protocol, all steps inline |
-| Multiple issue types / output formats / media | **Router + Extensions** — router classifies, routes via `activate` |
-| Domain has a decision tree | **Router + Extensions** |
-| Single workflow but exceeds 350 lines or too complex for weaker models | **Chain** — split into sequential adapters linked via `forward` + slug |
-| Reference material needed by steps | Extract to a separate file, not a protocol |
-**2. Collect per protocol:**
-- **Title** — clear, descriptive H1.
-- **User problem** — what real problem does this solve?
-- **Agent behaviour** — what behaviour should this create in the agent?
-- **Mode map** — which steps are for discovery, clarification, ideation,
-  planning, execution, validation, review, or handoff?
-- **Steps** — each H2 must earn its place and end with a challenge.
-- **Challenge type per step** — use the strongest observable contract possible.
-- **Domain reference** — guides / docs the protocol should load.
-- **Existing protocols** — reuse, compose, or extract shared content.
-- **DRY / size check** — extract duplicated content; split if >350 lines.
-- **Chain position** — entry, middle, or exit? What slug does the previous link forward to?
-- **Failure analysis** — where would a weaker agent misread this protocol?
-**3. If Router pattern:** variants, classification questions, forbidden types,
-and which parts stay in the router vs extensions.
-**4. If Chain pattern:** Load `protocol-linking-guide` for full rules
-(`forward` with `squadrules://adapter/protocol-linking-guide`). Collect: chain
-links and concerns, minimum number of links, entry point (matched by
-`activate`), and artifacts flowing between links.
-
-### For `review` — audit existing adapters against this checklist
-
-Export target adapter(s). For each adapter, check:
-1. **User-need fit** — does the adapter solve a real user problem, or merely
-   mirror literal wording?
-2. **Mode / phase clarity** — are discovery, clarification, ideation,
-   execution, validation, and review clearly separated?
-3. **Cross-reference completeness** — are all required related adapters linked?
-4. **Adapter handoff gaps** — does it hand off where another adapter should own
-   the work?
-5. **DRY violations** — is policy content duplicated instead of linked?
-6. **Contract coverage** — does every executable H2 have the right contract?
-7. **Truth-first behaviour** — does it reduce guessing, fake certainty, and
-   silent assumption-making?
-8. **Activation pattern accuracy** — do triggers match what users actually say?
-9. **Structure compliance** — first H2 Activation Patterns, last H2 Reward
-   Signal, no duplicate H2s, under 350 lines.
-10. **Sibling consistency** — are equivalent steps present across sibling
-    adapters in the same family?
-11. **Chained adapter families** (when applicable) — extension adapters include
-    `chain_root` and a prerequisite clause pointing at the root; parent adapters
-    use explicit `forward` when the next adapter slug is already known; reserve
-    `activate` for ambiguous runtime discovery (see `protocol-linking-guide`,
-    **Chaining Back and Forward**).
-12. **Critic-loop integration** — does the adapter include critic-loop chain
-    links at major phase boundaries? Does each critic-loop invocation have a
-    FAIL gate shell contract (`grep -qi '^PASS$'` on the verdict file)? Are
-    solution checks restricted to irreversible remote mutations (see
-    `critic-loop-guide`)?
+| One workflow, no variants | **Standalone** — one adapter, all steps inline |
+| Multiple issue types / output formats | **Router + Extensions** — router classifies, routes via `activate` |
+| Exceeds 350 lines or too complex for weaker models | **Chain** — split into sequential adapters linked via `forward` + slug |
+
+**2. Collect per adapter:**
+- Title, user problem, agent behaviour, mode map, steps, challenge type per step
+- Domain reference, existing adapters to reuse/compose, DRY/size check
+- Chain position, failure analysis
+
+### For `review` — audit existing adapters
+
+Export target adapter(s). Check: user-need fit, mode/step clarity,
+cross-reference completeness, handoff gaps, DRY violations, contract coverage,
+truth-first behaviour, activation pattern accuracy, structure compliance
+(first H2 Activation Patterns, last H2 Reward Signal, under 350 lines),
+sibling consistency, chained adapter families, critic-loop integration.
 
 ### For `update` — identify the specific issue
 
 Export the target adapter, read the current markdown, identify the exact gap or
-error, and plan the minimal change. Do not alter unrelated layers.
-
-Summarise gathered requirements or findings.
+error, and plan the minimal change.
 
 ```json
-{"contract":{"type":"comment","comment":{"min_length":80},"required":true}}
+{"contract":{"type":"subagent","subagent":{"instruction":"Gather requirements for the resolved operation: collect pattern/details for create, audit checklist for review, or identify the specific issue for update."},"required":true}}
 ```
 
 ## 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.
+- A personal adapter stored in MCP **cannot** reference local files.
 - 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.
+- Personal adapters must be **self-contained**.
 - 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`.
-
-### For `review` — draft findings report
-
-Write a structured gap report to `$REVIEW_FINDINGS_FILE` (an absolute path
-provided by the invoking agent or chosen by you under
-`$SQUADRULES_LOCAL_ARTIFACT_DIR` with a session-unique segment). For each finding
-include:
-- adapter title
-- gap type
-- severity
-- why the issue matters for AI-agent behaviour
-- specific recommended fix
-
-### For `update` — draft corrected adapter markdown
-
-Apply the identified change and show a diff-style summary of what changed.
-
-### Shared drafting rules (all operations)
-**Core SQUADRULES rule — right mode at the right time:**
+  via `train` (with `mime`, `artifact_name`, `adapter_uri`).
 
-Every protocol must help the agent recognise whether the current step is for
-exploration, clarification, ideation, planning, execution, validation, review,
-or handoff. Do not blur those modes.
-**Truth over fluency:**
+### Drafting rules (all operations)
 
-Design protocols to reduce guessing and fake certainty. Prefer explicit prompts,
-explicit stop conditions, explicit uncertainty escalation, and observable
-verification over narrative reassurance.
-**User need over literal phrasing:**
+**Right mode at the right time:** Every adapter must help the agent recognise
+whether the current step is for exploration, clarification, ideation, planning,
+execution, validation, review, or handoff.
 
-The protocol should help the agent provide what the user actually needs, not
-just echo the wording used in the request.
-**DRY:**
+**Truth over fluency:** Prefer explicit prompts, stop conditions, uncertainty
+escalation, and observable verification over narrative reassurance.
 
-Shared content across protocols must live in one place. If two protocols share
->50% of their body, extract shared logic.
+**DRY:** Shared content across adapters must live in one place.
 
-**350-line maximum per file:**
+**350-line maximum per file.** Split into linked adapters if exceeded.
 
-No protocol file may exceed 350 lines. If it grows beyond that, split it into
-linked adapters or extract a reference file.
+**Slug convention:** Every adapter gets a short, unique, lowercase-hyphenated slug.
 
-**Generic-first — create generic, link from detailed:**
-
-Create protocols from generic to detailed. The generic adapter must stand alone.
-Extensions should contain only the delta.
-
-**Slug convention — deterministic protocol linking:**
-
-Every protocol gets a short, unique, lowercase-hyphenated `slug`.
-
-**Artifacts:**
-
-Store scripts or config blobs as artifacts via `train` (set `mime`,
-`artifact_name`, `adapter_uri`). Retrieve with `export` using
-`squadrules://artifact/{uuid}`.
-
-**Protocol structure:** H1 title, first H2 Activation Patterns, second H2
-Preflight Dependencies, middle H2s one per step with JSON contract block, last
-H2 Reward Signal. Frontmatter: `slug` (required), `version` (optional),
-`chain_root` (required for mid-chain adapters).
+**Structure:** H1 title, first H2 Activation Patterns, second H2 Preflight
+Dependencies, middle H2s one per step with JSON contract block, last H2 Reward
+Signal. Frontmatter: `slug` (required), `version` (optional), `chain_root`
+(required for mid-chain adapters).
 
 **Challenge types:** Load `challenge-type-guide` for decision rules and JSON
 formats (`forward` with `squadrules://adapter/challenge-type-guide`).
 
 **Critic-loop and mutation gates:** Load `critic-loop-guide` for placement,
-FAIL gate, and solution check rules (`forward` with `squadrules://adapter/critic-loop-guide`).
+FAIL gate, and solution check rules (`forward` with
+`squadrules://adapter/critic-loop-guide`).
 
-**If Router pattern:** draft the router and each extension as separate files.
-
-Post the full drafted markdown.
+For `create`: draft the full adapter markdown.
+For `review`: write a structured gap report to `$REVIEW_FINDINGS_FILE`.
+For `update`: apply the identified change and show a diff-style summary.
 
 ```json
-{"contract":{"type":"comment","comment":{"min_length":120},"required":true}}
+{"contract":{"type":"subagent","subagent":{"instruction":"Draft the adapter markdown (create), findings report (review), or corrected markdown (update) following all shared drafting rules."},"required":true}}
 ```
 
 ## Critic-Loop Review (create and update only)
 
-For `create` and `update`: run critic-loop against the drafted markdown. This is an
-autonomous quality loop — the agent owns content, the critic owns quality, and no
-human approval is requested at any point.
+For `create` and `update`: run critic-loop against the drafted markdown. This is
+an autonomous quality loop — the agent owns content, the critic owns quality, and
+no human approval is requested at any point.
 
 1. Invoke critic-loop via `forward` with `squadrules://adapter/critic-loop`.
    Submit the drafted markdown as a `file_set` work submission — write
@@ -302,7 +185,7 @@ human approval is requested at any point.
 2. Run the FAIL gate shell contract on the verdict file:
 
 ```json
-{"contract":{"type":"shell","shell":{"cmd":"head -1 \"$VERDICT_FILE\" | grep -qi '^PASS$'","timeout_seconds":5},"required":true}}
+{"contract":{"type":"shell","shell":{"cmd":"head -1 \"$VERDICT_FILE\" | grep -qi '^PASS$'","interpreter":"bash","timeout_seconds":5},"required":true}}
 ```
 
 3. If FAIL: address every finding, then re-invoke critic-loop and re-run the FAIL
@@ -313,29 +196,10 @@ human approval is requested at any point.
 
 For `review`: skip this step (read-only operation).
 
-```json
-{"contract":{"type":"comment","comment":{"min_length":80},"required":true}}
-```
-
-## Autonomous Review Gate
-
-No human approval step. The critic-loop PASS verdict from the previous step is the
-sole quality gate; once it is PASS, proceed directly to finalise.
-
-For `create`: record the drafted adapter slug(s) and the critic-loop verdict, then
-continue to `train`.
-
-For `review`: record the findings and the actions taken, then continue.
-
-For `update`: record the corrected markdown, the change summary, and the critic
-verdict, then continue.
-
-```json
-{"contract":{"type":"comment","comment":{"min_length":80},"required":true}}
-```
-
 ## FinaliseOperation
 
+No human approval step. The critic-loop PASS verdict is the sole quality gate.
+
 For `create`: call `train` with the drafted markdown and `review_evidence`
 from the critic-loop step. Use `force_update: false` unless overwrite was
 explicitly requested.
@@ -343,14 +207,12 @@ explicitly requested.
 For `review`: do not call `train`. Save the findings report only if requested.
 
 For `update`: use `tune` with the existing adapter URI, corrected content, and
-`review_evidence` for edits that preserve adapter identity and layer count.
-Use `train` with `force_update: true` only for a required structural replacement
-(such as changing identity/H1 mapping or layer count), preserving the intended
-space and verifying the resulting identity. Never create a duplicate as fallback.
-Update the corresponding repository source when the adapter is repo-managed;
-make repository edits in the task's isolated worktree.
-
-Report the outcome: adapter URI(s) for create / update, or findings summary for
+`review_evidence`. Use `train` with `force_update: true` only for a required
+structural replacement (changing identity/H1 mapping or layer count). Update the
+corresponding repository source when the adapter is repo-managed; make repository
+edits in the task's isolated worktree.
+
+Report the outcome: adapter URI(s) for create/update, or findings summary for
 review.
 
 ```json
@@ -359,11 +221,11 @@ review.
 
 ## Reward Signal
 
-Protocol complete when:
+Adapter complete when:
 - `create` — adapter(s) stored via `train` (with review_evidence) and URI(s) reported
 - `review` — findings report delivered
 - `update` — corrected adapter saved via `tune` (or required structural replacement),
   read back and verified; repo-managed source updated in the task worktree
 
 A successful result means the resulting SQUADRULES adapter is more truthful,
-phase-aware, agent-readable, and aligned with human–AI harmony.
+step-aware, agent-readable, and aligned with human–AI harmony.

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

@@ -1,6 +1,6 @@
 ---
 slug: bulk-insert-adapters-via-cli
-version: "5.10.1"
+version: "5.12.0"
 title: Bulk Insert Adapters via SQUADRULES CLI
 ---
 
@@ -12,42 +12,43 @@ Batch-register multiple SQUADRULES adapters from a local directory tree using th
 `squadrules train` CLI. Handles directory scanning, validation, space targeting,
 and error recovery for bulk operations.
 
-**Run this protocol when the user says ANY of:**
+**Run this workflow when the user says ANY of:**
 
 - "bulk insert adapters" / "bulk train adapters"
-- "train all protocols in a directory"
+- "train all adapters in a directory"
 - "batch register adapters from folder"
 - "upload all .md files to SQUADRULES"
-- "sync local protocols to SQUADRULES" / "push protocols to SQUADRULES"
+- "sync local adapters to SQUADRULES" / "push adapters to SQUADRULES"
 - "train directory recursively" / "train --recursive"
 
 **Trigger pattern:** **bulk** / **batch** / **all** / **directory** / **recursive** +
-(train | insert | register | upload | push | sync) + (adapters | protocols).
+(train | insert | register | upload | push | sync) + (adapters | workflows).
 
 **Must Never:**
 
 - Train files without first validating their structure.
-- Overwrite existing adapters without explicit user confirmation (`--force`).
-- Train files that contain secrets or token-like strings without `--allow-sensitive-upload`.
+- Overwrite existing adapters without explicit `--force`.
+- Train files that contain secrets or token-like strings without
+  `--allow-sensitive-upload`.
 - Skip reporting partial failures in a batch.
 
 **Must Always:**
 
 - Verify the target directory exists and contains `.md` files.
-- Show the user the file list and target space before executing.
+- Show the file list and target space before executing.
 - Report per-file success/failure after the batch completes.
 - Respect the user's choice of space (personal or group).
 
 **Good trigger examples:**
 
-- "Train all adapters in squadrules-v4/_personal/" → run this protocol
-- "Bulk insert the protocols from my export folder" → run this protocol
-- "Push all .md files in this directory to my personal space" → run this protocol
+- "Train all adapters in my-adapters/" → run this workflow
+- "Bulk insert the adapters from my export folder" → run this workflow
+- "Push all .md files in this directory to my personal space" → run this workflow
 
 **Bad trigger examples:**
 
-- "Train this one protocol" → use `squadrules train <file>` directly
-- "Create a new protocol" → use `author-adapter`
+- "Train this one adapter" → use `squadrules train <file>` directly
+- "Create a new adapter" → use `author-adapter`
 - "Export my adapters" → use `squadrules export`
 
 ## Preflight Dependencies
@@ -62,42 +63,30 @@ Verify before execution:
 If any check fails, stop and report the issue with remediation guidance.
 
 ```json
-{"contract":{"type":"shell","shell":{"cmd":"squadrules --version && squadrules token > /dev/null 2>&1 && echo 'auth: ok'","timeout_seconds":15},"required":true}}
+{"contract":{"type":"shell","shell":{"cmd":"squadrules --version && squadrules token > /dev/null 2>&1 && echo 'auth: ok'","interpreter":"bash","timeout_seconds":15},"required":true}}
 ```
 
-## Resolve Scope Autonomously
+## Resolve Scope and Validate
 
-Resolve and record the batch operation details:
+Resolve the batch operation details autonomously:
 
 1. **Source directory** — absolute path.
 2. **File count** — number of `.md` files found (recursive or flat).
 3. **Target space** — personal (default) or a named group space.
 4. **Force mode** — whether `--force` will be used (overwrites existing).
-5. **Model attribution** — which `--model` value to use.
-
-List the files that will be trained, record the resolved scope, and proceed
-autonomously — no confirmation prompt.
-
-```json
-{"contract":{"type":"comment","comment":{"min_length":80},"required":true}}
-```
-
-## Validate Structure
-
-Before training, validate each `.md` file against SQUADRULES adapter requirements:
 
+Validate each `.md` file against SQUADRULES adapter requirements:
 - Has an H1 title.
 - First H2 is "Activation Patterns".
 - Last H2 is "Reward Signal".
 - Contains at least one fenced `json` block with a top-level `contract` object.
 - Does not exceed 350 lines.
 
-Report any files that fail validation, then proceed autonomously: skip the invalid
-files, train the valid subset, and document every skipped file with its validation
-error and a suggested fix. Do not stop to ask the user.
+Skip invalid files, train the valid subset, and document every skipped file with
+its validation error and a suggested fix. Do not stop to ask the user.
 
 ```json
-{"contract":{"type":"shell","shell":{"cmd":"echo 'Validation complete — see output above for results'","timeout_seconds":30},"required":true}}
+{"contract":{"type":"shell","shell":{"cmd":"test -d \"$SOURCE_DIR\" && find \"$SOURCE_DIR\" -name '*.md' | head -1 | grep -q .","interpreter":"bash","timeout_seconds":10},"required":true}}
 ```
 
 ## Execute Bulk Train
@@ -109,14 +98,13 @@ squadrules train <directory> --recursive --model <model> --space <space> [--forc
 ```
 
 If the directory contains files that should NOT be trained (README, reference
-docs), either:
-- train file-by-file for the valid subset, or
-- move non-adapter files out before running `--recursive`
+docs), either train file-by-file for the valid subset, or move non-adapter files
+out before running `--recursive`.
 
 Capture stdout and stderr. The CLI reports per-file status.
 
 ```json
-{"contract":{"type":"shell","shell":{"cmd":"squadrules train <directory> --recursive --model <model_id> --space <space>","timeout_seconds":120},"required":true}}
+{"contract":{"type":"shell","shell":{"cmd":"squadrules train \"$SOURCE_DIR\" --recursive --model \"$MODEL_ID\" --space \"$TARGET_SPACE\"","interpreter":"bash","timeout_seconds":120},"required":true}}
 ```
 
 ## Report Results
@@ -130,11 +118,7 @@ Summarise the batch outcome:
 | Failed | N |
 | Skipped (invalid) | N |
 
-For each failure, report:
-- File path
-- Error message
-- Suggested fix
-
+For each failure, report: file path, error message, suggested fix.
 If all succeeded, confirm adapter URIs are accessible via `squadrules spaces`.
 
 ```json
@@ -143,11 +127,11 @@ If all succeeded, confirm adapter URIs are accessible via `squadrules spaces`.
 
 ## Reward Signal
 
-Protocol complete when:
+Workflow complete when:
 - All valid adapter files in the target directory have been trained to the
   specified space.
-- Per-file results have been reported to the user.
+- Per-file results have been reported.
 - Any failures have been documented with remediation guidance.
 
-A successful bulk insert means the user's local protocol library is now
+A successful bulk insert means the user's local adapter library is now
 registered in SQUADRULES and available for activation by AI agents.