@squadrules/mcp 4.8.6

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

@@ -0,0 +1,199 @@
+---
+version: "4.8.6"
+slug: phase-critic-guide
+title: Phase Critic Integration and Mutation Gate Guide
+---
+
+# Phase Critic Integration and Mutation Gate Guide
+
+Decision rules for integrating `phase-critic` into adapter protocols and
+determining when solution checks (hard verification gates) are required versus
+when phase-critic review is sufficient.
+
+## Activation Patterns
+
+**Typically invoked by:** `create-new-protocol` during adapter drafting, and
+any adapter that includes review or validation phases.
+
+**Can be invoked directly when agent needs:**
+- "when to add phase critic" / "should I use solution check"
+- "mutation gate rules" / "which actions need hard gates"
+- "phase critic vs solution check" / "irreversible action rules"
+- "add review step to protocol" / "where does critic go"
+
+**Trigger pattern:** **phase critic** / **mutation gate** / **solution check** +
+(integration | when | rules | guide | which | where).
+
+**Must Never:**
+- Be used as an execution protocol.
+- Override the adapter author's judgment on review depth.
+- Recommend solution checks for reversible or local-only actions.
+
+**Must Always:**
+- Distinguish between quality review (phase-critic) and mutation blocking
+  (solution checks).
+- Recommend phase-critic at every major phase boundary.
+- Restrict solution checks to irreversible remote-system mutations.
+
+**Good trigger examples:**
+- drafting a new adapter and deciding where to add review → load this
+- reviewing whether an adapter has the right solution checks → load this
+- "does my MR step need a solution check?" → load this
+
+**Bad trigger examples:**
+- "run the phase critic" → use `activate` to match `phase-critic`
+- "create a new protocol" → use `create-new-protocol`
+- "which challenge type for this step?" → use `challenge-type-guide`
+
+## Core Decision Rule
+
+**Phase-critic** is an adversarial review step at phase boundaries. It verifies
+claims, gathers evidence, and searches for contradictions. Use it for quality
+and truthfulness review.
+
+**Solution checks** are per-layer contract verification mechanisms (shell
+commands, MCP tool calls, user input). Use them ONLY to block actions that
+cause **irreversible changes on remote systems**.
+
+### What counts as an irreversible remote mutation
+
+| Action | Needs solution check? | Why |
+|--------|----------------------|-----|
+| Create/update merge request | Yes | Remote system state change |
+| Create/update Jira issue | Yes | Remote system state change |
+| Send email | Yes | Cannot unsend |
+| Send Teams message | Yes | Cannot unsend |
+| Create calendar invite | Yes | Sends notifications |
+| Deploy to production | Yes | Irreversible infrastructure change |
+| Delete remote resource | Yes | Irreversible |
+| Push to git remote | Yes | Remote state change |
+| Write/edit local file | No | Use phase-critic instead |
+| Run local tests | No | Read-only / local |
+| Analyze code | No | Read-only |
+| Generate report | No | Local artifact |
+| Read data from API | No | Read-only |
+| Compute / transform data | No | Local operation |
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":30},"required":true}}
+```
+
+## How to Chain Phase-Critic into an Adapter
+
+Use `forward` + slug to invoke `phase-critic` at phase boundaries. The standard
+pattern is a `mcp` contract that requires calling `forward` with the
+`phase-critic` slug:
+
+### After a planning phase
+
+```json
+{"contract":{"type":"mcp","mcp":{"tool_name":"forward","arguments":{"uri":"kairos://adapter/phase-critic"}},"required":true}}
+```
+
+### After an implementation phase
+
+Use the same contract. The phase-critic adapter receives the calling protocol's
+context and independently verifies the work.
+
+### Verdict handoff pattern
+
+Phase-critic writes a verdict file. The calling adapter reads it:
+
+1. Phase-critic writes `$VERDICT_FILE` with `PASS`/`FAIL` on line 1.
+2. Calling adapter's next layer reads the verdict file.
+3. If `FAIL` → **hard stop**: do NOT proceed to reward, do NOT ask the user
+   for approval, do NOT continue to the next phase. Address findings first.
+4. If `PASS` → the adapter continues to the next phase.
+
+**FAIL is a hard stop, not an escalation trigger.** A FAIL verdict means the
+work is not ready. Asking the user "should I proceed?" after FAIL bypasses the
+review. The correct action is to fix the findings and re-invoke phase-critic.
+
+### FAIL gate contract (required after every phase-critic invocation)
+
+Every adapter that chains phase-critic **must** include a shell contract that
+fails when the verdict is not PASS. This is the mechanical guard that prevents
+weaker agents from proceeding after FAIL:
+
+```json
+{"contract":{"type":"shell","shell":{"cmd":"head -1 \"$VERDICT_FILE\" | grep -qi '^PASS$'","timeout_seconds":5},"required":true}}
+```
+
+If the critic wrote FAIL, this shell command exits non-zero. The server rejects
+the solution and the agent cannot advance to the next layer. Protocol wording
+alone does not stop determined agents; this contract does.
+
+## Train/Tune Evidence Requirement
+
+`train` and `tune` enforce phase-critic PASS at the tool level:
+
+- **Adapter (markdown) `train`** requires `review_evidence`: verdict_file path,
+  exit_code (must be 0), and stdout (line 1 must be PASS). Without it, the
+  server rejects the store with `REVIEW_EVIDENCE_REQUIRED`.
+- **`tune` with content** requires the same `review_evidence`. Space-only moves
+  skip this check.
+- **Artifact trains** (non-markdown mime) skip the evidence check.
+
+This is the tool-level enforcement of the FAIL gate. Even if an agent bypasses
+the adapter flow and calls `train` directly, the server rejects the store
+without PASS evidence. The agent must run phase-critic, capture the verdict
+file, and pass it as `review_evidence`.
+
+## Mutation Gate Pattern
+
+When an adapter step performs an irreversible remote mutation, add a solution
+check that requires explicit confirmation BEFORE the action:
+
+### Pre-mutation confirmation
+
+```json
+{"contract":{"type":"user_input","user_input":{"prompt":"Confirm: you are about to create a merge request on repo X targeting branch Y. This action cannot be undone."},"required":true}}
+```
+
+### Post-mutation verification
+
+```json
+{"contract":{"type":"mcp","mcp":{"tool_name":"getMergeRequest","arguments":{"repo":"X"}},"required":true}}
+```
+
+## Phase-Critic Placement Rules
+
+1. **Add phase-critic at every major phase boundary** — after planning, after
+   implementation, after validation.
+2. **Do NOT add phase-critic between every layer** — it is a phase-level review,
+   not a step-level check.
+3. **Add solution checks ONLY on layers that perform remote mutations** — see
+   the table above.
+4. **Never replace a solution check with phase-critic** for remote mutations —
+   phase-critic reviews truth, it does not block execution.
+5. **Never add a solution check for local operations** — phase-critic provides
+   sufficient review.
+
+## Adapter Authoring Checklist
+
+When drafting a new adapter, apply this checklist:
+
+1. Identify all phase boundaries in the adapter flow.
+2. Add a `phase-critic` chain link at each boundary.
+3. Identify all steps that perform irreversible remote mutations.
+4. Add solution checks (user_input + post-action verification) for each.
+5. Verify that no solution checks exist for purely local operations.
+6. Verify that the phase-critic verdict handoff pattern is present.
+7. Verify that a FAIL gate shell contract follows every phase-critic invocation.
+8. Verify that `train`/`tune` calls include `review_evidence` from the critic.
+9. Ensure the adapter's Reward Signal describes what the critic protects.
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":80},"required":true}}
+```
+
+## Reward Signal
+
+Only reachable after all prior steps are solved.
+
+The agent can now:
+1. Decide when to use phase-critic versus solution checks
+2. Identify irreversible remote mutations that need hard gates
+3. Chain phase-critic into adapters at the correct phase boundaries
+4. Apply the mutation gate pattern for remote-system actions
+5. Avoid unnecessary solution checks for local or read-only operations

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

