eduevidence 6.0.0 → 6.3.0

package/scripts/pre_verdict_gate.py

@@ -1,13 +1,13 @@
 #!/usr/bin/env python3
 """pre_verdict_gate.py — Pre-Verdict Gate (Phase 15).
 
-An 11-item checklist that must pass (or be explicitly degraded) before a
+A 12-item checklist that must pass (or be explicitly degraded) before a
 verdict may carry a high confidence label. The gate is deterministic and
 reads ONLY the run workspace — no model call, no network.
 
 Checklist:
 
-  1.  research_frame_valid       frame.json validates against education-frame.schema.json
+  1.  research_frame_valid       frame.json validates against the run domain frame schema
   2.  sources_valid              sources.jsonl non-empty and schema-valid
   3.  evidence_schema_valid      evidence.jsonl non-empty and schema-valid
   4.  source_dedupe              no duplicate sources remain (dedupe applied)
@@ -58,7 +58,7 @@ for _p in (str(ROOT), str(ROOT / "scripts")):
 
 from validate_schema import SchemaError, Validator  # noqa: E402
 from evidence_score import independent_samples, independent_studies  # noqa: E402
-from evidence_semantics import claim_relation  # noqa: E402
+from evidence_semantics import claim_relation, decision_relation  # noqa: E402
 from run_workspace import utc_now  # noqa: E402
 
 GATE_VERSION = "2026-08-13.v1"
@@ -66,29 +66,52 @@ GATE_VERSION = "2026-08-13.v1"
 CONFIDENCE_RANK = {"Insufficient": 0, "Low": 1, "Moderate": 2, "High": 3}
 
 #: Advisory taxonomy for verdict outcome keys (shared with claim_audit).
-SUPPORTED_OUTCOMES = {
-    "knowledge_gain", "concept_understanding", "retention", "transfer",
-    "independent_problem_solving", "completion_time", "accuracy",
-    "code_quality", "assignment_score", "engagement", "motivation",
-    "cognitive_load", "help_seeking", "metacognition", "ai_dependency",
-    "over_reliance", "reduced_effort", "reduced_transfer",
-    "academic_integrity_risk", "false_confidence",
-}
+def _supported_outcomes() -> set[str]:
+    """Every registered outcome token, read from the domain registry.
+
+    This was a hand-copied 20-token education list in three separate files;
+    it silently rejected policy tokens such as policy_effectiveness. The
+    registry (domains/<id>/outcome_taxonomy.json) is the single authority.
+    """
+    from engine.taxonomy import all_tokens_ordered
+
+    return set(all_tokens_ordered())
+
+
+SUPPORTED_OUTCOMES = _supported_outcomes()
 
 _CLAIM_ID_RE = re.compile(r"\b[A-Z]{1,3}-\d{2,4}\b")
 
 _SCHEMA_CACHE: dict[str, dict[str, Any]] = {}
 
 
+def _schema_path(name: str) -> Path:
+    """Resolve a schema name to a file.
+
+    Accepts a bare name in schemas/ as well as a repository-relative path,
+    because a domain may own its frame contract outside schemas/ (policy does:
+    domains/policy/frame.schema.json).
+    """
+    candidate = ROOT / "schemas" / name
+    if candidate.is_file():
+        return candidate
+    owned = ROOT / name
+    if owned.is_file():
+        return owned
+    return candidate  # missing: the caller reports it
+
+
 def _schema(name: str) -> dict[str, Any]:
-    if name not in _SCHEMA_CACHE:
-        _SCHEMA_CACHE[name] = json.loads((ROOT / "schemas" / name).read_text(encoding="utf-8"))
-    return _SCHEMA_CACHE[name]
+    path = _schema_path(name)
+    key = str(path)
+    if key not in _SCHEMA_CACHE:
+        _SCHEMA_CACHE[key] = json.loads(path.read_text(encoding="utf-8"))
+    return _SCHEMA_CACHE[key]
 
 
 def _validate_records(records: list[dict[str, Any]], schema_name: str, path: str) -> list[str]:
     schema = _schema(schema_name)
-    validator = Validator(schema, base_dir=(ROOT / "schemas"))
+    validator = Validator(schema, base_dir=_schema_path(schema_name).parent)
     errors = []
     for idx, record in enumerate(records):
         try:
@@ -133,11 +156,43 @@ def _item_res(status: str, detail: str, *, blocks_high: bool | None = None) -> d
     return res
 
 
+def workspace_domain(ws: Path) -> str:
+    """The domain this run/pack registered; defaults to education when absent.
+
+    A run workspace records it in run_manifest.json, but an example pack has
+    no manifest: reading only that file made a policy pack validate against the
+    education frame schema and fail item 1. Fall back to the same declared
+    places the read model uses, in the same order.
+    """
+    manifest = _load_ws_json(ws, "run_manifest.json")
+    if manifest.get("domain"):
+        return str(manifest["domain"])
+    frame = _load_ws_json(ws, "frame.json")
+    declared = (frame.get("extensions") or {}).get("domain")
+    if declared:
+        return str(declared)
+    result_meta = (_load_ws_json(ws, "result.json").get("meta") or {})
+    if result_meta.get("domain"):
+        return str(result_meta["domain"])
+    return "education"
+
+
+def frame_schema_name(domain: str) -> str:
+    """Registered frame schema for a domain (repository-relative path)."""
+    from engine.evidencecore import load_domain
+
+    return str(load_domain(domain)["frame_schema"])
+
+
 def check_research_frame(ws: Path) -> dict[str, str]:
     frame = _load_ws_json(ws, "frame.json")
     if not frame:
         return _item_res("fail", "frame.json missing or empty (research question not framed)")
-    errors = _validate_records([frame], "education-frame.schema.json", "frame")
+    try:
+        schema_name = frame_schema_name(workspace_domain(ws))
+    except KeyError as exc:
+        return _item_res("fail", f"run declares an unknown domain: {exc}")
+    errors = _validate_records([frame], schema_name, "frame")
     if errors:
         return _item_res("fail", f"frame.json schema invalid: {errors[0]}")
     return _item_res("pass", f"frame.json valid (question={frame.get('question', '')[:80]})")
@@ -182,11 +237,41 @@ def check_counter_evidence(ws: Path) -> dict[str, str]:
         return _item_res("fail", "skeptic.json missing or empty (counter-evidence search not performed)")
     if skeptic.get("search_performed") is not True:
         return _item_res("fail", "skeptic.json lacks search_performed=true")
-    contradictions = skeptic.get("contradictions", []) or []
-    null_results = skeptic.get("null_results", []) or []
-    detail = f"search_performed=true; contradictions={len(contradictions)}, null_results={len(null_results)}"
-    if skeptic.get("no_contradictory_evidence_found"):
-        detail += "; no contradictory evidence found"
+
+    # The nine fixed checks are the contract (skill/task-briefs/challenge.md).
+    # A two-key shell used to pass this gate, which made the counter-evidence
+    # check cosmetic on every deterministic path.
+    required_checks = (
+        "1_null_result", "2_negative_result", "3_contradictory_evidence",
+        "4_alternative_explanation", "5_measurement_mismatch", "6_sampling_bias",
+        "7_novelty_effect", "8_ai_dependency", "9_scope_overreach",
+    )
+    findings = skeptic.get("skeptic_findings")
+    if not isinstance(findings, list) or not findings:
+        return _item_res(
+            "fail", "skeptic.json lacks skeptic_findings[] (nine fixed checks not run)")
+    present = {str(f.get("check")) for f in findings if isinstance(f, dict)}
+    missing = [c for c in required_checks if c not in present]
+    if missing:
+        return _item_res("fail", f"skeptic findings incomplete; missing {missing}")
+    for item in findings:
+        if not isinstance(item, dict) or item.get("status") not in ("found", "not_found"):
+            return _item_res(
+                "fail", f"skeptic finding {item.get('check')!r} lacks a found/not_found status")
+
+    found = bool(skeptic.get("contradictory_evidence_found"))
+    statement = skeptic.get("no_contradictory_evidence_statement")
+    if not found and not statement:
+        # Absence of counter-evidence must be asserted, not left implicit.
+        return _item_res(
+            "fail", "no contradictory evidence found but no statement recorded")
+    if found and statement:
+        return _item_res(
+            "fail", "contradictory_evidence_found=true together with a no-evidence statement")
+
+    found_checks = sum(1 for f in findings if f.get("status") == "found")
+    detail = (f"search_performed=true; 9/9 checks run; findings={found_checks}; "
+              f"contradictory_evidence_found={found}")
     return _item_res("pass", detail)
 
 
@@ -270,6 +355,105 @@ def check_claim_evidence(ws: Path) -> dict[str, str]:
     return _item_res("pass", "all verdict claims bind to existing evidence with consistent categories")
 
 
+def _primary_evidence_summary(ws: Path) -> dict[str, Any]:
+    """Re-derive ADOPT eligibility from the pack's own evidence records.
+
+    The gate audits an artifact another party wrote, so it cannot trust the
+    verdict about itself: primary-result directness is read back from the
+    corpus (frame primary outcomes + per-record D5 Directness), using the same
+    domain registry and directness threshold the tribunal imports.
+    """
+    from engine.decision_policy import (
+        ADOPT_DIRECTNESS,
+        outcome_category,
+        primary_effect_categories,
+    )
+
+    domain = workspace_domain(ws)
+    try:
+        primary = primary_effect_categories(domain)
+    except (KeyError, ValueError) as exc:
+        return {"domain": domain, "primary": (), "direct": False, "error": str(exc)}
+
+    frame = _load_ws_json(ws, "frame.json")
+    declared_primary = [
+        str(token) for token in ((frame.get("outcomes") or {}).get("primary") or [])
+    ]
+    evidence = _load_ws_jsonl(ws, "evidence.jsonl")
+    direct_hits: list[str] = []
+    for ev in evidence:
+        token = str(ev.get("outcome_type") or "")
+        category = outcome_category(domain, token, primary)
+        if category is None or category not in primary:
+            continue
+        dims = ev.get("quality_dimensions") or {}
+        d5 = dims.get("D5_directness")
+        if isinstance(d5, bool) or not isinstance(d5, int):
+            continue
+        if d5 >= ADOPT_DIRECTNESS:
+            direct_hits.append(str(ev.get("evidence_id") or "?"))
+    return {
+        "domain": domain,
+        "primary": primary,
+        "declared_primary": declared_primary,
+        "direct": bool(direct_hits),
+        "direct_evidence_ids": direct_hits,
+    }
+
+
+def check_decision_action(ws: Path) -> dict[str, str]:
+    """The stated action must be the action the evidence supports.
+
+    A verdict cannot hand itself ADOPT: the gate requires High confidence, a
+    supporting decisive relation, and primary-outcome evidence at directness 2.
+    Anything less is capped to pilot - the conservative bound - because the
+    underlying evidence may still justify a bounded trial.
+    """
+    verdict = _verdict_for_audit(ws)
+    if not verdict:
+        return _item_res("warn", "no verdict artifact yet; action not audited")
+    action = str(verdict.get("recommended_action") or "").lower()
+    if action != "adopt":
+        label = action or "unset"
+        return _item_res("pass", "action=" + label + " is within the conservative bound")
+
+    from engine.decision_policy import (
+        ADOPT_REQUIRED_LABEL,
+        decision_outcome,
+    )
+
+    evidence = _load_ws_jsonl(ws, "evidence.jsonl")
+    relations = [decision_relation(ev) for ev in evidence]
+    decisive = {str(index): rel for index, rel in enumerate(relations)
+                if rel in ("support_adoption", "oppose_adoption",
+                           "conditional", "conflict", "mixed")}
+    label = str(verdict.get("confidence") or "")
+    summary = _primary_evidence_summary(ws)
+    outcome = decision_outcome(
+        confidence_label=label,
+        decisive_relations=decisive,
+        has_direct_primary_evidence=bool(summary.get("direct")),
+    )
+    expected = outcome["action"]
+    downgrade_reason = outcome.get("downgrade_reason")
+    if expected == "ADOPT":
+        detail = "ADOPT is supported: " + label + " confidence with direct primary-outcome evidence"
+        return _item_res("pass", detail)
+    reasons: list[str] = []
+    if label != ADOPT_REQUIRED_LABEL:
+        reasons.append("confidence=" + (label or "unset") + " (needs " + ADOPT_REQUIRED_LABEL + ")")
+    if "support_adoption" not in relations:
+        reasons.append("no decisive supporting evidence")
+    if not summary.get("direct"):
+        reasons.append("no primary-outcome evidence at directness 2")
+    if downgrade_reason:
+        reasons.append("downgrade_reason=" + downgrade_reason)
+    detail = ("recommended_action=adopt is not supported (" + "; ".join(reasons)
+              + "); the evidence bounds this decision to "
+              + str(expected).lower())
+    return _item_res("fail", detail)
+
+
 def check_outcome_mapping(ws: Path) -> dict[str, str]:
     verdict = _verdict_for_audit(ws)
     frame = _load_ws_json(ws, "frame.json")
@@ -282,18 +466,35 @@ def check_outcome_mapping(ws: Path) -> dict[str, str]:
         issues.append(f"unknown outcome key(s) in verdict: {', '.join(sorted(unknown))}")
 
     evidence_outcomes = {e.get("outcome_type") for e in _load_ws_jsonl(ws, "evidence.jsonl")}
+    frame_outcomes = frame.get("outcomes", {}) or {}
     declared = set()
     for group in ("primary", "secondary", "risk"):
-        declared.update((frame.get("outcomes", {}) or {}).get(group, []) or [])
+        declared.update(frame_outcomes.get(group, []) or [])
     if declared:
         missing = sorted(d for d in declared if d and d not in evidence_outcomes)
         if missing:
-            notes.append(f"frame-declared outcomes without evidence: {', '.join(missing)}")
+            # Missing evidence is not a zero effect, and a secondary or risk
+            # outcome the frame named but the corpus never measured does not
+            # contaminate the decision. Only a PRIMARY outcome with no
+            # evidence at all means the decision rests on the wrong construct,
+            # so only that case blocks High confidence.
+            primary_missing = sorted(
+                d for d in (frame_outcomes.get("primary", []) or [])
+                if d and d not in evidence_outcomes)
+            note = f"frame-declared outcomes without evidence: {', '.join(missing)}"
+            if primary_missing:
+                return _item_res(
+                    "warn",
+                    note + f"; primary outcomes unmeasured: {', '.join(primary_missing)}",
+                    blocks_high=True)
+            notes.append(note)
+        else:
+            notes.append("all frame-declared outcomes are covered by evidence")
 
     if issues:
         return _item_res("fail", "; ".join(issues))
-    if notes:
-        return _item_res("warn", "outcome keys known; " + notes[0])
+    if notes and "without evidence" in notes[0]:
+        return _item_res("warn", "outcome keys known; " + notes[0], blocks_high=False)
     if not declared:
         return _item_res("warn", "outcome keys known; frame declares no outcomes to map")
     return _item_res("pass", f"outcome mapping complete ({len(evidence_outcomes)} outcome type(s) covered)")
@@ -375,18 +576,20 @@ GATE_ITEMS: list[dict[str, Any]] = [
     {"id": "claim_evidence_audit", "title": "Claim-Evidence Audit", "critical": True,
      "blocks_high": False, "check": check_claim_evidence},
     {"id": "outcome_mapping", "title": "Outcome mapping", "critical": False,
-     "blocks_high": False, "check": check_outcome_mapping},
+     "blocks_high": True, "check": check_outcome_mapping},
     {"id": "scope_calibration", "title": "Scope calibration", "critical": False,
-     "blocks_high": False, "check": check_scope_calibration},
+     "blocks_high": True, "check": check_scope_calibration},
     {"id": "independent_study_count", "title": "Independent study-sample count", "critical": True,
      "blocks_high": True, "check": check_study_count},
     {"id": "deterministic_confidence", "title": "Deterministic confidence", "critical": True,
      "blocks_high": True, "check": None},
+    {"id": "decision_action_consistency", "title": "Decision action consistency",
+     "critical": True, "blocks_high": False, "check": check_decision_action},
 ]
 
 
 def evaluate_workspace(workspace: Path, *, require_final: bool = True) -> dict[str, Any]:
-    """Run the 11-item gate over a run workspace. Pure, deterministic, read-only."""
+    """Run the 12-item gate over a run workspace. Pure, deterministic, read-only."""
     ws = Path(workspace)
     items: dict[str, dict[str, Any]] = {}
     for spec in GATE_ITEMS:
@@ -437,6 +640,7 @@ def apply_enforcement(verdict: dict[str, Any], gate: dict[str, Any]) -> dict[str
 
     - gate failed            -> confidence at most Low; adopt downgraded to pilot
     - gate passed but High blocked -> confidence at most Moderate
+    - stated adopt the evidence does not support -> downgraded to pilot
     Always records the enforcement inside verdict.extensions.gate_enforcement.
     """
     import copy
