@squadrules/mcp 4.8.6

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

@@ -0,0 +1,278 @@
+---
+version: "4.8.6"
+slug: challenge-type-guide
+title: Challenge Type Selection Guide
+---
+
+
+
+# Challenge Type Selection Guide
+
+Decision rules, JSON formats, interpreter selection, and anti-patterns for
+choosing KAIROS challenge types. Loaded by protocol-authoring agents during
+drafting and review.
+
+## Activation Patterns
+
+**Typically invoked by:** `create-new-protocol` and
+`phase-critic`.
+
+**Can be invoked directly when agent needs:**
+- "challenge type reference" / "which challenge type to use"
+- "how to write shell challenges" / "challenge format"
+- "interpreter selection for challenges"
+
+**Trigger pattern:** **challenge** + (type | format | selection | guide).
+
+**Must Never:**
+- Be used as an execution protocol.
+- Select `comment` merely because it is easy.
+
+**Must Always:**
+- Be consulted before assigning challenge types to protocol steps.
+- Choose the strongest observable contract available.
+- Match challenge choice to the mode of the step: ask, decide, act, verify, or review.
+
+**Good trigger examples:**
+- drafting a new protocol and need challenge types → load this
+- reviewing challenge type selection in a draft → load this
+
+**Bad trigger examples:**
+- "Create a new protocol" → use `create-new-protocol`
+- "Review my protocol draft" → use `phase-critic`
+
+## Core Rules
+
+`comment` is the challenge type of **last resort**. If a step produces any
+observable artifact — a file, a git state change, an API response, or an exit
+code — use `shell` or `mcp` instead.
+
+**Mode before challenge type:**
+- **clarify / approve** → `user_input`
+- **call a KAIROS / MCP tool** → `mcp`
+- **execute or verify local state** → `shell`
+- **pure reasoning with no observable artifact** → `comment`
+
+### Decision Tree
+
+```
+Does the step call an MCP tool?
+ ├─ YES → Is the step a chain link to another adapter?
+ │         ├─ YES → "mcp" with tool_name + arguments (forward + slug URI)
+ │         └─ NO  → "mcp" with tool_name only
+ └─ NO → Does the step produce or verify a file, command result, or system state?
+          ├─ YES → "shell"
+          └─ NO → Does the step require human approval or choice?
+                   ├─ YES → "user_input"
+                   └─ NO → "comment" only if there is no stronger observable contract
+```
+
+### Challenge JSON Formats
+
+**shell**
+```json
+{"contract":{"type":"shell","shell":{"cmd":"<command>","timeout_seconds":30},"required":true}}
+```
+
+**mcp**
+```json
+{"contract":{"type":"mcp","mcp":{"tool_name":"<tool>"},"required":true}}
+```
+
+**mcp with arguments (chain link)**
+```json
+{"contract":{"type":"mcp","mcp":{"tool_name":"forward","arguments":{"uri":"kairos://adapter/<slug>"}},"required":true}}
+```
+
+Use the `arguments` form when the step's purpose is to invoke a specific
+adapter via `forward`. The server validates that `solution.mcp.arguments`
+is a superset of the contract's `mcp.arguments` (subset/deep matching),
+proving the agent called the correct target — not just any `forward` call.
+
+**user_input**
+```json
+{"contract":{"type":"user_input","user_input":{"prompt":"<specific question>"},"required":true}}
+```
+
+**comment**
+```json
+{"contract":{"type":"comment","comment":{"min_length":50},"required":true}}
+```
+
+### Solution JSON Formats
+
+Every solution, regardless of type, follows the same envelope:
+
+```json
+{
+  "type": "<challenge_type>",
+  "outcome": "success | failure | skipped",
+  "evidence": { /* type-specific proof data */ },
+  "nonce": "<echo from contract>",
+  "proof_hash": "<echo from contract>"
+}
+```
+
+**shell solution**
+```json
+{
+  "type": "shell",
+  "outcome": "success",
+  "evidence": {
+    "exit_code": 0,
+    "stdout": "...",
+    "stderr": "",
+    "duration_seconds": 1.2
+  }
+}
+```
+
+**mcp solution**
+```json
+{
+  "type": "mcp",
+  "outcome": "success",
+  "evidence": {
+    "tool_name": "activate",
+    "arguments": { "query": "example search" },
+    "response": { "choices": [...] }
+  }
+}
+```
+
+**user_input solution**
+```json
+{
+  "type": "user_input",
+  "outcome": "success",
+  "evidence": {
+    "confirmation": "agreed. proceed",
+    "timestamp": "2026-05-18T14:49:00Z"
+  }
+}
+```
+
+**comment solution**
+```json
+{
+  "type": "comment",
+  "outcome": "success",
+  "evidence": {
+    "text": "Verified all 78 issues now have repo: labels."
+  }
+}
+```
+
+### Compatibility
+
+The server also accepts older solution shapes where data is placed directly
+under the type key (e.g. `{ "type": "shell", "shell": { "exit_code": 0 } }`)
+instead of inside an `evidence` envelope. Always use the unified envelope with
+`outcome` and `evidence` for new protocols.
+
+## Interpreter Selection
+
+| Task | Use bash | Use perl | Use python3 |
+|---|---|---|---|
+| File exists, tool installed, git state | yes | no | no |
+| Simple content grep | yes | no | no |
+| Multi-line regex | no | yes | no |
+| Paragraph processing | no | yes | no |
+| JSON validation | maybe | yes | yes |
+| YAML / complex data structure checks | no | no | yes |
+
+**Rule of thumb:** if bash requires `while read`, `grep | awk`, or heavy quote
+escaping, rewrite in Perl. If you need imports for data formats, use Python.
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":30},"required":true}}
+```
+
+## Security and Working Directory Rules
+
+Use `$KAIROS_LOCAL_ARTIFACT_DIR` as the base directory for local handoff
+artifacts. File paths within it are provided as variables by the invoking agent
+to avoid collisions between parallel sessions.
+
+**Rules:**
+- all file paths in shell challenges reference variables (e.g., `$DRAFT_FILE`,
+  `$VERDICT_FILE`) set by the parent agent — never hardcode filenames
+- the parent agent constructs collision-free paths under
+  `$KAIROS_LOCAL_ARTIFACT_DIR` (e.g., with a session ID or random suffix)
+- when using KAIROS MCP, the latest `activate` / `forward` / `next` response field `kairos_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 KAIROS_LOCAL_ARTIFACT_DIR="<absolute>"` if your shell does not already define it
+- if the server-returned path is not usable on your local filesystem, resolve
+  locally to `$PROJECT_DIR/.local/kairos/work` and keep it stable for the run
+- prerequisites create the directory
+- Reward Signal cleans it up
+- never write credentials or secrets to files
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":30},"required":true}}
+```
+
+## Composition Patterns
+
+**Multi-check compound command**
+- chain with `&&`
+- let the first failure stop execution
+
+**Agent-readable shell status**
+- use when failure can produce no output, especially `test`, quiet `grep`,
+  JSON probes, pipelines, or commands that redirect stderr
+- empty stdout or stderr is not success; success is the real process status
+  reported as `solution.shell.exit_code`
+- print the final status marker to stderr when stdout is machine-readable
+- preserve the original status exactly:
+  ```bash
+  ( set -o pipefail; <command> ); rc=$?; printf '\nKAIROS_SHELL_EXIT=%s\n' "$rc" >&2; exit "$rc"
+  ```
+- keep `&&` inside `<command>` for ordered checks; use the final
+  `; rc=$?; ...` trailer only to capture, print, and return the process status
+- do not use `<command> || echo ERROR && false`; shell operators group
+  left-to-right, so that form can fail after a successful command and it loses
+  the original status
+
+**Freeze-then-verify**
+- step N writes checksum
+- step N+1 verifies checksum before publish
+
+**Write-then-grep**
+- subagent writes a verdict file
+- main agent checks the first line for `PASS`
+
+**Phase-batch with critic**
+- batch related TODO items into one phase
+- verify hard artifacts with shell
+- then call `phase-critic` for adversarial review
+
+**Dry-run before execution**
+- dry-run command
+- human review
+- real command
+
+**Chain-link via forward + slug**
+- layer N's contract requires `forward` with a specific adapter slug
+- agent calls `forward` to start the next adapter (new `execution_id`)
+- next adapter runs its own layer chain through to `reward`
+- use when the protocol exceeds 350 lines or needs multi-path routing
+- NOT a replacement for layers — layers remain the primary unit of work
+- example contract:
+  ```json
+  {"contract":{"type":"mcp","mcp":{"tool_name":"forward","arguments":{"uri":"kairos://adapter/implement-plan"}},"required":true}}
+  ```
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":30},"required":true}}
+```
+
+## Reward Signal
+
+Only reachable after all prior steps are solved.
+
+The agent can now:
+1. pick the correct challenge type for each protocol step
+2. match challenge type to the step's mode
+3. choose the right interpreter
+4. apply working-directory and security rules
+5. preserve real shell statuses for silent checks
+6. use stronger verification patterns instead of weak narrative checks

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

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