eduevidence 5.2.0 → 6.2.0

package/scripts/build_readme_diagrams.py

@@ -0,0 +1,72 @@
+"""Generate GitHub-safe vector diagrams from the canonical protocol registry."""
+from pathlib import Path
+import sys
+from html import escape
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+from engine.workflows import SCIENTIFIC_STAGE_IDS  # noqa: E402
+
+OUT = ROOT / 'assets/readme'
+OUT.mkdir(parents=True, exist_ok=True)
+
+
+def start(title, subtitle, height):
+    return [f'''<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="{height}" viewBox="0 0 1200 {height}" role="img" aria-label="{escape(title)}">
+<title>{escape(title)}</title><desc>{escape(subtitle)}</desc>
+<defs><marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse"><path d="M0 0L10 5L0 10" fill="none" stroke="#a15c40" stroke-width="1.5"/></marker></defs>
+<rect width="1200" height="{height}" rx="24" fill="#f7f5f0"/>
+<g font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Arial,sans-serif">
+<text x="48" y="43" font-size="12" letter-spacing="3" fill="#9b5e45">EDUEVIDENCE / RESEARCH STUDIO</text>
+<text x="48" y="92" font-size="32" font-weight="600" fill="#272924">{escape(title)}</text>
+<text x="48" y="126" font-size="16" fill="#6f7068">{escape(subtitle)}</text>''']
+
+
+def card(parts, x, y, w, num, title, detail, accent=False):
+    fill = '#eee2d8' if accent else '#ffffff'
+    parts.append(f'<rect x="{x}" y="{y}" width="{w}" height="96" rx="14" fill="{fill}" stroke="#dcd8ce"/>')
+    parts.append(f'<text x="{x+20}" y="{y+28}" font-size="12" fill="#a15c40">{escape(num)}</text>')
+    parts.append(f'<text x="{x+20}" y="{y+54}" font-size="21" font-weight="600" fill="#30332e">{escape(title)}</text>')
+    parts.append(f'<text x="{x+20}" y="{y+78}" font-size="13" fill="#6f7068">{escape(detail)}</text>')
+
+
+def line(parts, d):
+    parts.append(f'<path d="{d}" fill="none" stroke="#a15c40" stroke-width="1.7" marker-end="url(#arrow)"/>')
+
+
+labels = {
+    'frame': ('Frame / 定义问题', 'Question, population, comparison, outcomes'),
+    'retrieve': ('Retrieve / 检索来源', 'Primary sources and retrieval provenance'),
+    'extract': ('Extract / 提取证据', 'Study findings, measures and uncertainty'),
+    'challenge': ('Challenge / 反证质疑', 'Counter-evidence and alternative explanations'),
+    'audit': ('Audit / 方法审计', 'Study quality, bias and evidence limitations'),
+    'adjudicate': ('Adjudicate / 证据裁决', 'Supported claims and bounded decisions'),
+    'applicability': ('Applicability / 适用边界', 'For whom, where and under which conditions'),
+    'intervene': ('Intervene / 设计试点', 'A grounded knowledge gap before a new design'),
+    'evaluate': ('Evaluate / 评估更新', 'Validate new data and revise the decision'),
+}
+p=start('From evidence to a decision you can inspect', 'Nine scientific stages · 三条公开工作流 · Education + organizational policy', 704)
+for i, stage in enumerate(SCIENTIFIC_STAGE_IDS):
+    row,col=divmod(i,3)
+    if row==1: col=2-col
+    x,y=48+col*376,166+row*128
+    card(p,x,y,352,f'{i+1:02d}',*labels[stage],stage=='adjudicate')
+    if i in (0,1,6,7): line(p,f'M{x+352} {y+48} H{x+370}')
+    if i in (3,4): line(p,f'M{x} {y+48} H{x-18}')
+    if i in (2,5): line(p,f'M{x+176} {y+96} V{y+121}')
+p.append('<rect x="48" y="568" width="1104" height="88" rx="14" fill="#e9eee7"/>')
+p.append('<text x="70" y="600" font-size="18" font-weight="600" fill="#456450">Projection / 展示制品</text>')
+p.append('<text x="70" y="627" font-size="15" fill="#456450">Read-only Studio · Five report themes · Bilingual HTML · A report is not proof of an executed study.</text>')
+p.append('<text x="48" y="682" font-size="12" fill="#6f7068">Evidence Review 01–07   /   Decision &amp; Pilot 01–08   /   Evaluate &amp; Update 09</text></g></svg>')
+(OUT/'research-workflow.svg').write_text('\n'.join(p))
+p=start('One research record. Controlled contributions.', 'Roles describe scientific responsibilities. Workers contribute only when the host supports delegation.',600)
+card(p,48,178,290,'01 / LEAD','Plan the work','Bounded tasks and input snapshots')
+card(p,442,178,310,'02 / EXECUTION','Native or delegated','Same scientific protocol and validation gates')
+card(p,854,178,298,'03 / STAGING','Review contributions','Evidence, critique and audit artifacts')
+line(p,'M338 226 H432'); line(p,'M752 226 H844');line(p,'M1004 274 V330 H599 V358')
+card(p,442,368,310,'04 / VALIDATED COMMIT','Single writer','Lead commits a new immutable graph revision',True)
+line(p,'M762 416 H844');card(p,854,368,298,'05 / PROJECTION','Read and trace','Studio, reports and revision history')
+p.append('<text x="48" y="520" font-size="17" fill="#456450">Append evidence. Preserve provenance. Derive the decision from validated facts.</text>')
+p.append('<text x="48" y="550" font-size="14" fill="#6f7068">Native execution needs no worker service. Cross-backend empirical performance is a separate verification task.</text></g></svg>')
+(OUT/'controlled-execution.svg').write_text('\n'.join(p))
+print('Generated research-workflow.svg and controlled-execution.svg from current protocol.')

