eduevidence 5.2.0

package/scripts/rebake_all_5themes.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""scripts/rebake_all_5themes.py — Re-bake all 5 themes for all 3 projects with Lieflat figures and human language.
+"""
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+PROJECTS = [
+    "examples/highschool-math-ai-tutor",
+    "examples/esl-academic-writing-ai",
+    "examples/ai-coding-assistant-evidence"
+]
+
+THEMES = ["claude", "academic", "datalab", "datalab-dark", "presentation"]
+
+
+def rebake():
+    for proj in PROJECTS:
+        p_dir = ROOT / proj
+        r_en = p_dir / "result.json"
+        r_zh = p_dir / "result.zh.json"
+        out_html = p_dir / "EduEvidence_Report.html"
+        themes_dir = p_dir / "reports-5themes"
+        themes_dir.mkdir(parents=True, exist_ok=True)
+        
+        print(f"\n==========================================")
+        print(f"Re-baking project: {proj}")
+        print(f"==========================================")
+        
+        # 1. Main report (default claude theme)
+        cmd = [
+            sys.executable,
+            str(ROOT / "visualization/eduevidence-report/scripts/build_report.py"),
+            "--result", str(r_en),
+            "--result-zh", str(r_zh),
+            "--out", str(out_html)
+        ]
+        res = subprocess.run(cmd, capture_output=True, text=True)
+        print(f"Main report: code={res.returncode}")
+        if res.returncode != 0:
+            print("STDERR:", res.stderr)
+            sys.exit(1)
+            
+        # 2. 5 theme reports
+        for t in THEMES:
+            t_out = themes_dir / f"report_{t}.html"
+            t_cmd = [
+                sys.executable,
+                str(ROOT / "visualization/eduevidence-report/scripts/build_report.py"),
+                "--result", str(r_en),
+                "--result-zh", str(r_zh),
+                "--theme", t,
+                "--out", str(t_out)
+            ]
+            t_res = subprocess.run(t_cmd, capture_output=True, text=True)
+            print(f"  Theme {t:15s} -> {t_out.name} (code={t_res.returncode})")
+            if t_res.returncode != 0:
+                print("  STDERR:", t_res.stderr)
+                sys.exit(1)
+            # Also copy to EduEvidence_Report_{t}.html for compatibility
+            compat_out = themes_dir / f"EduEvidence_Report_{t}.html"
+            compat_out.write_bytes(t_out.read_bytes())
+
+        # 3. Artifact manifest (HTML-03): all 5 theme HTMLs must embed the same
+        #    result.json hash; refresh artifact_manifest.json after the bake.
+        manifest_cmd = [
+            sys.executable,
+            str(ROOT / "visualization/eduevidence-report/scripts/build_artifact_manifest.py"),
+            "--result", str(r_en),
+            "--result-zh", str(r_zh),
+            "--html-dir", str(themes_dir),
+            "--out", str(p_dir / "artifact_manifest.json"),
+        ]
+        m_res = subprocess.run(manifest_cmd, capture_output=True, text=True)
+        print(f"Manifest: code={m_res.returncode} {m_res.stdout.strip()}")
+        if m_res.returncode != 0:
+            print("STDERR:", m_res.stderr)
+            sys.exit(1)
+
+    print("\nAll 3 projects (15 theme reports) successfully re-baked with Lieflat Charts!")
+
+
+if __name__ == "__main__":
+    rebake()

package/scripts/recompute_demo_quality.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""recompute_demo_quality.py — Recompute evidence quality scores for the demo
+against references/evidence-quality.md and emit an explainable report.
+
+The five dimensions (each 0/1/2, total 0-10) are recomputed from the evidence's
+own structured fields, so every score is traceable to a rubric rule:
+
+    D1 Study Design        -> study_type / comparison
+    D2 Sample Quality      -> sample_size / attrition / self-selection / baseline
+                              (population matching belongs to D5, NOT D2)
+    D3 Measurement Validity-> outcome_measure / method
+    D4 Temporal Strength   -> duration / method / outcome_measure
+                              (2 requires >=8-week intervention OR a retention/
+                              transfer measure)
+    D5 Directness          -> education_level / subject vs the target frame
+                              (university first-year C programming + generative
+                              AI coding assistant + independent problem solving)
+
+Usage:
+    python3 scripts/recompute_demo_quality.py [--evidence examples/ai-coding-assistant/evidence.jsonl]
+    python3 scripts/recompute_demo_quality.py --evidence ... --check
+
+--check additionally verifies that the quality_dimensions / quality_score
+stored in the data file match the recomputed values; exit code 1 on mismatch.
+
+Exit code 0 = recomputed successfully (and, with --check, data is consistent).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from evidence_score import quality_level
+
+# Target frame the demo decision is anchored to (frame.json).
+TARGET_FRAME = "大学一年级 C 语言课程 + 生成式 AI 编程助手 + 独立问题解决"
+
+DIMS = [
+    ("D1_study_design", "D1 研究设计"),
+    ("D2_sample_quality", "D2 样本质量"),
+    ("D3_measurement_validity", "D3 测量有效性"),
+    ("D4_temporal_strength", "D4 时间强度"),
+    ("D5_directness", "D5 直接性"),
+]
+
+
+def load_evidence(path: Path) -> list[dict]:
+    records = []
+    for lineno, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            records.append(json.loads(line))
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"{path}:{lineno}: invalid JSON: {exc}") from exc
+    return records
+
+
+# --- per-dimension rubric rules ---------------------------------------------
+
+def d1(ev: dict[str, Any]) -> tuple[int, str]:
+    study_type = ev.get("study_type", "")
+    has_control = bool(ev.get("comparison"))
+    if study_type == "rct" and has_control:
+        return 2, "RCT 随机对照试验，含对照组，干预与测量分离（rubric D1=2）。"
+    if has_control:
+        return 1, "有对照但非随机（如自然班对照 / 前后测对照），记 1 分（rubric D1=1）。"
+    return 0, "无对照的描述性 / 观察研究，记 0 分（rubric D1=0）。"
+
+
+def d2(ev: dict[str, Any]) -> tuple[int, str]:
+    """D2 只评样本量 / 流失 / 偏差 / 基线；人群匹配一律归 D5。"""
+    n = ev.get("sample_size")
+    confounders = " ".join(ev.get("confounders", []))
+    limitations = " ".join(ev.get("limitations", []))
+    method = ev.get("method", "")
+    if "self_selection" in confounders or "consent" in method or "自选" in limitations:
+        return 1, "知情同意 / 报名参与引入自选偏差（rubric D2=1：样本有偏差）。"
+    if isinstance(n, (int, float)) and n >= 100:
+        return 2, (f"样本量充足（n={int(n)}，每组 ≥ 30），随机分组并报告基线协变量，"
+                   "无显著流失（rubric D2=2）。")
+    if isinstance(n, (int, float)) and n >= 60 and ev.get("study_type") == "rct":
+        return 2, (f"总样本 n={int(n)}（两组各约 30+），随机分组、基线能力已测量并处理"
+                   "（rubric D2=2，按每组 ≥ 30 判）。")
+    if isinstance(n, (int, float)) and n >= 10:
+        return 1, f"样本量偏小（n={int(n)}，每组 10–30），记 1 分（rubric D2=1）。"
+    return 0, "样本量 < 10 或无样本描述，记 0 分（rubric D2=0）。"
+
+
+def d3(ev: dict[str, Any]) -> tuple[int, str]:
+    outcome = ev.get("outcome_type", "")
+    measure = ev.get("outcome_measure", "")
+    method = ev.get("method", "")
+    if outcome == "assignment_score" and "practice" in measure:
+        return 2, ("任务表现测量与声称结果（练习任务表现）对应，且同研究以独立闭卷考试"
+                   "明确区分任务表现与学习效果，未把任务表现当学习效果（rubric D3=2）。")
+    if outcome == "retention":
+        return 2, "标准延迟保持测试，测量与声称的保持力结果对应（rubric D3=2）。"
+    if "exam" in measure and "without" in measure:
+        return 2, "独立闭卷考试（无 AI 访问），客观评分，测量与学习效果结果对应（rubric D3=2）。"
+    if "modification" in measure:
+        return 1, "自编同场次代码修改任务，测量合理但未经验证、无盲评（rubric D3=1）。"
+    if "pre-post" in measure or "delayed" in method:
+        return 2, "前测-后测-延迟测设计，写作测试有规范评分（rubric D3=2）。"
+    if "task" in measure and "time" in measure:
+        return 2, "标准代码编写任务 + 客观进度 / 用时指标，评分有规范（rubric D3=2）。"
+    return 1, "测量合理但未验证（自编题目 / 自评量表），记 1 分（rubric D3=1）。"
+
+
+def d4(ev: dict[str, Any]) -> tuple[int, str]:
+    """>=8 周干预 或 含 retention/transfer 测量 才给 2 分。"""
+    text = " ".join(str(ev.get(k, "")) for k in ("duration", "method", "outcome_measure"))
+    if any(sig in text for sig in ("retention", "transfer", "delayed")):
+        return 2, "含保持测试 / 迁移测试（满足 >=8 周干预或含 retention/transfer 即给 2，rubric D4=2）。"
+    if "in_class" in text or "weeks" in text:
+        return 1, "干预 2–8 周（课堂学习时段），有后测但无保持 / 迁移测量（rubric D4=1）。"
+    return 0, "单次实验 / 单课时干预，或只有即时效果无后续测量（rubric D4=0）。"
+
+
+def d5(ev: dict[str, Any]) -> tuple[int, str]:
+    edu = ev.get("education_level", "")
+    subject = ev.get("subject", "")
+    if subject == "academic_writing_esl":
+        return 0, "仅变量名称相关：学术写作 vs 编程，结果与目标 Frame 不对应（rubric D5=0）。"
+    if edu == "k12_ages_10_17":
+        return 1, ("大致对应但有偏差：同为入门编程 + 代码生成工具，但学习者（K-12 10-17 岁）"
+                   "与课程（Python vs C 语言）不同（rubric D5=1）。")
+    if edu == "high_school":
+        return 1, ("大致对应但有偏差：同为生成式 AI 工具 + 独立问题解决，但高中（数学）"
+                   "vs 大学（C 编程）不同（rubric D5=1）。")
+    return 2, "干预 x 学习者 x 课程 x 工具 x 结果与目标 Frame 完全对应（rubric D5=2）。"
+
+
+RULES = {"D1_study_design": d1, "D2_sample_quality": d2,
+         "D3_measurement_validity": d3, "D4_temporal_strength": d4,
+         "D5_directness": d5}
+
+
+def recompute(ev: dict[str, Any]) -> tuple[dict[str, int], dict[str, str], float]:
+    dims: dict[str, int] = {}
+    reasons: dict[str, str] = {}
+    for key, _ in DIMS:
+        score, reason = RULES[key](ev)
+        dims[key] = score
+        reasons[key] = reason
+    return dims, reasons, sum(dims.values())
+
+
+def render_report(evidence_list: list[dict]) -> str:
+    lines = [
+        "Evidence Quality 重算报告（rubric: references/evidence-quality.md）",
+        f"目标 Frame: {TARGET_FRAME}",
+        "=" * 78,
+    ]
+    for ev in evidence_list:
+        dims, reasons, total = recompute(ev)
+        lines.append(f"\n{ev['evidence_id']}  {ev['claim']}")
+        lines.append(f"  source={ev.get('source_id')}  outcome={ev.get('outcome_type')}  "
+                     f"duration={ev.get('duration')}  n={ev.get('sample_size')}")
+        for key, label in DIMS:
+            lines.append(f"  {label} = {dims[key]}/2  ({reasons[key]})")
+        level = quality_level(total)
+        lines.append(f"  -> 总分 {total}/10 = {level}")
+    lines.append("\n" + "=" * 78)
+    lines.append("等级映射: 8-10 strong | 5-7 moderate | 2-4 weak | 0-1 very_weak (rubric 总分与等级)")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--evidence", default="examples/ai-coding-assistant/evidence.jsonl",
+                        help="Path to evidence.jsonl")
+    parser.add_argument("--check", action="store_true",
+                        help="Verify stored quality values match the recomputed ones")
+    args = parser.parse_args()
+
+    evs = load_evidence(Path(args.evidence))
+    print(render_report(evs))
+
+    if args.check:
+        mismatches = []
+        for ev in evs:
+            dims, _, total = recompute(ev)
+            stored_dims = ev.get("quality_dimensions", {})
+            stored_score = ev.get("quality_score")
+            if stored_dims != dims:
+                mismatches.append(f"{ev['evidence_id']}: stored dims {stored_dims} != recomputed {dims}")
+            if stored_score != total:
+                mismatches.append(f"{ev['evidence_id']}: stored score {stored_score} != recomputed {total}")
+        if mismatches:
+            print("\nCHECK FAILED:")
+            for m in mismatches:
+                print("  " + m)
+            return 1
+        print(f"\nCHECK PASSED: {len(evs)} 条证据存储的 quality_dimensions / quality_score "
+              "与 rubric 重算结果一致。")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/render_report.py

@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+"""render_report.py — Render a Research & Decision Pack (plan section 29) to Markdown.
+
+The final output is not a single essay but a Research & Decision Pack:
+
+    01 Executive Decision     06 Conflict Analysis         11 Claim-Evidence Trace
+    02 Education Research Frame 07 Evidence Tribunal       12 Sources
+    03 Evidence Summary       08 Applicability
+    04 Evidence Matrix        09 Teaching Intervention
+    05 Methodology Audit      10 Evaluation Plan
+
+Usage:
+    python scripts/render_report.py \
+        --frame frame.json \
+        --evidence evidence.jsonl \
+        --verdict verdict.json \
+        --intervention intervention.json \
+        --evaluation evaluation.json \
+        --methodology methodology.json \
+        --out REPORT.md
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from evidence_matrix import evidence_matrix, render_markdown
+
+
+def load_json(path: Path | None) -> dict | None:
+    if path is None or not path.exists():
+        return None
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def load_jsonl(path: Path | None) -> list[dict]:
+    if path is None or not path.exists():
+        return []
+    records = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if line:
+            records.append(json.loads(line))
+    return records
+
+
+def section(title: str, body: str) -> str:
+    return f"## {title}\n\n{body}\n"
+
+
+def render_frame(frame: dict) -> str:
+    if not frame:
+        return "_no frame provided_"
+    lines = [f"**问题**: {frame.get('question', '')}",
+             f"**决策目标**: {frame.get('decision_target', '')}"]
+    for key in ("learner", "course", "intervention", "context", "scope"):
+        if frame.get(key):
+            lines.append(f"**{key}**: " + ", ".join(
+                f"{k}={v}" for k, v in frame[key].items()))
+    if frame.get("comparison"):
+        lines.append(f"**对照**: {frame['comparison']}")
+    if frame.get("success_condition"):
+        lines.append(f"**成功条件**: {frame['success_condition']}")
+    return "\n".join(lines)
+
+
+def render_evidence_summary(evidence: list[dict]) -> str:
+    if not evidence:
+        return "_no evidence provided_"
+    by_outcome: dict[str, list[dict]] = {}
+    for ev in evidence:
+        by_outcome.setdefault(ev.get("outcome_type", "unknown"), []).append(ev)
+    lines = []
+    for outcome, evs in sorted(by_outcome.items()):
+        lines.append(f"### {outcome} ({len(evs)})")
+        for ev in evs:
+            direction = ev.get("direction", "neutral")
+            lines.append(f"- [{direction}] {ev.get('claim', '')} "
+                         f"(source={ev.get('source_id', '?')}, quality={ev.get('quality_score', '?')})")
+    return "\n".join(lines)
+
+
+def render_verdict(verdict: dict) -> str:
+    if not verdict:
+        return "_no verdict provided_"
+    action = verdict.get("recommended_action", "")
+    lines = [
+        f"**决策**: **{action.upper()}**",
+        f"**置信度**: {verdict.get('confidence', '')}",
+    ]
+    if verdict.get("what_can_be_claimed"):
+        lines.append("\n**可以主张**:\n" + "\n".join(f"- {c}" for c in verdict["what_can_be_claimed"]))
+    if verdict.get("what_cannot_be_claimed"):
+        lines.append("\n**不能主张**:\n" + "\n".join(f"- {c}" for c in verdict["what_cannot_be_claimed"]))
+    if verdict.get("missing_evidence"):
+        lines.append("\n**缺失证据**:\n" + "\n".join(f"- {m}" for m in verdict["missing_evidence"]))
+    if verdict.get("exceeds_evidence_boundary"):
+        lines.append("\n**超出证据边界**:\n" + "\n".join(f"- {e}" for e in verdict["exceeds_evidence_boundary"]))
+    if verdict.get("decision_rationale"):
+        lines.append(f"\n**理由**: {verdict['decision_rationale']}")
+    return "\n".join(lines)
+
+
+def render_intervention(intervention: dict) -> str:
+    if not intervention:
+        return "_no intervention provided_"
+    lines = [f"**决策**: {intervention.get('decision', '')}",
+             f"**目标学习者**: {intervention.get('target_learners', '')}",
+             f"**试点时长**: {intervention.get('pilot_duration', '')}"]
+    if intervention.get("ai_usage_policy"):
+        lines.append(f"\n**AI 使用规则**: {intervention['ai_usage_policy']}")
+    for phase in ("phase_1", "phase_2", "phase_3"):
+        if intervention.get(phase):
+            p = intervention[phase]
+            name = p.get("name", phase)
+            lines.append(f"\n**{name}**: {p.get('ai_usage_rule', '')}")
+            if p.get("activities"):
+                lines.append("\n".join(f"- {a}" for a in p["activities"]))
+    if intervention.get("stop_conditions"):
+        lines.append("\n**停止条件**:\n" + "\n".join(f"- {s}" for s in intervention["stop_conditions"]))
+    return "\n".join(lines)
+
+
+def render_evaluation(evaluation: dict) -> str:
+    if not evaluation:
+        return "_no evaluation plan provided_"
+    lines = [f"**研究问题**: {evaluation.get('research_question', '')}"]
+    groups = evaluation.get("groups", {})
+    if groups:
+        lines.append(f"**组**: 干预={groups.get('treatment', '')} / 对照={groups.get('comparison', '')}")
+    for key, label in (("baseline", "基线"), ("post_test", "后测"), ("retention_test", "保持测试"),
+                       ("transfer_test", "迁移测试")):
+        if evaluation.get(key):
+            lines.append(f"**{label}**: {evaluation[key]}")
+    if evaluation.get("success_threshold"):
+        lines.append(f"**成功阈值**: {evaluation['success_threshold']}")
+    if evaluation.get("stop_conditions"):
+        lines.append("\n**停止条件**:\n" + "\n".join(f"- {s}" for s in evaluation["stop_conditions"]))
+    return "\n".join(lines)
+
+
+def render_conflict_analysis(verdict: dict) -> str:
+    """Section 06 — why different studies reach different conclusions."""
+    if not verdict:
+        return "_no verdict provided_"
+    lines = []
+    if verdict.get("reason_for_disagreement"):
+        lines.append(f"**冲突来源**: {verdict['reason_for_disagreement']}")
+    if verdict.get("outcome_specific_findings"):
+        lines.append("\n**按 Outcome 的发现**:")
+        for outcome, finding in verdict["outcome_specific_findings"].items():
+            lines.append(f"- {outcome}: {finding}")
+    if verdict.get("exceeds_evidence_boundary"):
+        lines.append("\n**越过证据边界的结论**:")
+        lines.extend(f"- {e}" for e in verdict["exceeds_evidence_boundary"])
+    return "\n".join(lines) if lines else "_no conflict analysis data_"
+
+
+def render_tribunal(verdict: dict) -> str:
+    """Section 07 — Evidence Tribunal: what the evidence supports and cannot support."""
+    if not verdict:
+        return "_no verdict provided_"
+    lines = [f"**决策**: {verdict.get('recommended_action', '').upper()}",
+             f"**置信度**: {verdict.get('confidence', '')}"]
+    for key, label in (("supported_claims", "支持的结论"), ("uncertain_claims", "不确定的结论"),
+                       ("contradicted_claims", "被反驳的结论")):
+        if verdict.get(key):
+            lines.append(f"\n**{label}**:")
+            lines.extend(f"- {c}" for c in verdict[key])
+    return "\n".join(lines)
+
+
+def render_applicability(verdict: dict) -> str:
+    """Section 08 — Applicability: for whom, for which course, under what conditions."""
+    if not verdict:
+        return "_no verdict provided_"
+    app = verdict.get("applicability", {})
+    if not app:
+        return "_no applicability data_"
+    lines = []
+    for key, label in (("suitable_for", "适合"), ("not_suitable_for", "不适合"),
+                       ("required_conditions", "必要条件")):
+        value = app.get(key)
+        if isinstance(value, list):
+            lines.append(f"**{label}**: " + "; ".join(value))
+        elif value:
+            lines.append(f"**{label}**: {value}")
+    return "\n".join(lines)
+
+
+def render_trace(evidence: list[dict]) -> str:
+    """Section 11 — Claim-Evidence Trace: every conclusion traceable to a source."""
+    if not evidence:
+        return "_no evidence provided_"
+    lines = []
+    for ev in evidence:
+        lines.append(f"- `{ev.get('evidence_id', '?')}` {ev.get('claim', '')} "
+                     f"→ `{ev.get('source_id', '?')}` [{ev.get('source_location', '?')}]")
+    return "\n".join(lines)
+
+
+def render_sources(evidence: list[dict]) -> str:
+    """Section 12 — deduplicated source list with verifiable locations."""
+    seen: dict[str, dict] = {}
+    for ev in evidence:
+        sid = ev.get("source_id", "?")
+        if sid not in seen:
+            seen[sid] = ev
+    lines = []
+    for sid, ev in sorted(seen.items()):
+        title = ev.get("title", "")
+        loc = ev.get("source_location", "")
+        year = ev.get("year", "")
+        lines.append(f"- **{sid}** ({year}): {title} — {loc}")
+    return "\n".join(lines) if lines else "_no sources_"
+
+
+def render_pack(frame, evidence, methodology, verdict, intervention, evaluation) -> str:
+    matrix = evidence_matrix(evidence)
+    matrix_md = render_markdown(matrix)
+
+    parts = [
+        "# EduEvidence Research & Decision Pack\n",
+        section("01 Executive Decision", render_verdict(verdict)),
+        section("02 Education Research Frame", render_frame(frame)),
+        section("03 Evidence Summary", render_evidence_summary(evidence)),
+        section("04 Evidence Matrix", matrix_md),
+        section("05 Methodology Audit",
+                f"```json\n{json.dumps(methodology, ensure_ascii=False, indent=2)}\n```"
+                if methodology else "_no methodology audit provided_"),
+        section("06 Conflict Analysis", render_conflict_analysis(verdict)),
+        section("07 Evidence Tribunal", render_tribunal(verdict)),
+        section("08 Applicability", render_applicability(verdict)),
+        section("09 Teaching Intervention", render_intervention(intervention)),
+        section("10 Evaluation Plan", render_evaluation(evaluation)),
+        section("11 Claim-Evidence Trace", render_trace(evidence)),
+        section("12 Sources", render_sources(evidence)),
+    ]
+    return "\n".join(parts) + "\n"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Render the Research & Decision Pack to Markdown")
+    parser.add_argument("--frame")
+    parser.add_argument("--evidence", required=True)
+    parser.add_argument("--methodology")
+    parser.add_argument("--verdict")
+    parser.add_argument("--intervention")
+    parser.add_argument("--evaluation")
+    parser.add_argument("--out", required=True)
+    args = parser.parse_args()
+
+    evidence = load_jsonl(Path(args.evidence))
+    md = render_pack(
+        load_json(Path(args.frame)) if args.frame else None,
+        evidence,
+        load_json(Path(args.methodology)) if args.methodology else None,
+        load_json(Path(args.verdict)) if args.verdict else None,
+        load_json(Path(args.intervention)) if args.intervention else None,
+        load_json(Path(args.evaluation)) if args.evaluation else None,
+    )
+    Path(args.out).write_text(md, encoding="utf-8")
+    print(f"wrote {args.out}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())