@debian777/kairos-mcp 4.7.3 → 4.8.0-beta.0

package/dist/embed-docs/mem/00000000-0000-0000-0000-000000002003.md

@@ -1,202 +1,30 @@
 ---
-version: "4.7.3"
+version: "4.8.0-beta.0"
 slug: create-new-protocol-review
-title: Review and Publish New KAIROS Protocol
+title: "DEPRECATED — use phase-critic + create-new-protocol"
 ---
 
+# DEPRECATED — create-new-protocol-review
 
-# Review and Publish New KAIROS Protocol
+This adapter is **deprecated** as of v4.8.0.
 
-Validate a drafted KAIROS protocol through format review, stranger review, user
-approval, and train. Invoked by the authoring adapter (`create-new-protocol`) or
-directly to re-review an existing draft.
+Its responsibilities are now handled by:
 
-## Activation Patterns
+1. **phase-critic** (`2005`) — adversarial phase-boundary review (integrated
+   into the 2001 authoring flow as a mandatory gate before train).
+2. **create-new-protocol** (`2001`) — authoring adapter that now invokes
+   `phase-critic` directly and includes `review_evidence` in its `train` call.
 
-**Typically invoked by:** the authoring adapter's handoff step via
-`activate()` or a stored adapter URI.
+## Why deprecated
 
-**Can be invoked directly when user says:**
-- "review my protocol draft" / "validate this protocol"
-- "re-run format review on my draft"
-- "train my protocol" / "register my adapter"
+The original flow split authoring (2001) and review (2003) into two chained
+adapters. The phase-critic quality gate consolidates review into a single
+`forward` step inside 2001, eliminating the chain hop and providing structured
+evidence (`review_evidence`) on every train call.
 
-**Trigger pattern:** **review** / **validate** / **train** + (protocol / draft).
+## Migration
 