package/scripts/build_report_variants.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Bake all five report identities from the same validated bilingual inputs.
+
+This is a build step, never a read endpoint. No evidence or decision is changed.
+Failures are explicit and never replaced with a synthetic success document.
+"""
+from __future__ import annotations
+import argparse
+import hashlib
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+THEMES = ('claude', 'academic', 'datalab', 'datalab-dark', 'presentation')
+
+
+def bake(examples: Path, *, force: bool = False) -> list[dict]:
+    renderer_dir = ROOT / 'visualization' / 'eduevidence-report'
+    renderer = renderer_dir / 'scripts' / 'build_report.py'
+    digest = hashlib.sha256()
+    for path in sorted(renderer_dir.rglob('*')):
+        if path.suffix in {'.py', '.css', '.js', '.json'} and '__pycache__' not in path.parts:
+            digest.update(path.relative_to(renderer_dir).as_posix().encode())
+            digest.update(path.read_bytes())
+    engine_hash = digest.hexdigest()
+    reports = []
+    for directory in sorted(examples.iterdir()):
+        if not directory.is_dir() or directory.is_symlink():
+            continue
+        source, parallel = directory / 'result.json', directory / 'result.zh.json'
+        if not source.exists() or not parallel.exists():
+            continue
+        result_hash = hashlib.sha256(source.read_bytes()).hexdigest()
+        cache_key = hashlib.sha256((engine_hash + result_hash + hashlib.sha256(parallel.read_bytes()).hexdigest()).encode()).hexdigest()
+        out_dir = directory / 'reports-5themes'
+        manifest = out_dir / 'reader-manifest.json'
+        if not force and manifest.is_file():
+            try:
+                prior = json.loads(manifest.read_text(encoding='utf-8'))
+                main = prior.get('main_report') or {}
+                main_ok = bool(main.get('file')) and (directory / main['file']).is_file() and                     hashlib.sha256((directory / main['file']).read_bytes()).hexdigest() == main.get('sha256')
+                valid = prior.get('cache_key') == cache_key and main_ok and all(
+                    (out_dir / record['file']).is_file() and hashlib.sha256((out_dir / record['file']).read_bytes()).hexdigest() == record['sha256']
+                    for record in prior.get('reports', [])) and len(prior.get('reports', [])) == len(THEMES)
+                if valid:
+                    reports.append(prior)
+                    continue
+            except (ValueError, KeyError, OSError):
+                pass
+        out_dir.mkdir(parents=True, exist_ok=True)
+        records = []
+        for theme in THEMES:
+            target = out_dir / f'EduEvidence_Report_{theme}.html'
+            # Build to temporary files, promote only after scientific gates pass.
+            temporary = out_dir / f'.{theme}.pending.html'
+            spec = out_dir / f'report_spec_{theme}.json'
+            completed = subprocess.run([sys.executable, str(renderer), '--result', str(source),
+                                        '--result-zh', str(parallel), '--theme', theme,
+                                        '--out', str(temporary), '--spec-out', str(spec)],
+                                       cwd=ROOT, capture_output=True, text=True, timeout=120)
+            if completed.returncode:
+                temporary.unlink(missing_ok=True)
+                raise RuntimeError(f'{directory.name}/{theme}: renderer rejected input\n{completed.stdout}\n{completed.stderr}')
+            os.replace(temporary, target)
+            records.append({'theme': theme, 'file': target.name, 'sha256': hashlib.sha256(target.read_bytes()).hexdigest()})
+        # Also refresh the pack-root report. This used to write only the themed
+        # variants, so examples/*/EduEvidence_Report.html kept whatever bytes it
+        # was first rendered with - the packaged example shipped a report the
+        # current renderer would not produce.
+        from_default = next((r for r in records if r['theme'] == 'claude'), records[0])
+        main_target = directory / 'EduEvidence_Report.html'
+        main_temp = directory / '.EduEvidence_Report.pending.html'
+        main_temp.write_bytes((out_dir / from_default['file']).read_bytes())
+        os.replace(main_temp, main_target)
+        main_sha = hashlib.sha256(main_target.read_bytes()).hexdigest()
+
+        value = {'schema_version': 1, 'project': directory.name, 'cache_key': cache_key,
+                 'result_sha256': result_hash, 'renderer_sha256': engine_hash,
+                 'main_report': {'file': main_target.name, 'sha256': main_sha,
+                                 'theme': from_default['theme']},
+                 'reports': records}
+        manifest.write_text(json.dumps(value, indent=2) + '\n', encoding='utf-8')
+        reports.append(value)
+        print(f'{directory.name}: {len(records)} verified report variants')
+    return reports
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--examples', type=Path, default=ROOT / 'examples')
+    parser.add_argument('--force', action='store_true')
+    args = parser.parse_args()
+    bake(args.examples, force=args.force)
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/scripts/build_result.py

@@ -30,14 +30,14 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 from evidence_semantics import effect_direction
 from engine.versions import ENGINE_VERSION
 
-OUTCOME_ORDER = [
-    "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 _outcome_order() -> list[str]:
+    """Registered outcome tokens in registry order (was a hard-coded list)."""
+    from engine.taxonomy import all_tokens_ordered
+
+    return list(all_tokens_ordered())
+
+
+OUTCOME_ORDER = _outcome_order()
 
 
 def _load_json(path: Path) -> dict[str, Any] | None:
@@ -221,12 +221,74 @@ def build_claims(evidence: list[dict[str, Any]]) -> list[dict[str, Any]]:
     return list(claims.values())
 
 
+def _applicability(pack_dir: Path, verdict: dict) -> dict:
+    """Stage-7 applicability assessment, falling back to the verdict boundary.
+
+    applicability.json is the dedicated deliverable of the Applicability stage.
+    It used to be written and then ignored, because the renderer only looked at
+    the verdict; this is where it re-enters the result.
+    """
+    import json as _json
+
+    path = pack_dir / "applicability.json"
+    if path.is_file():
+        try:
+            data = _json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, _json.JSONDecodeError):
+            data = None
+        if isinstance(data, dict) and data and data.get("status") != "NOT_CAPTURED":
+            return data
+    value = verdict.get("applicability") if isinstance(verdict, dict) else None
+    return value if isinstance(value, dict) else {}
+
+def _derive_study_audits(methodology: list[dict], evidence: list[dict]) -> list[dict]:
+    """Per-study audit rows derived from the audits and evidence present.
+
+    Each row names the study and reports the audit verdict that covers it,
+    so the per-study axis the schema advertises actually exists downstream.
+    Rows are only emitted for studies the audits or evidence actually name.
+    """
+    by_study: dict[str, dict] = {}
+    for audit in methodology:
+        if not isinstance(audit, dict):
+            continue
+        target = audit.get("target") or "overall"
+        if target == "overall":
+            # The aggregate audit is not a study row; label it as the
+            # body-of-evidence review so it cannot be mistaken for one.
+            target = "body_of_evidence"
+        entry = by_study.setdefault(target, {
+            "study_id": target,
+            "verdict": audit.get("verdict"),
+            "audit_items": audit.get("audit_items") or {},
+            "limitations": list(audit.get("limitations") or []),
+            "task_vs_learning_guard": audit.get("task_vs_learning_guard"),
+        })
+        entry.setdefault("evidence_ids", [])
+    known = {e.get("study_id") for e in evidence if e.get("study_id")}
+    for study_id in sorted(known):
+        by_study.setdefault(study_id, {
+            "study_id": study_id,
+            "verdict": None,
+            "audit_items": {},
+            "limitations": [],
+            "task_vs_learning_guard": None,
+            "evidence_ids": [e.get("evidence_id") for e in evidence
+                             if e.get("study_id") == study_id],
+        })
+    return list(by_study.values())
+
+
 def build_result(pack_dir: Path, *, mode: str = "platform_native") -> dict[str, Any]:
     frame = _load_json(pack_dir / "frame.json") or {}
     evidence = _load_jsonl(pack_dir / "evidence.jsonl")
     # methodology.json is a single MethodologyAudit object (or a JSONL list)
     methodology_single = _load_json(pack_dir / "methodology.json")
     methodology = [methodology_single] if methodology_single else _load_jsonl(pack_dir / "methodology.jsonl")
+    # Per-study audits: the contract advertised them but nothing produced
+    # them, so a multi-study review silently shipped a single audit object.
+    # Derive the per-study axis from the audits actually present.
+    study_audits = _derive_study_audits(methodology, evidence)
     verdict = _load_json(pack_dir / "verdict.json") or {}
     intervention = _load_json(pack_dir / "intervention.json") or {}
     evaluation = _load_json(pack_dir / "evaluation.json") or {}
@@ -268,9 +330,12 @@ def build_result(pack_dir: Path, *, mode: str = "platform_native") -> dict[str,
         "sources": sources,
         "evidence": evidence,
         "methodology_reviews": methodology,
+        "study_audits": study_audits,
         "conflicts": [{"reason_for_disagreement": verdict.get("reason_for_disagreement", "")}]
         if verdict.get("reason_for_disagreement") else [],
-        "applicability": verdict.get("applicability", {}),
+        # Prefer the dedicated stage-7 assessment; fall back to the verdict-embedded
+        # boundary when the run carries no separate applicability.json.
+        "applicability": _applicability(pack_dir, verdict),
         "intervention": intervention,
         "evaluation": evaluation,
         "benchmark": {},

package/scripts/check_autoresearch_invariants.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+
+def fail(message: str) -> None:
+    print(f"ERROR: {message}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def main() -> int:
+    invariants = ROOT / "references" / "scientific-invariants.md"
+    if not invariants.is_file():
+        fail("missing scientific invariants")
+    text = invariants.read_text(encoding="utf-8").lower()
+    for phrase in (
+        "optimize the research process, never the conclusion.",
+        "single writer",
+        "append-only",
+    ):
+        if phrase not in text:
+            fail(f"missing invariant: {phrase}")
+
+    registry = ROOT / "skill" / "roles" / "registry.yaml"
+    if not registry.is_file():
+        fail("missing role registry")
+    registry_text = registry.read_text(encoding="utf-8")
+    for role in ("evidence-retriever", "skeptic", "method-reviewer", "evidence-judge"):
+        if role not in registry_text:
+            fail(f"role missing: {role}")
+
+    from engine.orchestration import CanonicalWriteGuard, ExecutionPlanner
+    for level, cap in (("S", 0), ("M", 3), ("L", 6)):
+        plan = ExecutionPlanner().plan(level)
+        if level == "S" and plan.delegated_tasks:
+            fail("S must delegate zero tasks")
+        if len(plan.delegated_tasks) > cap:
+            fail(f"{level} delegated worker plan exceeds policy cap")
+        if max((len(group) for group in plan.parallel_groups), default=0) > plan.max_parallel_workers:
+            fail(f"{level} execution group exceeds max_parallel_workers")
+    try:
+        CanonicalWriteGuard().require("worker", "GraphRevision")
+        fail("single writer guard did not block worker")
+    except PermissionError:
+        pass
+
+    schema_dir = ROOT / "schemas" / "vNext"
+    required = {
+        "research-iteration.schema.json",
+        "research-strategy.schema.json",
+        "negative-search-record.schema.json",
+        "gap-priority.schema.json",
+        "task-spec.schema.json",
+        "worker-result.schema.json",
+        "execution-plan.schema.json",
+        "skill-experiment.schema.json",
+        "eval-snapshot.schema.json",
+        "autoevolve-session.schema.json",
+    }
+    missing = [name for name in required if not (schema_dir / name).is_file()]
+    if missing:
+        fail("missing schemas: " + ",".join(sorted(missing)))
+    for name in required:
+        json.loads((schema_dir / name).read_text(encoding="utf-8"))
+
+    head = os.getenv("GITHUB_HEAD_REF", "") or os.getenv("GITHUB_REF_NAME", "")
+    if head.startswith("autoresearch/"):
+        base = os.getenv("GITHUB_BASE_REF", "main")
+        subprocess.run(
+            ["git", "fetch", "origin", base, "--depth=1"],
+            cwd=ROOT,
+            check=True,
+            stdout=subprocess.DEVNULL,
+        )
+        changed = subprocess.check_output(
+            ["git", "diff", "--name-only", f"origin/{base}...HEAD"],
+            cwd=ROOT,
+            text=True,
+        ).splitlines()
+        from engine.autoevolve import ProtectedManifest
+        ok, bad = ProtectedManifest.from_repo(ROOT).validate_changes(changed)
+        if not ok:
+            fail("protected mutation on autoresearch branch: " + ",".join(bad))
+
+    print("autoresearch invariants OK")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/check_package_parity.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""check_package_parity.py - prove the shipped package matches the source tree.
+
+The upload package is a projection of this repository. If a source file changed
+and the package still carries the old bytes, reviewers receive a different
+product from the one under source control. CI previously compared only
+SKILL.md, so a renamed role file went unnoticed for a whole change set.
+
+Compares every file the shared payload allowlist ships: content must match and
+nothing may be missing. Stdlib only; exit 1 on any drift.
+"""
+from __future__ import annotations
+
+import hashlib
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+sys.path.insert(0, str(ROOT / "scripts"))
+
+PACKAGE = ROOT / "dist" / "eduevidence-submission"
+
+
+def digest(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def main() -> int:
+    if not PACKAGE.is_dir():
+        print(f"ERROR: no package at {PACKAGE}; run bash packaging/make_upload.sh")
+        return 1
+
+    from skill_payload import payload_files
+
+    expected = set(payload_files(ROOT))
+    # The manifest and the packaging notes are written by the build, not copied.
+    generated = {"submission-manifest.json", "UPLOAD-README.md", "START-HERE.md",
+                 "scp-manifest.json", "upload-layout.md", "README.zh-CN.md"}
+    expected |= {name for name in generated if (PACKAGE / name).is_file()}
+
+    missing = sorted(rel for rel in expected if not (PACKAGE / rel).is_file())
+
+    # Reverse direction: a file the package carries but the source does not is
+    # stale output from an earlier build. A one-way check cannot see that,
+    # which is how pre-rename report copies once survived inside a package.
+    unexpected = []
+    for path in sorted(PACKAGE.rglob("*")):
+        if not path.is_file():
+            continue
+        rel = path.relative_to(PACKAGE).as_posix()
+        if rel in expected or rel == "submission-manifest.json":
+            continue
+        if any(part in {"__pycache__", ".git"} for part in path.parts):
+            continue
+        if path.suffix in {".pyc", ".pyo"} or path.name == ".DS_Store":
+            continue
+        if not (ROOT / rel).exists():
+            unexpected.append(rel)
+    differing = []
+    for rel in sorted(expected):
+        source = ROOT / rel
+        shipped = PACKAGE / rel
+        if not source.is_file() or not shipped.is_file():
+            continue
+        if digest(source) != digest(shipped):
+            differing.append(rel)
+
+    if missing or differing or unexpected:
+        print("ERROR: package does not match the source tree", file=sys.stderr)
+        for rel in missing[:20]:
+            print(f"  missing from package: {rel}", file=sys.stderr)
+        for rel in differing[:20]:
+            print(f"  differs from source:  {rel}", file=sys.stderr)
+        for rel in unexpected[:20]:
+            print(f"  stale in package:     {rel}", file=sys.stderr)
+        print("  fix: bash packaging/make_upload.sh", file=sys.stderr)
+        return 1
+
+    print(f"package parity OK ({len(expected)} files byte-identical to source)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())