eduevidence 6.0.0 → 6.3.0

package/skill/roles/registry.yaml

@@ -1,42 +1,42 @@
 roles:
-  education-planner:
+  research-planner:
     responsibility: framing completeness and scope
     stages: [frame]
-    capabilities: [research-planning]
+    capabilities: [research_framing]
     critical_path: true
   evidence-retriever:
     responsibility: source acquisition and provenance
     stages: [retrieve]
-    capabilities: [literature-review, full-text-fetch, source-validation]
+    capabilities: [literature_search, counter_evidence_search, source_fetch, source_validation]
   evidence-analyst:
     responsibility: structured finding extraction
     stages: [extract]
-    capabilities: [evidence-extraction]
+    capabilities: [study_extraction, finding_extraction, claim_linking]
   skeptic:
     responsibility: independent counter-evidence coverage
     stages: [challenge]
-    capabilities: [contradiction-analysis, counter-retrieval]
-    independence_required: true
+    capabilities: [counter_evidence_search]
+    independence_required: different-model-family
     critical_path: true
   method-reviewer:
     responsibility: methodology and construct-validity appraisal
     stages: [audit]
-    capabilities: [methodology-audit]
-    independence_required: true
+    capabilities: [methodology_appraisal]
+    independence_required: role-separation
     critical_path: true
   evidence-judge:
     responsibility: evidence-bounded adjudication and applicability
     stages: [adjudicate, applicability]
-    capabilities: [evidence-review, decision-adjudication, 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, intervention-design]
+    capabilities: [study_design, measurement_design, intervention_design]
   evaluation-designer:
     responsibility: estimable evaluation and update logic
     stages: [evaluate]
-    capabilities: [evaluation-design, data-analysis]
+    capabilities: [evaluation_design, data_validation, data_analysis]
 
 execution:
   max_parallel_workers: 6

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`

package/skill/sub-skills/methodology-audit/SKILL.md

@@ -1,20 +1,37 @@
 ---
 name: methodology-audit
 description: "Audits empirical studies against WWC 5.0, GRADE risk-of-bias frameworks, and social science pitfalls."
+capability: methodology_appraisal
 ---
+
 # Methodology Audit Skill (Methodology Tribunal)
 
-## 1. When to Use
+## When to Use
 Trigger before claim synthesis to evaluate threats to internal and external validity, applying methodological confidence scoring.
 
-## 2. Audit Frameworks
-1. **WWC 5.0 Rating**:
-   - Tier 1: Meets WWC Standards Without Reservations (clean RCT, low attrition).
-   - Tier 2: Meets WWC Standards With Reservations (QED with baseline equivalence).
-   - Tier 3: Correlational / Promising.
-2. **Social Science 4 Critical Pitfalls**:
-   - Task Performance != Genuine Learning.
-   - Short-Term Score != Long-Term Retention (4+ weeks).
-   - AI-Assisted Performance != Independent Transfer.
-   - Correlation != Causation.
-3. **GRADE Certainty Rating**: High, Moderate, Low, Very Low.
+## Inputs
+- `evidence.jsonl` + `fetch/` 原文
+- `references/wwc_standards.md`、`references/grade_framework.md`、`references/social_science_pitfalls.md`
+
+## Process
+1. **WWC 5.0 Rating**: Tier 1 (meets standards without reservations — clean RCT, low attrition), Tier 2 (with reservations — QED with baseline equivalence), Tier 3 (correlational / promising).
+2. **Social Science Pitfalls**: task performance ≠ genuine learning; short-term score ≠ retention (4+ weeks); AI-assisted performance ≠ independent transfer; correlation ≠ causation.
+3. **GRADE Certainty**: High / Moderate / Low / Very Low at the body-of-evidence level.
+4. **15-item checklist** in fixed order (control_group … dropout), each `met|partial|missing|not_applicable`.
+
+## Output Contract
+`methodology.json` per `schemas/methodology.schema.json`, including `task_vs_learning_guard.equates_task_with_learning`.
+
+## Quality Gates
+- [ ] 15 项齐全且仅用四值枚举。
+- [ ] guard 结论明确。
+- [ ] 审计只判"证据是否成立"，不判"证据说什么"。
+
+## Anti-Patterns
+- 用样本量大掩盖无对照；把相关性研究列入因果结论；缺项直接记 `met`。
+
+## Worked Example
+某准实验无前测等价性 → Tier 2 (with reservations) + `pre_test: missing`；其结论只可用于"提示可能"，不进强支持列。
+
+## References
+- `references/methodology-audit.md`、`references/tribunal-policy.md`、`skill/agents/method-reviewer.md`、`skill/task-briefs/audit.md`

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

@@ -1,6 +1,7 @@
 ---
 name: report-generation
 description: "Renders 5 baked-theme single-file bilingual HTML reports, executive Visual Briefs, and Markdown reports, powered by Lieflat Charts editorial visualization standards and AI-composed, data-driven chart galleries."
+capability: report_projection + report_rendering
 ---
 # Report Generation Skill
 
@@ -55,3 +56,30 @@ Dark themes draw on the theme's `card_bg`; text contrast is checked against the
 
 ## 4. Web Studio Sync
 The Local Web Studio (`scripts/dashboard_server.py`) serves the baked HTML reports and Lieflat figures directly.
+
+## Inputs
+- `result.json` / `result.zh.json`（叙述字段先过语言门禁 `check_language_parallel`）
+- 当前 Graph Revision 与 decision snapshot 标识
+
+## Quality Gates
+- [ ] 双语语义对齐（数字 / ID / 枚举 / URL 不变）。
+- [ ] 渲染完整性门通过：显示数值可回溯到 `result.json`，探针无 `REPORT_INVALID`。
+- [ ] 布局不变量通过 `scripts/lint_report_layout.py`（390 / 768 / 1280 × brief/full）。
+- [ ] 溯源表格保留（来源表 / 证据矩阵 / Claim Trace），图表只作补充。
+- [ ] `artifact_manifest.json` 记录来源 revision 与各产物哈希。
+
+## Anti-Patterns
+- 由模型写入图表数值（数值必须来自 `scripts/charts_data.py` 提取器）。
+- 为了"更可视化"而删除可核验表格；用占位或虚构数据补齐缺失图表。
+- 报告与快照不一致时改报告不改结论；在 HTML 内提供运行时换肤。
+
+## Failure Handling
+| 失败 | 处理 |
+|---|---|
+| `REPORT_INVALID` | 阻断发布并重跑渲染，不带缺陷投放。 |
+| 双语不对齐 | 修复 `result.zh.json` 后重新烘焙。 |
+| 数据不足以支撑某图 | 抑制该图并记录原因，不补造数据。 |
+| 快照缺失 | 回到上游科学阶段补齐；禁止用默认值生成报告。 |
+
+## References
+- `skill/task-briefs/present.md`、`skill/task-briefs/projection.md`、`visualization/eduevidence-report/references/layout-constraints.md`