eduevidence 6.0.0 → 6.3.0

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

@@ -7,4 +7,79 @@ description: Convert a bounded evidence decision into a reversible, measurable p
 
 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 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

@@ -8,3 +8,86 @@ description: Re-inject validated outcome data into an evidence graph and re-adju
 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

@@ -11,3 +11,107 @@ Run `Frame → Retrieve → Extract → Challenge → Audit → Adjudicate → A
 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/skill/workflows/experimental-jev.md

@@ -0,0 +1,170 @@
+---
+name: experimental-jev
+description: Optional Jev / SemDecide Tier-0 acceleration overlay. Modes 0 standard / 1 jev-mcp / 2 semdecide / 3 hybrid. Fail-closed. Never replaces Pre-Verdict Gate or Skeptic.
+---
+
+# Experimental Jev Overlay
+
+Use only when the run explicitly enables the overlay: `eduevidence run --enhancement jev`
+(and/or `--enhancement semdecide`, which is recorded in the run's `intake.json`), or
+`EDU_EXPERIMENTAL_JEV=<mode>` for the detect CLIs (`--experimental <0|1|2|3>` is a flag of
+`integrations/jev_mcp.py` and `integrations/semantic_decide.py`, not of the host CLI).
+This is an **acceleration overlay** on the scientific protocol — not a fourth workflow,
+not a substitute for scientific gates, and not a source of evidence.
+
+Default without an explicit selection: **mode 0 standard** (existing large-model pipeline only).
+
+## Modes
+
+| Mode | Name | Backing | When |
+|---:|---|---|---|
+| 0 | standard | host large model only | default; no experimental flag |
+| 1 | jev-mcp | `integrations/jev/` → FreeJev or Vercel AI Gateway `typesafe-ai/jev` (urllib) or documented MCP (`https://freejev.org/mcp`, `npx -y @jkudish/jev-mcp`) | Tier-0 typed judgments, fast & cheap |
+| 2 | semdecide | `integrations/semantic_decide.py` → `semdecide is / filter / choose` | Unix-pipeline predicates, filtering, routing |
+| 3 | hybrid | 1 + 2 together | screen/rerank/extract/classify/verify via Jev; local predicates via SemDecide |
+
+Enable:
+
+```bash
+# resolve mode + detect backends (no network judgment yet)
+python3 integrations/jev_mcp.py --experimental 3
+python3 integrations/semantic_decide.py --experimental 3
+
+# user confirmation gate (writes ~/.eduevidence/jev_mcp_approval.json)
+python3 integrations/jev_mcp.py --experimental 3 --approve
+
+# host CLI (documented entry; the enhancement selection turns the overlay on for the run)
+eduevidence run --question "..." --run-id <id> --enhancement jev --enhancement semdecide
+```
+
+Secrets live only in `~/.eduevidence/env` — never in the repository, never on argv.
+
+| Provider | Env | Decide endpoint | MCP (documented only) |
+|---|---|---|---|
+| `freejev` | `FREEJEV_API_KEY`, `JEV_PROVIDER=freejev` | `https://freejev.org/api/v1/decide` | `https://freejev.org/mcp` |
+| `vercel` (default) | `AI_GATEWAY_API_KEY` or `TYPESAFE_API_KEY`, `JEV_PROVIDER=vercel` | Vercel AI Gateway System One | `npx -y @jkudish/jev-mcp` |
+
+**FreeJev `request_id` is an idempotency key — never retry the same `request_id`.**
+On timeout / 5xx / unknown outcome, fail-closed escalate this call to the large
+model. A deliberate re-ask must use a **new** `request_id` and its own provenance row.
+
+## Non-negotiable boundaries
+
+1. **Fail-closed.** Any Jev `JEV_INVALID_RESPONSE` / `JEV_PROVIDER_ERROR`, and any
+   SemDecide exit **2 / 3 / 4** (plus `SEMDECIDE_UNAVAILABLE` / `SEMDECIDE_TIMEOUT`),
+   escalates to the large model (or a human). Never invent, never silently
+   accept, never force a binary on an uncertain probability.
+2. **FreeJev `request_id` 不重试.** Same `request_id` is never resent; escalate instead.
+2. **Does not replace `scripts/pre_verdict_gate.py`.** Stage Adjudicate still runs the
+   Pre-Verdict Gate before any verdict is final.
+3. **Does not replace Skeptic.** Stage Challenge still executes all nine fixed checks
+   (`skill/sub-skills/contradiction-analysis`). `claim_verify` may pre-triage claims only.
+4. **Does not replace methodology audit / tribunal / outcome separation.**
+5. **Snippet ≠ evidence (RULE 2).** `content_screen` / `semantic_rerank` operate on
+   discovery material only. Only fetched, validated content enters Extract.
+6. **Verbatim extract only.** `field_extract` returns regex-matched substrings chosen by
+   Jev — never model-authored field values. `review` / `not_found` are not extraction.
+7. **Approval gate.** Network Tier-0 calls require
+   `~/.eduevidence/jev_mcp_approval.json` (tools hash + provider + model). Missing or
+   mismatched approval → `JEV_APPROVAL_REQUIRED`, escalate.
+
+## Nine-stage mapping (`engine/workflows.py::SCIENTIFIC_STAGE_IDS`)
+
+| # | Stage | Mode 1 / 3 Jev Tier-0 | Mode 2 / 3 SemDecide | Still mandatory (never skipped) |
+|---:|---|---|---|---|
+| 1 | Frame | — | `choose` optional route for domain/frame vocabulary (uncertain → planner) | Frame schema; no intervention advice before framing |
+| 2 | Retrieve | `content_screen` (pre-context injection/substance/relevance); `semantic_rerank` (discovery order); `classify_check` (inclusion pre-triage) | `filter` on candidate JSONL; `is` for cheap exclusion predicates | Search plan + counter-evidence queries; Fetch/Validate gate; provenance export |
+| 3 | Extract | `field_extract` (verbatim n / effect / CI candidates); `classify_check` (outcome type pre-label) | `is` for task-vs-learning guard pre-check | Evidence Objects schema; outcome separation; finding ≠ study merge ban |
+| 4 | Challenge | `claim_verify` **assist only** (claim↔evidence relation triage) | `is` for "is there a contradiction signal?" assist | **All nine Skeptic checks**; `NO CONTRADICTORY EVIDENCE FOUND` rule |
+| 5 | Audit | `claim_verify` assist on claim support | `is` for checklist pre-filter | Methodology audit + `task_vs_learning_guard` |
+| 6 | Adjudicate | — (Tier-0 must not score final verdict) | — | Four-state verdict; confidence breakdown; **`scripts/pre_verdict_gate.py`** |
+| 7 | Applicability | `classify_check` optional population/context tags | `choose` optional applicability bounds | Population / conditions / exclusions / uncertainty stated |
+| 8 | Intervene | — | — | Intervention design gates (`intervention_design`) |
+| 9 | Evaluate | — | — | Evaluation design + data validation (`evaluation_design`, `data_validation`) |
+
+Projection (report render) stays outside the nine stages and outside this overlay.
+
+## Capability ↔ tool
+
+Registered in `engine/capabilities.py` (experimental set; resolve with
+`capability_registry(include_experimental=True)` or `experimental_capability_registry()` —
+omitted from the default scientific registry because Tier-0 is not role-owned work):
+
+| capability_id | Tool | Mode |
+|---|---|---|
+| `content_screen` | `jev_mcp.screen` | 1, 3 |
+| `semantic_rerank` | `jev_mcp.rerank` | 1, 3 |
+| `field_extract` | `jev_mcp.extract` | 1, 3 |
+| `classify_check` | `jev_mcp.classify` | 1, 3 |
+| `claim_verify` | `jev_mcp.verify` | 1, 3 |
+
+SemDecide wrappers (`integrations/semantic_decide.py`) support stages without new
+capability IDs: `is` / `filter` / `choose`.
+
+## Fail-closed matrix
+
+Aligned with `integrations/semantic_decide.py` (`EXIT_MEANINGS`, `ESCALATE_EXIT_CODES`,
+`requires_llm_escalation`, `escalate_plan`) and `integrations/jev/gateway.py` status codes.
+
+| Signal | Meaning | Action |
+|---|---|---|
+| Jev `JEV_INVALID_RESPONSE` | typed answer / `answers` envelope missing or malformed | escalate to large model; mark `review` |
+| Jev `JEV_PROVIDER_ERROR` | transport / HTTP 401, 403, 429, 529, 5xx | escalate this call only; record attempt |
+| FreeJev `request_id` failure/timeout | idempotent decide attempt already keyed | **do not retry same `request_id`**; escalate / new id only |
+| `JEV_APPROVAL_REQUIRED` | no/wrong approval file | do not call network; escalate / ask user to approve |
+| `JEV_UNAVAILABLE` | no key and no MCP path | mode 0 standard pipeline |
+| SemDecide exit `0` | `true/selected/match` | semantic result usable |
+| SemDecide exit `1` | `false/no match` | usable; `filter` exit 1 is **not** an escalation by itself |
+| SemDecide exit `2` | `invalid input` | repair input and re-run, or hand the whole decision to the large model |
+| SemDecide exit `3` | `uncertain` | escalate to large model / human; never force true/false |
+| SemDecide exit `4` | `provider failure` | degrade to large model for this call only; record the attempt |
+| `SEMDECIDE_UNAVAILABLE` | binary missing / spawn failed | escalate (`requires_llm_escalation`) |
+| `SEMDECIDE_TIMEOUT` | CLI timed out | escalate (`escalate=ESCALATE_TO_LLM`) |
+| Screen `block` / `review` | injection or low trust | do not enter context; discard or human review |
+| Extract `review` / `not_found` | provisional or absent value | not an extracted field; large model re-extract |
+| Classify `review` | low confidence / margin | large model re-label |
+| Verify `review` / `unknown` | low confidence / invalid | large model claim check; never auto-adopt |
+
+## Degradation path
+
+```
+mode 3 hybrid
+  ├─ provider key + approval             → Tier-0 screen/rerank/extract/classify/verify
+  │    (FreeJev: FREEJEV_API_KEY + JEV_PROVIDER=freejev; request_id never retried)
+  ├─ semdecide on PATH                   → is/filter/choose
+  ├─ exit 2/3/4 / SEMDECIDE_TIMEOUT
+  │    / JEV_INVALID_RESPONSE / JEV_PROVIDER_ERROR
+  │                                    → large model for THAT call (fail-closed)
+  ├─ Jev unavailable                     → SemDecide only (mode 2 slice)
+  ├─ semdecide unavailable               → Jev only (mode 1 slice)
+  └─ both unavailable / overlay not selected → mode 0 standard (Platform Native)
+```
+
+Scientific gates do not degrade: Pre-Verdict Gate, Skeptic nine checks, methodology
+audit, and the four-state tribunal always run on the host path.
+
+## Acceptance checklist
+
+- [ ] The overlay selection is recorded on the run (`intake.json` enhancements); absent
+      selection means mode 0.
+- [ ] Approval file present and `tools_hash` matches before any gateway call.
+- [ ] Every Tier-0 result stored with `status` / `confidence` / `escalate` provenance.
+- [ ] All SemDecide exit 2/3/4, `SEMDECIDE_UNAVAILABLE`, and `SEMDECIDE_TIMEOUT` rows
+      show an escalation record (no silent coercion). `filter` exit 1 alone is not escalated.
+- [ ] FreeJev calls never reuse a `request_id` for retry; each attempt is one shot.
+- [ ] Stage 4 Challenge still has the nine Skeptic checks + explicit contradiction statement.
+- [ ] Stage 6 Adjudicate still ran `scripts/pre_verdict_gate.py` before finalising.
+- [ ] A/B metrics logged per `docs/j-ev-experimental.md` (speedup口径 + quality gates).
+- [ ] No secrets in artifacts (`AI_GATEWAY_API_KEY` / `TYPESAFE_API_KEY` / `FREEJEV_API_KEY`);
+      keys only from `~/.eduevidence/env` / process env.
+
+## Minimal example
+
+```bash
+export EDU_EXPERIMENTAL_JEV=3   # detect CLIs read this; the host run uses --enhancement
+python3 integrations/jev_mcp.py --experimental 3 --approve
+eduevidence run --question "Should first-year CS students use generative AI coding assistants?" \
+  --run-id ai-cs1-jev --enhancement jev --enhancement semdecide
+# Scientific path unchanged: Frame → Retrieve → Extract → Challenge → Audit → Adjudicate → Applicability
+# Tier-0 only pre-screens, re-ranks, extracts verbatim fields, pre-labels, pre-verifies claims.
+```

