eduevidence 6.2.0 → 6.3.0

package/SKILL.md

@@ -2,7 +2,7 @@
 name: eduevidence
 description: "Decision-grade evidence synthesis for education and applied social science intervention decisions. Use when a user needs to determine whether, when, for whom, or how to adopt, pilot, evaluate, or revise a teaching method, curriculum change, AI tool, program, or policy intervention. Run an auditable evidence-to-decision workflow spanning systematic retrieval, counter-evidence challenge, methodological quality and evidence-certainty appraisal, provenance-traceable evidence graphs, applicability boundaries, evidence-grounded gap detection, preregistration-ready study or pilot design, empirical evidence re-injection, and decision revision."
 ---
-# EduEvidence 6.2 — Decision-Grade Evidence Engine
+# EduEvidence 6.3 — Decision-Grade Evidence Engine
 > **AI4SS Track | Art–Science Integration · General Intelligence**  
 > **From empirical questions to decision-grade evidence and evidence-to-action loops.**
 
@@ -28,6 +28,7 @@ Treat roles, models, Agent MCP, retrievers, scripts, and HTML reports as **execu
 ---
 
 ## 2. Route the Request to a Workflow
+Before selecting a primary workflow, run the one-shot two-round intake in `skill/workflows/intake.md` (research question → execution enhancements → depth; then enhancement mappings + Frame boundary confirmation). Persist non-question preferences via `scripts/intake/` to `~/.eduevidence/prefs.json`. After the wrap-up summary is confirmed once, continue unattended.
 Load exactly one primary workflow for the current task:
 - `skill/workflows/evidence-review.md` — use for evidence synthesis and decision appraisal from existing research.
 - `skill/workflows/decision-and-pilot.md` — use when the evidence must be converted into an actionable pilot or intervention plan.
@@ -109,7 +110,7 @@ Applicability → Intervene → Evaluate
 | 3 | **Extract** | `evidence.schema.json` | Extract findings, effect sizes, confidence intervals, sample sizes, outcomes, population characteristics, and study design information when available. |
 | 4 | **Challenge** | `evidence.schema.json` | Search explicitly for null findings, negative findings, contradictory evidence, alternative explanations, and confounders. |
 | 5 | **Audit** | `methodology.schema.json` | Appraise study quality and evidence certainty. Apply WWC 5.0 criteria where relevant to education-study design; use GRADE-informed certainty assessment at the body-of-evidence level where appropriate. |
-| 6 | **Adjudicate** | `verdict.schema.json` | Integrate evidence and emit a bounded decision: `ADOPT`, `PILOT`, `DO_NOT_ADOPT`, or `INSUFFICIENT`. Pass the Pre-Verdict Gate before finalizing. |
+| 6 | **Adjudicate** | `verdict.schema.json` | Integrate evidence and emit a bounded decision: `ADOPT`, `PILOT`, `REJECT`, or `INSUFFICIENT_EVIDENCE`. Pass the Pre-Verdict Gate before finalizing. |
 | 7 | **Applicability** | `references/applicability-policy.md` | State who the evidence applies to, in which contexts, for which outcomes, and under what conditions. |
 | 8 | **Intervene** | `intervention.schema.json` | Design the minimum viable intervention or pilot and define explicit success, failure, and stop conditions. |
 | 9 | **Evaluate** | `evaluation.schema.json` | Define baseline, post-intervention, retention/maintenance, transfer, and decision-update logic. |
@@ -138,7 +139,7 @@ Include, where relevant:
 ### Gate C — No Direct Learning Evidence, No ADOPT
 For education interventions, do not issue `ADOPT` based only on task speed, task completion, productivity, usability, preference, or subjective experience.
 Require direct evidence on learning, retention, independent transfer, or another explicitly decision-relevant outcome before `ADOPT` can be considered.
-If direct evidence is missing, bound the decision to `PILOT`, `INSUFFICIENT`, or `DO_NOT_ADOPT` as justified by the evidence.
+If direct evidence is missing, bound the decision to `PILOT`, `INSUFFICIENT_EVIDENCE`, or `REJECT` as justified by the evidence.
 ### Gate D — No False Precision
 Never invent missing uncertainty statistics.
 - If a confidence interval is not reported, do not fabricate one.
@@ -303,13 +304,13 @@ The example demonstrates:
 - Empirical evidence re-injection followed by decision revision.
 Do not generalize the flagship verdict to unrelated populations, courses, tools, or policy contexts.
 
-The four-state output is reachable on both ends, and each public case records which end it reached:
+The four-state matrix (`engine.decision_policy.decision_outcome`) is the gate-enforced landing; each public case also records the adjudicator's own `recommended_action`. Recomputed from the pack's own `evidence.jsonl` + confidence label:
 