-**Must Never:**
-- Run shell verification without verifying that all input file paths exist first.
-- Skip format or stranger review.
-- Approve a draft merely because it sounds polished.
-
-**Must Always:**
-- Verify all input file paths exist before proceeding (`test -f`).
-- Require both reviews to pass before presenting to the user.
-- Freeze the draft checksum before `train`.
-- Review for truth, phase clarity, ambiguity, and weaker-agent executability.
-
-**Good trigger examples:**
-- handoff from `create-new-protocol` → run this protocol
-- "Review and train my protocol draft" → run this protocol
-
-**Bad trigger examples:**
-- "Create a new protocol" → use `create-new-protocol`
-- "Search for a protocol" → use `activate`
-
-## Preflight Dependencies
-
-Before running review/publish steps, verify prerequisites up front:
-
-1. Required MCP tools are reachable: `activate`, `forward`, `reward`, `train`.
-2. Required shell utilities used in this workflow are callable.
-3. Required authentication/session state is valid for MCP and SCM hosts.
-4. All input file paths provided by the parent agent exist (`test -f`).
-
-If any dependency or auth check fails, stop and ask the user to choose either:
-proceed with AI-assisted setup or abort this run now.
-
-```json
-{"contract":{"type":"comment","comment":{"min_length":80},"required":true}}
-```
-
-## Prerequisites
-
-This protocol receives all file paths as absolute paths from the invoking agent:
-
-- `$DRAFT_FILE` — the protocol draft to review (required)
-- `$REQUIREMENTS_FILE` — requirements document (optional)
-- `$FORMAT_REVIEW_FILE` — output path for format review verdict
-- `$STRANGER_REVIEW_FILE` — output path for stranger review verdict
-- `$DRAFT_CHECKSUM_FILE` — output path for the frozen checksum
-
-The parent agent is responsible for choosing collision-free paths (e.g., under
-`$KAIROS_LOCAL_ARTIFACT_DIR` with a session-unique segment). This protocol only
-verifies paths exist via `test -f` and writes to the provided output paths.
-
-If invoked directly, export the variables before proceeding.
-
-**Security:** never write credentials, tokens, or secrets into output files.
-
-## Format Review [SUBAGENT]
-
-Delegate format verification to a subagent. The subagent writes its verdict to
-`$FORMAT_REVIEW_FILE`.
-
-**Input:** `$DRAFT_FILE`
-
-**Subagent task:**
-1. Read the draft.
-2. Verify structure:
-   - H1 present exactly once
-   - first H2 is `Activation Patterns`
-   - last H2 is `Reward Signal`
-   - every middle H2 has a challenge block
-   - no duplicate H2 headings
-3. Verify authoring quality:
-   - explicit phase separation where relevant
-   - no hidden assumptions
-   - no vague filler such as "as needed" when a concrete instruction is required
-4. Verify challenge type selection using `challenge-type-guide`:
-   - no `comment` challenges for steps that create files, call tools, or check state
-   - `shell` challenges include `timeout_seconds`
-   - shell chains use `&&`, not `;`, except for the agent-readable shell status
-     trailer from `challenge-type-guide`
-5. Verify DRY, slug, and 350-line compliance.
-6. Write verdict to `$FORMAT_REVIEW_FILE`. First line MUST be
-   `PASS` or `FAIL`. Remaining lines list concrete fixes.
-
-**Output:** `$FORMAT_REVIEW_FILE`
-
-```json
-{"contract":{"type":"shell","shell":{"cmd":"test -f \"$FORMAT_REVIEW_FILE\" && head -1 \"$FORMAT_REVIEW_FILE\" | grep -qi 'pass'","timeout_seconds":5},"required":true}}
-```
-
-## Stranger Review [SUBAGENT]
-
-Delegate executability review to a subagent with junior AI agent persona. The
-subagent writes its verdict to `$STRANGER_REVIEW_FILE`.
-
-**Input:** `$DRAFT_FILE`
-
-**Subagent task:**
-1. Assume persona: junior AI agent, first time encountering KAIROS protocols.
-2. Mocked dry-run: walk every step in order and produce structurally correct
-   challenge responses.
-3. Check:
-   - can I execute this without guessing?
-   - are phases clear?
-   - do I know when to stop, ask, execute, verify, or escalate uncertainty?
-   - are any variables or concepts undefined?
-4. Write verdict to `$STRANGER_REVIEW_FILE`. First line MUST be
-   `PASS` or `FAIL`. If FAIL, include specific failing mocks and missing context.
-
-**Output:** `$STRANGER_REVIEW_FILE`
-
-```json
-{"contract":{"type":"shell","shell":{"cmd":"test -f \"$STRANGER_REVIEW_FILE\" && head -1 \"$STRANGER_REVIEW_FILE\" | grep -qi 'pass'","timeout_seconds":5},"required":true}}
-```
-
-## Checksum Freeze [SUBAGENT]
-
-Freeze the draft after both reviews pass.
-
-**Input:** `$DRAFT_FILE`
-
-**Actions:**
-1. Compute md5 checksum of the draft file.
-2. Write checksum to `$DRAFT_CHECKSUM_FILE`.
-
-**Output:** `$DRAFT_CHECKSUM_FILE`
-
-```json
-{"contract":{"type":"shell","shell":{"cmd":"md5 -q \"$DRAFT_FILE\" > \"$DRAFT_CHECKSUM_FILE\" && test -s \"$DRAFT_CHECKSUM_FILE\"","timeout_seconds":5},"required":true}}
-```
-
-## User Review [SUBAGENT]
-
-Present the reviewed protocol to the user for final approval.
-
-**Input:** draft plus both review files
-
-**Actions:**
-1. Present full protocol markdown.
-2. Summarise pattern used, step count, challenge types, slug(s), and both review verdicts.
-3. Ask the user to approve, request changes, or cancel.
-
-**Output:** user approval, changes, or cancellation.
-
-```json
-{"contract":{"type":"user_input","user_input":{"prompt":"Review the protocol draft above. Type 'approved' to run train, describe adjustments, or 'cancel'."},"required":true}}
-```
-
-## Train adapter [SUBAGENT]
-
-Verify the draft is unchanged since checksum freeze, then call `train`.
-
-**Input:** approved `$DRAFT_FILE`
-
-**Actions:**
-1. Verify draft unchanged against checksum.
-2. Call `train` with `force_update: false` unless overwrite was explicitly requested.
-3. If router pattern: train router first, then extensions in order.
-4. Verify each `train` call returned a URI.
-5. Report stored adapter URI(s) back to the user.
-
-**Output:** confirmation with stored adapter URI(s)
-
-```json
-{"contract":{"type":"mcp","mcp":{"tool_name":"train"},"required":true}}
-```
-
-## Reward Signal
-
-Only reachable after all prior steps are solved.
-
-The user now has a trained KAIROS adapter that passed:
-1. format review
-2. stranger review
-3. checksum verification
-4. user approval
-5. successful storage via `train`
-
-The resulting adapter is more likely to be truthful, phase-aware, and usable by
-weaker agents.
+- If you were forwarded here by `create-new-protocol`, the parent adapter
+  already runs `phase-critic` and will train automatically.
+- If you invoked this slug directly, use `activate` with a phrase like
+  "create a new protocol" to match `2001` instead.

