eduevidence 5.2.0

package/scripts/build_result.py

@@ -0,0 +1,311 @@
+#!/usr/bin/env python3
+"""build_result.py — Assemble result.json from an example research pack.
+
+result.json is the validated research-core output (总体实施计划 §27) consumed by
+the visualization layer. It aggregates the pack files:
+
+    frame.json + evidence.jsonl + methodology.json + verdict.json
+    + intervention.json + evaluation.json  (+ optional sources.jsonl)
+
+and computes the outcome-level aggregation and claim rows (Claim-Evidence
+Contract). The report layer consumes ONLY this file and never edits it.
+
+Usage:
+    python3 scripts/build_result.py --pack examples/ai-coding-assistant \
+        --out examples/ai-coding-assistant/result.json
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+# Repo-root bootstrap so `python3 scripts/build_result.py` works without venv
+# install (removed by the src-layout migration, plan item E1).
+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 _load_json(path: Path) -> dict[str, Any] | None:
+    if path.exists():
+        return json.loads(path.read_text(encoding="utf-8"))
+    return None
+
+
+def _load_jsonl(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+
+
+def _derive_source_from_evidence(ev: dict[str, Any]) -> dict[str, Any] | None:
+    """Honest source fallback (review P1-2): a real DOI in the location
+    yields tier1; otherwise the lowest authority is assumed and the record
+    is flagged source_metadata_incomplete. Never fabricates a canonical URL."""
+    from retrieval.source import parse_doi_from_url  # noqa: PLC0415
+
+    loc = (ev.get("source_location") or "").strip()
+    if not loc:
+        return None
+    doi = parse_doi_from_url(loc)
+    authority = "tier1_paper_doi" if doi else "tier5_general_web"
+    return {
+        "source_id": ev.get("source_id", ""),
+        "title": ev.get("title", ""),
+        "year": ev.get("year"),
+        "canonical_url": loc,
+        "authority_level": authority,
+        "source_location": loc,
+        "extensions": {"source_metadata_incomplete": not doi},
+    }
+
+
+NOT_CAPTURED_USAGE: dict[str, Any] = {
+    "measurement_status": "NOT_CAPTURED",
+    "input_tokens": None,
+    "output_tokens": None,
+    "cost_usd": None,
+    "latency_s": None,
+}
+
+
+def derive_provenance(sources: list[dict[str, Any]]) -> dict[str, Any]:
+    """Aggregate provenance from real Source.fetch records (P1-3).
+
+    fetched_at only appears when an actual fetch recorded it (sources[].fetch.
+    fetched_at); the result-assembly time is reported as meta.generated_at and
+    must never be passed off as a fetch time. Unknown values stay unknown.
+    """
+    fetched = [
+        s["fetch"]["fetched_at"] for s in sources
+        if isinstance(s.get("fetch"), dict) and s["fetch"].get("fetched_at")
+    ]
+    providers = sorted({
+        s["fetch"]["fetch_provider"] for s in sources
+        if isinstance(s.get("fetch"), dict) and s["fetch"].get("fetch_provider")
+    })
+    provenance: dict[str, Any] = {"search_provider": ", ".join(providers) if providers else "n/a"}
+    if fetched:
+        provenance["fetched_at"] = min(fetched)
+    return provenance
+
+
+def aggregate_outcomes(evidence: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Outcome-level aggregation keyed by effect_direction (C-1).
+
+    Outcome rows carry positive_count / negative_count / null_count (based on
+    effect_direction) — not support/contradict counts, which are claim-level
+    semantics and only belong in the claim trace (relation_to_claim).
+    """
+    by_outcome: dict[str, dict[str, Any]] = {}
+    for ev in evidence:
+        outcome = ev.get("outcome_type", "unknown")
+        row = by_outcome.setdefault(outcome, {
+            "outcome_type": outcome, "positive_count": 0,
+            "negative_count": 0, "null_count": 0, "evidence_ids": [],
+        })
+        effect = effect_direction(ev)
+        if effect == "positive":
+            row["positive_count"] += 1
+        elif effect == "negative":
+            row["negative_count"] += 1
+        else:
+            row["null_count"] += 1
+        row["evidence_ids"].append(ev.get("evidence_id", ""))
+    return [by_outcome[o] for o in OUTCOME_ORDER if o in by_outcome]
+
+
+def build_outcome_mapping(evidence: list[dict[str, Any]],
+                          frame: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Frame-declared vs evidence-covered outcome map (OPEN-2).
+
+    Every outcome type seen in the frame or in evidence gets exactly one
+    entry with directional counts (support / contradict / neutral -- never
+    mixed, consistent with the three-column Evidence Matrix) and an explicit
+    status:
+
+        supported / contested / contradicted / null_evidence_only / no_evidence
+
+    Frame-declared outcomes with no covering evidence are surfaced in
+    declared_without_evidence so a decision must disclose its gaps.
+    """
+    declared: set[str] = set()
+    for group in ("primary", "secondary", "risk"):
+        declared.update((frame or {}).get("outcomes", {}).get(group, []) or [])
+    declared.discard("")
+
+    by_outcome: dict[str, dict[str, Any]] = {}
+    for ev in evidence:
+        outcome = ev.get("outcome_type") or "unknown"
+        row = by_outcome.setdefault(outcome, {
+            "outcome_type": outcome,
+            "support_count": 0, "contradict_count": 0, "neutral_count": 0,
+            "evidence_ids": [],
+        })
+        direction = ev.get("direction", "neutral")
+        if direction == "support":
+            row["support_count"] += 1
+        elif direction == "contradict":
+            row["contradict_count"] += 1
+        else:
+            row["neutral_count"] += 1
+        if ev.get("evidence_id"):
+            row["evidence_ids"].append(ev["evidence_id"])
+
+    entries: list[dict[str, Any]] = []
+    for outcome in sorted(set(declared) | set(by_outcome)):
+        row = by_outcome.get(outcome) or {
+            "outcome_type": outcome, "support_count": 0,
+            "contradict_count": 0, "neutral_count": 0, "evidence_ids": []}
+        s, c, n = row["support_count"], row["contradict_count"], row["neutral_count"]
+        if s > 0 and c > 0:
+            status = "contested"
+        elif s > 0:
+            status = "supported"
+        elif c > 0:
+            status = "contradicted"
+        elif n > 0:
+            status = "null_evidence_only"
+        else:
+            status = "no_evidence"
+        entries.append({
+            "outcome_type": outcome,
+            "declared_in_frame": outcome in declared,
+            "status": status,
+            "support_count": s,
+            "contradict_count": c,
+            "neutral_count": n,
+            "evidence_ids": list(row["evidence_ids"]),
+        })
+
+    declared_without_evidence = sorted(d for d in declared if d not in by_outcome)
+    return {"entries": entries, "declared_without_evidence": declared_without_evidence}
+
+def build_claims(evidence: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Claim-level rows bound to evidence (Claim-Evidence Contract, A-3).
+
+    claim_id comes from the evidence objects themselves (first-class field of
+    the Evidence Contract), so Claim -> Evidence -> Source never depends on
+    render-time renumbering. Legacy evidence without claim_id falls back to a
+    deterministic C-{idx:03d} sequence.
+    """
+    claims: dict[str, dict[str, Any]] = {}
+    for idx, ev in enumerate(evidence, 1):
+        claim = ev.get("claim", "")
+        outcome = ev.get("outcome_type", "")
+        key = (claim, outcome)
+        row = claims.setdefault(key, {
+            "claim": claim, "outcome_type": outcome,
+            "claim_id": ev.get("claim_id") or f"C-{idx:03d}",
+            "evidence_ids": [], "status": "SUPPORTED",
+        })
+        row["evidence_ids"].append(ev.get("evidence_id", ""))
+        status = ev.get("status")
+        rank = {"CONTRADICT": 3, "UNSUPPORTED": 2, "DOWNGRADE_CONFIDENCE": 1}.get(status, 0)
+        if rank > {"CONTRADICT": 3, "UNSUPPORTED": 2, "DOWNGRADE_CONFIDENCE": 1}.get(row["status"], 0):
+            row["status"] = status
+    return list(claims.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")
+    verdict = _load_json(pack_dir / "verdict.json") or {}
+    intervention = _load_json(pack_dir / "intervention.json") or {}
+    evaluation = _load_json(pack_dir / "evaluation.json") or {}
+    sources = _load_jsonl(pack_dir / "sources.jsonl")
+
+    if not sources:
+        seen: dict[str, dict[str, Any]] = {}
+        for ev in evidence:
+            sid = ev.get("source_id", "")
+            if sid and sid not in seen:
+                derived = _derive_source_from_evidence(ev)
+                if derived is not None:
+                    seen[sid] = derived
+        sources = list(seen.values())
+
+    decision = verdict
+    # execution summary derived from pack (complexity via frame target/depth is optional)
+    execution = {
+        "complexity": frame.get("complexity", "M"),
+        "mode": mode,
+        "agents": [],
+        "usage": dict(NOT_CAPTURED_USAGE),
+    }
+
+    result = {
+        "meta": {
+            "skill": "eduevidence",
+            "version": ENGINE_VERSION,
+            "generated_at": datetime.now(timezone.utc).isoformat(),
+            "mode": mode,
+            "question": frame.get("question", ""),
+        },
+        "execution": execution,
+        "research_frame": frame,
+        "decision": decision,
+        "outcomes": aggregate_outcomes(evidence),
+        "outcome_mapping": build_outcome_mapping(evidence, frame),
+        "claims": build_claims(evidence),
+        "sources": sources,
+        "evidence": evidence,
+        "methodology_reviews": methodology,
+        "conflicts": [{"reason_for_disagreement": verdict.get("reason_for_disagreement", "")}]
+        if verdict.get("reason_for_disagreement") else [],
+        "applicability": verdict.get("applicability", {}),
+        "intervention": intervention,
+        "evaluation": evaluation,
+        "benchmark": {},
+        "provenance": derive_provenance(sources),
+    }
+    return result
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Assemble result.json from an example pack")
+    parser.add_argument("--pack", required=True, help="example pack directory")
+    parser.add_argument("--out", required=True, help="output result.json path")
+    parser.add_argument("--mode", choices=["platform_native", "agent_mcp_enhanced"],
+                        default="platform_native")
+    parser.add_argument("--data-origin", choices=["real", "synthetic", "hybrid", "manual_curated"],
+                        default=None,
+                        help="provenance of the pack data (plan R4); rendered as a badge in reports")
+    args = parser.parse_args()
+
+    result = build_result(Path(args.pack), mode=args.mode)
+    if args.data_origin:
+        result["meta"]["data_origin"] = args.data_origin
+        # keep the bilingual projection in lockstep with the English source
+        out = Path(args.out)
+        zh_path = out.parent / "result.zh.json"
+        if zh_path.exists():
+            zh_result = json.loads(zh_path.read_text(encoding="utf-8"))
+            zh_result.setdefault("meta", {})["data_origin"] = args.data_origin
+            zh_path.write_text(json.dumps(zh_result, ensure_ascii=False, indent=2), encoding="utf-8")
+    out = Path(args.out)
+    out.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
+    print(f"wrote {args.out} (sources={len(result['sources'])}, evidence={len(result['evidence'])}, "
+          f"claims={len(result['claims'])}, outcomes={len(result['outcomes'])})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/check_version_consistency.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Version consistency gate: engine/versions.py is the single version authority.
+
+Fails (exit 1) when the declared versions drift apart:
+
+- engine/versions.py  ENGINE_VERSION            <- authority
+- pyproject.toml      [project] version
+- package.json        version
+- CHANGELOG.md        first `## [x.y.z]` heading
+- SKILL.md            `# EduEvidence X.Y` title (major.minor only)
+
+Stdlib only; run in CI before tests.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+VERSION_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+VERSIONS_PY_RE = re.compile(r'^ENGINE_VERSION\s*=\s*"(\d+\.\d+\.\d+)"', re.M)
+PYPROJECT_RE = re.compile(r'^version\s*=\s*"(\d+\.\d+\.\d+)"', re.M)
+PACKAGE_JSON_RE = re.compile(r'"version"\s*:\s*"(\d+\.\d+\.\d+)"')
+CHANGELOG_RE = re.compile(r"^##\s*\[(\d+\.\d+\.\d+)\]", re.M)
+SKILL_TITLE_RE = re.compile(r"^#\s*EduEvidence\s+(\d+\.\d+)", re.M)
+
+
+def _read(rel: str) -> str:
+    path = REPO_ROOT / rel
+    if not path.exists():
+        return ""
+    return path.read_text(encoding="utf-8")
+
+
+def main() -> int:
+    errors: list[str] = []
+
+    m = VERSIONS_PY_RE.search(_read("engine/versions.py"))
+    if not m:
+        print("FAIL: cannot parse ENGINE_VERSION from engine/versions.py")
+        return 1
+    authoritative = m.group(1)
+    if not VERSION_RE.match(authoritative):
+        errors.append(f"engine/versions.py ENGINE_VERSION not semver: {authoritative!r}")
+
+    def check_full(label: str, found: str) -> None:
+        if found != authoritative:
+            errors.append(f"{label} = {found} != engine/versions.py {authoritative}")
+
+    def check_minor(label: str, found: str) -> None:
+        prefix = authoritative.rsplit(".", 1)[0]
+        if found != prefix:
+            errors.append(f"{label} = {found} != {prefix} (from {authoritative})")
+
+    # -- pyproject.toml ------------------------------------------------------
+    pp = PYPROJECT_RE.search(_read("pyproject.toml"))
+    if pp:
+        check_full("pyproject.toml", pp.group(1))
+    else:
+        errors.append("cannot parse version from pyproject.toml")
+
+    # -- package.json --------------------------------------------------------
+    pj = PACKAGE_JSON_RE.search(_read("package.json"))
+    if pj:
+        check_full("package.json", pj.group(1))
+    else:
+        errors.append("cannot parse version from package.json")
+
+    # -- CHANGELOG.md ---------------------------------------------------------
+    cl = CHANGELOG_RE.search(_read("CHANGELOG.md"))
+    if cl:
+        check_full("CHANGELOG.md head entry", cl.group(1))
+    else:
+        errors.append("cannot parse leading '## [x.y.z]' from CHANGELOG.md")
+
+    # -- SKILL.md (major.minor only) ------------------------------------------
+    sk = SKILL_TITLE_RE.search(_read("SKILL.md"))
+    if sk:
+        check_minor("SKILL.md title", sk.group(1))
+    else:
+        errors.append("cannot parse '# EduEvidence X.Y' title from SKILL.md")
+
+    if errors:
+        for e in errors:
+            print(f"FAIL: {e}")
+        print(f"Version authority: engine/versions.py = {authoritative}")
+        return 1
+    print(f"version consistency OK ({authoritative})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/citation_check.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""CLI: verify every DOI in a pack's sources/evidence against registries (E6).
+
+Usage:
+    python3 scripts/citation_check.py --pack examples/ai-coding-assistant-evidence
+    python3 scripts/citation_check.py --sources examples/X/sources.jsonl --out /tmp/cite.json
+
+Writes citation_check.json (+ .md) into the pack dir by default and exits 1
+when any not_found/mismatch/retracted is found unless --no-fail.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from engine.citation_check import RegistryClient, extract_dois  # noqa: E402
+
+
+def load_records(path: Path) -> list[dict]:
+    text = path.read_text(encoding="utf-8")
+    if path.suffix == ".jsonl":
+        return [json.loads(line) for line in text.splitlines() if line.strip()]
+    return [json.loads(text)]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--pack", help="example pack directory")
+    parser.add_argument("--sources", help="single sources.jsonl / evidence.jsonl")
+    parser.add_argument("--out", help="output JSON path (default <pack>/citation_check.json)")
+    parser.add_argument("--no-fail", action="store_true")
+    parser.add_argument("--write-back", action="store_true",
+                        help="inject doi_verified/retracted into the pack's sources.jsonl")
+    args = parser.parse_args()
+
+    targets: list[Path] = []
+    out_path: Path | None = None
+    if args.pack:
+        pack = Path(args.pack)
+        for name in ("sources.jsonl", "evidence.jsonl"):
+            f = pack / name
+            if f.exists():
+                targets.append(f)
+        out_path = pack / "citation_check.json"
+    elif args.sources:
+        targets.append(Path(args.sources))
+        out_path = Path(args.out) if args.out else Path("citation_check.json")
+    else:
+        parser.error("pass --pack or --sources")
+    if not targets:
+        print("no sources/evidence files found; nothing to check")
+        return 0
+
+    records: list[tuple[str, dict]] = []
+    for t in targets:
+        records.extend((t.name, rec) for rec in load_records(t))
+
+    client = RegistryClient()
+    seen: set[str] = set()
+    rows = []
+    for fname, rec in records:
+        for doi, title in extract_dois(rec):
+            if doi in seen:
+                continue
+            seen.add(doi)
+            verdict = client.check(doi, title)
+            rows.append({"file": fname, **verdict})
+            print(f"{verdict['status']:9s} retracted={verdict['retracted']!s:5s} {doi}")
+
+    bad = [r for r in rows if r["status"] != "ok" or r["retracted"]]
+    report = {
+        "generated_at": time.strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "checked": len(rows),
+        "bad": len(bad),
+        "results": rows,
+    }
+    assert out_path is not None
+    out_path.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    md = out_path.with_suffix(".md")
+    lines = ["# Citation Check", "",
+             f"生成时间：{report['generated_at']}；核验 DOI：{len(rows)}；异常：{len(bad)}", ""]
+    if bad:
+        lines += ["| DOI | 状态 | 撤稿 | 注册表标题 |", "|---|---|---|---|"]
+        for r in bad:
+            t = (r.get("registry_title") or "")[:70].replace("|", "\\|")
+            lines.append(f"| `{r['doi']}` | {r['status']} | {'⚠️ 是' if r['retracted'] else '否'} | {t} |")
+    md.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    print(f"\ncitation check -> {out_path} (bad={len(bad)})")
+
+    if args.write_back and args.pack:
+        by_doi = {r["doi"]: r for r in rows}
+        src_file = Path(args.pack) / "sources.jsonl"
+        if src_file.exists():
+            lines = []
+            changed = 0
+            for line in src_file.read_text(encoding="utf-8").splitlines():
+                if not line.strip():
+                    continue
+                rec = json.loads(line)
+                for doi, v in by_doi.items():
+                    rec_doi = (rec.get("doi") or "").strip()
+                    if rec_doi == doi or doi in json.dumps(rec):
+                        new_flags = {"doi_verified": v["doi_verified"], "retracted": v["retracted"]}
+                        if any(rec.get(k) != val for k, val in new_flags.items()):
+                            rec.update(new_flags)
+                            changed += 1
+                        break
+                lines.append(json.dumps(rec, ensure_ascii=False))
+            src_file.write_text("\n".join(lines) + "\n", encoding="utf-8")
+            print(f"write-back: {changed} source rows updated in {src_file}")
+
+    return (1 if bad else 0) if not args.no_fail else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/claim_audit.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""claim_audit.py — Citation Audit (plan section 11).
+
+Runs before final report generation. For each claim-evidence pair:
+
+    Claim exists? -> Evidence exists? -> Source exists? -> Source supports claim?
+    -> Outcome matches? -> Scope exceeds source?
+
+Failures are marked:
+    UNSUPPORTED             evidence cannot be bound to a verifiable source
+    CONTRADICT              bound evidence contradicts the claim (relation_to_claim)
+    DOWNGRADE_CONFIDENCE    claim overstates the source (scope/outcome mismatch)
+
+Citation relation is judged ONLY by relation_to_claim (via
+evidence_semantics.claim_relation) — never by effect_direction or the legacy
+direction field: a negative effect can support a negative claim.
+
+Usage:
+    python scripts/claim_audit.py --claims claims.jsonl --evidence evidence.jsonl
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from evidence_semantics import claim_relation
+
+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 load_records(path: Path) -> list[dict]:
+    records = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if line:
+            records.append(json.loads(line))
+    return records
+
+
+def audit_claim(claim: dict, evidence_by_id: dict[str, dict]) -> dict:
+    """Audit a single claim. Returns a status record."""
+    result = {
+        "claim": claim.get("claim", ""),
+        "status": "SUPPORTED",
+        "issues": [],
+    }
+
+    # 1. Claim exists?
+    if not claim.get("claim"):
+        result["status"] = "UNSUPPORTED"
+        result["issues"].append("claim is empty")
+        return result
+
+    # 2. Evidence exists?
+    evidence_ids = claim.get("evidence_ids", [])
+    if not evidence_ids:
+        result["status"] = "UNSUPPORTED"
+        result["issues"].append("no evidence_ids bound to claim")
+        return result
+
+    bound = []
+    for eid in evidence_ids:
+        ev = evidence_by_id.get(eid)
+        if ev is None:
+            result["issues"].append(f"evidence {eid} not found")
+            continue
+        bound.append(ev)
+
+    if not bound:
+        result["status"] = "UNSUPPORTED"
+        result["issues"].append("no bound evidence found in corpus")
+        return result
+
+    # 3. Source exists (source_id + source_location)
+    for ev in bound:
+        if not ev.get("source_id"):
+            result["issues"].append(f"{ev.get('evidence_id')}: missing source_id")
+        if not ev.get("source_location"):
+            result["issues"].append(f"{ev.get('evidence_id')}: missing source_location")
+
+    # 4. Source supports claim (judged ONLY by relation_to_claim; a negative
+    #    effect can support a negative claim — never use effect_direction or
+    #    the legacy direction field as a citation relation)
+    for ev in bound:
+        if claim_relation(ev) == "contradict":
+            result["issues"].append(
+                f"{ev.get('evidence_id')}: evidence contradicts claim (relation_to_claim=contradict)")
+
+    # 5. Outcome matches
+    for ev in bound:
+        outcome = ev.get("outcome_type", "")
+        if outcome not in SUPPORTED_OUTCOMES:
+            result["issues"].append(
+                f"{ev.get('evidence_id')}: unknown outcome_type {outcome!r}")
+        claimed_outcome = claim.get("outcome_type")
+        if claimed_outcome and outcome and claimed_outcome != outcome:
+            result["issues"].append(
+                f"{ev.get('evidence_id')}: outcome mismatch (claim={claimed_outcome}, evidence={outcome})")
+
+    # 6. Scope exceeds source?
+    claim_scope = claim.get("scope")
+    if claim_scope:
+        for ev in bound:
+            ev_scope = ev.get("applicability", {}).get("scope", "")
+            if ev_scope and claim_scope not in ev_scope:
+                result["issues"].append(
+                    f"{ev.get('evidence_id')}: claim scope {claim_scope!r} exceeds source scope {ev_scope!r}")
+
+    if result["issues"]:
+        if any("contradicts claim" in i for i in result["issues"]):
+            # Contradiction is the dominant signal: the claim is contradicted
+            # by its own evidence, distinct from being unverifiable.
+            result["status"] = "CONTRADICT"
+        else:
+            severe = any("missing source" in i or "not found" in i
+                         for i in result["issues"])
+            result["status"] = "UNSUPPORTED" if severe else "DOWNGRADE_CONFIDENCE"
+    return result
+
+
+def audit_claims(claims: list[dict], evidence_list: list[dict]) -> list[dict]:
+    evidence_by_id = {ev.get("evidence_id"): ev for ev in evidence_list}
+    return [audit_claim(c, evidence_by_id) for c in claims]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run the Citation Audit over claims and evidence")
+    parser.add_argument("--claims", required=True, help="claims.jsonl (each line: claim, evidence_ids, outcome_type, scope)")
+    parser.add_argument("--evidence", required=True, help="evidence.jsonl")
+    args = parser.parse_args()
+
+    claims = load_records(Path(args.claims))
+    evidence = load_records(Path(args.evidence))
+    results = audit_claims(claims, evidence)
+
+    summary = {"SUPPORTED": 0, "UNSUPPORTED": 0, "DOWNGRADE_CONFIDENCE": 0, "CONTRADICT": 0}
+    for r in results:
+        summary[r["status"]] += 1
+        if r["issues"]:
+            print(f"[{r['status']}] {r['claim']}")
+            for issue in r["issues"]:
+                print(f"    - {issue}")
+    print(json.dumps(summary, ensure_ascii=False))
+    return 0 if summary["UNSUPPORTED"] == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())