@squadrules/mcp 5.13.7 → 5.14.0

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

@@ -1,6 +1,6 @@
 ---
 slug: author-adapter
-version: "5.13.7"
+version: "5.14.0"
 title: Author Adapter (Create / Review / Refactor)
 ---
 
@@ -30,6 +30,10 @@ Supports three operations:
 - **update** — apply specific corrections to an existing adapter and
   save the correction. Also triggered by: edit, fix, modify, change, improve, patch, refactor.
 
+A fourth lifecycle operation, **delete**, is not run here: follow the Delete flow
+in `docs/adapter-authoring-guide.md` (export, check the slug is not a chain
+dependency, call `delete`, verify it no longer resolves).
+
 **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"
@@ -45,6 +49,8 @@ Supports three operations:
 **Must Never:**
 - Run when the user only asked to execute an existing adapter.
 - Mutate adapters during a `review` operation.
+- Review your own draft: the critic pass is delegated, never performed on the
+  drafting thread.
 - Optimise only for pretty wording; this adapter designs agent behaviour.
 - Treat "update", "edit", or "modify an existing adapter" as **create**.
 
@@ -60,16 +66,15 @@ Supports three operations:
 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.
+2. A subagent facility is available in this host for the critic pass. Without it
+   this adapter cannot verify its own work: stop and report the blocker rather
+   than reviewing the draft yourself.
 3. Required auth/session state is valid for the target MCP server.
 
 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":"shell","shell":{"cmd":"echo 'preflight: ok'","interpreter":"bash","timeout_seconds":10},"required":true}}
