eduevidence 5.2.0 → 6.0.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,85 @@
+#!/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'))
+                valid = prior.get('cache_key') == cache_key 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()})
+        value = {'schema_version': 1, 'project': directory.name, 'cache_key': cache_key,
+                 'result_sha256': result_hash, 'renderer_sha256': engine_hash, '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/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/daily_evolve.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+import argparse
+import json
+from engine.autoevolve import DailyEvolutionRunner, DailyProfile
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="Run bounded branch-only EduEvidence evolution")
+    parser.add_argument("--repo", default=".")
+    parser.add_argument("--agent-command", required=True)
+    parser.add_argument("--eval-command", required=True)
+    parser.add_argument("--run-tag")
+    parser.add_argument("--max-experiments", type=int, default=20)
+    parser.add_argument("--max-cost-usd", type=float, default=5)
+    parser.add_argument("--max-wall-minutes", type=int, default=180)
+    parser.add_argument("--push-branch", action="store_true")
+    args = parser.parse_args(argv)
+    profile = DailyProfile(args.max_experiments, args.max_cost_usd, args.max_wall_minutes)
+    report = DailyEvolutionRunner(args.repo, profile=profile).run(
+        agent_command=args.agent_command,
+        eval_command=args.eval_command,
+        run_tag=args.run_tag,
+        push_branch=args.push_branch,
+    )
+    print(json.dumps(report, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())