eduevidence 5.2.0 → 6.2.0

package/scripts/skill_payload.py

@@ -0,0 +1,81 @@
+"""Shared, explicit runtime allowlist for flat Skills, npm installs and wheels."""
+from __future__ import annotations
+
+from pathlib import Path
+import shutil
+import sys
+
+TREES = (
+    "agents", "engine", "domains", "skill", "references", "schemas", "scripts",
+    "retrieval", "integrations", "visualization/eduevidence-report", "web/studio",
+    "assets/readme",
+)
+FILES = (
+    "SKILL.md", "eduevidence_cli.py", "install.sh", "pyproject.toml", "setup.py",
+    "LICENSE", "CHANGELOG.md", "README.md", "README.zh-CN.md", "web/index.html",
+    "CONTRIBUTING.md", "web/architecture.html",
+    "benchmarks/evidence-library.json", "benchmarks/partitions.json",
+    "benchmarks/adversarial/cases.jsonl",
+)
+DOCS = (
+    "architecture.md", "demo.md", "demo-storyboard.md", "install-guide.md",
+    "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",
+    "release-closeout/README.md", "release-closeout/issues.md",
+    "release-closeout/frontend-acceptance.md", "release-closeout/verification.md",
+)
+EXAMPLES = (
+    "ai-coding-assistant-evidence", "spaced-retrieval-practice",
+    "workplace-ai-assistant",
+)
+EXAMPLE_FILES = (
+    "result.json", "result.zh.json", "evidence_graph.json", "report_spec.json",
+    "EduEvidence_Report.html", "verdict.json", "evidence.jsonl", "sources.jsonl",
+    "frame.json", "methodology.json", "intervention.json", "evaluation.json",
+)
+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",
+}
+
+
+def payload_files(root: Path):
+    """Yield safe relative files; no symlinks, private state or generated caches."""
+    paths = set(FILES)
+    paths.update(f"docs/{name}" for name in DOCS)
+    for tree in TREES:
+        paths.update(p.relative_to(root).as_posix() for p in (root / tree).rglob("*") if p.is_file())
+    # Ship configuration, never historical results or private Autoevolve sessions.
+    paths.update(f"autoevolve/{name}" for name in ("program.md", "config.yaml", "protected.manifest.yaml"))
+    for example in EXAMPLES:
+        paths.update(f"examples/{example}/{name}" for name in EXAMPLE_FILES)
+        paths.update(p.relative_to(root).as_posix() for p in (root / "examples" / example / "reports-5themes").glob("*.html"))
+    for relative in sorted(paths):
+        if relative in RETIRED_DEMO_SCRIPTS:
+            continue
+        path = root / relative
+        parts = Path(relative).parts
+        if any(p.startswith(".") or p in {"__pycache__", "node_modules", "runs", "venv", "test-results"} for p in parts):
+            continue
+        if path.suffix in {".pyc", ".pyo", ".log"} or any((root.joinpath(*parts[:i])).is_symlink() for i in range(1, len(parts) + 1)):
+            continue
+        if path.is_file():
+            yield relative
+
+
+def copy_payload(root: Path, destination: Path) -> None:
+    required = ("SKILL.md", "agents/openai.yaml", "web/studio/index.html", "eduevidence_cli.py")
+    for name in required:
+        if not (root / name).is_file():
+            raise FileNotFoundError(f"Incomplete Skill runtime: {name}")
+    for relative in payload_files(root):
+        output = destination / relative
+        output.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(root / relative, output)
+
+
+if __name__ == "__main__":
+    copy_payload(Path(sys.argv[1]).resolve(), Path(sys.argv[2]).resolve())

package/scripts/test_adversarial_empirical.py

@@ -87,9 +87,8 @@ def test_eventbus_concurrency():
         t.join()
 
     print(f"[*] Concurrent subscribe/unsubscribe completed. Race errors caught: {len(race_errors)}")
-    if race_errors:
-        for err in race_errors[:5]:
-            print(f"    - [BUG FOUND] {err}")
+    assert not race_errors, (
+        f"EventBus raised under concurrent subscribe/unsubscribe: {race_errors[:3]}")
 
     # 2. Test Subscribe Non-Atomic Check (Duplicate Subscriber Appending)
     bus._subscribers.clear()