-- `examples/ai-coding-assistant-evidence/` - `PILOT` / Moderate / 0.586. Primary evidence stops at task performance, so the decision is bounded.
-- `examples/spaced-retrieval-practice/` - `ADOPT` / High / 0.893. Retention and transfer, the primary outcomes, carry direct evidence at directness 2.
-- `examples/workplace-ai-assistant/` - `PILOT` / Moderate / 0.578, using the policy domain contract.
+- `examples/ai-coding-assistant-evidence/` - matrix `INSUFFICIENT_EVIDENCE` (`unresolved_conflict`: the decisive relations contain both `support_adoption` and `oppose_adoption`, so the conflict check fires first) / Moderate / 0.586. The pack records `PILOT`; primary evidence stops at task performance (no directness-2 learning outcome), so the decision is bounded — but the matrix does not let a conflicted relation set claim `PILOT`.
+- `examples/spaced-retrieval-practice/` - matrix `ADOPT` / High / 0.893. Retention and transfer, the primary outcomes, carry direct evidence at directness 2. The pack records `ADOPT`; this is the only public case where stated and matrix landings agree.
+- `examples/workplace-ai-assistant/` - matrix `INSUFFICIENT_EVIDENCE` with `downgrade_reason=None` / Moderate / 0.578, using the policy domain contract: all four decisive relations are `conditional`, and `conditional` is not a conflict relation (`CONFLICT_RELATIONS` = `{conflict, mixed}`), so no downgrade reason is recorded and, with no decisive `support_adoption`, Moderate confidence cannot reach `PILOT`. The pack records `PILOT`.
 
-A verdict never awards itself an action: the Pre-Verdict Gate re-derives primary-outcome directness from the evidence corpus and caps an unsupported `ADOPT` to `PILOT`. Never present a case as ADOPT without that derivation passing.
+A verdict never awards itself an action: the Pre-Verdict Gate re-derives primary-outcome directness from the evidence corpus and caps an unsupported `ADOPT` to `PILOT`. Never present a case as ADOPT without that derivation passing. Where the matrix landing is `INSUFFICIENT_EVIDENCE`, do not describe the case as having landed at `PILOT` — report both the recorded action and the matrix bound, and do not invent evidence to force a stronger landing.
 
 ---
 
@@ -451,7 +452,7 @@ This appendix keeps the deterministic repository gates (skill lint / version / m
 - **EduEvidence Research Engine** — the runnable engine delivered as a Skill package (`engine/`, `retrieval/`, `scripts/`, `schemas/`).
 - **Shared Research Library** — verified external facts (`Source` / `Study` / `Finding` / `Audit`) may be reused across project snapshots; interpretive objects (`Claim` / `EvidenceLink` / `Applicability` / `Decision`) stay project-local.
 - **No new study design without evidence grounding** — every study or pilot must cite an explicit, evidence-supported `KnowledgeGap` identifier.
-- **Schema 版本口径**：schemas/ 顶层 13 个 = V1 契约（evidence.schema.json 当前修订 1.1、education-frame / verdict 等）；schemas/v2/ 17 个 = V2 契约（evidence-link / research-intent / study / graph-revision / project 等）。文档与代理配置一律以此口径命名。
+- **Schema 版本口径**：schemas/ 顶层 15 个 = V1 契约（evidence.schema.json 当前修订 1.1、education-frame / verdict / report-spec 等）；schemas/v2/ 18 个 = V2 契约（evidence-link / research-intent / intake / study / graph-revision / project 等）；另有 v3 3 个、v4 4 个、vNext 10 个，递归合计 50 个（计数以 `scripts/generate_metrics.py` 为准）。文档与代理配置一律以此口径命名。
 - Five baked report themes (presentation systems, not science):
 
     ├─ Claude Research      [Light]

package/benchmarks/evidence-library.json

@@ -4941,6 +4941,282 @@
         "assessment_edtech"
       ]
     },