-```
+established autonomously. These are checks you perform, not gates: a failure here
+produces a repair action, so no contract is spent on them.
 
 ## Resolve Intent Autonomously
 
@@ -86,10 +91,6 @@ 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":"subagent","subagent":{"context":"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 adapter
@@ -113,27 +114,75 @@ 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.
+sibling consistency, chained adapter families, and whether every critic hop in
+the audited adapters is a `subagent` contract rather than a `forward` contract.
 
 ### 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.
 
-```json
-{"contract":{"type":"subagent","subagent":{"context":"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
+
+### Allocate the handoff paths first
+
+The gates below read files that only exist if you created them. Resolve one hint
+from the `squadrules_local_artifact_dir` field of the latest `activate` or
+`forward` response (`project://<rel>` → this project root, `user://<rel>` → your
+home or `$XDG_CONFIG_HOME`), export the absolute result as
+`SQUADRULES_LOCAL_ARTIFACT_DIR`, then allocate collision-free paths for the
+target slug:
+
+```bash
+export SQUADRULES_LOCAL_ARTIFACT_DIR="<resolved absolute path>"
+D="$SQUADRULES_LOCAL_ARTIFACT_DIR/author-adapter-$SLUG"
+mkdir -p "$D"
+export WORK_MANIFEST="$D/work-manifest.txt"      # the critic's submission
+export VERDICT_FILE="$D/verdict.txt"             # the critic's verdict
+export REVIEW_FINDINGS_FILE="$D/findings.md"     # review operation only
 ```
 
-## Draft Markdown
+The server never names a path on your machine; you do.
 
 ### MCP / Local-Filesystem Boundary
 
 - 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**.
-- When a shell contract needs a reusable script, attach it as an **artifact**
-  via `train` (with `mime`, `artifact_name`, `adapter_uri`).
+- Any adapter — system or personal — may chain to another adapter with a
+  `forward` contract naming `squadrules://adapter/<slug>`; slugs are globally
+  unique, so resolution is deterministic.
+- A personal adapter must still be **self-contained** in its instructions: it
+  cannot rely on files that only exist in one repository.
+- When a `shell` check has more than one condition, parses JSON, or does not fit
+  one readable line, put it in a **gate script artifact** — it is stored with the
+  adapter and materialized at run time, not read from your local files; never
+  escape a program inline into `cmd`.
+- Order: `train` the adapter markdown first, then `train` the script as an
+  artifact — an artifact attaches only to an adapter that already exists. Pin the
+  script's identity with a `# squadrules-artifact:` header, and pass
+  `force_update: true` on a re-train that matches it, so a fix updates
+  that artifact instead of adding a second one. Input fields and the refusal
+  message: the `train` tool description.
+- The artifact train targets `squadrules://adapter/<slug>`, so pin the adapter's
+  slug with frontmatter `slug:` instead of guessing the slug `train` derived from
+  the title.
+- Keep the contract one line: `interpreter: "bash"`, `cmd: python3
+  "$SQUADRULES_LOCAL_ARTIFACT_DIR/artifacts/<name>.py" --gate <name>`.
+- Verify before shipping — **two** checks, both required:
+  1. `activate` the adapter and confirm `linked_artifacts[].relative_path` is
+     exactly the path `cmd` invokes. Run each row's `materialize` command before
+     the contract that needs it.
+  2. **Export check:** call MCP **`export`** with
+     `uri: "squadrules://adapter/<slug>"` and `format: skill_tree` (or
+     `skill_zip` for the bundle) and confirm the script is present under
+     `artifacts/` at the path the contract invokes. Read the returned
+     `diagnostics[]`: `artifact_stored_sha_mismatch` or
+     `artifact_relative_path_invalid` means the stored artifact is broken —
+     re-train it instead of shipping it.
+- A `cmd` that names a script the export does not contain is a broken adapter:
+  it fails at run time with a missing-file error and burns the user's step.
+  Fix it before shipping. The only exception is a repository-owned gate that
+  the adapter names explicitly and that lives in the user's repository — say so
+  in the adapter text, and state how the agent finds it.
 
 ### Drafting rules (all operations)
 
@@ -151,81 +200,94 @@ escalation, and observable verification over narrative reassurance.
 **Slug convention:** Every adapter gets a short, unique, lowercase-hyphenated slug.
 
 **Structure:** H1 title, first H2 Activation Patterns, second H2 Preflight
-Dependencies, middle H2s one per step with JSON contract block, last H2 Reward
+Dependencies, middle H2s one per stage 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`).
+**Scripts are obtained, not assumed:** when a step's `cmd` invokes a script, the
+adapter must state in its own text how the agent obtains that file before
+running the command — materialize the `activate` artifact row, or `export` the
+adapter. A step that says only "run `python3 …/artifacts/x.py`" leaves the agent
+guessing where the file is; a missing-file gate failure is the most common
+result of that omission.
+
+**Contracts:** One per adapter is the default; a second is justified only at a
+boundary that is hard to roll back. 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
+the FAIL gate, and the work-submission rules (`forward` with
 `squadrules://adapter/critic-loop-guide`).
 
 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":"subagent","subagent":{"context":"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`: have the draft reviewed. This is an autonomous quality
+loop — the agent owns content, the critic owns quality, and no human approval is
+requested at any point. The critic must not be you: you wrote the draft, so your
+own re-reading cannot detect what you did not intend to write.
 
-1. Invoke critic-loop via `forward` with `squadrules://adapter/critic-loop`.
-   Submit the drafted markdown as a `file_set` work submission — write
-   `kind: file_set`, `root: <directory of the draft>`, then the drafted file
-   under `items:` into the handoff pointed to by `$WORK_MANIFEST` — with the
-   slug as `calling_protocol_slug` and "structural compliance and agent
-   behaviour" as `verification_target`.
-2. Run the FAIL gate shell contract on the verdict file:
+Write the submission handoff to `$WORK_MANIFEST` as flat keys — `kind: file_set`,
+`root: <directory of the draft>`, then `items:` with the drafted file's path on
+one line — and delegate the review to a subagent. Delegate it now; do not audit
+the draft on this thread first.
 
 ```json
-{"contract":{"type":"shell","shell":{"cmd":"head -1 \"$VERDICT_FILE\" | grep -qi '^PASS$'","interpreter":"bash","timeout_seconds":5},"required":true}}
+{"contract":{"type":"subagent","subagent":{"context":"Run the critic on the drafted adapter markdown and return its actual report. Call the forward tool with uri squadrules://adapter/critic-loop and submit: work from $WORK_MANIFEST (kind file_set, the drafted file), the original requirement list, calling_protocol_slug author-adapter, verification_target 'structural compliance and agent behaviour', context.verdict_file $VERDICT_FILE, context.iteration and context.max_iterations (8). Follow critic-loop to its end, let it write $VERDICT_FILE, and report back its findings plus the verdict file's first two lines. Do not review the draft yourself and do not re-delegate the review.","mcp":[{"tool_name":"forward","arguments":{"uri":"squadrules://adapter/critic-loop"}}]},"required":true}}
 ```
 
-3. If FAIL: address every finding, then re-invoke critic-loop and re-run the FAIL
-   gate. **Loop automatically until the verdict is PASS** — do not proceed and do
-   not ask the user whether to continue.
-4. If PASS: capture the verdict file path for the `review_evidence` field
-   in the `train` call below.
-
-For `review`: skip this step (read-only operation).
-
-## 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.
-
-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`. 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.
+## Save After a PASS Verdict
+
+Read the verdict the critic left behind and act on it, then save.
+
+1. Run the gate below. `FAIL` → address **every** finding in the report, then
+   start a fresh critic pass the same way (a subagent delegating
+   `squadrules://adapter/critic-loop` with the corrected draft, the same
+   requirements, and `iteration` incremented) and re-run this gate. Loop
+   automatically; do not ask the user whether to continue.
+2. The loop is bounded by `max_iterations`. When `iteration` exceeds it, the
+   critic returns `failure_class: iteration_ceiling`: **stop looping**, report the
+   unresolved findings, and do not save an unreviewed draft as if it passed.
+3. On `PASS`, capture the verdict file path and save:
+   - `create` — call `train` with the drafted markdown and `review_evidence`
+     (verdict file path, exit code, stdout). Use `force_update: false` unless an
+     overwrite was explicitly requested.
+   - `update` — call `tune` with the existing adapter URI, corrected content, and
+     `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, and
+     make repository edits in the task's isolated worktree.
+   - `review` — do not call `train`; the operation is read-only and this gate is
+     satisfied by the findings report at `$REVIEW_FINDINGS_FILE`.
+4. Read the stored adapter back (`export` it, or the CLI on a local transport)
+   and compare it against what you intended to save; report the URI and any
+   difference. This is the run's completion criterion, not a gate: a remote
+   store cannot be observed from a shell command, so no contract asserts it.
 
 ```json
-{"contract":{"type":"comment","comment":{"min_length":80},"required":true}}
+{"contract":{"type":"shell","shell":{"cmd":"head -1 \"$VERDICT_FILE\" | grep -qi '^PASS$'","interpreter":"bash","timeout_seconds":5},"required":true}}
 ```
 
 ## Reward Signal
 
 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
+- `create` — a delegated critic returned `PASS`, the adapter is stored via `train`
+  with that `review_evidence`, its URI is reported, and the stored copy was read
+  back
+- `review` — findings report delivered from `$REVIEW_FINDINGS_FILE`
+- `update` — a delegated critic returned `PASS` on the changed parts, the corrected
+  adapter is saved via `tune` (or a required structural replacement), read back and
+  reported; repo-managed source updated in the task worktree
+
+What this proves: a separate context ran `critic-loop` over the draft and left a
+verdict file that reads `PASS`, and the store accepted that evidence. What it does
+not prove: that the report came from that context, or that the verdict is bound to
+the reviewed content — server-issued review receipts would be needed for that.
+Report the outcome as it stands; a passing gate is not a guarantee of correctness.
 
 A successful result means the resulting SQUADRULES adapter is more truthful,
 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.13.7"
+version: "5.14.0"
 title: Bulk Insert Adapters via SQUADRULES CLI
 ---
 
@@ -59,12 +59,11 @@ Verify before execution:
 2. Authentication is valid (`squadrules token` returns a token without error).
 3. Target directory path exists and contains at least one `.md` file.
 4. If a space is specified, confirm it exists via `squadrules spaces`.
+5. A subagent facility is available for the review hop below. Without it the
+   store will refuse the upload; report the blocker, do not skip the review.
 
-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'","interpreter":"bash","timeout_seconds":15},"required":true}}
-```
+If any check fails, stop and report the issue with remediation guidance. These
+checks are performed, not gated — the gate sits at the write.
 
 ## Resolve Scope and Validate
 
@@ -85,31 +84,54 @@ Validate each `.md` file against SQUADRULES adapter requirements:
 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.
 
+## Review the Set Before Uploading
+
+`train` refuses a markdown adapter without critic-loop `PASS` evidence, so an
+unreviewed batch uploads nothing. Allocate the handoff paths under
+`$SQUADRULES_LOCAL_ARTIFACT_DIR` — resolve a hint from the
+`squadrules_local_artifact_dir` field of the latest `activate`/`forward` response
+and export it; the server never names a path on your machine. You need
+`$WORK_MANIFEST`, `$VERDICT_FILE`, and `$BULK_LOG_FILE`. List the valid files in
+`$WORK_MANIFEST` as flat keys (`kind: file_set`, `root: <source directory>`, then
+`items:` with one file path per line) and delegate the review:
+
 ```json
-{"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}}
+{"contract":{"type":"subagent","subagent":{"context":"Run the critic over the adapter files listed in $WORK_MANIFEST and return its actual report. Call the forward tool with uri squadrules://adapter/critic-loop, submitting the file list as work kind file_set with the source directory as root, the requirement list above as requirements, and context.verdict_file $VERDICT_FILE with context.iteration and context.max_iterations (8). Do not review the files yourself.","mcp":[{"tool_name":"forward","arguments":{"uri":"squadrules://adapter/critic-loop"}}]},"required":true}}
 ```
 
-## Execute Bulk Train
+## Prove the Write Boundary
 
-Run the batch train operation using the SQUADRULES CLI:
+A directory batch overwrites adapters in a shared space: hard to roll back, so
+one gate sits in front of it and one behind it. Run the gate below **before** any
+`train` command. If it exits non-zero, nothing has been uploaded — fix the named
+condition (install the CLI, re-authenticate, correct `$SOURCE_DIR`, or obtain a
+`PASS` verdict), then run it again.
 
-```
-squadrules train <directory> --recursive --model <model> --space <space> [--force]
+```json
+{"contract":{"type":"shell","shell":{"cmd":"squadrules --version && squadrules token > /dev/null && test -d \"$SOURCE_DIR\" && find \"$SOURCE_DIR\" -name '*.md' | head -1 | grep -q . && head -1 \"$VERDICT_FILE\" | grep -qi '^PASS$'","interpreter":"bash","timeout_seconds":30},"required":true}}
 ```
 
-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`.
+## Run the Batch and Report
 
-Capture stdout and stderr. The CLI reports per-file status.
+Run the batch and keep its report. The CLI reads review evidence from the
+`SQUADRULES_REVIEW_EVIDENCE` environment variable as one JSON object
+(`verdict_file`, `exit_code`, `stdout`) and reuses it for every file in a
+directory batch. Therefore:
 
-```json
-{"contract":{"type":"shell","shell":{"cmd":"squadrules train \"$SOURCE_DIR\" --recursive --model \"$MODEL_ID\" --space \"$TARGET_SPACE\"","interpreter":"bash","timeout_seconds":120},"required":true}}
-```
+- If the critic reviewed the set as one submission, export that verdict once and
+  train the directory, capturing its report:
 
-## Report Results
+  ```
+  squadrules train <directory> --recursive --model <model> --space <space> [--force] 2>&1 | tee "$BULK_LOG_FILE"
+  ```
 
-Summarise the batch outcome:
+- If the critic reviewed files individually, train file-by-file and re-export
+  `SQUADRULES_REVIEW_EVIDENCE` for each file, so no adapter is stored under
+  another adapter's verdict; append every run to `$BULK_LOG_FILE`. Move
+  non-adapter files (README, reference docs) out of the directory before using
+  `--recursive` — the batch skips `README.md` by name and nothing else.
+
+Summarise the outcome for the user:
 
 | Metric | Value |
 |--------|-------|
@@ -118,20 +140,33 @@ Summarise the batch outcome:
 | Failed | N |
 | Skipped (invalid) | N |
 
-For each failure, report: file path, error message, suggested fix.
-If all succeeded, confirm adapter URIs are accessible via `squadrules spaces`.
+For each failure, report: file path, error message, suggested fix. If all
+succeeded, confirm the adapter URIs are accessible via `squadrules spaces`.
+A `REVIEW_EVIDENCE_REQUIRED` failure means the review did not cover that file:
+review it, then retry; never store an unreviewed adapter to clear the error.
+
+The batch prints one summary line (`<n> ok, <m> failed (of <total>)`) and one
+`ERR <path>: <error>` line per failure. The gate below reads that captured report
+instead of trusting a recollection of it, so the write is verified by what the
+CLI actually stored:
 
 ```json
-{"contract":{"type":"comment","comment":{"min_length":80},"required":true}}
+{"contract":{"type":"shell","shell":{"cmd":"test -s \"$BULK_LOG_FILE\" && grep -qE '[1-9][0-9]* ok, 0 failed' \"$BULK_LOG_FILE\" && ! grep -q 'ERR ' \"$BULK_LOG_FILE\"","interpreter":"bash","timeout_seconds":10},"required":true}}
 ```
 
 ## Reward Signal
 
 Workflow complete when:
+- A delegated critic returned `PASS` over the files being uploaded.
 - All valid adapter files in the target directory have been trained to the
-  specified space.
+  specified space, and the captured batch report shows `0 failed`.
 - Per-file results have been reported.
 - Any failures have been documented with remediation guidance.
 
+What this proves: the store accepted the uploads and the CLI reported no failures
+in the captured output. What it does not prove: that the review covered each file
+individually when one verdict served a directory batch, or that the verdict came
+from the delegated context rather than this one.
+
 A successful bulk insert means the user's local adapter library is now
 registered in SQUADRULES and available for activation by AI agents.

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

@@ -1,5 +1,5 @@
 ---
-version: "5.13.7"
+version: "5.14.0"
 slug: challenge-type-guide
 title: Challenge Type Selection Guide
 ---
@@ -135,7 +135,7 @@ Every solution follows the same envelope:
 
 **forward solution**
 ```json
-{"type":"forward","outcome":"success","evidence":{"target":"squadrules://adapter/critic-loop","success":true}}
+{"type":"forward","outcome":"success","evidence":{"target":"squadrules://adapter/implement-terraform","success":true}}
 ```
 
 **subagent solution**
@@ -168,6 +168,12 @@ Every solution follows the same envelope:
 data formats, or complex string processing, use `python3`. Use `node` only when
 the check requires the Node.js runtime.
 
+`cmd` is always program text: `python3` / `node` receive it as `-c` / `-e` source,
+so these rows describe short inline programs. Once a check needs more than one
+readable line, stop choosing an interpreter and ship the script as an artifact,
+invoked through a `bash` wrapper — see
+[Artifacts for Shell Contracts](#artifacts-for-shell-contracts).
+
 ## Security and Working Directory Rules
 
 Use `$SQUADRULES_LOCAL_ARTIFACT_DIR` as the base directory for local handoff
@@ -230,7 +236,8 @@ external worktrees, or open the worktree as a separate project window.
 **Write-then-grep** — subagent writes a verdict file, main agent checks line 1.
 
 **Phase-batch with critic** — batch related items, verify hard artifacts with
-shell, then call `critic-loop` for adversarial review.
+shell, then delegate `critic-loop` for adversarial review from a `subagent`
+contract. The review must not run on the thread that produced the work.
 
 **Chain-link via forward + slug** — layer N's contract requires `forward` with a
 specific adapter slug. Use when the adapter exceeds 350 lines or needs
@@ -241,16 +248,48 @@ Example ```json
 
 ## Artifacts for Shell Contracts
 
-When a shell contract needs a reusable script, **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.
-3. In the shell contract, reference it via `export` with
-   `squadrules://artifact/{uuid}` at execution time.
-
-This keeps adapter markdown clean and makes scripts independently versionable.
+A gate that needs more than one short command belongs in a **script shipped with
+the adapter**, not in the contract's `cmd`. An artifact keeps the contract
+readable, makes the script independently versionable, and lets one dispatcher
+serve many gates.
+
+**Author it in this order** — an artifact attaches to an adapter that already
+exists:
+
+1. Draft the markdown. The contract stays one line and invokes the script by its
+   artifact path. `interpreter` names the wrapper that runs that line, because
+   `cmd` is program text for every interpreter:
+   Example ```json
+   {"contract":{"type":"shell","shell":{"cmd":"python3 \"$SQUADRULES_LOCAL_ARTIFACT_DIR/artifacts/my-gates.py\" --gate preflight","interpreter":"bash","timeout_seconds":60},"required":true}}
+   ```
+2. `train` the markdown.
+3. `train` the script with the `mime` matching its extension (`text/x-python`,
+   `text/x-shellscript`, `text/javascript`), `artifact_name`, and that adapter's
+   `adapter_uri`. Add `relative_path` only when the default
+   `artifacts/<artifact_name>` is not the path you want; the identity header and
+   slug rules are in the `train` description.
+4. Verify before you run it — **two** checks:
+   - `activate` the adapter and check that `linked_artifacts[].relative_path`
+     equals the path the contract invokes.
+   - **Export check:** `export` the adapter (`format: skill_tree`, or
+     `skill_zip` for the bundle) and confirm the script is in the bundle at
+     that path, with no `artifact_stored_sha_mismatch` or
+     `artifact_relative_path_invalid` in `diagnostics[]`.
+
+   A mismatch surfaces only when the gate runs — by then it is the user's
+   failed step, not your typo.
+
+**At execution time:** run the `materialize` command carried by that
+`linked_artifacts[]` row — it writes the payload under
+`$SQUADRULES_LOCAL_ARTIFACT_DIR`, verifies the digest, and marks the file
+executable. `forward` responses do not repeat the list, so materialize during the
+run's first step. When the choice carries no artifact row, the agent obtains the
+script with **`export`** (`format: skill_tree` or `format: skill_zip`) and takes
+it from `artifacts/`. State which route applies in the adapter text — a step that
+does not say how to get the file leaves the agent guessing.
+
+**One script, many gates:** `--gate <name>` on a single dispatcher replaces one
+inlined program per step. Change the gate once, not seven times.
 
 Example ```json
 {"contract":{"type":"comment","comment":{"min_length":30},"required":true}}
@@ -268,3 +307,4 @@ The agent can now:
 5. use forward contracts for chain links
 6. use subagent contracts for delegated work
 7. apply stronger verification patterns instead of weak comment checks
+8. ship a multi-step gate as an adapter artifact and keep its contract one line