kairos-chain 3.19.1 → 3.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef45a8e58aedc056cd5303abb6463a66503da146fc2bb7abe8ee018569fde8e0
-  data.tar.gz: c62bc1328bc6a22e577cb1a8dad2de501bf184dd9022acb207257a4cfaa49955
+  metadata.gz: 20e2a223137f51dc61025e57dd6fd205a8f702ef923b5b0b2e0d464a308d279f
+  data.tar.gz: 51627cb487cf5fc2e46b8e6055bf36e0cf5c8839f15cb2c2236f2ff56efa2def
 SHA512:
-  metadata.gz: 9e6236cd2860aa3cf244361962de9660b04aa47e0eed03689bb16dd4e95f3f6e1f9f6fe7377e9c0b5b6be87842346757c8b273f6ac8564d293f5cd2157baa727
-  data.tar.gz: e83f1c792045a5141c9914d6ef09d1ac4ecc33ae6664e27316cf9ab82987c8c5555981869ec18fbb0309cefe071f5d62eb748b6cd2d92b1d2ff9835bf5f5fed3
+  metadata.gz: 9fd4b17a28bdc06b7b19195e7274ef41e4ba7a93fc70e2c3a38083c58eae85ea8dfd432cb7cc6219cf7ba49ba637dbed12c48ea12312f4a3f26f46dfb936438f
+  data.tar.gz: fadb35fdbf47eeebfc9b667685452a0c222ecb396dbb2031de08ac27b2df1de1a3985fc41c03e4e767d22a58ec98a77d52c2059e921f8084d1663a2a099bdd1d

data/CHANGELOG.md