+    {
+      "entry_id": "lib-ai-coding-assistant-E-001",
+      "source_id": "S-2023-kazemitabaar",
+      "title": "Studying the effect of AI Code Generators on Supporting Novice Learners in Introductory Programming",
+      "year": 2023,
+      "outcome_token": "completion_time",
+      "outcome_tokens": [
+        "completion_time"
+      ],
+      "direction": "support",
+      "study_type": "rct",
+      "claim_text": "AI coding assistants significantly increase task completion speed and completion rate during training.",
+      "effect_summary": "1.15x completion rate, 0.57x time, 1.8x correctness",
+      "confidence_markers": [
+        "evidence_level:strong",
+        "quality_score:9.0",
+        "confidence:0.7",
+        "decision_relation:support_adoption"
+      ],
+      "domains": [
+        "ai-coding-assistant"
+      ]
+    },
+    {
+      "entry_id": "lib-ai-coding-assistant-E-002",
+      "source_id": "S-2023-kazemitabaar",
+      "title": "Studying the effect of AI Code Generators on Supporting Novice Learners in Introductory Programming",
+      "year": 2023,
+      "outcome_token": "independent_problem_solving",
+      "outcome_tokens": [
+        "independent_problem_solving"
+      ],
+      "direction": "neutral",
+      "study_type": "rct",
+      "claim_text": "Access to AI code generation did not decrease performance on manual code-modification tasks.",
+      "effect_summary": "no significant difference between groups",
+      "confidence_markers": [
+        "evidence_level:moderate",
+        "quality_score:7.0",
+        "confidence:0.5",
+        "decision_relation:neutral"
+      ],
+      "domains": [
+        "ai-coding-assistant"
+      ]
+    },
+    {
+      "entry_id": "lib-ai-coding-assistant-E-003",
+      "source_id": "S-2023-kazemitabaar",
+      "title": "Studying the effect of AI Code Generators on Supporting Novice Learners in Introductory Programming",
+      "year": 2023,
+      "outcome_token": "retention",
+      "outcome_tokens": [
+        "retention"
+      ],
+      "direction": "neutral",
+      "study_type": "rct",
+      "claim_text": "One week after training, retention differences between Codex and baseline groups did not reach statistical significance.",
+      "effect_summary": "slightly better for Codex group but not significant",
+      "confidence_markers": [
+        "evidence_level:strong",
+        "quality_score:9.0",
+        "confidence:0.5",
+        "decision_relation:neutral"
+      ],
+      "domains": [
+        "ai-coding-assistant"
+      ]
+    },
+    {
+      "entry_id": "lib-ai-coding-assistant-E-004",
+      "source_id": "S-2025-bastani",
+      "title": "Generative AI without guardrails can harm learning: Evidence from high school mathematics",
+      "year": 2025,
+      "outcome_token": "independent_problem_solving",
+      "outcome_tokens": [
+        "independent_problem_solving"
+      ],
+      "direction": "contradict",
+      "study_type": "rct",
+      "claim_text": "Students with unguarded GPT-4 access performed 17% worse on the independent exam than the control group, despite higher practice performance.",
+      "effect_summary": "negative_17_percent_on_independent_exam",
+      "confidence_markers": [
+        "evidence_level:strong",
+        "quality_score:8.0",
+        "confidence:0.75",
+        "decision_relation:oppose_adoption"
+      ],
+      "domains": [
+        "ai-coding-assistant"
+      ]
+    },
+    {
+      "entry_id": "lib-ai-coding-assistant-E-005",
+      "source_id": "S-2025-bastani",
+      "title": "Generative AI without guardrails can harm learning: Evidence from high school mathematics",
+      "year": 2025,
+      "outcome_token": "independent_problem_solving",
+      "outcome_tokens": [
+        "independent_problem_solving"
+      ],
+      "direction": "support",
+      "study_type": "rct",
+      "claim_text": "Guardrail design of the AI tutor (hints instead of answers, teacher-informed prompts) largely eliminated the negative learning effect.",
+      "effect_summary": "negative effect essentially eradicated, no positive effect observed",
+      "confidence_markers": [
+        "evidence_level:strong",
+        "quality_score:8.0",
+        "confidence:0.75",
+        "decision_relation:conditional"
+      ],
+      "domains": [
+        "ai-coding-assistant"
+      ]
+    },
+    {
+      "entry_id": "lib-ai-coding-assistant-E-006",
+      "source_id": "S-2025-bastani",
+      "title": "Generative AI without guardrails can harm learning: Evidence from high school mathematics",
+      "year": 2025,
+      "outcome_token": "assignment_score",
+      "outcome_tokens": [
+        "assignment_score"
+      ],
+      "direction": "support",
+      "study_type": "rct",
+      "claim_text": "Access to GPT-4 during practice improves task performance (48% for GPT Base, 127% for GPT Tutor) — but this task performance does not transfer to independent exam performance.",
+      "effect_summary": "48-127 percent improvement on practice problems",
+      "confidence_markers": [
+        "evidence_level:strong",
+        "quality_score:8.0",
+        "confidence:0.75",
+        "decision_relation:conditional"
+      ],
+      "domains": [
+        "ai-coding-assistant"
+      ]
+    },
+    {
+      "entry_id": "lib-ai-coding-assistant-E-007",
+      "source_id": "S-2024-marzuki",
+      "title": "Impact of ChatGPT on ESL students' academic writing skills",
+      "year": 2024,
+      "outcome_token": "knowledge_gain",
+      "outcome_tokens": [
+        "knowledge_gain"
+      ],
+      "direction": "support",
+      "study_type": "mixed_methods",
+      "claim_text": "ChatGPT as a formative feedback tool produced a significant positive impact on students' academic writing skills with positive student perceptions.",
+      "effect_summary": "significant positive impact on writing skills",
+      "confidence_markers": [
+        "evidence_level:moderate",
+        "quality_score:6.0",
+        "confidence:0.55",
+        "decision_relation:support_adoption"
+      ],
+      "domains": [
+        "ai-coding-assistant"
+      ]
+    },
+    {
+      "entry_id": "lib-ai-coding-assistant-E-008",
+      "source_id": "S-2023-peng",
+      "title": "The Impact of AI on Developer Productivity: Evidence from GitHub Copilot",
+      "year": 2023,
+      "outcome_token": "completion_time",
+      "outcome_tokens": [
+        "completion_time"
+      ],
+      "direction": "support",
+      "study_type": "rct",
+      "claim_text": "Professional developers with Copilot access completed a standardized coding task about 55% faster than the control group (RCT, n=95).",
+      "effect_summary": "~55.8% faster task completion in Copilot group",
+      "confidence_markers": [
+        "evidence_level:moderate",
+        "quality_score:8.0",
+        "confidence:0.6",
+        "decision_relation:conditional"
+      ],
+      "domains": [
+        "ai-coding-assistant"
+      ]
+    },
+    {
+      "entry_id": "lib-ai-coding-assistant-E-009",
+      "source_id": "S-2023-yetistiren",
+      "title": "GitHub Copilot AI Pair Programmer: Asset or Liability?",
+      "year": 2023,
+      "outcome_token": "code_quality",
+      "outcome_tokens": [
+        "code_quality"
+      ],
+      "direction": "support",
+      "study_type": "observational",
+      "claim_text": "Systematic benchmark evaluation reports mixed quality results for Copilot-generated code relative to human code: correctness competitive on parts of the benchmark while security-relevant defects are documented.",
+      "effect_summary": "mixed quality profile; no single-direction summary",
+      "confidence_markers": [
+        "evidence_level:moderate",
+        "quality_score:7.0",
+        "confidence:0.55",
+        "decision_relation:conditional"
+      ],
+      "domains": [
+        "ai-coding-assistant"
+      ]
+    },
+    {
+      "entry_id": "lib-ai-coding-assistant-E-010",
+      "source_id": "S-2022-finnie-ansley",
+      "title": "Using GitHub Copilot to Solve Introductory Programming Problems",
+      "year": 2022,
+      "outcome_token": "assignment_score",
+      "outcome_tokens": [
+        "assignment_score"
+      ],
+      "direction": "support",
+      "study_type": "observational",
+      "claim_text": "Codex produced passing-level solutions for roughly half to three-quarters of CS1 exam-style questions depending on the dataset, indicating substantial task-capability headroom available to novices.",
+      "effect_summary": "passing solutions on ~50-75% of questions across datasets",
+      "confidence_markers": [
+        "evidence_level:moderate",
+        "quality_score:7.0",
+        "confidence:0.55",
+        "decision_relation:conditional"
+      ],
+      "domains": [
+        "ai-coding-assistant"
+      ]
+    },
+    {
+      "entry_id": "lib-ai-coding-assistant-E-011",
+      "source_id": "S-2023-explanations-compare",
+      "title": "Comparing Code Explanations Created by Students and Large Language Models",
+      "year": 2023,
+      "outcome_token": "metacognition",
+      "outcome_tokens": [
+        "metacognition"
+      ],
+      "direction": "support",
+      "study_type": "observational",
+      "claim_text": "Controlled comparisons find LLM-generated code explanations comparable to (in places better than) student-authored explanations, suggesting viability as explanatory scaffold material rather than as a replacement for student explanation practice.",
+      "effect_summary": "comparable-or-better rated quality vs student explanations",
+      "confidence_markers": [
+        "evidence_level:moderate",
+        "quality_score:7.0",
+        "confidence:0.55",
+        "decision_relation:conditional"
+      ],
+      "domains": [
+        "ai-coding-assistant"
+      ]
+    },
+    {
+      "entry_id": "lib-ai-coding-assistant-E-012",
+      "source_id": "S-2022-vaithilingam",
+      "title": "Expectation vs. Experience: Evaluating the Usability of Code Generation Tools",
+      "year": 2022,
+      "outcome_token": "over_reliance",
+      "outcome_tokens": [
+        "over_reliance"
+      ],
+      "direction": "support",
+      "study_type": "qualitative",
+      "claim_text": "Despite faster first-task completion, participants struggled to understand and debug AI-generated solutions and reported low ownership of the final program - documenting metacognitive and dependence risks that pure speed metrics miss.",
+      "effect_summary": "documented comprehension/ownership difficulties despite speed gain",
+      "confidence_markers": [
+        "evidence_level:moderate",
+        "quality_score:7.0",
+        "confidence:0.55",
+        "decision_relation:conditional"
+      ],
+      "domains": [
+        "ai-coding-assistant"
+      ]
+    },
     {
       "entry_id": "lib-ai-tutor-E-001",
       "source_id": "S-2025-bastani",
@@ -5264,5 +5540,5 @@
       ]
     }
   ],
