eduevidence 5.2.0 → 6.0.0

package/install.sh

@@ -28,7 +28,7 @@ REPO_URL="https://github.com/37chengshan/eduevidence"
 SKILL_NAME="eduevidence"
 # Skill 本体（运行协议 + 确定性脚本 + 检索/集成层 + 展示层）。
 # retrieval/ 与 integrations/ 会被 scripts/ 直接 import；visualization/ 负责最终 HTML 渲染。
-SKILL_PAYLOAD=(SKILL.md engine domains skill references schemas scripts retrieval integrations visualization)
+SKILL_PAYLOAD=(SKILL.md agents engine domains skill references schemas scripts retrieval integrations visualization web examples docs autoevolve eduevidence_cli.py)
 # Agent MCP 声明文件：安装完成后写入 AGENT_MCP_INSTALLED=1，供
 # integrations/agent_mcp.py 作为 env 后备来源读取（真实环境变量优先于该文件）。
 AGENT_MCP_ENV_FILE="${AGENT_MCP_ENV_FILE:-$HOME/.eduevidence/env}"
@@ -149,7 +149,7 @@ host_skill_root() {
 
 # ---------- 通用提示词（方式三：宿主不在支持列表时交给任意 AI） ----------
 UNIVERSAL_PROMPT="请把 https://github.com/37chengshan/eduevidence 仓库中的 EduEvidence 安装为 skill：
-1. 将仓库根目录的 SKILL.md、skill/、references/、schemas/、scripts/、retrieval/、integrations/、visualization/ 复制到你的 skill 目录
+1. 将仓库根目录的 完整分发目录（含 SKILL.md、engine/、domains/、skill/、schemas/、scripts/、web/studio/ 等）复制到你的 skill 目录
    （如 ~/.claude/skills/eduevidence/、~/.omp/agent/skills/eduevidence/、~/.agents/skills/eduevidence/ 等），
    或按你的 skill 装载机制导入；
 2. 安装完成后确认能读取 SKILL.md，并能运行 scripts/ 下的确定性脚本；
@@ -268,13 +268,13 @@ local_setup() {
     # 5. 自检：Schema 校验 + 报告渲染
     echo "==> 自检：Schema 校验"
     python scripts/validate_schema.py --schema schemas/verdict.schema.json \
-        --data examples/ai-coding-assistant/verdict.json
+        --data examples/ai-coding-assistant-evidence/verdict.json
     python scripts/validate_schema.py --schema schemas/evidence.schema.json \
-        --data examples/ai-coding-assistant/evidence.jsonl
+        --data examples/ai-coding-assistant-evidence/evidence.jsonl
 
     echo "==> 自检：渲染双语 HTML 报告"
     python visualization/eduevidence-report/scripts/build_report.py \
-        --result examples/ai-coding-assistant/result.json \
+        --result examples/ai-coding-assistant-evidence/result.json \
         --out /tmp/eduevidence-smoke.html
     rm -f /tmp/eduevidence-smoke.html
 
@@ -291,7 +291,7 @@ local_setup() {
 local_finish() {
     echo ""
     echo "安装完成。下一步："
-    echo "  1. 查看示例报告:  open examples/ai-coding-assistant/EduEvidence_Report.html"
+    echo "  1. 查看示例报告:  open examples/ai-coding-assistant-evidence/EduEvidence_Report.html"
     echo "  2. 渲染自己的 result.json（需同时准备 result.zh.json 中文平行数据）:"
     echo "     python visualization/eduevidence-report/scripts/build_report.py \\"
     echo "         --result <你的 result.json> --out REPORT.html"
@@ -315,7 +315,7 @@ install_to_dir() {
         rm -rf "$dest"
     fi
     mkdir -p "$dest"
-    cp -R "${SKILL_PAYLOAD[@]}" "$dest"/
+    python3 scripts/skill_payload.py "$PWD" "$dest"
     echo "    ✅ 已安装: $dest"
 }
 

package/integrations/orchestration_dispatch.py

@@ -0,0 +1,146 @@
+"""TaskSpec-aware dispatch and acceptance adapter for Agent MCP.
+
+Agent MCP remains the only implementation of CLI/model approval and spawn
+payload construction. EduEvidence adds two scientific contract gates around
+it:
+
+1. every delegated worker must carry a dispatch-ready TaskSpec;
+2. every returned worker payload must be reconstructed and validated in the
+   main process before any artifact can enter Judge context.
+
+Workers are staging-only. Raw host output is never a Judge input.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from engine.orchestration import ExecutionMode, TaskSpec
+from engine.worker_result import (
+    ArtifactValidator,
+    WorkerResult,
+    require_validated_artifacts_for_judge,
+    validate_worker_output,
+)
+from integrations.agent_mcp import safe_spawn
+
+
+TASKSPEC_REQUIRED = "TASKSPEC_REQUIRED"
+TASKSPEC_INVALID = "TASKSPEC_INVALID"
+WORKER_OUTPUT_REJECTED = "WORKER_OUTPUT_REJECTED"
+HostExecutor = Callable[[dict[str, Any]], dict[str, Any]]
+
+
+def dispatch_task(
+    task: TaskSpec,
+    prompt: str,
+    approval: dict[str, Any] | None,
+    *,
+    target_cli: str | None = None,
+    model: str | None = None,
+    allowed_clis: list[str] | None = None,
+    cwd: str = ".",
+    permission_mode: str = "plan",
+    context_mode: str = "compact",
+    summary_chars: int | None = None,
+) -> dict[str, Any]:
+    """Validate a dispatch-ready TaskSpec, then pass it through safe_spawn()."""
+    if not isinstance(task, TaskSpec):
+        return {
+            "status": TASKSPEC_REQUIRED,
+            "spawn_call": None,
+            "reason": "subagent dispatch requires a TaskSpec",
+        }
+    try:
+        task.validate_for_dispatch()
+    except ValueError as exc:
+        return {
+            "status": TASKSPEC_INVALID,
+            "spawn_call": None,
+            "reason": str(exc),
+        }
+    if task.execution_mode is not ExecutionMode.DELEGATED:
+        return {
+            "status": TASKSPEC_INVALID,
+            "spawn_call": None,
+            "reason": "only delegated TaskSpecs may be sent to Agent MCP",
+        }
+
+    worker_prompt = f"{task.to_prompt_contract()}\n\nWORKER INSTRUCTIONS:\n{prompt.strip()}"
+    result = safe_spawn(
+        task.role,
+        worker_prompt,
+        approval,
+        target_cli=target_cli,
+        model=model,
+        allowed_clis=allowed_clis,
+        cwd=cwd,
+        permission_mode=permission_mode,
+        context_mode=context_mode,
+        summary_chars=summary_chars,
+        timeout_seconds=task.timeout_seconds,
+        token_budget=task.token_budget,
+    )
+    if result.get("status") == "READY":
+        result["task_id"] = task.task_id
+        result["run_id"] = task.run_id
+        result["base_revision"] = task.base_revision
+        result["stage"] = task.stage
+        result["evidence_axis"] = task.evidence_axis
+        result["allowed_capabilities"] = list(task.allowed_capabilities)
+        result["expected_staging_outputs"] = list(task.expected_outputs)
+        result["output_contract"] = dict(task.output_contract)
+    return result
+
+
+def accept_worker_output(
+    task: TaskSpec,
+    raw_output: dict[str, Any],
+    *,
+    artifact_validator: ArtifactValidator | None = None,
+) -> WorkerResult:
+    """Main-process acceptance boundary for host/Agent-MCP worker output.
+
+    Worker self-attestation is ignored by `validate_worker_output`. Callers must
+    retain the originating TaskSpec and validate against that exact contract.
+    """
+    return validate_worker_output(
+        task,
+        raw_output,
+        artifact_validator=artifact_validator,
+    )
+
+
+def execute_dispatched_task(
+    task: TaskSpec,
+    dispatch_result: dict[str, Any],
+    host_executor: HostExecutor,
+    *,
+    artifact_validator: ArtifactValidator | None = None,
+) -> WorkerResult:
+    """Execute one READY spawn call and immediately pass through acceptance.
+
+    This is the conformant host adapter. It intentionally does not expose a
+    helper that returns raw worker artifacts after execution.
+    """
+    if dispatch_result.get("status") != "READY":
+        raise PermissionError("cannot execute a dispatch result that is not READY")
+    if dispatch_result.get("task_id") != task.task_id:
+        raise ValueError("dispatch result task_id does not match TaskSpec")
+    spawn_call = dispatch_result.get("spawn_call")
+    if not isinstance(spawn_call, dict):
+        raise ValueError("READY dispatch result must contain one spawn_call object")
+    raw = host_executor(dict(spawn_call))
+    if not isinstance(raw, dict):
+        raise ValueError("host executor must return one worker output object")
+    return accept_worker_output(
+        task,
+        raw,
+        artifact_validator=artifact_validator,
+    )
+
+
+def judge_artifacts(
+    results: list[WorkerResult] | tuple[WorkerResult, ...],
+) -> list[dict[str, Any]]:
+    """Return Judge inputs only when every worker result passed acceptance."""
+    return require_validated_artifacts_for_judge(results)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "eduevidence",
-  "version": "5.2.0",
-  "description": "Evidence-Based Education Decision Skill — from any education question to an auditable, evidence-grounded decision.",
+  "version": "6.0.0",
+  "description": "Evidence research and decision skill with education and organizational policy domains.",
   "license": "MIT",
   "author": "EduEvidence Contributors",
   "homepage": "https://github.com/37chengshan/eduevidence#readme",
@@ -42,9 +42,43 @@
     "scripts/",
     "retrieval/",
     "integrations/",
-    "visualization/eduevidence-report/"
+    "visualization/eduevidence-report/",
+    "agents/",
+    "web/studio/",
+    "web/index.html",
+    "autoevolve/config.yaml",
+    "autoevolve/program.md",
+    "autoevolve/protected.manifest.yaml",
+    "setup.py",
+    "docs/architecture.md",
+    "docs/install-guide.md",
+    "docs/release-contract.md",
+    "docs/research-studio-guide.zh-CN.md",
+    "docs/autoresearch-evolution-plan.md",
+    "docs/orchestration-role-model.md",
+    "docs/autoresearch-implementation-status.md",
+    "benchmarks/evidence-library.json",
+    "benchmarks/partitions.json",
+    "benchmarks/adversarial/cases.jsonl",
+    "examples/ai-coding-assistant-evidence/*.json",
+    "examples/ai-coding-assistant-evidence/*.jsonl",
+    "examples/ai-coding-assistant-evidence/*.html",
+    "examples/ai-coding-assistant-evidence/reports-5themes/*.html",
+    "examples/workplace-ai-assistant/*.json",
+    "examples/workplace-ai-assistant/*.jsonl",
+    "examples/workplace-ai-assistant/*.html",
+    "examples/workplace-ai-assistant/reports-5themes/*.html",
+    "docs/demo-workplace-ai.md",
+    "docs/demo.md",
+    "docs/demo-storyboard.md",
+    "docs/release-closeout/*.md",
+    "assets/readme/"
   ],
   "engines": {
     "node": ">=18"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
   }
 }

package/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "eduevidence"
-version = "5.2.0"
-description = "Evidence-Based Education Decision Skill — from any education question (teaching methods, curriculum, assessment, learning interventions, AI tools) to an evidence-based decision."
+version = "6.0.0"
+description = "Evidence research and decision skill with education and organizational policy domains."
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "MIT" }
@@ -24,32 +24,23 @@ dev = ["pytest>=7.0"]
 eduevidence = "eduevidence_cli:main"
 
 [tool.pytest.ini_options]
-# scripts/ 只为收编历史遗留的红队压测 scripts/test_adversarial_empirical.py
-# （E5：该文件是全仓唯一 test_*.py 命名的脚本，纳入默认收集后不再"死测试"）。
 testpaths = ["tests", "scripts"]
 python_files = ["test_*.py"]
 addopts = "-q"
 filterwarnings = ["ignore::pytest.PytestReturnNotNoneWarning:scripts.*"]
 
-# wheel 自包含 CLI：eduevidence_cli + engine + scripts（V1/V2 命令实现与
-# validate_schema）+ schemas 数据文件（data-files 安装到 share/eduevidence/，
-# engine.contracts / orchestrator 按回退路径解析）。Skill 本体（SKILL.md +
-# skill/ + references/ + retrieval/ + integrations/ + visualization/ +
-# assets/）由 install.sh 或源码包完整分发。
 [tool.setuptools]
 py-modules = ["eduevidence_cli"]
-packages = ["engine", "scripts"]
 
-[tool.setuptools.data-files]
-"share/eduevidence/schemas" = ["schemas/*.json"]
-"share/eduevidence/schemas/v2" = ["schemas/v2/*.json"]
-"share/eduevidence/schemas/v3" = ["schemas/v3/*.json"]
-"share/eduevidence/schemas/v4" = ["schemas/v4/*.json"]
-"share/eduevidence/domains" = ["domains/manifest.json", "domains/education/manifest.json", "domains/education/outcome_taxonomy.json", "domains/policy/manifest.json", "domains/policy/frame.schema.json", "domains/policy/outcome_taxonomy.json", "domains/policy/methodology_checklist.json"]
-"share/eduevidence/domains/policy/references" = ["domains/policy/references/*.md"]
-"share/eduevidence/benchmarks" = ["benchmarks/evidence-library.json"]
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["engine*", "scripts*", "retrieval*", "integrations*"]
 
 [tool.ruff.lint]
-# E5 最小守门集：语法层错误 + 未定义/重定义名。风格类规则不设（存量代码
-# 不做一次性大规模格式化，避免淹没 review）。
 select = ["E9", "F63", "F7", "F82"]
+
+[tool.ruff.lint.per-file-ignores]
+# build_report.py enables postponed annotations; its legacy Optional annotation
+# is not evaluated at runtime. Keep this F821 exception narrowly scoped rather
+# than weakening undefined-name checks for the repository.
+"visualization/eduevidence-report/scripts/build_report.py" = ["F821"]

package/references/autoresearch.md

@@ -0,0 +1,30 @@
+# Evidence Autoresearch
+
+Use this reference for bounded autonomous evidence acquisition inside an existing EduEvidence Project.
+
+## Loop
+
+`GraphRevision + DecisionSnapshot + KnowledgeGaps → rank DVI → choose ONE gap → ONE falsifiable strategy → bounded execution → validate staging evidence → single-writer graph commit or no-gain log → re-adjudicate → next gap`.
+
+## Hard rules
+
+- A KnowledgeGap must already be grounded in the Evidence Graph.
+- DVI is an ordinal HIGH/MEDIUM/LOW prioritization heuristic, never EVPI/EVSI or a probability.
+- Run one primary research hypothesis per ResearchIteration.
+- Validated evidence is append-only whether supportive, contradictory, neutral, or null.
+- A no-gain iteration creates ResearchIteration memory but no GraphRevision.
+- Negative search results may only state that no eligible evidence was found within the recorded search scope.
+- Stop on resolved gap, loss of decision sensitivity, budget exhaustion, saturation, tool blockage, user stop, or need for new empirical evidence.
+- Literature → Pilot requires HIGH DVI + decision materiality + unresolved gap + search saturation + ethical/operational feasibility.
+- New decision outputs created by autonomous refresh remain candidate decisions until an appropriate human/review gate accepts them.
+
+## CLI
+
+```text
+eduevidence research auto step --project <id>
+eduevidence research auto step --project <id> --outcome-file <validated-staging.json>
+eduevidence research auto status --project <id>
+eduevidence research auto stop --project <id>
+```
+
+Without an execution artifact, `step` emits the selected GapPriority and ResearchStrategy and stops at `awaiting_execution`; it never fabricates search results.

package/references/evaluation-policy.md

@@ -0,0 +1,24 @@
+# Skill Autoresearch Evaluation Policy
+
+Evaluate candidate EduEvidence implementations with **constraint-first Pareto evaluation**, never a single LLM score.
+
+## Order
+
+1. **L0 hard gates** — schema validity, provenance, graph integrity, study identity, no false precision, no unsupported ADOPT, synthetic/real separation, grounded gaps, protected integrity, privacy. Any failure = REJECT.
+2. **L1 scientific correctness** — outcome separation, citation support, contradiction precision/recall, scope/decision calibration, methodology issue detection, gap correctness. Material regression = REJECT.
+3. **L2 research quality** — direct evidence gain, unique eligible evidence yield, counter-evidence yield, applicability coverage, gap-resolution and saturation efficiency.
+4. **L3 robustness** — S/M/L, domains, model families, repeated runs, provider variation, missing/adversarial conditions.
+5. **L4 efficiency** — token, cost, latency, search/fetch calls, subagent count, parallel speedup.
+6. **L5 simplicity** — LOC, loaded Skill context, branches, dependencies, maintenance surface. Equal evidence quality prefers the simpler candidate.
+
+## Promotion
+
+- Hard gate fail or scientific regression → `REJECT`.
+- Candidate improvement within empirical noise → `RETEST`.
+- Material quality improvement without core regression → `KEEP`.
+- Real Pareto trade-off → `HUMAN_REVIEW`.
+- Protected mutation → `INVALID` before scoring.
+
+Use at least 3 repeated empirical runs, preferably 5, for stochastic model evaluation. DEV is visible to candidate experiments. HOLDOUT and ADVERSARIAL are evaluator-only promotion inputs. Temporal evaluation is timestamped and not permanent gold.
+
+Skill Autoresearch operates only on fixture/benchmark research state and an `autoresearch/<run-tag>` branch/worktree. It never changes real user evidence state, merges main, releases, deploys, or launches a human-subject study automatically.

package/references/orchestration.md

@@ -0,0 +1,22 @@
+# Orchestration
+
+Treat these concepts as distinct:
+
+`Protocol Stage ≠ Scientific Role ≠ Capability ≠ Worker/Subagent ≠ Model/CLI`.
+
+A Scientific Role is an accountability boundary. It does not imply a permanent agent. A Capability is reusable implementation. A Worker/Subagent is a temporary execution instance. Model/CLI selection is an execution adapter governed by existing user approval.
+
+## Default topology
+
+- **S**: lead-only, zero delegated workers.
+- **M**: selectively delegate independent direct/counter evidence acquisition and, when useful, an independent Skeptic.
+- **L**: split retrieval by evidence axis (direct causal; transfer/retention; null/negative/risk; applicability/freshness), then deterministic merge, optional independent Skeptic/Method Reviewer, single-writer commit, Judge, and high-impact independent final review.
+- Hard parallel cap: 6. Never recursive swarm.
+
+## TaskSpec and dispatch
+
+Every delegated worker requires a validated TaskSpec. Workers are read-only against canonical project state and return staging artifacts only. Agent MCP delegation must pass through the TaskSpec dispatch adapter and the existing `safe_spawn()` approval gate. Do not route by provider name; providers are tools, while evidence axes are epistemic objectives.
+
+## Single Writer
+
+Parallelize independent evidence acquisition and analysis; serialize canonical state transitions. Only the lead/single-writer path may commit GraphRevision, DecisionSnapshot, persistent KnowledgeGap state, StudyDesign, PilotRun, or AnalysisRun. Judges consume validated artifacts, never unvalidated worker prose.

package/references/scientific-invariants.md

@@ -0,0 +1,19 @@
+# EduEvidence Scientific Invariants
+
+These rules are protected scientific constraints. Autoresearch may optimize the research process, but must never optimize the evidence set toward a preferred conclusion.
+
+1. **Optimize for decision integrity, not answer confidence.**
+2. **Optimize the research process, never the conclusion.**
+3. **Every iteration must improve the evidence state, improve the research system, or teach why an attempted path failed.**
+4. Validated evidence is append-only regardless of whether it supports, contradicts, is null, or is neutral toward the current decision.
+5. Search snippets are discovery metadata, never direct evidence.
+6. Task performance is not learning; direct learning/retention/independent-transfer evidence is required before ADOPT for education interventions.
+7. Missing uncertainty statistics must never be fabricated.
+8. Causal estimators fail closed on invalid or unidentified designs.
+9. StudyDesign requires an explicit evidence-grounded KnowledgeGap.
+10. Negative search results describe the bounded search scope only; never infer that evidence does not exist globally.
+11. Evidence Autoresearch may update project research state but may not modify Skill/repository code.
+12. Skill Autoresearch may modify approved mutable repository surfaces but may not touch real user research state.
+13. Holdout/gold/evaluator/schema/scientific-invariant surfaces are protected from automatic mutation.
+14. Canonical project state has a single writer. Subagents return staging artifacts only.
+15. No autonomous human-subject study launch, policy deployment, main-branch merge, or release.

package/retrieval/audit.py

@@ -0,0 +1,154 @@
+"""Auditable, bounded search execution for evidence retrieval.
+
+Provider implementations remain deliberately separate. This module records
+the query intent, every provider attempt, screening decisions and saturation
+stop reason so a search result is never mistaken for unobserved provenance.
+"""
+from __future__ import annotations
+
+import csv
+import json
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Iterable
+
+from retrieval.search import SearchHit
+from retrieval.source import parse_doi_from_url, title_fingerprint
+
+
+@dataclass(frozen=True)
+class SearchQuery:
+    query_id: str
+    query: str
+    purpose: str  # core | expansion | counter_evidence | citation_chain
+
+
+@dataclass(frozen=True)
+class SearchPlan:
+    question: str
+    domain: str
+    concepts: tuple[str, ...]
+    synonyms: tuple[str, ...]
+    inclusion_criteria: tuple[str, ...]
+    exclusion_criteria: tuple[str, ...]
+    queries: tuple[SearchQuery, ...]
+    provider_budget: int = 10
+    policy_version: str = "2026.09"
+
+    @classmethod
+    def from_question(cls, question: str, *, domain: str = "education",
+                      concepts: Iterable[str] = (), synonyms: Iterable[str] = ()) -> "SearchPlan":
+        terms = tuple(dict.fromkeys(x.strip() for x in (*concepts, *synonyms) if x.strip()))
+        core = " ".join(terms) or question
+        return cls(question, domain, tuple(concepts), tuple(synonyms), (), (), (
+            SearchQuery("Q1", core, "core"),
+            SearchQuery("Q2", f"{core} systematic review OR meta-analysis", "expansion"),
+            SearchQuery("Q3", f"{core} null negative harm bias limitation", "counter_evidence"),
+        ))
+
+
+@dataclass
+class SearchAttempt:
+    attempt_id: str
+    query_id: str
+    provider: str
+    started_at: float
+    ended_at: float
+    status: str
+    result_count: int
+    error: str = ""
+    retry_index: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        value = asdict(self)
+        value["latency_ms"] = round((self.ended_at - self.started_at) * 1000, 2)
+        return value
+
+
+def _hit_key(hit: SearchHit) -> tuple[str, str, str]:
+    doi = (hit.doi or parse_doi_from_url(hit.url) or "").lower()
+    return doi, hit.url.rstrip("/").lower(), title_fingerprint(hit.title)
+
+
+def dedupe_hits(hits: Iterable[SearchHit]) -> list[SearchHit]:
+    """Deduplicate DOI, canonical URL and normalized title, retaining priority."""
+    seen: set[tuple[str, str]] = set()
+    kept: list[SearchHit] = []
+    for hit in sorted(hits, key=lambda item: (item.score, item.citation_count or 0), reverse=True):
+        doi, url, title = _hit_key(hit)
+        keys = [("doi", doi), ("url", url), ("title", title)]
+        nonempty = [key for key in keys if key[1]]
+        if any(key in seen for key in nonempty):
+            continue
+        seen.update(nonempty)
+        kept.append(hit)
+    return kept
+
+
+class AuditedSearchExecutor:
+    """Runs an explicit plan with bounded retries and durable audit exports."""
+
+    def __init__(self, providers: Iterable[Any], *, max_retries: int = 1):
+        self.providers = list(providers)
+        self.max_retries = max_retries
+
+    def execute(self, plan: SearchPlan, output_dir: Path, *, limit: int = 10) -> list[SearchHit]:
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+        attempts: list[SearchAttempt] = []
+        hits: list[SearchHit] = []
+        attempted: set[tuple[str, str]] = set()
+        counter_hits = 0
+        for query in plan.queries:
+            for provider in self.providers:
+                name = getattr(provider, "name", provider.__class__.__name__)
+                fingerprint = (name, query.query)
+                if fingerprint in attempted:
+                    continue
+                attempted.add(fingerprint)
+                for retry in range(self.max_retries + 1):
+                    started = time.time()
+                    try:
+                        result = provider.search(query.query, limit=limit)
+                        ended = time.time()
+                        attempts.append(SearchAttempt(
+                            f"A-{len(attempts) + 1:04d}", query.query_id, name, started, ended,
+                            "success", len(result), retry_index=retry,
+                        ))
+                        hits.extend(result)
+                        if query.purpose == "counter_evidence":
+                            counter_hits += len(result)
+                        break
+                    except Exception as exc:  # failures are recorded, never swallowed
+                        ended = time.time()
+                        attempts.append(SearchAttempt(
+                            f"A-{len(attempts) + 1:04d}", query.query_id, name, started, ended,
+                            "failed", 0, error=f"{type(exc).__name__}: {exc}", retry_index=retry,
+                        ))
+        unique = dedupe_hits(hits)
+        self._write_exports(output_dir, plan, attempts, unique, counter_hits)
+        return unique[:limit]
+
+    @staticmethod
+    def _write_exports(output_dir: Path, plan: SearchPlan, attempts: list[SearchAttempt],
+                       hits: list[SearchHit], counter_hits: int) -> None:
+        (output_dir / "search-provenance.json").write_text(json.dumps({
+            "plan": {**asdict(plan), "queries": [asdict(q) for q in plan.queries]},
+            "search_completed": True,
+            "counter_evidence_queries_executed": sum(q.purpose == "counter_evidence" for q in plan.queries),
+            "counter_evidence_hit_count": counter_hits,
+            "stop_reason": "planned_queries_completed",
+        }, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        (output_dir / "search-attempts.jsonl").write_text(
+            "".join(json.dumps(item.to_dict(), ensure_ascii=False) + "\n" for item in attempts), encoding="utf-8")
+        with (output_dir / "source-screening.csv").open("w", newline="", encoding="utf-8") as fh:
+            writer = csv.DictWriter(fh, fieldnames=["title", "doi", "url", "provider", "year", "screening_status", "reason"])
+            writer.writeheader()
+            for hit in hits:
+                writer.writerow({"title": hit.title, "doi": hit.doi or parse_doi_from_url(hit.url) or "", "url": hit.url,
+                                 "provider": hit.provider, "year": hit.year or "", "screening_status": "candidate",
+                                 "reason": "discovery metadata only; fetch and validation required before evidence extraction"})
+        with (output_dir / "exclusion-log.csv").open("w", newline="", encoding="utf-8") as fh:
+            writer = csv.DictWriter(fh, fieldnames=["identifier", "reason"])
+            writer.writeheader()