@@ -4,6 +4,77 @@ All notable changes to the `kairos-chain` gem will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.24.0] - 2026-04-27
+
+### Added
+
+- **multi_llm_review_wait MCP tool** (Phase 1.5) — optional blocking gate
+  between `multi_llm_review` (Phase 1) and `multi_llm_review_collect`
+  (Phase 2). Wraps the existing `WaitForWorker.wait` polling loop and
+  exposes 6 distinct status codes (`ready`, `still_pending`, `crashed`,
+  `unknown_token`, `already_collected`, `past_collect_deadline`) each with
+  a `next_action` recovery hint pointing at the right next tool.
+- **`next_action` hint on `multi_llm_review` delegation_pending response** —
+  structured `{tool, args, purpose}` field nudging the orchestrator to call
+  `multi_llm_review_wait` after persona Agent dispatch. MCP does not enforce
+  ordering; this is a hint, not a constraint, but in practice LLMs follow
+  it reliably.
+- **Path A vs Path B disambiguation in workflow knowledge doc** — surfaces
+  the long-implicit distinction between the host-tracked Bash workflow
+  (Claude Code's `Bash(background)` pattern, statusbar shows `XX shells`)
+  and the MCP-managed SkillSet (detached worker, no host-side tracking,
+  polling required).
+- New config keys under `delegation.parallel`:
+  `wait_poll_interval_seconds: 1.0`, `wait_max_default_seconds: 600`,
+  `wait_max_hard_cap_seconds: 1800`, `wait_still_pending_streak_limit: 3`.
+- Streak guard: 3 consecutive `still_pending` returns escalate to
+  `crashed/wait_exhausted` so a wedged worker cannot trap the orchestrator
+  in an infinite wait loop.
+- 14 new tests in `test_multi_llm_review_wait.rb` covering all status
+  paths, streak persistence/reset, hard cap clamping, deadline-remaining
+  clamping, and backward compatibility (collect still works without wait).
+
+### Changed
+
+- `multi_llm_review` SkillSet version 0.4.0 → 0.5.0.
+- `delegation` instruction text now mentions wait → collect chain.
+
+### Notes
+
+- Backward compatible: callers that skip wait and call collect directly
+  still work via collect's existing internal polling.
+- Design review (Codex GPT-5.5 + Cursor Composer-2 + Claude Team Opus 4.7)
+  produced 3/3 REVISE with 6-7 P1 issues; revisions R1-R14 captured in
+  handoff L2 `multi_llm_review_wait_tool_handoff` before implementation.
+
+## [3.23.3] - 2026-04-27
+
+### Documentation
+
+- **multi_llm_review_workflow knowledge** — Added "Async/Parallel Collect
+  Timing — Iron Rule" subsection. Documents the workflow constraint that the
+  orchestrator must call `multi_llm_review_collect` immediately after persona
+  Agent reviews complete, without intervening user dialogue. Explains the
+  underlying mechanics (LLM is not event-driven; collect already polls
+  internally at 0.5s intervals; token expiry vs subprocess completion). Adds
+  recommended flow, anti-pattern, and manual recovery instructions.
+- Updated stale `must_collect_by` default reference (600s → 1800s).
+
+## [3.23.2] - 2026-04-26
+
+### Fixed
+
+- **multi_llm_review collect_deadline bug** — `timeout_seconds_override` no longer
+  leaves the orchestrator's submission window shorter than the worker lifespan.
+  In the async/parallel path, `collect_deadline` is now auto-extended to cover
+  `worker self_timeout + poll margin` so raising `timeout_seconds_override`
+  alone keeps the token alive while the worker is healthy.
+- New `collect_deadline_seconds_override` argument on `multi_llm_review` for
+  explicit control of the orchestrator's submission window.
+- Default `delegation.collect_deadline_seconds` raised from `600` (10 min) to
+  `1800` (30 min) to better fit interactive runs where user dialogue intervenes
+  between Phase 1 and `multi_llm_review_collect`.
+
 ## [3.17.0] - 2026-04-22
 
 ### Added

data/lib/kairos_mcp/version.rb

@@ -1,4 +1,4 @@
 module KairosMcp
-  VERSION = "3.19.1"
+  VERSION = "3.24.0"
   CHANGELOG_URL = "https://github.com/masaomi/KairosChain_2026/blob/main/CHANGELOG.md"
 end

data/templates/knowledge/multi_llm_review_workflow/multi_llm_review_workflow.md

@@ -29,6 +29,54 @@ This skill covers:
 For **WHO** (which LLM is good at what), see: `multi_llm_reviewer_evaluation`
 For **development lifecycle** (design → implement → verify), see: `design_to_implementation_workflow`
 
+## Two Execution Paths (read this first)
+
+There are **two distinct execution paths** with the same name "multi-LLM review".
+They differ in subprocess lifecycle ownership and completion-detection mechanics.
+Pick the right one for your environment:
+
+### Path A — Host-tracked (Bash workflow)
+
+- **Trigger**: orchestrator (LLM) calls Claude Code's `Bash` tool with
+  `run_in_background: true` to spawn `claude -p`, `codex exec`, `agent -p` directly.
+- **Process parent**: Claude Code (the host harness).
+- **Completion detection**: **event-driven**. Claude Code's shell tracker monitors
+  the spawned shells; when they exit, the LLM is notified through the standard
+  tool-result mechanism. Statusbar shows `XX shells` while reviewers are running.
+- **When to use**: interactive Claude Code sessions for one-off Tier 3 reviews.
+- **Reference**: see "Orchestration Template" section below for the canonical
+  `Bash(background)` pattern.
+
+### Path B — MCP-managed (multi_llm_review SkillSet)
+
+- **Trigger**: orchestrator calls the MCP tool `multi_llm_review`.
+- **Process parent**: the kairos-chain Ruby gem (MCP server). The gem forks a
+  detached worker (`bin/dispatch_worker.rb`) which calls `Process.setsid` and
+  spawns CLI reviewers as a separate session leader.
+- **Completion detection**: **polling required**. Claude Code is not the parent,
+  so the spawned subprocesses do NOT appear in the `XX shells` statusbar count.
+  The orchestrator must call `multi_llm_review_collect` (and optionally
+  `multi_llm_review_wait` first) to observe completion.
+- **When to use**: portable execution (other MCP hosts, autonomous Agent SkillSet),
+  or any case where you want the consensus computation done server-side.
+- **Recommended chain (3-step)**: `multi_llm_review` → `multi_llm_review_wait` →
+  `multi_llm_review_collect`. Each Phase-1/1.5 response carries a `next_action`
+  hint pointing at the next tool. wait is optional but recommended — without it,
+  collect's internal polling still covers worker completion, but recovery hints
+  for `still_pending`, `crashed`, and `past_collect_deadline` are less explicit.
+- **Reference**: see "Orchestrator Delegation Protocol" + "Async/Parallel Collect
+  Timing — Iron Rule" sections below.
+
+### Quick selector
+
+| Question | Answer |
+|----------|--------|
+| Are you in an interactive Claude Code session and just need one review? | **Path A** |
+| Do you need this to work in Cursor / autonomous mode / other MCP host? | **Path B** |
+| Do you want the consensus result inside the MCP tool response? | **Path B** |
+| Did you observe `XX shells` in the statusbar last time it worked? | That was Path A |
+| Did the run produce a `collect_token` and a `pending/<token>/` directory? | That was Path B |
+
 ## Roles
 
 | Role | Who | Responsibility |
@@ -331,8 +379,8 @@ cross-model subprocess reviewers give epistemic diversity. The two are complemen
 
 **Failure modes**:
 - `expired_or_unknown_token`: orchestrator missed `must_collect_by` deadline
-  (default 600s), or token never existed. The pending review is gone; call
-  `multi_llm_review` again from scratch.
+  (default 1800s since v3.23.2; was 600s), or token never existed. The pending
+  review is gone; call `multi_llm_review` again from scratch.
 - `error: invalid orchestrator_reviews`: persona count outside 2-4 or missing
   required fields. Fix and retry collect with the same token.
 - All-subprocess-failed at Call 1: returns error immediately; no token issued.
@@ -340,6 +388,62 @@ cross-model subprocess reviewers give epistemic diversity. The two are complemen
 **Default**: `orchestrator_strategy` defaults to `"exclude"` (back-compat). Use
 `"delegate"` explicitly until validated by use.
 
+#### Async/Parallel Collect Timing — Iron Rule
+
+When `delegation.parallel.default: true` (the v3.x default), Call 1 returns
+`delegation_pending` **immediately** (~50ms) and a detached worker runs the
+subprocess reviewers in parallel with the orchestrator's persona Agent
+reviews. This is faster, but introduces a timing trap:
+
+> **The orchestrator MUST call `multi_llm_review_collect` immediately after
+> the persona Agent reviews complete — without intervening user dialogue,
+> unrelated tool calls, or context switches.**
+
+Why this matters:
+
+- The LLM is **not event-driven**. When the worker finishes writing
+  `subprocess_status: "done"` to `state.json`, nothing wakes the orchestrator.
+  The orchestrator only notices when it next calls `multi_llm_review_collect`.
+- `multi_llm_review_collect` already polls internally at
+  `poll_interval_seconds: 0.5` for up to `collect_max_wait_seconds: 420` (7min)
+  per call. Polling is not the bottleneck — the bottleneck is the orchestrator
+  forgetting to call collect at all.
+- The token expires at `collect_deadline` (default 30min since v3.23.2). If
+  user dialogue or other work intervenes between persona Agent completion and
+  the collect call, the token can expire while the subprocess results sit
+  ready and unread on disk.
+
+Recommended orchestrator flow (single LLM turn, no detours):
+
+```
+1. multi_llm_review(...) → receive delegation_pending + collect_token
+2. Spawn persona Agent reviews (Agent tool, parallel, 2-4 personas)
+3. As soon as ALL personas return → multi_llm_review_collect(collect_token, ...)
+4. Return final consensus to user
+```
+
+Anti-pattern (do NOT do this):
+
+```
+1. multi_llm_review(...) → delegation_pending
+2. Run persona Agent reviews
+3. ❌ "By the way, while we wait, let me explain X to the user…"
+4. ❌ User asks an unrelated question, conversation drifts
+5. ❌ 30+ minutes later, finally try collect → expired_or_unknown_token
+```
+
+If the orchestrator is genuinely interrupted (user explicitly switches topic,
+or persona Agent itself takes a long time and the orchestrator wants to
+report progress), it should still **call collect first** — collect returns
+quickly if the worker is already done, or blocks up to 7min if not. Either
+way, the token stays alive and consensus is captured before resuming side
+work.
+
+Manual recovery if expiry happens: subprocess results are persisted at
+`.kairos/multi_llm_review/pending/<token>/subprocess_results.json` and remain
+readable until GC. Read them directly and synthesize manually, then re-run
+`multi_llm_review` for fresh results if needed.
+
 ### Critical CLI Notes
 
 - **Cursor Agent stdin**: `cat file | agent -p -` does NOT work. Use file-reference:

data/templates/skillsets/agent/config/agent.yml

@@ -107,12 +107,25 @@ complexity_review:
   post_act_review: true                       # enable medium-complexity post-ACT review
   # Multi-LLM review integration (Gate 5.5c)
   multi_llm_review:
-    enabled: false              # opt-in: enable for multi-LLM review during autonomous mode
-    trigger_on:                 # complexity signals that trigger multi-LLM review
+    # Phase 12 PR2: KairosChain framework default — multi-LLM review is on by
+    # default as structural compensation for current LLM metacognition limits.
+    # See knowledge: project_multi_llm_review_default_philosophy.
+    # Override with `enabled: false` if you specifically need legacy single-LLM
+    # behavior; `system_upgrade` 3-way merge preserves user overrides.
+    enabled: true
+    # rule_or_hint (default): OR-floor — review fires when EITHER the deterministic
+    #   rule (trigger_on ∩ complexity[:signals]) fires OR the LLM-emitted
+    #   review_hint.needed=true. The hint is ADDITIVE only; it cannot suppress the
+    #   rule (Phase 12 §3.2 trust boundary).
+    # rule_only: legacy/diagnostic — ignore review_hint, rule path only.
+    # unknown values: fail-closed to rule_only (most restrictive).
+    trigger_mode: rule_or_hint
+    trigger_on:                 # validated against KNOWN_SIGNALS at session start (§12)
       - l0_change
       - design_scope
     max_concurrent: 2           # override Dispatcher default
     timeout_seconds: 300
+    insufficient_first_attempt: retry  # retry | checkpoint (§3.8)
     # Reviewer roster delegates to multi_llm_review/config/multi_llm_review.yml
 
 # Audit

data/templates/skillsets/agent/lib/agent/review_hint.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module KairosMcp
+  module SkillSets
+    module Agent
+      # Strict validator for the LLM-emitted review_hint structure (Phase 12 §3.6).
+      #
+      # Critical property: this hint is ADDITIVE only (§3.2 OR-floor). A return value
+      # of `false` does NOT suppress rule-based triggers — rule_fired || hint_needed.
+      # Therefore malformed hints fail-through to `false` (no review request from
+      # this side), and the OR-floor lets the deterministic rule path fire on its own.
+      #
+      # Schema:
+      #   review_hint: {
+      #     needed:  Boolean,
+      #     reason:  String  | nil,
+      #     urgency: 'low' | 'medium' | 'high' | nil
+      #   }
+      class ReviewHint
+        VALID_URGENCY = %w[low medium high].freeze
+
+        # PR3 hardening: per-process counter of validation failures, exposed for
+        # observability. agent_status / introspection tools may read this to
+        # surface drift (e.g., DECIDE LLM repeatedly emitting malformed hints).
+        # Reset by tests via reset_failure_count!.
+        @failure_count = 0
+        class << self
+          attr_reader :failure_count
+        end
+
+        def self.reset_failure_count!
+          @failure_count = 0
+        end
+
+        # Parse and validate. Returns boolean.
+        # On any validation failure, returns false (and logs + increments counter).
+        # The counter exposes audit signal without forcing a chain_record dependency
+        # in this hot path (Phase 12 kairos Prop 3: recognition without raise/break,
+        # but observable through @failure_count + log).
+        def self.parse(raw, logger: nil)
+          return false unless raw.is_a?(Hash)
+
+          needed = raw['needed']
+          unless needed == true || needed == false
+            note_failure(logger, "review_hint.needed must be boolean, got #{needed.inspect}")
+            return false
+          end
+
+          reason = raw['reason']
+          unless reason.nil? || reason.is_a?(String)
+            note_failure(logger, "review_hint.reason must be string or nil, got #{reason.class}")
+            return false
+          end
+
+          urgency = raw['urgency']
+          unless urgency.nil? || VALID_URGENCY.include?(urgency)
+            note_failure(logger, "review_hint.urgency must be one of #{VALID_URGENCY} or nil, got #{urgency.inspect}")
+            return false
+          end
+
+          needed
+        rescue StandardError => e
+          note_failure(logger, "review_hint parse error: #{e.class}: #{e.message}")
+          false
+        end
+
+        def self.note_failure(logger, msg)
+          @failure_count += 1
+          log(logger, msg)
+        end
+        private_class_method :note_failure
+
+        def self.log(logger, msg)
+          if logger
+            logger.warn("[review_hint] #{msg}")
+          else
+            warn "[review_hint] #{msg}"
+          end
+        end
+        private_class_method :log
+      end
+    end
+  end
+end

data/templates/skillsets/agent/lib/agent/trigger_validator.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module KairosMcp
+  module SkillSets
+    module Agent
+      # Validates agent.yml's complexity_review.multi_llm_review.trigger_on against
+      # the actual signal vocabulary produced by assess_decision_complexity.
+      #
+      # Phase 12 §12 / v0.4 P-1. Aligned with agent_step.rb:1005-1031.
+      #
+      # Fail-loud at session start (not silently at first cycle) so typos like
+      # "l0_chagne" don't bypass the review gate at runtime.
+      class TriggerValidator
+        KNOWN_SIGNALS = %w[
+          high_risk
+          many_steps
+          design_scope
+          l0_change
+          core_files
+          multi_file
+          state_mutation
+        ].freeze
+
+        class ConfigurationError < StandardError; end
+
+        # @param trigger_on [Array<String>] from agent.yml
+        # @param multi_cfg [Hash, nil] complexity_review.multi_llm_review subtree;
+        #   when provided, validate! warns on the rule_only + enabled + empty
+        #   trigger_on combination (review gate effectively disabled despite enabled:true).
+        # @return [Array<String>] the validated, stringified signals (echo of input)
+        # @raise [ConfigurationError] on unknown signal name
+        def self.validate!(trigger_on, multi_cfg: nil)
+          stringified = Array(trigger_on).map(&:to_s)
+          if stringified.empty?
+            warn_if_review_unreachable(multi_cfg)
+            return []
+          end
+          unknown = stringified - KNOWN_SIGNALS
+          unless unknown.empty?
+            raise ConfigurationError,
+                  "agent.yml complexity_review.multi_llm_review.trigger_on contains " \
+                  "unknown signals: #{unknown.inspect}. Known: #{KNOWN_SIGNALS.inspect}"
+          end
+          stringified
+        end
+
+        # PR3 hardening: surface configuration that would silently disable the
+        # review gate. enabled:true + trigger_on:[] under rule_only mode means
+        # rule never fires; under rule_or_hint, only LLM hints can ever trigger
+        # which is unreliable. Either case warrants an operator warning.
+        def self.warn_if_review_unreachable(multi_cfg)
+          return unless multi_cfg.is_a?(Hash) && multi_cfg['enabled']
+          mode = multi_cfg['trigger_mode'] || 'rule_or_hint'
+          if mode == 'rule_only'
+            warn '[trigger_validator] WARNING: enabled:true but trigger_on:[] with ' \
+                 'trigger_mode:rule_only — review gate cannot fire. ' \
+                 'Either populate trigger_on (e.g. [l0_change, design_scope]) or ' \
+                 'set trigger_mode:rule_or_hint to allow LLM hints to trigger review.'
+          else
+            warn '[trigger_validator] note: trigger_on:[] under rule_or_hint — ' \
+                 'review gate fires only on LLM-emitted review_hint.needed=true. ' \
+                 'Consider adding [l0_change, design_scope] for structural floor.'
+          end
+        end
+        private_class_method :warn_if_review_unreachable
+      end
+    end
+  end
+end

data/templates/skillsets/agent/lib/agent.rb

@@ -4,3 +4,5 @@ require_relative 'agent/session'
 require_relative 'agent/message_format'
 require_relative 'agent/cognitive_loop'
 require_relative 'agent/mandate_adapter'
+require_relative 'agent/review_hint'
+require_relative 'agent/trigger_validator'

data/templates/skillsets/agent/test/test_agent_complexity_review.rb

@@ -345,11 +345,17 @@ assert "test_merge_llm_cannot_lower: LLM low + structural high → final high" d
   result[:level] == 'high'
 end
 
-assert "test_merge_llm_same_level: LLM medium + structural medium → final medium" do
+assert "test_merge_llm_same_level: LLM medium + structural medium → final medium (signals trust-quarantined)" do
+  # Phase 12 §3.2 / v0.4 P-2 trust boundary: LLM-emitted signals MUST NOT enter
+  # :signals (which is the OR-floor input). They go into :complexity_hint_signals
+  # (advisory only). This test verifies the quarantine.
   structural = { level: 'medium', signals: ['high_risk'] }
   llm_hint = { 'level' => 'medium', 'signals' => ['moderate_scope'] }
   result = step.send(:merge_complexity, structural, llm_hint)
-  result[:level] == 'medium' && result[:signals].include?('moderate_scope')
+  result[:level] == 'medium' &&
+    result[:signals] == ['high_risk'] &&
+    !result[:signals].include?('moderate_scope') &&
+    result[:complexity_hint_signals].include?('moderate_scope')
 end
 
 assert "test_merge_nil_hint: nil LLM hint → structural unchanged" do
@@ -358,11 +364,13 @@ assert "test_merge_nil_hint: nil LLM hint → structural unchanged" do
   result[:level] == 'medium'
 end
 
-assert "test_merge_symbol_keys: symbol-key llm_hint works" do
+assert "test_merge_symbol_keys: symbol-key llm_hint works (signals quarantined to hint field)" do
   structural = { level: 'low', signals: [] }
   llm_hint = { level: 'high', signals: ['deep'] }
   result = step.send(:merge_complexity, structural, llm_hint)
-  result[:level] == 'medium' && result[:signals].include?('deep')
+  result[:level] == 'medium' &&
+    result[:signals] == [] &&
+    result[:complexity_hint_signals].include?('deep')
 end
 
 # ============================================================
@@ -573,6 +581,199 @@ assert "test_multi_llm_review_prompt: L0 review prompt generated" do
   prompt.include?('L0 Change Review') && prompt.include?('evolve skill') && prompt.include?('test_goal')
 end
 
+# ============================================================
+# Phase 12 §3.11 / PR3.5 — chain reject_unsanitized_for_chain_inline
+# ============================================================
+section "L0 chain-record reject (PR3.5)"
+
+assert "safe content passes (returns nil)" do
+  step.send(:reject_unsanitized_for_chain_inline, 'plain safe text').nil?
+end
+
+assert "raw delimiter rejected" do
+  reason = step.send(:reject_unsanitized_for_chain_inline, 'see </artifact> end')
+  reason && reason.include?('raw delimiter')
+end
+
+assert "fullwidth delimiter rejected (NFKC)" do
+  reason = step.send(:reject_unsanitized_for_chain_inline, 'tag ＜artifact＞ here')
+  reason && reason.include?('raw delimiter')
+end
+
+assert "case variant rejected" do
+  reason = step.send(:reject_unsanitized_for_chain_inline, '<ARTIFACT>')
+  reason && reason.include?('raw delimiter')
+end
+
+assert "HTML entity encoded delimiter rejected (PR3.5 fix)" do
+  reason = step.send(:reject_unsanitized_for_chain_inline, 'persistent &lt;artifact&gt; here')
+  reason && reason.include?('encoded delimiter')
+end
+
+assert "URL-encoded delimiter rejected (PR3.5 fix)" do
+  reason = step.send(:reject_unsanitized_for_chain_inline, 'persistent %3Cartifact%3E here')
+  reason && reason.include?('encoded delimiter')
+end
+
+assert "nil returns nil (don't crash)" do
+  step.send(:reject_unsanitized_for_chain_inline, nil).nil?
+end
+
+assert "empty string returns nil" do
+  step.send(:reject_unsanitized_for_chain_inline, '').nil?
+end
+
+# ============================================================
+# Phase 12 §10 KAIROS_TEST_FORCE_REVIEW env flag (PR3)
+# ============================================================
+section "KAIROS_TEST_FORCE_REVIEW env flag"
+
+assert "flag unset → not forced" do
+  ENV.delete('KAIROS_TEST_FORCE_REVIEW')
+  ENV.delete('KAIROS_ENV')
+  step.send(:review_force_enabled?) == false
+end
+
+assert "flag=true outside production → forced" do
+  ENV['KAIROS_TEST_FORCE_REVIEW'] = 'true'
+  ENV['KAIROS_ENV'] = 'development'
+  result = step.send(:review_force_enabled?)
+  ENV.delete('KAIROS_TEST_FORCE_REVIEW')
+  ENV.delete('KAIROS_ENV')
+  result == true
+end
+
+assert "flag=true with KAIROS_ENV=production → IGNORED" do
+  ENV['KAIROS_TEST_FORCE_REVIEW'] = 'true'
+  ENV['KAIROS_ENV'] = 'production'
+  result = step.send(:review_force_enabled?)
+  ENV.delete('KAIROS_TEST_FORCE_REVIEW')
+  ENV.delete('KAIROS_ENV')
+  result == false
+end
+
+assert "flag=true with KAIROS_ENV=PRODUCTION (case insensitive) → IGNORED" do
+  ENV['KAIROS_TEST_FORCE_REVIEW'] = 'true'
+  ENV['KAIROS_ENV'] = 'PRODUCTION'
+  result = step.send(:review_force_enabled?)
+  ENV.delete('KAIROS_TEST_FORCE_REVIEW')
+  ENV.delete('KAIROS_ENV')
+  result == false
+end
+
+assert "flag=anything-else → not forced" do
+  ENV['KAIROS_TEST_FORCE_REVIEW'] = '1'  # not 'true' literally
+  result = step.send(:review_force_enabled?)
+  ENV.delete('KAIROS_TEST_FORCE_REVIEW')
+  result == false
+end
+
+# ============================================================
+# Phase 12 §3.10 schema_version validation (PR2)
+# ============================================================
+section "Schema version validation (fail-closed)"
+
+assert "current schema (v=1, f=1) → no error" do
+  step.send(:schema_version_check, {
+    'verdict_schema_version' => 1, 'feedback_text_schema_version' => 1
+  }).nil?
+end
+
+assert "missing verdict_schema_version → reject" do
+  msg = step.send(:schema_version_check, { 'feedback_text_schema_version' => 1 })
+  msg && msg.include?('verdict_schema_version missing')
+end
+
+assert "missing feedback_text_schema_version → reject" do
+  msg = step.send(:schema_version_check, { 'verdict_schema_version' => 1 })
+  msg && msg.include?('feedback_text_schema_version missing')
+end
+
+assert "newer verdict_schema_version → reject (fail-closed)" do
+  msg = step.send(:schema_version_check, {
+    'verdict_schema_version' => 99, 'feedback_text_schema_version' => 1
+  })
+  msg && msg.include?('newer than supported')
+end
+
+assert "newer feedback_text_schema_version → reject" do
+  msg = step.send(:schema_version_check, {
+    'verdict_schema_version' => 1, 'feedback_text_schema_version' => 99
+  })
+  msg && msg.include?('newer than supported')
+end
+
+# ============================================================
+# Phase 12 §3.2 OR-floor trigger (PR2)
+# ============================================================
+section "OR-floor trigger logic"
+
+assert "rule_or_hint: rule fires (l0_change in signals) → review needed" do
+  cfg = { 'enabled' => true, 'trigger_mode' => 'rule_or_hint',
+          'trigger_on' => ['l0_change', 'design_scope'] }
+  complexity = { signals: ['l0_change'] }
+  decision = { 'review_hint' => { 'needed' => false } }
+  step.send(:multi_llm_review_needed?, cfg, complexity, decision) == true
+end
+
+assert "rule_or_hint: needed:false CANNOT suppress rule (critical OR-floor property)" do
+  cfg = { 'enabled' => true, 'trigger_mode' => 'rule_or_hint',
+          'trigger_on' => ['l0_change'] }
+  complexity = { signals: ['l0_change'] }                    # rule fires
+  decision = { 'review_hint' => { 'needed' => false } }      # hint suppresses... but rule wins
+  step.send(:multi_llm_review_needed?, cfg, complexity, decision) == true
+end
+
+assert "rule_or_hint: hint:true raises gate when rule does NOT fire" do
+  cfg = { 'enabled' => true, 'trigger_mode' => 'rule_or_hint',
+          'trigger_on' => ['l0_change'] }
+  complexity = { signals: ['high_risk'] }                    # rule does not fire
+  decision = { 'review_hint' => { 'needed' => true, 'urgency' => 'high' } }
+  step.send(:multi_llm_review_needed?, cfg, complexity, decision) == true
+end
+
+assert "rule_or_hint: neither rule nor hint → no review" do
+  cfg = { 'enabled' => true, 'trigger_mode' => 'rule_or_hint',
+          'trigger_on' => ['l0_change'] }
+  complexity = { signals: ['high_risk'] }
+  decision = { 'review_hint' => { 'needed' => false } }
+  step.send(:multi_llm_review_needed?, cfg, complexity, decision) == false
+end
+
+assert "rule_or_hint: malformed review_hint falls through to rule (additive contract)" do
+  cfg = { 'enabled' => true, 'trigger_mode' => 'rule_or_hint',
+          'trigger_on' => ['l0_change'] }
+  complexity = { signals: ['l0_change'] }
+  decision = { 'review_hint' => { 'needed' => 'yes' } }      # malformed string
+  # ReviewHint.parse → false; OR-floor still uses rule which fires
+  step.send(:multi_llm_review_needed?, cfg, complexity, decision) == true
+end
+
+assert "rule_only: ignores review_hint even when needed:true" do
+  cfg = { 'enabled' => true, 'trigger_mode' => 'rule_only',
+          'trigger_on' => ['l0_change'] }
+  complexity = { signals: ['high_risk'] }                    # rule does NOT fire
+  decision = { 'review_hint' => { 'needed' => true, 'urgency' => 'high' } }
+  step.send(:multi_llm_review_needed?, cfg, complexity, decision) == false
+end
+
+assert "unknown trigger_mode → fail-closed to rule_only" do
+  cfg = { 'enabled' => true, 'trigger_mode' => 'evil_typo',
+          'trigger_on' => ['l0_change'] }
+  complexity = { signals: ['high_risk'] }                    # rule does not fire
+  decision = { 'review_hint' => { 'needed' => true } }       # would have raised under rule_or_hint
+  # fails closed to rule_only → hint ignored → false
+  step.send(:multi_llm_review_needed?, cfg, complexity, decision) == false
+end
+
+assert "missing review_hint key in payload is treated as no hint" do
+  cfg = { 'enabled' => true, 'trigger_mode' => 'rule_or_hint',
+          'trigger_on' => ['l0_change'] }
+  complexity = { signals: ['high_risk'] }
+  decision = {}  # no review_hint
+  step.send(:multi_llm_review_needed?, cfg, complexity, decision) == false
+end
+
 # ============================================================
 # Summary
 # ============================================================