-  "coverage_note": "内置证据库：由 30 份金标准标注（benchmarks/annotations/gold-Q01..Q30 的 key_claims/key_supporting_sources/known_contradictions/correct_outcome_types）+ 3 个示例工作流 evidence.jsonl（ai-coding-assistant / ai-tutor / ai-writing-assistant）抽取生成；按 (source_id, outcome_token, claim_text) 去重合并。direction 语义为采纳方向：support=支持采纳（初步裁决=>pilot），contradict=反对采纳（=>reject），neutral=中性；金标准条目按 expected_decision_range 粗粒度映射方向（纯 reject 问题反向映射），conflict 与混合方向问题的单条断言方向可能不精确。仅用于离线初步裁决（preliminary，保守），从不直接给出 adopt。"
+  "coverage_note": "内置证据库：由 30 份金标准标注（benchmarks/annotations/gold-Q01..Q30 的 key_claims/key_supporting_sources/known_contradictions/correct_outcome_types）+ 3 个示例工作流 evidence.jsonl（ai-coding-assistant / ai-tutor / ai-writing-assistant）抽取生成；按 (source_id, outcome_token, claim_text) 去重合并。direction 语义为采纳方向：support=支持采纳（离线初筛上限 => pilot，永不输出 adopt），contradict=反对采纳（oppose-only 时 => reject；与 support 并存属未决冲突，应交 engine.decision_policy.decision_outcome 判为 INSUFFICIENT_EVIDENCE），neutral=中性；金标准条目按 expected_decision_range 粗粒度映射方向（纯 reject 问题反向映射），conflict 与混合方向问题的单条断言方向可能不精确。仅用于离线初步裁决（preliminary，保守），从不直接给出 adopt；完整 ADOPT 只能由 engine.decision_policy.decision_outcome 给出（High + support + 主要结果 directness 2）。"
 }