package/skill/workflows/intake.md

@@ -0,0 +1,120 @@
+---
+name: intake
+description: One-shot two-round user intake before any research workflow. User answers only mode and questions; the agent infers the rest and then runs unattended.
+---
+
+# Intake — 一次性两轮引导
+
+Use this **before** selecting `evidence-review` / `decision-and-pilot` / `evaluate-and-update`.
+The user answers **only** mode and questions. Everything else is agent judgment.
+After the wrap-up summary is confirmed once, run **unattended**.
+
+Programmatic twin: `scripts/intake/` package (`session.py` + `prefs.py` + `hooks.py`) +
+`schemas/v2/intake.schema.json`.
+Non-question preferences persist to `~/.eduevidence/prefs.json`
+(`enhancement`, `mcp`/`jev` mappings, `depth_preference`, `open_browser`,
+`default_main_theme`). **Never record the research question in prefs.**
+All five report themes stay rendered; `default_main_theme` only decides which one to open.
+
+---
+
+## 第一轮固定语句（逐字使用）
+
+```text
+1) 研究问题（必填）
+2) 执行增强（可多选，各附一句话简介）：
+   [agent_mcp] Agent MCP — 多 CLI/多模型分工、独立子上下文、超时恢复（可选执行增强）
+   [jev]       Jev — 轻量工具子集派发，适合把确定性小步交给受限工具面
+   [semdecide] SemDecide — 语义决策辅助，只结构化上游意图，不改下游确定性路由
+   [none]      均不启用 — 平台原生模式，零外部执行增强
+3) 深度：
+   [S]    S 快检 — 单点问题，最小检索面，直接给边界结论
+   [M]    M 标准 — 常规采用/比较问题，标准证据到决策流程
+   [L]    L 深研 — 高影响、有争议或要试点，完整深研与决策扩展
+   [auto] 自动 — 不选则按指南判定
+```
+
+### 深度自动判定指南（仅当用户选 auto / 不选）
+
+| 信号 | 判定 |
+|---|---|
+| 单点问题（查定义、查公式、单条事实） | **S** |
+| 常规采用 / 是否有效 / 比较对照 | **M** |
+| 高影响、有争议、要试点 / 全面部署 / 政策级 | **L** |
+| 不确定 | **M** |
+
+用户显式选 S / M / L 时**不再**自动判定。CLI 同义词：`quick=S`，`standard=M`，`deep=L`。
+
+---
+
+## 第二轮（仅在需要时追问）
+
+### A. 增强项（仅当第一轮勾选了对应增强）
+
+| 增强开启时 | 第二轮只问这一项 | 落盘位置 |
+|---|---|---|
+| **Agent MCP** | 角色 → CLI / 模型 **授权表**（只展示本机扫描到的真实 CLI/模型；确认后固化 `~/.eduevidence/agent_mcp_approval.json`，含 `role_mapping_hash`） | prefs.`mcp.role_mapping` + 批准文件 |
+| **Jev** | 工具子集（如 `search` / `fetch` / `validate`；只派发确定性小步，禁止旁路 spawn） | prefs.`jev.tool_subset` |
+| **SemDecide** | 用途说明（只结构化上游 ResearchIntent / Frame，供 `recommend_mode`；**不改**下游确定性路由） | prefs / intake.`semdecide.purpose` |
+
+未勾选的增强**不得**追问。勾选「均不启用」则整段跳过。
+
+### B. 背景智能深挖（始终执行）
+
+按题目推断领域 Frame 骨架后，针对该题追问 **3–6** 个影响边界的问题：
+
+1. **人群**（目标学习者 / 决策对象）
+2. **干预**（具体方法 / 工具及用法）
+3. **对照**（与什么比较；可用 business as usual）
+4. **主结果**（一个主要结果指标）
+5. **情境**（学制 / 班型 / 线上线下 / 支持条件）
+
+规则：
+
+- **智能默认 + 一次确认**：能从题目直接推出的字段给出默认值，用户回车即采纳；推出不出的字段留空追问，**禁止编造**。
+- 全部边界答完后，打印一次摘要，**一次确认**。
+- 摘要确认后进入无人值守，不再逐步打断。
+
+### C. 收尾摘要（一次确认）
+
+```text
+—— 收尾摘要（一次确认后无人值守）——
+  问题：…
+  增强：…
+  深度：…（判定理由）
+  边界：population / intervention / comparison / primary_outcome / context
+  结束后打开报告：是|否 ｜ 主主题：claude|academic|datalab|datalab-dark|presentation
+  确认并开始无人值守执行？[Y/n]
+```
+
+用户确认后：写入 `intake.json`（过 `schemas/v2/intake.schema.json`），更新 `prefs.json`（不含研究问题），调用 `eduevidence run` / 工作流，**不再提问**。
+
+---
+
+## 无人值守与浏览器
+
+- `python3 -m intake.cli --print-prompts`（或 `python3 scripts/intake/__main__.py --print-prompts`）
+- `eduevidence run --yes` 或非 TTY：跳过全部提问，只用 prefs + CLI 标志，**不**弹浏览器。
+- 结束时若 `prefs.open_browser` 为 true 且终端可交互：用 `webbrowser.open` 打开**主报告**。
+- 五主题全部渲染并保留在 `reports-5themes/`；主报告 = `default_main_theme` 对应的那份，只决定**打开哪份**，不删除其余主题。
+- `python3 scripts/dashboard_server.py --open`（或 `eduevidence dashboard --open`）启动后打开 Studio URL `/studio/`。
+
+## 与 Canonical Protocol 的关系
+
+Intake 不是协议阶段，只是启动前的**一次性**用户契约收集。收集完成后的流程仍走：
+
+```text
+Evidence Review → Decision & Pilot → Evaluate & Update
+```
+
+Frame 阶段（`skill/task-briefs/frame.md`）继续负责完整 Research Frame 与 `NEEDS_USER_CONTEXT`；
+本文件的边界追问只是提前把用户才知道的边界收齐，避免中途反复打断。
+
+## 失败处理
+
+| 失败 | 处理 |
+|---|---|
+| 研究问题为空 | 第一轮重问；不得带空问题进入工作流。 |
+| 用户不确认收尾摘要 | 回到对应轮次修改，不得静默开跑。 |
+| 增强不可用（如 Agent MCP 未安装） | 记录 `AGENT_MCP_UNAVAILABLE` 并降级 Platform Native；不阻断科学正确性。 |
+| 边界字段用户拒绝提供 | 显式标注 `unknown + 如何获取`（FR-03），禁止用默认值冒充事实。 |

