@squadrules/mcp 5.9.0 → 5.9.2

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

@@ -1,5 +1,5 @@
 ---
-version: "5.9.0"
+version: "5.9.2"
 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.0"
+version: "5.9.2"
 title: Author Adapter (Create / Review / Refactor)
 ---
 

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

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

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

@@ -1,5 +1,5 @@
 ---
-version: "5.9.0"
+version: "5.9.2"
 slug: challenge-type-guide
 title: Challenge Type Selection Guide
 ---

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

@@ -1,5 +1,5 @@
 ---
-version: "5.9.0"
+version: "5.9.2"
 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.0"
+version: "5.9.2"
 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.0"
+version: "5.9.2"
 slug: critic-loop
 title: Critic Loop
 ---

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

@@ -1,5 +1,5 @@
 ---
-version: "5.9.0"
+version: "5.9.2"
 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.0"
+version: "5.9.2"
 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.0"
+version: "5.9.2"
 slug: protocol-linking-guide
 title: Protocol Linking Guide
 ---

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

@@ -1,5 +1,5 @@
 ---
-version: "5.9.0"
+version: "5.9.2"
 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.0"
+version: "5.9.2"
 slug: skill-format-guide
 title: Skill Format and Local Authoring Guide
 ---

package/dist/resources/embedded-mcp-resources.js