package/docs/architecture.md

@@ -183,7 +183,7 @@ motion/motion.css + motion/motion.js（data-lieflat reveal：滚入播放、
         点击重播 + timer 清理、prefers-reduced-motion 降级、打印全开）
 ```
 
-学术图（outcome-comparison / benchmark / forest）保持主题无关的出版级渲染；Lieflat 部分只渲染 `resolve_visual_layout` 校验通过的条目。注册表、契约与推荐组合见 `visualization/eduevidence-report/references/lieflat-composition.md`，schema 见 `visualization/eduevidence-report/schemas/visual-layout.schema.json`。
+学术图（outcome-comparison / benchmark / forest）保持主题无关的出版级渲染；Lieflat 部分只渲染 `resolve_visual_layout` 校验通过的条目。注册表、契约与推荐组合见 `visualization/eduevidence-report/references/lieflat-composition.md`，schema 见 `visualization/eduevidence-report/schemas/visual-layout.schema.json`（完整路径；短路径 `references/lieflat-composition.md` 与 `/lieflat/lupi`、`docs/lieflat*` 均为已废弃死路径，禁止引用）。
 
 该协议是**可剥离的**：即使没有 Agent 框架，只要按此协议组织检索、抽取、审计与裁决，也能得到可复现的决策链。
 
@@ -276,8 +276,11 @@ edu/
 ├── integrations/           # 集成层（Agent MCP 增强 + Smart Web Fetch）
 ├── visualization/          # 呈现层（eduevidence-report：build_report / build_charts /
 │                           # build_infographics / build_figures / charts_data 提取器 /
-│                           # lieflat_engine 注册表渲染器 / motion / themes / schemas；
-│                           # lieflat-charts：图表品味法典正本）
+│                           # lieflat_engine 注册表渲染器 / motion / themes / schemas。
+│                           # 注册表文档：references/lieflat-composition.md；
+│                           # schema：schemas/visual-layout.schema.json。
+│                           # 注：历史路径 /lieflat/lupi 与 docs/lieflat* 已废弃，
+│                           # 不在 skill_payload / npm files 内；勿再引用。）
 ├── benchmarks/             # 基准评测（questions / annotations / baselines /
 │                           # evaluator / results / v2）
 ├── examples/               # 端到端示例

package/docs/j-ev-experimental.md

@@ -0,0 +1,250 @@
+# Jev 生态实验模式（Experimental Jev / SemDecide Tier-0）
+
+> **实验性加速层，不是科学门。** Tier-0（screen / rerank / extract / classify / verify）
+> 只做窄域类型化判断，**不替代** `scripts/pre_verdict_gate.py`、Skeptic 九项检查、
+> 方法学审计与 Tribunal。不确定 / 非法结果 **fail-closed** 升级大模型。
+>
+> 入口开关：`--experimental <0|1|2|3>` 或 `EDU_EXPERIMENTAL_JEV=<mode>`。
+> 密钥仅存 `~/.eduevidence/env`（`AI_GATEWAY_API_KEY` + `JEV_PROVIDER=vercel`，可选
+> `TYPESAFE_API_KEY`；或 FreeJev：`FREEJEV_API_KEY` + `JEV_PROVIDER=freejev`），
+> **禁止写入仓库**。
+
+## 1. 定位
+
+| 组件 | 实现 | 上游 |
+|---|---|---|
+| `integrations/jev_mcp.py` | detect → approval → urllib 调 Vercel AI Gateway `typesafe-ai/jev` | TypeSafe System One / `@jkudish/jev-mcp` |
+| `integrations/semantic_decide.py` | subprocess `semdecide is / filter / choose` | [sharziki/semdecide](https://github.com/sharziki/semdecide) |
+| `engine/capabilities.py` | 注册 5 个实验能力（`experimental_capability_registry()`；默认科学注册表不含它们，避免协议角色门误伤） | 本仓库能力注册表 |
+| `skill/workflows/experimental-jev.md` | 模式 / 九阶段映射 / fail-closed | Skill 工作流覆盖层 |
+
+原则（与 agent-mcp 一致）：**检测 → 推荐 → 用户确认 → 调用 → 降级**。不迁移、不复制
+上游实现；上游不可用时整体退回 Platform Native / mode 0，科学协议不变。
+
+## 2. 启用方式
+
+```bash
+# 0) 密钥（本地，勿提交）
+# ~/.eduevidence/env
+#   # Vercel AI Gateway 路径
+#   export AI_GATEWAY_API_KEY=...
+#   export JEV_PROVIDER=vercel
+#   # 或 FreeJev 路径
+#   export FREEJEV_API_KEY=...
+#   export JEV_PROVIDER=freejev
+
+# 1) 检测
+python3 integrations/jev_mcp.py --experimental 3
+python3 integrations/semantic_decide.py --experimental 3
+
+# 2) 用户确认门 → ~/.eduevidence/jev_mcp_approval.json
+python3 integrations/jev_mcp.py --experimental 3 --approve
+
+# 3) 运行时打开 overlay（宿主 CLI 用 --enhancement 选择；写入 run 的 intake.json）
+eduevidence run --question "..." --run-id <id> --enhancement jev --enhancement semdecide
+# 检测类 CLI 用模式号：--experimental <0|1|2|3>，或 export EDU_EXPERIMENTAL_JEV=3
+```
+
+| Mode | 名称 | 后端 |
+|---:|---|---|
+| 0 | standard | 仅大模型（默认，无 `--experimental`） |
+| 1 | jev-mcp | FreeJev / Vercel Gateway urllib **或** 文档化 MCP |
+| 2 | semdecide | `semdecide is / filter / choose` |
+| 3 | hybrid | 1 + 2 |
+
+### Provider（Mode 1 / 3）
+
+| `JEV_PROVIDER` | 密钥 | Decide 端点 | 备注 |
+|---|---|---|---|
+| `freejev` | `FREEJEV_API_KEY` | `https://freejev.org/api/v1/decide` | 仅 `FREEJEV_API_KEY` 时可自动选中 |
+| `vercel`（默认） | `AI_GATEWAY_API_KEY`（或 `TYPESAFE_API_KEY`） | `https://ai-gateway.vercel.sh/typesafe/v1/systemone` | `model=typesafe-ai/jev` |
+
+MCP 备选（不自动 spawn，仅文档化）：
+
+```bash
+# FreeJev MCP
+#   https://freejev.org/mcp   + FREEJEV_API_KEY
+# npx 包路径
+claude mcp add jev -- npx -y @jkudish/jev-mcp
+# 通用 JSON：npx -y @jkudish/jev-mcp + TYPESAFE_API_KEY / AI_GATEWAY_API_KEY
+python3 integrations/jev_mcp.py --mcp-guide
+```
+
+**FreeJev `request_id` 不重试。** Decide 调用的 `request_id` 是幂等键：同一
+`request_id` **禁止重试**（超时 / 5xx / 未知结果一律不重发）。本调用
+fail-closed 升级大模型；若业务上必须再问一次，使用**新的** `request_id` 发起
+新调用，并单独记录 provenance。
+
+## 3. Tier-0 API 列表
+
+传输：`POST` 到 provider decide 端点（Vercel System One 或 FreeJev），
+`Authorization: Bearer $AI_GATEWAY_API_KEY` / `$FREEJEV_API_KEY`，
+`model=typesafe-ai/jev`。
+请求体 TypeSafe System One：`{ model, state, questions }` → `{ model, answers, usage }`。
+FreeJev 另带 `request_id`（见上：**不重试**）。
+
+| # | Python API | capability_id | MCP 工具 | SemDecide 对应 | 问题形态 | 默认阈值 |
+|---|---|---|---|---|---|---|
+| 1 | `jev_mcp.screen(text, purpose)` | `content_screen` | `jev_screen` | — | 3× Noul：injection / substance / relevance | `block_at=0.75`, `review_at=0.25` |
+| 2 | `jev_mcp.rerank(query, candidates)` | `semantic_rerank` | `jev_rerank` | — | 1× Noul / candidate | `auto_accept=0.70` |
+| 3 | `jev_mcp.extract(document, fields)` | `field_extract` | `jev_extract` | — | 1× Choice / field（regex 候选 + `none_of_them`） | `auto_accept=0.80`, `margin=0.40` |
+| 4 | `jev_mcp.classify(items, classes)` | `classify_check` | `jev_classify` | `choose` 可路由 | 1× Choice / item | `auto_accept=0.85`, `margin=0.50` |
+| 5 | `jev_mcp.verify(claims, evidence)` | `claim_verify` | `jev_verify` | `is` 可预筛 | 1× Choice / claim：supports / contradicts / says_nothing | `auto_accept=0.80` |
+
+统一入口：`jev_mcp.safe_call(capability_id, ...)`（先过 approval 门）。
+
+SemDecide 封装（exit 2/3/4 → 升级大模型）：
+
+| API | CLI | 用途 |
+|---|---|---|
+| `semdecide.is_predicate(text, predicate)` | `semdecide is` | 语义谓词 |
+| `semdecide.filter_records(records, predicate)` | `semdecide filter` | JSONL 语义过滤（保序） |
+| `semdecide.choose_route(text, question, options)` | `semdecide choose` | 命名选项路由 |
+
+### 状态与 fail-closed（与 `integrations/semantic_decide.py` 对齐）
+
+Jev / Tier-0：
+
+| 状态 | 含义 | 管道行为 |
+|---|---|---|
+| `ok` + `action/auto` | 可自动采用（仍不是科学门） | 记录 provenance，继续阶段 |
+| `review` / `not_found` / `JEV_INVALID_RESPONSE` | 低置信或非法答案（envelope 缺 `answers` 等） | **升级大模型**；extract 的 `review` 值不得当作已抽取 |
+| `JEV_APPROVAL_REQUIRED` | 无/错 approval | 不发网络请求 |
+| `JEV_UNAVAILABLE` | 无密钥 / 无可用传输 | 本调用升级大模型；hybrid 可切 mode 2 切片 |
+| `JEV_PROVIDER_ERROR` | 上游失败（HTTP 401/403/429/529/5xx） | 本调用升级大模型；FreeJev **`request_id` 不重试** |
+
+SemDecide（`EXIT_MEANINGS` / `ESCALATE_EXIT_CODES={2,3,4}`）：
+
+| exit / status | `EXIT_MEANINGS` | 管道行为 |
+|---|---|---|
+| `0` | `true/selected/match` | 语义结果可用 |
+| `1` | `false/no match` | 语义结果可用；`filter` 的 exit 1 **不**单独升级 |
+| **`2`** | `invalid input` | 修输入重跑，或整段决策**升级大模型**（`escalate_plan`） |
+| **`3`** | `uncertain` | **升级大模型 / 人工**；禁止强行 true/false |
+| **`4`** | `provider failure` | **升级大模型**（仅本调用）；记录 attempt |
+| `SEMDECIDE_UNAVAILABLE` | binary 缺失 / spawn 失败 | **升级大模型**（`requires_llm_escalation`） |
+| `SEMDECIDE_TIMEOUT` | 超时 | **升级大模型**（`result.escalate=ESCALATE_TO_LLM`） |
+
+`screen` 的 recommendation（pass / review / block / skip）仅为咨询；拦截执行权在调用方。
+
+## 4. 阈值
+
+| 参数 | 默认 | 调节建议 |
+|---|---:|---|
+| `screen_block_at` | 0.75 | 注入概率 ≥ 则 block（咨询） |
+| `screen_review_at` | 0.25 | 注入概率 ≥ 则 review |
+| `verify_auto_accept` | 0.80 | 关系裁决 confidence ≥ 才 `auto` |
+| `classify_auto_accept` | 0.85 | top 概率门槛 |
+| `classify_minimum_margin` | 0.50 | 冠亚军差门槛（二者同时满足才 auto） |
+| `extract_auto_accept` | 0.80 | 字段挑选 confidence |
+| `extract_minimum_margin` | 0.40 | 候选差门槛；失败 → `review` |
+| `rerank_auto_accept` | 0.70 | 相关 Noul 门槛 |
+| SemDecide `--threshold` | 0.70 | `is` / `filter` |
+| SemDecide `--min-confidence` | 0.70 | `choose`；低于则 exit 3 |
+| SemDecide `--uncertainty-margin` | 0.0 | 边缘区不强行二值化 |
+
+阈值是起点（TypeSafe cookbook 基线），**先在自有数据上校准再强制**。
+
+## 5. 九阶段映射（加速点）
+
+`frame → retrieve → extract → challenge → audit → adjudicate → applicability → intervene → evaluate`
+
+| 阶段 | Jev Tier-0 | SemDecide | 不变的科学门 |
+|---|---|---|---|
+| Frame | — | `choose` 可选 | frame schema |
+| Retrieve | screen / rerank / classify | `filter`, `is` | 检索计划 + 反方检索 + Fetch/Validate |
+| Extract | extract / classify | `is` 预检 | Evidence Objects、task ≠ learning |
+| Challenge | **verify 仅辅助** | `is` 辅助 | **Skeptic 九项检查** |
+| Audit | verify 辅助 | `is` 预筛 | 方法学审计 + guard |
+| Adjudicate | —（禁止 Tier-0 定裁决） | — | **Pre-Verdict Gate** + 四态裁决 |
+| Applicability | classify 可选 | `choose` 可选 | 人群/条件/排除/不确定性 |
+| Intervene | — | — | intervention_design |
+| Evaluate | — | — | evaluation_design / data_validation |
+
+完整矩阵见 `skill/workflows/experimental-jev.md`。
+
+## 6. 加速比口径（speedup）
+
+只比较**同一问题、同一 Complexity Gate、同一九阶段协议**下 mode 0 基线 vs 实验模式。
+
+| 指标 | 定义 | 统计范围 |
+|---|---|---|
+| `T_stage` | 单阶段 wall-clock（s），从进入阶段到产物过 schema/gate | 仅计 **gate 通过** 的阶段 |
+| `T_run` | Frame→Applicability（或声明的阶段子集）累计 | 同上 |
+| `speedup_stage` | `T_stage(mode0) / T_stage(exp)` | per stage |
+| `speedup_run` | `T_run(mode0) / T_run(exp)` | per run |
+| `cost_tokens` | 主模型 + Tier-0 `usage.input_tokens/output_tokens` | 双方同口径合计 |
+| `escalation_rate` | fail-closed 升级次数 / Tier-0 调用次数 | 实验侧 |
+| `gate_pass_rate` | 过科学门的阶段数 / 执行阶段数 | 双方 |
+
+规则：
+
+1. **质量门优先**：`gate_pass_rate(exp) < gate_pass_rate(mode0)` 时 speedup **无效**（质量退化不算加速）。
+2. Tier-0 调用耗时与 token 计入实验侧成本，不得只计大模型。
+3. 升级到大模型的调用耗时计入实验侧（含往返），避免“看起来快”。
+4. 未过 gate / 中断 / 人工改写的 run **不进入** speedup 均值，单独列表。
+5. 报告格式：每 run 一行 `{run_id, mode, T_run, speedup_run, cost_tokens, escalation_rate, gate_pass_rate}`。
+
+示例（示意，非承诺值）：
+
+| run | mode | T_run | speedup_run | escalations | gate_pass |
+|---|---:|---:|---:|---:|---:|
+| ai-cs1-b | 0 | 3120s | 1.00× | — | 7/7 |
+| ai-cs1-j | 3 | 1810s | 1.72× | 4/38 | 7/7 |
+
+## 7. A/B 验收
+
+| 项 | 通过条件 |
+|---|---|
+| 科学完整性 | 挑战阶段九项 Skeptic 全跑；Adjudicate 前 `pre_verdict_gate` 必跑且结论不被 Tier-0 覆盖 |
+| 质量非劣 | `gate_pass_rate` 不低于基线；Pre-Verdict critical 失败数不增加 |
+| 校准 | `verify`/`classify` 的 auto 集抽样人工一致率 ≥ 约定阈值（建议 ≥ 0.9） |
+| Fail-closed | 抽检 100% 的 SemDecide exit 2/3/4、`SEMDECIDE_TIMEOUT`/`SEMDECIDE_UNAVAILABLE` 与 `JEV_INVALID_RESPONSE`/`JEV_PROVIDER_ERROR` 都有升级记录 |
+| 密钥卫生 | 仓库与 run 产物无 `AI_GATEWAY_API_KEY` / `TYPESAFE_API_KEY` / `FREEJEV_API_KEY` 明文 |
+| FreeJev 幂等 | 抽检无同一 `request_id` 重试；失败一律升级大模型 |
+| 可复现 | mode、approval `tools_hash`、阈值、上游 model id 写入 run 元数据 |
+| 加速有效 | `speedup_run ≥ 1.2`（目标，可调）且质量非劣；否则保持 mode 0 |
+
+## 8. 降级路径
+
+```
+--experimental 3 (hybrid)
+  ├─ provider key + jev_mcp_approval.json → Tier-0 screen/rerank/extract/classify/verify
+  │    (FreeJev: FREEJEV_API_KEY + JEV_PROVIDER=freejev；request_id 不重试)
+  ├─ semdecide on PATH                  → is/filter/choose
+  ├─ exit 2/3/4 / SEMDECIDE_TIMEOUT
+  │    / JEV_INVALID_RESPONSE / JEV_PROVIDER_ERROR
+  │                                    → 单次升级大模型（fail-closed）
+  ├─ Jev 不可用                         → 仅 SemDecide（mode 2 切片）
+  ├─ semdecide 不可用                   → 仅 Jev（mode 1 切片）
+  └─ 双不可用 / 未开 --experimental     → mode 0 standard
+
+科学门永不降级：Pre-Verdict Gate / Skeptic 九项 / 方法学审计 / Tribunal 始终在宿主路径执行。
+```
+
+## 9. API 速查（代码）
+
+```python
+from integrations.jev_mcp import (
+    detect_jev_mcp, write_approval, load_approval,
+    screen, rerank, extract, classify, verify, safe_call,
+    resolve_experimental_mode, npx_mcp_guide,
+)
+from integrations.semantic_decide import (
+    detect_semdecide, is_predicate, filter_records, choose_route,
+    requires_llm_escalation, escalate_plan,
+)
+
+mode = resolve_experimental_mode(3)          # 0..3
+approval = load_approval()                   # ~/.eduevidence/jev_mcp_approval.json
+verdict = safe_call("claim_verify", claims, evidence, approval=approval)
+if verdict.get("escalate"):
+    ...  # fail-closed → large model
+```
+
+## 10. 变更记录
+
+| 日期 | 内容 |
+|---|---|
+| 2026-09-22 | 首版：Tier-0 五能力、approval 门、mode 0–3、阈值、加速比口径、A/B 验收、降级路径 |
+| 2026-09-22 | 收口：FreeJev（`FREEJEV_API_KEY` / `JEV_PROVIDER=freejev` / MCP `https://freejev.org/mcp` / `request_id` 不重试）；fail-closed 表与 `semantic_decide.py` 对齐 |