eduevidence 5.2.0 → 6.0.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/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")
 
 

package/engine/gaps.py

@@ -4,10 +4,15 @@ A KnowledgeGap is not free-form "future work": it is derived from coverage —
 the research frame's requested outcomes vs what the graph's Findings
 actually measure. A task-performance Finding never covers a retention or
 transfer gap.
+
+`gap_id` identifies one revision-local gap artifact. `extensions.autoresearch_key`
+is a stable semantic lineage key so bounded research memory survives graph
+revisions when the same unresolved gap is re-derived.
 """
 
 from __future__ import annotations
 
+import hashlib
 import json
 from pathlib import Path
 
@@ -16,23 +21,35 @@ from engine.graph_store import GraphStore
 from engine.ids import new_local_id
 from engine.synthesis import ClaimSynthesis
 
-# outcome_type names for timepoint-like gaps (frame.requested_outcomes entries
-# may carry outcome_type or be plain strings; we match on outcome_type)
 _RETENTION_TYPES = {"retention", "long_term", "learning_retention"}
 _TRANSFER_TYPES = {"transfer", "transfer_learning", "far_transfer"}
 _TASK_PERFORMANCE = {"task_performance", "assignment_score", "task_completion"}
 _LEARNING = {"learning"}
 
 
+def _autoresearch_key(
+    gap_type: str,
+    *,
+    related_claims: list[str],
+    related_outcomes: list[str],
+    semantic_token: str,
+) -> str:
+    payload = {
+        "gap_type": gap_type,
+        "related_claims": sorted(related_claims),
+        "related_outcomes": sorted(related_outcomes),
+        "semantic_token": semantic_token.strip().lower(),
+    }
+    digest = hashlib.sha256(
+        json.dumps(payload, sort_keys=True, ensure_ascii=False).encode("utf-8")
+    ).hexdigest()[:20]
+    return f"KGK-{digest}"
+
+
 def derive_gaps(*, store: GraphStore,
                 syntheses: tuple[ClaimSynthesis, ...] | None = None,
                 frame: dict | None = None) -> list[dict]:
-    """Derive structured gaps from graph coverage vs the research frame.
-
-    `frame` carries `requested_outcomes` (list of outcome names/types) and
-    optionally `target_population`. Findings' outcome types come from the
-    graph's outcomes table.
-    """
+    """Derive structured gaps from graph coverage vs the research frame."""
     frame = frame or {}
     requested = frame.get("requested_outcomes") or []
     if not requested and frame.get("target_outcomes"):
@@ -47,30 +64,34 @@ def derive_gaps(*, store: GraphStore,
             covered_types.add(o.get("outcome_type", ""))
 
     claims = store.read_table("claims")
-    claim_ids = [c["claim_id"] for c in claims]
-
     gaps: list[dict] = []
     rev = store.active_revision()
 
     def add(gap_type: str, priority: str, reasoning: str,
             related_claims: list[str] | None = None,
-            related_outcomes: list[str] | None = None):
+            related_outcomes: list[str] | None = None,
+            semantic_token: str = ""):
+        related_claims = related_claims or []
+        related_outcomes = related_outcomes or []
+        key = _autoresearch_key(
+            gap_type,
+            related_claims=related_claims,
+            related_outcomes=related_outcomes,
+            semantic_token=semantic_token or reasoning,
+        )
         gaps.append({
             "gap_id": new_local_id("GAP", {g["gap_id"] for g in gaps}),
             "gap_type": gap_type,
-            "related_claim_ids": related_claims or [],
-            "related_outcome_ids": related_outcomes or [],
+            "related_claim_ids": related_claims,
+            "related_outcome_ids": related_outcomes,
             "priority": priority,
             "reasoning": reasoning,
             "status": "open",
             "derived_from_graph_revision": rev,
-            "extensions": {},
+            "extensions": {"autoresearch_key": key},
         })
 
     def _req_kind(req) -> tuple[str, str]:
-        """Classify a requested outcome: retention | transfer |
-        task_performance | learning | other. Type-aware: names are matched
-        only within the outcome's declared type, never type-blind."""
         if isinstance(req, dict):
             req_name = str(req.get("name", "")).lower()
             req_type = str(req.get("outcome_type", "")).lower()