@@ -446,8 +650,15 @@ def apply_enforcement(verdict: dict[str, Any], gate: dict[str, Any]) -> dict[str
     current = out.get("confidence", "Insufficient")
     if CONFIDENCE_RANK.get(current, 0) > CONFIDENCE_RANK.get(cap, 0):
         out["confidence"] = cap
+    downgrade_reason = None
     if not gate.get("passed", False) and out.get("recommended_action") == "adopt":
         out["recommended_action"] = "pilot"
+        downgrade_reason = "gate_critical"
+    action_item = (gate.get("items") or {}).get("decision_action_consistency") or {}
+    if action_item.get("status") == "fail" and out.get("recommended_action") == "adopt":
+        out["recommended_action"] = "pilot"
+        if downgrade_reason is None:
+            downgrade_reason = "missing_direct_primary"
     extensions = out.setdefault("extensions", {})
     if not isinstance(extensions, dict):
         extensions = {}
@@ -461,6 +672,7 @@ def apply_enforcement(verdict: dict[str, Any], gate: dict[str, Any]) -> dict[str
         "max_confidence": cap,
         "confidence_before": current,
         "action_before": verdict.get("recommended_action"),
+        "downgrade_reason": downgrade_reason,
     })
     return out
 
@@ -469,7 +681,7 @@ def apply_enforcement(verdict: dict[str, Any], gate: dict[str, Any]) -> dict[str
 
 
 def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(description="EduEvidence Pre-Verdict Gate (11-item checklist)")
+    parser = argparse.ArgumentParser(description="EduEvidence Pre-Verdict Gate (12-item checklist)")
     parser.add_argument("--workspace", required=True, help="run workspace directory (runs/<run_id>)")
     parser.add_argument("--require-final", action="store_true",
                         help="item 11 fails when final_verdict.json is missing (default: warn)")

package/scripts/quickstart.py

@@ -40,8 +40,23 @@ STAGE_BRIEFS = {
 }
 
 
+def runs_root() -> Path:
+    """Runs directory, honouring EDUEVIDENCE_RUNS_DIR like the orchestrator does.
+
+    Without this the quickstart wrote into the repository even when the user had
+    pointed the runs directory elsewhere.
+    """
+    import os
+
+    return Path(os.environ.get("EDUEVIDENCE_RUNS_DIR") or (ROOT / "runs"))
+
+
 def newest_run_dir() -> Path:
-    runs_dir = ROOT / "runs"
+    runs_dir = runs_root()
+    if not runs_dir.is_dir():
+        raise SystemExit(
+            f"no runs directory at {runs_dir}; run `eduevidence run --question ...` first "
+            "(or set EDUEVIDENCE_RUNS_DIR)")
     candidates = sorted((p for p in runs_dir.iterdir() if p.is_dir()),
                         key=lambda p: p.stat().st_mtime, reverse=True)
     if not candidates:
@@ -86,7 +101,8 @@ def build_next_steps(run_dir: Path, question: str, depth: str) -> str:
         "",
         "## 可信度自检",
         "",
-        "- 引用逐条核验报告：`benchmarks/doi-audit/report.md` 与包内 `citation_check.md`",
+        "- 引用逐条核验报告：包内 `citation_check.md`"
+        "（源码仓库另见 `benchmarks/doi-audit/report.md`）",
         "- 报告头徽章标注 data_origin；synthetic 演示不得当作实证引用",
         ""]
     return "\n".join(lines)