package/dist/embed-docs/mem/00000000-0000-0000-0000-000000002004.md

@@ -1,5 +1,5 @@
 ---
-version: "4.7.3"
+version: "4.8.0-beta.0"
 slug: challenge-type-guide
 title: Challenge Type Selection Guide
 ---
@@ -15,7 +15,7 @@ drafting and review.
 ## Activation Patterns
 
 **Typically invoked by:** `create-new-protocol` and
-`create-new-protocol-review`.
+`phase-critic`.
 
 **Can be invoked directly when agent needs:**
 - "challenge type reference" / "which challenge type to use"
@@ -39,7 +39,7 @@ drafting and review.
 
 **Bad trigger examples:**
 - "Create a new protocol" → use `create-new-protocol`
-- "Review my protocol draft" → use `create-new-protocol-review`
+- "Review my protocol draft" → use `phase-critic`
 
 ## Core Rules
 

package/dist/embed-docs/mem/00000000-0000-0000-0000-000000002005.md

@@ -1,5 +1,5 @@
 ---
-version: "4.7.3"
+version: "4.8.0-beta.0"
 slug: phase-critic
 title: Phase Critic
 ---
@@ -189,6 +189,12 @@ Turn the audit into a final PASS / FAIL result.
    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

package/dist/embed-docs/mem/00000000-0000-0000-0000-000000002006.md

@@ -1,5 +1,5 @@
 ---
-version: "4.7.3"
+version: "4.8.0-beta.0"
 slug: protocol-linking-guide
 title: Protocol Linking Guide
 ---
@@ -15,7 +15,7 @@ validation for deterministic cross-protocol linking.
 ## Activation Patterns
 
 **Typically invoked by:** `create-new-protocol` and
-`create-new-protocol-review`.
+`phase-critic`.
 
 **Can be invoked directly when agent needs:**
 - "layers vs chains" / "when to split into multiple adapters"

package/dist/embed-docs/mem/00000000-0000-0000-0000-000000002007.md

@@ -1,6 +1,6 @@
 ---
 slug: bulk-insert-adapters-via-cli
-version: "4.7.3"
+version: "4.8.0-beta.0"
 title: Bulk Insert Adapters via KAIROS CLI
 ---
 

package/dist/embed-docs/mem/00000000-0000-0000-0000-000000002008.md

@@ -1,5 +1,5 @@
 ---
-version: "4.7.3"
+version: "4.8.0-beta.0"
 slug: skill-format-guide
 title: Skill Format and Local Authoring Guide
 ---
@@ -16,7 +16,7 @@ protocol-authoring agents during drafting and review when the output format is
 ## Activation Patterns
 
 **Typically invoked by:** `create-new-protocol` and
-`create-new-protocol-review`.
+`phase-critic`.
 
 **Can be invoked directly when agent needs:**
 - "SKILL.md format reference" / "how to write a skill"

package/dist/embed-docs/mem/00000000-0000-0000-0000-000000002009.md

@@ -0,0 +1,199 @@
+---
+version: "4.8.0-beta.0"
+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