@@ -23,18 +23,18 @@ export const mcpResources = {
     },
     "mem": {},
     "meta": {
-        "adapter-migration": "---\nversion: \"5.9.0\"\nslug: adapter-migration\ntitle: Adapter Migration Protocol\n---\n\n# Adapter Migration Protocol\n\nBatch-migrate all adapters in a space to the current structural scheme. Exports\nevery adapter, applies conservative structural transformations, reports changes\nper adapter, and re-trains the conforming subset autonomously.\n\nThis protocol handles structural migrations only — it preserves semantic content\n(steps, intent, examples) while updating format, headings, and contract shapes\nto match the latest SQUADRULES requirements.\n\n## Activation Patterns\n\n**Run this protocol when the user says ANY of:**\n\n- \"migrate all adapters\" / \"batch update adapters\"\n- \"update adapters to latest scheme\" / \"update adapter structure\"\n- \"run structural migration\" / \"migrate protocols\"\n- \"update all my adapters\" / \"fix adapter structure\"\n- \"apply latest adapter format\" / \"restructure adapters\"\n- \"run adapter migration\" / \"migrate to new format\"\n\n**Trigger pattern:** **migrate** / **batch update** / **structural migration** /\n**update format** + (adapters | protocols | all | space).\n\n**Must Never:**\n- Alter semantic content (step text, trigger phrases, examples, intent).\n- Auto-train an adapter without first producing a per-adapter change report.\n- Guess transformations when the adapter structure is ambiguous.\n- Delete adapters or layers during migration.\n- Migrate adapters that already conform (report them as \"no changes needed\").\n\n**Must Always:**\n- Export every adapter before making any changes.\n- Apply only conservative, reversible structural transformations.\n- Flag ambiguous cases for manual review instead of guessing.\n- Produce a per-adapter change report before executing any writes.\n- Preserve the adapter's slug, version, and chain_root fields.\n\n**Good trigger examples:**\n- \"migrate all my personal adapters to the latest format\" → run this protocol\n- \"update all adapters in the team space\" → run this protocol\n- \"we changed the solution scheme, update all adapters\" → run this protocol\n\n**Bad trigger examples:**\n- \"update this one adapter\" → use `author-adapter` with `fix` operation\n- \"create a new adapter\" → use `author-adapter`\n- \"export my adapters\" → use `export` directly\n\n## Preflight Dependencies\n\nBefore running migration, verify readiness:\n\n1. `export` tool is available and callable.\n2. `tune` and `train` tools are available for writes.\n3. Target space is identified (personal or a named group space).\n4. The migration is structural-only (no semantic changes).\n\nIf any tool is unavailable, stop and report the connection blocker with\nremediation guidance.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Export All Adapters\n\nExport every adapter from the target space using bulk export:\n\n1. Call `export` with `all_adapters: true`, `space_name` set to the target\n   space, and `format: skill_tree`.\n2. Record the total adapter count from the response.\n3. For each adapter in the response, extract its slug, URI, and content.\n\nIf the space has no adapters, report this and stop.\n\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"export\",\"arguments\":{\"all_adapters\":true,\"space_name\":\"<space>\",\"format\":\"skill_tree\"}},\"required\":true}}\n```\n\n## Analyze and Transform\n\nFor each exported adapter, perform structural analysis and apply migrations.\n\n### Structural checks (apply all that are needed)\n\n1. **Heading order** — first H2 must be `Activation Patterns`, last H2 must be\n   `Reward Signal`. If missing or out of order, flag for restructuring.\n2. **Contract fences** — all contract JSON blocks must use ` ```json ` (not\n   plain ` ``` `). If plain fences contain contract JSON, convert them.\n3. **Field rename** — any `\"challenge\":` key inside contract JSON blocks must\n   become `\"contract\":`. Apply globally within JSON fences.\n4. **Frontmatter** — must include `slug`. Add `version` if missing. Preserve\n   existing `chain_root` when present.\n5. **Line count** — adapters exceeding 350 lines must be flagged for splitting\n   (do NOT auto-split; report as manual review needed).\n6. **Critic-loop integration** — check whether the adapter includes at least\n   one `critic-loop` chain link. If not, add a recommendation (do NOT\n   auto-add; report as suggestion).\n\n### Transformation rules\n\n- **Conservative only:** If a transformation might change meaning, skip it and\n  flag for manual review.\n- **Reversible:** Every change must be expressible as a diff so it is auditable\n  and reversible.\n- **Idempotent:** Running migration twice on the same adapter produces no\n  additional changes.\n\nFor each adapter, produce:\n- `status`: `needs_changes` | `up_to_date` | `needs_manual_review`\n- `changes`: list of specific transformations applied\n- `warnings`: list of items flagged for manual review\n- `transformed_content`: the full updated markdown (when `needs_changes`)\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":120},\"required\":true}}\n```\n\n## Report Changes\n\nRecord a summary table:\n\n| Adapter slug | Status | Changes | Warnings |\n|-------------|--------|---------|----------|\n| example-adapter | needs_changes | 3 structural fixes | 0 |\n| another-adapter | up_to_date | 0 | 0 |\n| complex-adapter | needs_manual_review | 1 fix | line count exceeds 350 |\n\nFor each adapter with `needs_changes`, show the specific transformations:\n- What was changed (before/after for the affected lines).\n- Why (which structural rule it satisfies).\n\nFor each adapter with `needs_manual_review`, explain what needs human\nattention and why the protocol cannot auto-fix it.\n\nApply the migration autonomously:\n- **Apply all** `needs_changes` adapters.\n- **Leave untouched** every `needs_manual_review` adapter and report it with the\n  reason it cannot be auto-fixed.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":120},\"required\":true}}\n```\n\n## Execute Migration\n\nFor each `needs_changes` adapter, apply the structural changes:\n\n1. For adapters needing only content-level fixes (heading reorder, fence\n   conversion, field rename): use `tune` with the transformed content and\n   the adapter's URI.\n2. For adapters needing structural changes that alter layer count or identity:\n   use `train` with `force_update: true` and the transformed content.\n3. Record the outcome (success or failure) for each adapter.\n\nDo NOT change the adapter's space assignment during migration.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":120},\"required\":true}}\n```\n\n## Verify and Report\n\nAfter executing all migrations:\n\n1. Re-export each migrated adapter to verify structural compliance.\n2. Report final status:\n\n| Metric | Count |\n|--------|-------|\n| Adapters scanned | N |\n| Already up to date | N |\n| Successfully migrated | N |\n| Migration failed | N |\n| Flagged for manual review | N |\n\n3. For each failure, report the error message and suggested fix.\n4. Recommend running `critic-loop` on migrated adapters to verify semantic\n   integrity after structural changes.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Reward Signal\n\nOnly reachable after all prior steps are solved.\n\nThe adapter library in the target space now conforms to the current structural\nscheme. Every adapter has:\n- Correct heading order (Activation Patterns first, Reward Signal last).\n- Proper ` ```json ` contract fences.\n- Current field names (`contract`, not `challenge`).\n- Valid frontmatter with `slug` and optional `version`.\n- Been verified post-migration for structural compliance.\n\nSemantic content (steps, intent, examples, triggers) is preserved unchanged.\n",
-        "author-adapter": "---\nslug: author-adapter\nversion: \"5.9.0\"\ntitle: Author Adapter (Create / Review / Refactor)\n---\n\n\n\n# Author Adapter (Create / Review / Refactor)\n\n> **Note to the agent:** SQUADRULES protocols are interfaces for AI agents — you\n> are the primary user. When you author a protocol, you design behaviour for\n> yourself and others. Write for them: single source of truth (never duplicate\n> rules), explicit over implicit (agents fill ambiguity with hallucination),\n> phases teach modes (each step teaches its cognitive mode), truth over fluency\n> (a protocol that reads well but causes wrong behaviour is worse than one that\n> reads rough but executes correctly).\n\n## Activation Patterns\n\nPreferred entry URI: `squadrules://adapter/author-adapter`. The retired\n`create-new-protocol` slug is a redirect tombstone (see phase-critic pattern).\nIf `forward.authoring` is present, use its operation and target throughout this\nrun. Do not reinterpret update as create or change the target mid-run. This\ncontext describes the requested work; it does not override host permissions.\n\nSQUADRULES authoring lifecycle — create, review, or update adapters / protocols / workflows.\nIn this context, those words refer to the same stored artifact and can be treated\nas synonyms. Supports three operations:\n- **create** — draft and train a new adapter / protocol from scratch.\n- **review** — audit an existing adapter, family, or bundle for structural issues,\n  missing cross-references, chaining gaps, DRY violations, stale guidance, or\n  agent-hostile ambiguity. Read-only.\n- **update** — apply specific corrections to an existing adapter / protocol and\n  save the correction. Also triggered by: edit, fix, modify, change, improve, patch, refactor.\n**Run this protocol when the user says ANY of:**\n- \"create a new SQUADRULES protocol\" / \"create new protocol adapter\"\n- \"register personal SQUADRULES adapter\" / \"register a personal adapter\"\n- \"train adapter into personal\" / \"train protocol into personal\"\n- \"train a workflow\" / \"register a new adapter\" / \"create a new workflow\"\n- \"review protocol\" / \"audit adapters\" / \"check protocol families for gaps\"\n- \"update adapter\" / \"edit adapter\" / \"fix protocol\" / \"modify adapter\"\n- \"patch protocol\" / \"refactor protocol\" / \"change adapter\" / \"improve adapter\"\n- \"create new protocol\" (when `activate` found no match and user confirms)\n**Trigger pattern:** **create** / **train** / **register** / **review** /\n**audit** / **fix** / **update** / **edit** / **modify** / **change** /\n**improve** / **patch** / **refactor** / **correct** +\n(protocol / adapter / workflow).\n**Must Never:**\n- Run when the user only asked to execute an existing protocol.\n- Mutate adapters during a `review` operation.\n- Optimise only for pretty wording; this protocol designs agent behaviour.\n- Treat \"update\", \"edit\", or \"modify an existing adapter\" as **create**.\n**Must Always:**\n- Infer `{operation}` from trigger: create / review / update.\n  When the user says \"update\", \"edit\", \"modify\", or \"fix\" → operation is **update**.\n- Optimise for truth, low ambiguity, explicit sequencing, and user-need alignment.\n- Design or review phase transitions explicitly: discovery, clarification,\n  ideation, planning, execution, validation, review, handoff.\n- Include Activation Patterns as the first H2 and Reward Signal as the last H2\n  in any newly drafted adapter.\n- Enforce the 350-line limit per file.\n**Good trigger examples:**\n- \"Create a new SQUADRULES protocol for code review\" → run this protocol (create)\n- \"No match found; I want to create a new protocol\" → run this protocol (create)\n- \"Review all v4 protocol families for missing cross-references\" → run this protocol (review)\n- \"Update the MR adapter to include a review step\" → run this protocol (update)\n- \"Edit the critic-loop adapter triggers\" → run this protocol (update)\n- \"Refactor the MR adapter to be less ambiguous\" → run this protocol (update)\n**Bad trigger examples:**\n- \"Run the standardise project protocol\" → use activate / forward\n- \"Search for deployment protocol\" → use activate\n- \"Create an MR\" → use the MR adapter, not this protocol\n\n## Preflight Dependencies\n\nBefore running authoring actions, verify dependency and auth readiness for this\nrun:\n1. Required MCP tools are available and reachable: `activate`, `forward`,\n   `reward`, and the operation-dependent tool (`train`, `export`, or `tune`).\n2. Required CLI tools for planned shell steps are installed and callable.\n3. Required auth/session state is valid for the target MCP server.\n\nIf any check fails, attempt AI-assisted remediation automatically (install or\nconfigure the missing tool, refresh auth/session), then re-run preflight. Only\nhard-stop when a required tool or auth genuinely cannot be established\nautonomously; report the concrete blocker and the remediation already attempted.\nDo not continue to intent resolution until preflight passes.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Resolve Intent Autonomously\n\nUse structured `authoring` when provided. For original calls without it, infer\n`{operation}` from the user's trigger — do not stop to ask for confirmation:\n\n| Signal | Operation |\n|---|---|\n| \"create\", \"new\", \"train\", no match from activate | **create** |\n| \"review\", \"audit\", \"check\", \"gaps\", \"cross-references\" | **review** |\n| \"update\", \"edit\", \"fix\", \"modify\", \"change\", \"improve\", \"patch\", \"refactor\", \"add missing\", \"correct\" | **update** |\n\nResolve the target from context without a confirmation prompt: for `create`,\nproceed to author a new adapter; for `review`, select the adapter(s), family, or\nbundle named or implied by the request; for `update`, select the adapter and the\nspecific issue. Record the inferred operation and target, then continue. Escalate\nto the user only when the request is genuinely ambiguous and no reasonable default\nexists.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Gather Requirements\n\n### For `create` — collect details for a new protocol\n**1. Determine the pattern:**\n\n| Signal | Pattern |\n|---|---|\n| One workflow, no variants | **Standalone** — one protocol, all steps inline |\n| Multiple issue types / output formats / media | **Router + Extensions** — router classifies, routes via `activate` |\n| Domain has a decision tree | **Router + Extensions** |\n| Single workflow but exceeds 350 lines or too complex for weaker models | **Chain** — split into sequential adapters linked via `forward` + slug |\n| Reference material needed by steps | Extract to a separate file, not a protocol |\n**2. Collect per protocol:**\n- **Title** — clear, descriptive H1.\n- **User problem** — what real problem does this solve?\n- **Agent behaviour** — what behaviour should this create in the agent?\n- **Mode map** — which steps are for discovery, clarification, ideation,\n  planning, execution, validation, review, or handoff?\n- **Steps** — each H2 must earn its place and end with a challenge.\n- **Challenge type per step** — use the strongest observable contract possible.\n- **Domain reference** — guides / docs the protocol should load.\n- **Existing protocols** — reuse, compose, or extract shared content.\n- **DRY / size check** — extract duplicated content; split if >350 lines.\n- **Chain position** — entry, middle, or exit? What slug does the previous link forward to?\n- **Failure analysis** — where would a weaker agent misread this protocol?\n**3. If Router pattern:** variants, classification questions, forbidden types,\nand which parts stay in the router vs extensions.\n**4. If Chain pattern:** Load `protocol-linking-guide` for full rules\n(`forward` with `squadrules://adapter/protocol-linking-guide`). Collect: chain\nlinks and concerns, minimum number of links, entry point (matched by\n`activate`), and artifacts flowing between links.\n\n### For `review` — audit existing adapters against this checklist\n\nExport target adapter(s). For each adapter, check:\n1. **User-need fit** — does the adapter solve a real user problem, or merely\n   mirror literal wording?\n2. **Mode / phase clarity** — are discovery, clarification, ideation,\n   execution, validation, and review clearly separated?\n3. **Cross-reference completeness** — are all required related adapters linked?\n4. **Adapter handoff gaps** — does it hand off where another adapter should own\n   the work?\n5. **DRY violations** — is policy content duplicated instead of linked?\n6. **Contract coverage** — does every executable H2 have the right contract?\n7. **Truth-first behaviour** — does it reduce guessing, fake certainty, and\n   silent assumption-making?\n8. **Activation pattern accuracy** — do triggers match what users actually say?\n9. **Structure compliance** — first H2 Activation Patterns, last H2 Reward\n   Signal, no duplicate H2s, under 350 lines.\n10. **Sibling consistency** — are equivalent steps present across sibling\n    adapters in the same family?\n11. **Chained adapter families** (when applicable) — extension adapters include\n    `chain_root` and a prerequisite clause pointing at the root; parent adapters\n    use explicit `forward` when the next adapter slug is already known; reserve\n    `activate` for ambiguous runtime discovery (see `protocol-linking-guide`,\n    **Chaining Back and Forward**).\n12. **Critic-loop integration** — does the adapter include critic-loop chain\n    links at major phase boundaries? Does each critic-loop invocation have a\n    FAIL gate shell contract (`grep -qi '^PASS$'` on the verdict file)? Are\n    solution checks restricted to irreversible remote mutations (see\n    `critic-loop-guide`)?\n\n### For `update` — identify the specific issue\n\nExport the target adapter, read the current markdown, identify the exact gap or\nerror, and plan the minimal change. Do not alter unrelated layers.\n\nSummarise gathered requirements or findings.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Draft Markdown\n\n### For `create` — draft new adapter markdown\n\nDraft the full markdown for `train`.\n\n### For `review` — draft findings report\n\nWrite a structured gap report to `$REVIEW_FINDINGS_FILE` (an absolute path\nprovided by the invoking agent or chosen by you under\n`$SQUADRULES_LOCAL_ARTIFACT_DIR` with a session-unique segment). For each finding\ninclude:\n- adapter title\n- gap type\n- severity\n- why the issue matters for AI-agent behaviour\n- specific recommended fix\n\n### For `update` — draft corrected adapter markdown\n\nApply the identified change and show a diff-style summary of what changed.\n\n### Shared drafting rules (all operations)\n**Core SQUADRULES rule — right mode at the right time:**\n\nEvery protocol must help the agent recognise whether the current step is for\nexploration, clarification, ideation, planning, execution, validation, review,\nor handoff. Do not blur those modes.\n**Truth over fluency:**\n\nDesign protocols to reduce guessing and fake certainty. Prefer explicit prompts,\nexplicit stop conditions, explicit uncertainty escalation, and observable\nverification over narrative reassurance.\n**User need over literal phrasing:**\n\nThe protocol should help the agent provide what the user actually needs, not\njust echo the wording used in the request.\n**DRY:**\n\nShared content across protocols must live in one place. If two protocols share\n>50% of their body, extract shared logic.\n\n**350-line maximum per file:**\n\nNo protocol file may exceed 350 lines. If it grows beyond that, split it into\nlinked adapters or extract a reference file.\n\n**Generic-first — create generic, link from detailed:**\n\nCreate protocols from generic to detailed. The generic adapter must stand alone.\nExtensions should contain only the delta.\n\n**Slug convention — deterministic protocol linking:**\n\nEvery protocol gets a short, unique, lowercase-hyphenated `slug`.\n\n**Artifacts:**\n\nStore scripts or config blobs as artifacts via `train` (set `mime`,\n`artifact_name`, `adapter_uri`). Retrieve with `export` using\n`squadrules://artifact/{uuid}`.\n\n**Protocol structure:** H1 title, first H2 Activation Patterns, second H2\nPreflight Dependencies, middle H2s one per step with JSON contract block, last\nH2 Reward Signal. Frontmatter: `slug` (required), `version` (optional),\n`chain_root` (required for mid-chain adapters).\n\n**Challenge types:** Load `challenge-type-guide` for decision rules and JSON\nformats (`forward` with `squadrules://adapter/challenge-type-guide`).\n\n**Critic-loop and mutation gates:** Load `critic-loop-guide` for placement,\nFAIL gate, and solution check rules (`forward` with `squadrules://adapter/critic-loop-guide`).\n\n**If Router pattern:** draft the router and each extension as separate files.\n\nPost the full drafted markdown.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":120},\"required\":true}}\n```\n\n## Critic-Loop Review (create and update only)\n\nFor `create` and `update`: run critic-loop against the drafted markdown. This is an\nautonomous quality loop — the agent owns content, the critic owns quality, and no\nhuman approval is requested at any point.\n\n1. Invoke critic-loop via `forward` with `squadrules://adapter/critic-loop`.\n   Submit the drafted markdown as a `file_set` work submission — write\n   `kind: file_set`, `root: <directory of the draft>`, then the drafted file\n   under `items:` into the handoff pointed to by `$WORK_MANIFEST` — with the\n   slug as `calling_protocol_slug` and \"structural compliance and agent\n   behaviour\" as `verification_target`.\n2. Run the FAIL gate shell contract on the verdict file:\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"head -1 \\\"$VERDICT_FILE\\\" | grep -qi '^PASS$'\",\"timeout_seconds\":5},\"required\":true}}\n```\n\n3. If FAIL: address every finding, then re-invoke critic-loop and re-run the FAIL\n   gate. **Loop automatically until the verdict is PASS** — do not proceed and do\n   not ask the user whether to continue.\n4. If PASS: capture the verdict file path for the `review_evidence` field\n   in the `train` call below.\n\nFor `review`: skip this step (read-only operation).\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Autonomous Review Gate\n\nNo human approval step. The critic-loop PASS verdict from the previous step is the\nsole quality gate; once it is PASS, proceed directly to finalise.\n\nFor `create`: record the drafted adapter slug(s) and the critic-loop verdict, then\ncontinue to `train`.\n\nFor `review`: record the findings and the actions taken, then continue.\n\nFor `update`: record the corrected markdown, the change summary, and the critic\nverdict, then continue.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## FinaliseOperation\n\nFor `create`: call `train` with the drafted markdown and `review_evidence`\nfrom the critic-loop step. Use `force_update: false` unless overwrite was\nexplicitly requested.\n\nFor `review`: do not call `train`. Save the findings report only if requested.\n\nFor `update`: use `tune` with the existing adapter URI, corrected content, and\n`review_evidence` for edits that preserve adapter identity and layer count.\nUse `train` with `force_update: true` only for a required structural replacement\n(such as changing identity/H1 mapping or layer count), preserving the intended\nspace and verifying the resulting identity. Never create a duplicate as fallback.\nUpdate the corresponding repository source when the adapter is repo-managed;\nmake repository edits in the task's isolated worktree.\n\nReport the outcome: adapter URI(s) for create / update, or findings summary for\nreview.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Reward Signal\n\nProtocol complete when:\n- `create` — adapter(s) stored via `train` (with review_evidence) and URI(s) reported\n- `review` — findings report delivered\n- `update` — corrected adapter saved via `tune` (or required structural replacement),\n  read back and verified; repo-managed source updated in the task worktree\n\nA successful result means the resulting SQUADRULES adapter is more truthful,\nphase-aware, agent-readable, and aligned with human–AI harmony.\n",
-        "bulk-insert-adapters-via-cli": "---\nslug: bulk-insert-adapters-via-cli\nversion: \"5.9.0\"\ntitle: Bulk Insert Adapters via SQUADRULES CLI\n---\n\n# Bulk Insert Adapters via SQUADRULES CLI\n\n## Activation Patterns\n\nBatch-register multiple SQUADRULES adapters from a local directory tree using the\n`squadrules train` CLI. Handles directory scanning, validation, space targeting,\nand error recovery for bulk operations.\n\n**Run this protocol when the user says ANY of:**\n\n- \"bulk insert adapters\" / \"bulk train adapters\"\n- \"train all protocols in a directory\"\n- \"batch register adapters from folder\"\n- \"upload all .md files to SQUADRULES\"\n- \"sync local protocols to SQUADRULES\" / \"push protocols to SQUADRULES\"\n- \"train directory recursively\" / \"train --recursive\"\n\n**Trigger pattern:** **bulk** / **batch** / **all** / **directory** / **recursive** +\n(train | insert | register | upload | push | sync) + (adapters | protocols).\n\n**Must Never:**\n\n- Train files without first validating their structure.\n- Overwrite existing adapters without explicit user confirmation (`--force`).\n- Train files that contain secrets or token-like strings without `--allow-sensitive-upload`.\n- Skip reporting partial failures in a batch.\n\n**Must Always:**\n\n- Verify the target directory exists and contains `.md` files.\n- Show the user the file list and target space before executing.\n- Report per-file success/failure after the batch completes.\n- Respect the user's choice of space (personal or group).\n\n**Good trigger examples:**\n\n- \"Train all adapters in squadrules-v4/_personal/\" → run this protocol\n- \"Bulk insert the protocols from my export folder\" → run this protocol\n- \"Push all .md files in this directory to my personal space\" → run this protocol\n\n**Bad trigger examples:**\n\n- \"Train this one protocol\" → use `squadrules train <file>` directly\n- \"Create a new protocol\" → use `author-adapter`\n- \"Export my adapters\" → use `squadrules export`\n\n## Preflight Dependencies\n\nVerify before execution:\n\n1. `squadrules` CLI is installed and callable (`squadrules --version`).\n2. Authentication is valid (`squadrules token` returns a token without error).\n3. Target directory path exists and contains at least one `.md` file.\n4. If a space is specified, confirm it exists via `squadrules spaces`.\n\nIf any check fails, stop and report the issue with remediation guidance.\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"squadrules --version && squadrules token > /dev/null 2>&1 && echo 'auth: ok'\",\"timeout_seconds\":15},\"required\":true}}\n```\n\n## Resolve Scope Autonomously\n\nResolve and record the batch operation details:\n\n1. **Source directory** — absolute path.\n2. **File count** — number of `.md` files found (recursive or flat).\n3. **Target space** — personal (default) or a named group space.\n4. **Force mode** — whether `--force` will be used (overwrites existing).\n5. **Model attribution** — which `--model` value to use.\n\nList the files that will be trained, record the resolved scope, and proceed\nautonomously — no confirmation prompt.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Validate Structure\n\nBefore training, validate each `.md` file against SQUADRULES adapter requirements:\n\n- Has an H1 title.\n- First H2 is \"Activation Patterns\".\n- Last H2 is \"Reward Signal\".\n- Contains at least one fenced `json` block with a top-level `contract` object.\n- Does not exceed 350 lines.\n\nReport any files that fail validation, then proceed autonomously: skip the invalid\nfiles, train the valid subset, and document every skipped file with its validation\nerror and a suggested fix. Do not stop to ask the user.\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"echo 'Validation complete — see output above for results'\",\"timeout_seconds\":30},\"required\":true}}\n```\n\n## Execute Bulk Train\n\nRun the batch train operation using the SQUADRULES CLI:\n\n```\nsquadrules train <directory> --recursive --model <model> --space <space> [--force]\n```\n\nIf the directory contains files that should NOT be trained (README, reference\ndocs), either:\n- train file-by-file for the valid subset, or\n- move non-adapter files out before running `--recursive`\n\nCapture stdout and stderr. The CLI reports per-file status.\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"squadrules train <directory> --recursive --model <model_id> --space <space>\",\"timeout_seconds\":120},\"required\":true}}\n```\n\n## Report Results\n\nSummarise the batch outcome:\n\n| Metric | Value |\n|--------|-------|\n| Files attempted | N |\n| Successfully trained | N |\n| Failed | N |\n| Skipped (invalid) | N |\n\nFor each failure, report:\n- File path\n- Error message\n- Suggested fix\n\nIf all succeeded, confirm adapter URIs are accessible via `squadrules spaces`.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Reward Signal\n\nProtocol complete when:\n- All valid adapter files in the target directory have been trained to the\n  specified space.\n- Per-file results have been reported to the user.\n- Any failures have been documented with remediation guidance.\n\nA successful bulk insert means the user's local protocol library is now\nregistered in SQUADRULES and available for activation by AI agents.\n",
-        "challenge-type-guide": "---\nversion: \"5.9.0\"\nslug: challenge-type-guide\ntitle: Challenge Type Selection Guide\n---\n\n\n\n# Challenge Type Selection Guide\n\nDecision rules, JSON formats, interpreter selection, and anti-patterns for\nchoosing SQUADRULES challenge types. Loaded by protocol-authoring agents during\ndrafting and review.\n\n## Activation Patterns\n\n**Typically invoked by:** `author-adapter` and\n`critic-loop`.\n\n**Can be invoked directly when agent needs:**\n- \"challenge type reference\" / \"which challenge type to use\"\n- \"how to write shell challenges\" / \"challenge format\"\n- \"interpreter selection for challenges\"\n\n**Trigger pattern:** **challenge** + (type | format | selection | guide).\n\n**Must Never:**\n- Be used as an execution protocol.\n- Select `comment` merely because it is easy.\n\n**Must Always:**\n- Be consulted before assigning challenge types to protocol steps.\n- Choose the strongest observable contract available.\n- Match challenge choice to the mode of the step: ask, decide, act, verify, or review.\n\n**Good trigger examples:**\n- drafting a new protocol and need challenge types → load this\n- reviewing challenge type selection in a draft → load this\n\n**Bad trigger examples:**\n- \"Create a new protocol\" → use `author-adapter`\n- \"Review my protocol draft\" → use `critic-loop`\n\n## Core Rules\n\n`comment` is the challenge type of **last resort**. If a step produces any\nobservable artifact — a file, a git state change, an API response, or an exit\ncode — use `shell` or `mcp` instead.\n\n**Mode before challenge type:**\n- **clarify / approve** → `user_input`\n- **call a SQUADRULES / MCP tool** → `mcp`\n- **execute or verify local state** → `shell`\n- **pure reasoning with no observable artifact** → `comment`\n\n### Decision Tree\n\n```\nDoes the step call an MCP tool?\n ├─ YES → Is the step a chain link to another adapter?\n │         ├─ YES → \"mcp\" with tool_name + arguments (forward + slug URI)\n │         └─ NO  → \"mcp\" with tool_name only\n └─ NO → Does the step produce or verify a file, command result, or system state?\n          ├─ YES → \"shell\"\n          └─ NO → Does the step require human approval or choice?\n                   ├─ YES → \"user_input\"\n                   └─ NO → \"comment\" only if there is no stronger observable contract\n```\n\n### Challenge JSON Formats\n\n**shell**\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"<command>\",\"timeout_seconds\":30},\"required\":true}}\n```\n\n**mcp**\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"<tool>\"},\"required\":true}}\n```\n\n**mcp with arguments (chain link)**\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"forward\",\"arguments\":{\"uri\":\"squadrules://adapter/<slug>\"}},\"required\":true}}\n```\n\nUse the `arguments` form when the step's purpose is to invoke a specific\nadapter via `forward`. The server validates that `solution.mcp.arguments`\nis a superset of the contract's `mcp.arguments` (subset/deep matching),\nproving the agent called the correct target — not just any `forward` call.\n\n**user_input**\n```json\n{\"contract\":{\"type\":\"user_input\",\"user_input\":{\"prompt\":\"<specific question>\"},\"required\":true}}\n```\n\n**comment**\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":50},\"required\":true}}\n```\n\n### Solution JSON Formats\n\nEvery solution, regardless of type, follows the same envelope:\n\n```json\n{\n  \"type\": \"<challenge_type>\",\n  \"outcome\": \"success | failure | skipped\",\n  \"evidence\": { /* type-specific proof data */ },\n  \"nonce\": \"<echo from contract>\",\n  \"proof_hash\": \"<echo from contract>\"\n}\n```\n\n**shell solution**\n```json\n{\n  \"type\": \"shell\",\n  \"outcome\": \"success\",\n  \"evidence\": {\n    \"exit_code\": 0,\n    \"stdout\": \"...\",\n    \"stderr\": \"\",\n    \"duration_seconds\": 1.2\n  }\n}\n```\n\n**mcp solution**\n```json\n{\n  \"type\": \"mcp\",\n  \"outcome\": \"success\",\n  \"evidence\": {\n    \"tool_name\": \"activate\",\n    \"arguments\": { \"query\": \"example search\" },\n    \"response\": { \"choices\": [...] }\n  }\n}\n```\n\n**user_input solution**\n```json\n{\n  \"type\": \"user_input\",\n  \"outcome\": \"success\",\n  \"evidence\": {\n    \"confirmation\": \"agreed. proceed\",\n    \"timestamp\": \"2026-05-18T14:49:00Z\"\n  }\n}\n```\n\n**comment solution**\n```json\n{\n  \"type\": \"comment\",\n  \"outcome\": \"success\",\n  \"evidence\": {\n    \"text\": \"Verified all 78 issues now have repo: labels.\"\n  }\n}\n```\n\n### Compatibility\n\nThe server also accepts older solution shapes where data is placed directly\nunder the type key (e.g. `{ \"type\": \"shell\", \"shell\": { \"exit_code\": 0 } }`)\ninstead of inside an `evidence` envelope. Always use the unified envelope with\n`outcome` and `evidence` for new protocols.\n\n## Interpreter Selection\n\n| Task | Use bash | Use perl | Use python3 |\n|---|---|---|---|\n| File exists, tool installed, git state | yes | no | no |\n| Simple content grep | yes | no | no |\n| Multi-line regex | no | yes | no |\n| Paragraph processing | no | yes | no |\n| JSON validation | maybe | yes | yes |\n| YAML / complex data structure checks | no | no | yes |\n\n**Rule of thumb:** if bash requires `while read`, `grep | awk`, or heavy quote\nescaping, rewrite in Perl. If you need imports for data formats, use Python.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Security and Working Directory Rules\n\nUse `$SQUADRULES_LOCAL_ARTIFACT_DIR` as the base directory for local handoff\nartifacts. File paths within it are provided as variables by the invoking agent\nto avoid collisions between parallel sessions.\n\n**Rules:**\n- all file paths in shell challenges reference variables (e.g., `$DRAFT_FILE`,\n  `$VERDICT_FILE`) set by the parent agent — never hardcode filenames\n- the parent agent constructs collision-free paths under\n  `$SQUADRULES_LOCAL_ARTIFACT_DIR` (e.g., with a session ID or random suffix)\n- when using SQUADRULES MCP, the latest `activate` / `forward` / `next` response field `squadrules_local_artifact_dir` is an ordered array of URI hints (`project://<rel>`, `user://<rel>`); pick one (`project://` when you have exactly one project context, otherwise `user://`), resolve on your machine, and `export SQUADRULES_LOCAL_ARTIFACT_DIR=\"<absolute>\"` if your shell does not already define it\n- if the server-returned path is not usable on your local filesystem, resolve\n  locally to `$PROJECT_DIR/.local/squadrules/work` and keep it stable for the run\n- prerequisites create the directory\n- Reward Signal cleans it up\n- never write credentials or secrets to files\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Composition Patterns\n\n**Multi-check compound command**\n- chain with `&&`\n- let the first failure stop execution\n\n**Agent-readable shell status**\n- use when failure can produce no output, especially `test`, quiet `grep`,\n  JSON probes, pipelines, or commands that redirect stderr\n- empty stdout or stderr is not success; success is the real process status\n  reported as `solution.shell.exit_code`\n- print the final status marker to stderr when stdout is machine-readable\n- preserve the original status exactly:\n  ```bash\n  ( set -o pipefail; <command> ); rc=$?; printf '\\nSQUADRULES_SHELL_EXIT=%s\\n' \"$rc\" >&2; exit \"$rc\"\n  ```\n- keep `&&` inside `<command>` for ordered checks; use the final\n  `; rc=$?; ...` trailer only to capture, print, and return the process status\n- do not use `<command> || echo ERROR && false`; shell operators group\n  left-to-right, so that form can fail after a successful command and it loses\n  the original status\n\n**Freeze-then-verify**\n- step N writes checksum\n- step N+1 verifies checksum before publish\n\n**Write-then-grep**\n- subagent writes a verdict file\n- main agent checks the first line for `PASS`\n\n**Phase-batch with critic**\n- batch related TODO items into one phase\n- verify hard artifacts with shell\n- then call `critic-loop` for adversarial review\n\n**Dry-run before execution**\n- dry-run command\n- human review\n- real command\n\n**Chain-link via forward + slug**\n- layer N's contract requires `forward` with a specific adapter slug\n- agent calls `forward` to start the next adapter (new `execution_id`)\n- next adapter runs its own layer chain through to `reward`\n- use when the protocol exceeds 350 lines or needs multi-path routing\n- NOT a replacement for layers — layers remain the primary unit of work\n- example contract:\n  ```json\n  {\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"forward\",\"arguments\":{\"uri\":\"squadrules://adapter/implement-plan\"}},\"required\":true}}\n  ```\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Reward Signal\n\nOnly reachable after all prior steps are solved.\n\nThe agent can now:\n1. pick the correct challenge type for each protocol step\n2. match challenge type to the step's mode\n3. choose the right interpreter\n4. apply working-directory and security rules\n5. preserve real shell statuses for silent checks\n6. use stronger verification patterns instead of weak narrative checks\n",
-        "create-new-protocol": "---\nversion: \"5.9.0\"\nslug: create-new-protocol\ntitle: Create New Protocol (Redirect to Author Adapter)\n---\n\n# Create New Protocol (Redirect to Author Adapter)\n\n`create-new-protocol` was renamed to **`author-adapter`** in 5.6.0. This adapter\nis a redirect tombstone: it exists only so a stored adapter that still chains to\n`squadrules://adapter/create-new-protocol` resolves and is sent to the replacement\ninstead of dangling. It carries no authoring logic. Do not author new adapters\nagainst this slug — use `squadrules://adapter/author-adapter`.\n\n## Activation Patterns\n\n**Typically invoked by:** a stored adapter that still forwards to the retired\n`create-new-protocol` slug.\n\n**Can be invoked directly when agent needs:**\n- \"create new protocol\" — the retired name for the author adapter\n\n**Must Never:**\n- Perform any authoring itself; this tombstone only redirects.\n- Be used as the target of a new adapter chain.\n\n**Must Always:**\n- Send the caller to `squadrules://adapter/author-adapter`, forwarding the same\n  context it received.\n\n## Redirect\n\nForward to the replacement and continue the run there. `author-adapter` is the\ncreate / review / update lifecycle that replaced `create-new-protocol`; its\nintegration rules live in the adapter itself. See ADR 0016 (the rename).\n\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"forward\",\"arguments\":{\"uri\":\"squadrules://adapter/author-adapter\"}},\"required\":true}}\n```\n\n## Reward Signal\n\nThe caller reached `squadrules://adapter/author-adapter`, so the retired slug\nresolved and redirected instead of dangling.\n",
-        "critic-loop-guide": "---\nversion: \"5.9.0\"\nslug: critic-loop-guide\ntitle: Critic Loop Integration and Mutation Gate Guide\n---\n\n# Critic Loop Integration and Mutation Gate Guide\n\nDecision rules for integrating `critic-loop` into adapter protocols: when a\nsolution check (hard verification gate) is required versus when critic-loop\nreview is sufficient, and how to split and batch proofs so reversible work stays\ncheap while irreversible boundaries stay guarded.\n\n## Activation Patterns\n\n**Typically invoked by:** `author-adapter` during adapter drafting, and\nany adapter that includes review or validation phases.\n\n**Can be invoked directly when agent needs:**\n- \"when to add critic loop\" / \"should I use solution check\"\n- \"mutation gate rules\" / \"which actions need hard gates\"\n- \"critic loop vs solution check\" / \"irreversible action rules\"\n- \"add review step to protocol\" / \"where does critic go\"\n\n**Trigger pattern:** **critic loop** / **mutation gate** / **solution check** +\n(integration | when | rules | guide | which | where).\n\n**Must Never:**\n- Be used as an execution protocol.\n- Override the adapter author's judgment on review depth.\n- Recommend solution checks for reversible or local-only actions.\n\n**Must Always:**\n- Distinguish between quality review (critic-loop) and mutation blocking\n  (solution checks).\n- Recommend looping critic-loop until PASS at every major phase boundary, fed the\n  requirement list and bounded by an iteration ceiling.\n- Restrict solution checks to irreversibility boundaries, and batch reversible\n  checkable steps into one strict-conjunction proof.\n\n**Good trigger examples:**\n- drafting a new adapter and deciding where to add review → load this\n- reviewing whether an adapter has the right solution checks → load this\n- \"does my MR step need a solution check?\" → load this\n\n**Bad trigger examples:**\n- \"run the critic loop\" → use `activate` to match `critic-loop`\n- \"create a new protocol\" → use `author-adapter`\n- \"which challenge type for this step?\" → use `challenge-type-guide`\n\n## Core Decision Rule\n\n**Critic-loop** is an adversarial review the calling protocol **loops until it\nreturns PASS** — not a one-shot step. It verifies claims, gathers evidence,\nsearches for contradictions, and checks the work against the original requirement\nlist. Use it for quality and truthfulness review, and whenever a step is\nnon-deterministic or has no objective proof. Run it **before** the work is handed\nto the next step, and before it is presented to the human.\n\n**Solution checks** are per-layer contract verification mechanisms (shell\ncommands, MCP tool calls). Use them ONLY where getting it wrong is expensive or\nimpossible to undo — **irreversible changes on remote systems** and the local\npreconditions that guard them (for example, being on a throwaway worktree/branch\nbefore you commit). Everything else is reversible: give the agent freedom and\nreview with critic-loop instead of adding a hoop.\n\n### What counts as an irreversible remote mutation\n\n| Action | Needs solution check? | Why |\n|--------|----------------------|-----|\n| Create/update merge request | Yes | Remote system state change |\n| Create/update Jira issue | Yes | Remote system state change |\n| Send email | Yes | Cannot unsend |\n| Send Teams message | Yes | Cannot unsend |\n| Create calendar invite | Yes | Sends notifications |\n| Deploy to production | Yes | Irreversible infrastructure change |\n| Delete remote resource | Yes | Irreversible |\n| Push to git remote | Yes | Remote state change |\n| Write/edit local file | No | Use critic-loop instead |\n| Run local tests | No | Read-only / local |\n| Analyze code | No | Read-only |\n| Generate report | No | Local artifact |\n| Read data from API | No | Read-only |\n| Compute / transform data | No | Local operation |\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Proof Splitting: Batch Checkable Steps Into One Proof\n\nSplit proofs by **reversibility cost**, not by step count:\n\n- **One proof per irreversibility boundary.** A boundary is where undoing the next\n  part is expensive or impossible: commit to `main`, mutate the human's active\n  worktree, `git push`, `gh pr create`, deploy, send.\n- **Batch reversible, checkable steps** and verify them together afterward with a\n  single aggregate proof — fewer round-trips, same guarantee.\n- **The aggregate proof must be a strict conjunction** that re-verifies every\n  sub-condition (`A && B && C && echo OK`):\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"test -f \\\"$OUT_A\\\" && test -f \\\"$OUT_B\\\" && grep -q \\\"$EXPECTED\\\" \\\"$OUT_A\\\" && echo OK\",\"timeout_seconds\":10},\"required\":true}}\n```\n\n- **Never let an aggregate proof degrade to `echo \"done\"`.** A proof that asserts\n  nothing is worse than no gate because it looks like one. If you cannot write a\n  real conjunction, the step is non-deterministic → review it with critic-loop\n  instead of faking a proof.\n\n### Guard the boundary before you cross it\n\nThe cheapest proof is the precondition that stops an irreversible mistake before\nit happens — for example, confirm you are on a throwaway worktree and branch (not\n`main`, not the human's active checkout) **before** making changes:\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"test \\\"$(git rev-parse --abbrev-ref HEAD)\\\" != main && git rev-parse --git-common-dir | grep -q worktrees\",\"timeout_seconds\":5},\"required\":true}}\n```\n\n## How to Chain Critic-Loop into an Adapter\n\nUse `forward` + slug to invoke `critic-loop` at phase boundaries. The standard\npattern is a `mcp` contract that requires calling `forward` with the\n`critic-loop` slug:\n\n### After a planning phase\n\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"forward\",\"arguments\":{\"uri\":\"squadrules://adapter/critic-loop\"}},\"required\":true}}\n```\n\n### After an implementation phase\n\nUse the same contract. The critic-loop adapter receives the calling protocol's\ncontext and independently verifies the work.\n\n### What to submit for review\n\nThe submission is the **work itself**, not a summary of it. Pass `work` with a\n`kind`, an `items` list, and the absolute `root` the items resolve against:\n\n| `kind` | `items` contain | Resolved by | Typical work |\n|---|---|---|---|\n| `file_set` | paths (absolute, or relative to `root`) | read each file | docs, generated code, configs |\n| `links` | URLs, `squadrules://` resource URIs | fetch each one | published pages, external references |\n| `git_diff` | `base..head` refs, or empty for the working tree | `git diff` | an unpushed implementation |\n| `pr` | PR numbers or URLs | `gh pr view` + `gh pr diff` | a reviewable pull request |\n| `command_output` | commands to run from `root` | run and capture | migrations, builds, data pulls |\n| `inline` | the text itself | read the manifest | a plan, a decision, a message draft |\n\nRecord `work` in the handoff file pointed to by `$WORK_MANIFEST`, as flat keys —\n`kind:`, `root:`, then `items:` with one item per line — so the precondition\nstays a machine-checkable file test instead of prose:\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"test -f \\\"${WORK_MANIFEST:-}\\\" || test -f \\\"${INPUT_FILE:-}\\\"\",\"timeout_seconds\":3},\"required\":true}}\n```\n\nAnything that cannot be resolved is `verification_blocked` — an item the critic\ncould not read is never treated as an item that passed. `input_file` still works\nand means a one-item `file_set`; prefer `work_manifest` for anything that is not\na single document. A `pr` or `git_diff` submission is judged on the diff and the\ntests it touches, not on the description written next to it.\n\n### Feed it the requirements, then loop with a ceiling\n\nPass the original requirement list in the forward context. A critic that sees only\nthe output can check internal consistency but **cannot detect an omitted\nrequirement** — omission leaves no trace in the artifact — so \"no requirements\nlost\" is only enforceable if the critic is given the list and asserts coverage\nitem by item. Then loop: on FAIL, fix, increment `iteration`, and re-invoke until\nPASS or until `max_iterations` is reached. The ceiling is a hard stop that\nsurfaces the unresolved findings; it prevents a weak agent from thrashing forever.\n\n### Verdict handoff pattern\n\nCritic-loop writes a verdict file. The calling adapter reads it:\n\n1. Critic-loop writes `$VERDICT_FILE` with `PASS`/`FAIL` on line 1.\n2. Calling adapter's next layer reads the verdict file.\n3. If `FAIL` → **hard stop**: do NOT proceed to reward, do NOT ask the user\n   for approval, do NOT continue to the next phase. Address findings first.\n4. If `PASS` → the adapter continues to the next phase.\n\n**FAIL is a hard stop, not an escalation trigger.** A FAIL verdict means the\nwork is not ready. Asking the user \"should I proceed?\" after FAIL bypasses the\nreview. The correct action is to fix the findings and re-invoke critic-loop.\n\n### FAIL gate contract (required after every critic-loop invocation)\n\nEvery adapter that chains critic-loop **must** include a shell contract that\nfails when the verdict is not PASS. This is the mechanical guard that prevents\nweaker agents from proceeding after FAIL:\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"head -1 \\\"$VERDICT_FILE\\\" | grep -qi '^PASS$'\",\"timeout_seconds\":5},\"required\":true}}\n```\n\nIf the critic wrote FAIL, this shell command exits non-zero. The server rejects\nthe solution and the agent cannot advance to the next layer. Protocol wording\nalone does not stop determined agents; this contract does.\n\n## Train/Tune Evidence Requirement\n\n`train` and `tune` enforce critic-loop PASS at the tool level:\n\n- **Adapter (markdown) `train`** requires `review_evidence`: verdict_file path,\n  exit_code (must be 0), and stdout (line 1 must be PASS). Without it, the\n  server rejects the store with `REVIEW_EVIDENCE_REQUIRED`.\n- **`tune` with content** requires the same `review_evidence`. Space-only moves\n  skip this check.\n- **Artifact trains** (non-markdown mime) skip the evidence check.\n\nThis is the tool-level enforcement of the FAIL gate. Even if an agent bypasses\nthe adapter flow and calls `train` directly, the server rejects the store\nwithout PASS evidence. The agent must run critic-loop, capture the verdict\nfile, and pass it as `review_evidence`.\n\n## Mutation Gate Pattern\n\nUnder the AI-ownership model, agents execute autonomously — irreversible remote\nmutations are **not** gated by a human confirmation prompt. Gate them with\nobjective, machine-checkable contracts instead:\n\n### Pre-mutation readiness (objective, no human prompt)\n\nAssert the preconditions with a shell or mcp contract so the action only runs from a\nvalid state — never with a `user_input` \"are you sure?\" prompt:\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"test -n \\\"$TARGET_REPO\\\" && test -n \\\"$TARGET_BRANCH\\\"\",\"timeout_seconds\":5},\"required\":true}}\n```\n\n### Post-mutation verification (objective)\n\nConfirm the mutation actually took effect by reading the remote state back:\n\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"getMergeRequest\",\"arguments\":{\"repo\":\"X\"}},\"required\":true}}\n```\n\nThe guarantee comes from critic-loop (truth of intent) plus these objective\npre/post checks — not from asking a human to approve. Do not add `user_input`\nconfirmation gates for remote mutations.\n\n## Critic-Loop Placement Rules\n\n1. **Loop critic-loop until PASS at every major phase boundary** — after planning,\n   after implementation, after validation — feeding it the requirement list and\n   bounding it with an iteration ceiling.\n2. **Do NOT add critic-loop between every layer** — it is a phase-level review,\n   not a step-level check.\n3. **Put one objective proof at each irreversibility boundary** — remote mutation\n   or the local precondition that guards it: pre-mutation readiness +\n   post-mutation verification, never a human confirmation prompt.\n4. **Batch reversible, checkable steps into one aggregate strict-conjunction\n   proof** instead of one proof per step; never let it degrade to `echo \"done\"`.\n5. **Never replace a boundary proof with critic-loop** — critic-loop reviews truth\n   after the fact; it does not block an irreversible step.\n6. **Never add a proof for purely local, reversible operations** — critic-loop\n   provides sufficient review.\n\n## Adapter Authoring Checklist\n\nWhen drafting a new adapter, apply this checklist:\n\n1. Identify all phase boundaries in the adapter flow.\n2. Add a `critic-loop` chain link at each boundary.\n3. Identify all steps that perform irreversible remote mutations.\n4. Add objective solution checks (pre-mutation readiness + post-action\n   verification) for each — no `user_input` human-confirmation gate.\n5. Verify that no solution checks exist for purely local operations.\n6. Verify that the critic-loop verdict handoff pattern is present.\n7. Verify that a FAIL gate shell contract follows every critic-loop invocation.\n8. Verify that `train`/`tune` calls include `review_evidence` from the critic.\n9. Ensure the adapter's Reward Signal describes what the critic protects.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Reward Signal\n\nOnly reachable after all prior steps are solved.\n\nThe agent can now:\n1. Decide when to use critic-loop versus solution checks\n2. Identify irreversible remote mutations that need hard gates\n3. Chain critic-loop into adapters at the correct phase boundaries\n4. Apply the mutation gate pattern for remote-system actions\n5. Avoid unnecessary solution checks for local or read-only operations\n",
-        "critic-loop": "---\nversion: \"5.9.0\"\nslug: critic-loop\ntitle: Critic Loop\n---\n\n\n\n# Critic Loop\n\nBounded adversarial investigator that the calling protocol **loops until it\nreturns PASS** — not a one-shot review. Receives a work submission (files,\nlinks, a git diff, a pull request, command output, or inline text), the\noriginal requirement list, and the calling protocol's invariants, then\nindependently verifies the submitted work by extracting claims, gathering\nevidence, searching for contradictions, and checking requirement-by-requirement\ncoverage. A FAIL sends the caller back to fix and re-invoke; the loop is bounded\nby an explicit iteration ceiling (see Verdict).\n\n## Activation Patterns\n\n**Typically invoked by:** another protocol at the end of a plan, implement,\nvalidation, or review phase via `forward` with the stored adapter URI\n`squadrules://adapter/critic-loop`.\n\n**Can be invoked directly when agent needs:**\n- \"review phase output\" / \"verify plan\" / \"audit implementation\"\n- \"adversarial review\" / \"critic review\"\n\n**Trigger pattern:** **review** / **verify** / **audit** / **critic** +\n(phase / plan / implementation / output).\n\n**Must Never:**\n- Modify any submitted item or any file other than the verdict path.\n- Trust the executor's assertions without independent evidence.\n- Classify a claim as `verified` based only on absence of contradiction.\n- Keep investigating after a precondition failure that blocks verification.\n\n**Must Always:**\n- Extract claims before investigating.\n- Verify in-scope claims first.\n- Search for contradictory evidence, not only confirming evidence.\n- Check every item in the supplied requirement list for coverage; a missing\n  requirement is a FAIL even when the output is internally consistent.\n- Include confidence in every verdict and failure class in every FAIL verdict.\n- Preserve the boundary between execution and review.\n\n**Good trigger examples:**\n- implement protocol fires this after planning → run this protocol\n- compose protocol fires this after output generation → run this protocol\n\n**Bad trigger examples:**\n- \"Create a new protocol\" → use `author-adapter`\n- \"Implement a feature\" → use an execution protocol, not this one\n\n## Artifact Contract\n\nThis protocol receives:\n\n```text\n{\n  work: {\n    kind: 'file_set' | 'links' | 'git_diff' | 'pr' | 'command_output' | 'inline',\n    items: string[],              // paths | URLs | 'base..head' refs | PR URL/number | commands | text\n    root: string                  // absolute cwd used to resolve relative paths, refs and commands\n  },\n  work_manifest: string,          // absolute path to the handoff file recording `work`\n  input_file: string,             // accepted alias: a one-item work.kind='file_set'\n  calling_protocol_slug: string,\n  verification_target: string,\n  requirements: string[],         // original intent / requirement list to check coverage against\n  context: {\n    operation: string,\n    verdict_file: string,          // absolute path where the verdict will be written\n    iteration: number,             // 1-based loop pass; caller increments after each FAIL\n    max_iterations: number         // hard ceiling; exceeding it is a terminal FAIL\n  }\n}\n```\n\nThe submission is the **work itself**, not an essay about it. Write `work` to\n`$WORK_MANIFEST` as flat keys so the handoff stays machine-checkable:\n`kind:`, `root:`, then `items:` with one item per line. Callers that still pass\nonly `input_file` are handled as `kind: file_set` with that single path; the\nreview rules do not change, only the scope of what is submitted.\n\nThis protocol produces:\n\n```text\n{\n  verdict: \"PASS\" | \"FAIL\",\n  confidence: \"High\" | \"Medium\" | \"Low\",\n  failure_class: string,           // incorrect_claim | verification_blocked | requirement_gap | iteration_ceiling\n  uncovered_requirements: string[],// requirement items lacking positive evidence (empty on PASS)\n  verdict_file: \"{context.verdict_file}\"\n}\n```\n\n## Precondition Check [SUBAGENT]\n\nVerify foundational preconditions before deep investigation. Early-abort if any\nare broken.\n\n**Input:** `$WORK_MANIFEST` (or the older-spelling `$INPUT_FILE`), calling protocol slug, context\n\n**Actions:**\n1. Verify a submission handoff is present: `$WORK_MANIFEST`, or `$INPUT_FILE`\n   when the caller passed no manifest.\n2. Verify the verdict output path is writable (parent directory exists).\n3. Load the calling protocol's Must Never / Must Always sections if possible.\n4. Verify the target state is available for review.\n5. Verify required tools are available for the submission's `kind` (a `pr`\n   submission with no `gh` on the host is `verification_blocked`, not skipped).\n\n**On early-abort:**\n- verdict = `FAIL`\n- failure class = `verification_blocked`\n- confidence = `Low`\n- write focused diagnostics\n- skip all later steps\n\n**Output:** verified preconditions or early-abort diagnostics\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"test -f \\\"${WORK_MANIFEST:-}\\\" || test -f \\\"${INPUT_FILE:-}\\\"\",\"timeout_seconds\":3},\"required\":true}}\n```\n\n## Resolve Submission [SUBAGENT]\n\nTurn the submission into the material under review. What cannot be resolved is\nnever guessed at.\n\n**Input:** `work` recorded in `$WORK_MANIFEST` (or the older-spelling `$INPUT_FILE`),\n`work.root`\n\n**Actions:**\n1. Read `kind`, `root`, `items`. An unknown `kind`, an empty `items` list, or a\n   malformed manifest is `verification_blocked`.\n2. Resolve every item by kind, always from `work.root`:\n   - `file_set` — read each path; relative paths resolve against `root`, and a\n     missing path is `verification_blocked`.\n   - `links` — fetch each URL; a URL that cannot be fetched is\n     `verification_blocked`, not an `unverifiable` claim.\n   - `git_diff` — `git -C \"$root\" diff <base>..<head>`, or the working tree when\n     no range is given; no `git`, no repository, or a bad ref is\n     `verification_blocked`.\n   - `pr` — `gh pr view` plus `gh pr diff` for the number or URL; a missing\n     `gh`, an expired login, or an unreachable host is `verification_blocked`.\n   - `command_output` — run each command from `root` and capture stdout and\n     stderr as the material.\n   - `inline` — the text recorded in the manifest is the material.\n3. Record the resolved inventory before auditing: `kind`, item count, per-item\n   status (`resolved` or `blocked`), and where each item's evidence lives. The\n   audit investigates this inventory and nothing else.\n4. A `pr` or `git_diff` submission is reviewed as a diff: claims are checked\n   against the changed lines and the tests they touch, never against the\n   description written alongside them.\n\n**Output:** resolved work inventory for the audit\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Audit [SUBAGENT]\n\nPerform bounded adversarial review of the target against the resolved work\nsubmission and invariants.\n\n**Input:** resolved work inventory, invariants, verification target, requirement list, context\n\n**Actions:**\n\n**Step 1 — Extract claims**\nExtract every verifiable claim that matters operationally:\n- workflows, commands, tool calls\n- configuration and environment variable claims\n- architecture claims that imply behaviour\n- guarantees and constraints\n- security, auth, and permission claims\n\n**Step 2 — Investigate with scope discipline**\n1. verify all in-scope claims first\n2. review high-risk claims with maximum depth\n3. expand beyond scope only when contradiction signals, dependencies, or\n   high-risk impact require it\n4. continue reviewing all in-scope claims even after a normal FAIL condition is met;\n   only a precondition failure stops the audit early\n\n**High-risk areas**\n- setup steps and prerequisites\n- CLI commands and flags\n- configuration keys and environment variables\n- authentication, identity, and permissions\n- deployment and release behaviour\n- external publishing actions\n- destructive or irreversible operations\n\n**Step 3 — Gather evidence using the hierarchy**\n\n| Priority | Evidence source |\n|---|---|\n| 1 | source code, config files, schemas, route definitions |\n| 2 | direct runtime verification |\n| 3 | tests |\n| 4 | MCP-queried system state |\n| 5 | external docs, web pages, linked references |\n| 6 | conversational assumption or indirect inference |\n\n**Rules:**\n- higher-priority evidence overrides lower-priority evidence\n- priority 5–6 alone is not enough for `verified`\n- a submitted link or PR description is priority 5 evidence: verify the claim\n  against the fetched content or the actual diff, never against the summary\n\n**Step 4 — Produce claim verdicts**\n\nFor each claim, record:\n- CLAIM\n- EVIDENCE\n- EVIDENCE PRIORITY\n- VERDICT: `verified` / `partially_verified` / `unverifiable` / `incorrect`\n\nA claim must not be marked `verified` without positive supporting evidence.\n\n**Step 5 — Review the phase boundary**\nCheck whether the calling protocol preserved the right mode boundary:\n- was execution reviewed independently?\n- were review and execution kept separate?\n- did the protocol switch to verification when it should have?\n- is escalation needed because certainty was overstated?\n\n**Step 6 — Check requirement coverage**\nFor every item in the supplied `requirements` list, confirm the target addresses\nit with positive evidence and record it as `covered` / `partial` / `missing`. An\nomitted requirement leaves no trace in the output, so coverage can only be judged\nagainst the list, never from the artifact alone. Any `missing` item — or any\n`partial` high-risk item — forces a FAIL with `failure_class: requirement_gap`.\n\n**Output:** structured audit findings for the verdict step\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":120},\"required\":true}}\n```\n\n## Verdict [SUBAGENT]\n\nTurn the audit into a final PASS / FAIL result.\n\n**Input:** audit findings and verdict file path from context (use it as\n`$VERDICT_FILE`)\n\n**Actions:**\n1. Fail if any critical claim is incorrect.\n2. Fail if verification was blocked.\n3. Fail if the evidence base is too weak for high-risk claims.\n4. Fail if any requirement is `missing`, or a high-risk requirement is only\n   `partial` (`failure_class: requirement_gap`); list the uncovered items.\n5. Fail terminally if `context.iteration` exceeds `context.max_iterations`\n   (`failure_class: iteration_ceiling`) so the loop stops instead of thrashing.\n6. Otherwise, pass with the appropriate confidence.\n7. Write `$VERDICT_FILE` so line 1 is `PASS` or `FAIL`,\n   line 2 is `High`, `Medium`, or `Low`, and the remaining lines summarise key\n   findings and any uncovered requirements.\n\n**Verdict contract (calling adapter must obey):**\n- Line 1 is `PASS` → the loop is satisfied; the calling adapter may continue.\n- Line 1 is `FAIL` → the calling adapter **MUST NOT** proceed to reward, **MUST\n  NOT** ask the user for approval, and **MUST NOT** continue. It must address the\n  findings, increment `context.iteration`, and re-invoke critic-loop.\n- `failure_class: iteration_ceiling` → stop looping and surface the unresolved\n  findings; never silently pass. The ceiling bounds the loop so a weak agent\n  cannot thrash forever.\n\n**Output:** final verdict file\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"test -f \\\"$VERDICT_FILE\\\" && head -1 \\\"$VERDICT_FILE\\\" | grep -qiE '^(PASS|FAIL)$' && sed -n '2p' \\\"$VERDICT_FILE\\\" | grep -qiE '^(High|Medium|Low)$'\",\"timeout_seconds\":5},\"required\":true}}\n```\n\n## Reward Signal\n\nOnly reachable after all prior steps are solved.\n\nThe phase output has been independently challenged and looped until satisfied. The\nresulting verdict is more truthful because it is based on extracted claims,\nexplicit evidence, contradiction search, requirement-by-requirement coverage, and\na clean boundary between execution and review.\n",
-        "phase-critic-guide": "---\nversion: \"5.9.0\"\nslug: phase-critic-guide\ntitle: Phase Critic Guide (Redirect to Critic Loop Guide)\n---\n\n# Phase Critic Guide (Redirect to Critic Loop Guide)\n\n`phase-critic-guide` was renamed to **`critic-loop-guide`** in 5.4.0. This is a\nredirect tombstone kept so the retired slug still resolves. It carries no rules\nof its own — read **`squadrules://adapter/critic-loop-guide`** for the current\ncritic-loop integration, the solution-check-vs-critic decision table, and the\nproof-splitting rules. Do not author against this slug.\n\n## Activation Patterns\n\n**Typically invoked by:** an agent or adapter that still references the retired\n`phase-critic-guide` slug.\n\n**Can be invoked directly when agent needs:**\n- \"phase critic guide\" — the retired name for the critic-loop guide\n\n**Must Never:**\n- Restate the integration rules here; they live in `critic-loop-guide`.\n\n**Must Always:**\n- Point the reader to `squadrules://adapter/critic-loop-guide`.\n\n## Redirect\n\n`critic-loop-guide` is the single home for critic-loop integration and mutation\ngate placement. Activate `squadrules://adapter/critic-loop-guide` and read it\nthere. See ADR 0010 (the rename) and ADR 0012 (why the tombstone is kept).\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":40},\"required\":true}}\n```\n\n## Reward Signal\n\nThe reader was directed to `squadrules://adapter/critic-loop-guide`, so the\nretired slug resolved instead of dangling.\n",
-        "phase-critic": "---\nversion: \"5.9.0\"\nslug: phase-critic\ntitle: Phase Critic (Redirect to Critic Loop)\n---\n\n# Phase Critic (Redirect to Critic Loop)\n\n`phase-critic` was renamed to **`critic-loop`** in 5.4.0. This adapter is a\nredirect tombstone: it exists only so a stored adapter that still chains to\n`squadrules://adapter/phase-critic` resolves and is sent to the replacement\ninstead of dangling. It carries no review logic. Do not author new adapters\nagainst this slug — use `squadrules://adapter/critic-loop`.\n\n## Activation Patterns\n\n**Typically invoked by:** a stored adapter that still forwards to the retired\n`phase-critic` slug.\n\n**Can be invoked directly when agent needs:**\n- \"phase critic\" — the retired name for the critic loop\n\n**Must Never:**\n- Perform a review itself; this tombstone only redirects.\n- Be used as the target of a new adapter chain.\n\n**Must Always:**\n- Send the caller to `squadrules://adapter/critic-loop`, forwarding the same\n  `work` submission (or the older-spelling `input_file`), `requirements`, and\n  `context` it received.\n\n## Redirect\n\nForward to the replacement and continue the run there. `critic-loop` is the\nbounded, requirement-aware review that replaced `phase-critic`; its integration\nrules live in `critic-loop-guide`. See ADR 0010 (the rename) and ADR 0012 (why\nthe tombstone is kept).\n\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"forward\",\"arguments\":{\"uri\":\"squadrules://adapter/critic-loop\"}},\"required\":true}}\n```\n\n## Reward Signal\n\nThe caller reached `squadrules://adapter/critic-loop`, so the retired slug\nresolved and redirected instead of dangling.\n",
-        "protocol-linking-guide": "---\nversion: \"5.9.0\"\nslug: protocol-linking-guide\ntitle: Protocol Linking Guide\n---\n\n\n\n# Protocol Linking Guide\n\nDecision rules for structuring adapter relationships: layers vs chains,\n`activate` vs `forward` + slug, chain-root collapsing, and MCP argument\nvalidation for deterministic cross-protocol linking.\n\n## Activation Patterns\n\n**Typically invoked by:** `author-adapter` and\n`critic-loop`.\n\n**Can be invoked directly when agent needs:**\n- \"layers vs chains\" / \"when to split into multiple adapters\"\n- \"how to link adapters\" / \"cross-protocol linking\"\n- \"activate vs forward\" / \"when to use forward with slug\"\n- \"chain-root collapsing\" / \"how chain_root works\"\n\n**Trigger pattern:** **layers** / **chains** / **linking** / **forward** +\n(slug | adapter | protocol).\n\n**Must Never:**\n- Be used as an execution protocol.\n- Recommend chaining when layers suffice.\n\n**Must Always:**\n- Be consulted before splitting a protocol into multiple adapters.\n- Be consulted before adding `forward` calls or `chain_root` frontmatter.\n\n**Good trigger examples:**\n- \"my protocol is 400 lines, should I split?\" → load this\n- \"how do I link adapter A to adapter B?\" → load this\n- \"what is chain_root?\" → load this\n\n**Bad trigger examples:**\n- \"which challenge type for this step?\" → use `challenge-type-guide`\n- \"create a new protocol\" → use `author-adapter`\n\n## Layers vs Chains\n\n**Layers** (H2 steps within one adapter) are the preferred unit of work. Use\nlayers when all steps fit in one adapter under 350 lines and serve a single\ncohesive concern.\n\n**Chain via `forward` + slug** — use only when:\n- the adapter exceeds 350 lines\n- weaker models cannot follow the full adapter in one pass\n- runtime routing to different adapters is needed (Router pattern)\n- a step is reusable across multiple parent adapters (e.g. `critic-loop`)\n\nChaining is NOT a replacement for layers. A 6-step protocol that fits in 350\nlines should stay as one adapter with 6 H2 layers.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## `activate` vs `forward` + slug\n\n| Situation | Use |\n|---|---|\n| Initial user-intent resolution | `activate` |\n| Target adapter is known at authoring time | `forward` + slug |\n| Target depends on runtime classification the current adapter cannot resolve | `activate` |\n| Linking to the next adapter in a chain | `forward` + slug |\n| Reusable sub-protocol invoked by multiple parents | `forward` + slug |\n\nNever call `activate` just to get a slug you already know — it wastes a\nround-trip and introduces non-determinism.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Chaining Back and Forward\n\nWhen a family of adapters has a root conductor and smaller domain extensions,\ndocument both directions of chaining.\n\n### Chaining back with `chain_root`\n\nExtension adapters should include `chain_root` frontmatter and a prerequisite\nclause:\n\n**Prerequisite:** Start from `<root-adapter-slug>` unless the caller already\nprovided a mission brief, safety gates, authorization boundary, and evidence\nrequirements.\n\nThis protects activation entry points. If a user or weak agent activates a\nmid-chain extension directly, the extension can collapse back to the root unless\nit already received the required parent context.\n\n### Chaining forward with `forward`\n\n`chain_root` does not replace explicit `forward` calls inside the chain.\n\nWhen the next adapter is known at authoring time or after deterministic runtime\nclassification, use `forward` with the target slug. Do not call `activate` just\nto rediscover a slug already known by the current adapter.\n\nForwarded adapters should receive:\n- current mission brief;\n- safety gates;\n- authorization boundary;\n- evidence requirements;\n- user constraints;\n- reason for forwarding.\n\nUse `activate` only when the next adapter must be discovered from an ambiguous\nruntime need.\n\n### Multi-layer conductors and extension URIs\n\nWhen you are executing **`forward`** inside a **multi-layer** adapter (for example\na root conductor), each continuation follows **`next_call`** for the **same**\n`execution_id` until the last layer directs **`reward`**. A layer that mentions\nanother adapter URI only as routing guidance — for example\n`squadrules://adapter/e2e-coding-pr-delivery` — does **not** cause the server to\nswitch executions: the next **`forward`** in that run still advances the\n**current** adapter’s next layer.\n\nTo run an extension adapter, call **`forward`** with\n`squadrules://adapter/<slug>` as a **new** first call (adapter URI; omit\n`solution`). That starts a **separate** execution with its own layers. Common\npattern: complete the conductor with **`reward`**, then **`forward`** to the\nextension slug when coding or PR-shaped work should run under that adapter’s\ncontracts.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## System adapters vs user adapters\n\nBoth system and user-authored adapters chain using slugs in `next_action`:\n\n```text\ncall forward with squadrules://adapter/critic-loop ...\ncall forward with squadrules://adapter/implement-terraform ...\n```\n\nSlugs are globally unique (enforced by `train`), so resolution is\ndeterministic — no scoring, no ambiguity.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## MCP argument validation for chain links\n\nA bare `mcp` contract checks only the tool name:\n\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"forward\"},\"required\":true}}\n```\n\nAn `mcp` contract **with `arguments`** verifies the exact target:\n\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"forward\",\"arguments\":{\"uri\":\"squadrules://adapter/code-review-policy\"}},\"required\":true}}\n```\n\nThe server validates that `solution.mcp.arguments` is a superset of the\ncontract's `mcp.arguments` (subset/deep matching). This proves the agent\ncalled `forward` with the correct slug, not just any `forward` call.\n\nUse the `arguments` form whenever a step's purpose is to invoke a specific\nknown adapter.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Chain-root collapsing\n\nWhen a chain has multiple adapters, `activate` might match a mid-chain adapter\ndirectly. Without protection, the agent would start at the wrong step, missing\nprerequisite context gathered by earlier phases.\n\n**`chain_root` frontmatter field** solves this at the server level. Add it to\nevery mid-chain adapter:\n\n```yaml\n---\nslug: implement-plan\nversion: 1.0.0\nchain_root: implement\n---\n```\n\n**Server behaviour:** When `activate` returns a match that has `chain_root`,\nthe server resolves the slug to the root adapter's URI and replaces the\nchoice's `uri` and `next_action` to point there. Multiple mid-chain matches\nfrom the same chain are deduplicated to a single entry. The agent always\nstarts at the chain entry point.\n\n**Defense in depth — protocol-level safeguards:** Each mid-chain adapter\nshould include a **Prerequisites** paragraph in its Activation Patterns\nlisting inputs required from earlier phases and directing the agent to start\nfrom the chain root if those inputs are missing. This catches direct `forward`\ncalls that bypass `activate`.\n\n**Rules:**\n- The chain root adapter must NOT have `chain_root` in its frontmatter.\n- `chain_root` must refer to an existing slug (the chain entry point).\n- `forward` calls within a chain are unaffected — `chain_root` only changes\n  `activate` output routing.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Reward Signal\n\nOnly reachable after all prior steps are solved.\n\nThe agent can now:\n1. decide when to use layers vs chains\n2. choose `activate` vs `forward` + slug correctly\n3. use slug-based linking for all adapters (system and user)\n4. apply MCP argument validation for deterministic chain links\n5. implement `chain_root` collapsing with defense-in-depth safeguards\n6. document chaining back (`chain_root` + prerequisites) and chaining forward\n   (`forward` with known slugs) for root + extension families\n",
-        "refine-search": "---\nversion: \"5.9.0\"\nslug: refine-search\ntitle: Get help refining your search\n---\n\n\n\n# Get help refining your search\n\n**You are an AI agent.** You ran `activate` and got no solid match, or only weak\n/ ambiguous matches. This adapter helps you turn a vague request into a better\nquery so the next `activate` can find the right adapter.\n\nSQUADRULES principle: before acting, understand the user better. The goal is not to\nrepeat the failed phrase with minor edits. The goal is to recover the user's\nreal intent.\n\n## Activation Patterns\n\n**Run this adapter when:**\n- `activate` returned no match.\n- `activate` returned only weak choices.\n- The response included a `refine` choice.\n\n**Trigger pattern:** after `activate` when no strong match exists.\n\n**Must Never:**\n- Run when a strong match already exists.\n- Loop refinement endlessly.\n\n**Must Always:**\n- Infer the real goal, context, and missing constraints from the user's request.\n- Build a more specific query than the one that failed.\n- Run at most once per user request; if the second activation still fails, stop\n  and offer clarification or protocol creation.\n\n**Good trigger examples:**\n- activate returned only \"refine\" / weak matches → run this adapter\n- \"No protocol matched 'do the thing'\" → run this adapter\n\n**Bad trigger examples:**\n- activate returned a strong match → use that match instead\n- user asked \"what adapters exist?\" → use `activate` / `spaces`, not this\n\n## Step 1: Extract what the user actually wants\n\nFrom the user's original message, identify:\n- the real goal\n- relevant context\n- missing constraints\n- likely wording that would help SQUADRULES find the right adapter\n\nWrite your analysis as the solution.\n\n```json\n{\n  \"contract\": {\n    \"type\": \"comment\",\n    \"comment\": { \"min_length\": 60 },\n    \"required\": true\n  }\n}\n```\n\n## Step 2: Build and run a refined activate query\n\nUsing Step 1, construct one refined query with 3–8 specific words. Do not reuse\nthe vague phrase that already failed.\n\nCall `activate` with it.\n\n- **Strong match (score >= 0.5):** pick that choice and `forward`.\n- **Weak matches only:** ask the user to clarify or offer the create path.\n\nDo not loop more than once.\n\n```json\n{\n  \"contract\": {\n    \"type\": \"mcp\",\n    \"mcp\": { \"tool_name\": \"activate\" },\n    \"required\": true\n  }\n}\n```\n\n## Reward Signal\n\nOnly reachable after all prior steps are solved.\n\nThe agent has converted a failed literal search into a more truthful,\nuser-aligned activation attempt.\n",
-        "skill-format-guide": "---\nversion: \"5.9.0\"\nslug: skill-format-guide\ntitle: Skill Format and Local Authoring Guide\n---\n\n\n\n# Skill Format and Local Authoring Guide\n\nDecision rules for authoring SKILL.md files, choosing between local (git) and\nserver (SQUADRULES) storage, and quality gates for skill content. Fetches the\ncurrent Agent Skills format spec (Context7 or agentskills.io) as the\nauthoritative generic format, then layers SQUADRULES customizations on top. Loaded\nby protocol-authoring agents during drafting and review when the output format\nis `skill`.\n\n## Activation Patterns\n\n**Typically invoked by:** `author-adapter` and\n`critic-loop`.\n\n**Can be invoked directly when agent needs:**\n- \"SKILL.md format reference\" / \"how to write a skill\"\n- \"latest SKILL.md spec\" / \"current agentskills format\"\n- \"skill vs adapter\" / \"local skill or SQUADRULES adapter\"\n- \"skill quality gates\" / \"SKILL.md structure\"\n- \"project-level skill\" / \"where to put a skill\"\n\n**Trigger pattern:** **skill** + (format | structure | guide | quality | local | spec).\n\n**Must Never:**\n- Be used as an execution protocol.\n- Recommend storing a skill in both git AND SQUADRULES server simultaneously.\n- Confuse SKILL.md (agent instruction file) with protocol markdown (adapter).\n- Hardcode the generic SKILL.md format from memory when the current spec is\n  reachable via Context7 or agentskills.io.\n\n**Must Always:**\n- Be consulted before writing any SKILL.md file.\n- Fetch the current Agent Skills spec before authoring or reviewing generic\n  format, and apply SQUADRULES customizations after it.\n- Enforce single source of truth: each skill lives in exactly one place.\n- Match storage location to the skill's scope and discoverability needs.\n\n**Good trigger examples:**\n- drafting a new skill and need format rules → load this\n- reviewing a SKILL.md for quality → load this\n- deciding local vs server for a skill → load this\n\n**Bad trigger examples:**\n- \"which challenge type for this step?\" → use `challenge-type-guide`\n- \"create a new protocol\" → use `author-adapter`\n\n## Storage Decision\n\nEvery skill has ONE home. Choose at authoring time. Never both.\n\n| Scope | Storage | Discovery | Source of Truth |\n|---|---|---|---|\n| Project-specific (deploy, test, release) | Git: `.agents/skills/{name}/` or `.cursor/skills/{name}/` | IDE host scans description field | Git repo |\n| Personal cross-project (universal) | SQUADRULES server via `train` | `activate` embedding search | SQUADRULES server |\n| Team/group shared | SQUADRULES server (group space) | `activate` | SQUADRULES server |\n\n### Decision Tree\n\n```\nIs this skill specific to ONE project's codebase?\n ├─ YES → Does it reference repo files, paths, or project-specific tools?\n │         ├─ YES → LOCAL (git)\n │         └─ NO  → Could it help in other projects?\n │                   ├─ YES → SERVER (SQUADRULES)\n │                   └─ NO  → LOCAL (git)\n └─ NO → SERVER (SQUADRULES)\n```\n\n### Local Storage Paths\n\n| Host | Path | Scope |\n|---|---|---|\n| Cursor IDE (project) | `.cursor/skills/{name}/SKILL.md` | Repo-scoped, git-controlled |\n| Cursor IDE (personal) | `~/.cursor/skills/{name}/SKILL.md` | User-wide, all projects |\n| Claude Code (project) | `.agents/skills/{name}/SKILL.md` | Repo-scoped, git-controlled |\n| Claude Code (personal) | `~/.agents/skills/{name}/SKILL.md` | User-wide, all projects |\n\n**Never** create skills in `~/.cursor/skills-cursor/` — reserved for system.\n\n### Promotion and Demotion\n\n**Local → Server (skill graduates to universal):**\n1. Read existing SKILL.md\n2. Optionally wrap in protocol structure (Activation Patterns, contracts)\n3. `train` to SQUADRULES server\n4. Delete local copy or mark deprecated\n5. Git commit the deletion\n\n**Server → Local (adapter becomes project-specific):**\n1. `export` with `format: skill_zip` or `format: markdown`\n2. Write to `.agents/skills/{slug}/SKILL.md`\n3. Optionally `delete` from server\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Fetch the Current Skill Format Spec\n\nDo NOT rely on a frozen copy of the SKILL.md format. The Agent Skills format\nevolves (new frontmatter fields, directory conventions, size guidance). Before\nauthoring or reviewing a SKILL.md, fetch the **current** specification and treat\nit as authoritative for the generic format. The SQUADRULES customizations in the\nsections *after* this one layer on top of that generic spec.\n\n**Authoritative source (fetch fresh — do not guess):**\n\n1. **Context7 (preferred):** query the Agent Skills docs library for the\n   SKILL.md format. Use one of these library IDs directly (skip\n   `resolve-library-id`):\n   - `/llmstxt/agentskills_io_llms-full_txt` — full spec text (best coverage)\n   - `/websites/agentskills_io` — the agentskills.io site docs\n   Example query: \"SKILL.md frontmatter fields, directory structure, size limits\".\n2. **URL fallback:** if Context7 is unavailable or returns nothing usable,\n   fetch `https://agentskills.io/specification`. Use\n   `https://agentskills.io/llms.txt` as the documentation index to discover\n   related pages.\n\n**What to extract from the fetched spec (do not hardcode from memory):**\n- Required and optional YAML frontmatter fields and their constraints\n  (for example `name`, `description`, and any newer fields such as `license`,\n  `compatibility`, `metadata`, `allowed-tools`).\n- Directory structure and conventional subdirectory names\n  (for example `scripts/`, `references/`, `assets/`).\n- Body content recommendations and section guidance.\n- Size / progressive-disclosure guidance (line and token targets).\n- Any spec-provided validation tooling (for example `skills-ref validate`).\n\n**Rules:**\n- Apply the fetched spec's constraints exactly for the generic format.\n- If the fetch fails on BOTH Context7 and the URL, STOP and tell the user the\n  spec is unreachable — do not fabricate field lists or limits from memory.\n- Record which source and (if available) which version/date you fetched, so the\n  authoring decision is auditable.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## SQUADRULES Customizations (apply after the generic spec)\n\nEverything below is SQUADRULES-specific and layers on top of the fetched Agent\nSkills spec. When the generic spec and these rules disagree on generic format,\nfollow the spec; these rules add SQUADRULES storage, integrity, and routing\nbehavior the generic spec does not cover.\n\n### SQUADRULES additions to structure\n\n- **`SHA256SUMS`** — required for SQUADRULES-exported skill bundles (GNU\n  `sha256sum` format, paths relative to the skill dir). This is a SQUADRULES\n  integrity requirement, not part of the generic Agent Skills spec.\n- **`disable-model-invocation`** — when the host supports it, SQUADRULES-authored\n  skills default this to `true` (explicit load only) unless the skill is meant\n  to auto-trigger. Only add fields the fetched spec actually recognizes.\n- **Reference depth** — keep references one level deep (SKILL.md → reference\n  file, never deeper), consistent with the spec's progressive-disclosure model.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Quality Gates\n\n### Description Quality\n\nThe description is the primary discovery mechanism. It must:\n\n1. Be written in **third person** (not \"I can help\" or \"you can use\")\n2. State **WHAT** the skill does (specific capabilities)\n3. State **WHEN** to use it (trigger scenarios, file patterns, keywords)\n4. Include **trigger terms** that match real user language\n5. Avoid vague words: \"helps with\", \"assists\", \"various\"\n\n**Good:**\n```yaml\ndescription: >-\n  Validate and publish Confluence pages managed as local markdown via Mark CLI.\n  Use when the user asks to dry-run, validate, publish, or sync a Confluence\n  page, or when working with files under confluence/ that have Mark metadata.\n```\n\n**Bad:**\n```yaml\ndescription: Helps with Confluence stuff.\n```\n\n### Content Quality\n\n| Check | Rule |\n|---|---|\n| Consistent terminology | One term per concept throughout |\n| No time-sensitive info | No \"before August 2025\" conditions |\n| Concrete examples | Real inputs/outputs, not abstract |\n| Actionable instructions | Agent knows what to DO, not just what exists |\n| Default tool choice | One recommended tool, escape hatch for alternatives |\n| No Windows paths | Forward slashes only |\n\n### Degree of Freedom\n\nMatch instruction specificity to the task's fragility:\n\n| Level | When | Example |\n|---|---|---|\n| High (text guidelines) | Multiple valid approaches | Code review guidelines |\n| Medium (templates/pseudocode) | Preferred pattern, acceptable variation | Report generation |\n| Low (exact scripts) | Fragile operations, consistency critical | DB migrations |\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Finalisation Paths\n\n### Path A: Local Write (project-level skill)\n\nWhen `{target}=local`:\n\n1. Determine output path from scope:\n   - Project Cursor: `.cursor/skills/{name}/SKILL.md`\n   - Project Claude: `.agents/skills/{name}/SKILL.md`\n   - Personal: `~/.cursor/skills/{name}/SKILL.md` or `~/.agents/skills/{name}/`\n2. Create directory if needed\n3. Write SKILL.md with frontmatter and body\n4. Generate `SHA256SUMS` (GNU sha256sum format, paths relative to skill dir)\n5. Write any reference files and scripts\n6. Verify: `test -f \"{path}/SKILL.md\" && wc -l \"{path}/SKILL.md\"`\n7. Report path and line count to user\n\nDo NOT call `train`. The skill lives only in git.\n\n### Path B: Server Train (SQUADRULES-routable adapter)\n\nWhen `{target}=server`:\n\n1. Wrap skill content in protocol markdown if needed:\n   - Add Activation Patterns (first H2)\n   - Add contract blocks per layer\n   - Add Reward Signal (last H2)\n2. Call `train` with full markdown\n3. Verify adapter URI returned\n4. Report URI and slug to user\n\nDo NOT write to local disk. The adapter lives only in SQUADRULES.\n\n### Path C: Hybrid Authoring (skill that is also an adapter)\n\nWhen `{target}=hybrid` (rare — use only when explicitly requested):\n\n1. Author as a SQUADRULES protocol (Activation Patterns, contracts, Reward Signal)\n2. `train` to server\n3. `export` with `format: skill_zip` to produce local SKILL.md bundle\n4. The exported SKILL.md is a **read-only derived artifact**, not a source of truth\n5. Document in the SKILL.md header that it was exported from SQUADRULES\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Reward Signal\n\nOnly reachable after all prior steps are solved.\n\nThe agent can now:\n1. Fetch the current Agent Skills spec (Context7 or agentskills.io) instead of\n   relying on a frozen copy, and apply it as the authoritative generic format\n2. Layer the SQUADRULES customizations (storage, `SHA256SUMS`, routing) on top of\n   that fetched spec\n3. Choose the correct storage location for a skill\n4. Author SKILL.md with valid frontmatter and structure per the current spec\n5. Apply quality gates to descriptions and content\n6. Finalize via local write OR server train (never both)\n7. Produce SHA256SUMS for integrity verification\n"
+        "adapter-migration": "---\nversion: \"5.9.2\"\nslug: adapter-migration\ntitle: Adapter Migration Protocol\n---\n\n# Adapter Migration Protocol\n\nBatch-migrate all adapters in a space to the current structural scheme. Exports\nevery adapter, applies conservative structural transformations, reports changes\nper adapter, and re-trains the conforming subset autonomously.\n\nThis protocol handles structural migrations only — it preserves semantic content\n(steps, intent, examples) while updating format, headings, and contract shapes\nto match the latest SQUADRULES requirements.\n\n## Activation Patterns\n\n**Run this protocol when the user says ANY of:**\n\n- \"migrate all adapters\" / \"batch update adapters\"\n- \"update adapters to latest scheme\" / \"update adapter structure\"\n- \"run structural migration\" / \"migrate protocols\"\n- \"update all my adapters\" / \"fix adapter structure\"\n- \"apply latest adapter format\" / \"restructure adapters\"\n- \"run adapter migration\" / \"migrate to new format\"\n\n**Trigger pattern:** **migrate** / **batch update** / **structural migration** /\n**update format** + (adapters | protocols | all | space).\n\n**Must Never:**\n- Alter semantic content (step text, trigger phrases, examples, intent).\n- Auto-train an adapter without first producing a per-adapter change report.\n- Guess transformations when the adapter structure is ambiguous.\n- Delete adapters or layers during migration.\n- Migrate adapters that already conform (report them as \"no changes needed\").\n\n**Must Always:**\n- Export every adapter before making any changes.\n- Apply only conservative, reversible structural transformations.\n- Flag ambiguous cases for manual review instead of guessing.\n- Produce a per-adapter change report before executing any writes.\n- Preserve the adapter's slug, version, and chain_root fields.\n\n**Good trigger examples:**\n- \"migrate all my personal adapters to the latest format\" → run this protocol\n- \"update all adapters in the team space\" → run this protocol\n- \"we changed the solution scheme, update all adapters\" → run this protocol\n\n**Bad trigger examples:**\n- \"update this one adapter\" → use `author-adapter` with `fix` operation\n- \"create a new adapter\" → use `author-adapter`\n- \"export my adapters\" → use `export` directly\n\n## Preflight Dependencies\n\nBefore running migration, verify readiness:\n\n1. `export` tool is available and callable.\n2. `tune` and `train` tools are available for writes.\n3. Target space is identified (personal or a named group space).\n4. The migration is structural-only (no semantic changes).\n\nIf any tool is unavailable, stop and report the connection blocker with\nremediation guidance.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Export All Adapters\n\nExport every adapter from the target space using bulk export:\n\n1. Call `export` with `all_adapters: true`, `space_name` set to the target\n   space, and `format: skill_tree`.\n2. Record the total adapter count from the response.\n3. For each adapter in the response, extract its slug, URI, and content.\n\nIf the space has no adapters, report this and stop.\n\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"export\",\"arguments\":{\"all_adapters\":true,\"space_name\":\"<space>\",\"format\":\"skill_tree\"}},\"required\":true}}\n```\n\n## Analyze and Transform\n\nFor each exported adapter, perform structural analysis and apply migrations.\n\n### Structural checks (apply all that are needed)\n\n1. **Heading order** — first H2 must be `Activation Patterns`, last H2 must be\n   `Reward Signal`. If missing or out of order, flag for restructuring.\n2. **Contract fences** — all contract JSON blocks must use ` ```json ` (not\n   plain ` ``` `). If plain fences contain contract JSON, convert them.\n3. **Field rename** — any `\"challenge\":` key inside contract JSON blocks must\n   become `\"contract\":`. Apply globally within JSON fences.\n4. **Frontmatter** — must include `slug`. Add `version` if missing. Preserve\n   existing `chain_root` when present.\n5. **Line count** — adapters exceeding 350 lines must be flagged for splitting\n   (do NOT auto-split; report as manual review needed).\n6. **Critic-loop integration** — check whether the adapter includes at least\n   one `critic-loop` chain link. If not, add a recommendation (do NOT\n   auto-add; report as suggestion).\n\n### Transformation rules\n\n- **Conservative only:** If a transformation might change meaning, skip it and\n  flag for manual review.\n- **Reversible:** Every change must be expressible as a diff so it is auditable\n  and reversible.\n- **Idempotent:** Running migration twice on the same adapter produces no\n  additional changes.\n\nFor each adapter, produce:\n- `status`: `needs_changes` | `up_to_date` | `needs_manual_review`\n- `changes`: list of specific transformations applied\n- `warnings`: list of items flagged for manual review\n- `transformed_content`: the full updated markdown (when `needs_changes`)\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":120},\"required\":true}}\n```\n\n## Report Changes\n\nRecord a summary table:\n\n| Adapter slug | Status | Changes | Warnings |\n|-------------|--------|---------|----------|\n| example-adapter | needs_changes | 3 structural fixes | 0 |\n| another-adapter | up_to_date | 0 | 0 |\n| complex-adapter | needs_manual_review | 1 fix | line count exceeds 350 |\n\nFor each adapter with `needs_changes`, show the specific transformations:\n- What was changed (before/after for the affected lines).\n- Why (which structural rule it satisfies).\n\nFor each adapter with `needs_manual_review`, explain what needs human\nattention and why the protocol cannot auto-fix it.\n\nApply the migration autonomously:\n- **Apply all** `needs_changes` adapters.\n- **Leave untouched** every `needs_manual_review` adapter and report it with the\n  reason it cannot be auto-fixed.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":120},\"required\":true}}\n```\n\n## Execute Migration\n\nFor each `needs_changes` adapter, apply the structural changes:\n\n1. For adapters needing only content-level fixes (heading reorder, fence\n   conversion, field rename): use `tune` with the transformed content and\n   the adapter's URI.\n2. For adapters needing structural changes that alter layer count or identity:\n   use `train` with `force_update: true` and the transformed content.\n3. Record the outcome (success or failure) for each adapter.\n\nDo NOT change the adapter's space assignment during migration.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":120},\"required\":true}}\n```\n\n## Verify and Report\n\nAfter executing all migrations:\n\n1. Re-export each migrated adapter to verify structural compliance.\n2. Report final status:\n\n| Metric | Count |\n|--------|-------|\n| Adapters scanned | N |\n| Already up to date | N |\n| Successfully migrated | N |\n| Migration failed | N |\n| Flagged for manual review | N |\n\n3. For each failure, report the error message and suggested fix.\n4. Recommend running `critic-loop` on migrated adapters to verify semantic\n   integrity after structural changes.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Reward Signal\n\nOnly reachable after all prior steps are solved.\n\nThe adapter library in the target space now conforms to the current structural\nscheme. Every adapter has:\n- Correct heading order (Activation Patterns first, Reward Signal last).\n- Proper ` ```json ` contract fences.\n- Current field names (`contract`, not `challenge`).\n- Valid frontmatter with `slug` and optional `version`.\n- Been verified post-migration for structural compliance.\n\nSemantic content (steps, intent, examples, triggers) is preserved unchanged.\n",
+        "author-adapter": "---\nslug: author-adapter\nversion: \"5.9.2\"\ntitle: Author Adapter (Create / Review / Refactor)\n---\n\n\n\n# Author Adapter (Create / Review / Refactor)\n\n> **Note to the agent:** SQUADRULES protocols are interfaces for AI agents — you\n> are the primary user. When you author a protocol, you design behaviour for\n> yourself and others. Write for them: single source of truth (never duplicate\n> rules), explicit over implicit (agents fill ambiguity with hallucination),\n> phases teach modes (each step teaches its cognitive mode), truth over fluency\n> (a protocol that reads well but causes wrong behaviour is worse than one that\n> reads rough but executes correctly).\n\n## Activation Patterns\n\nPreferred entry URI: `squadrules://adapter/author-adapter`. The retired\n`create-new-protocol` slug is a redirect tombstone (see phase-critic pattern).\nIf `forward.authoring` is present, use its operation and target throughout this\nrun. Do not reinterpret update as create or change the target mid-run. This\ncontext describes the requested work; it does not override host permissions.\n\nSQUADRULES authoring lifecycle — create, review, or update adapters / protocols / workflows.\nIn this context, those words refer to the same stored artifact and can be treated\nas synonyms. Supports three operations:\n- **create** — draft and train a new adapter / protocol from scratch.\n- **review** — audit an existing adapter, family, or bundle for structural issues,\n  missing cross-references, chaining gaps, DRY violations, stale guidance, or\n  agent-hostile ambiguity. Read-only.\n- **update** — apply specific corrections to an existing adapter / protocol and\n  save the correction. Also triggered by: edit, fix, modify, change, improve, patch, refactor.\n**Run this protocol when the user says ANY of:**\n- \"create a new SQUADRULES protocol\" / \"create new protocol adapter\"\n- \"register personal SQUADRULES adapter\" / \"register a personal adapter\"\n- \"train adapter into personal\" / \"train protocol into personal\"\n- \"train a workflow\" / \"register a new adapter\" / \"create a new workflow\"\n- \"review protocol\" / \"audit adapters\" / \"check protocol families for gaps\"\n- \"update adapter\" / \"edit adapter\" / \"fix protocol\" / \"modify adapter\"\n- \"patch protocol\" / \"refactor protocol\" / \"change adapter\" / \"improve adapter\"\n- \"create new protocol\" (when `activate` found no match and user confirms)\n**Trigger pattern:** **create** / **train** / **register** / **review** /\n**audit** / **fix** / **update** / **edit** / **modify** / **change** /\n**improve** / **patch** / **refactor** / **correct** +\n(protocol / adapter / workflow).\n**Must Never:**\n- Run when the user only asked to execute an existing protocol.\n- Mutate adapters during a `review` operation.\n- Optimise only for pretty wording; this protocol designs agent behaviour.\n- Treat \"update\", \"edit\", or \"modify an existing adapter\" as **create**.\n**Must Always:**\n- Infer `{operation}` from trigger: create / review / update.\n  When the user says \"update\", \"edit\", \"modify\", or \"fix\" → operation is **update**.\n- Optimise for truth, low ambiguity, explicit sequencing, and user-need alignment.\n- Design or review phase transitions explicitly: discovery, clarification,\n  ideation, planning, execution, validation, review, handoff.\n- Include Activation Patterns as the first H2 and Reward Signal as the last H2\n  in any newly drafted adapter.\n- Enforce the 350-line limit per file.\n**Good trigger examples:**\n- \"Create a new SQUADRULES protocol for code review\" → run this protocol (create)\n- \"No match found; I want to create a new protocol\" → run this protocol (create)\n- \"Review all v4 protocol families for missing cross-references\" → run this protocol (review)\n- \"Update the MR adapter to include a review step\" → run this protocol (update)\n- \"Edit the critic-loop adapter triggers\" → run this protocol (update)\n- \"Refactor the MR adapter to be less ambiguous\" → run this protocol (update)\n**Bad trigger examples:**\n- \"Run the standardise project protocol\" → use activate / forward\n- \"Search for deployment protocol\" → use activate\n- \"Create an MR\" → use the MR adapter, not this protocol\n\n## Preflight Dependencies\n\nBefore running authoring actions, verify dependency and auth readiness for this\nrun:\n1. Required MCP tools are available and reachable: `activate`, `forward`,\n   `reward`, and the operation-dependent tool (`train`, `export`, or `tune`).\n2. Required CLI tools for planned shell steps are installed and callable.\n3. Required auth/session state is valid for the target MCP server.\n\nIf any check fails, attempt AI-assisted remediation automatically (install or\nconfigure the missing tool, refresh auth/session), then re-run preflight. Only\nhard-stop when a required tool or auth genuinely cannot be established\nautonomously; report the concrete blocker and the remediation already attempted.\nDo not continue to intent resolution until preflight passes.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Resolve Intent Autonomously\n\nUse structured `authoring` when provided. For original calls without it, infer\n`{operation}` from the user's trigger — do not stop to ask for confirmation:\n\n| Signal | Operation |\n|---|---|\n| \"create\", \"new\", \"train\", no match from activate | **create** |\n| \"review\", \"audit\", \"check\", \"gaps\", \"cross-references\" | **review** |\n| \"update\", \"edit\", \"fix\", \"modify\", \"change\", \"improve\", \"patch\", \"refactor\", \"add missing\", \"correct\" | **update** |\n\nResolve the target from context without a confirmation prompt: for `create`,\nproceed to author a new adapter; for `review`, select the adapter(s), family, or\nbundle named or implied by the request; for `update`, select the adapter and the\nspecific issue. Record the inferred operation and target, then continue. Escalate\nto the user only when the request is genuinely ambiguous and no reasonable default\nexists.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Gather Requirements\n\n### For `create` — collect details for a new protocol\n**1. Determine the pattern:**\n\n| Signal | Pattern |\n|---|---|\n| One workflow, no variants | **Standalone** — one protocol, all steps inline |\n| Multiple issue types / output formats / media | **Router + Extensions** — router classifies, routes via `activate` |\n| Domain has a decision tree | **Router + Extensions** |\n| Single workflow but exceeds 350 lines or too complex for weaker models | **Chain** — split into sequential adapters linked via `forward` + slug |\n| Reference material needed by steps | Extract to a separate file, not a protocol |\n**2. Collect per protocol:**\n- **Title** — clear, descriptive H1.\n- **User problem** — what real problem does this solve?\n- **Agent behaviour** — what behaviour should this create in the agent?\n- **Mode map** — which steps are for discovery, clarification, ideation,\n  planning, execution, validation, review, or handoff?\n- **Steps** — each H2 must earn its place and end with a challenge.\n- **Challenge type per step** — use the strongest observable contract possible.\n- **Domain reference** — guides / docs the protocol should load.\n- **Existing protocols** — reuse, compose, or extract shared content.\n- **DRY / size check** — extract duplicated content; split if >350 lines.\n- **Chain position** — entry, middle, or exit? What slug does the previous link forward to?\n- **Failure analysis** — where would a weaker agent misread this protocol?\n**3. If Router pattern:** variants, classification questions, forbidden types,\nand which parts stay in the router vs extensions.\n**4. If Chain pattern:** Load `protocol-linking-guide` for full rules\n(`forward` with `squadrules://adapter/protocol-linking-guide`). Collect: chain\nlinks and concerns, minimum number of links, entry point (matched by\n`activate`), and artifacts flowing between links.\n\n### For `review` — audit existing adapters against this checklist\n\nExport target adapter(s). For each adapter, check:\n1. **User-need fit** — does the adapter solve a real user problem, or merely\n   mirror literal wording?\n2. **Mode / phase clarity** — are discovery, clarification, ideation,\n   execution, validation, and review clearly separated?\n3. **Cross-reference completeness** — are all required related adapters linked?\n4. **Adapter handoff gaps** — does it hand off where another adapter should own\n   the work?\n5. **DRY violations** — is policy content duplicated instead of linked?\n6. **Contract coverage** — does every executable H2 have the right contract?\n7. **Truth-first behaviour** — does it reduce guessing, fake certainty, and\n   silent assumption-making?\n8. **Activation pattern accuracy** — do triggers match what users actually say?\n9. **Structure compliance** — first H2 Activation Patterns, last H2 Reward\n   Signal, no duplicate H2s, under 350 lines.\n10. **Sibling consistency** — are equivalent steps present across sibling\n    adapters in the same family?\n11. **Chained adapter families** (when applicable) — extension adapters include\n    `chain_root` and a prerequisite clause pointing at the root; parent adapters\n    use explicit `forward` when the next adapter slug is already known; reserve\n    `activate` for ambiguous runtime discovery (see `protocol-linking-guide`,\n    **Chaining Back and Forward**).\n12. **Critic-loop integration** — does the adapter include critic-loop chain\n    links at major phase boundaries? Does each critic-loop invocation have a\n    FAIL gate shell contract (`grep -qi '^PASS$'` on the verdict file)? Are\n    solution checks restricted to irreversible remote mutations (see\n    `critic-loop-guide`)?\n\n### For `update` — identify the specific issue\n\nExport the target adapter, read the current markdown, identify the exact gap or\nerror, and plan the minimal change. Do not alter unrelated layers.\n\nSummarise gathered requirements or findings.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Draft Markdown\n\n### For `create` — draft new adapter markdown\n\nDraft the full markdown for `train`.\n\n### For `review` — draft findings report\n\nWrite a structured gap report to `$REVIEW_FINDINGS_FILE` (an absolute path\nprovided by the invoking agent or chosen by you under\n`$SQUADRULES_LOCAL_ARTIFACT_DIR` with a session-unique segment). For each finding\ninclude:\n- adapter title\n- gap type\n- severity\n- why the issue matters for AI-agent behaviour\n- specific recommended fix\n\n### For `update` — draft corrected adapter markdown\n\nApply the identified change and show a diff-style summary of what changed.\n\n### Shared drafting rules (all operations)\n**Core SQUADRULES rule — right mode at the right time:**\n\nEvery protocol must help the agent recognise whether the current step is for\nexploration, clarification, ideation, planning, execution, validation, review,\nor handoff. Do not blur those modes.\n**Truth over fluency:**\n\nDesign protocols to reduce guessing and fake certainty. Prefer explicit prompts,\nexplicit stop conditions, explicit uncertainty escalation, and observable\nverification over narrative reassurance.\n**User need over literal phrasing:**\n\nThe protocol should help the agent provide what the user actually needs, not\njust echo the wording used in the request.\n**DRY:**\n\nShared content across protocols must live in one place. If two protocols share\n>50% of their body, extract shared logic.\n\n**350-line maximum per file:**\n\nNo protocol file may exceed 350 lines. If it grows beyond that, split it into\nlinked adapters or extract a reference file.\n\n**Generic-first — create generic, link from detailed:**\n\nCreate protocols from generic to detailed. The generic adapter must stand alone.\nExtensions should contain only the delta.\n\n**Slug convention — deterministic protocol linking:**\n\nEvery protocol gets a short, unique, lowercase-hyphenated `slug`.\n\n**Artifacts:**\n\nStore scripts or config blobs as artifacts via `train` (set `mime`,\n`artifact_name`, `adapter_uri`). Retrieve with `export` using\n`squadrules://artifact/{uuid}`.\n\n**Protocol structure:** H1 title, first H2 Activation Patterns, second H2\nPreflight Dependencies, middle H2s one per step with JSON contract block, last\nH2 Reward Signal. Frontmatter: `slug` (required), `version` (optional),\n`chain_root` (required for mid-chain adapters).\n\n**Challenge types:** Load `challenge-type-guide` for decision rules and JSON\nformats (`forward` with `squadrules://adapter/challenge-type-guide`).\n\n**Critic-loop and mutation gates:** Load `critic-loop-guide` for placement,\nFAIL gate, and solution check rules (`forward` with `squadrules://adapter/critic-loop-guide`).\n\n**If Router pattern:** draft the router and each extension as separate files.\n\nPost the full drafted markdown.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":120},\"required\":true}}\n```\n\n## Critic-Loop Review (create and update only)\n\nFor `create` and `update`: run critic-loop against the drafted markdown. This is an\nautonomous quality loop — the agent owns content, the critic owns quality, and no\nhuman approval is requested at any point.\n\n1. Invoke critic-loop via `forward` with `squadrules://adapter/critic-loop`.\n   Submit the drafted markdown as a `file_set` work submission — write\n   `kind: file_set`, `root: <directory of the draft>`, then the drafted file\n   under `items:` into the handoff pointed to by `$WORK_MANIFEST` — with the\n   slug as `calling_protocol_slug` and \"structural compliance and agent\n   behaviour\" as `verification_target`.\n2. Run the FAIL gate shell contract on the verdict file:\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"head -1 \\\"$VERDICT_FILE\\\" | grep -qi '^PASS$'\",\"timeout_seconds\":5},\"required\":true}}\n```\n\n3. If FAIL: address every finding, then re-invoke critic-loop and re-run the FAIL\n   gate. **Loop automatically until the verdict is PASS** — do not proceed and do\n   not ask the user whether to continue.\n4. If PASS: capture the verdict file path for the `review_evidence` field\n   in the `train` call below.\n\nFor `review`: skip this step (read-only operation).\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Autonomous Review Gate\n\nNo human approval step. The critic-loop PASS verdict from the previous step is the\nsole quality gate; once it is PASS, proceed directly to finalise.\n\nFor `create`: record the drafted adapter slug(s) and the critic-loop verdict, then\ncontinue to `train`.\n\nFor `review`: record the findings and the actions taken, then continue.\n\nFor `update`: record the corrected markdown, the change summary, and the critic\nverdict, then continue.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## FinaliseOperation\n\nFor `create`: call `train` with the drafted markdown and `review_evidence`\nfrom the critic-loop step. Use `force_update: false` unless overwrite was\nexplicitly requested.\n\nFor `review`: do not call `train`. Save the findings report only if requested.\n\nFor `update`: use `tune` with the existing adapter URI, corrected content, and\n`review_evidence` for edits that preserve adapter identity and layer count.\nUse `train` with `force_update: true` only for a required structural replacement\n(such as changing identity/H1 mapping or layer count), preserving the intended\nspace and verifying the resulting identity. Never create a duplicate as fallback.\nUpdate the corresponding repository source when the adapter is repo-managed;\nmake repository edits in the task's isolated worktree.\n\nReport the outcome: adapter URI(s) for create / update, or findings summary for\nreview.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Reward Signal\n\nProtocol complete when:\n- `create` — adapter(s) stored via `train` (with review_evidence) and URI(s) reported\n- `review` — findings report delivered\n- `update` — corrected adapter saved via `tune` (or required structural replacement),\n  read back and verified; repo-managed source updated in the task worktree\n\nA successful result means the resulting SQUADRULES adapter is more truthful,\nphase-aware, agent-readable, and aligned with human–AI harmony.\n",
+        "bulk-insert-adapters-via-cli": "---\nslug: bulk-insert-adapters-via-cli\nversion: \"5.9.2\"\ntitle: Bulk Insert Adapters via SQUADRULES CLI\n---\n\n# Bulk Insert Adapters via SQUADRULES CLI\n\n## Activation Patterns\n\nBatch-register multiple SQUADRULES adapters from a local directory tree using the\n`squadrules train` CLI. Handles directory scanning, validation, space targeting,\nand error recovery for bulk operations.\n\n**Run this protocol when the user says ANY of:**\n\n- \"bulk insert adapters\" / \"bulk train adapters\"\n- \"train all protocols in a directory\"\n- \"batch register adapters from folder\"\n- \"upload all .md files to SQUADRULES\"\n- \"sync local protocols to SQUADRULES\" / \"push protocols to SQUADRULES\"\n- \"train directory recursively\" / \"train --recursive\"\n\n**Trigger pattern:** **bulk** / **batch** / **all** / **directory** / **recursive** +\n(train | insert | register | upload | push | sync) + (adapters | protocols).\n\n**Must Never:**\n\n- Train files without first validating their structure.\n- Overwrite existing adapters without explicit user confirmation (`--force`).\n- Train files that contain secrets or token-like strings without `--allow-sensitive-upload`.\n- Skip reporting partial failures in a batch.\n\n**Must Always:**\n\n- Verify the target directory exists and contains `.md` files.\n- Show the user the file list and target space before executing.\n- Report per-file success/failure after the batch completes.\n- Respect the user's choice of space (personal or group).\n\n**Good trigger examples:**\n\n- \"Train all adapters in squadrules-v4/_personal/\" → run this protocol\n- \"Bulk insert the protocols from my export folder\" → run this protocol\n- \"Push all .md files in this directory to my personal space\" → run this protocol\n\n**Bad trigger examples:**\n\n- \"Train this one protocol\" → use `squadrules train <file>` directly\n- \"Create a new protocol\" → use `author-adapter`\n- \"Export my adapters\" → use `squadrules export`\n\n## Preflight Dependencies\n\nVerify before execution:\n\n1. `squadrules` CLI is installed and callable (`squadrules --version`).\n2. Authentication is valid (`squadrules token` returns a token without error).\n3. Target directory path exists and contains at least one `.md` file.\n4. If a space is specified, confirm it exists via `squadrules spaces`.\n\nIf any check fails, stop and report the issue with remediation guidance.\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"squadrules --version && squadrules token > /dev/null 2>&1 && echo 'auth: ok'\",\"timeout_seconds\":15},\"required\":true}}\n```\n\n## Resolve Scope Autonomously\n\nResolve and record the batch operation details:\n\n1. **Source directory** — absolute path.\n2. **File count** — number of `.md` files found (recursive or flat).\n3. **Target space** — personal (default) or a named group space.\n4. **Force mode** — whether `--force` will be used (overwrites existing).\n5. **Model attribution** — which `--model` value to use.\n\nList the files that will be trained, record the resolved scope, and proceed\nautonomously — no confirmation prompt.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Validate Structure\n\nBefore training, validate each `.md` file against SQUADRULES adapter requirements:\n\n- Has an H1 title.\n- First H2 is \"Activation Patterns\".\n- Last H2 is \"Reward Signal\".\n- Contains at least one fenced `json` block with a top-level `contract` object.\n- Does not exceed 350 lines.\n\nReport any files that fail validation, then proceed autonomously: skip the invalid\nfiles, train the valid subset, and document every skipped file with its validation\nerror and a suggested fix. Do not stop to ask the user.\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"echo 'Validation complete — see output above for results'\",\"timeout_seconds\":30},\"required\":true}}\n```\n\n## Execute Bulk Train\n\nRun the batch train operation using the SQUADRULES CLI:\n\n```\nsquadrules train <directory> --recursive --model <model> --space <space> [--force]\n```\n\nIf the directory contains files that should NOT be trained (README, reference\ndocs), either:\n- train file-by-file for the valid subset, or\n- move non-adapter files out before running `--recursive`\n\nCapture stdout and stderr. The CLI reports per-file status.\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"squadrules train <directory> --recursive --model <model_id> --space <space>\",\"timeout_seconds\":120},\"required\":true}}\n```\n\n## Report Results\n\nSummarise the batch outcome:\n\n| Metric | Value |\n|--------|-------|\n| Files attempted | N |\n| Successfully trained | N |\n| Failed | N |\n| Skipped (invalid) | N |\n\nFor each failure, report:\n- File path\n- Error message\n- Suggested fix\n\nIf all succeeded, confirm adapter URIs are accessible via `squadrules spaces`.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Reward Signal\n\nProtocol complete when:\n- All valid adapter files in the target directory have been trained to the\n  specified space.\n- Per-file results have been reported to the user.\n- Any failures have been documented with remediation guidance.\n\nA successful bulk insert means the user's local protocol library is now\nregistered in SQUADRULES and available for activation by AI agents.\n",
+        "challenge-type-guide": "---\nversion: \"5.9.2\"\nslug: challenge-type-guide\ntitle: Challenge Type Selection Guide\n---\n\n\n\n# Challenge Type Selection Guide\n\nDecision rules, JSON formats, interpreter selection, and anti-patterns for\nchoosing SQUADRULES challenge types. Loaded by protocol-authoring agents during\ndrafting and review.\n\n## Activation Patterns\n\n**Typically invoked by:** `author-adapter` and\n`critic-loop`.\n\n**Can be invoked directly when agent needs:**\n- \"challenge type reference\" / \"which challenge type to use\"\n- \"how to write shell challenges\" / \"challenge format\"\n- \"interpreter selection for challenges\"\n\n**Trigger pattern:** **challenge** + (type | format | selection | guide).\n\n**Must Never:**\n- Be used as an execution protocol.\n- Select `comment` merely because it is easy.\n\n**Must Always:**\n- Be consulted before assigning challenge types to protocol steps.\n- Choose the strongest observable contract available.\n- Match challenge choice to the mode of the step: ask, decide, act, verify, or review.\n\n**Good trigger examples:**\n- drafting a new protocol and need challenge types → load this\n- reviewing challenge type selection in a draft → load this\n\n**Bad trigger examples:**\n- \"Create a new protocol\" → use `author-adapter`\n- \"Review my protocol draft\" → use `critic-loop`\n\n## Core Rules\n\n`comment` is the challenge type of **last resort**. If a step produces any\nobservable artifact — a file, a git state change, an API response, or an exit\ncode — use `shell` or `mcp` instead.\n\n**Mode before challenge type:**\n- **clarify / approve** → `user_input`\n- **call a SQUADRULES / MCP tool** → `mcp`\n- **execute or verify local state** → `shell`\n- **pure reasoning with no observable artifact** → `comment`\n\n### Decision Tree\n\n```\nDoes the step call an MCP tool?\n ├─ YES → Is the step a chain link to another adapter?\n │         ├─ YES → \"mcp\" with tool_name + arguments (forward + slug URI)\n │         └─ NO  → \"mcp\" with tool_name only\n └─ NO → Does the step produce or verify a file, command result, or system state?\n          ├─ YES → \"shell\"\n          └─ NO → Does the step require human approval or choice?\n                   ├─ YES → \"user_input\"\n                   └─ NO → \"comment\" only if there is no stronger observable contract\n```\n\n### Challenge JSON Formats\n\n**shell**\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"<command>\",\"timeout_seconds\":30},\"required\":true}}\n```\n\n**mcp**\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"<tool>\"},\"required\":true}}\n```\n\n**mcp with arguments (chain link)**\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"forward\",\"arguments\":{\"uri\":\"squadrules://adapter/<slug>\"}},\"required\":true}}\n```\n\nUse the `arguments` form when the step's purpose is to invoke a specific\nadapter via `forward`. The server validates that `solution.mcp.arguments`\nis a superset of the contract's `mcp.arguments` (subset/deep matching),\nproving the agent called the correct target — not just any `forward` call.\n\n**user_input**\n```json\n{\"contract\":{\"type\":\"user_input\",\"user_input\":{\"prompt\":\"<specific question>\"},\"required\":true}}\n```\n\n**comment**\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":50},\"required\":true}}\n```\n\n### Solution JSON Formats\n\nEvery solution, regardless of type, follows the same envelope:\n\n```json\n{\n  \"type\": \"<challenge_type>\",\n  \"outcome\": \"success | failure | skipped\",\n  \"evidence\": { /* type-specific proof data */ },\n  \"nonce\": \"<echo from contract>\",\n  \"proof_hash\": \"<echo from contract>\"\n}\n```\n\n**shell solution**\n```json\n{\n  \"type\": \"shell\",\n  \"outcome\": \"success\",\n  \"evidence\": {\n    \"exit_code\": 0,\n    \"stdout\": \"...\",\n    \"stderr\": \"\",\n    \"duration_seconds\": 1.2\n  }\n}\n```\n\n**mcp solution**\n```json\n{\n  \"type\": \"mcp\",\n  \"outcome\": \"success\",\n  \"evidence\": {\n    \"tool_name\": \"activate\",\n    \"arguments\": { \"query\": \"example search\" },\n    \"response\": { \"choices\": [...] }\n  }\n}\n```\n\n**user_input solution**\n```json\n{\n  \"type\": \"user_input\",\n  \"outcome\": \"success\",\n  \"evidence\": {\n    \"confirmation\": \"agreed. proceed\",\n    \"timestamp\": \"2026-05-18T14:49:00Z\"\n  }\n}\n```\n\n**comment solution**\n```json\n{\n  \"type\": \"comment\",\n  \"outcome\": \"success\",\n  \"evidence\": {\n    \"text\": \"Verified all 78 issues now have repo: labels.\"\n  }\n}\n```\n\n### Compatibility\n\nThe server also accepts older solution shapes where data is placed directly\nunder the type key (e.g. `{ \"type\": \"shell\", \"shell\": { \"exit_code\": 0 } }`)\ninstead of inside an `evidence` envelope. Always use the unified envelope with\n`outcome` and `evidence` for new protocols.\n\n## Interpreter Selection\n\n| Task | Use bash | Use perl | Use python3 |\n|---|---|---|---|\n| File exists, tool installed, git state | yes | no | no |\n| Simple content grep | yes | no | no |\n| Multi-line regex | no | yes | no |\n| Paragraph processing | no | yes | no |\n| JSON validation | maybe | yes | yes |\n| YAML / complex data structure checks | no | no | yes |\n\n**Rule of thumb:** if bash requires `while read`, `grep | awk`, or heavy quote\nescaping, rewrite in Perl. If you need imports for data formats, use Python.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Security and Working Directory Rules\n\nUse `$SQUADRULES_LOCAL_ARTIFACT_DIR` as the base directory for local handoff\nartifacts. File paths within it are provided as variables by the invoking agent\nto avoid collisions between parallel sessions.\n\n**Rules:**\n- all file paths in shell challenges reference variables (e.g., `$DRAFT_FILE`,\n  `$VERDICT_FILE`) set by the parent agent — never hardcode filenames\n- the parent agent constructs collision-free paths under\n  `$SQUADRULES_LOCAL_ARTIFACT_DIR` (e.g., with a session ID or random suffix)\n- when using SQUADRULES MCP, the latest `activate` / `forward` / `next` response field `squadrules_local_artifact_dir` is an ordered array of URI hints (`project://<rel>`, `user://<rel>`); pick one (`project://` when you have exactly one project context, otherwise `user://`), resolve on your machine, and `export SQUADRULES_LOCAL_ARTIFACT_DIR=\"<absolute>\"` if your shell does not already define it\n- if the server-returned path is not usable on your local filesystem, resolve\n  locally to `$PROJECT_DIR/.local/squadrules/work` and keep it stable for the run\n- prerequisites create the directory\n- Reward Signal cleans it up\n- never write credentials or secrets to files\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Composition Patterns\n\n**Multi-check compound command**\n- chain with `&&`\n- let the first failure stop execution\n\n**Agent-readable shell status**\n- use when failure can produce no output, especially `test`, quiet `grep`,\n  JSON probes, pipelines, or commands that redirect stderr\n- empty stdout or stderr is not success; success is the real process status\n  reported as `solution.shell.exit_code`\n- print the final status marker to stderr when stdout is machine-readable\n- preserve the original status exactly:\n  ```bash\n  ( set -o pipefail; <command> ); rc=$?; printf '\\nSQUADRULES_SHELL_EXIT=%s\\n' \"$rc\" >&2; exit \"$rc\"\n  ```\n- keep `&&` inside `<command>` for ordered checks; use the final\n  `; rc=$?; ...` trailer only to capture, print, and return the process status\n- do not use `<command> || echo ERROR && false`; shell operators group\n  left-to-right, so that form can fail after a successful command and it loses\n  the original status\n\n**Freeze-then-verify**\n- step N writes checksum\n- step N+1 verifies checksum before publish\n\n**Write-then-grep**\n- subagent writes a verdict file\n- main agent checks the first line for `PASS`\n\n**Phase-batch with critic**\n- batch related TODO items into one phase\n- verify hard artifacts with shell\n- then call `critic-loop` for adversarial review\n\n**Dry-run before execution**\n- dry-run command\n- human review\n- real command\n\n**Chain-link via forward + slug**\n- layer N's contract requires `forward` with a specific adapter slug\n- agent calls `forward` to start the next adapter (new `execution_id`)\n- next adapter runs its own layer chain through to `reward`\n- use when the protocol exceeds 350 lines or needs multi-path routing\n- NOT a replacement for layers — layers remain the primary unit of work\n- example contract:\n  ```json\n  {\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"forward\",\"arguments\":{\"uri\":\"squadrules://adapter/implement-plan\"}},\"required\":true}}\n  ```\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Reward Signal\n\nOnly reachable after all prior steps are solved.\n\nThe agent can now:\n1. pick the correct challenge type for each protocol step\n2. match challenge type to the step's mode\n3. choose the right interpreter\n4. apply working-directory and security rules\n5. preserve real shell statuses for silent checks\n6. use stronger verification patterns instead of weak narrative checks\n",
+        "create-new-protocol": "---\nversion: \"5.9.2\"\nslug: create-new-protocol\ntitle: Create New Protocol (Redirect to Author Adapter)\n---\n\n# Create New Protocol (Redirect to Author Adapter)\n\n`create-new-protocol` was renamed to **`author-adapter`** in 5.6.0. This adapter\nis a redirect tombstone: it exists only so a stored adapter that still chains to\n`squadrules://adapter/create-new-protocol` resolves and is sent to the replacement\ninstead of dangling. It carries no authoring logic. Do not author new adapters\nagainst this slug — use `squadrules://adapter/author-adapter`.\n\n## Activation Patterns\n\n**Typically invoked by:** a stored adapter that still forwards to the retired\n`create-new-protocol` slug.\n\n**Can be invoked directly when agent needs:**\n- \"create new protocol\" — the retired name for the author adapter\n\n**Must Never:**\n- Perform any authoring itself; this tombstone only redirects.\n- Be used as the target of a new adapter chain.\n\n**Must Always:**\n- Send the caller to `squadrules://adapter/author-adapter`, forwarding the same\n  context it received.\n\n## Redirect\n\nForward to the replacement and continue the run there. `author-adapter` is the\ncreate / review / update lifecycle that replaced `create-new-protocol`; its\nintegration rules live in the adapter itself. See ADR 0016 (the rename).\n\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"forward\",\"arguments\":{\"uri\":\"squadrules://adapter/author-adapter\"}},\"required\":true}}\n```\n\n## Reward Signal\n\nThe caller reached `squadrules://adapter/author-adapter`, so the retired slug\nresolved and redirected instead of dangling.\n",
+        "critic-loop-guide": "---\nversion: \"5.9.2\"\nslug: critic-loop-guide\ntitle: Critic Loop Integration and Mutation Gate Guide\n---\n\n# Critic Loop Integration and Mutation Gate Guide\n\nDecision rules for integrating `critic-loop` into adapter protocols: when a\nsolution check (hard verification gate) is required versus when critic-loop\nreview is sufficient, and how to split and batch proofs so reversible work stays\ncheap while irreversible boundaries stay guarded.\n\n## Activation Patterns\n\n**Typically invoked by:** `author-adapter` during adapter drafting, and\nany adapter that includes review or validation phases.\n\n**Can be invoked directly when agent needs:**\n- \"when to add critic loop\" / \"should I use solution check\"\n- \"mutation gate rules\" / \"which actions need hard gates\"\n- \"critic loop vs solution check\" / \"irreversible action rules\"\n- \"add review step to protocol\" / \"where does critic go\"\n\n**Trigger pattern:** **critic loop** / **mutation gate** / **solution check** +\n(integration | when | rules | guide | which | where).\n\n**Must Never:**\n- Be used as an execution protocol.\n- Override the adapter author's judgment on review depth.\n- Recommend solution checks for reversible or local-only actions.\n\n**Must Always:**\n- Distinguish between quality review (critic-loop) and mutation blocking\n  (solution checks).\n- Recommend looping critic-loop until PASS at every major phase boundary, fed the\n  requirement list and bounded by an iteration ceiling.\n- Restrict solution checks to irreversibility boundaries, and batch reversible\n  checkable steps into one strict-conjunction proof.\n\n**Good trigger examples:**\n- drafting a new adapter and deciding where to add review → load this\n- reviewing whether an adapter has the right solution checks → load this\n- \"does my MR step need a solution check?\" → load this\n\n**Bad trigger examples:**\n- \"run the critic loop\" → use `activate` to match `critic-loop`\n- \"create a new protocol\" → use `author-adapter`\n- \"which challenge type for this step?\" → use `challenge-type-guide`\n\n## Core Decision Rule\n\n**Critic-loop** is an adversarial review the calling protocol **loops until it\nreturns PASS** — not a one-shot step. It verifies claims, gathers evidence,\nsearches for contradictions, and checks the work against the original requirement\nlist. Use it for quality and truthfulness review, and whenever a step is\nnon-deterministic or has no objective proof. Run it **before** the work is handed\nto the next step, and before it is presented to the human.\n\n**Solution checks** are per-layer contract verification mechanisms (shell\ncommands, MCP tool calls). Use them ONLY where getting it wrong is expensive or\nimpossible to undo — **irreversible changes on remote systems** and the local\npreconditions that guard them (for example, being on a throwaway worktree/branch\nbefore you commit). Everything else is reversible: give the agent freedom and\nreview with critic-loop instead of adding a hoop.\n\n### What counts as an irreversible remote mutation\n\n| Action | Needs solution check? | Why |\n|--------|----------------------|-----|\n| Create/update merge request | Yes | Remote system state change |\n| Create/update Jira issue | Yes | Remote system state change |\n| Send email | Yes | Cannot unsend |\n| Send Teams message | Yes | Cannot unsend |\n| Create calendar invite | Yes | Sends notifications |\n| Deploy to production | Yes | Irreversible infrastructure change |\n| Delete remote resource | Yes | Irreversible |\n| Push to git remote | Yes | Remote state change |\n| Write/edit local file | No | Use critic-loop instead |\n| Run local tests | No | Read-only / local |\n| Analyze code | No | Read-only |\n| Generate report | No | Local artifact |\n| Read data from API | No | Read-only |\n| Compute / transform data | No | Local operation |\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Proof Splitting: Batch Checkable Steps Into One Proof\n\nSplit proofs by **reversibility cost**, not by step count:\n\n- **One proof per irreversibility boundary.** A boundary is where undoing the next\n  part is expensive or impossible: commit to `main`, mutate the human's active\n  worktree, `git push`, `gh pr create`, deploy, send.\n- **Batch reversible, checkable steps** and verify them together afterward with a\n  single aggregate proof — fewer round-trips, same guarantee.\n- **The aggregate proof must be a strict conjunction** that re-verifies every\n  sub-condition (`A && B && C && echo OK`):\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"test -f \\\"$OUT_A\\\" && test -f \\\"$OUT_B\\\" && grep -q \\\"$EXPECTED\\\" \\\"$OUT_A\\\" && echo OK\",\"timeout_seconds\":10},\"required\":true}}\n```\n\n- **Never let an aggregate proof degrade to `echo \"done\"`.** A proof that asserts\n  nothing is worse than no gate because it looks like one. If you cannot write a\n  real conjunction, the step is non-deterministic → review it with critic-loop\n  instead of faking a proof.\n\n### Guard the boundary before you cross it\n\nThe cheapest proof is the precondition that stops an irreversible mistake before\nit happens — for example, confirm you are on a throwaway worktree and branch (not\n`main`, not the human's active checkout) **before** making changes:\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"test \\\"$(git rev-parse --abbrev-ref HEAD)\\\" != main && git rev-parse --git-common-dir | grep -q worktrees\",\"timeout_seconds\":5},\"required\":true}}\n```\n\n## How to Chain Critic-Loop into an Adapter\n\nUse `forward` + slug to invoke `critic-loop` at phase boundaries. The standard\npattern is a `mcp` contract that requires calling `forward` with the\n`critic-loop` slug:\n\n### After a planning phase\n\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"forward\",\"arguments\":{\"uri\":\"squadrules://adapter/critic-loop\"}},\"required\":true}}\n```\n\n### After an implementation phase\n\nUse the same contract. The critic-loop adapter receives the calling protocol's\ncontext and independently verifies the work.\n\n### What to submit for review\n\nThe submission is the **work itself**, not a summary of it. Pass `work` with a\n`kind`, an `items` list, and the absolute `root` the items resolve against:\n\n| `kind` | `items` contain | Resolved by | Typical work |\n|---|---|---|---|\n| `file_set` | paths (absolute, or relative to `root`) | read each file | docs, generated code, configs |\n| `links` | URLs, `squadrules://` resource URIs | fetch each one | published pages, external references |\n| `git_diff` | `base..head` refs, or empty for the working tree | `git diff` | an unpushed implementation |\n| `pr` | PR numbers or URLs | `gh pr view` + `gh pr diff` | a reviewable pull request |\n| `command_output` | commands to run from `root` | run and capture | migrations, builds, data pulls |\n| `inline` | the text itself | read the manifest | a plan, a decision, a message draft |\n\nRecord `work` in the handoff file pointed to by `$WORK_MANIFEST`, as flat keys —\n`kind:`, `root:`, then `items:` with one item per line — so the precondition\nstays a machine-checkable file test instead of prose:\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"test -f \\\"${WORK_MANIFEST:-}\\\" || test -f \\\"${INPUT_FILE:-}\\\"\",\"timeout_seconds\":3},\"required\":true}}\n```\n\nAnything that cannot be resolved is `verification_blocked` — an item the critic\ncould not read is never treated as an item that passed. `input_file` still works\nand means a one-item `file_set`; prefer `work_manifest` for anything that is not\na single document. A `pr` or `git_diff` submission is judged on the diff and the\ntests it touches, not on the description written next to it.\n\n### Feed it the requirements, then loop with a ceiling\n\nPass the original requirement list in the forward context. A critic that sees only\nthe output can check internal consistency but **cannot detect an omitted\nrequirement** — omission leaves no trace in the artifact — so \"no requirements\nlost\" is only enforceable if the critic is given the list and asserts coverage\nitem by item. Then loop: on FAIL, fix, increment `iteration`, and re-invoke until\nPASS or until `max_iterations` is reached. The ceiling is a hard stop that\nsurfaces the unresolved findings; it prevents a weak agent from thrashing forever.\n\n### Verdict handoff pattern\n\nCritic-loop writes a verdict file. The calling adapter reads it:\n\n1. Critic-loop writes `$VERDICT_FILE` with `PASS`/`FAIL` on line 1.\n2. Calling adapter's next layer reads the verdict file.\n3. If `FAIL` → **hard stop**: do NOT proceed to reward, do NOT ask the user\n   for approval, do NOT continue to the next phase. Address findings first.\n4. If `PASS` → the adapter continues to the next phase.\n\n**FAIL is a hard stop, not an escalation trigger.** A FAIL verdict means the\nwork is not ready. Asking the user \"should I proceed?\" after FAIL bypasses the\nreview. The correct action is to fix the findings and re-invoke critic-loop.\n\n### FAIL gate contract (required after every critic-loop invocation)\n\nEvery adapter that chains critic-loop **must** include a shell contract that\nfails when the verdict is not PASS. This is the mechanical guard that prevents\nweaker agents from proceeding after FAIL:\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"head -1 \\\"$VERDICT_FILE\\\" | grep -qi '^PASS$'\",\"timeout_seconds\":5},\"required\":true}}\n```\n\nIf the critic wrote FAIL, this shell command exits non-zero. The server rejects\nthe solution and the agent cannot advance to the next layer. Protocol wording\nalone does not stop determined agents; this contract does.\n\n## Train/Tune Evidence Requirement\n\n`train` and `tune` enforce critic-loop PASS at the tool level:\n\n- **Adapter (markdown) `train`** requires `review_evidence`: verdict_file path,\n  exit_code (must be 0), and stdout (line 1 must be PASS). Without it, the\n  server rejects the store with `REVIEW_EVIDENCE_REQUIRED`.\n- **`tune` with content** requires the same `review_evidence`. Space-only moves\n  skip this check.\n- **Artifact trains** (non-markdown mime) skip the evidence check.\n\nThis is the tool-level enforcement of the FAIL gate. Even if an agent bypasses\nthe adapter flow and calls `train` directly, the server rejects the store\nwithout PASS evidence. The agent must run critic-loop, capture the verdict\nfile, and pass it as `review_evidence`.\n\n## Mutation Gate Pattern\n\nUnder the AI-ownership model, agents execute autonomously — irreversible remote\nmutations are **not** gated by a human confirmation prompt. Gate them with\nobjective, machine-checkable contracts instead:\n\n### Pre-mutation readiness (objective, no human prompt)\n\nAssert the preconditions with a shell or mcp contract so the action only runs from a\nvalid state — never with a `user_input` \"are you sure?\" prompt:\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"test -n \\\"$TARGET_REPO\\\" && test -n \\\"$TARGET_BRANCH\\\"\",\"timeout_seconds\":5},\"required\":true}}\n```\n\n### Post-mutation verification (objective)\n\nConfirm the mutation actually took effect by reading the remote state back:\n\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"getMergeRequest\",\"arguments\":{\"repo\":\"X\"}},\"required\":true}}\n```\n\nThe guarantee comes from critic-loop (truth of intent) plus these objective\npre/post checks — not from asking a human to approve. Do not add `user_input`\nconfirmation gates for remote mutations.\n\n## Critic-Loop Placement Rules\n\n1. **Loop critic-loop until PASS at every major phase boundary** — after planning,\n   after implementation, after validation — feeding it the requirement list and\n   bounding it with an iteration ceiling.\n2. **Do NOT add critic-loop between every layer** — it is a phase-level review,\n   not a step-level check.\n3. **Put one objective proof at each irreversibility boundary** — remote mutation\n   or the local precondition that guards it: pre-mutation readiness +\n   post-mutation verification, never a human confirmation prompt.\n4. **Batch reversible, checkable steps into one aggregate strict-conjunction\n   proof** instead of one proof per step; never let it degrade to `echo \"done\"`.\n5. **Never replace a boundary proof with critic-loop** — critic-loop reviews truth\n   after the fact; it does not block an irreversible step.\n6. **Never add a proof for purely local, reversible operations** — critic-loop\n   provides sufficient review.\n\n## Adapter Authoring Checklist\n\nWhen drafting a new adapter, apply this checklist:\n\n1. Identify all phase boundaries in the adapter flow.\n2. Add a `critic-loop` chain link at each boundary.\n3. Identify all steps that perform irreversible remote mutations.\n4. Add objective solution checks (pre-mutation readiness + post-action\n   verification) for each — no `user_input` human-confirmation gate.\n5. Verify that no solution checks exist for purely local operations.\n6. Verify that the critic-loop verdict handoff pattern is present.\n7. Verify that a FAIL gate shell contract follows every critic-loop invocation.\n8. Verify that `train`/`tune` calls include `review_evidence` from the critic.\n9. Ensure the adapter's Reward Signal describes what the critic protects.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Reward Signal\n\nOnly reachable after all prior steps are solved.\n\nThe agent can now:\n1. Decide when to use critic-loop versus solution checks\n2. Identify irreversible remote mutations that need hard gates\n3. Chain critic-loop into adapters at the correct phase boundaries\n4. Apply the mutation gate pattern for remote-system actions\n5. Avoid unnecessary solution checks for local or read-only operations\n",
+        "critic-loop": "---\nversion: \"5.9.2\"\nslug: critic-loop\ntitle: Critic Loop\n---\n\n\n\n# Critic Loop\n\nBounded adversarial investigator that the calling protocol **loops until it\nreturns PASS** — not a one-shot review. Receives a work submission (files,\nlinks, a git diff, a pull request, command output, or inline text), the\noriginal requirement list, and the calling protocol's invariants, then\nindependently verifies the submitted work by extracting claims, gathering\nevidence, searching for contradictions, and checking requirement-by-requirement\ncoverage. A FAIL sends the caller back to fix and re-invoke; the loop is bounded\nby an explicit iteration ceiling (see Verdict).\n\n## Activation Patterns\n\n**Typically invoked by:** another protocol at the end of a plan, implement,\nvalidation, or review phase via `forward` with the stored adapter URI\n`squadrules://adapter/critic-loop`.\n\n**Can be invoked directly when agent needs:**\n- \"review phase output\" / \"verify plan\" / \"audit implementation\"\n- \"adversarial review\" / \"critic review\"\n\n**Trigger pattern:** **review** / **verify** / **audit** / **critic** +\n(phase / plan / implementation / output).\n\n**Must Never:**\n- Modify any submitted item or any file other than the verdict path.\n- Trust the executor's assertions without independent evidence.\n- Classify a claim as `verified` based only on absence of contradiction.\n- Keep investigating after a precondition failure that blocks verification.\n\n**Must Always:**\n- Extract claims before investigating.\n- Verify in-scope claims first.\n- Search for contradictory evidence, not only confirming evidence.\n- Check every item in the supplied requirement list for coverage; a missing\n  requirement is a FAIL even when the output is internally consistent.\n- Include confidence in every verdict and failure class in every FAIL verdict.\n- Preserve the boundary between execution and review.\n\n**Good trigger examples:**\n- implement protocol fires this after planning → run this protocol\n- compose protocol fires this after output generation → run this protocol\n\n**Bad trigger examples:**\n- \"Create a new protocol\" → use `author-adapter`\n- \"Implement a feature\" → use an execution protocol, not this one\n\n## Artifact Contract\n\nThis protocol receives:\n\n```text\n{\n  work: {\n    kind: 'file_set' | 'links' | 'git_diff' | 'pr' | 'command_output' | 'inline',\n    items: string[],              // paths | URLs | 'base..head' refs | PR URL/number | commands | text\n    root: string                  // absolute cwd used to resolve relative paths, refs and commands\n  },\n  work_manifest: string,          // absolute path to the handoff file recording `work`\n  input_file: string,             // accepted alias: a one-item work.kind='file_set'\n  calling_protocol_slug: string,\n  verification_target: string,\n  requirements: string[],         // original intent / requirement list to check coverage against\n  context: {\n    operation: string,\n    verdict_file: string,          // absolute path where the verdict will be written\n    iteration: number,             // 1-based loop pass; caller increments after each FAIL\n    max_iterations: number         // hard ceiling; exceeding it is a terminal FAIL\n  }\n}\n```\n\nThe submission is the **work itself**, not an essay about it. Write `work` to\n`$WORK_MANIFEST` as flat keys so the handoff stays machine-checkable:\n`kind:`, `root:`, then `items:` with one item per line. Callers that still pass\nonly `input_file` are handled as `kind: file_set` with that single path; the\nreview rules do not change, only the scope of what is submitted.\n\nThis protocol produces:\n\n```text\n{\n  verdict: \"PASS\" | \"FAIL\",\n  confidence: \"High\" | \"Medium\" | \"Low\",\n  failure_class: string,           // incorrect_claim | verification_blocked | requirement_gap | iteration_ceiling\n  uncovered_requirements: string[],// requirement items lacking positive evidence (empty on PASS)\n  verdict_file: \"{context.verdict_file}\"\n}\n```\n\n## Precondition Check [SUBAGENT]\n\nVerify foundational preconditions before deep investigation. Early-abort if any\nare broken.\n\n**Input:** `$WORK_MANIFEST` (or the older-spelling `$INPUT_FILE`), calling protocol slug, context\n\n**Actions:**\n1. Verify a submission handoff is present: `$WORK_MANIFEST`, or `$INPUT_FILE`\n   when the caller passed no manifest.\n2. Verify the verdict output path is writable (parent directory exists).\n3. Load the calling protocol's Must Never / Must Always sections if possible.\n4. Verify the target state is available for review.\n5. Verify required tools are available for the submission's `kind` (a `pr`\n   submission with no `gh` on the host is `verification_blocked`, not skipped).\n\n**On early-abort:**\n- verdict = `FAIL`\n- failure class = `verification_blocked`\n- confidence = `Low`\n- write focused diagnostics\n- skip all later steps\n\n**Output:** verified preconditions or early-abort diagnostics\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"test -f \\\"${WORK_MANIFEST:-}\\\" || test -f \\\"${INPUT_FILE:-}\\\"\",\"timeout_seconds\":3},\"required\":true}}\n```\n\n## Resolve Submission [SUBAGENT]\n\nTurn the submission into the material under review. What cannot be resolved is\nnever guessed at.\n\n**Input:** `work` recorded in `$WORK_MANIFEST` (or the older-spelling `$INPUT_FILE`),\n`work.root`\n\n**Actions:**\n1. Read `kind`, `root`, `items`. An unknown `kind`, an empty `items` list, or a\n   malformed manifest is `verification_blocked`.\n2. Resolve every item by kind, always from `work.root`:\n   - `file_set` — read each path; relative paths resolve against `root`, and a\n     missing path is `verification_blocked`.\n   - `links` — fetch each URL; a URL that cannot be fetched is\n     `verification_blocked`, not an `unverifiable` claim.\n   - `git_diff` — `git -C \"$root\" diff <base>..<head>`, or the working tree when\n     no range is given; no `git`, no repository, or a bad ref is\n     `verification_blocked`.\n   - `pr` — `gh pr view` plus `gh pr diff` for the number or URL; a missing\n     `gh`, an expired login, or an unreachable host is `verification_blocked`.\n   - `command_output` — run each command from `root` and capture stdout and\n     stderr as the material.\n   - `inline` — the text recorded in the manifest is the material.\n3. Record the resolved inventory before auditing: `kind`, item count, per-item\n   status (`resolved` or `blocked`), and where each item's evidence lives. The\n   audit investigates this inventory and nothing else.\n4. A `pr` or `git_diff` submission is reviewed as a diff: claims are checked\n   against the changed lines and the tests they touch, never against the\n   description written alongside them.\n\n**Output:** resolved work inventory for the audit\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":80},\"required\":true}}\n```\n\n## Audit [SUBAGENT]\n\nPerform bounded adversarial review of the target against the resolved work\nsubmission and invariants.\n\n**Input:** resolved work inventory, invariants, verification target, requirement list, context\n\n**Actions:**\n\n**Step 1 — Extract claims**\nExtract every verifiable claim that matters operationally:\n- workflows, commands, tool calls\n- configuration and environment variable claims\n- architecture claims that imply behaviour\n- guarantees and constraints\n- security, auth, and permission claims\n\n**Step 2 — Investigate with scope discipline**\n1. verify all in-scope claims first\n2. review high-risk claims with maximum depth\n3. expand beyond scope only when contradiction signals, dependencies, or\n   high-risk impact require it\n4. continue reviewing all in-scope claims even after a normal FAIL condition is met;\n   only a precondition failure stops the audit early\n\n**High-risk areas**\n- setup steps and prerequisites\n- CLI commands and flags\n- configuration keys and environment variables\n- authentication, identity, and permissions\n- deployment and release behaviour\n- external publishing actions\n- destructive or irreversible operations\n\n**Step 3 — Gather evidence using the hierarchy**\n\n| Priority | Evidence source |\n|---|---|\n| 1 | source code, config files, schemas, route definitions |\n| 2 | direct runtime verification |\n| 3 | tests |\n| 4 | MCP-queried system state |\n| 5 | external docs, web pages, linked references |\n| 6 | conversational assumption or indirect inference |\n\n**Rules:**\n- higher-priority evidence overrides lower-priority evidence\n- priority 5–6 alone is not enough for `verified`\n- a submitted link or PR description is priority 5 evidence: verify the claim\n  against the fetched content or the actual diff, never against the summary\n\n**Step 4 — Produce claim verdicts**\n\nFor each claim, record:\n- CLAIM\n- EVIDENCE\n- EVIDENCE PRIORITY\n- VERDICT: `verified` / `partially_verified` / `unverifiable` / `incorrect`\n\nA claim must not be marked `verified` without positive supporting evidence.\n\n**Step 5 — Review the phase boundary**\nCheck whether the calling protocol preserved the right mode boundary:\n- was execution reviewed independently?\n- were review and execution kept separate?\n- did the protocol switch to verification when it should have?\n- is escalation needed because certainty was overstated?\n\n**Step 6 — Check requirement coverage**\nFor every item in the supplied `requirements` list, confirm the target addresses\nit with positive evidence and record it as `covered` / `partial` / `missing`. An\nomitted requirement leaves no trace in the output, so coverage can only be judged\nagainst the list, never from the artifact alone. Any `missing` item — or any\n`partial` high-risk item — forces a FAIL with `failure_class: requirement_gap`.\n\n**Output:** structured audit findings for the verdict step\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":120},\"required\":true}}\n```\n\n## Verdict [SUBAGENT]\n\nTurn the audit into a final PASS / FAIL result.\n\n**Input:** audit findings and verdict file path from context (use it as\n`$VERDICT_FILE`)\n\n**Actions:**\n1. Fail if any critical claim is incorrect.\n2. Fail if verification was blocked.\n3. Fail if the evidence base is too weak for high-risk claims.\n4. Fail if any requirement is `missing`, or a high-risk requirement is only\n   `partial` (`failure_class: requirement_gap`); list the uncovered items.\n5. Fail terminally if `context.iteration` exceeds `context.max_iterations`\n   (`failure_class: iteration_ceiling`) so the loop stops instead of thrashing.\n6. Otherwise, pass with the appropriate confidence.\n7. Write `$VERDICT_FILE` so line 1 is `PASS` or `FAIL`,\n   line 2 is `High`, `Medium`, or `Low`, and the remaining lines summarise key\n   findings and any uncovered requirements.\n\n**Verdict contract (calling adapter must obey):**\n- Line 1 is `PASS` → the loop is satisfied; the calling adapter may continue.\n- Line 1 is `FAIL` → the calling adapter **MUST NOT** proceed to reward, **MUST\n  NOT** ask the user for approval, and **MUST NOT** continue. It must address the\n  findings, increment `context.iteration`, and re-invoke critic-loop.\n- `failure_class: iteration_ceiling` → stop looping and surface the unresolved\n  findings; never silently pass. The ceiling bounds the loop so a weak agent\n  cannot thrash forever.\n\n**Output:** final verdict file\n\n```json\n{\"contract\":{\"type\":\"shell\",\"shell\":{\"cmd\":\"test -f \\\"$VERDICT_FILE\\\" && head -1 \\\"$VERDICT_FILE\\\" | grep -qiE '^(PASS|FAIL)$' && sed -n '2p' \\\"$VERDICT_FILE\\\" | grep -qiE '^(High|Medium|Low)$'\",\"timeout_seconds\":5},\"required\":true}}\n```\n\n## Reward Signal\n\nOnly reachable after all prior steps are solved.\n\nThe phase output has been independently challenged and looped until satisfied. The\nresulting verdict is more truthful because it is based on extracted claims,\nexplicit evidence, contradiction search, requirement-by-requirement coverage, and\na clean boundary between execution and review.\n",
+        "phase-critic-guide": "---\nversion: \"5.9.2\"\nslug: phase-critic-guide\ntitle: Phase Critic Guide (Redirect to Critic Loop Guide)\n---\n\n# Phase Critic Guide (Redirect to Critic Loop Guide)\n\n`phase-critic-guide` was renamed to **`critic-loop-guide`** in 5.4.0. This is a\nredirect tombstone kept so the retired slug still resolves. It carries no rules\nof its own — read **`squadrules://adapter/critic-loop-guide`** for the current\ncritic-loop integration, the solution-check-vs-critic decision table, and the\nproof-splitting rules. Do not author against this slug.\n\n## Activation Patterns\n\n**Typically invoked by:** an agent or adapter that still references the retired\n`phase-critic-guide` slug.\n\n**Can be invoked directly when agent needs:**\n- \"phase critic guide\" — the retired name for the critic-loop guide\n\n**Must Never:**\n- Restate the integration rules here; they live in `critic-loop-guide`.\n\n**Must Always:**\n- Point the reader to `squadrules://adapter/critic-loop-guide`.\n\n## Redirect\n\n`critic-loop-guide` is the single home for critic-loop integration and mutation\ngate placement. Activate `squadrules://adapter/critic-loop-guide` and read it\nthere. See ADR 0010 (the rename) and ADR 0012 (why the tombstone is kept).\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":40},\"required\":true}}\n```\n\n## Reward Signal\n\nThe reader was directed to `squadrules://adapter/critic-loop-guide`, so the\nretired slug resolved instead of dangling.\n",
+        "phase-critic": "---\nversion: \"5.9.2\"\nslug: phase-critic\ntitle: Phase Critic (Redirect to Critic Loop)\n---\n\n# Phase Critic (Redirect to Critic Loop)\n\n`phase-critic` was renamed to **`critic-loop`** in 5.4.0. This adapter is a\nredirect tombstone: it exists only so a stored adapter that still chains to\n`squadrules://adapter/phase-critic` resolves and is sent to the replacement\ninstead of dangling. It carries no review logic. Do not author new adapters\nagainst this slug — use `squadrules://adapter/critic-loop`.\n\n## Activation Patterns\n\n**Typically invoked by:** a stored adapter that still forwards to the retired\n`phase-critic` slug.\n\n**Can be invoked directly when agent needs:**\n- \"phase critic\" — the retired name for the critic loop\n\n**Must Never:**\n- Perform a review itself; this tombstone only redirects.\n- Be used as the target of a new adapter chain.\n\n**Must Always:**\n- Send the caller to `squadrules://adapter/critic-loop`, forwarding the same\n  `work` submission (or the older-spelling `input_file`), `requirements`, and\n  `context` it received.\n\n## Redirect\n\nForward to the replacement and continue the run there. `critic-loop` is the\nbounded, requirement-aware review that replaced `phase-critic`; its integration\nrules live in `critic-loop-guide`. See ADR 0010 (the rename) and ADR 0012 (why\nthe tombstone is kept).\n\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"forward\",\"arguments\":{\"uri\":\"squadrules://adapter/critic-loop\"}},\"required\":true}}\n```\n\n## Reward Signal\n\nThe caller reached `squadrules://adapter/critic-loop`, so the retired slug\nresolved and redirected instead of dangling.\n",
+        "protocol-linking-guide": "---\nversion: \"5.9.2\"\nslug: protocol-linking-guide\ntitle: Protocol Linking Guide\n---\n\n\n\n# Protocol Linking Guide\n\nDecision rules for structuring adapter relationships: layers vs chains,\n`activate` vs `forward` + slug, chain-root collapsing, and MCP argument\nvalidation for deterministic cross-protocol linking.\n\n## Activation Patterns\n\n**Typically invoked by:** `author-adapter` and\n`critic-loop`.\n\n**Can be invoked directly when agent needs:**\n- \"layers vs chains\" / \"when to split into multiple adapters\"\n- \"how to link adapters\" / \"cross-protocol linking\"\n- \"activate vs forward\" / \"when to use forward with slug\"\n- \"chain-root collapsing\" / \"how chain_root works\"\n\n**Trigger pattern:** **layers** / **chains** / **linking** / **forward** +\n(slug | adapter | protocol).\n\n**Must Never:**\n- Be used as an execution protocol.\n- Recommend chaining when layers suffice.\n\n**Must Always:**\n- Be consulted before splitting a protocol into multiple adapters.\n- Be consulted before adding `forward` calls or `chain_root` frontmatter.\n\n**Good trigger examples:**\n- \"my protocol is 400 lines, should I split?\" → load this\n- \"how do I link adapter A to adapter B?\" → load this\n- \"what is chain_root?\" → load this\n\n**Bad trigger examples:**\n- \"which challenge type for this step?\" → use `challenge-type-guide`\n- \"create a new protocol\" → use `author-adapter`\n\n## Layers vs Chains\n\n**Layers** (H2 steps within one adapter) are the preferred unit of work. Use\nlayers when all steps fit in one adapter under 350 lines and serve a single\ncohesive concern.\n\n**Chain via `forward` + slug** — use only when:\n- the adapter exceeds 350 lines\n- weaker models cannot follow the full adapter in one pass\n- runtime routing to different adapters is needed (Router pattern)\n- a step is reusable across multiple parent adapters (e.g. `critic-loop`)\n\nChaining is NOT a replacement for layers. A 6-step protocol that fits in 350\nlines should stay as one adapter with 6 H2 layers.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## `activate` vs `forward` + slug\n\n| Situation | Use |\n|---|---|\n| Initial user-intent resolution | `activate` |\n| Target adapter is known at authoring time | `forward` + slug |\n| Target depends on runtime classification the current adapter cannot resolve | `activate` |\n| Linking to the next adapter in a chain | `forward` + slug |\n| Reusable sub-protocol invoked by multiple parents | `forward` + slug |\n\nNever call `activate` just to get a slug you already know — it wastes a\nround-trip and introduces non-determinism.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Chaining Back and Forward\n\nWhen a family of adapters has a root conductor and smaller domain extensions,\ndocument both directions of chaining.\n\n### Chaining back with `chain_root`\n\nExtension adapters should include `chain_root` frontmatter and a prerequisite\nclause:\n\n**Prerequisite:** Start from `<root-adapter-slug>` unless the caller already\nprovided a mission brief, safety gates, authorization boundary, and evidence\nrequirements.\n\nThis protects activation entry points. If a user or weak agent activates a\nmid-chain extension directly, the extension can collapse back to the root unless\nit already received the required parent context.\n\n### Chaining forward with `forward`\n\n`chain_root` does not replace explicit `forward` calls inside the chain.\n\nWhen the next adapter is known at authoring time or after deterministic runtime\nclassification, use `forward` with the target slug. Do not call `activate` just\nto rediscover a slug already known by the current adapter.\n\nForwarded adapters should receive:\n- current mission brief;\n- safety gates;\n- authorization boundary;\n- evidence requirements;\n- user constraints;\n- reason for forwarding.\n\nUse `activate` only when the next adapter must be discovered from an ambiguous\nruntime need.\n\n### Multi-layer conductors and extension URIs\n\nWhen you are executing **`forward`** inside a **multi-layer** adapter (for example\na root conductor), each continuation follows **`next_call`** for the **same**\n`execution_id` until the last layer directs **`reward`**. A layer that mentions\nanother adapter URI only as routing guidance — for example\n`squadrules://adapter/e2e-coding-pr-delivery` — does **not** cause the server to\nswitch executions: the next **`forward`** in that run still advances the\n**current** adapter’s next layer.\n\nTo run an extension adapter, call **`forward`** with\n`squadrules://adapter/<slug>` as a **new** first call (adapter URI; omit\n`solution`). That starts a **separate** execution with its own layers. Common\npattern: complete the conductor with **`reward`**, then **`forward`** to the\nextension slug when coding or PR-shaped work should run under that adapter’s\ncontracts.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## System adapters vs user adapters\n\nBoth system and user-authored adapters chain using slugs in `next_action`:\n\n```text\ncall forward with squadrules://adapter/critic-loop ...\ncall forward with squadrules://adapter/implement-terraform ...\n```\n\nSlugs are globally unique (enforced by `train`), so resolution is\ndeterministic — no scoring, no ambiguity.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## MCP argument validation for chain links\n\nA bare `mcp` contract checks only the tool name:\n\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"forward\"},\"required\":true}}\n```\n\nAn `mcp` contract **with `arguments`** verifies the exact target:\n\n```json\n{\"contract\":{\"type\":\"mcp\",\"mcp\":{\"tool_name\":\"forward\",\"arguments\":{\"uri\":\"squadrules://adapter/code-review-policy\"}},\"required\":true}}\n```\n\nThe server validates that `solution.mcp.arguments` is a superset of the\ncontract's `mcp.arguments` (subset/deep matching). This proves the agent\ncalled `forward` with the correct slug, not just any `forward` call.\n\nUse the `arguments` form whenever a step's purpose is to invoke a specific\nknown adapter.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Chain-root collapsing\n\nWhen a chain has multiple adapters, `activate` might match a mid-chain adapter\ndirectly. Without protection, the agent would start at the wrong step, missing\nprerequisite context gathered by earlier phases.\n\n**`chain_root` frontmatter field** solves this at the server level. Add it to\nevery mid-chain adapter:\n\n```yaml\n---\nslug: implement-plan\nversion: 1.0.0\nchain_root: implement\n---\n```\n\n**Server behaviour:** When `activate` returns a match that has `chain_root`,\nthe server resolves the slug to the root adapter's URI and replaces the\nchoice's `uri` and `next_action` to point there. Multiple mid-chain matches\nfrom the same chain are deduplicated to a single entry. The agent always\nstarts at the chain entry point.\n\n**Defense in depth — protocol-level safeguards:** Each mid-chain adapter\nshould include a **Prerequisites** paragraph in its Activation Patterns\nlisting inputs required from earlier phases and directing the agent to start\nfrom the chain root if those inputs are missing. This catches direct `forward`\ncalls that bypass `activate`.\n\n**Rules:**\n- The chain root adapter must NOT have `chain_root` in its frontmatter.\n- `chain_root` must refer to an existing slug (the chain entry point).\n- `forward` calls within a chain are unaffected — `chain_root` only changes\n  `activate` output routing.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Reward Signal\n\nOnly reachable after all prior steps are solved.\n\nThe agent can now:\n1. decide when to use layers vs chains\n2. choose `activate` vs `forward` + slug correctly\n3. use slug-based linking for all adapters (system and user)\n4. apply MCP argument validation for deterministic chain links\n5. implement `chain_root` collapsing with defense-in-depth safeguards\n6. document chaining back (`chain_root` + prerequisites) and chaining forward\n   (`forward` with known slugs) for root + extension families\n",
+        "refine-search": "---\nversion: \"5.9.2\"\nslug: refine-search\ntitle: Get help refining your search\n---\n\n\n\n# Get help refining your search\n\n**You are an AI agent.** You ran `activate` and got no solid match, or only weak\n/ ambiguous matches. This adapter helps you turn a vague request into a better\nquery so the next `activate` can find the right adapter.\n\nSQUADRULES principle: before acting, understand the user better. The goal is not to\nrepeat the failed phrase with minor edits. The goal is to recover the user's\nreal intent.\n\n## Activation Patterns\n\n**Run this adapter when:**\n- `activate` returned no match.\n- `activate` returned only weak choices.\n- The response included a `refine` choice.\n\n**Trigger pattern:** after `activate` when no strong match exists.\n\n**Must Never:**\n- Run when a strong match already exists.\n- Loop refinement endlessly.\n\n**Must Always:**\n- Infer the real goal, context, and missing constraints from the user's request.\n- Build a more specific query than the one that failed.\n- Run at most once per user request; if the second activation still fails, stop\n  and offer clarification or protocol creation.\n\n**Good trigger examples:**\n- activate returned only \"refine\" / weak matches → run this adapter\n- \"No protocol matched 'do the thing'\" → run this adapter\n\n**Bad trigger examples:**\n- activate returned a strong match → use that match instead\n- user asked \"what adapters exist?\" → use `activate` / `spaces`, not this\n\n## Step 1: Extract what the user actually wants\n\nFrom the user's original message, identify:\n- the real goal\n- relevant context\n- missing constraints\n- likely wording that would help SQUADRULES find the right adapter\n\nWrite your analysis as the solution.\n\n```json\n{\n  \"contract\": {\n    \"type\": \"comment\",\n    \"comment\": { \"min_length\": 60 },\n    \"required\": true\n  }\n}\n```\n\n## Step 2: Build and run a refined activate query\n\nUsing Step 1, construct one refined query with 3–8 specific words. Do not reuse\nthe vague phrase that already failed.\n\nCall `activate` with it.\n\n- **Strong match (score >= 0.5):** pick that choice and `forward`.\n- **Weak matches only:** ask the user to clarify or offer the create path.\n\nDo not loop more than once.\n\n```json\n{\n  \"contract\": {\n    \"type\": \"mcp\",\n    \"mcp\": { \"tool_name\": \"activate\" },\n    \"required\": true\n  }\n}\n```\n\n## Reward Signal\n\nOnly reachable after all prior steps are solved.\n\nThe agent has converted a failed literal search into a more truthful,\nuser-aligned activation attempt.\n",
+        "skill-format-guide": "---\nversion: \"5.9.2\"\nslug: skill-format-guide\ntitle: Skill Format and Local Authoring Guide\n---\n\n\n\n# Skill Format and Local Authoring Guide\n\nDecision rules for authoring SKILL.md files, choosing between local (git) and\nserver (SQUADRULES) storage, and quality gates for skill content. Fetches the\ncurrent Agent Skills format spec (Context7 or agentskills.io) as the\nauthoritative generic format, then layers SQUADRULES customizations on top. Loaded\nby protocol-authoring agents during drafting and review when the output format\nis `skill`.\n\n## Activation Patterns\n\n**Typically invoked by:** `author-adapter` and\n`critic-loop`.\n\n**Can be invoked directly when agent needs:**\n- \"SKILL.md format reference\" / \"how to write a skill\"\n- \"latest SKILL.md spec\" / \"current agentskills format\"\n- \"skill vs adapter\" / \"local skill or SQUADRULES adapter\"\n- \"skill quality gates\" / \"SKILL.md structure\"\n- \"project-level skill\" / \"where to put a skill\"\n\n**Trigger pattern:** **skill** + (format | structure | guide | quality | local | spec).\n\n**Must Never:**\n- Be used as an execution protocol.\n- Recommend storing a skill in both git AND SQUADRULES server simultaneously.\n- Confuse SKILL.md (agent instruction file) with protocol markdown (adapter).\n- Hardcode the generic SKILL.md format from memory when the current spec is\n  reachable via Context7 or agentskills.io.\n\n**Must Always:**\n- Be consulted before writing any SKILL.md file.\n- Fetch the current Agent Skills spec before authoring or reviewing generic\n  format, and apply SQUADRULES customizations after it.\n- Enforce single source of truth: each skill lives in exactly one place.\n- Match storage location to the skill's scope and discoverability needs.\n\n**Good trigger examples:**\n- drafting a new skill and need format rules → load this\n- reviewing a SKILL.md for quality → load this\n- deciding local vs server for a skill → load this\n\n**Bad trigger examples:**\n- \"which challenge type for this step?\" → use `challenge-type-guide`\n- \"create a new protocol\" → use `author-adapter`\n\n## Storage Decision\n\nEvery skill has ONE home. Choose at authoring time. Never both.\n\n| Scope | Storage | Discovery | Source of Truth |\n|---|---|---|---|\n| Project-specific (deploy, test, release) | Git: `.agents/skills/{name}/` or `.cursor/skills/{name}/` | IDE host scans description field | Git repo |\n| Personal cross-project (universal) | SQUADRULES server via `train` | `activate` embedding search | SQUADRULES server |\n| Team/group shared | SQUADRULES server (group space) | `activate` | SQUADRULES server |\n\n### Decision Tree\n\n```\nIs this skill specific to ONE project's codebase?\n ├─ YES → Does it reference repo files, paths, or project-specific tools?\n │         ├─ YES → LOCAL (git)\n │         └─ NO  → Could it help in other projects?\n │                   ├─ YES → SERVER (SQUADRULES)\n │                   └─ NO  → LOCAL (git)\n └─ NO → SERVER (SQUADRULES)\n```\n\n### Local Storage Paths\n\n| Host | Path | Scope |\n|---|---|---|\n| Cursor IDE (project) | `.cursor/skills/{name}/SKILL.md` | Repo-scoped, git-controlled |\n| Cursor IDE (personal) | `~/.cursor/skills/{name}/SKILL.md` | User-wide, all projects |\n| Claude Code (project) | `.agents/skills/{name}/SKILL.md` | Repo-scoped, git-controlled |\n| Claude Code (personal) | `~/.agents/skills/{name}/SKILL.md` | User-wide, all projects |\n\n**Never** create skills in `~/.cursor/skills-cursor/` — reserved for system.\n\n### Promotion and Demotion\n\n**Local → Server (skill graduates to universal):**\n1. Read existing SKILL.md\n2. Optionally wrap in protocol structure (Activation Patterns, contracts)\n3. `train` to SQUADRULES server\n4. Delete local copy or mark deprecated\n5. Git commit the deletion\n\n**Server → Local (adapter becomes project-specific):**\n1. `export` with `format: skill_zip` or `format: markdown`\n2. Write to `.agents/skills/{slug}/SKILL.md`\n3. Optionally `delete` from server\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Fetch the Current Skill Format Spec\n\nDo NOT rely on a frozen copy of the SKILL.md format. The Agent Skills format\nevolves (new frontmatter fields, directory conventions, size guidance). Before\nauthoring or reviewing a SKILL.md, fetch the **current** specification and treat\nit as authoritative for the generic format. The SQUADRULES customizations in the\nsections *after* this one layer on top of that generic spec.\n\n**Authoritative source (fetch fresh — do not guess):**\n\n1. **Context7 (preferred):** query the Agent Skills docs library for the\n   SKILL.md format. Use one of these library IDs directly (skip\n   `resolve-library-id`):\n   - `/llmstxt/agentskills_io_llms-full_txt` — full spec text (best coverage)\n   - `/websites/agentskills_io` — the agentskills.io site docs\n   Example query: \"SKILL.md frontmatter fields, directory structure, size limits\".\n2. **URL fallback:** if Context7 is unavailable or returns nothing usable,\n   fetch `https://agentskills.io/specification`. Use\n   `https://agentskills.io/llms.txt` as the documentation index to discover\n   related pages.\n\n**What to extract from the fetched spec (do not hardcode from memory):**\n- Required and optional YAML frontmatter fields and their constraints\n  (for example `name`, `description`, and any newer fields such as `license`,\n  `compatibility`, `metadata`, `allowed-tools`).\n- Directory structure and conventional subdirectory names\n  (for example `scripts/`, `references/`, `assets/`).\n- Body content recommendations and section guidance.\n- Size / progressive-disclosure guidance (line and token targets).\n- Any spec-provided validation tooling (for example `skills-ref validate`).\n\n**Rules:**\n- Apply the fetched spec's constraints exactly for the generic format.\n- If the fetch fails on BOTH Context7 and the URL, STOP and tell the user the\n  spec is unreachable — do not fabricate field lists or limits from memory.\n- Record which source and (if available) which version/date you fetched, so the\n  authoring decision is auditable.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## SQUADRULES Customizations (apply after the generic spec)\n\nEverything below is SQUADRULES-specific and layers on top of the fetched Agent\nSkills spec. When the generic spec and these rules disagree on generic format,\nfollow the spec; these rules add SQUADRULES storage, integrity, and routing\nbehavior the generic spec does not cover.\n\n### SQUADRULES additions to structure\n\n- **`SHA256SUMS`** — required for SQUADRULES-exported skill bundles (GNU\n  `sha256sum` format, paths relative to the skill dir). This is a SQUADRULES\n  integrity requirement, not part of the generic Agent Skills spec.\n- **`disable-model-invocation`** — when the host supports it, SQUADRULES-authored\n  skills default this to `true` (explicit load only) unless the skill is meant\n  to auto-trigger. Only add fields the fetched spec actually recognizes.\n- **Reference depth** — keep references one level deep (SKILL.md → reference\n  file, never deeper), consistent with the spec's progressive-disclosure model.\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Quality Gates\n\n### Description Quality\n\nThe description is the primary discovery mechanism. It must:\n\n1. Be written in **third person** (not \"I can help\" or \"you can use\")\n2. State **WHAT** the skill does (specific capabilities)\n3. State **WHEN** to use it (trigger scenarios, file patterns, keywords)\n4. Include **trigger terms** that match real user language\n5. Avoid vague words: \"helps with\", \"assists\", \"various\"\n\n**Good:**\n```yaml\ndescription: >-\n  Validate and publish Confluence pages managed as local markdown via Mark CLI.\n  Use when the user asks to dry-run, validate, publish, or sync a Confluence\n  page, or when working with files under confluence/ that have Mark metadata.\n```\n\n**Bad:**\n```yaml\ndescription: Helps with Confluence stuff.\n```\n\n### Content Quality\n\n| Check | Rule |\n|---|---|\n| Consistent terminology | One term per concept throughout |\n| No time-sensitive info | No \"before August 2025\" conditions |\n| Concrete examples | Real inputs/outputs, not abstract |\n| Actionable instructions | Agent knows what to DO, not just what exists |\n| Default tool choice | One recommended tool, escape hatch for alternatives |\n| No Windows paths | Forward slashes only |\n\n### Degree of Freedom\n\nMatch instruction specificity to the task's fragility:\n\n| Level | When | Example |\n|---|---|---|\n| High (text guidelines) | Multiple valid approaches | Code review guidelines |\n| Medium (templates/pseudocode) | Preferred pattern, acceptable variation | Report generation |\n| Low (exact scripts) | Fragile operations, consistency critical | DB migrations |\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Finalisation Paths\n\n### Path A: Local Write (project-level skill)\n\nWhen `{target}=local`:\n\n1. Determine output path from scope:\n   - Project Cursor: `.cursor/skills/{name}/SKILL.md`\n   - Project Claude: `.agents/skills/{name}/SKILL.md`\n   - Personal: `~/.cursor/skills/{name}/SKILL.md` or `~/.agents/skills/{name}/`\n2. Create directory if needed\n3. Write SKILL.md with frontmatter and body\n4. Generate `SHA256SUMS` (GNU sha256sum format, paths relative to skill dir)\n5. Write any reference files and scripts\n6. Verify: `test -f \"{path}/SKILL.md\" && wc -l \"{path}/SKILL.md\"`\n7. Report path and line count to user\n\nDo NOT call `train`. The skill lives only in git.\n\n### Path B: Server Train (SQUADRULES-routable adapter)\n\nWhen `{target}=server`:\n\n1. Wrap skill content in protocol markdown if needed:\n   - Add Activation Patterns (first H2)\n   - Add contract blocks per layer\n   - Add Reward Signal (last H2)\n2. Call `train` with full markdown\n3. Verify adapter URI returned\n4. Report URI and slug to user\n\nDo NOT write to local disk. The adapter lives only in SQUADRULES.\n\n### Path C: Hybrid Authoring (skill that is also an adapter)\n\nWhen `{target}=hybrid` (rare — use only when explicitly requested):\n\n1. Author as a SQUADRULES protocol (Activation Patterns, contracts, Reward Signal)\n2. `train` to server\n3. `export` with `format: skill_zip` to produce local SKILL.md bundle\n4. The exported SKILL.md is a **read-only derived artifact**, not a source of truth\n5. Document in the SKILL.md header that it was exported from SQUADRULES\n\n```json\n{\"contract\":{\"type\":\"comment\",\"comment\":{\"min_length\":30},\"required\":true}}\n```\n\n## Reward Signal\n\nOnly reachable after all prior steps are solved.\n\nThe agent can now:\n1. Fetch the current Agent Skills spec (Context7 or agentskills.io) instead of\n   relying on a frozen copy, and apply it as the authoritative generic format\n2. Layer the SQUADRULES customizations (storage, `SHA256SUMS`, routing) on top of\n   that fetched spec\n3. Choose the correct storage location for a skill\n4. Author SKILL.md with valid frontmatter and structure per the current spec\n5. Apply quality gates to descriptions and content\n6. Finalize via local write OR server train (never both)\n7. Produce SHA256SUMS for integrity verification\n"
     }
 };
 /**