eduevidence 5.2.0 → 6.0.0

package/scripts/skill_payload.py

@@ -0,0 +1,78 @@
+"""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",
+    "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",
+    "release-closeout/README.md", "release-closeout/issues.md",
+    "release-closeout/frontend-acceptance.md", "release-closeout/verification.md",
+)
+EXAMPLES = (
+    "ai-coding-assistant-evidence", "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/validate_schema.py

@@ -121,7 +121,21 @@ 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
 
         if "type" in schema:

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/roles/registry.yaml

@@ -0,0 +1,45 @@
+roles:
+  education-planner:
+    responsibility: framing completeness and scope
+    stages: [frame]
+    capabilities: [research-planning]
+    critical_path: true
+  evidence-retriever:
+    responsibility: source acquisition and provenance
+    stages: [retrieve]
+    capabilities: [literature-review, full-text-fetch, source-validation]
+  evidence-analyst:
+    responsibility: structured finding extraction
+    stages: [extract]
+    capabilities: [evidence-extraction]
+  skeptic:
+    responsibility: independent counter-evidence coverage
+    stages: [challenge]
+    capabilities: [contradiction-analysis, counter-retrieval]
+    independence_required: true
+    critical_path: true
+  method-reviewer:
+    responsibility: methodology and construct-validity appraisal
+    stages: [audit]
+    capabilities: [methodology-audit]
+    independence_required: true
+    critical_path: true
+  evidence-judge:
+    responsibility: evidence-bounded adjudication and applicability
+    stages: [adjudicate, applicability]
+    capabilities: [evidence-review, decision-adjudication, applicability]
+    critical_path: true
+  intervention-designer:
+    responsibility: grounded intervention or pilot design
+    stages: [intervene]
+    capabilities: [study-design, intervention-design]
+  evaluation-designer:
+    responsibility: estimable evaluation and update logic
+    stages: [evaluate]
+    capabilities: [evaluation-design, data-analysis]
+
+execution:
+  max_parallel_workers: 6
+  split_by: evidence_axis
+  single_writer: lead-orchestrator
+  recursive_swarm: false

package/skill/sub-skills/report-generation/SKILL.md

@@ -7,23 +7,29 @@ description: "Renders 5 baked-theme single-file bilingual HTML reports, executiv
 ## 1. When to Use
 Trigger at the completion of a research cycle (Step 9: Present stage) to deliver visual dossiers, decision briefs, and publication-grade reports.
 
-## 2. Lieflat Charts Editorial Standards Integration
-All statistical figures, evidence matrices, and causal trajectories follow the **Lieflat Charts Editorial Codex** (`visualization/lieflat-charts/`). Chart galleries are **AI-composed but data-driven**: the upstream AI writes a chart plan (`visual_layout`), and the deterministic renderer extracts every number from `result.json` via `scripts/charts_data.py`. **The AI never writes numeric values into the layout** — values are un-tamperable and always traceable.
+## 2. AI-Composed Data Visualization
+Use the self-contained selection catalog at `visualization/eduevidence-report/references/chart-selection-catalog.md` together with the executable registry in `references/lieflat-composition.md`. Chart galleries are **AI-composed but data-driven**: the upstream AI writes a chart plan (`visual_layout`), and the deterministic renderer extracts every number from `result.json` via `scripts/charts_data.py`. **The AI never writes numeric values into the layout** — values are traceable and cannot be replaced by invented chart data.
 
 ### 2.1 Six-Step Chart Composition Workflow
 1. **判数据形状。** 看 `result.json` 的数据长什么样（效应量 g+CI / 年份×维度 / 方向计数 / 阶段周区间 / 置信度单值 / 审计状态……），形状是选图的主键。
-2. **按 catalog 审计候选。** 在 `visualization/lieflat-charts/catalog.md` 按数据形状召回候选，至少比较 3 个并写下淘汰理由（语义契合、单位诚实、标签容纳、阅读速度、本批次是否重复）。Glance 系只在 Lupi/Basics 不适配或用户明确要求快读时进入候选。
+2. **按自包含 catalog 审计候选。** 在 `visualization/eduevidence-report/references/chart-selection-catalog.md` 按数据形状召回候选；通常比较至少 3 个可行图型并写下淘汰理由（语义契合、单位诚实、标签容纳、阅读速度、移动端适配、本批次是否重复）。如果数据形状只有 1–2 个有效候选，不得为了凑满 3 个选择语义错误的图。
 3. **锁定注册表 `type`。** 只能选 `visualization/eduevidence-report/references/lieflat-composition.md` 注册表内的图型（type ↔ 目录编号 ↔ 数据形状 ↔ 提取器）；**未注册 type 会显式报错并被丢弃，不存在静默回退**。
 4. **写 `report_outline` + `visual_layout`。** 每张图承担一个独立结论；总数 ≤6 张；同一批形状不重复（不堆同类环/条/点阵）；每张图写清 `type / catalog_ref / title_zh+en / subtitle_zh+en / caption_zh+en / source / params`，副标题写清图例与单位；主题色系由烘焙主题锁定，布局不得换色。
 5. **渲染。** 运行 `build_report.py`（或 `scripts/rebake_all_5themes.py`）——渲染器对每个条目走注册表提取器：数据不足 → 该图抑制并记录原因（镜像 Meaningful Visualization Gate）；全部无效 → 确定性安全组合（forest_plot + dot_cascade + bubble_almanac + tick_rows）。
-6. **按 Lieflat skill 第八节自检**（面积 sqrt、最小字号 6.5/5.5px、数值 800、reveal 滚入播放 + 点击重播 + reduced-motion、卡片四件套齐全、数值与视觉成正比）。
+6. **按本地 catalog + 渲染不变量自检**（面积 sqrt、最小字号 6.5/5.5px、数值 800、reveal 滚入播放 + 点击重播 + reduced-motion、卡片四件套齐全、数值与视觉成正比）。
 
 ### 2.2 数据契约：AI 写计划，渲染器出数
 - `visual_layout` 条目 = 图型 + 目录编号 + 双语文案 + 数据源参数。**数值一律由 `scripts/charts_data.py` 的提取器从 `result.json` 读出**，渲染器只接收提取器 bundle——被篡改的数值天然不被采用，完整性门 `lieflat_data_bound` 逐值核对溯源。
 - 50 篇级大样本 → 提取器 top-N 截断 + SVG `<title>` 悬停读数，不加欺骗性交互。
 - 中文长类目 → 按决策树选横排图（F5/F1/F6 系），L2 cascade 类目名 ≤4 字约束保留。
 
-### 2.3 5 Theme Palettes Adaptive Binding (Zero-CDN Guarantee)
+### 2.3 Tables are audit surfaces, not failed visualizations
+- Keep `EvidenceMatrix`, `SourceList`, methodology details, and `ClaimTrace` for exact row-level verification and provenance.
+- Use charts for patterns, comparisons, distributions, composition, time/phase structure, and decision summaries.
+- Never replace a provenance table merely to make the report look more visual. A chart may summarize a table, but the auditable rows remain reachable.
+- If no chart adds information without inventing missing values or mixing incompatible outcomes, suppress the visualization and explain why.
+
+### 2.4 5 Theme Palettes Adaptive Binding (Zero-CDN Guarantee)
 Every chart is rendered as **pure self-contained inline SVG** following the baked report theme's color system:
 - **`claude` (智库典雅)** ➔ **Lieflat Palm (暖棕)**: `#FAF7F2` paper base, `#B8694A` terracotta, `#5E8A6A` forest green, `#C99A4A` amber.
 - **`academic` (学术顶刊)** ➔ **Lieflat Mono / Nature (学术黑白灰)**: `#FFFFFF` paper base, `#0F172A` ink black, Okabe-Ito colorblind-safe accents.
@@ -33,7 +39,7 @@ Every chart is rendered as **pure self-contained inline SVG** following the bake
 
 Dark themes draw on the theme's `card_bg`; text contrast is checked against the theme palette (≥4.5:1 for body/labels). The chart structure is identical across light/dark — only colors change.
 
-### 2.4 排版守则（五主题统一约束）
+### 2.5 排版守则（五主题统一约束）
 五个烘焙主题的排版必须通过 `scripts/lint_report_layout.py`（静态不变量 + 浏览器级
 390/768/1280 × brief/full 实测）：轨道 `minmax(0,1fr)` / `minmax(min(Npx,100%),1fr)`、
 主题自带移动端媒体覆写、禁止裸 `1fr` 与固定 px 最小值 auto-fit、表格外包 `overflow-x:auto`。

package/skill/task-briefs/applicability.md

@@ -0,0 +1,3 @@
+# Applicability stage
+
+Assess transportability to the target population and setting. State supported population, implementation conditions, excluded populations, outcome limits, and uncertainty. Do not infer applicability from the presence of a positive result.

package/skill/task-briefs/projection.md

@@ -0,0 +1,3 @@
+# Projection stage
+
+Build reports and exports only from completed artifacts and decision snapshots. Projection errors must not change a scientific result. Record the exact source revision and rendered artifact hash.

package/skill/workflows/decision-and-pilot.md

@@ -0,0 +1,10 @@
+---
+name: decision-and-pilot
+description: Convert a bounded evidence decision into a reversible, measurable pilot.
+---
+
+# Decision & Pilot
+
+Use only after an Evidence Review has produced an auditable decision snapshot. Add `Intervene` with a minimal pilot, explicit stop conditions, owner, population, and outcome measures. A pilot is not an adoption claim.
+
+When this workflow is reached from Evidence Autoresearch, require the bridge in `references/autoresearch.md`: the KnowledgeGap is HIGH-DVI and decision-material, remains unresolved, bounded secondary search is saturated, and the empirical study is ethically/operationally feasible. Then still pass the existing grounded StudyDesign gate; “few papers found” alone never authorizes a pilot.

package/skill/workflows/evaluate-and-update.md

@@ -0,0 +1,10 @@
+---
+name: evaluate-and-update
+description: Re-inject validated outcome data into an evidence graph and re-adjudicate.
+---
+
+# Evaluate & Update
+
+Use when pilot or field data exists. Validate provenance and missingness before analysis, fail closed when inference is not estimable, commit a graph revision, then produce a new decision snapshot and a decision diff.
+
+For autonomous/living refreshes, preserve prior revisions and treat the newly re-adjudicated decision as a candidate update until the applicable review/human gate accepts it. New evidence does not need to flip the action; unchanged action with changed certainty, applicability, or boundary is a valid revision.

package/skill/workflows/evidence-review.md

@@ -0,0 +1,13 @@
+---
+name: evidence-review
+description: Traceable evidence review with mandatory counter-evidence and methodology gates.
+---
+
+# Evidence Review
+
+Use for a question that needs a bounded, decision-grade evidence assessment.
+Run `Frame → Retrieve → Extract → Challenge → Audit → Adjudicate → Applicability`.
+
+The required outputs are a search plan and attempt log, validated sources, claim-level evidence links, a methodology audit, a decision boundary, and applicability limits. Search snippets are discovery metadata, never evidence.
+
+When the user asks to continue autonomously, identify the next most decision-relevant evidence, or keep iterating until the evidence state reaches a bounded stopping condition, load `references/autoresearch.md`. Keep the public workflow unchanged: Evidence Autoresearch is a meta-layer over this review, not a fourth user-facing workflow. Preserve append-only evidence and the Single Writer rule.

package/visualization/eduevidence-report/assets/base.css

@@ -17,7 +17,7 @@ body { margin:0; background:var(--bg); color:var(--text);
 .controls { width:calc(100% - 36px); max-width:1200px; margin:0 auto 16px; padding:12px clamp(0px,1vw,12px); display:flex; gap:18px; flex-wrap:wrap; align-items:center;
             border-bottom:1px solid var(--border); }
 .report-header { border-bottom:1px solid var(--border); padding-bottom:16px; margin-bottom:24px; }
-.report-header h1 { font-family:var(--font-head); font-size:1.9rem; margin:0 0 8px; color:var(--text); }
+.report-header h1 { font-family:var(--font-head); font-size:1.55rem; margin:0 0 8px; color:var(--text); }
 .report-header .meta { color:var(--insufficient); font-size:.85rem; }
 .lang-switcher { display:flex; gap:8px; align-items:center; flex-wrap:wrap; }
 .lang-switcher span { font-size:.82rem; color:var(--insufficient); }
@@ -300,7 +300,7 @@ button:focus-visible, a:focus-visible, input:focus-visible, select:focus-visible
   .controls { width:calc(100% - 24px); margin-bottom:10px; padding-left:8px; padding-right:8px; }
   .report-shell { width:100%; padding:12px 14px 56px; }
   .report-header { width:100%; }
-  .report-header h1 { font-size:1.55rem; overflow-wrap:anywhere; }
+  .report-header h1 { font-size:1.3rem; overflow-wrap:anywhere; }
   .report-header .meta, .brief-source h3, .claim-cell, .detail-body, .source-detail-grid dd { overflow-wrap:anywhere; word-break:break-word; }
   .data-table { font-size:.78rem; }
   .hero-insights, .tribunal-grid, .scope-grid, .retrieval-grid, .brief-source-grid, .method-audit-grid { grid-template-columns:1fr; }