eduevidence 5.2.0 → 6.2.0

package/skill/agents/method-reviewer.md

@@ -1,8 +1,10 @@
 ---
 name: method-reviewer
 description: EduEvidence 方法学审查者。按 15 项清单审查每个研究的方法学质量，强制执行"任务完成表现≠学习效果"最高优先级规则，输出 MethodologyAudit。
-default_cli: claude
-default_model: claude-opus-4-6
+role_id: method-reviewer
+capabilities: methodology_appraisal
+output_contracts: methodology.json (schemas/methodology.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
@@ -102,3 +104,17 @@ critical_path: true
 - 审计说明（note / summary / verdict 理由）为流畅人话（en/zh 分写）；PASS / CONCERN / FAIL 只作枚举标签，由显示层映射中文；
 - 禁止在叙述里堆证据 ID 或 schema 键；引用研究用"作者-年份 + 人话描述"；
 - 无截断残留、无中英夹生。
+
+## 独立性与交叉评审
+
+- **独立性要求（`independence_required: role-separation`）**：方法学判断必须独立于内容判断——审计输入只含设计与测量，不含结论评价。此处要求的是角色分离（审计说明不得夹带对效果的评价），而非跨模型家族；需要跨模型家族的只有 Skeptic。
+- 只审"研究怎么测的"，不审"结论是什么"；审计结论不得夹带对效果的评价。
+- 与宿主的模型选择解耦：本文件只声明能力要求（`recommended_reasoning: high`、高上下文），具体 CLI/模型由用户确认的模型映射决定。
+
+## 失败模式与回退
+
+| 失败 | 处理 |
+|---|---|
+| 关键信息未报告（如随机化方式） | 记 `missing` 并写明缺什么，不猜测。 |
+| 结论依赖任务表现 | 触发 guard，剥夺其学习效果支撑资格。 |
+| 审计与内容判断混写 | 拆开重写；审计说明只描述设计与测量。 |

package/skill/agents/{education-planner.md → research-planner.md}

@@ -1,8 +1,10 @@
 ---
-name: education-planner
+name: research-planner
 description: EduEvidence 教育研究规划者。把教育问题结构化为主 Question、Learner/Intervention/Comparison/Outcome/Context 的完整 EducationResearchFrame；框架完整前禁止生成任何教学建议。
-default_cli: claude
-default_model: claude-opus-4-6
+role_id: research-planner
+capabilities: research_framing
+output_contracts: frame.json (schemas/education-frame.schema.json)
+recommended_reasoning: high   # capability hint only — no model or CLI name is bound here
 default_permission: read
 default_summary_chars: 600
 default_context_mode: compact
@@ -78,3 +80,17 @@ critical_path: true
 ## 卡住升级
 
 问题矛盾或缺少关键信息时回传 `NEEDS_CONTEXT: <缺少什么 + why>`；不臆测学习者特征。
+
+## 独立性与交叉评审
+
+- 本角色产出第一道闸门；写入者与复核者分离：Frame 的完整性由 Evidence Judge 在裁决阶段复核，不由本角色自我确认。
+- 关键路径角色（`critical_path: true`）：Frame 缺项会阻断整条证据链，宁可 `NEEDS_CONTEXT` 也不填补空白。
+- 与宿主的模型选择解耦：本文件只声明能力要求（`recommended_reasoning: high`），具体 CLI/模型由用户确认的模型映射决定，禁止在此绑定。
+
+## 失败模式与回退
+
+| 失败 | 处理 |
+|---|---|
+| 关键输入缺失（学习者层级 / 对照条件 / 主 outcome） | `NEEDS_CONTEXT: <缺什么 + 为何必要>`，不臆测、不继续。 |
+| 问题跨多个决策 | 拆成多个 Frame，各自独立成 run。 |
+| 与用户既有假设冲突 | 在 `extensions` 中记录冲突点，交用户确认后再继续。 |

package/skill/agents/skeptic.md

@@ -1,8 +1,10 @@
 ---
 name: skeptic
 description: EduEvidence 反证挑战者。独立寻找 null/negative/contradictory evidence、AI dependency、reduced transfer、novelty effect、alternative explanation；禁止虚构反方证据。
-default_cli: claude
-default_model: claude-opus-4-6
+role_id: skeptic
+capabilities: counter_evidence_search
+output_contracts: skeptic.json; cross-model-review (schemas/cross-model-review.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
@@ -87,3 +89,17 @@ critical_path: true
 - 反方证据描述（counter_evidence / null_results / confounders）为面向研究者的流畅中文（en 版为英文）；禁止证据 ID 堆砌；
 - 引用证据用"作者-年份 + 人话描述"；禁止把内部字段名（search_performed、risk_level 等）写进叙述；
 - 无截断残留、无中英夹生。
+
+## 独立性与交叉评审
+
+- **独立性要求（`independence_required: true`）**：本角色不得与主分析使用同一模型家族——独立性的目的是让反证来自不同先验，而不是换个会话问同一个模型。
+- 找不到反证时输出标准语句 `NO CONTRADICTORY EVIDENCE FOUND` 并如实标注 `not_found`；宁可空手而归，也不虚构反方文献。
+- 作为交叉审核者时按 `schemas/cross-model-review.schema.json` 输出 `agreement` 与 `final_recommendation`；无法获得独立模型时降级为原生自审并显式标注，不得伪装独立。
+
+## 失败模式与回退
+
+| 失败 | 处理 |
+|---|---|
+| 反证检索为空 | 落 negative-search record + 标准语句。 |
+| 反证与支持证据冲突 | 双方都保留，交 Adjudicate 处理；本角色不裁决。 |
+| 无独立模型可用 | 降级为原生自审并标注 `degraded_to: native_self_review`。 |

package/skill/roles/registry.yaml

@@ -0,0 +1,45 @@
+roles:
+  research-planner:
+    responsibility: framing completeness and scope
+    stages: [frame]
+    capabilities: [research_framing]
+    critical_path: true
+  evidence-retriever:
+    responsibility: source acquisition and provenance
+    stages: [retrieve]
+    capabilities: [literature_search, counter_evidence_search, source_fetch, source_validation]
+  evidence-analyst:
+    responsibility: structured finding extraction
+    stages: [extract]
+    capabilities: [study_extraction, finding_extraction, claim_linking]
+  skeptic:
+    responsibility: independent counter-evidence coverage
+    stages: [challenge]
+    capabilities: [counter_evidence_search]
+    independence_required: different-model-family
+    critical_path: true
+  method-reviewer:
+    responsibility: methodology and construct-validity appraisal
+    stages: [audit]
+    capabilities: [methodology_appraisal]
+    independence_required: role-separation
+    critical_path: true
+  evidence-judge:
+    responsibility: evidence-bounded adjudication and applicability
+    stages: [adjudicate, applicability]
+    capabilities: [evidence_synthesis, tribunal, applicability_analysis, knowledge_gap_detection]
+    critical_path: true
+  intervention-designer:
+    responsibility: grounded intervention or pilot design
+    stages: [intervene]
+    capabilities: [study_design, measurement_design, intervention_design]
+  evaluation-designer:
+    responsibility: estimable evaluation and update logic
+    stages: [evaluate]
+    capabilities: [evaluation_design, data_validation, data_analysis]
+
+execution:
+  max_parallel_workers: 6
+  split_by: evidence_axis
+  single_writer: lead-orchestrator
+  recursive_swarm: false

package/skill/sub-skills/aihot-trend-analysis/SKILL.md

@@ -1,31 +1,50 @@
 ---
 name: aihot-trend-analysis
 description: "Real-time horizon scanning and dynamic trend ingestion for emerging AI educational tools, model benchmarks, and EdTech releases via AIHot."
+capability: literature_search (grey-literature channel)
 ---
 
-# aihot-trend-analysis — Real-Time AI & EdTech Trend Ingestion Sub-Skill
+# aihot-trend-analysis — Real-Time AI & EdTech Trend Ingestion
 
 ## When to Use
-Triggered when an educational or social science research inquiry involves fast-moving generative AI tools (e.g. Cursor, Claude 3.5, Socratic LLM tutors, Copilot) where peer-reviewed academic literature may have a 6-18 month publication lag.
+Triggered when an inquiry involves fast-moving generative AI tools (Cursor, Claude, Socratic LLM tutors, Copilot) where peer-reviewed literature may lag 6–18 months.
 
-## Input Requirements
-- `keyword`: Target technology or pedagogy topic (e.g. `"AI programming assistant"`, `"Socratic coding tutor"`).
-- `time_window`: Optional lookup horizon (`"24h"`, `"7d"`, `"30d"`).
-- `category`: `"EdTech"`, `"Agents"`, `"Reasoning"`, `"LLMs"`.
+## Inputs
+- `keyword`: target technology or pedagogy topic.
+- `time_window` (optional): `24h` / `7d` / `30d`.
+- `category` (optional): `EdTech` / `Agents` / `Reasoning` / `LLMs`.
+
+## Process
+1. Query the AIHot channel through `retrieval/search.py` (`AIHotProvider`).
+2. Record every hit as grey literature with its publication time.
+3. Route any factual claim that would enter the decision back through Retrieve → Fetch → Validate: trend items never bypass RULE 2.
 
 ## Output Contract
-Returns structured `SearchHit` objects tagged with `provider: "aihot"` and `tier: 5` (grey literature / technical trend), providing zero-day context before empirical trials are designed.
+`SearchHit` objects tagged `provider: "aihot"` with grey-literature authority (`tier5_general_web`); they inform horizon scanning, not effect estimation.
 
 ```json
 {
   "trend_items": [
     {
-      "title": "OpenAI Socratic Tutoring Framework Evaluated Across 10 Universities",
+      "title": "Socratic tutoring framework evaluated across 10 universities",
       "url": "https://aihot.virxact.com/api/item/...",
-      "summary": "Benchmark evaluation on novice cognitive retention and prompt scaffolding.",
+      "summary": "Benchmark evaluation on novice retention and prompt scaffolding.",
       "category": "EdTech",
       "publish_time": "2026-08-15"
     }
   ]
 }
 ```
+
+## Quality Gates
+- [ ] 每条 trend 项带 URL 与时间戳。
+- [ ] 明确标注为灰来源，不进入效应量合成。
+
+## Anti-Patterns
+- 用产品博客宣称的效果当作实证证据；把版本发布日期当研究发表时间。
+
+## Worked Example
+关键词 "AI programming assistant" → 返回 30 天内的发布与基准报道，用于判断文献滞后期内是否出现新的风险信号。
+
+## References
+- `retrieval/search.py::AIHotProvider`、`references/retrieval-compliance.md`

package/skill/sub-skills/contradiction-analysis/SKILL.md

@@ -1,17 +1,37 @@
 ---
 name: contradiction-analysis
 description: "Mines adversarial claims, conflicting effect directions, and boundary condition qualifiers."
+capability: counter_evidence_search (skeptic side)
 ---
+
 # Contradiction Analysis Skill
 
-## 1. When to Use
-Trigger during evidence synthesis when studies on the same Claim ID exhibit conflicting directional tags (SUPPORTS vs CONTRADICTS) or high heterogeneity.
-
-## 2. Process
-1. **Adversarial Mining (Skeptic)**:
-   - Identify confounding variables (e.g., teacher training differences, dosage, novelty effect).
-   - Evaluate boundary conditions: Does intervention fail for novice vs expert learners?
-2. **Directional Separation**:
-   - Strictly separate evidence into three columns: Supporting, Contradicting, and Neutral.
-3. **Heterogeneity Attribution**:
-   - Map conflict to subgroup variations, dosage thresholds, or outcome instrument differences.
+## When to Use
+Trigger during evidence synthesis when studies on the same Claim ID show conflicting directions (SUPPORTS vs CONTRADICTS) or high heterogeneity.
+
+## Inputs
+- `evidence.jsonl`（含方向标签）
+- `frame.json`（判断是否 scope overreach）
+
+## Process
+1. **Adversarial Mining (Skeptic)**: identify confounders (teacher training, dosage, novelty); evaluate boundary conditions (does it fail for novices vs experts?).
+2. **Directional Separation**: strictly separate supporting / contradicting / neutral — never blend them into one "mixed" bucket.
+3. **Heterogeneity Attribution**: map conflict to subgroup variation, dosage thresholds, or outcome instrument differences.
+4. **Nine fixed checks** per `skill/agents/skeptic.md`; absence of counter-evidence yields the standard statement, never invented sources.
+
+## Output Contract
+`skeptic.json` — `skeptic_findings[]` (`check` / `status` / `detail` / `related_evidence_ids`), `contradictory_evidence_found`, `no_contradictory_evidence_statement`, `threats_to_validity`.
+
+## Quality Gates
+- [ ] 九项检查齐全。
+- [ ] 每条 found 绑定证据或来源。
+- [ ] 标准语句与布尔标志语义一致。
+
+## Anti-Patterns
+- 把三列合并成"总体看有效"；为了显得严谨而虚构反证。
+
+## Worked Example
+同一 claim 下出现 g=+0.48（无护栏练习）与 g=−0.17（独立考试），归因到 outcome 测量差异与护栏配置，而非取平均。
+
+## References
+- `references/skeptic-protocol.md`、`skill/agents/skeptic.md`、`skill/task-briefs/challenge.md`

package/skill/sub-skills/data-analysis/SKILL.md

@@ -1,23 +1,42 @@
 ---
 name: data-analysis
 description: "Runs deterministic statistical regression (DID/OLS) on user-uploaded classroom and field datasets to re-inject local empirical evidence."
+capability: data_validation + data_analysis
 ---
+
 # Data Analysis Skill
 
-## 1. When to Use
+## When to Use
 Trigger when the user imports empirical classroom or survey data (CSV/XLSX) from an active field trial or pilot deployment.
 
-## 2. Process
-1. **Data Ingestion & Cleaning**:
-   - Profile columns, check missingness, identify Treatment and Post indicators.
-2. **Deterministic DID Regression**:
-   - Run Difference-in-Differences OLS: Y = beta0 + beta1*Treat + beta2*Post + delta*(Treat*Post) + epsilon.
-   - Calculate treatment effect delta, standard error, t-statistic, p-value, and Hedges' g.
-3. **Graph Re-adjudication**:
-   - Generate local Evidence Node (EVD-LOCAL-*) and re-run tribunal to update decision snapshot.
-
-## 3. Visualization Sync
-Append the local trial result to the project's visualization contract so the Data Visualization page reflects it without hard-coding:
-- result.json → forest_plot_data: one entry with study_label "Local Field Trial (DID)", outcome_dimension from the trial outcome, effect_size = Hedges' g, ci_lower/ci_upper from the regression CI.
-- result.json → evidence: one evidence object with relation_to_claim derived from the DID delta sign.
-- evidence_graph.json: re-export after adding the EVD-LOCAL-* node.
+## Inputs
+- 数据集 + 采集溯源（谁、何时、从哪个人群、何种同意）
+- 预先注册的分析计划（不得在看到数据后修改）
+
+## Process
+1. **Data Ingestion & Cleaning**: profile columns, check missingness, identify Treatment and Post indicators; the provenance/hash/missingness gate runs before analysis.
+2. **Deterministic DID Regression** (`scripts/did_regression.py`): Y = β0 + β1·Treat + β2·Post + δ·(Treat×Post) + ε; report δ, SE, t, p and Hedges' g (`scripts/effect_calculator.py`).
+3. **Fail closed**: when the design is not estimable (no baseline, no control, attrition beyond tolerance) return `ANALYSIS_NOT_ESTIMABLE` — never fabricate p-values or silently substitute a weaker estimator.
+4. **Graph Re-adjudication**: add a local Evidence Node (`EVD-LOCAL-*`), commit a new revision, re-run the tribunal.
+
+## Output Contract
+`analysis-run` + `dataset-manifest`; the graph revision carries the local node; the decision diff is produced by the update workflow.
+
+## Visualization Sync
+- `result.json` → `forest_plot_data`: one entry with `study_label` "Local Field Trial (DID)", outcome dimension from the trial, effect size = Hedges' g, CI bounds from the regression.
+- `result.json` → `evidence`: one evidence object whose `relation_to_claim` follows the sign of δ.
+- `evidence_graph.json`: re-export after adding the `EVD-LOCAL-*` node.
+
+## Quality Gates
+- [ ] 溯源、哈希、缺失率在分析前记录。
+- [ ] 分析严格按预注册计划执行。
+- [ ] 本地结果作为"一项研究"并入，不覆盖既有证据。
+
+## Anti-Patterns
+- 事后改阈值；把不显著说成无效果；用本地单点结果推翻既有证据体。
+
+## Worked Example
+两班前后测数据 → DID δ=+0.21（不显著）：报告为"本地未复现"，不改变原裁决方向，仅下调适用性置信。
+
+## References
+- `scripts/did_regression.py`、`references/evaluation-design.md`、`skill/workflows/evaluate-and-update.md`

package/skill/sub-skills/ethics-review/SKILL.md

@@ -1,25 +1,48 @@
 ---
 name: ethics-review
-description: "Evaluates trial designs, intervention protocols, and student data collection against Institutional Review Board (IRB) and educational research ethics standards."
+description: "Evaluates trial designs, intervention protocols, and human-subject data collection against IRB and research ethics standards (education and other applied domains)."
+capability: (engine-level gate; no deterministic capability)
 ---
 
-# ethics-review — Research Ethics & IRB Compliance Sub-Skill
+# ethics-review — Research Ethics & IRB Compliance
 
 ## When to Use
-Triggered prior to finalizing any 12-week Quasi-Experimental / DID field trial design involving human student cohorts, classroom telemetry, or control group assignment.
+Triggered before finalising any quasi-experimental / DID field trial design involving human student cohorts, classroom telemetry, or control-group assignment.
 
-## Ethical Audit Checklist
-1. **Control Group Harm Prevention**: Ensures the control group is not deprived of essential pedagogical learning opportunities (recommends delayed crossover or active alternative pedagogies).
-2. **Student Privacy & Telemetry Protection**: Verifies that LLM interaction prompts, code logs, and exam scores are pseudonymized and compliant with FERPA/GDPR educational data privacy.
-3. **Informed Consent & Voluntary Participation**: Enforces opt-out mechanisms without academic penalty.
-4. **Algorithmic Bias & Equity Check**: Audits whether AI tools introduce unfair grading or accessibility barriers for underrepresented student groups.
+## Inputs
+- `intervention.json` / study-design 草案（阶段、人群、对照、数据采集范围）
+- 数据采集清单（分数、日志、提示词、遥测）
+
+## Process — Ethical Audit Checklist
+1. **Control Group Harm Prevention**: the control group must not be deprived of essential learning opportunities (use delayed crossover or active alternatives).
+2. **Participant Privacy & Telemetry Protection**: pseudonymise prompts, interaction logs, and outcome records; comply with the applicable regime (FERPA / GDPR or the domain's equivalent).
+3. **Informed Consent & Voluntary Participation**: opt-out without academic penalty.
+4. **Algorithmic Bias & Equity Check**: audit whether the tool introduces grading bias or accessibility barriers for underrepresented groups.
+5. **Data Retention**: state what is stored, where, and for how long; commercial LLM endpoints must not retain prompts.
+
+## Output Contract
+Ethics review record attached to the study design; a non-passing review blocks the pilot.
 
-## Output Schema
 ```json
 {
   "ethics_status": "APPROVED_WITH_CONDITIONS",
   "irb_tier": "Exempt / Expedited Educational Research (Category 1)",
   "privacy_safeguards": ["Anonymized student IDs", "Zero prompt retention on commercial LLM endpoints"],
-  "equity_protections": "Provide universal high-speed campus lab access to eliminate socioeconomic hardware disparities."
+  "equity_protections": "Provide universal campus lab access to eliminate hardware disparities."
 }
 ```
+
+## Quality Gates
+- [ ] 对照组的可接受替代方案已给出。
+- [ ] 采集字段清单与去标识方式明确。
+- [ ] 退出机制不产生学业惩罚。
+- [ ] 设备/网络差异导致的公平性问题被处理。
+
+## Anti-Patterns
+- 以"教改豁免"跳过伦理审查；保留可回指到个人的提示词日志；用"照常上课"掩盖对照组机会剥夺。
+
+## Worked Example
+12 周准实验含对照班 → APPROVED_WITH_CONDITIONS：延迟交叉 + 匿名 ID + 关闭端点日志留存 + 统一机房访问。
+
+## References
+- `references/evaluation-design.md`、`references/social_science_pitfalls.md`、`skill/task-briefs/intervene.md`

package/skill/sub-skills/evidence-extraction/SKILL.md

@@ -1,19 +1,37 @@
 ---
 name: evidence-extraction
 description: "Extracts fine-grained claims, effect sizes (Hedges g), sample sizes, and methodology variables from validated full-text sources."
+capability: study_extraction + finding_extraction
 ---
+
 # Evidence Extraction Skill
 
-## 1. When to Use
+## When to Use
 Trigger on fetched and validated source texts to perform claim-level feature and statistical extraction.
 
-## 2. Process
-1. **Statistical Extraction**:
-   - Sample sizes (N_treatment, N_control).
-   - Means and standard deviations (M1, SD1, M2, SD2).
-   - Standardized effect size metric: compute Hedges' g, Cohen's d, or Odds Ratio.
-   - 95% Confidence Intervals [CI_lower, CI_upper] and p-values.
-2. **Methodology Extraction**:
-   - Design type: RCT, Quasi-Experimental (DID, PSM, RDD), Correlational.
-   - Outcome classification: Task Performance vs Conceptual Learning vs Delayed Retention.
-3. **Output Contract**: Emit evidence objects per schemas/evidence.schema.json（V1 顶层契约，修订 1.1）into evidence.jsonl; 图谱层投射为 EvidenceLink 时用 schemas/v2/evidence-link.schema.json（V2 契约）。
+## Inputs
+- `sources.jsonl`（全部 FETCH_VALID / 确认的 FETCH_PARTIAL）
+- `fetch/` 清正文；必要时经 Sciverse `/content` 读取定位段落
+
+## Process
+1. **Statistical Extraction**: sample sizes (N_treatment, N_control); means/SDs; standardized effect size (Hedges' g, Cohen's d, Odds Ratio via `scripts/effect_calculator.py`); 95% CIs and p-values when reported.
+2. **Methodology Extraction**: design type (RCT, quasi-experimental DID/PSM/RDD, correlational); outcome classification (task performance vs conceptual learning vs delayed retention).
+3. **Locate precisely**: keep `source_location` (page/section/offset) so every claim can be re-opened.
+
+## Output Contract
+Evidence Objects per `schemas/evidence.schema.json` (V1 top-level, revision 1.1) into `evidence.jsonl`; graph projections use `schemas/v2/evidence-link.schema.json` (V2).
+
+## Quality Gates
+- [ ] 每行通过 evidence schema，枚举合法。
+- [ ] 任务表现与学习效果记录分离。
+- [ ] 缺失统计量保持缺失（禁止由显著性反推效应量）。
+- [ ] 每条记录可定位回原文。
+
+## Anti-Patterns
+- 把 `relation_to_claim` 写到研究本体；把即测分数当保持/迁移；从摘要估算效应量。
+
+## Worked Example
+PNAS 2025 三臂 RCT → 三条 evidence：练习表现（task_performance, support）、独立考试（learning, contradict）、护栏组（learning, support），各带 N 与效应量。
+
+## References
+- `references/evidence-quality.md`、`references/effect_size_formulas.md`、`skill/task-briefs/extract.md`

package/skill/sub-skills/evidence-review/SKILL.md

@@ -1,18 +1,37 @@
 ---
 name: evidence-review
 description: "Synthesizes extracted claims and evidence nodes into the project Evidence Graph with meta-analysis pooling."
+capability: claim_linking + evidence_synthesis
 ---
+
 # Evidence Review Skill
 
-## 1. When to Use
-Trigger to aggregate all validated evidence nodes into the project's single source of truth (SSOT) Claim Graph and execute quantitative synthesis.
-
-## 2. Process
-1. **Evidence Graph State Machine**:
-   - Construct directed graph of Claims, Sources, and Findings.
-   - Determine claim status: SUPPORTED, CONTRADICTED, MIXED, or UNCERTAIN.
-2. **Meta-Analysis Pooling**:
-   - Fixed-effect inverse-variance pooling and DerSimonian-Laird random-effects pooling.
-   - Cochran's Q, degrees of freedom, and I^2 heterogeneity index.
-   - Egger regression and Rosenthal Fail-Safe N publication bias checks.
-   - Leave-one-out study sensitivity analysis.
+## When to Use
+Trigger to aggregate validated evidence nodes into the project's single source of truth (SSOT) Claim Graph and execute quantitative synthesis.
+
+## Inputs
+- `evidence.jsonl` + `methodology.json`
+- 项目 Evidence Graph 当前 revision
+
+## Process
+1. **Evidence Graph State Machine**: build the directed graph of claims, sources, findings; determine claim status (SUPPORTED / CONTRADICTED / MIXED / UNCERTAIN).
+2. **Meta-Analysis Pooling** (`engine/meta_analysis.py`): fixed-effect inverse-variance pooling and DerSimonian–Laird random-effects pooling; Cochran's Q, df, I².
+3. **Publication Bias & Robustness** (`engine/bias.py` / `engine/robustness.py`): Egger regression, Rosenthal fail-safe N, leave-one-out sensitivity.
+4. **Counting rule**: pool by independent **study**, never by finding count.
+
+## Output Contract
+Graph revision (append-only) plus synthesis artifacts; projections (`result.json`, HTML) are derived, never the source of truth.
+
+## Quality Gates
+- [ ] 按独立研究计数，非按 finding 计数。
+- [ ] 异质性（I²、Q）与偏倚检验结果一并报告。
+- [ ] 三个方向列未被合并隐藏。
+
+## Anti-Patterns
+- 同一研究的多个 outcome 当作多项独立证据；对不可合并的结果强行做标准化合并。
+
+## Worked Example
+8 来源 12 条发现 → 仅部分可合并；不可合并者以叙述式证据矩阵呈现并标注原因。
+
+## References
+- `references/evidence-quality.md`、`docs/evidence-synthesis.md`、`engine/meta_analysis.py`

package/skill/sub-skills/gap-analysis/SKILL.md

@@ -1,25 +1,47 @@
 ---
 name: gap-analysis
-description: "Identifies population, measurement, and methodological gaps in the Evidence Graph and diagnoses cross-study empirical contradictions using BioGapLens PICO taxonomy."
+description: "Identifies population, measurement, and methodological gaps in the Evidence Graph and diagnoses cross-study empirical contradictions."
+capability: knowledge_gap_detection
 ---
 
-# gap-analysis — Research Gap Discovery & Contradiction Lens Sub-Skill
+# gap-analysis — Research Gap Discovery & Contradiction Lens
 
 ## When to Use
-Triggered after Evidence Extraction and Meta-Analysis (between Step 8 and Step 9) to ensure that trial designs are strictly grounded on verified empirical gaps rather than generic templates.
+Triggered after evidence extraction and meta-analysis, before study design: trial designs must be grounded on verified empirical gaps, never on generic templates.
 
-## Execution Rules
-1. **Measurement & Retention Gap Audit**: If evidence only measures immediate task speed (OutcomeDimension: PROCEDURAL_EFFICIENCY), flag a missing delayed unassisted retention gap.
-2. **Population Heterogeneity Audit**: Check if studies exclusively evaluate elite CS majors or introductory cohorts; flag advanced algorithmic transfer gaps.
-3. **Contradiction Lens**: When studies report divergent effect directions ($g > +0.3$ vs $g < -0.1$), isolate the moderating variable (e.g. Socratic scaffolding vs unguided copy-pasting).
+## Inputs
+- Evidence Graph（含 claim 状态与 outcome 维度）
+- 矛盾诊断（方向冲突、异质性来源）
+
+## Process
+1. **Measurement & Retention Gap Audit**: if evidence only measures immediate task speed, flag the missing delayed unassisted retention measurement.
+2. **Population Heterogeneity Audit**: check whether studies cover only elite CS majors or introductory cohorts; flag advanced-transfer gaps.
+3. **Contradiction Lens**: when directions diverge (g > +0.3 vs g < −0.1), isolate the moderating variable (e.g. scaffolded vs unguided use).
+4. **Priority**: rank gaps by decision-materiality so study design is not spent on immaterial questions.
+
+## Output Contract
+`GapNode` list written directly to the SSOT Evidence Graph, each with `gap_id`, `gap_type`, `description`, `target_outcome`, `recommended_trial_design`.
 
-## Output Contract (`GapNode` list written directly to SSOT `EvidenceGraph`)
 ```json
 {
   "gap_id": "GAP-RETENTION-001",
   "gap_type": "Measurement/Retention Gap",
   "description": "Lack of 12-week longitudinal retention data measuring unassisted transfer in CS1.",
   "target_outcome": "Delayed Unassisted Problem Solving",
-  "recommended_trial_design": "12-Week Cluster Randomized Trial with 4-week delayed post-test without AI access"
+  "recommended_trial_design": "12-week cluster randomized trial with 4-week delayed post-test without AI access"
 }
 ```
+
+## Quality Gates
+- [ ] 每个 gap 绑定具体未满足的测量/人群/方法维度。
+- [ ] gap 与决策材料性关联，而非"文献少"。
+- [ ] 不把"论文数量少"当作研究缺口。
+
+## Anti-Patterns
+- 用"研究不足"概括一切；把已有证据能回答的问题标成缺口。
+
+## Worked Example
+现有证据多为即测任务表现 → 产出 GAP-RETENTION-001，约束后续 StudyDesign 必须包含无 AI 的延迟后测。
+
+## References
+- `engine/gap_lens.py`、`engine/gaps.py`、`references/scientific-invariants.md`

package/skill/sub-skills/literature-review/SKILL.md

@@ -1,21 +1,42 @@
 ---
 name: literature-review
-description: "Executes multi-source academic and web retrieval across OpenAlex, Semantic Scholar, CrossRef, AIHot, AgentSearch, and user-configured providers (Tavily, Brave, SerpAPI)."
+description: "Executes multi-source academic and web retrieval across OpenAlex, Semantic Scholar, CrossRef, AIHot, AgentSearch, Sciverse, and user-configured providers."
+capability: literature_search + counter_evidence_search + source_fetch + source_validation
 ---
+
 # Literature Review Skill
 
-## 1. When to Use
+## When to Use
 Trigger after research intent is established to gather candidate empirical studies, peer-reviewed papers, and verified grey literature.
 
-## 2. Multi-Channel Search Routing
-1. **Zero-Config Academic Providers**:
-   - OpenAlex: Search 250M+ scholarly works for peer-reviewed studies with DOIs.
-   - Semantic Scholar: Graph-based citation and abstract retrieval.
-   - CrossRef: Official DOI resolution and metadata extraction.
-   - AIHot: Real-time AI research trends and technical reports.
-   - AgentSearch: SciPhi open academic and vector search.
-2. **Configured API Key Providers**:
-   - Tavily, Brave Search, SerpAPI, Exa, Bocha.
-3. **Fetch & Validation**:
-   - Pass candidate URLs through retrieval/fetch.py and validate via retrieval/validate.py.
-   - Strictly reject ungrounded snippet hallucinations.
+## Inputs
+- `frame.json`（检索边界、纳排标准）
+- 检索预算（S/M/L 决定）与可选 key：`SCIVERSE_API_TOKEN` / `TAVILY_API_KEY` / `BRAVE_API_KEY`
+
+## Process
+1. **Plan first** — 写 `SearchPlan`（core / expansion / **counter_evidence**），经 `retrieval/audit.py` 执行并导出审计四件套。
+2. **Zero-Config Academic Providers**: OpenAlex (250M+ works with DOIs), Semantic Scholar (graph citations + abstracts), CrossRef (DOI registry), AIHot (real-time AI/EdTech feed), AgentSearch / ArXiv.
+3. **Key-based academic channel**: Sciverse (`SCIVERSE_API_TOKEN`) — `/meta-search` 产出 Source 级命中；`/agentic-search` 产出 chunk 定位子，必须经 `/content` 读原文并过校验门，定位写入 `chunks.jsonl`。
+4. **Configured web providers**: Tavily, Brave.
+5. **Fetch & Validation**: 候选 URL 走 `retrieval/fetch.py` 降级链并由 `retrieval/validate.py` 校验；严格拒绝 snippet 幻觉。
+6. **Compliance**: 遵守 `references/retrieval-compliance.md`（robots / 限速 / paywall / 署名与缓存）。
+
+## Output Contract
+- `sources.jsonl`（`schemas/source.schema.json`）+ `fetch/`（raw + clean + provenance + fallback_chain）
+- 审计导出：`search-provenance.json` / `search-attempts.jsonl` / `source-screening.csv` / `exclusion-log.csv`
+- Sciverse 定位：`chunks.jsonl`（`locator_state=discovery_only_requires_content_fetch`）
+
+## Quality Gates
+- [ ] 反方查询独立构造且计数 > 0。
+- [ ] 每条来源为 FETCH_VALID 或经确认的 FETCH_PARTIAL。
+- [ ] 无 DOI/URL 记录标 `needs_manual_location`，未伪造定位。
+- [ ] 排除记录写明原因。
+
+## Anti-Patterns
+- 用支持证据的检索式找反证；把 abstract 当证据内容；为凑数填充无关来源。
+
+## Worked Example
+`python scripts/search_provenance.py "first-year CS generative AI coding assistant" --out runs/x/provenance --concept "AI coding assistant"` → 审计四件套 + 候选来源表，随后逐条 fetch/validate。
+
+## References
+- `references/retrieval-protocol.md`、`references/retrieval-compliance.md`、`references/source-validity.md`、`skill/task-briefs/retrieve.md`