eduevidence 6.2.0 → 6.3.0

package/scripts/orchestrator.py

@@ -60,6 +60,13 @@ from pre_verdict_gate import apply_enforcement, evaluate_workspace  # noqa: E402
 from engine.versions import ENGINE_VERSION  # noqa: E402
 from engine.log import enable_console_logging, get_log  # noqa: E402
 
+# One-shot two-round intake + prefs (scripts/intake/). Soft-import so the
+# orchestrator still starts if intake is stripped from a minimal package.
+try:
+    from intake import hooks as _intake_hooks  # noqa: E402
+except Exception:  # pragma: no cover - optional adapter
+    _intake_hooks = None
+
 log = get_log("orchestrator")
 
 DEPTH_ALIASES = {"quick": "S", "standard": "M", "deep": "L"}
@@ -546,6 +553,10 @@ def _run_adjudicate(ws: RunWorkspace, question: str,
         json.dumps(final, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
 
     post = evaluate_workspace(ws.path, require_final=True)
+    if not post.get("passed") or post.get("critical_failures"):
+        final = apply_enforcement(final, post)
+        (ws.path / "final_verdict.json").write_text(
+            json.dumps(final, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
     gate_report = {"run_id": ws.run_id, "stage": "adjudicate",
                    "pre": {"passed": pre["passed"], "max_confidence": pre["max_confidence"],
                            "critical_failures": pre["critical_failures"]},
@@ -571,8 +582,7 @@ def _run_adjudicate(ws: RunWorkspace, question: str,
 
 def _assemble_result(ws: RunWorkspace, manifest: dict[str, Any]) -> dict[str, Any]:
     """Assemble result.json from workspace artifacts (decision=final_verdict.json)."""
-    from build_result import (NOT_CAPTURED_USAGE, OUTCOME_ORDER,
-                              aggregate_outcomes, build_claims,
+    from build_result import (NOT_CAPTURED_USAGE, aggregate_outcomes, build_claims,
                               build_outcome_mapping, derive_provenance)
 
     frame = load_json(ws.path / "frame.json")
@@ -976,13 +986,45 @@ def load_global_approval() -> dict | None:
 
 
 def _cmd_run(args: argparse.Namespace) -> int:
-    approve = args.approve_agent_mcp or interactive_agent_mcp_setup(args.approve_agent_mcp)
-    approval_record = None
-    if approve:
-        approval_record = load_global_approval()
-    ws = init_run(Path(args.runs_dir), args.question, depth=args.depth, run_id=args.run_id,
+    """Create a run workspace. Delegates intake/open to scripts/intake/hooks.py."""
+    assume_yes = bool(getattr(args, "yes", False))
+    domain = getattr(args, "domain", "education")
+    enhancements = list(getattr(args, "enhancement", None) or []) or None
+    intake_record: dict[str, Any] | None = None
+
+    if _intake_hooks is not None:
+        ctx = _intake_hooks.prepare_run(
+            question=args.question,
+            depth=getattr(args, "depth", None),
+            enhancements=enhancements,
+            domain=domain,
+            assume_yes=assume_yes,
+        )
+        if ctx.get("error"):
+            print(f"ERROR: intake failed: {ctx['error']}", file=sys.stderr)
+            return 2
+        question, depth_arg = ctx["question"], ctx["depth"]
+        enhancements, intake_record = ctx["enhancements"], ctx["intake_record"]
+        wants_mcp = ctx["wants_mcp"]
+    else:
+        question = args.question
+        depth_arg = DEPTH_ALIASES.get(getattr(args, "depth", None) or "M",
+                                     getattr(args, "depth", None) or "M")
+        if depth_arg not in DEPTHS:
+            depth_arg = "M"
+        wants_mcp = bool(enhancements and "agent_mcp" in enhancements
+                         and "none" not in enhancements)
+
+    approve = bool(args.approve_agent_mcp)
+    if wants_mcp and not assume_yes and sys.stdin.isatty():
+        approve = approve or interactive_agent_mcp_setup(approve)
+    approval_record = load_global_approval() if approve else None
+
+    ws = init_run(Path(args.runs_dir), question, depth=depth_arg, run_id=args.run_id,
                   approve_agent_mcp=approve, approval_record=approval_record,
-                  domain=getattr(args, "domain", "education"))
+                  domain=domain)
+    if _intake_hooks is not None:
+        _intake_hooks.write_intake_artifact(ws.path, intake_record)
     print(f"workspace created: {ws.path}")
     print(f"manifest: {json.dumps(ws.load_manifest(), ensure_ascii=False, indent=2)}")
     if args.dry_run:
@@ -990,9 +1032,9 @@ def _cmd_run(args: argparse.Namespace) -> int:
         return 0
     summary = advance(ws, demo_pack=args.demo_pack)
     print(json.dumps(summary, ensure_ascii=False, indent=2))
-    if summary["failures"]:
-        return 1
-    return 0
+    if _intake_hooks is not None:
+        _intake_hooks.after_run(ws.path, intake_record=intake_record, summary=summary)
+    return 1 if summary["failures"] else 0
 
 
 def _print_status(ws) -> None:
@@ -1087,7 +1129,7 @@ def _cmd_domain(args) -> int:
 
 def _cmd_living(args) -> int:
     from engine.project import ProjectWorkspace
-    from engine.living import create_subscription, refresh, set_subscription_status
+    from engine.living import create_subscription, refresh
     home = _home(args)
     ws = ProjectWorkspace.open(home, args.project)
     if args.action == "subscribe":
@@ -1107,7 +1149,6 @@ def _cmd_living(args) -> int:
         print(drift.get("summary", ""))
         return 0
     if args.action == "status":
-        from pathlib import Path as _P
         import json as _json
         p = ws.path / "living" / "subscriptions" / f"{args.subscription}.json"
         if not p.is_file():
@@ -1319,7 +1360,7 @@ def _cmd_study(args) -> int:
             print(e, file=sys.stderr)
         return 1
     from engine.study_design import save_study_design
-    path = save_study_design(ws, design)
+    save_study_design(ws, design)   # persists study-designs/<id>.json
     print(design["design_id"])
     return 0
 
@@ -1397,7 +1438,8 @@ def _cmd_migrate(args) -> int:
 
 def _cmd_dashboard(args) -> int:
     from dashboard_server import run_dashboard_server
-    run_dashboard_server(host=args.host, port=args.port)
+    run_dashboard_server(host=args.host, port=args.port,
+                         open_browser=bool(getattr(args, "open", False)))
     return 0
 
 
@@ -1455,13 +1497,20 @@ def main(argv: list[str] | None = None) -> int:
     p_run.add_argument("--domain", default="education", metavar="ID",
                        help="registered research domain (default: education; "
                             "see `domain list`)")
-    p_run.add_argument("--depth", default="M", choices=["quick", "standard", "deep", "S", "M", "L"],
-                       help="complexity depth (default: standard/M)")
+    p_run.add_argument("--depth", default=None,
+                       choices=["quick", "standard", "deep", "S", "M", "L", "auto"],
+                       help="complexity depth (S/M/L/auto or quick/standard/deep; "
+                            "default: intake/prefs auto guideline)")
     p_run.add_argument("--run-id", default=None, help="explicit run id (default: timestamp)")
     p_run.add_argument("--demo-pack", default=None, type=Path,
                        help="seed external stages from an example pack (demo/test mode)")
     p_run.add_argument("--approve-agent-mcp", action="store_true",
                        help="record agent-mcp approval in the manifest")
+    p_run.add_argument("--yes", action="store_true",
+                       help="skip the two-round intake prompts; use prefs + flags unattended")
+    p_run.add_argument("--enhancement", action="append", default=None,
+                       choices=["agent_mcp", "jev", "semdecide", "none"],
+                       help="execution enhancement (repeatable; used by intake)")
     p_run.add_argument("--dry-run", action="store_true", help="initialize only, do not advance")
     p_run.add_argument("--runs-dir", default=os.environ.get("EDUEVIDENCE_RUNS_DIR", str(ROOT / "runs")),
                        help="directory holding run workspaces (default: <repo>/runs)")
@@ -1645,6 +1694,8 @@ def main(argv: list[str] | None = None) -> int:
     p_dash = sub.add_parser("dashboard", help="start local research & token dashboard")
     p_dash.add_argument("--host", default="127.0.0.1")
     p_dash.add_argument("--port", type=int, default=8765)
+    p_dash.add_argument("--open", action="store_true",
+                        help="open the Studio URL in the system browser once the server is up")
     p_dash.set_defaults(func=_cmd_dashboard)
 
     p_srch = sub.add_parser("search", help="multi-channel hybrid search")

package/scripts/pre_verdict_gate.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """pre_verdict_gate.py — Pre-Verdict Gate (Phase 15).
 
-An 11-item checklist that must pass (or be explicitly degraded) before a
+A 12-item checklist that must pass (or be explicitly degraded) before a
 verdict may carry a high confidence label. The gate is deterministic and
 reads ONLY the run workspace — no model call, no network.
 
@@ -417,19 +417,25 @@ def check_decision_action(ws: Path) -> dict[str, str]:
         label = action or "unset"
         return _item_res("pass", "action=" + label + " is within the conservative bound")
 
-    from engine.decision_policy import ADOPT_REQUIRED_LABEL, decision_action
+    from engine.decision_policy import (
+        ADOPT_REQUIRED_LABEL,
+        decision_outcome,
+    )
 
     evidence = _load_ws_jsonl(ws, "evidence.jsonl")
     relations = [decision_relation(ev) for ev in evidence]
     decisive = {str(index): rel for index, rel in enumerate(relations)
-                if rel in ("support_adoption", "oppose_adoption")}
+                if rel in ("support_adoption", "oppose_adoption",
+                           "conditional", "conflict", "mixed")}
     label = str(verdict.get("confidence") or "")
     summary = _primary_evidence_summary(ws)
-    expected = decision_action(
+    outcome = decision_outcome(
         confidence_label=label,
         decisive_relations=decisive,
         has_direct_primary_evidence=bool(summary.get("direct")),
     )
+    expected = outcome["action"]
+    downgrade_reason = outcome.get("downgrade_reason")
     if expected == "ADOPT":
         detail = "ADOPT is supported: " + label + " confidence with direct primary-outcome evidence"
         return _item_res("pass", detail)
@@ -440,8 +446,11 @@ def check_decision_action(ws: Path) -> dict[str, str]:
         reasons.append("no decisive supporting evidence")
     if not summary.get("direct"):
         reasons.append("no primary-outcome evidence at directness 2")
+    if downgrade_reason:
+        reasons.append("downgrade_reason=" + downgrade_reason)
     detail = ("recommended_action=adopt is not supported (" + "; ".join(reasons)
-              + "); the evidence bounds this decision to pilot")
+              + "); the evidence bounds this decision to "
+              + str(expected).lower())
     return _item_res("fail", detail)
 
 
@@ -580,7 +589,7 @@ GATE_ITEMS: list[dict[str, Any]] = [
 
 
 def evaluate_workspace(workspace: Path, *, require_final: bool = True) -> dict[str, Any]:
-    """Run the 11-item gate over a run workspace. Pure, deterministic, read-only."""
+    """Run the 12-item gate over a run workspace. Pure, deterministic, read-only."""
     ws = Path(workspace)
     items: dict[str, dict[str, Any]] = {}
     for spec in GATE_ITEMS:
@@ -641,11 +650,15 @@ def apply_enforcement(verdict: dict[str, Any], gate: dict[str, Any]) -> dict[str
     current = out.get("confidence", "Insufficient")
     if CONFIDENCE_RANK.get(current, 0) > CONFIDENCE_RANK.get(cap, 0):
         out["confidence"] = cap
+    downgrade_reason = None
     if not gate.get("passed", False) and out.get("recommended_action") == "adopt":
         out["recommended_action"] = "pilot"
+        downgrade_reason = "gate_critical"
     action_item = (gate.get("items") or {}).get("decision_action_consistency") or {}
     if action_item.get("status") == "fail" and out.get("recommended_action") == "adopt":
         out["recommended_action"] = "pilot"
+        if downgrade_reason is None:
+            downgrade_reason = "missing_direct_primary"
     extensions = out.setdefault("extensions", {})
     if not isinstance(extensions, dict):
         extensions = {}
@@ -659,6 +672,7 @@ def apply_enforcement(verdict: dict[str, Any], gate: dict[str, Any]) -> dict[str
         "max_confidence": cap,
         "confidence_before": current,
         "action_before": verdict.get("recommended_action"),
+        "downgrade_reason": downgrade_reason,
     })
     return out
 
@@ -667,7 +681,7 @@ def apply_enforcement(verdict: dict[str, Any], gate: dict[str, Any]) -> dict[str
 
 
 def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(description="EduEvidence Pre-Verdict Gate (11-item checklist)")
+    parser = argparse.ArgumentParser(description="EduEvidence Pre-Verdict Gate (12-item checklist)")
     parser.add_argument("--workspace", required=True, help="run workspace directory (runs/<run_id>)")
     parser.add_argument("--require-final", action="store_true",
                         help="item 11 fails when final_verdict.json is missing (default: warn)")

package/scripts/skill_lint.py

@@ -13,7 +13,6 @@ Usage:
 """
 from __future__ import annotations
 
-import os
 import re
 import sys
 from pathlib import Path
@@ -130,6 +129,17 @@ def lint_skill() -> list[str]:
         if re.search(r"theme-btn|theme-switcher|data-theme-target", ltext):
             errors.append("scripts/render_report_html.py still contains runtime theme switcher")
 
+    # 10. File-layer hard gate (also runnable alone: python3 scripts/lint_file_layers.py)
+    try:
+        sys.path.insert(0, str(ROOT / "scripts"))
+        from lint_file_layers import check_file_layers  # noqa: PLC0415
+        layer_errors, layer_warnings = check_file_layers()
+        errors.extend(layer_errors)
+        for w in layer_warnings:
+            print(f"    ! {w}")
+    except Exception as exc:  # pragma: no cover - lint must still run
+        errors.append(f"file-layer gate failed to load: {exc}")
+
     return errors
 
 

package/scripts/skill_payload.py

@@ -7,6 +7,7 @@ import sys
 
 TREES = (
     "agents", "engine", "domains", "skill", "references", "schemas", "scripts",
+    "integrations", "visualization/eduevidence-report",
     "retrieval", "integrations", "visualization/eduevidence-report", "web/studio",
     "assets/readme",
 )
@@ -22,7 +23,7 @@ DOCS = (
     "reproducibility.md", "release-contract.md", "autoresearch-evolution-plan.md",
     "orchestration-role-model.md", "autoresearch-implementation-status.md",
     "research-studio-guide.zh-CN.md", "demo-workplace-ai.md",
-    "sciverse-api.md",
+    "sciverse-api.md", "j-ev-experimental.md",
     "release-closeout/README.md", "release-closeout/issues.md",
     "release-closeout/frontend-acceptance.md", "release-closeout/verification.md",
 )
@@ -37,8 +38,7 @@ EXAMPLE_FILES = (
 )
 RETIRED_DEMO_SCRIPTS = {
     "scripts/build_esl_artifacts.py", "scripts/generate_new_projects.py",
-    "scripts/enrich_projects_human_and_lieflat.py", "scripts/build_killer_demo.py",
-    "scripts/sync_killer_demo_report.py",
+    "scripts/enrich_projects_human_and_lieflat.py",
 }
 
 

package/scripts/test_adversarial_empirical.py

@@ -44,7 +44,6 @@ from engine.evidence_graph import (
 )
 from engine.gap_lens import gap_lens
 from engine.semantics import OutcomeClassifier, OutcomeDimension
-from engine.tribunal import _confidence, _decision_action, _study_implication
 from retrieval.corpus_store import DomainCorpusStore, corpus_store
 from retrieval.search import search_evidence, search_router
 from scripts.did_regression import run_did_analysis
@@ -444,15 +443,21 @@ def test_offline_corpus_and_network_isolation():
 def test_dashboard_server_adversarial():
     print_section("TEST 6: Dashboard Server Concurrency, SSE Disconnection & Source Leakage")
 
-    import socketserver
+    import http.server
     from scripts.dashboard_server import StudioHandler
 
-    class _ReuseServer(socketserver.TCPServer):
-        # allow_reuse_address 必须在 bind() 之前生效（构造时读取类属性）
+    class _AdversarialServer(http.server.ThreadingHTTPServer):
+        # Exercise the class the shipped server actually runs
+        # (scripts/dashboard_server.py run_dashboard_server -> ThreadingHTTPServer).
+        # A single-threaded socketserver.TCPServer answers a 30-client burst from a
+        # 5-slot accept queue, and the kernel resets the overflow ([Errno 54]
+        # on macOS). That harness choice - not the product - caused the resets.
         allow_reuse_address = True
+        request_queue_size = 128  # the 30 simultaneous connects below must fit
+        daemon_threads = True
 
     test_port = 0  # 临时端口：避免与常驻服务/上次残留监听冲突
-    server = _ReuseServer(("127.0.0.1", test_port), StudioHandler)
+    server = _AdversarialServer(("127.0.0.1", test_port), StudioHandler)
     test_port = server.server_address[1]
     
     t = threading.Thread(target=server.serve_forever, daemon=True)
@@ -517,9 +522,68 @@ def test_dashboard_server_adversarial():
             futures = [executor.submit(fetch_data, i) for i in range(30)]
             statuses = [f.result() for f in futures]
         elapsed = time.time() - t0
+        assert statuses == [200] * 30, (
+            "30 concurrent /api/projects requests did not all succeed: "
+            f"statuses={sorted(set(statuses))}")
         print(f"    - 30 concurrent requests finished in {elapsed:.3f}s (all status: 200).")
-        print(f"    - Note: TCPServer is single-threaded; requests are strictly serialized.")
+        print(f"    - Note: the shipped server is ThreadingHTTPServer; requests are served concurrently.")
         results["concurrency_30_time"] = elapsed
+        results["concurrency_30_statuses"] = statuses
+
+        # 4. Host / CSRF guards (dashboard_server.py do_GET) must fail closed on
+        #    the projection API, without blocking legitimate same-origin readers.
+        def raw_get(request: str) -> tuple[int, str]:
+            """Send one raw HTTP request; return (status_code, body snippet)."""
+            sock = socket.create_connection(("127.0.0.1", test_port), timeout=5)
+            sock.settimeout(3)
+            try:
+                sock.sendall(request.encode("latin-1"))
+                buf = b""
+                while len(buf) < 16384:
+                    try:
+                        chunk = sock.recv(4096)
+                    except socket.timeout:
+                        break
+                    if not chunk:
+                        break
+                    buf += chunk
+            finally:
+                sock.close()
+            head, _, body = buf.partition(b"\r\n\r\n")
+            first_line = head.split(b"\r\n", 1)[0].decode("latin-1", errors="ignore")
+            fields = first_line.split(" ")
+            status = int(fields[1]) if len(fields) > 1 and fields[1].isdigit() else 0
+            return status, body.decode("utf-8", errors="ignore")[:200]
+
+        untrusted_status, untrusted_body = raw_get(
+            "GET /api/projects HTTP/1.1\r\nHost: evil.example.com\r\n\r\n")
+        assert untrusted_status == 403, (
+            "an untrusted Host header reached the projection API: "
+            f"status={untrusted_status}")
+        assert "untrusted host" in untrusted_body, untrusted_body
+
+        csrf_status, csrf_body = raw_get(
+            f"GET /api/projects HTTP/1.1\r\nHost: 127.0.0.1:{test_port}\r\n"
+            "Sec-Fetch-Site: cross-site\r\n\r\n")
+        assert csrf_status == 403, (
+            f"a cross-site request reached the projection API: status={csrf_status}")
+        assert "cross-origin" in csrf_body, csrf_body
+
+        same_origin_status, _ = raw_get(
+            f"GET /api/projects HTTP/1.1\r\nHost: 127.0.0.1:{test_port}\r\n"
+            "Sec-Fetch-Site: same-origin\r\n\r\n")
+        assert same_origin_status == 200, (
+            f"a legitimate same-origin reader was blocked: status={same_origin_status}")
+
+        print("\n[*] Host / CSRF guard probes:")
+        print(f"    - untrusted Host -> {untrusted_status} ({untrusted_body.strip()})")
+        print(f"    - Sec-Fetch-Site: cross-site -> {csrf_status} ({csrf_body.strip()})")
+        print(f"    - Sec-Fetch-Site: same-origin -> {same_origin_status}")
+        results["host_csrf_guard"] = {
+            "untrusted_host": untrusted_status,
+            "cross_site": csrf_status,
+            "same_origin": same_origin_status,
+        }
 
     finally:
         server.shutdown()

package/skill/agents/evidence-judge.md

@@ -24,12 +24,54 @@ critical_path: true
 
 ## 四态决策规则（硬标准）
 
-| 决策 | 要求 |
-|---|---|
-| ADOPT | 多项关键 Outcome 有较强直接证据 + 风险可控 + 场景匹配 |
-| PILOT | 有积极证据，但长期效果/迁移/风险仍不明确 |
-| REJECT | 关键结果稳定负效应，或风险明显大于收益 |
-| INSUFFICIENT EVIDENCE | 来源不足 / 直接性差 / 设计弱 / 冲突无法解释 |
+| 决策 | 要求 | downgrade_reason |
+|---|---|---|
+| ADOPT | High + support + 主结果 directness=2 直接证据 + 风险可控 + 场景匹配 | （无） |
+| PILOT | High + support 但缺主结果直接证据；或 Moderate + support + 可验证主结果路径 | `missing_direct_primary` / `confidence_band` |
+| REJECT | 关键结果稳定负效应（oppose），或风险明显大于收益 | （无） |
+| INSUFFICIENT EVIDENCE | Low / 间接（Moderate 无可验证主结果路径）/ 冲突无法解释 / 来源不足 | `confidence_band` / `missing_direct_primary` |
+
+闸门强制降级（`GATE_CRITICAL_FAILURE`）时记录 `downgrade_reason=gate_critical`。
+
+### 四态均衡 Few-shot
+
+**ADOPT**（High + support + 主结果直接证据）
+```json
+{
+  "confidence": "High",
+  "recommended_action": "adopt",
+  "decision_rationale": "延迟保持与迁移两项主要结果上均有直接且一致的支持证据，风险可控，场景高度匹配，因此可以推广。"
+}
+```
+
+**PILOT**（Moderate + support + 可验证主结果路径；或 High 缺主结果直接证据）
+```json
+{
+  "confidence": "Moderate",
+  "recommended_action": "pilot",
+  "decision_rationale": "任务表现与部分学习指标方向积极，主要结果上存在可验证的测量路径，但长期保持与迁移仍不确定，因此建议有边界的试点。"
+}
+```
+
+**REJECT**（oppose / 稳定负效应）
+```json
+{
+  "confidence": "Moderate",
+  "recommended_action": "reject",
+  "decision_rationale": "多项独立研究在关键结果上呈现稳定负效应，且风险大于收益，因此不建议采纳。"
+}
+```
+
+**INSUFFICIENT EVIDENCE**（Low / 间接 / 冲突）
+```json
+{
+  "confidence": "Low",
+  "recommended_action": "insufficient_evidence",
+  "decision_rationale": "现有来源多为间接证据且结论互相冲突，主要结果上缺少可验证路径，因此证据不足以支持采纳或试点。"
+}
+```
+
+禁止把四态收成「一律 PILOT」：ADOPT 与 INSUFFICIENT、REJECT 都必须按上表真实可达。
 
 ## 输入
 
@@ -154,6 +196,6 @@ critical_path: true
 | 失败 | 处理 |
 |---|---|
 | `PRE_VERDICT_FAILED` | 修复前置产物后重跑闸门，不得跳过。 |
-| `GATE_CRITICAL_FAILURE` | 封顶置信度，强制降级为 PILOT 或 INSUFFICIENT EVIDENCE。 |
+| `GATE_CRITICAL_FAILURE` | 封顶置信度，强制降级为 PILOT 或 INSUFFICIENT EVIDENCE，并记录 `downgrade_reason=gate_critical`。 |
 | `CONFLICT_UNRESOLVED` | 保持不确定，不强行裁决。 |
 | 证据只支持任务表现 | 不得产出学习效果类结论。 |

package/skill/workflows/experimental-jev.md

@@ -0,0 +1,170 @@
+---
+name: experimental-jev
+description: Optional Jev / SemDecide Tier-0 acceleration overlay. Modes 0 standard / 1 jev-mcp / 2 semdecide / 3 hybrid. Fail-closed. Never replaces Pre-Verdict Gate or Skeptic.
+---
+
+# Experimental Jev Overlay
+
+Use only when the run explicitly enables the overlay: `eduevidence run --enhancement jev`
+(and/or `--enhancement semdecide`, which is recorded in the run's `intake.json`), or
+`EDU_EXPERIMENTAL_JEV=<mode>` for the detect CLIs (`--experimental <0|1|2|3>` is a flag of
+`integrations/jev_mcp.py` and `integrations/semantic_decide.py`, not of the host CLI).
+This is an **acceleration overlay** on the scientific protocol — not a fourth workflow,
+not a substitute for scientific gates, and not a source of evidence.
+
+Default without an explicit selection: **mode 0 standard** (existing large-model pipeline only).
+
+## Modes
+
+| Mode | Name | Backing | When |
+|---:|---|---|---|
+| 0 | standard | host large model only | default; no experimental flag |
+| 1 | jev-mcp | `integrations/jev/` → FreeJev or Vercel AI Gateway `typesafe-ai/jev` (urllib) or documented MCP (`https://freejev.org/mcp`, `npx -y @jkudish/jev-mcp`) | Tier-0 typed judgments, fast & cheap |
+| 2 | semdecide | `integrations/semantic_decide.py` → `semdecide is / filter / choose` | Unix-pipeline predicates, filtering, routing |
+| 3 | hybrid | 1 + 2 together | screen/rerank/extract/classify/verify via Jev; local predicates via SemDecide |
+
+Enable:
+
+```bash
+# resolve mode + detect backends (no network judgment yet)
+python3 integrations/jev_mcp.py --experimental 3
+python3 integrations/semantic_decide.py --experimental 3
+
+# user confirmation gate (writes ~/.eduevidence/jev_mcp_approval.json)
+python3 integrations/jev_mcp.py --experimental 3 --approve
+
+# host CLI (documented entry; the enhancement selection turns the overlay on for the run)
+eduevidence run --question "..." --run-id <id> --enhancement jev --enhancement semdecide
+```
+
+Secrets live only in `~/.eduevidence/env` — never in the repository, never on argv.
+
+| Provider | Env | Decide endpoint | MCP (documented only) |
+|---|---|---|---|
+| `freejev` | `FREEJEV_API_KEY`, `JEV_PROVIDER=freejev` | `https://freejev.org/api/v1/decide` | `https://freejev.org/mcp` |
+| `vercel` (default) | `AI_GATEWAY_API_KEY` or `TYPESAFE_API_KEY`, `JEV_PROVIDER=vercel` | Vercel AI Gateway System One | `npx -y @jkudish/jev-mcp` |
+
+**FreeJev `request_id` is an idempotency key — never retry the same `request_id`.**
+On timeout / 5xx / unknown outcome, fail-closed escalate this call to the large
+model. A deliberate re-ask must use a **new** `request_id` and its own provenance row.
+
+## Non-negotiable boundaries
+
+1. **Fail-closed.** Any Jev `JEV_INVALID_RESPONSE` / `JEV_PROVIDER_ERROR`, and any
+   SemDecide exit **2 / 3 / 4** (plus `SEMDECIDE_UNAVAILABLE` / `SEMDECIDE_TIMEOUT`),
+   escalates to the large model (or a human). Never invent, never silently
+   accept, never force a binary on an uncertain probability.
+2. **FreeJev `request_id` 不重试.** Same `request_id` is never resent; escalate instead.
+2. **Does not replace `scripts/pre_verdict_gate.py`.** Stage Adjudicate still runs the
+   Pre-Verdict Gate before any verdict is final.
+3. **Does not replace Skeptic.** Stage Challenge still executes all nine fixed checks
+   (`skill/sub-skills/contradiction-analysis`). `claim_verify` may pre-triage claims only.
+4. **Does not replace methodology audit / tribunal / outcome separation.**
+5. **Snippet ≠ evidence (RULE 2).** `content_screen` / `semantic_rerank` operate on
+   discovery material only. Only fetched, validated content enters Extract.
+6. **Verbatim extract only.** `field_extract` returns regex-matched substrings chosen by
+   Jev — never model-authored field values. `review` / `not_found` are not extraction.
+7. **Approval gate.** Network Tier-0 calls require
+   `~/.eduevidence/jev_mcp_approval.json` (tools hash + provider + model). Missing or
+   mismatched approval → `JEV_APPROVAL_REQUIRED`, escalate.
+
+## Nine-stage mapping (`engine/workflows.py::SCIENTIFIC_STAGE_IDS`)
+
+| # | Stage | Mode 1 / 3 Jev Tier-0 | Mode 2 / 3 SemDecide | Still mandatory (never skipped) |
+|---:|---|---|---|---|
+| 1 | Frame | — | `choose` optional route for domain/frame vocabulary (uncertain → planner) | Frame schema; no intervention advice before framing |
+| 2 | Retrieve | `content_screen` (pre-context injection/substance/relevance); `semantic_rerank` (discovery order); `classify_check` (inclusion pre-triage) | `filter` on candidate JSONL; `is` for cheap exclusion predicates | Search plan + counter-evidence queries; Fetch/Validate gate; provenance export |
+| 3 | Extract | `field_extract` (verbatim n / effect / CI candidates); `classify_check` (outcome type pre-label) | `is` for task-vs-learning guard pre-check | Evidence Objects schema; outcome separation; finding ≠ study merge ban |
+| 4 | Challenge | `claim_verify` **assist only** (claim↔evidence relation triage) | `is` for "is there a contradiction signal?" assist | **All nine Skeptic checks**; `NO CONTRADICTORY EVIDENCE FOUND` rule |
+| 5 | Audit | `claim_verify` assist on claim support | `is` for checklist pre-filter | Methodology audit + `task_vs_learning_guard` |
+| 6 | Adjudicate | — (Tier-0 must not score final verdict) | — | Four-state verdict; confidence breakdown; **`scripts/pre_verdict_gate.py`** |
+| 7 | Applicability | `classify_check` optional population/context tags | `choose` optional applicability bounds | Population / conditions / exclusions / uncertainty stated |
+| 8 | Intervene | — | — | Intervention design gates (`intervention_design`) |
+| 9 | Evaluate | — | — | Evaluation design + data validation (`evaluation_design`, `data_validation`) |
+
+Projection (report render) stays outside the nine stages and outside this overlay.
+
+## Capability ↔ tool
+
+Registered in `engine/capabilities.py` (experimental set; resolve with
+`capability_registry(include_experimental=True)` or `experimental_capability_registry()` —
+omitted from the default scientific registry because Tier-0 is not role-owned work):
+
+| capability_id | Tool | Mode |
+|---|---|---|
+| `content_screen` | `jev_mcp.screen` | 1, 3 |
+| `semantic_rerank` | `jev_mcp.rerank` | 1, 3 |
+| `field_extract` | `jev_mcp.extract` | 1, 3 |
+| `classify_check` | `jev_mcp.classify` | 1, 3 |
+| `claim_verify` | `jev_mcp.verify` | 1, 3 |
+
+SemDecide wrappers (`integrations/semantic_decide.py`) support stages without new
+capability IDs: `is` / `filter` / `choose`.
+
+## Fail-closed matrix
+
+Aligned with `integrations/semantic_decide.py` (`EXIT_MEANINGS`, `ESCALATE_EXIT_CODES`,
+`requires_llm_escalation`, `escalate_plan`) and `integrations/jev/gateway.py` status codes.
+
+| Signal | Meaning | Action |
+|---|---|---|
+| Jev `JEV_INVALID_RESPONSE` | typed answer / `answers` envelope missing or malformed | escalate to large model; mark `review` |
+| Jev `JEV_PROVIDER_ERROR` | transport / HTTP 401, 403, 429, 529, 5xx | escalate this call only; record attempt |
+| FreeJev `request_id` failure/timeout | idempotent decide attempt already keyed | **do not retry same `request_id`**; escalate / new id only |
+| `JEV_APPROVAL_REQUIRED` | no/wrong approval file | do not call network; escalate / ask user to approve |
+| `JEV_UNAVAILABLE` | no key and no MCP path | mode 0 standard pipeline |
+| SemDecide exit `0` | `true/selected/match` | semantic result usable |
+| SemDecide exit `1` | `false/no match` | usable; `filter` exit 1 is **not** an escalation by itself |
+| SemDecide exit `2` | `invalid input` | repair input and re-run, or hand the whole decision to the large model |
+| SemDecide exit `3` | `uncertain` | escalate to large model / human; never force true/false |
+| SemDecide exit `4` | `provider failure` | degrade to large model for this call only; record the attempt |
+| `SEMDECIDE_UNAVAILABLE` | binary missing / spawn failed | escalate (`requires_llm_escalation`) |
+| `SEMDECIDE_TIMEOUT` | CLI timed out | escalate (`escalate=ESCALATE_TO_LLM`) |
+| Screen `block` / `review` | injection or low trust | do not enter context; discard or human review |
+| Extract `review` / `not_found` | provisional or absent value | not an extracted field; large model re-extract |
+| Classify `review` | low confidence / margin | large model re-label |
+| Verify `review` / `unknown` | low confidence / invalid | large model claim check; never auto-adopt |
+
+## Degradation path
+
+```
+mode 3 hybrid
+  ├─ provider key + approval             → Tier-0 screen/rerank/extract/classify/verify
+  │    (FreeJev: FREEJEV_API_KEY + JEV_PROVIDER=freejev; request_id never retried)
+  ├─ semdecide on PATH                   → is/filter/choose
+  ├─ exit 2/3/4 / SEMDECIDE_TIMEOUT
+  │    / JEV_INVALID_RESPONSE / JEV_PROVIDER_ERROR
+  │                                    → large model for THAT call (fail-closed)
+  ├─ Jev unavailable                     → SemDecide only (mode 2 slice)
+  ├─ semdecide unavailable               → Jev only (mode 1 slice)
+  └─ both unavailable / overlay not selected → mode 0 standard (Platform Native)
+```
+
+Scientific gates do not degrade: Pre-Verdict Gate, Skeptic nine checks, methodology
+audit, and the four-state tribunal always run on the host path.
+
+## Acceptance checklist
+
+- [ ] The overlay selection is recorded on the run (`intake.json` enhancements); absent
+      selection means mode 0.
+- [ ] Approval file present and `tools_hash` matches before any gateway call.
+- [ ] Every Tier-0 result stored with `status` / `confidence` / `escalate` provenance.
+- [ ] All SemDecide exit 2/3/4, `SEMDECIDE_UNAVAILABLE`, and `SEMDECIDE_TIMEOUT` rows
+      show an escalation record (no silent coercion). `filter` exit 1 alone is not escalated.
+- [ ] FreeJev calls never reuse a `request_id` for retry; each attempt is one shot.
+- [ ] Stage 4 Challenge still has the nine Skeptic checks + explicit contradiction statement.
+- [ ] Stage 6 Adjudicate still ran `scripts/pre_verdict_gate.py` before finalising.
+- [ ] A/B metrics logged per `docs/j-ev-experimental.md` (speedup口径 + quality gates).
+- [ ] No secrets in artifacts (`AI_GATEWAY_API_KEY` / `TYPESAFE_API_KEY` / `FREEJEV_API_KEY`);
+      keys only from `~/.eduevidence/env` / process env.
+
+## Minimal example
+
+```bash
+export EDU_EXPERIMENTAL_JEV=3   # detect CLIs read this; the host run uses --enhancement
+python3 integrations/jev_mcp.py --experimental 3 --approve
+eduevidence run --question "Should first-year CS students use generative AI coding assistants?" \
+  --run-id ai-cs1-jev --enhancement jev --enhancement semdecide
+# Scientific path unchanged: Frame → Retrieve → Extract → Challenge → Audit → Adjudicate → Applicability
+# Tier-0 only pre-screens, re-ranks, extracts verbatim fields, pre-labels, pre-verifies claims.
+```