eduevidence 5.2.0 → 6.2.0

package/engine/autoresearch/research_memory.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+import json
+from pathlib import Path
+from typing import Any
+from .contracts import NegativeSearchRecord, ResearchIteration
+
+
+class ResearchMemory:
+    def __init__(self, root: str | Path):
+        self.root = Path(root)
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.iterations_path = self.root / "research-iterations.jsonl"
+        self.negative_path = self.root / "negative-searches.jsonl"
+
+    @staticmethod
+    def _append(path: Path, record: dict[str, Any]) -> None:
+        with path.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(record, ensure_ascii=False, sort_keys=True) + "\n")
+
+    def append_iteration(self, iteration: ResearchIteration) -> None:
+        iteration.validate()
+        self._append(self.iterations_path, iteration.as_dict())
+
+    def append_negative_search(self, record: NegativeSearchRecord) -> None:
+        record.validate()
+        self._append(self.negative_path, record.__dict__)
+
+    def load_iterations(
+        self,
+        gap_id: str | None = None,
+        *,
+        gap_lineage_key: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """Load iteration history, preferring stable lineage across revisions.
+
+        Legacy rows without `gap_lineage_key` remain queryable by `gap_id`.
+        When a lineage key is supplied, new keyed rows match by lineage and old
+        unkeyed rows may additionally match the supplied gap_id for migration.
+        """
+        if not self.iterations_path.exists():
+            return []
+        rows = [
+            json.loads(line)
+            for line in self.iterations_path.read_text(encoding="utf-8").splitlines()
+            if line.strip()
+        ]
+        if gap_lineage_key is not None:
+            return [
+                row for row in rows
+                if row.get("gap_lineage_key") == gap_lineage_key
+                or (
+                    not row.get("gap_lineage_key")
+                    and gap_id is not None
+                    and row.get("gap_id") == gap_id
+                )
+            ]
+        if gap_id is not None:
+            return [row for row in rows if row.get("gap_id") == gap_id]
+        return rows

package/engine/autoresearch/saturation.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class SaturationResult:
+    saturated: bool
+    low_yield_streak: int
+    strategy_diversity_exhausted: bool
+    rationale: tuple[str, ...]
+
+
+def _is_low_yield(row: dict[str, Any]) -> bool:
+    gain = row.get("evidence_gain") or {}
+    unique = int(gain.get("unique_eligible_evidence", 0) or 0)
+    direct = int(gain.get("direct_outcome_findings", 0) or 0)
+    delta = float(gain.get("decision_boundary_delta", 0) or 0)
+    duplicate_rate = float(gain.get("duplicate_rate", 0) or 0)
+    candidate_sources = row.get("candidate_sources") or []
+    no_candidates = len(candidate_sources) == 0
+    return (
+        unique == 0
+        and direct == 0
+        and abs(delta) < 1e-12
+        and (duplicate_rate >= 0.5 or no_candidates)
+    )
+
+
+def detect_saturation(
+    iterations: list[dict[str, Any]],
+    *,
+    min_consecutive: int = 2,
+    available_strategy_types: set[str] | None = None,
+) -> SaturationResult:
+    """Detect bounded secondary-search saturation.
+
+    Strategy diversity is computed across the full history for the gap, while
+    the low-yield condition is intentionally a trailing streak. Empty searches
+    count as low-yield even when duplicate_rate is zero; otherwise a provider
+    returning no candidates could keep the loop alive forever.
+    """
+    attempted_all = {
+        str((row.get("strategy") or {}).get("experiment_type", ""))
+        for row in iterations
+        if str((row.get("strategy") or {}).get("experiment_type", ""))
+    }
+    streak = 0
+    for row in reversed(iterations):
+        if _is_low_yield(row):
+            streak += 1
+        else:
+            break
+
+    if available_strategy_types:
+        diversity_exhausted = available_strategy_types.issubset(attempted_all)
+    else:
+        diversity_exhausted = len(attempted_all) >= 2
+
+    rationale: list[str] = []
+    if streak >= min_consecutive:
+        rationale.append(
+            f"{streak} consecutive iterations produced no unique/direct evidence or decision-boundary change"
+        )
+    if diversity_exhausted:
+        rationale.append("strategy diversity exhausted for the configured search space")
+    return SaturationResult(
+        streak >= min_consecutive and diversity_exhausted,
+        streak,
+        diversity_exhausted,
+        tuple(rationale),
+    )
+
+
+def transition_to_empirical(
+    *,
+    dvi_band: str,
+    decision_material: bool,
+    unresolved: bool,
+    saturation: SaturationResult,
+    ethics_feasible: bool,
+) -> tuple[bool, tuple[str, ...]]:
+    checks = [
+        (dvi_band.upper() == "HIGH", "gap DVI is HIGH"),
+        (decision_material, "gap is material to the decision"),
+        (unresolved, "gap remains unresolved"),
+        (saturation.saturated, "secondary search is saturated"),
+        (ethics_feasible, "empirical study is ethically/operationally feasible"),
+    ]
+    reasons = tuple(text for ok, text in checks if ok)
+    return all(ok for ok, _ in checks), reasons

package/engine/briefs.py

@@ -14,6 +14,7 @@ from pathlib import Path
 
 from engine.contracts import load_schema, schema_path
 from engine.planner import PlanStep
+from engine.project import ProjectWorkspace
 
 
 def _schema_section(schema: dict) -> str:
@@ -73,7 +74,7 @@ def build_task_brief(step: PlanStep, *, project: ProjectWorkspace,
         f"Validate the output with `engine.contracts.validate_record({schema_name!r}, record)` — "
         f"it must return [] (empty errors).",
         "",
-        f"## Output path",
+        "## Output path",
         str(output_path),
         "",
         "## Inputs",

package/engine/capabilities.py

@@ -18,6 +18,7 @@ class CapabilitySpec:
     output_contracts: tuple[str, ...]
     deterministic_local: bool
     scientific_gate: str | None
+    workflow_ids: tuple[str, ...] = ()
 
 
 _REGISTRY: dict[str, CapabilitySpec] = {}

package/engine/contracts.py

@@ -12,7 +12,9 @@ from typing import Callable
 
 from scripts.validate_schema import SchemaError, validate
 
-_REPO_SCHEMA_DIR = Path(__file__).resolve().parent.parent / "schemas" / "v2"
+from engine._resources import resource_root
+
+_REPO_SCHEMA_DIR = resource_root() / "schemas" / "v2"
 
 
 def _resolve_schema_dir() -> Path:

package/engine/decision_policy.py

@@ -0,0 +1,96 @@
+"""Single source of truth for the ADOPT direct-evidence gate.
+
+The four-state decision (ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE) is
+computed by two layers that must never drift apart:
+
+  * engine/tribunal.py - V2 Evidence Graph adjudication
+  * scripts/pre_verdict_gate.py - V1 run/example-pack gate enforcement
+
+Before this module existed the rule lived only inside the tribunal, so the V1
+gate could not enforce it and a hand-written verdict could carry any action it
+liked. Both layers now resolve the 'which outcome categories count for this
+domain' question here, and the V1 gate additionally re-derives direct-evidence
+presence from the pack's own evidence records.
+
+Stdlib only, consistent with the "Native Core" policy of engine/.
+"""
+from __future__ import annotations
+
+#: Category buckets that count as a domain's PRIMARY effect for the ADOPT gate.
+#: The gate asks 'is there direct evidence on the outcome this decision is
+#: actually about?' - for education that is a learning outcome (task
+#: performance and process measures never qualify); for policy it is the
+#: policy-effectiveness / cost class. Every entry must name a category the
+#: domain registry declares, which check_protocol_alignment.py enforces.
+PRIMARY_EFFECT_CATEGORIES: dict[str, tuple[str, ...]] = {
+    "education": ("learning",),
+    "policy": ("effectiveness", "cost"),
+}
+
+#: Directness (0-2) at which an evidence link may carry an ADOPT claim.
+ADOPT_DIRECTNESS = 2
+
+#: Confidence band required before ADOPT is possible at all.
+ADOPT_REQUIRED_LABEL = "High"
+
+
+def primary_effect_categories(domain: str) -> tuple[str, ...]:
+    """Categories that satisfy the ADOPT direct-evidence gate for a domain."""
+    from engine.taxonomy import categories as taxonomy_categories
+
+    declared = PRIMARY_EFFECT_CATEGORIES.get(domain)
+    if declared:
+        known = taxonomy_categories(domain)
+        missing = [c for c in declared if c not in known]
+        if missing:
+            raise ValueError(
+                'domain ' + repr(domain) + ' ADOPT gate references undeclared '
+                'categories ' + repr(missing) + '; declared: ' + repr(sorted(known)))
+        return declared
+    known = taxonomy_categories(domain)
+    if not known:
+        raise ValueError('domain ' + repr(domain) + ' declares no outcome categories')
+    return (next(iter(known)),)
+
+
+def outcome_category(domain: str, value: str, primary: tuple[str, ...]) -> str | None:
+    """Resolve an outcome value to its category, or None when unresolvable.
+
+    The outcomes table stores CATEGORY buckets (learning / task_performance /
+    process / risk, plus each domain's own buckets), while V1 packs store raw
+    taxonomy tokens. Accept a category directly and, for a token, resolve it
+    through the registry. An unknown value returns None so callers fail
+    closed instead of silently treating it as decision-grade evidence.
+    """
+    from engine.taxonomy import TaxonomyError, category_of
+
+    if value in primary:
+        return value
+    try:
+        return category_of(domain, value)
+    except (TaxonomyError, ValueError):
+        return None
+
+
+def decision_action(*, confidence_label: str, decisive_relations: dict[str, str],
+                    has_direct_primary_evidence: bool) -> str:
+    """Gate-enforced decision action (uppercase four-state).
+
+    REJECT requires usable direct opposition evidence (an independent Study
+    folded to oppose_adoption). Low/Insufficient can never yield ADOPT.
+    ADOPT additionally requires direct evidence on the domain's PRIMARY
+    outcome category: High + decisive support WITHOUT such evidence downgrades
+    to PILOT - task performance and procedural efficiency are not
+    decision-grade effects. Moderate + decisive support -> PILOT; otherwise
+    INSUFFICIENT_EVIDENCE.
+    """
+    has_oppose = any(r == "oppose_adoption" for r in decisive_relations.values())
+    has_support = any(r == "support_adoption" for r in decisive_relations.values())
+    if has_oppose:
+        return "REJECT"
+    if (confidence_label == ADOPT_REQUIRED_LABEL and has_support
+            and has_direct_primary_evidence):
+        return "ADOPT"
+    if confidence_label in ("High", "Moderate") and has_support:
+        return "PILOT"
+    return "INSUFFICIENT_EVIDENCE"

package/engine/evidence_graph.py

@@ -54,7 +54,11 @@ class EvidenceNode:
     outcome_dimension: str = OutcomeDimension.GENERAL_MEASURE
     claim_id: Optional[str] = None
     outcome_id: Optional[str] = None
-    effect_size: Dict[str, Any] = field(default_factory=lambda: {"metric": "Hedges g", "value": 0.0, "ci_lower": 0.0, "ci_upper": 0.0, "p_value": 0.05})
+    # A missing effect must stay missing: the old default fabricated a
+    # g = 0.0 with a p = 0.05, which would serialise as a real (and
+    # false) "no effect" result. Callers that need a number must supply
+    # one; the extractors already suppress charts when it is absent.
+    effect_size: Optional[Dict[str, Any]] = None
     sample_size: int = 0
     sample_description: str = ""
     study_design: str = "Quasi-Experimental"  # RCT, Quasi-Experimental DID, Meta-Analysis, Observational
@@ -292,9 +296,9 @@ class EvidenceGraph:
         for ev in self.evidence.values():
             paper = self.papers.get(ev.paper_id)
             study_label = f"{paper.authors[0] if paper and paper.authors else ev.paper_id} ({paper.year if paper else ''})"
-            effect_val = ev.effect_size.get("value", 0.0)
-            ci_l = ev.effect_size.get("ci_lower")
-            ci_u = ev.effect_size.get("ci_upper")
+            effect_val = (ev.effect_size or {}).get("value") or 0.0
+            ci_l = (ev.effect_size or {}).get("ci_lower")
+            ci_u = (ev.effect_size or {}).get("ci_upper")
             has_ci = ci_l is not None and ci_u is not None and float(ci_u) >= float(ci_l)
             points.append({
                 "evidence_id": ev.evidence_id,
@@ -327,13 +331,13 @@ class EvidenceGraph:
             precision_counts = {"reported_ci": 0, "derived_from_sample_size": 0}
             excluded_no_precision = 0
             for n in nodes:
-                eff = n.effect_size.get("value")
+                eff = (n.effect_size or {}).get("value")
                 if eff is None or math.isnan(float(eff)) or math.isinf(float(eff)):
                     continue
 
                 # Statistical variance derivation (Borenstein et al. 2009)
-                ci_l = n.effect_size.get("ci_lower")
-                ci_u = n.effect_size.get("ci_upper")
+                ci_l = (n.effect_size or {}).get("ci_lower")
+                ci_u = (n.effect_size or {}).get("ci_upper")
                 if ci_l is not None and ci_u is not None and float(ci_u) > float(ci_l):
                     se = (float(ci_u) - float(ci_l)) / (2.0 * 1.95996)
                     precision_counts["reported_ci"] += 1
@@ -422,7 +426,7 @@ class EvidenceGraph:
                 "quote": p.summary,
             })
         for ev in self.evidence.values():
-            effect_val = ev.effect_size.get("value", 0.0)
+            effect_val = (ev.effect_size or {}).get("value") or 0.0
             symbol_size = max(18, min(45, int(18 + abs(effect_val) * 20)))
             nodes.append({
                 "id": ev.evidence_id,
@@ -433,8 +437,8 @@ class EvidenceGraph:
                 "dimension": ev.outcome_dimension,
                 "direction": ev.direction,
                 "effect_size": effect_val,
-                "ci_lower": ev.effect_size.get("ci_lower", "N/A"),
-                "ci_upper": ev.effect_size.get("ci_upper", "N/A"),
+                "ci_lower": (ev.effect_size or {}).get("ci_lower", "N/A"),
+                "ci_upper": (ev.effect_size or {}).get("ci_upper", "N/A"),
                 "sample_size": ev.sample_size,
                 "wwc_rating": ev.wwc_rating,
                 "quote": ev.key_quote,

package/engine/evidencecore.py

@@ -12,8 +12,7 @@ v4 领域包机制：domains/ 注册表 + 领域契约加载 + frame 校验。
 education 域只是"指向现有契约"的注册：不新增任何逻辑路径、不引入新 schema
 或新校验器。领域选择（domain select）由主 agent 接 CLI 完成，引擎层不做选择。
 
-路径解析：当前按仓库布局（domains/ 在仓库根目录）解析；wheel 安装场景的
-share/ 回退留给后续步骤（pyproject data-files 未包含 domains/）。
+路径解析：支持仓库、独立 Skill 与 wheel 的 share/eduevidence 资源布局。
 """
 
 from __future__ import annotations
@@ -22,7 +21,9 @@ import json
 from pathlib import Path
 from typing import Any
 
-REPO_ROOT = Path(__file__).resolve().parent.parent
+from engine._resources import resource_root
+
+REPO_ROOT = resource_root()
 
 
 def _resolve_domains_dir() -> Path:
@@ -114,7 +115,7 @@ def _validate_contracts(entry: dict) -> None:
 
     - frame_schema / outcome_taxonomy / methodology_checklist：文件存在且
       为可解析 JSON（指针引用另校验指针内容）；
-    - golds_dir / references_dir：目录存在（null 视为"无此契约"，跳过）。
+    - references_dir：目录存在；golds_dir 属于独立 evaluator 资源，不是研究运行依赖。
     """
     domain_id = entry["id"]
 
@@ -142,7 +143,8 @@ def _validate_contracts(entry: dict) -> None:
     check_file("frame_schema")
     check_file("outcome_taxonomy")
     check_file("methodology_checklist")
-    check_dir("golds_dir")
+    # Evaluation annotations (including holdout answers) are intentionally absent
+    # from shipped Skills. Benchmark consumers validate their own input corpus.
     check_dir("references_dir")