@@ -86,20 +107,17 @@ def derive_gaps(*, store: GraphStore,
             return "learning", req.get("name", "") if isinstance(req, dict) else str(req)
         return "other", req.get("name", "") if isinstance(req, dict) else str(req)
 
-    _RETENTION_COVER = _RETENTION_TYPES
-    _TRANSFER_COVER = _TRANSFER_TYPES
     def covered_for_kind(kind: str) -> bool:
         if kind == "retention":
-            return bool(covered_types & _RETENTION_COVER)
+            return bool(covered_types & _RETENTION_TYPES)
         if kind == "transfer":
-            return bool(covered_types & _TRANSFER_COVER)
+            return bool(covered_types & _TRANSFER_TYPES)
         if kind == "task_performance":
             return bool(covered_types & _TASK_PERFORMANCE)
         if kind == "learning":
             return bool(covered_types & _LEARNING)
         return False
 
-    # one pass per requested outcome; each gap emitted exactly once
     seen: set[tuple[str, str]] = set()
     for req in requested:
         kind, label = _req_kind(req)
@@ -112,49 +130,70 @@ def derive_gaps(*, store: GraphStore,
         if covered_for_kind(kind):
             continue
         if kind == "retention":
-            add("missing_retention", "high",
+            add(
+                "missing_retention", "high",
                 f"frame requests retention outcome {label!r} but the graph has "
-                f"no retention-type measurement; task-performance coverage does "
-                f"not count (RULE 3)")
+                "no retention-type measurement; task-performance coverage does "
+                "not count (RULE 3)",
+                semantic_token=f"requested_outcome:{label}",
+            )
         elif kind == "transfer":
-            add("missing_transfer", "high",
+            add(
+                "missing_transfer", "high",
                 f"frame requests transfer outcome {label!r} but the graph has "
-                f"no transfer-type measurement; AI-assisted task performance "
-                f"does not count (RULE 3)")
+                "no transfer-type measurement; AI-assisted task performance "
+                "does not count (RULE 3)",
+                semantic_token=f"requested_outcome:{label}",
+            )
         elif kind == "task_performance":
-            add("missing_outcome", "medium",
-                f"frame requests task-performance outcome {label!r} with no "
-                f"covering finding")
+            add(
+                "missing_outcome", "medium",
+                f"frame requests task-performance outcome {label!r} with no covering finding",
+                semantic_token=f"requested_outcome:{label}",
+            )
         elif kind == "learning":
-            add("missing_outcome", "medium",
-                f"frame requests learning outcome {label!r} with no covering "
-                f"learning finding; task performance is not learning (RULE 3)")
+            add(
+                "missing_outcome", "medium",
+                f"frame requests learning outcome {label!r} with no covering learning finding; "
+                "task performance is not learning (RULE 3)",
+                semantic_token=f"requested_outcome:{label}",
+            )
         else:
-            add("missing_outcome", "medium",
-                f"frame requests outcome {label!r} with no covering finding")
-    claim_outcomes = {c["claim_id"]: c.get("primary_outcome_ids", [])
-                      for c in claims}
+            add(
+                "missing_outcome", "medium",
+                f"frame requests outcome {label!r} with no covering finding",
+                semantic_token=f"requested_outcome:{label}",
+            )
+
+    claim_outcomes = {
+        c["claim_id"]: c.get("primary_outcome_ids", [])
+        for c in claims
+    }
 
-    # contradiction gaps
     for syn in syntheses or ():
         if syn.status == "contested":
-            add("unresolved_conflict", "high",
+            add(
+                "unresolved_conflict", "high",
                 f"claim {syn.claim_id} has independent contradictory studies "
-                f"({', '.join(syn.study_ids)})", [syn.claim_id],
-                claim_outcomes.get(syn.claim_id, []))
+                f"({', '.join(syn.study_ids)})",
+                [syn.claim_id],
+                claim_outcomes.get(syn.claim_id, []),
+                semantic_token=f"claim:{syn.claim_id}",
+            )
 
-    # methodology weakness / insufficient independence
     if syntheses:
         for syn in syntheses:
             if syn.status == "insufficient" and len(syn.study_ids) < 2:
-                add("insufficient_sample_independence", "medium",
-                    f"claim {syn.claim_id} rests on fewer than two independent "
-                    f"studies", [syn.claim_id],
-                    claim_outcomes.get(syn.claim_id, []))
-
-    # validate each gap
-    for g in gaps:
-        errors = validate_record("knowledge-gap", g)
+                add(
+                    "insufficient_sample_independence", "medium",
+                    f"claim {syn.claim_id} rests on fewer than two independent studies",
+                    [syn.claim_id],
+                    claim_outcomes.get(syn.claim_id, []),
+                    semantic_token=f"claim:{syn.claim_id}",
+                )
+
+    for gap in gaps:
+        errors = validate_record("knowledge-gap", gap)
         if errors:
             raise ValueError(f"invalid gap: {errors}")
     return gaps

package/engine/judge_pack.py

@@ -0,0 +1,65 @@
+"""Build a transparent, self-describing judge evidence pack from real artifacts."""
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from engine.project import ProjectWorkspace
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as fh:
+        for block in iter(lambda: fh.read(65536), b""):
+            h.update(block)
+    return h.hexdigest()
+
+
+def export_judge_pack(project: ProjectWorkspace, output_dir: Path) -> dict[str, Any]:
+    """Copy available project evidence without inventing unavailable claims.
+
+    The manifest lists every required judge-pack category and explicitly marks
+    missing inputs. This makes the pack suitable for review while keeping its
+    limits auditable.
+    """
+    output_dir = Path(output_dir).resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+    candidates = {
+        "project_manifest": project.path / "project.json",
+        "graph": project.path / "graph",
+        "runs": project.path / "runs",
+        "decisions": project.path / "decisions",
+        "projections": project.path / "projections",
+        "reports": project.path / "reports",
+        "pilots": project.path / "pilots",
+    }
+    copied: list[dict[str, str]] = []
+    missing: list[str] = []
+    for name, source in candidates.items():
+        target = output_dir / name
+        if source.is_file():
+            shutil.copy2(source, target)
+            copied.append({"name": name, "path": target.name, "sha256": _sha256(target)})
+        elif source.is_dir() and any(source.rglob("*")):
+            shutil.copytree(source, target, dirs_exist_ok=True)
+            for item in sorted(path for path in target.rglob("*") if path.is_file()):
+                copied.append({"name": name, "path": str(item.relative_to(output_dir)), "sha256": _sha256(item)})
+        else:
+            missing.append(name)
+    manifest = {
+        "format": "eduevidence-judge-pack/2026.09",
+        "project_id": project.project_id,
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "copied_files": copied,
+        "missing_categories": missing,
+        "limitations": [
+            "Only immutable/project-scoped artifacts available at export time are included.",
+            "Benchmark, blinded-review and usability evidence must be supplied from completed study artifacts; they are never synthesized by this export.",
+        ],
+    }
+    (output_dir / "manifest.json").write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    return manifest

package/engine/library_builtin.py

@@ -42,7 +42,9 @@ from functools import lru_cache
 from pathlib import Path
 from typing import Any
 
-ROOT = Path(__file__).resolve().parent.parent
+from engine._resources import resource_root
+
+ROOT = resource_root()
 def _resolve_library_path() -> Path:
     """Repository layout first; wheel-installed share/ layout as fallback."""
     repo = ROOT / "benchmarks" / "evidence-library.json"

package/engine/living.py

@@ -43,7 +43,8 @@ from scripts.validate_schema import SchemaError, validate
 def _resolve_v4_schema_dir() -> Path:
     """Repository layout first; wheel-installed share/ layout as fallback
     (same pattern as engine/contracts._resolve_schema_dir)."""
-    repo = Path(__file__).resolve().parent.parent / "schemas" / "v4"
+    from engine._resources import resource_root
+    repo = resource_root() / "schemas" / "v4"
     if repo.is_dir():
         return repo
     import sys

package/engine/meta_synthesis.py

@@ -21,7 +21,9 @@ from engine.ids import new_local_id
 from engine.library import ResearchLibrary
 from scripts.validate_schema import SchemaError, validate
 
-_SYNTHESIS_SCHEMA = (Path(__file__).resolve().parent.parent / "schemas" / "v3"
+from engine._resources import resource_root
+
+_SYNTHESIS_SCHEMA = (resource_root() / "schemas" / "v3"
                      / "synthesis.schema.json")