@@ -0,0 +1,210 @@
+---
+version: "4.8.6"
+slug: phase-critic
+title: Phase Critic
+---
+
+
+
+# Phase Critic
+
+Bounded adversarial investigator fired at phase boundaries. Receives a reference
+document, loads the calling protocol's invariants, and independently verifies
+the verification target by extracting claims, gathering evidence, and searching
+for contradictions.
+
+## Activation Patterns
+
+**Typically invoked by:** another protocol at the end of a plan, implement,
+validation, or review phase via `forward` with the stored adapter URI
+`kairos://adapter/phase-critic`.
+
+**Can be invoked directly when agent needs:**
+- "review phase output" / "verify plan" / "audit implementation"
+- "adversarial review" / "critic review"
+
+**Trigger pattern:** **review** / **verify** / **audit** / **critic** +
+(phase / plan / implementation / output).
+
+**Must Never:**
+- Modify any file outside the provided input and output paths.
+- Trust the executor's assertions without independent evidence.
+- Classify a claim as `verified` based only on absence of contradiction.
+- Keep investigating after a precondition failure that blocks verification.
+
+**Must Always:**
+- Extract claims before investigating.
+- Verify in-scope claims first.
+- Search for contradictory evidence, not only confirming evidence.
+- Include confidence in every verdict and failure class in every FAIL verdict.
+- Preserve the boundary between execution and review.
+
+**Good trigger examples:**
+- implement protocol fires this after planning → run this protocol
+- compose protocol fires this after output generation → run this protocol
+
+**Bad trigger examples:**
+- "Create a new protocol" → use `create-new-protocol`
+- "Implement a feature" → use an execution protocol, not this one
+
+## Artifact Contract
+
+This protocol receives:
+
+```text
+{
+  input_file: string,              // absolute path to the document under review
+  calling_protocol_slug: string,
+  verification_target: string,
+  context: {
+    operation: string,
+    verdict_file: string           // absolute path where the verdict will be written
+  }
+}
+```
+
+This protocol produces:
+
+```text
+{
+  verdict: "PASS" | "FAIL",
+  confidence: "High" | "Medium" | "Low",
+  failure_class: string,
+  verdict_file: "{context.verdict_file}"
+}
+```
+
+## Precondition Check [SUBAGENT]
+
+Verify foundational preconditions before deep investigation. Early-abort if any
+are broken.
+
+**Input:** `$INPUT_FILE` (absolute path), calling protocol slug, context
+
+**Actions:**
+1. Verify the input file exists: `test -f "$INPUT_FILE"`.
+2. Verify the verdict output path is writable (parent directory exists).
+3. Load the calling protocol's Must Never / Must Always sections if possible.
+4. Verify the target state is available for review.
+5. Verify required tools are available.
+
+**On early-abort:**
+- verdict = `FAIL`
+- failure class = `verification_blocked`
+- confidence = `Low`
+- write focused diagnostics
+- skip all later steps
+
+**Output:** verified preconditions or early-abort diagnostics
+
+```json
+{"contract":{"type":"shell","shell":{"cmd":"test -f \"$INPUT_FILE\"","timeout_seconds":3},"required":true}}
+```
+
+## Audit [SUBAGENT]
+
+Perform bounded adversarial review of the target against the reference document
+and invariants.
+
+**Input:** reference document, invariants, verification target, context
+
+**Actions:**
+
+**Step 1 — Extract claims**
+Extract every verifiable claim that matters operationally:
+- workflows, commands, tool calls
+- configuration and environment variable claims
+- architecture claims that imply behaviour
+- guarantees and constraints
+- security, auth, and permission claims
+
+**Step 2 — Investigate with scope discipline**
+1. verify all in-scope claims first
+2. review high-risk claims with maximum depth
+3. expand beyond scope only when contradiction signals, dependencies, or
+   high-risk impact require it
+4. continue reviewing all in-scope claims even after a normal FAIL condition is met;
+   only a precondition failure stops the audit early
+
+**High-risk areas**
+- setup steps and prerequisites
+- CLI commands and flags
+- configuration keys and environment variables
+- authentication, identity, and permissions
+- deployment and release behaviour
+- external publishing actions
+- destructive or irreversible operations
+
+**Step 3 — Gather evidence using the hierarchy**
+
+| Priority | Evidence source |
+|---|---|
+| 1 | source code, config files, schemas, route definitions |
+| 2 | direct runtime verification |
+| 3 | tests |
+| 4 | MCP-queried system state |
+| 5 | external docs, web pages, linked references |
+| 6 | conversational assumption or indirect inference |
+
+**Rules:**
+- higher-priority evidence overrides lower-priority evidence
+- priority 5–6 alone is not enough for `verified`
+
+**Step 4 — Produce claim verdicts**
+
+For each claim, record:
+- CLAIM
+- EVIDENCE
+- EVIDENCE PRIORITY
+- VERDICT: `verified` / `partially_verified` / `unverifiable` / `incorrect`
+
+A claim must not be marked `verified` without positive supporting evidence.
+
+**Step 5 — Review the phase boundary**
+Check whether the calling protocol preserved the right mode boundary:
+- was execution reviewed independently?
+- were review and execution kept separate?
+- did the protocol switch to verification when it should have?
+- is escalation needed because certainty was overstated?
+
+**Output:** structured audit findings for the verdict step
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":120},"required":true}}
+```
+
+## Verdict [SUBAGENT]
+
+Turn the audit into a final PASS / FAIL result.
+
+**Input:** audit findings and verdict file path from context (use it as
+`$VERDICT_FILE`)
+
+**Actions:**
+1. Fail if any critical claim is incorrect.
+2. Fail if verification was blocked.
+3. Fail if the evidence base is too weak for high-risk claims.
+4. Otherwise, pass with the appropriate confidence.
+5. Write `$VERDICT_FILE` so line 1 is `PASS` or `FAIL`,
+   line 2 is `High`, `Medium`, or `Low`, and the remaining lines summarise key
+   findings.
+
+**Verdict contract (calling adapter must obey):**
+- Line 1 is `PASS` → calling adapter may continue to the next phase.
+- Line 1 is `FAIL` → calling adapter **MUST NOT** proceed to reward, **MUST NOT**
+  ask the user for approval, and **MUST NOT** continue to the next phase.
+  The calling adapter must address findings and re-invoke phase-critic.
+
+**Output:** final verdict file
+
+```json
+{"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}}
+```
+
+## Reward Signal
+
+Only reachable after all prior steps are solved.
+
+The phase output has been independently challenged. The resulting verdict is more
+truthful because it is based on extracted claims, explicit evidence, contradiction
+search, and a clean boundary between execution and review.

package/dist/embed-docs/mem/protocol-linking-guide.md

@@ -0,0 +1,231 @@
+---
+version: "4.8.6"
+slug: protocol-linking-guide
+title: Protocol Linking Guide
+---
+
+
+
+# Protocol Linking Guide
+
+Decision rules for structuring adapter relationships: layers vs chains,
+`activate` vs `forward` + slug, chain-root collapsing, and MCP argument
+validation for deterministic cross-protocol linking.
+
+## Activation Patterns
+
+**Typically invoked by:** `create-new-protocol` and
+`phase-critic`.
+
+**Can be invoked directly when agent needs:**
+- "layers vs chains" / "when to split into multiple adapters"
+- "how to link adapters" / "cross-protocol linking"
+- "activate vs forward" / "when to use forward with slug"
+- "chain-root collapsing" / "how chain_root works"
+
+**Trigger pattern:** **layers** / **chains** / **linking** / **forward** +
+(slug | adapter | protocol).
+
+**Must Never:**
+- Be used as an execution protocol.
+- Recommend chaining when layers suffice.
+
+**Must Always:**
+- Be consulted before splitting a protocol into multiple adapters.
+- Be consulted before adding `forward` calls or `chain_root` frontmatter.
+
+**Good trigger examples:**
+- "my protocol is 400 lines, should I split?" → load this
+- "how do I link adapter A to adapter B?" → load this
+- "what is chain_root?" → load this
+
+**Bad trigger examples:**
+- "which challenge type for this step?" → use `challenge-type-guide`
+- "create a new protocol" → use `create-new-protocol`
+
+## 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 only 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.
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":30},"required":true}}
+```
+
+## `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.
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":30},"required":true}}
+```
+
+## Chaining Back and Forward
+
+When a family of adapters has a root conductor and smaller domain extensions,
+document both directions of chaining.
+
+### Chaining back with `chain_root`
+
+Extension adapters should include `chain_root` frontmatter and a prerequisite
+clause:
+
+**Prerequisite:** Start from `<root-adapter-slug>` unless the caller already
+provided a mission brief, safety gates, authorization boundary, and evidence
+requirements.
+
+This protects activation entry points. If a user or weak agent activates a
+mid-chain extension directly, the extension can collapse back to the root unless
+it already received the required parent context.
+
+### Chaining forward with `forward`
+
+`chain_root` does not replace explicit `forward` calls inside the chain.
+
+When the next adapter is known at authoring time or after deterministic runtime
+classification, use `forward` with the target slug. Do not call `activate` just
+to rediscover a slug already known by the current adapter.
+
+Forwarded adapters should receive:
+- current mission brief;
+- safety gates;
+- authorization boundary;
+- evidence requirements;
+- user constraints;
+- reason for forwarding.
+
+Use `activate` only when the next adapter must be discovered from an ambiguous
+runtime need.
+
+### Multi-layer conductors and extension URIs
+
+When you are executing **`forward`** inside a **multi-layer** adapter (for example
+a root conductor), each continuation follows **`next_call`** for the **same**
+`execution_id` until the last layer directs **`reward`**. A layer that mentions
+another adapter URI only as routing guidance — for example
+`kairos://adapter/e2e-coding-pr-delivery` — does **not** cause the server to
+switch executions: the next **`forward`** in that run still advances the
+**current** adapter’s next layer.
+
+To run an extension adapter, call **`forward`** with
+`kairos://adapter/<slug>` as a **new** first call (adapter URI; omit
+`solution`). That starts a **separate** execution with its own layers. Common
+pattern: complete the conductor with **`reward`**, then **`forward`** to the
+extension slug when coding or PR-shaped work should run under that adapter’s
+contracts.
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":30},"required":true}}
+```
+
+## System adapters vs user adapters
+
+Both system and user-authored adapters chain using slugs in `next_action`:
+
+```text
+call forward with kairos://adapter/phase-critic ...
+call forward with kairos://adapter/implement-terraform ...
+```
+
+Slugs are globally unique (enforced by `train`), so resolution is
+deterministic — no scoring, no ambiguity.
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":30},"required":true}}
+```
+
+## MCP argument validation for chain links
+
+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.
+
+Use the `arguments` form whenever a step's purpose is to invoke a specific
+known adapter.
+
+```json
+{"contract":{"type":"comment","comment":{"min_length":30},"required":true}}
+```
+
+## 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:** Each mid-chain adapter
+should include a **Prerequisites** paragraph in its Activation Patterns
+listing inputs required from earlier phases and directing 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 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.
+
+```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. decide when to use layers vs chains
+2. choose `activate` vs `forward` + slug correctly
+3. use slug-based linking for all adapters (system and user)
+4. apply MCP argument validation for deterministic chain links
+5. implement `chain_root` collapsing with defense-in-depth safeguards
+6. document chaining back (`chain_root` + prerequisites) and chaining forward
+   (`forward` with known slugs) for root + extension families