package/scripts/run_workspace.py

@@ -179,14 +179,20 @@ def build_manifest(
     scp_available: bool | None = None,
     root: Path | None = None,
     started_at: str | None = None,
+    domain: str = "education",
 ) -> dict[str, Any]:
-    """Phase 13 run manifest with every contract field."""
+    """Phase 13 run manifest with every contract field.
+
+    ``domain`` selects which registered frame contract this run must satisfy;
+    it defaults to education so existing callers and manifests stay valid.
+    """
     return {
         "run_id": run_id,
         "skill_version": SKILL_VERSION,
         "git_commit": git_commit(root),
         "started_at": started_at or utc_now(),
         "question": question,
+        "domain": domain,
         "execution_mode": execution_mode,
         "scp_available": detect_scp() if scp_available is None else scp_available,
         "agent_mcp_available": agent_mcp_available,

package/scripts/skill_lint.py

@@ -13,7 +13,6 @@ Usage:
 """
 from __future__ import annotations
 
-import os
 import re
 import sys
 from pathlib import Path
@@ -130,6 +129,17 @@ def lint_skill() -> list[str]:
         if re.search(r"theme-btn|theme-switcher|data-theme-target", ltext):
             errors.append("scripts/render_report_html.py still contains runtime theme switcher")
 
+    # 10. File-layer hard gate (also runnable alone: python3 scripts/lint_file_layers.py)
+    try:
+        sys.path.insert(0, str(ROOT / "scripts"))
+        from lint_file_layers import check_file_layers  # noqa: PLC0415
+        layer_errors, layer_warnings = check_file_layers()
+        errors.extend(layer_errors)
+        for w in layer_warnings:
+            print(f"    ! {w}")
+    except Exception as exc:  # pragma: no cover - lint must still run
+        errors.append(f"file-layer gate failed to load: {exc}")
+
     return errors
 
 

package/scripts/skill_payload.py

@@ -7,12 +7,14 @@ import sys
 
 TREES = (
     "agents", "engine", "domains", "skill", "references", "schemas", "scripts",
+    "integrations", "visualization/eduevidence-report",
     "retrieval", "integrations", "visualization/eduevidence-report", "web/studio",
     "assets/readme",
 )
 FILES = (
     "SKILL.md", "eduevidence_cli.py", "install.sh", "pyproject.toml", "setup.py",
     "LICENSE", "CHANGELOG.md", "README.md", "README.zh-CN.md", "web/index.html",
+    "CONTRIBUTING.md", "web/architecture.html",
     "benchmarks/evidence-library.json", "benchmarks/partitions.json",
     "benchmarks/adversarial/cases.jsonl",
 )
@@ -21,11 +23,13 @@ DOCS = (
     "reproducibility.md", "release-contract.md", "autoresearch-evolution-plan.md",
     "orchestration-role-model.md", "autoresearch-implementation-status.md",
     "research-studio-guide.zh-CN.md", "demo-workplace-ai.md",
+    "sciverse-api.md", "j-ev-experimental.md",
     "release-closeout/README.md", "release-closeout/issues.md",
     "release-closeout/frontend-acceptance.md", "release-closeout/verification.md",
 )
 EXAMPLES = (
-    "ai-coding-assistant-evidence", "workplace-ai-assistant",
+    "ai-coding-assistant-evidence", "spaced-retrieval-practice",
+    "workplace-ai-assistant",
 )
 EXAMPLE_FILES = (
     "result.json", "result.zh.json", "evidence_graph.json", "report_spec.json",
@@ -34,8 +38,7 @@ EXAMPLE_FILES = (
 )
 RETIRED_DEMO_SCRIPTS = {
     "scripts/build_esl_artifacts.py", "scripts/generate_new_projects.py",
-    "scripts/enrich_projects_human_and_lieflat.py", "scripts/build_killer_demo.py",
-    "scripts/sync_killer_demo_report.py",
+    "scripts/enrich_projects_human_and_lieflat.py",
 }