package/visualization/eduevidence-report/scripts/build_figures.py

@@ -32,7 +32,7 @@ from pathlib import Path
 from typing import Any
 
 from adapter_contract import load_result, write_adapter_output
-from zh_labels import zh_outcome
+from zh_labels import label
 from build_charts import effect_outcomes
 
 OKABE_ITO = ["#E69F00", "#56B4E9", "#009E73", "#F0E442", "#0072B2", "#D55E00", "#CC79A7", "#000000"]
@@ -82,7 +82,26 @@ def _linear_ticks(maxv: int) -> list[int]:
     return ticks
 
 
+def _caption_width(caption: str, font_size: int = 11) -> int:
+    """Conservative width of an italic caption line at the SVG font stack.
+
+    The caption is a single unwrapped line, so a long title used to run past
+    the fixed 720px canvas and get clipped. CJK glyphs are a full em wide;
+    latin is bounded by the same cap-height factor used elsewhere in this
+    module.
+    """
+    cjk = sum(1 for ch in caption if "\u4e00" <= ch <= "\u9fff")
+    latin = len(caption) - cjk
+    # 0.75em is the measured upper bound for the latin part of the stack
+    # (Helvetica/Arial italic); ~2 full-width latin words at the start of the
+    # caption also shift the whole line right by the x=20 origin.
+    return int(cjk * font_size + latin * font_size * 0.78) + 60
+
+
 def _figure_svg(title: str, caption: str, body: str, w: int = 720, h: int = 300) -> str:
+    # Grow (never shrink) the canvas so the unwrapped caption fits instead of
+    # being cut off at the right edge; the body keeps its designed layout.
+    w = max(w, _caption_width(caption))
     return (f'<svg viewBox="0 0 {w} {h}" xmlns="http://www.w3.org/2000/svg" role="img" '
             f'aria-label="{_esc(caption)}">'
             f'<rect width="{w}" height="{h}" fill="#FFFFFF"/>'
@@ -337,8 +356,11 @@ def render_figures(figure_data: dict, theme: str = "okabe_ito", lang: str = "zh"
     # 绝不把 relation_to_claim 的 support/contradict 当作 outcome 好坏；计数轴整数刻度。)
     outcomes = figure_data.get("outcomes", [])
     if outcomes:
-        names = [zh_outcome(o["outcome_type"]) if lang == "zh"
-                 else o["outcome_type"] for o in outcomes]
+        # Both locales render a curated label. The English axis used to print
+        # the storage token ("knowledge_gain") because only zh went through
+        # OUTCOME_ZH; the English report then showed raw enum values as its
+        # headline comparison chart's axis.
+        names = [label(lang, "outcome", o["outcome_type"]) for o in outcomes]
         series = [{"name": s["name"],
                    "data": [o.get(s["data"], 0) for o in outcomes]}
                   for s in DIR_SERIES[lang]]