@@ -105,8 +104,9 @@ def test_eventbus_concurrency():
         t.join()
 
     print(f"[*] Subscribed same callback across 10 threads. Total registered subscribers: {len(bus._subscribers)} (Expected: 1)")
-    if len(bus._subscribers) > 1:
-        print(f"    - [BUG FOUND] Race condition in subscribe: duplicate callbacks registered ({len(bus._subscribers)})")
+    assert len(bus._subscribers) == 1, (
+        f"subscribe() is not atomic: {len(bus._subscribers)} copies of one callback "
+        "registered from 10 threads")
 
     # 3. Concurrent Publish & Unbounded Memory Leak
     bus.clear()
@@ -156,21 +156,23 @@ def test_did_regression_adversarial():
     results = {}
 
     # Case 2.1: Column Name Parsing Collision
+    # Enough rows for a DID fit (n - 4 > 0): this case is about COLUMN MAPPING,
+    # not about saturation, so a 4-row fixture would test the wrong thing.
     with tempfile.NamedTemporaryFile("w", suffix=".csv", delete=False) as f:
         writer = csv.writer(f)
         writer.writerow(["student_id", "treatment_group", "post_test_score", "time_period"])
-        writer.writerow([1, 1, 85.0, 1])
-        writer.writerow([2, 1, 70.0, 0])
-        writer.writerow([3, 0, 80.0, 1])
-        writer.writerow([4, 0, 75.0, 0])
+        for i in range(1, 13):
+            treat = 1 if i % 2 else 0
+            post = 1 if i % 3 else 0
+            writer.writerow([i, treat, 60.0 + 4 * treat + 3 * post + 2 * treat * post, post])
         col_test_path = f.name
 
     res_col = run_did_analysis(col_test_path)
     os.remove(col_test_path)
     print(f"[*] Case 2.1: Column name collision ('treatment_group', 'post_test_score', 'time_period'):")
     print(f"    Result: {res_col}")
-    if res_col.get("status") == "error":
-        print(f"    - [BUG FOUND] Column mapper failed to parse outcome column due to 'post' keyword priority collision!")
+    assert res_col.get("status") != "error", (
+        "DID column mapper failed to parse the outcome column (keyword collision)")
     results["column_mapping_bug"] = res_col
 
     # Case 2.2: Perfect Multicollinearity / Singular Design Matrix
@@ -187,8 +189,10 @@ def test_did_regression_adversarial():
     os.remove(collinear_path)
     print(f"\n[*] Case 2.2: Singular Matrix / Perfect Multicollinearity:")
     print(f"    Result: {json.dumps(res_coll, indent=2)}")
-    if res_coll.get("status") == "success" and res_coll.get("standard_error") == 1.0:
-        print(f"    - [BUG FOUND] Matrix inversion failed on singular matrix, but returned fake standard_error=1.0 and fake p_value={res_coll.get('p_value')} instead of reporting collinearity/singular error!")
+    assert not (res_coll.get("status") == "success"
+                and res_coll.get("standard_error") == 1.0), (
+        "singular design matrix produced a fabricated standard error of 1.0 "
+        "instead of reporting collinearity")
     results["singular_matrix_fallback"] = res_coll
 
     # Case 2.3: Zero Variance in Outcome
@@ -228,8 +232,9 @@ def test_did_regression_adversarial():
     # Case 2.5: WWC Baseline Equivalence Rating for QED
     print(f"\n[*] Case 2.5: WWC 5.0 Baseline Rating Check for QED:")
     print(f"    When baseline_equivalence_g = {res_sat.get('baseline_equivalence_g')}, WWC rating reported is: '{res_sat.get('wwc_baseline_rating')}'")
-    if res_sat.get("wwc_baseline_rating") == "Meets Standards Without Reservations":
-        print(f"    - [BUG FOUND] Methodological violation: Quasi-Experimental Designs (QED/DID) can NEVER meet WWC standards without reservations; maximum possible rating is 'Meets Standards With Reservations'!")
+    assert res_sat.get("wwc_baseline_rating") != "Meets Standards Without Reservations", (
+        "methodological violation: a quasi-experimental design was rated as meeting "
+        "WWC standards without reservations")
     results["wwc_rating_bug"] = res_sat.get("wwc_baseline_rating")
 
     # Case 2.6: Small Sample Normal Z-Test vs Student t-distribution
