eduevidence 5.2.0

package/engine/evidencecore.py

@@ -0,0 +1,182 @@
+"""engine/evidencecore.py - EvidenceCore v4 domain registry (抽象第一步).
+
+v4 领域包机制：domains/ 注册表 + 领域契约加载 + frame 校验。
+
+- 领域无关常量：DECISION_STATES（四态决策）、PROTOCOL_STEPS（9 步协议）。
+- list_domains()：按注册表顺序列出领域。
+- load_domain(domain_id)：读取并校验领域条目——所有引用契约必须真实存在。
+- validate_frame(domain_id, frame_dict)：用该领域的 frame schema 校验
+  frame（education 复用现有 scripts.validate_schema 校验
+  schemas/education-frame.schema.json；policy 用 domains/policy/frame.schema.json）。
+
+education 域只是"指向现有契约"的注册：不新增任何逻辑路径、不引入新 schema
+或新校验器。领域选择（domain select）由主 agent 接 CLI 完成，引擎层不做选择。
+
+路径解析：当前按仓库布局（domains/ 在仓库根目录）解析；wheel 安装场景的
+share/ 回退留给后续步骤（pyproject data-files 未包含 domains/）。
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+
+def _resolve_domains_dir() -> Path:
+    """Repository layout first; wheel-installed share/ layout as fallback."""
+    repo = REPO_ROOT / "domains"
+    if repo.is_dir():
+        return repo
+    import sys
+    share = Path(sys.prefix) / "share" / "eduevidence" / "domains"
+    if share.is_dir():
+        return share
+    return repo
+
+
+DOMAINS_DIR = _resolve_domains_dir()
+REGISTRY_FILE = DOMAINS_DIR / "manifest.json"
+
+#: 领域无关：四态决策（README: ADOPT / PILOT / REJECT / INSUFFICIENT EVIDENCE）。
+DECISION_STATES = ("adopt", "pilot", "reject", "insufficient_evidence")
+
+#: 领域无关：9 步 EvidenceFlow 协议（SKILL.md Research Core 6 + Decision Extension 3）。
+PROTOCOL_STEPS = (
+    "Frame", "Retrieve", "Extract", "Challenge", "Audit",
+    "Adjudicate", "Applicability", "Intervene", "Evaluate",
+)
+
+#: 注册表条目必备字段（domains/manifest.json）。
+REQUIRED_REGISTRY_FIELDS = (
+    "id", "name", "description", "frame_schema", "outcome_taxonomy",
+    "methodology_checklist", "golds_dir", "references_dir",
+)
+
+_cache: dict[str, Any] = {}
+
+
+def _load_registry() -> dict:
+    """读取（缓存）domains/manifest.json 注册表。"""
+    if "_registry" not in _cache:
+        _cache["_registry"] = json.loads(
+            REGISTRY_FILE.read_text(encoding="utf-8"))
+    return _cache["_registry"]
+
+
+def list_domains() -> list[dict]:
+    """按注册表顺序返回全部领域条目（id/name/description/契约引用）。"""
+    return list(_load_registry()["domains"])
+
+
+def _field_target(entry: dict, field: str) -> Path | None:
+    """把注册表路径字段解析为仓库内路径。
+
+    JSON Pointer 引用（"file.json#/pointer"）取文件本体路径；
+    指针指向的内容由 _check_pointer 另行校验。None 表示该字段
+    明确为 null（可选契约，如 policy 的 golds_dir）。
+    """
+    raw = entry.get(field)
+    if raw is None:
+        return None
+    return REPO_ROOT / str(raw).partition("#")[0]
+
+
+def _check_pointer(entry: dict, field: str) -> None:
+    """校验 "file.json#/pointer" 引用：文件存在且指针可解析为非空列表。"""
+    raw = str(entry[field])
+    path_text, _, pointer = raw.partition("#")
+    if not pointer:
+        return
+    target = REPO_ROOT / path_text
+    if not target.is_file():
+        raise FileNotFoundError(
+            f"domain {entry['id']!r}: {field} file missing: {target}")
+    node: Any = json.loads(target.read_text(encoding="utf-8"))
+    for part in pointer.strip("/").split("/"):
+        # RFC 6901 unescaping: ~1 -> "/", ~0 -> "~" (P2-9)
+        part = part.replace("~1", "/").replace("~0", "~")
+        if not isinstance(node, dict) or part not in node:
+            raise ValueError(
+                f"domain {entry['id']!r}: {field} pointer {pointer!r} "
+                f"unresolvable in {target}")
+        node = node[part]
+    if not isinstance(node, list) or not node:
+        raise ValueError(
+            f"domain {entry['id']!r}: {field} pointer {pointer!r} must "
+            f"resolve to a non-empty list, got {type(node).__name__}")
+
+
+def _validate_contracts(entry: dict) -> None:
+    """校验领域条目引用的契约真实存在（load_domain 的核心职责）。
+
+    - frame_schema / outcome_taxonomy / methodology_checklist：文件存在且
+      为可解析 JSON（指针引用另校验指针内容）；
+    - golds_dir / references_dir：目录存在（null 视为"无此契约"，跳过）。
+    """
+    domain_id = entry["id"]
+
+    def check_file(field: str) -> None:
+        target = _field_target(entry, field)
+        if target is None:
+            raise FileNotFoundError(
+                f"domain {domain_id!r}: {field} must reference a file")
+        if not target.is_file():
+            raise FileNotFoundError(
+                f"domain {domain_id!r}: {field} contract missing: {target}")
+        json.loads(target.read_text(encoding="utf-8"))  # must parse as JSON
+        if "#" in str(entry[field]):
+            _check_pointer(entry, field)
+
+    def check_dir(field: str) -> None:
+        raw = entry.get(field)
+        if raw is None:
+            return  # 可选契约（如 policy 的 golds_dir）
+        target = REPO_ROOT / str(raw)
+        if not target.is_dir():
+            raise FileNotFoundError(
+                f"domain {domain_id!r}: {field} missing: {target}")
+
+    check_file("frame_schema")
+    check_file("outcome_taxonomy")
+    check_file("methodology_checklist")
+    check_dir("golds_dir")
+    check_dir("references_dir")
+
+
+def load_domain(domain_id: str) -> dict:
+    """加载领域条目并校验 manifest/契约存在性。
+
+    Returns: domains/manifest.json 中该领域的注册条目（路径为仓库相对路径）。
+    Raises: KeyError（未知领域）；FileNotFoundError / ValueError（契约缺失
+    或损坏）。
+    """
+    for entry in list_domains():
+        if entry["id"] == domain_id:
+            _validate_contracts(entry)
+            return entry
+    known = ", ".join(d["id"] for d in list_domains())
+    raise KeyError(f"unknown domain {domain_id!r} (registered: {known})")
+
+
+def validate_frame(domain_id: str, frame: dict) -> list[str]:
+    """用该领域的 frame schema 校验 frame dict。
+
+    Returns: 稳定错误字符串列表（空 == 合法），与 engine/contracts.py 的
+    validate_record 约定一致；education 复用 scripts.validate_schema 校验
+    现有 schemas/education-frame.schema.json，不引入新校验器。
+    """
+    from scripts.validate_schema import SchemaError, validate  # noqa: PLC0415
+
+    entry = load_domain(domain_id)
+    schema_path = _field_target(entry, "frame_schema")
+    assert schema_path is not None  # load_domain 已保证存在
+    schema = json.loads(schema_path.read_text(encoding="utf-8"))
+    errors: list[str] = []
+    try:
+        validate(frame, schema)
+    except SchemaError as exc:
+        errors.append(str(exc))
+    return errors

package/engine/gap_lens.py

@@ -0,0 +1,132 @@
+"""engine/gap_lens.py — Research Gap Discovery & Contradiction Lens.
+
+Inspired by BioGapLens & PICO gap taxonomy. Analyzes the EvidenceGraph to identify:
+1. Population Gaps (unexplored cohorts, demographic bias)
+2. Measurement / Retention Gaps (missing delayed post-tests, lack of unassisted transfer)
+3. Methodological Gaps (lack of baseline equivalence, missing active controls)
+4. Contradiction Lenses (identifying moderators explaining divergent study findings)
+
+Generates pre-registered 12-week quasi-experimental DID / RCT trial protocols
+specifically grounded on verified gaps (enforcing the rule: 'No study design without evidence grounding').
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+from engine.evidence_graph import EvidenceGraph, GapNode, RiskNode
+from engine.semantics import OutcomeDimension
+
+
+class GapLensAnalyzer:
+    """Automated research gap discovery and contradiction diagnostic engine."""
+
+    def analyze_gaps(self, graph: EvidenceGraph) -> List[GapNode]:
+        gaps: List[GapNode] = []
+        pico = graph.intent.get("pico", {})
+        intervention = pico.get("intervention", "Target Intervention")
+        population = pico.get("population", "Target Population")
+
+        ev_list = list(graph.evidence.values())
+        if not ev_list:
+            return gaps
+
+        # 1. Measurement & Retention Gap Check
+        transfer_nodes = [ev for ev in ev_list if ev.outcome_dimension == OutcomeDimension.INDEPENDENT_TRANSFER]
+        procedural_nodes = [ev for ev in ev_list if ev.outcome_dimension == OutcomeDimension.PROCEDURAL_EFFICIENCY]
+
+        if procedural_nodes and not transfer_nodes:
+            gaps.append(GapNode(
+                gap_id=f"GAP-RETENTION-001",
+                gap_type="Measurement/Retention Gap",
+                description=f"Existing studies on {intervention} exclusively evaluate immediate in-session task speed without measuring delayed conceptual retention or unassisted transfer.",
+                target_outcome="Delayed Unassisted Transfer",
+                existing_evidence_summary=f"{len(procedural_nodes)} studies evaluated active speed; 0 studies measured unassisted delayed retention.",
+                recommended_trial_design="12-Week Cluster Randomized Trial with 4-week delayed post-test without AI assistance.",
+            ))
+        elif transfer_nodes and any(ev.effect_size.get("value", 0.0) <= 0.05 for ev in transfer_nodes):
+            avg_proc = (
+                sum(ev.effect_size.get("value", 0.0) for ev in procedural_nodes) / len(procedural_nodes)
+                if procedural_nodes else 0.0
+            )
+            avg_trans = (
+                sum(ev.effect_size.get("value", 0.0) for ev in transfer_nodes) / len(transfer_nodes)
+                if transfer_nodes else 0.0
+            )
+            gaps.append(GapNode(
+                gap_id=f"GAP-SCAFFOLD-FADE-001",
+                gap_type="Methodological Gap",
+                description=f"Delayed transfer tests indicate cognitive offloading/scaffolding dependency under unguarded {intervention}. Lack of trials evaluating structured 'fading' protocols.",
+                target_outcome="Independent Problem Solving",
+                existing_evidence_summary=f"Synthesized evidence shows {avg_proc:+.2f}g in-task speed ({len(procedural_nodes)} studies) vs {avg_trans:+.2f}g delayed unassisted transfer ({len(transfer_nodes)} studies).",
+                recommended_trial_design="2x2 Factorial Trial: Unguarded Access vs Structured Socratic Fading Scaffold vs Control.",
+            ))
+
+        # 2. Population & Context Heterogeneity Gap
+        cohorts = [ev.sample_description.lower() for ev in ev_list if ev.sample_description]
+        has_novice = any("freshman" in c or "novice" in c or "cs1" in c or "intro" in c or "初学" in c for c in cohorts)
+        has_advanced = any("senior" in c or "advanced" in c or "professional" in c or "高年级" in c or "专家" in c for c in cohorts)
+
+        if has_novice and not has_advanced:
+            gaps.append(GapNode(
+                gap_id=f"GAP-POP-EXPERTISE-001",
+                gap_type="Population Gap",
+                description=f"Evidence is heavily skewed toward introductory novices; efficacy on advanced algorithmic design and large-scale software engineering remains unexplored.",
+                target_outcome="Advanced Software Architecture",
+                existing_evidence_summary=f"Evaluations across {len(cohorts)} studies are restricted to introductory novice cohorts ({population}).",
+                recommended_trial_design="Comparative Quasi-Experimental Study evaluating CS3/CS4 upper-division capstone cohorts.",
+            ))
+
+        # 3. Contradiction Lens (Divergent effect size isolation)
+        pos_studies = [ev for ev in ev_list if ev.effect_size.get("value", 0.0) > 0.20]
+        neg_studies = [ev for ev in ev_list if ev.effect_size.get("value", 0.0) < -0.10]
+
+        if pos_studies and neg_studies:
+            gaps.append(GapNode(
+                gap_id=f"GAP-CONTRADICTION-001",
+                gap_type="Contradiction Lens",
+                description=f"Contradictory findings detected across {len(pos_studies)} positive vs {len(neg_studies)} negative studies. Moderator hypothesis: Degree of real-time Socratic prompting vs direct code generation.",
+                target_outcome="Syntax Speed vs Algorithmic Reasoning",
+                existing_evidence_summary=f"Positive studies ({[s.evidence_id for s in pos_studies[:2]]}) measured active code drafting; negative studies ({[s.evidence_id for s in neg_studies[:2]]}) measured unassisted closed-book exams.",
+                recommended_trial_design="Dismantling Study isolating the active ingredient of AI prompting modality.",
+            ))
+
+        # Register discovered gaps into graph
+        for g in gaps:
+            graph.add_gap(g)
+
+        return gaps
+
+    def generate_pre_registered_protocol(self, gap: GapNode, graph: EvidenceGraph) -> Dict[str, Any]:
+        """Generates a complete 12-week pre-registered quasi-experimental DID trial protocol."""
+        pico = graph.intent.get("pico", {})
+        intervention = pico.get("intervention", "Target Intervention")
+        population = pico.get("population", "Target Population")
+
+        return {
+            "protocol_id": f"PROTO-{gap.gap_id}",
+            "grounded_gap_id": gap.gap_id,
+            "title": f"Pre-Registered 12-Week Field Trial: Evaluating {gap.target_outcome} under {intervention}",
+            "design_type": "Difference-in-Differences (DID) with Baseline Equivalence",
+            "duration_weeks": 12,
+            "target_population": population,
+            "sample_size_target": 240,
+            "arms": [
+                {"name": "Treatment Arm (Scaffolded Intervention)", "n": 120, "description": f"{intervention} with mandatory reflection and phased scaffolding fade"},
+                {"name": "Active Control Arm (Standard Curriculum)", "n": 120, "description": "Traditional IDE with standard pedagogical TA support"},
+            ],
+            "timeline": [
+                {"week": "Week 1", "phase": "Pre-Test Baseline", "measurement": "Baseline Equivalence & Prior Achievement Test (WWC 5.0 compliant)"},
+                {"week": "Weeks 2-5", "phase": "Phase 1: Assisted Foundation", "measurement": "In-task procedural completion time and cognitive load"},
+                {"week": "Weeks 6-9", "phase": "Phase 2: Scaffolding Fade", "measurement": "Socratic prompt fidelity and conceptual mental model check"},
+                {"week": "Week 10", "phase": "Phase 3: Unassisted Transfer", "measurement": "Solo unassisted closed-book problem solving exam"},
+                {"week": "Week 12", "phase": "Phase 4: Delayed Retention Wave", "measurement": "4-week delayed retention test + DID regression data export"},
+            ],
+            "statistical_model": "DID Regression: Y_it = beta_0 + beta_1*Treat_i + beta_2*Post_t + delta*(Treat_i * Post_t) + gamma*X_it + epsilon_it",
+            "causal_estimand": "delta (Average Treatment Effect on the Treated / ATT)",
+            "stopping_rules": [
+                "Severe drop in solo mid-term exam performance (> 1.0 SD deficit vs control)",
+                "Academic integrity breach rate exceeding 15% in treatment cohort",
+            ]
+        }
+
+
+gap_lens = GapLensAnalyzer()

