eduevidence 6.0.0 → 6.3.0

package/CHANGELOG.md

@@ -0,0 +1,395 @@
+# Changelog
+
+所有显著变更均记录于此。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)；版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
+
+## [6.3.0] — 2026-09-22
+
+> Multi-domain copy packs and the two-round intake, the experimental Jev/SemDecide overlay,
+> one decision-funnel authority, and the post-audit fixes.
+> Fix: the four-state decision could not reach ADOPT through the V1 path, and all three
+> public cases read PILOT regardless of their evidence.
+
+### The ADOPT path is reachable, and provable
+- New `engine/decision_policy.py` is the single authority for the ADOPT gate (primary
+  outcome categories per domain, directness threshold, confidence band). `engine/tribunal.py`
+  and `scripts/pre_verdict_gate.py` both import it, so the V2 adjudicator and the V1 gate can
+  no longer drift apart.
+- `engine/migration.py` no longer hard-codes `directness: 1` on every migrated link. Directness
+  and `applicability.scope_match` are derived from the source record's D5 Directness, with an
+  explicit downgrade recorded when D5 is absent. A migrated pack used to be structurally
+  incapable of ADOPT; `spaced-retrieval-practice` now adjudicates to **ADOPT / High (0.893)**.
+- The Pre-Verdict Gate gained item 12, `decision_action_consistency`: a pack cannot award
+  itself ADOPT. The gate re-derives primary-outcome directness from the evidence corpus and
+  caps an unsupported adopt to pilot. The gate is now 12 items.
+- `outcome_mapping` blocks High only when a PRIMARY outcome has no evidence; an unmeasured
+  secondary or risk outcome is a scope note, since missing evidence is not a zero effect.
+- The gate resolves a pack's domain from `run_manifest.json`, then `frame.extensions.domain`,
+  then `result.meta.domain`, instead of assuming education. Policy packs no longer fail their
+  own frame check.
+
+### Public cases corrected and re-adjudicated
+- `spaced-retrieval-practice`: claims bound to evidence ids, deterministic confidence and the
+  action bound applied, narratives re-written for adoption. Verdict **ADOPT / High / 0.893**.
+- `ai-coding-assistant-evidence`: challenge stage written (`skeptic.json`, nine checks grounded
+  in the corpus), `final_verdict.json` added, policy version refreshed to `2026-08-12.v3`.
+  Verdict unchanged at **PILOT / Moderate / 0.586** — the evidence still stops at task performance.
+- `workplace-ai-assistant`: per-record quality dimensions added, the pack now declares the
+  policy domain's own outcome tokens (`policy_effectiveness` / `implementation_risk`) with the
+  teaching-neutral tokens kept in `extensions`, challenge record written, scope calibration
+  fields and claim bindings added. Verdict **PILOT / Moderate / 0.578**.
+- `schemas/v2/{study,finding,methodology-audit}.schema.json` accept the `ST-` study-id prefix so
+  curated packs migrate without being renamed.
+- All three packs pass the Pre-Verdict Gate (`passed=true`) and record a `gate_report.json`;
+  reports, five themes, Studio snapshot, Pages export and the submission package were rebuilt.
+  The submission package now ships all three examples, including the ADOPT case.
+
+### Multi-domain copy packs and the two-round intake
+- Domain copy packs land as data: `domains/{education,policy,_neutral}/copy/*.json`
+  (framing lexicon, section titles, module labels, risk constructs, terminology,
+  few-shots). `report_copy_pack`/`report_copy_policy_guard` in the report layer load
+  them, so report chrome and infographics no longer hardcode education vocabulary;
+  `domains/check_copy_packs.py` asserts the policy pack stays free of teaching words.
+- `scripts/intake/` is the one-shot two-round intake (research question → execution
+  enhancements → depth → Frame boundary confirmation) with `schemas/v2/intake.schema.json`
+  as its contract and `skill/workflows/intake.md` as the agent-facing workflow.
+  `orchestrator run` gained `--yes` / `--enhancement` / `--depth` and writes `intake.json`
+  into the run workspace; non-question preferences persist to `~/.eduevidence/prefs.json`.
+
+### Jev / SemDecide Tier-0 overlay (experimental, opt-in)
+- `integrations/jev/` (detect → approval → gateway, plus the five Tier-0 tools) and
+  `integrations/semantic_decide.py` (`semdecide is/filter/choose`) add an optional
+  acceleration layer behind `--experimental 0|1|2|3`. It never replaces the Pre-Verdict
+  Gate, the nine Skeptic checks or the Tribunal: uncertain/invalid/provider-failed
+  results fail closed and escalate to the large model.
+- The five experimental capabilities are registered in
+  `engine/capabilities.experimental_capability_registry()` and stay out of the default
+  scientific registry, so role-gate checks are unaffected.
+- `docs/j-ev-experimental.md` records the speedup口径, the A/B acceptance table and the
+  degradation ladder; `skill/workflows/experimental-jev.md` is the workflow overlay.
+
+### Decision funnel, contracts and packaging
+- The four-state landing is now derived from one authority everywhere: `engine/tribunal.py`
+  keeps no private copy of the rule, `scripts/pre_verdict_gate.py` imports it, and
+  `schemas/v2/decision-snapshot.schema.json` publishes the same four tokens.
+- `scripts/check_versioned_schemas.py` validates every vNext contract against the payload
+  its real producer emits (28 checks), including the autoevolve session report and the v3
+  benchmark run manifest.
+- `web/landing.html` states the schema count the repository actually ships, and the npm
+  tarball no longer leaks `__pycache__`/`*.pyc` (`**/` patterns in `.npmignore`).
+- The landing page claim is now machine-checked: `studio/verify-schema-count.mjs` derives
+  the expected count from `scripts/generate_metrics.py` and runs as
+  `npm run verify:schema-count` in the Research Studio CI job.
+
+### Fixes after the 2026-09-22 audit
+- `integrations/semantic_decide.py` was missing `import json` (five call sites in the
+  JSON payload and JSONL filter paths) and had no CLI entry; both are fixed, and
+  `python3 integrations/semantic_decide.py --experimental 3` now prints the detect JSON.
+- `integrations/jev/approval.is_approval_current()` referenced an undefined `path`
+  (NameError). It now takes an explicit `path` argument; the default still re-reads the
+  configured approval file, so a missing or unreadable file never counts as current.
+- Intake entry points: `scripts/intake/cli.py` gained its `__main__` guard (the documented
+  `python3 -m intake.cli --print-prompts` used to exit 0 with no output) and the package
+  now imports its siblings relatively, so `python3 -m intake.cli`, the direct script form
+  and `import scripts.intake.*` all work.
+- `scripts/test_adversarial_empirical.py` now drives the class the server actually ships
+  (`ThreadingHTTPServer`, 128-slot backlog) instead of a single-threaded `TCPServer` whose
+  five-slot accept queue made the kernel reset 24 of 30 concurrent connects. The burst now
+  asserts all 30 requests succeed, and the host / `Sec-Fetch-Site` guards are asserted with
+  raw requests (403 untrusted host, 403 cross-site, 200 same-origin).
+- `docs/metrics.json` was stale (922/102/49 against 928/103/50); the metrics gate is green
+  again, and `docs/reproducibility.md`, `CHANGELOG.md`, `docs/j-ev-experimental.md` plus the
+  two missing example `EduEvidence_Report.html` files are now in the npm `files` allowlist.
+- Hygiene: removed the retired `scripts/sync_killer_demo_report.py` (it imported the already
+  deleted synthetic generator), dropped `files` excludes that named deleted files, deleted
+  the shadowed decision path in `engine/tribunal.py`, corrected the "11-item" Pre-Verdict
+  Gate strings to 12, fixed the stale `engine/pilot.py _OUTCOME_CATEGORY` pointers in the
+  domain manifests, cleaned unused imports/variables, and restored relative report paths in
+  `web/api/projects.json` (18 host-absolute paths) with a CI guard so they cannot return.
+- New offline tests: `tests/test_semdecide_wrappers.py`, `tests/test_jev_approval_gate.py`,
+  `tests/test_intake_flow.py`; CI coverage now includes `integrations` and `scripts.intake`.
+
+## [6.2.0] — 2026-09-12
+
+> Audit remediation: the domain registry becomes the single authority, the report
+> first screen is written by the adjudicator, and the delivery pipeline proves parity.
+
+### Domain registry as the single authority
+- New `engine/taxonomy.py` reads `domains/<id>/outcome_taxonomy.json`; unknown tokens fail
+  closed instead of defaulting to a learning outcome.
+- `engine/pilot.py`, `engine/tribunal.py`, `engine/gaps.py`, `scripts/pre_verdict_gate.py`,
+  `scripts/claim_audit.py` and `scripts/build_result.py` no longer keep private copies of
+  the token list or the token-to-category map.
+- The frame stage resolves its schema from the run domain; `run` gains `--domain`; a policy
+  run validates against `domains/policy/frame.schema.json` instead of the education one.
+- `check_protocol_alignment.py` gained the taxonomy dimension: schema enums, ADOPT gate
+  categories and V2 buckets must all agree with the registry.
+
+### Report copy is written, not assembled
+- `verdict.schema.json` declares `strongest_support` / `key_uncertainty` / `main_risk` /
+  `next_action` as reader-facing prose; the judge prompt carries the writing contract.
+- The renderer no longer synthesises the first screen from claim fragments.
+- New `references/report-copy-style.md`; the language gate enforces length ceilings and
+  structural parallelism between the en and zh evidence sets.
+- Chinese example data corrected: population and claim were rotated across a three-item
+  block, and audit notes cited a non-existent evidence id.
+
+### Contract repair
+- Removed the deprecated `direction` from the result evidence contract; aligned
+  `report-spec` / `chart-spec` with their real producers; declared the effect-size family.
+- `EvidenceNode.effect_size` no longer defaults to a fabricated zero effect.
+- Added `skeptic.schema.json` / `applicability.schema.json` and wired both into the stage
+  gates; the counter-evidence gate now requires all nine checks.
+- Sciverse locators survive the Source contract; `study_audits` gained a producer; V1 to V2
+  migration keeps effect magnitudes; the confidence policy version has one authority.
+- The validator implements anyOf / oneOf / allOf, so alternative-shape contracts are real.
+
+### Gates and delivery
+- The red-team suite gained seven real assertions (it previously never failed) and it
+  immediately exposed a DID column-mapping defect, now fixed.
+- New `scripts/check_package_parity.py` proves the shipped package is byte-identical to
+  the source tree; CI runs it, and also runs the skill linter and covers `visualization/`.
+- Docs, npm ignores and a Python-version guard corrected; audit checklist in
+  `docs/audit-2026-09-12.md`.
+
+## [6.1.0] — 2026-09-12
+
+> Content and protocol depth: a citation-grade retrieval channel, runnable
+> runbooks, and a mechanical alignment gate.
+
+### Sciverse retrieval channel (key-based academic)
+- New `retrieval/sciverse.py`: `/meta-search`, `/agentic-search`, `/content` and
+  `/meta-paper-relations` with typed failure statuses, Unicode code-point
+  locators and no credential leakage. Inactive without `SCIVERSE_API_TOKEN`.
+- `SearchHit` gains optional `doc_id` / `chunk_id` / `offset` / `unique_id`;
+  `MultiSearchRouter` runs the key-based academic channel ahead of the
+  zero-config ones and reports it in `get_provider_status()`.
+- `retrieval/fetch.py::fetch_sciverse_content()` expands a chunk locator into a
+  FetchResult-shaped record, so RULE 2 (snippet ≠ evidence) is machine-enforced:
+  a chunk must be read through `/content` and pass the validation gate first.
+- Audit exports carry the locator: `chunks.jsonl` plus `doc_id`/`chunk_id`/`offset`
+  columns in `source-screening.csv`; DOI-less records are flagged
+  `needs_manual_location` instead of receiving a fabricated URL.
+- New `docs/sciverse-api.md`, `references/retrieval-compliance.md` (robots,
+  rate limits, paywalls, attribution, credentials) and Sciverse rules in
+  `references/retrieval-protocol.md`.
+
+### Runnable content depth
+- The three user workflows became full runbooks (step tables, gates, failure
+  handling, human hand-off points, resume semantics, acceptance checklists).
+- All stage briefs were rebuilt on one template (goal / prerequisites / artifacts
+  + schema / rules / quality gates / failure modes / language contract / hand-off).
+- All 12 sub-skill recipes were rebuilt on one template (When to Use / Inputs /
+  Process / Output Contract / Quality Gates / Anti-Patterns / Worked Example /
+  References) and mapped to engine capability IDs via frontmatter.
+- Role prompts declare `role_id` / `capabilities` / `output_contracts` /
+  `recommended_reasoning` instead of binding `default_cli` / `default_model`,
+  and gain independence + failure-mode sections; independence is graded
+  (`different-model-family` for the skeptic, `role-separation` for the reviewer).
+- `skill/roles/registry.yaml` capabilities now use the engine capability IDs.
+
+### Mechanical alignment
+- New `scripts/check_protocol_alignment.py` (+ `tests/test_protocol_alignment.py`,
+  wired into CI): stages ↔ briefs ↔ roles ↔ prompts ↔ capabilities ↔ sub-skills ↔
+  workflows ↔ packaging must agree, role prompts may not bind model/CLI names,
+  and packaging versions must equal `ENGINE_VERSION`.
+- New `CONTRIBUTING.md` (gates, scientific invariants, how to add a capability /
+  sub-skill / role / retrieval channel).
+- Fixed real drift: `retrieval/search.py` advertised four providers that do not
+  exist, `packaging/scp-manifest.json` was pinned at 4.0.0, and two docs carried
+  a stale test count.
+
+
+## [6.0.0] — 2026-08-31
+
+> Competition kernel convergence: Workflow → Capability → Contract.
+
+### Decision-grade control plane
+- Canonical runtime protocol now includes Applicability; report generation is a Projection outside scientific stages.
+- Added three user-facing workflow entries, durable Project/Run event storage, content-addressed immutable artifacts, and a judge-pack export.
+- Added auditable search plans, bounded provider-attempt records, counter-evidence query coverage, and screening exports.
+- Aligned submission CI with `dist/eduevidence-submission` and reduced report H1 scale across all five baked themes.
+ - Root `SKILL.md` replaced with the decision-grade English operating contract (workflow routing, scientific gates, applicability / projection semantics) plus a bilingual tooling contract appendix that keeps lint / version / metrics / release gates stable.
+ - Startup approval loop: on `run`, recommend a role to CLI to model table built only from scanned, user-usable models, ask for confirmation, and persist the hash-verified mapping to `~/.eduevidence/agent_mcp_approval.json` for reuse by later runs.
+ - Fail-closed model discipline: `safe_spawn` / `cross_model_review` refuse any unapproved CLI/model; benchmark and judge drivers no longer ship a default model (explicit `--model` or `EDUEVIDENCE_LLM_MODEL` required).
+
+## [5.2.0] — 2026-08-24
+
+> 可信度修复版：示例 provenance 纠偏 + 版本/口径单一权威（依据 docs/plans/v5.2-v6.0-iteration-plan.md）。
+
+### 版本治理
+- `engine/versions.py` 成为唯一版本权威；`engine/__init__.py` 的死值 2.0.0 改为 re-export。
+- 新增 `scripts/check_version_consistency.py` 并纳入 CI：versions.py ↔ pyproject ↔ CHANGELOG 头条目 ↔ SKILL.md 标题一致性校验。
+
+### 示例 provenance 纠偏（随本版后续提交补充）
+- 全量 DOI 审计（`scripts/audit_dois.py`，Crossref/DataCite 双注册表）：88 唯一 DOI 仅 16 真实。
+- 删除伪造旗舰包 `ai-coding-assistant-50`；新建 `ai-coding-assistant-evidence`：
+  8 个注册表核验来源、12 条证据、引擎确定性置信度（Moderate/0.586）、五主题烘焙 ALL CLEAN。
+- esl/math 示例：删除伪造的 agent_mcp_enhanced 运行记录，如实标注 `data_origin=synthetic`，
+  并首次通过 schema 契约（修复 CLM-### claim_id、非法 venue/statement 等历史违规）。
+- 报告头新增 data_origin 徽章；synthetic/hybrid 高亮警示。
+- 口径统一：`docs/metrics.json` 单一权威（752→762 测试函数、37 schema、15 参考、30 金标），
+  CI 校验 README/SKILL/install-guide 数字；README 语言命名归位（README.zh-CN.md）；
+  landing 页清除虚构统计（"50 篇顶刊"/+0.38g）与主办方泄漏词；Skill #650 失效外链移除。
+- 可信度功能化：`engine/citation_check.py` + CLI（--write-back 回写 sources.jsonl）、
+  schema 增 doi_verified/retracted、来源表 DOI ✓ / RETRACTED 徽章；
+  `scripts/retraction_watch.py` 定期撤稿监控。
+- 工程地基：红队压测纳入默认收集并修复至绿（StudioHandler 适配+临时端口）、
+  ruff(E9/F) 守门、pytest-cov 覆盖率报告、移除 CI 静默重试、wheel 隔离安装冒烟、
+  stdlib logging 贯穿 fetch/search/orchestrator（EDUEVIDENCE_LOG_LEVEL 开关）、
+  install.sh 供应链与副作用披露、web archive 快照删除+单一源声明、
+  quickstart 30 分钟引导器、Deep Research 对比页。
+
+
+## [5.1.1] — 2026-08-23
+
+> 排版修复 + 五主题布局约束门（含手机端）。
+
+### Judge（presentation）主题排版问题排查与修复
+- 根因一（移动端/平板横向裁切）：`:root[data-theme="X"]`（特异性 0,2,0）压过基座
+  `@media (max-width:980px)`（0,1,0）——presentation 的 `full-report-layout` 在 390px 仍为
+  `230px 104px` 两列，内容列被挤到 104px；datalab/dark/presentation 的 `outcome-groups`
+  `repeat(auto-fit,minmax(240px,1fr))` 内在尺寸爆炸，768px 平板第二列结果消失在视口外
+  （shell scrollWidth 1025 > 768）。
+- 修复范式：基座断点改 `minmax(0,1fr)` + 网格 item `min-width:0` 安全网；全部 5 主题
+  `auto-fit` 轨道改 `minmax(min(Npx,100%),1fr)`；三主题 `report-page-brief`/`full-report-layout`
+  自带 `@media ≤980` 覆写（同主题文件内，等特异性后声明生效）；`scope-grid`/`method-audit-grid`
+  同样处理。
+- 结果：18 份报告（3 示例 × 5 主题 + 3 主报告 + 13 篇示例）× 390/768/1280 × brief/full
+  浏览器实测 114 项全部无溢出、无裁切。
+
+### 展开动画「只有点击才触发」体验修复
+- 根因：首屏卡片在页面加载瞬间即播完动画（用户未看到），滚动中又常被错过，感知为
+  "只有点击才动"。`motion.js` 新增入场错峰：页面加载 1.5s 内命中的卡片按
+  `140ms + (index%6)*130ms` 逐个播放入场（draw-in 可见）；滚动进入与点击重播立即执行；
+  `prefers-reduced-motion`/无 JS 仍然静态可见。
+
+### 五主题排版约束机制（skill + 脚本 + 测试）
+- 新建 `scripts/lint_report_layout.py`：静态不变量审计（裸 1fr 轨道、无移动端覆写的双列
+  grid、固定 px 最小值 auto-fit 均为违规）+ 可选浏览器级门（调 `check_mobile_layout.js`）。
+- 新建 `visualization/eduevidence-report/scripts/check_mobile_layout.js`：零依赖 Node CDP
+  实测（390/768/1280 × brief/full）：页面无横向溢出、可见 shell 无裁切、逃逸元素排除
+  滚动容器/SVG 内部、画廊 reveal 契约（滚入全部 is-live）。
+- 新建 `tests/test_report_layout_mobile.py`：静态门必跑；浏览器级门在有 Chrome+Node 时跑，
+  否则 skip；reveal 契约静态断言。
+- 文档：新增 `visualization/eduevidence-report/references/layout-constraints.md`（守则 + 教训 +
+  验收清单）；`component-catalog.md` §10/§11 与 `report-generation` sub-skill §2.4 引用守则。
+
+## [5.1.0] — 2026-08-22
+
+> Present 层大改造：**AI 自由组合 Lieflat 图表 + 5 套主题文案排版优化（含展开动画）**。
+
+### 数据驱动 Lieflat 画廊（AI 自由组合）
+- 新增 `visualization/eduevidence-report/scripts/charts_data.py`：16 个提取器（meta.forest / evidence.ranked_effects / year_x_dimension / grouped_distribution / multidim_top / study_type & wwc_composition / outcomes.direction_counts & paired_counts & bipolar_axes / intervention.phase_weeks & activity_weights & phase_groups / decision.confidence_score / methodology.flag_rates / year_x_outcome_counts），数据不足返回 None + reason（镜像 Meaningful Visualization Gate），不编造单位。
+- 重构 `lieflat_engine.py`：REGISTRY（17 个 type ↔ 目录编号 ↔ 提取器 ↔ 渲染器）+ `render_figure` 调度器，未知 type 显式报错；**删除全部硬编码演示数据与 SVG 内嵌 `<style>`**，改为 `lf-pop/lf-fade/lf-draw` 类 + `--motion-delay`（点阵 12ms / 条形 100ms）；SVG 最小字号 6.5px、数值 800、面积 sqrt。
+- `build_figures.py`：学术图保持不变；Lieflat 部分只渲染 `resolve_visual_layout` 校验通过的条目，键用条目 chart_id。
+- `build_report.py`：新增 `resolve_visual_layout`（新契约 `{chart_id, type, catalog_ref, title_zh/en, subtitle_zh/en, caption_zh/en, source, params}`；兼容旧 title/subtitle 双语共用并告警；未注册/缺双语/参数非法 → 丢弃 + 原因入 report_spec；全无效 → 确定性安全组合 forest + dot_cascade + bubble_almanac + tick_rows）；完整性门新增 `lieflat_data_bound`（渲染值逐一比对提取器 bundle）；`render_lieflat_gallery_brief` 重写（四件套卡片 + `data-lieflat`/`data-visual` + 图注 + 抑制清单）；`report_spec.json` 增加 `lieflat_gallery`。
+- 新增 `schemas/visual-layout.schema.json`（目录原为空，正放新契约）。
+
+### 展开动画对齐 skill 正本（图表 SVG 为主）
+- `motion/motion.css`：新增 `data-lieflat` 区块——`.js-lf` 门控的 `lf-pop`（scale 0→1，cubic-bezier(.2,.7,.3,1.3)，500ms）/ `lf-fade`（900ms ease）/ `lf-draw`（dasharray 1，1s cubic-bezier(.4,0,.2,1)），`--motion-delay` stagger，reduced-motion 与 print 全关，无 JS 静态可见。
+- `motion/motion.js`：`[data-lieflat]` 实现 mono-tokens `obsReveal` 语义——IntersectionObserver（threshold .3）滚入播放一次；点击重播（先清该 id 已登记 timer，防叠加）；`CSS.escape` 安全。
+- `references/motion-system.md`：`chart-reveal` 写为固定模板角色，五主题不得另造动画逻辑。
+
+### 5 套主题文案排版优化（设计个性全部保留）
+- 文案：表头 meta 行规范为「模式：… · 生成时间：… · 证据 N 条 · 来源 N 个」（英文对应）；润色 `full_report_intro`、12 条 section leads、brief 各块 lead、`benchmark_note`；图表文案规范（标题写结论、副标题说清图例单位、来源行全大写）。
+- 排版：中文优先字体栈（PingFang SC / Noto Sans CJK，academic 保留 Songti 衬线）；中文正文不加 letter-spacing；数字 `tabular-nums`；claude 标题 500 字重与 measure 收窄；academic 打印 8.5pt；datalab/datalab-dark 4 列 brief 网格 + 章头双栏 + 控件尺寸统一（暗版对比度 ≥4.5:1 复核）；presentation 裁决字号阶梯 + insight 内边距 + 金橙对比度复核。
+
+### 夹具、测试与交付
+- 修复 `examples/ai-coding-assistant` 夹具（决策叙述中的 E-xxx 引用 / null 残留 / overall_risk schema 键 → 语言门禁 0 问题）；三个示例项目 `visual_layout` 升级为新双语契约（50 篇示例展示 L20/G15/L14/F11/L15/L16 六种轮廓组合）。
+- 新增 `tests/test_lieflat_composition.py`（提取器溯源、注册表拒绝、抑制、无演示值、schema、数据溯源门）；`test_build_report_html.py` 增补画廊卡片 / motion 定义唯一 / reveal 契约 / footer / meta 行；`test_build_figures.py` 按 layout 渲染。
+- 全量 pytest 与 `skill_lint.py` 全绿；`rebake_all_5themes.py` 重烘焙 3 示例 × 5 主题（15 份，integrity 全 PASS）。
+
+### 文档
+- `skill/sub-skills/report-generation/SKILL.md` §2 重写为六步组合工作流；新增 `references/lieflat-composition.md`（注册表 + 契约 + 推荐组合 + 抑制规则）；更新 `component-catalog.md` / `full-report-outline.md` / 根 `SKILL.md` Present 行 / `docs/architecture.md` Present 管线。
+
+## [5.0.0] — 2026-08-21
+
+> v5 大迭代旗舰版（`ENGINE_VERSION = "5.0.0"`）。主题：**「SSOT 证据图谱 × 杀手级实证闭环 × Claude 本地控制台」**。
+
+### 统一 SSOT 证据图谱引擎 (`engine/evidence_graph.py`)
+- **7 大统一实体节点模型**：`PaperNode` (文献)、`EvidenceNode` (量化效应量 Hedges' g、WWC 5.0 评级)、`OutcomeNode` (5维社科分类)、`ClaimNode` (科学主张)、`RiskNode` (方法学陷阱)、`GapNode` (学术空白)、`DecisionNode` (四态裁决快照)
+- **消除数据孤岛**：所有下游消费端（Tribunal 仲裁、HTML 报告、Web 控制台、GapLens）统一读取此 SSOT 图模型
+- **ECharts 力导向图导出**：支持可视化拓扑导出与交互式路径追踪
+
+### 50 篇真实学术文献杀手级 Demo (`examples/ai-coding-assistant-50/`)
+- **核心命题**：“高校大一程序设计课程引入 AI 编程助手是否真正提升计算思维与独立编程能力？”
+- **揭示社科核心悖论**：任务完成速度提升 $+0.64g$ vs 撤除 AI 后的独立闭卷期末考迁移赤字 $-0.28g$
+- **WWC 5.0 脚手架依赖陷阱检测**：自动触发认知陷阱告警，裁决为 `PILOT` (限制性试点)
+- **12周准实验因果闭环**：自动生成 12 周 DID 准实验设计，支持课堂 CSV 数据回注因果回归
+
+### Claude 风格本地控制台 (`scripts/dashboard_server.py`)
+- **浅色极简美学**：暖白底色 `#FAF9F6`、1px hairline 边框、`Instrument Serif` 衬线字体、呼吸感负空间
+- **实时事件流 (SSE)**：基于 `engine/events.py` 的 EventBus 内存总线实时推送 9 阶段执行日志
+- **Token 消耗与多模型成本矩阵**：实时比对 DeepSeek-V3/R1、Minimax 2.7、Claude 3.5 Sonnet 与 GPT-4o 成本
+- **混合多渠道检索诊断台**：支持 4 大免配置学术渠道与 AIHot 动态趋势渠道实时测试
+
+### 出版级 HTML 报告与图表重构
+- **出版级效应量森林图 (Forest Plot SVG)**：直观展现速度提升 vs 迁移赤字的尖锐分歧
+- **100% 数据一致性门控**：所有动态聚合与图表通过严苛校验，生成单文件 618KB 离线可用报告
+- **三层白话信息架构**：一页白话结论 (30秒) ➔ 可视化概要 (3分钟) ➔ 完整证据档案 (可折叠)
+
+### 外部 Skill 深度集成与安全补强
+- **`skills/aihot-trend-analysis/`**：集成 AIHot 实时 AI/EdTech 技术趋势雷达
+- **`skills/gap-analysis/`**：集成 BioGapLens 空白与矛盾透镜
+- **`skills/ethics-review/`**：引入人类受试者与 IRB 研究伦理审查
+- **`retrieval/corpus_store.py`**：内置 5 领域离线语料库，保障 100% 离线演示容灾
+- **测试矩阵**：补齐 `tests/test_search.py`，全量 703 个 pytest 用例 100% 零错误通过
+
+## [4.0.0] — 2026-08-14
+
+> v4 正式版（`ENGINE_VERSION = "4.0.0"`）。主题：**「科艺融合 × 通用智能」——从教育证据引擎到社科证据决策平台**。
+
+### EvidenceCore 领域泛化
+- `domains/` 领域注册表：`eduevidence domain list|select|check`；education 为注册域（零新增逻辑路径，v3 行为不变）；policy 为 v4 首个自带契约域（decision_object/intervention/population/stakeholders 政策框架、5 类政策结果、12 项政策证据质量清单、5 篇政策方法学参考）
+- `engine/evidencecore.py`：`DECISION_STATES`/`PROTOCOL_STEPS` 领域无关常量、`load_domain`（JSON Pointer 契约引用校验）、`validate_frame`（按域校验）
+
+### 证据综合层（Evidence Synthesis）
+- `engine/meta_analysis.py`：效应量提取、固定效应（inverse-variance）与随机效应（DerSimonian-Laird，Q/τ²/I²）双口径合并、森林图数据
+- `engine/bias.py`：Egger 回归（stdlib 手写 t 分布 p 值）、Rosenthal fail-safe N
+- `engine/robustness.py`：leave-one-study-out → robust/fragile 标签
+
+### Living Evidence（活证据）
+- `eduevidence living subscribe|refresh|status`：决策快照订阅 → 新证据（人工注入或 retriever 适配器）内容 hash 幂等入图 → 漂移报告（confirmed/changed/needs_review），绝不自动改判
+
+### 内置证据库 + 离线初步裁决
+- `benchmarks/evidence-library.json`（230 条：金标 209 + 示例 21）：`preliminary_verdict` 保守裁决（从不 adopt），无检索能力时可用
+
+### LLM Judge 评估
+- `eduevidence benchmark-judge run|report`：5 维 rubric（citation/outcome/scope/contradiction/decision）评审实证响应，与 heuristic 并列对照，披露同族模型独立性限制
+
+### CI 与工程
+- GitHub Actions 三作业并行：测试矩阵（3.10/3.12 + 重试）、schema-smoke（示例全量过契约）、upload 构建（SKILL.md 一致性 + 零泄漏 canary）
+- 测试 612 → 681（69 个 v4 用例），education 域零回归
+## [3.0.0] — 2026-08-14
+
+> v3 正式版（`engine/versions.py` → `ENGINE_VERSION = "3.0.0"`）。v3 三大方向：**可信度收口**（每个结论收紧到可追溯、可反驳、可审计）、**实证 Benchmark**（Layer B 真实模型运行）、**闭环能力**（PILOT → 真实数据 → 再裁决）。
+
+### 可信度收口（Credibility Tightening）
+
+- **Evidence Matrix 三列化（P1-1）**：支持 / 反驳 / 中性证据分列呈现，混合列不再被静默统计（`77db8b5`、`303054e`）。
+- **Pre-Verdict Gate 严格化（OPEN-1）**：`uncertain_claims` 必须绑定证据（`evidence_ids`），无绑定即校验失败（`77db8b5`）。
+- **outcome_mapping 报告（OPEN-2）**：决策输出新增 outcome 映射报告，学习效果与任务表现显式区分（`77db8b5`）。
+- **角色 prompt schema 契约（OPEN-4）**：八角色 prompt 内嵌 schema 契约与枚举值表，输出即契约（`352015a`）。
+- **agent MCP 三态（OPEN-5）**：MCP 可用性三态检测，`install` 自动写入 env（`a735cf6`）。
+- **检索层回归测试补强（P0-1）**：检索 / 校验层回归测试补强，并修复 dedupe stale-index 合并（`de741d0`）。
+- **Source fallback 诚实化（P1-2）**：真实 DOI 解析判 tier1，否则 tier5 + incomplete，杜绝编造 canonical URL（`985239e`）。
+- **fetch 基准站点标题无害化**：中文站点标题英文化 + 分类泛化（`d7f068b`）。
+
+### 实证 Benchmark（Empirical Benchmark，Layer B）
+
+- **benchmark_v3 harness**：真实模型调用 + run manifest 契约（`schemas/v3/run-manifest.schema.json`），SIMULATED 与 EMPIRICAL 严格区分（`26a1d1b`）。
+- **gold-based evaluator**：对照 `benchmarks/annotations/gold-*.json` 计算六项指标，每条标注 `method: heuristic`，均值按 95% CI 报告（`26a1d1b`）。
+- **30 金标补齐**：Q11–Q30 金标标注 + 一致性校验测试（`fced61c`）。
+- **CliDriver(omp)**：`omp` CLI 执行后端（`--driver cli`），实证运行落地 `benchmarks/empirical/run-empirical-01`（`503abca`）。
+
+### 闭环能力（Phase 2）
+
+- **Decision-to-Outcome Loop（pilot）**：PILOT 试点结果回填 → redecide → 再裁决（`715fae7`）。
+- **Multi-project library synthesis**：跨项目证据库综合 + `REPORT_CONTRACT_VERSION 3.0` + pilots 目录（`eb059fb`）。
+- **CLI 新子命令**：`pilot` / `synthesize` / `benchmark`（`400b346`）。
+
+### 交付与文档
+
+- **HTML 报告可访问性与诚实性小修**（6.1–6.5，保持视觉风格）（`d54d23a`）。
+- **文档统一**：Canonical Protocol 9 步（6+3）、Schema 13 个、方法论文档 11 篇、V2 contracts 17 个等数字口径修正（`5b0e886`、`907cd11`）。
+- **版本基线**：`3.0.0`（`715fae7` 起 3.0.0-dev，`ee7ae79` 正式化）。

package/CONTRIBUTING.md

@@ -0,0 +1,105 @@
+# Contributing to EduEvidence
+
+EduEvidence 是一个**证据驱动的决策引擎**：它的产出要能被第三方复核。因此本仓库的贡献规则有一条主线——**契约先行**。每个科学概念都在多处声明（协议、能力、角色、简报、子技能、分包），任何一处漂移都会让结论失去可追溯性。
+
+## 1. 环境准备
+
+```bash
+git clone https://github.com/37chengshan/eduevidence.git
+cd eduevidence
+bash install.sh            # venv + 依赖 + 自检 + 测试
+# 或最小安装
+python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
+```
+
+要求 Python ≥ 3.10；内核（`engine/`、`retrieval/`）零第三方依赖，测试需要 `pytest`。Node 只在构建 Research Studio 前端时需要。
+
+## 2. 提交前必须跑的门
+
+```bash
+python scripts/check_version_consistency.py   # 版本口径单一权威
+python scripts/generate_metrics.py --check    # 文档数字与仓库一致
+python scripts/skill_lint.py                  # Skill 结构完整
+python scripts/check_protocol_alignment.py    # 协议五方对齐
+ruff check --select E9,F63,F7,F82 .
+python -m pytest -q
+```
+
+CI（`.github/workflows/ci.yml`）会重复执行上述门，外加 wheel 隔离安装冒烟、schema-smoke 与提交包构建。本地全绿是提交的最低门槛。
+
+## 3. 科学不变量（不可协商）
+
+- **任务表现 ≠ 学习效果**：任何把任务完成度当作学习收益的写法都会被门拒绝。
+- **snippet ≠ 证据**：检索片段与摘要只是发现线索，只有抓取并通过校验门的正文可以抽取。
+- **缺证据 ≠ 零效应**：证据不足时输出 `INSUFFICIENT EVIDENCE`，不得换算成"无效"。
+- **无证据奠基不得设计新研究**：研究设计必须引用显式的 KnowledgeGap ID。
+- **证据 append-only**：修订产生新 revision 与新 decision snapshot，绝不覆盖历史。
+- **写入者唯一**：图修订只能由规范写入者提交，worker 不得直接写图。
+
+详见 `references/scientific-invariants.md`，由 `scripts/check_autoresearch_invariants.py` 强制。
+
+## 4. 如何新增一项能力（capability）
+
+能力是"协议能做什么"的最小单元，它与模型、CLI、Agent 数量无关。新增一项能力需要同时落地四处，缺一不可：
+
+1. `engine/capabilities.py`：用 `_register(...)` 注册 `capability_id`、输入/输出契约、是否可确定性本地执行，以及（如有）科学门。
+2. `skill/roles/registry.yaml`：把能力分配给承担它的角色（`capabilities:` 列表）。
+3. `skill/agents/<role>.md`：在 frontmatter 的 `capabilities` 中同步，并在正文写清产出契约。
+4. `skill/sub-skills/<name>/SKILL.md`：frontmatter 写 `capability:`，正文按 recipe 模板给出 Inputs / Process / Output Contract / Quality Gates / Anti-Patterns。
+
+跑 `python scripts/check_protocol_alignment.py` 验证五方一致。
+
+## 5. 如何新增一个子技能（sub-skill）
+
+子技能是内部能力配方，不是新的用户入口。模板：
+
+```markdown
+---
+name: <dir-name>            # 必须与目录名一致
+description: "..."
+capability: <capability_id>  # 映射到 engine/capabilities.py
+---
+
+# <Title>
+## When to Use
+## Inputs
+## Process
+## Output Contract
+## Quality Gates
+## Anti-Patterns
+## Worked Example
+## References
+```
+
+## 6. 如何新增一个角色（role）
+
+角色是责任单元，不是运行时 Agent。新增角色需要：`skill/roles/registry.yaml`（stage / capability / critical_path）、`skill/agents/<role>.md`（frontmatter 用 `role_id` / `capabilities` / `output_contracts` / `recommended_reasoning`，**不得写死模型或 CLI 名**）、`integrations/agent_mcp.py` 的 `ROLE_REQUIREMENTS`（只写能力等级）。
+
+需要独立性的角色显式声明：`independence_required: different-model-family`（如 skeptic）或 `role-separation`（如 method-reviewer）。
+
+## 7. 如何新增一个检索通道
+
+1. 在 `retrieval/` 下实现 provider（stdlib-only、超时、定型错误，不抛异常到管道）。
+2. 零配置通道进 `zero_config_academic` / `zero_config_web`；需 key 的学术通道进 `academic_key_providers`，并实现 `is_available()`。
+3. 命中结果统一为 `SearchHit`；沿用 `doc_id` / `chunk_id` / `offset` 表达定位（如适用）。
+4. 在 `docs/` 记录端点契约，在 `references/retrieval-compliance.md` 补齐配额与限制，在 `tests/` 用 mock HTTP 覆盖成功与各类失败。
+
+## 8. 证据纪律与文档
+
+- 示例与演示必须如实标注 `data_origin`（manual_curated / synthetic / hybrid）；不得把手工整理文献说成模型运行结果。
+- 数字口径以 `docs/metrics.json` 为准，文档中不硬编码会漂移的计数。
+- 内部文档用中文，`SKILL.md` 保持英文；协议语义（九步、四态、Projection 边界）不因文档改写而改变。
+
+## 9. PR 检查表
+
+- [ ] 五个门本地全绿（版本 / 指标 / skill_lint / 协议对齐 / 测试）。
+- [ ] 新增或改动的契约在五方（协议 / 能力 / 角色 / 简报 / 子技能）一致。
+- [ ] 未引入硬编码的模型名、CLI 名或密钥。
+- [ ] 科学不变量未被弱化；如有例外，在 PR 说明中显式论证。
+- [ ] 文档、CHANGELOG、`docs/plans/STATUS.md` 同步更新。
+- [ ] 未提交本地运行状态、私有数据或凭据。
+
+## 10. 行为准则
+
+讨论以证据为准：提出结论时给出可核验来源；被反驳时更新结论而不是更新措辞。对他人贡献的评审聚焦"证据是否支撑结论"，不针对作者。
+