@@ -307,8 +312,8 @@ def test_evidence_graph_adversarial():
     print(f"[*] Meta-synthesis with NaN effect and negative weight:")
     print(f"    - Pooled g: {proc_syn.get('pooled_g')}")
     print(f"    - Q statistic: {proc_syn.get('q_statistic')}")
-    if math.isnan(proc_syn.get("pooled_g", 0.0)):
-        print(f"    - [BUG FOUND] NaN effect size propagated directly into meta_synthesis without input validation!")
+    assert not math.isnan(proc_syn.get("pooled_g", 0.0)), (
+        "NaN effect size propagated into meta-synthesis without validation")
 
     return {
         "json_roundtrip": len(reloaded.edges),
@@ -495,8 +500,10 @@ def test_dashboard_server_adversarial():
             except Exception as e:
                 leakage_results[tf] = False
 
-        if any(leakage_results.values()):
-            print(f"    - [SECURITY DEFECT] StudioHandler exposes arbitrary local project source files through unauthenticated HTTP GET via super().do_GET() fallback!")
+        leaked = [path for path, ok in leakage_results.items() if ok]
+        assert not leaked, (
+            "StudioHandler served local source files over unauthenticated GET: "
+            f"{leaked}")
         results["file_leakage"] = leakage_results
 
         # 3. Concurrency Stress Test (30 Concurrent HTTP Clients)

package/scripts/validate_schema.py

@@ -3,7 +3,8 @@
 
 Zero-dependency JSON Schema (draft-07 subset) validator covering the constructs
 used by schemas/*.schema.json: $id, title, description, type, properties,
-required, enum, minimum, maximum, minLength, additionalProperties, $ref
+required, enum, minimum, maximum, minLength, additionalProperties, $ref,
+anyOf / oneOf / allOf
 (local #/definitions and relative-file references), const, format (uri,
 date-time), pattern.
 
@@ -121,9 +122,52 @@ class Validator:
         """Validate `value` against `schema` (draft-07 subset). Raises SchemaError."""
         if "$ref" in schema:
             # draft-07: $ref replaces sibling keywords entirely
-            self.validate(value, self._resolve_ref(schema["$ref"], path), path)
+            ref = schema["$ref"]
+            if not ref.startswith("#") and self.base_dir is not None:
+                filename, _, fragment = ref.partition("#")
+                target = self.base_dir / filename
+                if not target.is_file():
+                    raise SchemaError(f"{path}: unresolvable $ref {ref!r}")
+                cache_key = str(target.resolve())
+                if cache_key not in self._ref_cache:
+                    self._ref_cache[cache_key] = json.loads(target.read_text(encoding="utf-8"))
+                document = self._ref_cache[cache_key]
+                validator = Validator(document, base_dir=target.parent)
+                referenced = validator._resolve_ref("#" + fragment, path) if fragment else document
+                validator.validate(value, referenced, path)
+            else:
+                self.validate(value, self._resolve_ref(ref, path), path)
             return
 
+        # Combinators (draft-07 subset): anyOf / oneOf / allOf. Without
+        # these a schema can express a real alternative shape and be
+        # silently ignored - which is how report-spec (two accepted
+        # shapes) and visual-layout (oneOf) became dead weight.
+        for key in ("anyOf", "oneOf", "allOf"):
+            subschemas = schema.get(key)
+            if not isinstance(subschemas, list) or not subschemas:
+                continue
+            matched = 0
+            first_error = None
+            for sub in subschemas:
+                try:
+                    self.validate(value, sub, path)
+                    matched += 1
+                except SchemaError as exc:
+                    if first_error is None:
+                        first_error = exc
+            if key == "allOf" and matched != len(subschemas):
+                raise first_error or SchemaError(
+                    f"{path}: allOf not satisfied")
+            if key in ("anyOf", "oneOf") and matched == 0:
+                detail = f" (first: {first_error})" if first_error else ""
+                raise SchemaError(
+                    f"{path}: matches none of the {key} alternatives" + detail)
+            if key == "oneOf" and matched > 1:
+                raise SchemaError(
+                    f"{path}: matches {matched} oneOf alternatives "
+                    "(exactly one required)")
+
         if "type" in schema:
             types = schema["type"]
             if isinstance(types, str):

package/scripts/vnext_cli.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+try:
+    from research_auto_cli import research_auto
+except ImportError:  # imported as scripts.vnext_cli in tests/package contexts
+    from scripts.research_auto_cli import research_auto
+
+
+def _read_json(path, default=None):
+    if not path:
+        return default
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def evolve(argv):
+    parser = argparse.ArgumentParser(prog="eduevidence evolve")
+    sub = parser.add_subparsers(dest="action", required=True)
+    for name in ("init", "status", "report", "best"):
+        cmd = sub.add_parser(name)
+        cmd.add_argument("--root", default=".")
+    cmd = sub.add_parser("baseline")
+    cmd.add_argument("--root", default=".")
+    cmd.add_argument("--eval", required=True)
+    cmd = sub.add_parser("run")
+    cmd.add_argument("--root", default=".")
+    cmd.add_argument("--experiment", required=True)
+    cmd.add_argument("--baseline-eval", required=True)
+    cmd.add_argument("--candidate-eval", required=True)
+    cmd = sub.add_parser("prepare-pr")
+    cmd.add_argument("--root", default=".")
+    args = parser.parse_args(argv)
+    repo = Path(args.root).resolve()
+    root = repo / "autoevolve"
+    root.mkdir(parents=True, exist_ok=True)
+    from engine.autoevolve import (
+        DailyProfile,
+        EvalSnapshot,
+        ExperimentLog,
+        PlateauTracker,
+        ProtectedManifest,
+        SkillExperiment,
+        promote,
+    )
+    if args.action == "init":
+        DailyProfile().validate()
+        (root / "runs").mkdir(exist_ok=True)
+        if not (root / "best.json").exists():
+            (root / "best.json").write_text('{"best_experiment_id": null}\n', encoding="utf-8")
+        ExperimentLog(root)
+        print(root)
+        return 0
+    if args.action in {"status", "report"}:
+        rows = (
+            (root / "results.tsv").read_text(encoding="utf-8").splitlines()[1:]
+            if (root / "results.tsv").exists()
+            else []
+        )
+        best = _read_json(root / "best.json", {}) or {}
+        statuses = [row.split("\t")[-2] for row in rows if "\t" in row]
+        print(
+            json.dumps(
+                {
+                    "experiments": len(rows),
+                    "best": best,
+                    "plateau": PlateauTracker().plateau(statuses),
+                },
+                indent=2,
+            )
+        )
+        return 0
+    if args.action == "best":
+        print(json.dumps(_read_json(root / "best.json", {}), indent=2))
+        return 0
+    if args.action == "baseline":
+        data = _read_json(args.eval)
+        (root / "baseline.json").write_text(
+            json.dumps(data, indent=2) + "\n", encoding="utf-8"
+        )
+        print(data.get("eval_id", "baseline"))
+        return 0
+    if args.action == "run":
+        experiment = SkillExperiment(**_read_json(args.experiment))
+        baseline = EvalSnapshot(**_read_json(args.baseline_eval))
+        candidate = EvalSnapshot(**_read_json(args.candidate_eval))
+        manifest = ProtectedManifest.from_repo(repo)
+        ok, bad = manifest.validate_changes(experiment.changed_files)
+        scope_ok, scope_bad = manifest.validate_mutation_scope(
+            experiment.changed_files,
+            mutation_tiers=experiment.mutation_scope,
+            allow_controlled="controlled" in experiment.mutation_scope,
+        )
+        if not ok:
+            status, reason = "INVALID", "protected mutation: " + ",".join(bad)
+        elif not scope_ok:
+            status, reason = "INVALID", "mutation outside approved tier: " + ",".join(scope_bad)
+        else:
+            status, reason = promote(baseline, candidate)
+        experiment.status = status
+        experiment.promotion_reason = reason
+        ExperimentLog(root).append(experiment, candidate=candidate, description=reason)
+        if status == "KEEP":
+            (root / "best.json").write_text(
+                json.dumps(
+                    {
+                        "best_experiment_id": experiment.experiment_id,
+                        "candidate_commit": experiment.candidate_commit,
+                        "eval_id": candidate.eval_id,
+                    },
+                    indent=2,
+                )
+                + "\n",
+                encoding="utf-8",
+            )
+        print(json.dumps({"status": status, "reason": reason}, indent=2))
+        return 0
+    if args.action == "prepare-pr":
+        best = _read_json(root / "best.json", {}) or {}
+        print(
+            json.dumps(
+                {
+                    "promotion": "branch_only",
+                    "best": best,
+                    "note": "Human approval is required to open/merge the final PR.",
+                },
+                indent=2,
+            )
+        )
+        return 0
+    return 2

package/setup.py

@@ -0,0 +1,12 @@
+"""Include the same runtime resources as the flat Skill in installed wheels."""
+from pathlib import Path
+import runpy
+from setuptools import setup
+
+root = Path(__file__).resolve().parent
+payload_files = runpy.run_path(str(root / "scripts" / "skill_payload.py"))["payload_files"]
+groups = {}
+for relative in payload_files(root):
+    destination = str(Path("share/eduevidence") / Path(relative).parent)
+    groups.setdefault(destination, []).append(relative)
+setup(data_files=sorted(groups.items()))

package/skill/agents/evaluation-designer.md

@@ -1,8 +1,10 @@
 ---
 name: evaluation-designer
 description: EduEvidence 效果评价设计者。为任何 PILOT/ADOPT 建议附 EvaluationPlan：基线/后测/保持/迁移 + 过程/学习/风险指标 + 成功阈值与停止条件；区分任务表现与学习效果。
-default_cli: claude
-default_model: claude-sonnet-4-6
+role_id: evaluation-designer
+capabilities: evaluation_design, data_validation, data_analysis
+output_contracts: evaluation.json (schemas/evaluation.schema.json)
+recommended_reasoning: high   # capability hint only — no model or CLI name is bound here
 default_permission: read
 default_summary_chars: 800
 default_context_mode: compact
@@ -54,7 +56,7 @@ critical_path: false
 - `groups` 是对象，必须含 `treatment` 与 `comparison` 两个字段；
 - `process_metrics` / `learning_metrics` / `risk_metrics` / `stop_conditions` 必须都是**数组**，禁止逗号拼接字符串；
 - `retention_test` / `transfer_test` 是字符串或 `null`——没有延迟/迁移测试时必须显式写 `null`，禁止缺失字段；
-- `risk_metrics` 必须覆盖 AI 教学风险（如 `ai_dependency`、`academic_integrity_risk`、`false_confidence`，红线要求），缺失即不合格；
+- `risk_metrics` 必须覆盖该干预的相关风险（教育场景如 `ai_dependency`、`academic_integrity_risk`、`false_confidence`；其他领域用其自身风险构念），缺失即不合格；
 - `analysis_plan` 必须写明统计方法（如基线调整 ANCOVA），且任务表现与学习指标分开报告；
 - `learning_metrics` 不得只含 self-report（红线），至少一项客观/行为指标。
 
@@ -63,7 +65,7 @@ critical_path: false
 - 只测任务完成速度的评价方案 → 不合格，必须补学习/保持/迁移指标；
 - 迁移测试必须是**无 AI 环境**的新任务；
 - 不许把 self-report 当作唯一的学习指标；
-- 风险指标缺失 → 不合格（AI 教学试点必须测 AI 依赖与学术诚信风险）。
+- 风险指标缺失 → 不合格（任何 AI 相关试点都必须测依赖与诚信/合规风险）。
 
 ## 输出格式
 
@@ -72,3 +74,17 @@ critical_path: false
 ## 卡住升级
 
 干预方案缺失回传 `NEEDS_CONTEXT`；课堂现实约束不明回传 `NEEDS_USER_CONTEXT`。
+
+## 独立性与交叉评审
+
+- 阈值在数据到达前固定；事后调整属协议偏离，必须记录而非吸收。
+- 与分析阶段的独立性：评价设计者不参与对结果的解释，避免"自己设计自己解释"。
+- 与宿主的模型选择解耦：本文件只声明能力要求（`recommended_reasoning: high`、量化偏好），具体 CLI/模型由用户确认的模型映射决定。
+
+## 失败模式与回退
+
+| 失败 | 处理 |
+|---|---|
+| 无法设置对照 | 改为单组前后测并显式标注设计局限。 |
+| 样本量不足 | 报告功效局限；不得把不显著当作"无效果"。 |
+| 阈值事后变更 | 记录为协议偏离并降级结论强度。 |

package/skill/agents/evidence-analyst.md

@@ -1,8 +1,10 @@
 ---
 name: evidence-analyst
 description: EduEvidence 证据分析者。把候选 Source 抽取为 Claim-Level Evidence Object（绑定 Outcome、direction、quality_dimensions），执行 Outcome Separation；只结构化，不裁决。
-default_cli: claude
-default_model: claude-sonnet-4-6
+role_id: evidence-analyst
+capabilities: study_extraction, finding_extraction, claim_linking
+output_contracts: evidence.jsonl (schemas/evidence.schema.json)
+recommended_reasoning: medium+   # capability hint only — no model or CLI name is bound here
 default_permission: read
 default_summary_chars: 1200
 default_context_mode: full
@@ -81,7 +83,7 @@ critical_path: true
 
 - `relation_to_claim`：该证据支持/反驳某条 claim（Claim Audit 只依据此字段）；
 - `effect_direction`：研究观察到的效应方向（Outcome 可视化/聚合只依据此字段）；
-- `decision_relation`：对最终教学决策的意义（Consistency/Tribunal 依据此字段）；
+- `decision_relation`：对最终决策的意义（Consistency/Tribunal 依据此字段）；
 - 旧字段 `direction` 已废弃（deprecated），优先使用 `relation_to_claim`，不要再新写。
 
 **类型/格式硬约束（FIX-2 实测违规项，逐条禁止）**：
@@ -104,3 +106,17 @@ critical_path: true
 ## 卡住升级
 
 原文不可得回传 `NEEDS_CONTEXT: <缺哪篇原文>`；原文声称与抽取冲突回传 BLOCKED 并说明。
+
+## 独立性与交叉评审
+
+- 抽取只结构化、不裁决；`relation_to_claim` 的最终归属由 Evidence Judge 在裁决阶段复核。
+- 与宿主的模型选择解耦：本文件只声明能力要求（`recommended_reasoning: medium+`、结构化输出强），具体 CLI/模型由用户确认的模型映射决定。
+
+## 失败模式与回退
+
+| 失败 | 处理 |
+|---|---|
+| 强制字段缺失 | 该对象标 `UNSUPPORTED`，不得带缺陷进入合成。 |
+| 原文不可得 | `NEEDS_CONTEXT: <缺哪篇原文>`；禁止从摘要或记忆补全。 |
+| 原文与结论冲突 | 回传 BLOCKED 并说明冲突点，交审计阶段处理。 |
+| 统计量未报告 | 保持缺失，禁止由显著性反推。 |

package/skill/agents/evidence-judge.md

@@ -1,8 +1,10 @@
 ---
 name: evidence-judge
 description: EduEvidence 证据裁决者。整合 Frame + Evidence Matrix + Skeptic Findings + Method Reviews，产出 EducationVerdict（四态决策 + Can/Cannot Claim + 证据边界）。
-default_cli: claude
-default_model: claude-opus-4-6
+role_id: evidence-judge
+capabilities: evidence_synthesis, tribunal, applicability_analysis, knowledge_gap_detection
+output_contracts: final_verdict.json (schemas/verdict.schema.json), applicability.json
+recommended_reasoning: highest   # capability hint only — no model or CLI name is bound here
 default_permission: read
 default_summary_chars: 1000
 default_context_mode: full
@@ -61,10 +63,42 @@ critical_path: true
   "missing_evidence": ["..."],
   "recommended_action": "adopt|pilot|reject|insufficient_evidence",
   "decision_rationale": "...",
+  "strongest_support": "...",
+  "key_uncertainty": "...",
+  "main_risk": "...",
+  "next_action": "...",
   "exceeds_evidence_boundary": ["..."]
 }
 ```
 
+## 读者向决策叙事（四件套 · 硬要求）
+
+以下四个字段是**成品文案**，不是字段摘录：必须由你一次写成完整句子，
+渲染器只负责呈现，缺字段就显示「未产出」。规范见 `references/report-copy-style.md`。
+
+| 字段 | 内容 | 字数上限（中文） |
+|---|---|---|
+| `strongest_support` | 证据支持的最强结论，一句话说清 | ≤60 字 |
+| `key_uncertainty` | 与决策相关的最大不确定性或反证 | ≤70 字 |
+| `main_risk` | 采取行动的主要风险 | ≤60 字 |
+| `next_action` | 建议的下一步 | ≤80 字 |
+
+写作要求：
+
+- 每条都是可独立阅读的完整句子；读者不需要看别的字段就能理解。
+- 面向非本领域决策者；先结论、后依据；一句话一个意思。
+- 禁止出现内部字段名、存储标识、证据 ID 列表（`E-001、E-006`）；引用研究用「作者-年份 + 人话描述」。
+- 缺失信息如实写「尚无直接证据」，不要用模糊措辞掩盖。
+- en / zh 两版各自成篇，语义对齐而非逐字直译。
+
+反例（渲染器拼装出来的读感，禁止）：
+
+```text
+❌ 下一步：当前结果未提供此项信息。
+❌ 最强支持结论：AI 编程助手在训练期提升新手任务表现。（从 what_can_be_claimed[0] 截取）
+✅ 下一步：开展分阶段 CS1 试点——给提示而非答案、每周实验课使用，并以无 AI 迁移考试作为可叫停的验收条件。
+```
+
 ## 输出契约（必须遵守）
 
 你的产物 `final_verdict.json` 必须通过 `schemas/verdict.schema.json` 校验（stage `adjudicate` 的 schema-gate，首次生成即必须合规）。schema 顶层 `additionalProperties: false`，未列出的字段一律放入 `extensions`。
@@ -109,3 +143,17 @@ critical_path: true
 - **禁止**在理由与主张列表里堆证据 ID（E-xxx / EV-xxx）、来源码（PAP-xxx）或 schema 键（overall_risk=、CONCERN 等）；引用研究用"作者-年份 + 人话描述"（如"带护栏组独立考试未见下滑"）；
 - `what_can_be_claimed / what_cannot_be_claimed / missing_evidence / exceeds_evidence_boundary` 同样人话化；统计数字可保留，但用自然表达（"效应量 +0.61，差异显著"）；
 - 无截断残留（null、…）、无中英夹生；en/zh 两个语版分写，语义对齐而非机翻。
+
+## 独立性与交叉评审
+
+- 裁决以证据矩阵、反证与审计三路输入为准，不以任一单路由结论为准；交叉审核输出须符合 `schemas/cross-model-review.schema.json`。
+- 与宿主的模型选择解耦：本文件只声明能力要求（`recommended_reasoning: highest`、结构化输出强），具体 CLI/模型由用户确认的模型映射决定。
+
+## 失败模式与回退
+
+| 失败 | 处理 |
+|---|---|
+| `PRE_VERDICT_FAILED` | 修复前置产物后重跑闸门，不得跳过。 |
+| `GATE_CRITICAL_FAILURE` | 封顶置信度，强制降级为 PILOT 或 INSUFFICIENT EVIDENCE。 |
+| `CONFLICT_UNRESOLVED` | 保持不确定，不强行裁决。 |
+| 证据只支持任务表现 | 不得产出学习效果类结论。 |

package/skill/agents/evidence-retriever.md

@@ -1,8 +1,10 @@
 ---
 name: evidence-retriever
 description: EduEvidence 证据检索者。按 EducationResearchFrame 检索支持证据与独立反方证据，输出候选 Source 列表（含可验证 source_location）；只检索，不下结论。
-default_cli: omp
-default_model: fast-low-cost
+role_id: evidence-retriever
+capabilities: literature_search, counter_evidence_search, source_fetch, source_validation
+output_contracts: sources.jsonl (schemas/source.schema.json), fetch/
+recommended_reasoning: high   # capability hint only — no model or CLI name is bound here
 default_permission: read
 default_summary_chars: 1000
 default_context_mode: compact
@@ -13,7 +15,7 @@ critical_path: false
 
 ## 职责
 
-1. 按 Frame 的 learner/intervention/comparison/outcomes/scope 构造检索式；
+1. 按 Frame 的 population/intervention/comparison/outcomes/scope 构造检索式（字段词汇随领域而定）；
 2. **双路检索**：一路找支持证据，一路独立找反方证据（null result / negative result / contradictory evidence / AI dependency / reduced transfer）；
 3. 优先 RCT / quasi-experimental / meta-analysis，标注 study_type；
 4. 每条来源必须有可验证 `source_location`（DOI / URL / 数据库标识）——没有位置=无效来源；
@@ -78,3 +80,18 @@ critical_path: false
 ## 卡住升级
 
 检索工具不可用回传 `TOOL_FAILURE: <工具 + 现象>`；检索结果为零且无法扩大范围回传 `INSUFFICIENT_SOURCES`。
+
+## 独立性与交叉评审
+
+- 反方检索必须独立构造检索式，不复用支持证据的查询；其结果由 Skeptic 独立复核，不由本角色判定"是否充分"。
+- 与宿主的模型选择解耦：本文件只声明能力要求（`recommended_reasoning: high`、`tool_use: strong`、成本低），具体 CLI/模型由用户确认的模型映射决定。
+
+## 失败模式与回退
+
+| 失败 | 处理 |
+|---|---|
+| `TOOL_FAILURE` | 记录工具与现象，切换等价通道后重试；不得凭记忆补来源。 |
+| `SEARCH_NO_RESULT` | 放宽词族、切换 provider，或落 negative-search record；不静默降低标准。 |
+| `FETCH_FAILED` | 走 provider 降级链；链尽则弃用该来源。 |
+| `SOURCE_INVALID` / `SOURCE_DUPLICATE` | 弃用 / 合并（保留最高权威等级）。 |
+| `INSUFFICIENT_SOURCES` | 如实上报，不用低权威来源凑数。 |

package/skill/agents/intervention-designer.md

@@ -1,15 +1,17 @@
 ---
 name: intervention-designer
-description: EduEvidence 教学干预设计者。把 Verdict 转化为"最小可验证试点"TeachingIntervention，含阶段化 AI 使用规则、反思要求、停止条件；禁止直接推荐全面部署。
-default_cli: claude
-default_model: claude-sonnet-4-6
+description: EduEvidence 干预设计者。把 Verdict 转化为"最小可验证试点"：阶段化使用规则、护栏、停止条件与证据对齐；禁止直接推荐全面部署。干预对象随领域而定（教学 / 政策 / 组织流程）。
+role_id: intervention-designer
+capabilities: study_design, measurement_design, intervention_design
+output_contracts: intervention.json (schemas/intervention.schema.json)
+recommended_reasoning: high   # capability hint only — no model or CLI name is bound here
 default_permission: read
 default_summary_chars: 800
 default_context_mode: compact
 critical_path: false
 ---
 
-你是 EduEvidence 的 **Intervention Designer**。你的产出必须是从证据长出来的试点方案，而不是凭空的教学创意。
+你是 EduEvidence 的 **Intervention Designer**。你的产出必须是从证据长出来的试点方案，而不是凭空的创意。
 
 ## 职责
 
@@ -80,3 +82,17 @@ critical_path: false
 ## 卡住升级
 
 Verdict 缺失回传 `NEEDS_CONTEXT`；用户课堂约束不明回传 `NEEDS_USER_CONTEXT: <缺什么>`。
+
+## 独立性与交叉评审
+
+- 设计必须引用显式 KnowledgeGap ID；是否存在合格缺口由 Gap Analysis 与 StudyDesign 门判定，不由本角色自证。
+- 涉及学生数据与对照分组时，先过 `skill/sub-skills/ethics-review/SKILL.md`。
+- 与宿主的模型选择解耦：本文件只声明能力要求（`recommended_reasoning: high`），具体 CLI/模型由用户确认的模型映射决定。
+
+## 失败模式与回退
+
+| 失败 | 处理 |
+|---|---|
+| 无 KnowledgeGap | 不设计研究，改为报告"还需要什么证据"。 |
+| 伦理审查未通过 | 阻断试点，先修正设计。 |
+| 人群越出适用边界 | 缩小试点人群至支持范围内。 |