@squadrules/mcp 4.8.6

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

@@ -0,0 +1,140 @@
+# Bundled meta-protocols
+
+This directory contains the bundled KAIROS-internal adapters and policy
+documents that are injected into the Kairos app space at boot.
+
+<!-- kairos-doc-keep: directory-local authority for the shipped meta-protocol bundle (slugs, versions, chain-linking rules); source of truth for these files, not a restatement of wiki Core Concepts -->
+
+Version: **4.2.0**
+
+## Philosophy
+
+KAIROS exists for AI agents and for human–AI harmony.
+
+The bundle is designed to help agents recognise the right mode at the right
+time: discovery, clarification, ideation, planning, execution, validation,
+review, and handoff. The bundle prefers truth, explicit sequencing, and
+observable verification over polished but weak wording.
+
+Bundled mem resources that intentionally use **protocol** and **adapter** as
+synonyms. Prefer **adapter** in new copy when you are not mirroring user-facing trigger phrases.
+
+## Protocols
+
+| File | Slug | Purpose |
+|------|------|---------|
+| [create-new-protocol.md](create-new-protocol.md) | `create-new-protocol` | Authoring adapter — create, review, or refactor KAIROS protocols |
+| [refine-search.md](refine-search.md) | `refine-search` | Refine search — recover user intent after failed `activate` |
+| [phase-critic.md](phase-critic.md) | `phase-critic` | Phase-boundary adversarial review — verify claims against evidence |
+| [adapter-migration.md](adapter-migration.md) | `adapter-migration` | Batch structural migration — update all adapters to latest scheme |
+
+### Linked authoring flow
+
+```text
+create-new-protocol (Author) → forward(kairos://adapter/phase-critic) → phase-critic (Phase-Critic Review) → train (with review_evidence)
+```
+
+## Reference Documents
+
+| File | Slug | Purpose |
+|------|------|---------|
+| [challenge-type-guide.md](challenge-type-guide.md) | `challenge-type-guide` | Challenge type selection, interpreter choice, and stronger verification patterns |
+| [protocol-linking-guide.md](protocol-linking-guide.md) | `protocol-linking-guide` | Layers vs chains, `activate` vs `forward` + slug, chaining back/forward, multi-layer conductor vs extension URI, chain-root collapsing, MCP argument validation |
+| [phase-critic-guide.md](phase-critic-guide.md) | `phase-critic-guide` | Phase-critic integration rules, mutation gates, solution check vs critic decision table |
+
+## Cross-Protocol Linking
+
+### Layers vs chains
+
+**Layers (H2 steps within one adapter)** are the preferred unit of work. Use
+layers when all steps fit in one adapter under 350 lines and serve a single
+cohesive concern.
+
+**Chain via `forward` + slug** — use when:
+
+- the adapter exceeds 350 lines
+- weaker models cannot follow the full adapter in one pass
+- runtime routing to different adapters is needed (Router pattern)
+- a step is reusable across multiple parent adapters (e.g. `phase-critic`)
+
+Chaining is NOT a replacement for layers. A 6-step protocol that fits in 350
+lines should stay as one adapter with 6 H2 layers.
+
+### How forward + slug works
+
+Both system and user-authored adapters chain using slugs in `next_action`:
+
+```text
+call forward with kairos://adapter/phase-critic and no solution to start the phase critic
+call forward with kairos://adapter/implement-terraform and no solution to start this adapter
+```
+
+Slugs are globally unique (enforced by `train`), so resolution is
+deterministic — no scoring, no ambiguity.
+
+### Verifying chain links with MCP argument checks
+
+A bare `mcp` contract checks only the tool name:
+
+```json
+{"contract":{"type":"mcp","mcp":{"tool_name":"forward"},"required":true}}
+```
+
+An `mcp` contract **with `arguments`** verifies the exact target:
+
+```json
+{"contract":{"type":"mcp","mcp":{"tool_name":"forward","arguments":{"uri":"kairos://adapter/code-review-policy"}},"required":true}}
+```
+
+The server validates that `solution.mcp.arguments` is a superset of the
+contract's `mcp.arguments` (subset/deep matching). This proves the agent
+called `forward` with the correct slug, not just any `forward` call.
+
+### When to use `activate` vs `forward` + slug
+
+| Situation | Use |
+|---|---|
+| Initial user-intent resolution | `activate` |
+| Target adapter is known at authoring time | `forward` + slug |
+| Target depends on runtime classification the current adapter cannot resolve | `activate` |
+| Linking to the next adapter in a chain | `forward` + slug |
+| Reusable sub-protocol invoked by multiple parents | `forward` + slug |
+
+Never call `activate` just to get a slug you already know — it wastes a
+round-trip and introduces non-determinism.
+
+### Chain-root collapsing
+
+When a chain has multiple adapters, `activate` might match a mid-chain adapter
+directly. Without protection, the agent would start at the wrong step, missing
+prerequisite context gathered by earlier phases.
+
+**`chain_root` frontmatter field** solves this at the server level. Add it to
+every mid-chain adapter:
+
+```yaml
+---
+slug: implement-plan
+version: 1.0.0
+chain_root: implement
+---
+```
+
+**Server behaviour:** When `activate` returns a match that has `chain_root`,
+the server resolves the slug to the root adapter's URI and replaces the
+choice's `uri` and `next_action` to point there. Multiple mid-chain matches
+from the same chain are deduplicated to a single entry. The agent always
+starts at the chain entry point.
+
+**Defense in depth — protocol-level safeguards:** In addition to server-side
+collapsing, each mid-chain adapter should include a **Prerequisites** paragraph
+in its Activation Patterns section that lists required inputs from earlier
+phases and directs the agent to start from the chain root if those inputs are
+missing. This catches direct `forward` calls that bypass `activate`.
+
+**Rules:**
+
+- The chain root adapter itself must NOT have `chain_root` in its frontmatter.
+- `chain_root` must refer to an existing slug (the chain entry point).
+- `forward` calls within a chain are unaffected — `chain_root` only changes
+  `activate` output routing.

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