package/engine/gaps.py

@@ -0,0 +1,169 @@
+"""Structured Knowledge Gap derivation.
+
+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.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from engine.contracts import validate_record
+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 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.
+    """
+    frame = frame or {}
+    requested = frame.get("requested_outcomes") or []
+    if not requested and frame.get("target_outcomes"):
+        requested = frame["target_outcomes"]
+
+    findings = store.read_table("findings")
+    outcomes = {o["outcome_id"]: o for o in store.read_table("outcomes")}
+    covered_types: set[str] = set()
+    for f in findings:
+        o = outcomes.get(f["outcome_id"])
+        if o:
+            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):
+        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 [],
+            "priority": priority,
+            "reasoning": reasoning,
+            "status": "open",
+            "derived_from_graph_revision": rev,
+            "extensions": {},
+        })
+
+    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()
+        else:
+            req_name, req_type = str(req).lower(), ""
+        if req_type in _RETENTION_TYPES or req_name in _RETENTION_TYPES:
+            return "retention", req.get("name", "") if isinstance(req, dict) else str(req)
+        if req_type in _TRANSFER_TYPES or req_name in _TRANSFER_TYPES:
+            return "transfer", req.get("name", "") if isinstance(req, dict) else str(req)
+        if req_type in _TASK_PERFORMANCE or req_name in _TASK_PERFORMANCE:
+            return "task_performance", req.get("name", "") if isinstance(req, dict) else str(req)
+        if req_type in _LEARNING or req_name in _LEARNING:
+            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)
+        if kind == "transfer":
+            return bool(covered_types & _TRANSFER_COVER)
+        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)
+        if not label:
+            continue
+        key = (kind, label)
+        if key in seen:
+            continue
+        seen.add(key)
+        if covered_for_kind(kind):
+            continue
+        if kind == "retention":
+            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)")
+        elif kind == "transfer":
+            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)")
+        elif kind == "task_performance":
+            add("missing_outcome", "medium",
+                f"frame requests task-performance outcome {label!r} with no "
+                f"covering finding")
+        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)")
+        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}
+
+    # contradiction gaps
+    for syn in syntheses or ():
+        if syn.status == "contested":
+            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, []))
+
+    # 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)
+        if errors:
+            raise ValueError(f"invalid gap: {errors}")
+    return gaps
+
+
+def save_gaps(project, *, graph_revision: int, gaps: list[dict]) -> Path:
+    """Persist gaps under gaps/ (one JSONL file per revision)."""
+    path = project.path / "gaps" / f"gaps-rev-{graph_revision:06d}.jsonl"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines = "".join(json.dumps(g, ensure_ascii=False) + "\n" for g in gaps)
+    path.write_text(lines, encoding="utf-8")
+    return path