eduevidence 5.2.0 → 6.2.0

package/skill/task-briefs/present.md

@@ -1,16 +1,40 @@
 # Task Brief — stage: present（角色：report-generation）
 
 ## 目标
-汇总 result.json → result.zh.json（语义对齐、非机翻、数字/ID/枚举/URL 不变），并经
-visualization/eduevidence-report/scripts/build_report.py 烘焙双语报告
+汇总 `result.json` → `result.zh.json`（语义对齐、非机翻、数字/ID/枚举/URL 不变），并经
+`visualization/eduevidence-report/scripts/build_report.py` 烘焙双语报告
 （主题生成时五选一，最终 HTML 只保留中英文切换）。
 
-## 输入
-- result.json + result.zh.json（叙述字段必须先过语言门禁 check_language_parallel）
+## 前置输入
+- `result.json` + `result.zh.json`（叙述字段必须先过语言门禁 `check_language_parallel`）
+- 五主题：claude / academic / datalab / datalab-dark / presentation
 
 ## 产出
-- EduEvidence_Report.html / reports-5themes/*.html + report_spec.json + artifact_manifest.json
+- `EduEvidence_Report.html` / `reports-5themes/*.html` + `report_spec.json` + `artifact_manifest.json`
 
-## 规则
-- 语言门禁：叙述字段人话化（禁 E-xxx 堆砌/schema 键/null 残留/中英交叉污染）；
-  表格/ID/URL/枚举保留可追溯性。
+## 执行规则
+- 语言门禁：叙述字段人话化（禁 E-xxx 堆砌 / schema 键 / null 残留 / 中英交叉污染）；
+  表格/ID/URL/枚举保留可追溯性。
+- 图表由 AI 写 `visual_layout` 计划、渲染器从 `result.json` 取数：**数值不得由模型写入**；
+  未注册 type 显式报错，数据不足则该图抑制并记录原因。
+- 主题在生成时锁定，HTML 内不提供运行时换肤。
+- 报告与导出是投影：渲染失败不得改变任何科学结论。
+
+## 质量门
+- [ ] `check_language_parallel` 通过（中英语义对齐）。
+- [ ] 渲染完整性门通过（`REPORT_INVALID` 探针无命中，显示值可回溯到 `result.json`）。
+- [ ] 布局不变量通过 `scripts/lint_report_layout.py`（含 390/768/1280 × brief/full）。
+- [ ] 溯源表格保留（来源表、证据矩阵、Claim Trace），图表只作补充。
+
+## 失败模式与回退
+| 失败 | 处理 |
+|---|---|
+| `REPORT_INVALID` | 阻断发布并重跑渲染；不得带缺陷投放。 |
+| 双语不对齐 | 修复 `result.zh.json` 后重新烘焙。 |
+| 数据不足以支撑某图 | 抑制该图并写明原因，不用占位或虚构数据补位。 |
+
+## 语言与呈现契约
+面向读者的人话报告；可核验行保持可点击、可回查。
+
+## 交接说明
+报告仅为投影产物；任何结论修订都回到科学阶段并生成新 revision。

package/skill/task-briefs/projection.md

@@ -0,0 +1,37 @@
+# Task Brief — stage: projection（投影层，非科学阶段）
+
+## 目标
+仅从已完成的科学产物与 decision snapshot 生成报告与导出；投影错误不得改变任何科学结论。
+记录确切的来源 revision 与渲染产物哈希。
+
+## 前置输入
+- 已通过各自 schema 与闸门的科学产物（frame / evidence / skeptic / methodology / verdict / 等）
+- 当前 Graph Revision 与 decision snapshot 标识
+
+## 产出
+- `result.json` / `result.zh.json`、`report_spec.json`、`report.html`、`reports-5themes/*.html`、
+  `artifact_manifest.json`（含来源 revision 与产物哈希）、各类导出（证据包 / 判题包）。
+
+## 执行规则
+- 投影只读：**不得回写或修改任何科学产物**，不得据显示需要调整结论。
+- 投影产物一律标注来源 revision 与渲染哈希，使报告可被追溯回具体快照。
+- 呈现层与事实层分离：`result.json` / HTML / Markdown 都不是事实库。
+- 渲染失败只影响该产物本身：阻断发布、重跑渲染，不降级、不改写结论。
+
+## 质量门
+- [ ] `artifact_manifest.json` 记录来源 revision 与各产物哈希。
+- [ ] 投影内容与快照一一对应，无"报告比证据更新"的情况。
+- [ ] 渲染完整性门与布局不变量通过。
+
+## 失败模式与回退
+| 失败 | 处理 |
+|---|---|
+| 渲染失败 | 阻断发布，重跑渲染（`REPORT_INVALID` → `block_publish_rerun_render`）。 |
+| 快照缺失 | 回到上游科学阶段补齐；禁止用默认值或占位内容生成报告。 |
+| 报告与快照不一致 | 以快照为准重建投影。 |
+
+## 语言与呈现契约
+面向读者的人话呈现；可追溯行（ID / URL / 数值）保持可核验。
+
+## 交接说明
+投影产物可自由删除重建；重建不应改变任何科学结论或修订历史。

package/skill/task-briefs/retrieve.md

@@ -4,12 +4,42 @@
 按 Frame 的 scope 与 inclusion criteria 检索支持证据与独立反方证据；只检索，不下结论。
 Fetch/Validate 是 Retrieve 内部强制 gate（RULE 2：snippet ≠ 证据内容）。
 
-## 输入
-- frame.json（检索边界、纳排标准）
+## 前置输入
+- `frame.json`（检索边界、纳排标准）
+- 复杂度等级对应的检索预算（S/M/L）
 
 ## 产出
-- sources.jsonl：每行一个 Source Object（source_id/title/canonical_url/authority_level），
-  经 retrieval/validate.py 校验；抓取内容存 fetch/（raw + clean + provenance + fallback_chain）。
+- `sources.jsonl`：每行一个 Source Object（source_id / title / canonical_url / authority_level），
+  经 `retrieval/validate.py` 校验；抓取内容存 `fetch/`（raw + clean + provenance + fallback_chain）。
+- 检索审计导出（`scripts/search_provenance.py`）：`search-provenance.json`、`search-attempts.jsonl`、
+  `source-screening.csv`、`exclusion-log.csv`；Sciverse 通道命中另写 `chunks.jsonl`（定位子）。
 
-## 规则
-- 来源权威等级可验证（DOI/期刊/机构），禁止编造 canonical URL；检索记录真实来源。
+## 执行规则
+- **反方证据必须独立构造查询**（`purpose=counter_evidence`），不得复用支持证据的检索式。
+- 先写 `SearchPlan` 再执行；每条查询、每次 provider 尝试、每个排除决定都要留痕。
+- 来源权威等级可验证（DOI/期刊/机构），禁止编造 canonical URL；无 DOI 且无 URL 的记录标 `needs_manual_location`，
+  进入人工筛选，不得伪造定位。
+- **snippet/abstract 只是发现线索**：必须经 `retrieval/fetch.py` 抓取并通过 `retrieval/validate.py` 才可作为证据内容。
+- Sciverse 通道（`SCIVERSE_API_TOKEN`）：`/agentic-search` 返回的是 chunk 定位子，必须经 `/content` 读原文并过校验门。
+- 检索合规见 `references/retrieval-compliance.md`（robots、限速、paywall、署名与缓存政策）。
+
+## 质量门
+- [ ] `sources.jsonl` 每行通过 `schemas/source.schema.json`。
+- [ ] 审计导出四件套齐全，且反方查询计数 > 0。
+- [ ] 每条进入证据链的来源都有 FETCH_VALID 或经规则确认的 FETCH_PARTIAL。
+- [ ] 排除记录写明原因，人工筛选项显式标注。
+
+## 失败模式与回退
+| 失败 | 处理 |
+|---|---|
+| `SEARCH_NO_RESULT` | 放宽词族、切换 provider，或记录 negative-search record；不得静默降低证据标准。 |
+| `FETCH_FAILED` | 走 provider 降级链；链尽则弃用该来源并回退到检索。 |
+| `FETCH_PARTIAL` | 需规则或人工确认后才可进入抽取。 |
+| `SOURCE_INVALID` | 弃用并寻找替代来源。 |
+| `SOURCE_DUPLICATE` | 合并同一论文的镜像 URL，保留最高权威等级条目。 |
+
+## 语言与呈现契约
+筛选理由与排除原因用人话表述；来源标题保留原文，不改写、不翻译。
+
+## 交接说明
+`sources.jsonl` + `fetch/` 是 Extract 的唯一输入；snippet 不得作为抽取依据随链传递。

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

@@ -0,0 +1,85 @@
+---
+name: decision-and-pilot
+description: Convert a bounded evidence decision into a reversible, measurable pilot.
+---
+
+# Decision & Pilot
+
+Use only after an Evidence Review has produced an auditable decision snapshot. Add `Intervene` with a minimal pilot, explicit stop conditions, owner, population, and outcome measures. A pilot is not an adoption claim.
+
+When this workflow is reached from Evidence Autoresearch, require the bridge in `references/autoresearch.md`: the KnowledgeGap is HIGH-DVI and decision-material, remains unresolved, bounded secondary search is saturated, and the empirical study is ethically/operationally feasible. Then still pass the existing grounded StudyDesign gate; "few papers found" alone never authorizes a pilot.
+
+## When this workflow applies
+
+- The review reached `PILOT` (or `ADOPT` with conditions) and the decision must become something a team can actually run.
+- The user asks for an intervention plan, a rollout, a phased adoption, a stop rule, or "what would we do next week".
+- A bounded empirical gap must be closed before the institution can move further.
+
+Not for: producing the review itself (`evidence-review.md`), analysing data that already exists (`evaluate-and-update.md`), or recommending institution-wide deployment — that is an adoption claim this workflow is designed to prevent.
+
+## Prerequisites
+
+1. A completed, schema-valid `final_verdict.json` that passed the Pre-Verdict Gate. A pilot design without a review is a guess with extra steps.
+2. An applicability statement — the pilot population must sit inside the supported population.
+3. If the pilot closes an empirical gap: an explicit evidence-grounded KnowledgeGap ID. No KnowledgeGap, no study design.
+
+## Runbook
+
+| # | Stage | Role | Input | Artifact | Gate |
+|---|---|---|---|---|---|
+| 1–7 | (inherit the review) | — | prior run | `final_verdict.json` + `applicability.json` | the review's own gates must be green |
+| 8 | Intervene | intervention-designer | verdict + frame | `intervention.json` | `schemas/intervention.schema.json`; minimal reversible pilot, not a deployment plan |
+| 8b | (grounding check) | — | `intervention.json` | KnowledgeGap reference | `scripts/complexity_gate.py` + grounded StudyDesign gate |
+| 9 | Evaluate | evaluation-designer | `intervention.json` + verdict | `evaluation.json` | `schemas/evaluation.schema.json`; task vs learning separated, retention and transfer present |
+
+### Stage 8 — Intervene
+
+Design the minimum viable pilot: phased rollout with explicit usage rules and guardrails, an owner, the participating population, and the evidence it aligns to. Every phase needs a **stop condition** (including a harm/risk stop) and a decision point — weeks, not quarters. Resist scope creep: a pilot that cannot be stopped cheaply is not a pilot.
+
+### Stage 8b — Grounding check
+
+A design may proceed only when it answers a real, unresolved gap that the review identified and the evidence cannot close. If the gap is already answered by existing evidence, the correct output is an applicability-bounded decision, not a new trial.
+
+### Stage 9 — Evaluate
+
+Define the measurement plan: baseline, immediate post-test, retention, and transfer, plus process and risk indicators. Success thresholds must be pre-registered; failure and stop thresholds are equally mandatory. Make the analysis plan explicit enough that `scripts/did_regression.py` can execute it on the returned data without further decisions.
+
+## Failure handling and fallbacks
+
+| Failure | Handling |
+|---|---|
+| `NEEDS_USER_CONTEXT` | Ask for population, duration, staffing, and constraints; never invent an operating context. |
+| `INSUFFICIENT_EVIDENCE` | Stop here and return to the review — a pilot cannot substitute for missing evidence about safety or harm. |
+| `SCOPE_MISMATCH` | Shrink the pilot population until it sits inside the supported population. |
+| No grounded KnowledgeGap | Do not design the study; report what evidence would be needed instead. |
+| Ethics review unresolved | Block the pilot; see `skill/sub-skills/ethics-review/SKILL.md`. |
+
+## Human hand-off points
+
+- Before the pilot design is accepted: the course owner confirms feasibility, staffing, and time budget.
+- Before enrolment: ethics/IRB review where human participants or personal telemetry are involved.
+- Before every phase transition: the stop-condition check is a human decision, not an automatic continuation.
+
+## Resuming and updating
+
+Pilot outcome data returns through `reference/` and is re-injected by the `evaluate-and-update` workflow, which commits a new Evidence Graph revision and a new decision snapshot. Never edit a pilot's success threshold after seeing the data.
+
+## Minimal example
+
+```bash
+eduevidence project create --question "Unguarded AI coding assistance in CS1" --domain education   # policy / other registered domains work identically
+eduevidence project show --project PRJ-... # confirm the decision snapshot
+eduevidence study design --project PRJ-... --gap GAP-RETENTION-001 # grounded design
+# write intervention.json (phases + stop conditions) and evaluation.json (thresholds)
+eduevidence pilot register --project PRJ-... --decision DEC-... --title "Phased CS1 pilot"
+```
+
+## Acceptance checklist
+
+- [ ] The pilot traces to a schema-valid verdict and an applicability boundary.
+- [ ] Every phase has an owner, a duration, a stop condition, and a decision point.
+- [ ] Guardrails and usage rules are explicit (what participants may and may not do).
+- [ ] Evaluation separates task performance from learning and includes retention + transfer.
+- [ ] Success and failure thresholds were set before enrolment.
+- [ ] The KnowledgeGap reference exists, or the workflow exited without a study design.
+- [ ] Nothing in the output claims adoption, deployment, or proven benefit.

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

@@ -0,0 +1,93 @@
+---
+name: evaluate-and-update
+description: Re-inject validated outcome data into an evidence graph and re-adjudicate.
+---
+
+# Evaluate & Update
+
+Use when pilot or field data exists. Validate provenance and missingness before analysis, fail closed when inference is not estimable, commit a graph revision, then produce a new decision snapshot and a decision diff.
+
+For autonomous/living refreshes, preserve prior revisions and treat the newly re-adjudicated decision as a candidate update until the applicable review/human gate accepts it. New evidence does not need to flip the action; unchanged action with changed certainty, applicability, or boundary is a valid revision.
+
+## When this workflow applies
+
+- Pilot, field, or survey data has been collected and must now update the decision.
+- New literature or a retraction changes what the existing decision can rest on.
+- A scheduled Living Evidence refresh fires and must feed a decision diff.
+
+Not for: running the original review (`evidence-review.md`) or designing the pilot that produced the data (`decision-and-pilot.md`).
+
+## Prerequisites
+
+1. The dataset plus its collection provenance: who collected it, when, from which population, under which consent.
+2. The prior decision snapshot and the pilot's pre-registered thresholds — they must not be revised now.
+3. Confirmation that the analysis plan was fixed before the data arrived.
+
+## Runbook
+
+| # | Stage | Role | Input | Artifact | Gate |
+|---|---|---|---|---|---|
+| 1 | Validate data | (deterministic) | raw dataset | `dataset-manifest` | provenance, hash, and missingness checked before any analysis |
+| 2 | Analyse | evaluation-designer / `data-analysis` | manifest + analysis plan | `analysis-run` | fail closed when not estimable; never fabricate p-values |
+| 3 | Merge | (deterministic) | analysis + prior graph | new Evidence Graph revision | append-only; prior revisions preserved |
+| 4 | Re-adjudicate | evidence-judge | revised graph | new decision snapshot | verdict schema + Pre-Verdict Gate re-run |
+| 5 | Diff | (deterministic) | old vs new snapshot | `decision-diff` | every change states which evidence caused it |
+
+### Step 1 — Validate before analysing
+
+Profile the dataset for missingness, attrition, and provenance. `provenance/hash/missingness before analysis` is a hard gate: an undocumented dataset is not evidence, and a treatment/control label that cannot be verified is not a comparison.
+
+### Step 2 — Analyse under the pre-registered plan
+
+Run the fixed plan — for the standard classroom case, Difference-in-Differences via `scripts/did_regression.py`, with Hedges' g via `scripts/effect_calculator.py`. If the design is not estimable (no baseline, no control, attrition beyond tolerance), the correct output is `ANALYSIS_NOT_ESTIMABLE`, not a weaker statistic presented as if it were the plan.
+
+### Step 3 — Commit a revision, never an overwrite
+
+A local finding enters the graph as a new node (`EVD-LOCAL-*`) and a new graph revision. Existing sources, findings, and prior decisions stay untouched — the Single Writer rule applies to the commit.
+
+### Step 4 — Re-adjudicate against the whole body of evidence
+
+Local data is one study among many. Re-run the four-state decision over the complete evidence set; a single favourable classroom result never outvotes a body of contrary evidence, and a null local result does not erase positive evidence elsewhere.
+
+### Step 5 — Publish a decision diff
+
+The deliverable is the diff: what changed in action, confidence, applicability, or boundary, and which evidence moved each one. Unchanged action with changed uncertainty is a real result and should be reported as such.
+
+## Failure handling and fallbacks
+
+| Failure | Handling |
+|---|---|
+| `ANALYSIS_NOT_ESTIMABLE` / `ANALYSIS_CAPABILITY_UNAVAILABLE` | Fail closed: report the design limitation; never substitute a weaker estimator silently. |
+| Missingness above tolerance | Report attrition explicitly; downgrade certainty rather than dropping participants silently. |
+| Thresholds changed post-hoc | Stop; the change is a protocol deviation and must be recorded, not absorbed. |
+| New evidence contradicts on method only | Keep the finding, strip its support role (methodology gate). |
+| Retraction of a cited source | Run `scripts/retraction_watch.py`, remove the source's support, re-adjudicate. |
+
+## Human hand-off points
+
+- Before analysis: data owner confirms consent and de-identification.
+- Before the new decision is effective: the review/human gate accepts or rejects the candidate update (`living` refresh).
+- When the diff changes a stop condition: the course owner decides whether the pilot continues.
+
+## Resuming and updating
+
+Autonomous refreshes create candidate updates only. Living Evidence subscriptions keep prior revisions and surface each refresh as a diff for acceptance; nothing overwrites a published decision. Repeated no-change refreshes are recorded, not re-announced.
+
+## Minimal example
+
+```bash
+eduevidence data ingest --project PRJ-... --file pilot-results.csv
+eduevidence analyze --project PRJ-... --outcome retention --design did
+eduevidence adjudicate --project PRJ-... # new decision snapshot + diff
+eduevidence living status --project PRJ-... # scheduled refresh state
+```
+
+## Acceptance checklist
+
+- [ ] Dataset provenance, hashing, and missingness recorded before analysis.
+- [ ] Analysis followed the pre-registered plan; non-estimable designs failed closed.
+- [ ] A new graph revision was committed; no prior revision was modified.
+- [ ] Re-adjudication used the full evidence set, not the local data alone.
+- [ ] The decision diff states each change and the evidence that caused it.
+- [ ] Any retracted source was removed from the support structure.
+

package/skill/workflows/evidence-review.md

@@ -0,0 +1,117 @@
+---
+name: evidence-review
+description: Traceable evidence review with mandatory counter-evidence and methodology gates.
+---
+
+# Evidence Review
+
+Use for a question that needs a bounded, decision-grade evidence assessment.
+Run `Frame → Retrieve → Extract → Challenge → Audit → Adjudicate → Applicability`.
+
+The required outputs are a search plan and attempt log, validated sources, claim-level evidence links, a methodology audit, a decision boundary, and applicability limits. Search snippets are discovery metadata, never evidence.
+
+When the user asks to continue autonomously, identify the next most decision-relevant evidence, or keep iterating until the evidence state reaches a bounded stopping condition, load `references/autoresearch.md`. Keep the public workflow unchanged: Evidence Autoresearch is a meta-layer over this review, not a fourth user-facing workflow. Preserve append-only evidence and the Single Writer rule.
+
+## When this workflow applies
+
+- A decision question can be answered from **existing** research — across any field: teaching methods, curriculums, AI tools, policies, programmes, clinical or organisational practice, cultural or media interventions.
+- The user needs to know what the evidence supports, what it cannot support, for whom, and under which conditions.
+- The user explicitly asks for a review, synthesis, appraisal, or an evidence-bounded recommendation.
+
+Not for: designing a new study or pilot (use `decision-and-pilot.md`), re-injecting field data into an existing decision (use `evaluate-and-update.md`), or a quick literature list with no decision target.
+
+The **domain** changes the frame vocabulary, not the protocol. `education` frames populations as learner/course; `policy` frames them as decision object/population/stakeholders; other domains register their own frame contract under `domains/`. Every stage below is domain-independent.
+
+## Prerequisites
+
+1. A research question plus the decision it feeds — if the decision target is missing, run the `frame` stage before anything else.
+2. A run workspace (`eduevidence run --question "..."`) so every artifact has a durable home; do not carry state in chat.
+3. A Complexity Gate level (S/M/L) from `scripts/complexity_gate.py`; it fixes the retrieval breadth, not the protocol.
+
+## Runbook
+
+| # | Stage | Role | Input | Artifact | Gate |
+|---|---|---|---|---|---|
+| 1 | Frame | research-planner | user question | `frame.json` | the selected domain's frame schema (`domains/<id>/manifest.json` → `frame_schema`); no intervention advice before framing completes |
+| 2 | Retrieve | evidence-retriever | `frame.json` | `sources.jsonl` + `fetch/` | `schemas/source.schema.json`; Fetch/Validate gate inside Retrieve (RULE 2) |
+| 3 | Extract | evidence-analyst | `sources.jsonl` + `fetch/` | `evidence.jsonl` | `schemas/evidence.schema.json`; outcome separation (task ≠ learning) |
+| 4 | Challenge | skeptic | `evidence.jsonl` | `skeptic.json` | all 9 fixed checks executed; no fabricated counter-evidence |
+| 5 | Audit | method-reviewer | `evidence.jsonl` + fetched text | `methodology.json` | `schemas/methodology.schema.json`; `task_vs_learning_guard` present |
+| 6 | Adjudicate | evidence-judge | all of the above | `raw_verdict.json` → `final_verdict.json` | `schemas/verdict.schema.json`; Pre-Verdict Gate before finalising |
+| 7 | Applicability | evidence-judge | `evidence.jsonl` + verdict | `applicability.json` | supported population, conditions, exclusions and uncertainty stated |
+
+Execute the stages in order. A stage may be delegated to a sub-agent, a script, or the host model itself — the artifact and its gate are what count, never which adapter produced it.
+
+### Stage 1 — Frame
+
+Produce the PICO-style frame with decision target, scope, and inclusion/exclusion criteria, using the vocabulary of the selected domain (education: learner/course; policy: decision object/population/stakeholders). Ask the user only for inputs that cannot be inferred (target population, intervention variant, comparison, primary outcome); never invent defaults for them. Emit the suggested complexity level alongside the frame.
+
+### Stage 2 — Retrieve
+
+Write an auditable search plan (`SearchPlan`) with core, expansion, and **independent counter-evidence** queries, then execute it through `scripts/search_provenance.py` so attempts, screening decisions and exclusions are exported. `Fetch`/`Validate` are mandatory gates inside this stage: a snippet or abstract is a discovery aid; only fetched, validated content can be extracted from. Zero-config channels (OpenAlex / Semantic Scholar / CrossRef / AIHot / AgentSearch) work without keys; Sciverse (`SCIVERSE_API_TOKEN`) adds citation-grade retrieval with `doc_id`/`offset` provenance, and its chunk hits must be expanded through `/content` before use.
+
+### Stage 3 — Extract
+
+Extract claim-level Evidence Objects with effect sizes, CIs, sample sizes, outcome type and source location. Keep `relation_to_claim` on the link, never on the study. Do not merge task-performance and learning outcomes into one record.
+
+### Stage 4 — Challenge
+
+Run the nine fixed checks: null results, negative results, contradictory findings, alternative explanations, measurement mismatch, sampling bias, novelty effect, AI dependency, scope overreach. If nothing is found, state `NO CONTRADICTORY EVIDENCE FOUND` — absence of counter-evidence is a finding, not a gap to fill with invented sources.
+
+### Stage 5 — Audit
+
+Appraise each study against the methodology checklist and WWC 5.0 / GRADE-informed criteria. The auditor judges whether the evidence stands, never what it says. Record the `task_vs_learning_guard` verdict explicitly.
+
+### Stage 6 — Adjudicate
+
+Integrate frame, evidence matrix, skeptic findings and methodology audit into one of four states — `ADOPT` / `PILOT` / `REJECT` / `INSUFFICIENT EVIDENCE` — with `what_can_be_claimed` / `what_cannot_be_claimed` and a confidence breakdown. Run `scripts/pre_verdict_gate.py` **before** the verdict is treated as final; a critical failure caps confidence and forbids a high-confidence adoption claim.
+
+### Stage 7 — Applicability
+
+State who the evidence applies to, in which contexts, for which outcomes, under which conditions, and where it stops. A positive average effect never transfers automatically.
+
+## Failure handling and fallbacks
+
+| Failure | Handling |
+|---|---|
+| `SEARCH_NO_RESULT` | Broaden terms, switch discovery provider, or record a negative-search record — never lower the evidence bar silently. |
+| `FETCH_FAILED` | Run the provider degradation chain; if it is exhausted, discard the source and return to Retrieve. |
+| `FETCH_PARTIAL` | Require rule or human confirmation before extraction; never reconstruct missing text from memory. |
+| `SCHEMA_INVALID` | Block the stage, repair the artifact, re-run the gate; do not advance. |
+| `METHODOLOGY_TOO_WEAK` | Keep the study in the matrix but strip its support role. |
+| `CONFLICT_UNRESOLVED` | Stay uncertain; do not force adjudication. |
+| `INSUFFICIENT_EVIDENCE` | Emit `INSUFFICIENT EVIDENCE` with the specific evidence that would change the decision. |
+
+## Human hand-off points
+
+- After Frame, when population / intervention / comparison / outcome inputs are missing (`NEEDS_USER_CONTEXT`).
+- After Challenge, when counter-evidence is absent, thin, or directly contradicts the working conclusion.
+- After Adjudicate, before the decision is used for a real change in practice, curriculum, policy or operations.
+
+## Resuming and updating
+
+Resume with `eduevidence resume --run-id <id>`: the workspace continues from the first stage whose artifact is missing or schema-invalid. Evidence is append-only — a correction adds a new revision and a new decision snapshot; never overwrite an earlier one. To refresh the same question later, run the `evaluate-and-update` workflow so the change lands as a decision diff rather than a silently rewritten report.
+
+## Minimal example
+
+```bash
+eduevidence run --question "Should first-year CS students use generative AI coding assistants?" --run-id ai-cs1
+python scripts/search_provenance.py "first-year CS generative AI coding assistant learning outcomes" \
+  --out runs/ai-cs1/provenance --concept "AI coding assistant"
+eduevidence status --run-id ai-cs1
+eduevidence gate --run-id ai-cs1
+eduevidence report --run-id ai-cs1 --theme claude
+```
+
+The shipped reference result for this exact question is `examples/ai-coding-assistant-evidence/` — read its `frame.json` → `sources.jsonl` → `evidence.jsonl` → `skeptic.json` → `methodology.json` → `verdict.json` chain to see what a completed review looks like.
+
+## Acceptance checklist
+
+- [ ] Frame passes its schema and states scope plus inclusion/exclusion criteria.
+- [ ] Search plan shows core, expansion and independent counter-evidence queries with attempts and exclusions exported.
+- [ ] Every extracted finding traces to fetched, validated content — no snippet-only evidence.
+- [ ] All nine skeptic checks ran; the contradiction statement is explicit either way.
+- [ ] Methodology audit separates task performance from learning and records the guard verdict.
+- [ ] Verdict is one of the four states, carries its confidence breakdown, and passed the Pre-Verdict Gate.
+- [ ] Applicability states population, conditions, outcome limits and uncertainty.
+- [ ] Reports and exports are projections of the stored artifacts, not a new source of truth.

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

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