@@ -0,0 +1,202 @@
+---
+version: "4.8.6"
+slug: adapter-migration
+title: Adapter Migration Protocol
+---
+
+# Adapter Migration Protocol
+
+Batch-migrate all adapters in a space to the current structural scheme. Exports
+every adapter, applies conservative structural transformations, reports changes
+per adapter, and re-trains only after user approval.
+
+This protocol handles structural migrations only — it preserves semantic content
+(steps, intent, examples) while updating format, headings, and contract shapes
+to match the latest KAIROS requirements.
+
+## Activation Patterns
+
+**Run this protocol when the user says ANY of:**
+
+- "migrate all adapters" / "batch update adapters"
+- "update adapters to latest scheme" / "update adapter structure"
+- "run structural migration" / "migrate protocols"
+- "update all my adapters" / "fix adapter structure"
+- "apply latest adapter format" / "restructure adapters"
+- "run adapter migration" / "migrate to new format"
+
+**Trigger pattern:** **migrate** / **batch update** / **structural migration** /
+**update format** + (adapters | protocols | all | space).
+
+**Must Never:**
+- Alter semantic content (step text, trigger phrases, examples, intent).
+- Auto-train without showing the user a change report first.
+- Guess transformations when the adapter structure is ambiguous.
+- Delete adapters or layers during migration.
+- Migrate adapters that already conform (report them as "no changes needed").
+
+**Must Always:**
+- Export every adapter before making any changes.
+- Apply only conservative, reversible structural transformations.
+- Flag ambiguous cases for manual review instead of guessing.
+- Show a per-adapter change report before executing any writes.
+- Preserve the adapter's slug, version, and chain_root fields.
+
+**Good trigger examples:**
+- "migrate all my personal adapters to the latest format" → run this protocol
+- "update all adapters in the team space" → run this protocol
+- "we changed the solution scheme, update all adapters" → run this protocol
+
+**Bad trigger examples:**
+- "update this one adapter" → use `create-new-protocol` with `fix` operation
+- "create a new adapter" → use `create-new-protocol`
+- "export my adapters" → use `export` directly
+
+## Preflight Dependencies
+
+Before running migration, verify readiness:
+
+1. `export` tool is available and callable.
+2. `tune` and `train` tools are available for writes.
+3. Target space is identified (personal or a named group space).
+4. User understands this is a structural-only migration.
+
+If any tool is unavailable, stop and ask the user to fix the connection.
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":80},"required":true}}
+```
+
+## Export All Adapters
+
+Export every adapter from the target space using bulk export:
+
+1. Call `export` with `all_adapters: true`, `space_name` set to the target
+   space, and `format: skill_tree`.
+2. Record the total adapter count from the response.
+3. For each adapter in the response, extract its slug, URI, and content.
+
+If the space has no adapters, report this and stop.
+
+```json
+{"contract":{"type":"mcp","mcp":{"tool_name":"export","arguments":{"all_adapters":true,"space_name":"<space>","format":"skill_tree"}},"required":true}}
+```
+
+## Analyze and Transform
+
+For each exported adapter, perform structural analysis and apply migrations.
+
+### Structural checks (apply all that are needed)
+
+1. **Heading order** — first H2 must be `Activation Patterns`, last H2 must be
+   `Reward Signal`. If missing or out of order, flag for restructuring.
+2. **Contract fences** — all contract JSON blocks must use ` ```json ` (not
+   plain ` ``` `). If plain fences contain contract JSON, convert them.
+3. **Field rename** — any `"challenge":` key inside contract JSON blocks must
+   become `"contract":`. Apply globally within JSON fences.
+4. **Frontmatter** — must include `slug`. Add `version` if missing. Preserve
+   existing `chain_root` when present.
+5. **Line count** — adapters exceeding 350 lines must be flagged for splitting
+   (do NOT auto-split; report as manual review needed).
+6. **Phase-critic integration** — check whether the adapter includes at least
+   one `phase-critic` chain link. If not, add a recommendation (do NOT
+   auto-add; report as suggestion).
+
+### Transformation rules
+
+- **Conservative only:** If a transformation might change meaning, skip it and
+  flag for manual review.
+- **Reversible:** Every change must be expressible as a diff so the user can
+  reject individual changes.
+- **Idempotent:** Running migration twice on the same adapter produces no
+  additional changes.
+
+For each adapter, produce:
+- `status`: `needs_changes` | `up_to_date` | `needs_manual_review`
+- `changes`: list of specific transformations applied
+- `warnings`: list of items flagged for manual review
+- `transformed_content`: the full updated markdown (when `needs_changes`)
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":120},"required":true}}
+```
+
+## Report Changes
+
+Present a summary table to the user:
+
+| Adapter slug | Status | Changes | Warnings |
+|-------------|--------|---------|----------|
+| example-adapter | needs_changes | 3 structural fixes | 0 |
+| another-adapter | up_to_date | 0 | 0 |
+| complex-adapter | needs_manual_review | 1 fix | line count exceeds 350 |
+
+For each adapter with `needs_changes`, show the specific transformations:
+- What was changed (before/after for the affected lines).
+- Why (which structural rule it satisfies).
+
+For each adapter with `needs_manual_review`, explain what needs human
+attention and why the protocol cannot auto-fix it.
+
+Ask the user to choose:
+- **Apply all** — train all `needs_changes` adapters.
+- **Select individually** — choose which adapters to update.
+- **Abort** — cancel the migration without changes.
+
+```json
+{"contract":{"type":"user_input","user_input":{"prompt":"Review the migration report above. Choose: apply all, select individually, or abort."},"required":true}}
+```
+
+## Execute Migration
+
+For each approved adapter, apply the structural changes:
+
+1. For adapters needing only content-level fixes (heading reorder, fence
+   conversion, field rename): use `tune` with the transformed content and
+   the adapter's URI.
+2. For adapters needing structural changes that alter layer count or identity:
+   use `train` with `force_update: true` and the transformed content.
+3. Record the outcome (success or failure) for each adapter.
+
+Do NOT change the adapter's space assignment during migration.
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":120},"required":true}}
+```
+
+## Verify and Report
+
+After executing all approved migrations:
+
+1. Re-export each migrated adapter to verify structural compliance.
+2. Report final status:
+
+| Metric | Count |
+|--------|-------|
+| Adapters scanned | N |
+| Already up to date | N |
+| Successfully migrated | N |
+| Migration failed | N |
+| Flagged for manual review | N |
+
+3. For each failure, report the error message and suggested fix.
+4. Recommend running `phase-critic` on migrated adapters to verify semantic
+   integrity after structural changes.
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":80},"required":true}}
+```
+
+## Reward Signal
+
+Only reachable after all prior steps are solved.
+
+The adapter library in the target space now conforms to the current structural
+scheme. Every adapter has:
+- Correct heading order (Activation Patterns first, Reward Signal last).
+- Proper ` ```json ` contract fences.
+- Current field names (`contract`, not `challenge`).
+- Valid frontmatter with `slug` and optional `version`.
+- Been verified post-migration for structural compliance.
+
+Semantic content (steps, intent, examples, triggers) is preserved unchanged.

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

@@ -0,0 +1,152 @@
+---
+slug: bulk-insert-adapters-via-cli
+version: "4.8.6"
+title: Bulk Insert Adapters via KAIROS CLI
+---
+
+# Bulk Insert Adapters via KAIROS CLI
+
+## Activation Patterns
+
+Batch-register multiple KAIROS adapters from a local directory tree using the
+`kairos train` CLI. Handles directory scanning, validation, space targeting,
+and error recovery for bulk operations.
+
+**Run this protocol when the user says ANY of:**
+
+- "bulk insert adapters" / "bulk train adapters"
+- "train all protocols in a directory"
+- "batch register adapters from folder"
+- "upload all .md files to KAIROS"
+- "sync local protocols to KAIROS" / "push protocols to KAIROS"
+- "train directory recursively" / "train --recursive"
+
+**Trigger pattern:** **bulk** / **batch** / **all** / **directory** / **recursive** +
+(train | insert | register | upload | push | sync) + (adapters | protocols).
+
+**Must Never:**
+
+- Train files without first validating their structure.
+- Overwrite existing adapters without explicit user confirmation (`--force`).
+- Train files that contain secrets or token-like strings without `--allow-sensitive-upload`.
+- Skip reporting partial failures in a batch.
+
+**Must Always:**
+
+- Verify the target directory exists and contains `.md` files.
+- Show the user the file list and target space before executing.
+- Report per-file success/failure after the batch completes.
+- Respect the user's choice of space (personal or group).
+
+**Good trigger examples:**
+
+- "Train all adapters in kairos-v4/_personal/" → run this protocol
+- "Bulk insert the protocols from my export folder" → run this protocol
+- "Push all .md files in this directory to my personal space" → run this protocol
+
+**Bad trigger examples:**
+
+- "Train this one protocol" → use `kairos train <file>` directly
+- "Create a new protocol" → use `create-new-protocol`
+- "Export my adapters" → use `kairos export`
+
+## Preflight Dependencies
+
+Verify before execution:
+
+1. `kairos` CLI is installed and callable (`kairos --version`).
+2. Authentication is valid (`kairos token` returns a token without error).
+3. Target directory path exists and contains at least one `.md` file.
+4. If a space is specified, confirm it exists via `kairos spaces`.
+
+If any check fails, stop and report the issue with remediation guidance.
+
+```json
+{"contract":{"type":"shell","shell":{"cmd":"kairos --version && kairos token > /dev/null 2>&1 && echo 'auth: ok'","timeout_seconds":15},"required":true}}
+```
+
+## Confirm Scope
+
+Present the batch operation details to the user:
+
+1. **Source directory** — absolute path.
+2. **File count** — number of `.md` files found (recursive or flat).
+3. **Target space** — personal (default) or a named group space.
+4. **Force mode** — whether `--force` will be used (overwrites existing).
+5. **Model attribution** — which `--model` value to use.
+
+List the files that will be trained and ask for confirmation.
+
+```json
+{"contract":{"type":"user_input","user_input":{"prompt":"Confirm batch scope: directory, file list, target space, force mode, and model ID"},"required":true}}
+```
+
+## Validate Structure
+
+Before training, validate each `.md` file against KAIROS adapter requirements:
+
+- Has an H1 title.
+- First H2 is "Activation Patterns".
+- Last H2 is "Reward Signal".
+- Contains at least one fenced `json` block with a top-level `contract` object.
+- Does not exceed 350 lines.
+
+Report any files that fail validation. Ask user whether to:
+- skip invalid files and proceed with valid ones
+- abort and fix issues first
+
+```json
+{"contract":{"type":"shell","shell":{"cmd":"echo 'Validation complete — see output above for results'","timeout_seconds":30},"required":true}}
+```
+
+## Execute Bulk Train
+
+Run the batch train operation using the KAIROS CLI:
+
+```
+kairos train <directory> --recursive --model <model> --space <space> [--force]
+```
+
+If the directory contains files that should NOT be trained (README, reference
+docs), either:
+- train file-by-file for the valid subset, or
+- move non-adapter files out before running `--recursive`
+
+Capture stdout and stderr. The CLI reports per-file status.
+
+```json
+{"contract":{"type":"shell","shell":{"cmd":"kairos train <directory> --recursive --model <model_id> --space <space>","timeout_seconds":120},"required":true}}
+```
+
+## Report Results
+
+Summarise the batch outcome:
+
+| Metric | Value |
+|--------|-------|
+| Files attempted | N |
+| Successfully trained | N |
+| Failed | N |
+| Skipped (invalid) | N |
+
+For each failure, report:
+- File path
+- Error message
+- Suggested fix
+
+If all succeeded, confirm adapter URIs are accessible via `kairos spaces`.
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":80},"required":true}}
+```
+
+## Reward Signal
+
+Protocol complete when:
+- All valid adapter files in the target directory have been trained to the
+  specified space.
+- Per-file results have been reported to the user.
+- Any failures have been documented with remediation guidance.
+
+A successful bulk insert means the user's local protocol library is now
+registered in KAIROS and available for activation by AI agents.