eduevidence 5.2.0 → 6.2.0

package/engine/gaps.py

@@ -4,10 +4,15 @@ 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.
+
+`gap_id` identifies one revision-local gap artifact. `extensions.autoresearch_key`
+is a stable semantic lineage key so bounded research memory survives graph
+revisions when the same unresolved gap is re-derived.
 """
 
 from __future__ import annotations
 
+import hashlib
 import json
 from pathlib import Path
 
@@ -16,23 +21,57 @@ 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"}
+#: Gap kind -> the outcome categories that count as covering it. Categories are
+#: read from the domain registry, so a policy run classifies its outcomes with
+#: the policy buckets (effectiveness / cost / equity / feasibility / risk)
+#: instead of being measured against education vocabulary.
+GAP_KIND_CATEGORIES: dict[str, tuple[str, ...]] = {
+    "learning": ("learning",),
+    "retention": ("learning",),
+    "transfer": ("learning",),
+    "task_performance": ("task_performance",),
+    "process": ("process",),
+    "risk": ("risk",),
+    "effectiveness": ("effectiveness",),
+    "cost": ("cost",),
+    "equity": ("equity",),
+    "feasibility": ("feasibility",),
+}
+
+#: Legacy aliases accepted when a frame names its requested outcomes with older
+#: vocabulary; they resolve to a gap kind above.
+GAP_KIND_ALIASES: dict[str, str] = {
+    "long_term": "retention", "learning_retention": "retention",
+    "transfer_learning": "transfer", "far_transfer": "transfer",
+    "assignment_score": "task_performance", "task_completion": "task_performance",
+    "policy_effectiveness": "effectiveness", "cost_effectiveness": "cost",
+    "implementation_risk": "risk",
+}
+
+
+def _autoresearch_key(
+    gap_type: str,
+    *,
+    related_claims: list[str],
+    related_outcomes: list[str],
+    semantic_token: str,
+) -> str:
+    payload = {
+        "gap_type": gap_type,
+        "related_claims": sorted(related_claims),
+        "related_outcomes": sorted(related_outcomes),
+        "semantic_token": semantic_token.strip().lower(),
+    }
+    digest = hashlib.sha256(
+        json.dumps(payload, sort_keys=True, ensure_ascii=False).encode("utf-8")
+    ).hexdigest()[:20]
+    return f"KGK-{digest}"
 
 
 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.
-    """
+    """Derive structured gaps from graph coverage vs the research frame."""
     frame = frame or {}
     requested = frame.get("requested_outcomes") or []
     if not requested and frame.get("target_outcomes"):
@@ -47,59 +86,58 @@ def derive_gaps(*, store: GraphStore,
             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):
+            related_outcomes: list[str] | None = None,
+            semantic_token: str = ""):
+        related_claims = related_claims or []
+        related_outcomes = related_outcomes or []
+        key = _autoresearch_key(
+            gap_type,
+            related_claims=related_claims,
+            related_outcomes=related_outcomes,
+            semantic_token=semantic_token or reasoning,
+        )
         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 [],
+            "related_claim_ids": related_claims,
+            "related_outcome_ids": related_outcomes,
             "priority": priority,
             "reasoning": reasoning,
             "status": "open",
             "derived_from_graph_revision": rev,
-            "extensions": {},
+            "extensions": {"autoresearch_key": key},
         })
 
     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
+        label = req.get("name", "") if isinstance(req, dict) else str(req)
+        kind = GAP_KIND_ALIASES.get(req_type) or GAP_KIND_ALIASES.get(req_name)
+        if kind is None:
+            kind = req_type if req_type in GAP_KIND_CATEGORIES else req_name
+        if kind in GAP_KIND_CATEGORIES:
+            return kind, label
+        return "other", label
+
     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
+        """True when the graph already carries an outcome for this gap kind.
+
+        ``covered_types`` holds the category buckets stored on outcomes, which
+        is why this compares categories rather than V1 tokens.
+        """
+        expected = GAP_KIND_CATEGORIES.get(kind)
+        if not expected:
+            return False
+        return bool(covered_types & set(expected))
+
     seen: set[tuple[str, str]] = set()
     for req in requested:
         kind, label = _req_kind(req)
@@ -112,49 +150,70 @@ def derive_gaps(*, store: GraphStore,
         if covered_for_kind(kind):
             continue
         if kind == "retention":
-            add("missing_retention", "high",
+            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)")
+                "no retention-type measurement; task-performance coverage does "
+                "not count (RULE 3)",
+                semantic_token=f"requested_outcome:{label}",
+            )
         elif kind == "transfer":
-            add("missing_transfer", "high",
+            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)")
+                "no transfer-type measurement; AI-assisted task performance "
+                "does not count (RULE 3)",
+                semantic_token=f"requested_outcome:{label}",
+            )
         elif kind == "task_performance":
-            add("missing_outcome", "medium",
-                f"frame requests task-performance outcome {label!r} with no "
-                f"covering finding")
+            add(
+                "missing_outcome", "medium",
+                f"frame requests task-performance outcome {label!r} with no covering finding",
+                semantic_token=f"requested_outcome:{label}",
+            )
         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)")
+            add(
+                "missing_outcome", "medium",
+                f"frame requests learning outcome {label!r} with no covering learning finding; "
+                "task performance is not learning (RULE 3)",
+                semantic_token=f"requested_outcome:{label}",
+            )
         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}
+            add(
+                "missing_outcome", "medium",
+                f"frame requests outcome {label!r} with no covering finding",
+                semantic_token=f"requested_outcome:{label}",
+            )
+
+    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",
+            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, []))
+                f"({', '.join(syn.study_ids)})",
+                [syn.claim_id],
+                claim_outcomes.get(syn.claim_id, []),
+                semantic_token=f"claim:{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)
+                add(
+                    "insufficient_sample_independence", "medium",
+                    f"claim {syn.claim_id} rests on fewer than two independent studies",
+                    [syn.claim_id],
+                    claim_outcomes.get(syn.claim_id, []),
+                    semantic_token=f"claim:{syn.claim_id}",
+                )
+
+    for gap in gaps:
+        errors = validate_record("knowledge-gap", gap)
         if errors:
             raise ValueError(f"invalid gap: {errors}")
     return gaps

package/engine/ids.py

@@ -17,6 +17,8 @@ keep stable Project-local IDs across edits; version/revision metadata records
 change instead of silently re-identifying.
 """
 
+from __future__ import annotations
+
 from datetime import datetime, timezone
 import hashlib
 import secrets

package/engine/judge_pack.py

@@ -0,0 +1,65 @@
+"""Build a transparent, self-describing judge evidence pack from real artifacts."""
+from __future__ import annotations
+
+import hashlib
+import json
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from engine.project import ProjectWorkspace
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as fh:
+        for block in iter(lambda: fh.read(65536), b""):
+            h.update(block)
+    return h.hexdigest()
+
+
+def export_judge_pack(project: ProjectWorkspace, output_dir: Path) -> dict[str, Any]:
+    """Copy available project evidence without inventing unavailable claims.
+
+    The manifest lists every required judge-pack category and explicitly marks
+    missing inputs. This makes the pack suitable for review while keeping its
+    limits auditable.
+    """
+    output_dir = Path(output_dir).resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+    candidates = {
+        "project_manifest": project.path / "project.json",
+        "graph": project.path / "graph",
+        "runs": project.path / "runs",
+        "decisions": project.path / "decisions",
+        "projections": project.path / "projections",
+        "reports": project.path / "reports",
+        "pilots": project.path / "pilots",
+    }
+    copied: list[dict[str, str]] = []
+    missing: list[str] = []
+    for name, source in candidates.items():
+        target = output_dir / name
+        if source.is_file():
+            shutil.copy2(source, target)
+            copied.append({"name": name, "path": target.name, "sha256": _sha256(target)})
+        elif source.is_dir() and any(source.rglob("*")):
+            shutil.copytree(source, target, dirs_exist_ok=True)
+            for item in sorted(path for path in target.rglob("*") if path.is_file()):
+                copied.append({"name": name, "path": str(item.relative_to(output_dir)), "sha256": _sha256(item)})
+        else:
+            missing.append(name)
+    manifest = {
+        "format": "eduevidence-judge-pack/2026.09",
+        "project_id": project.project_id,
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "copied_files": copied,
+        "missing_categories": missing,
+        "limitations": [
+            "Only immutable/project-scoped artifacts available at export time are included.",
+            "Benchmark, blinded-review and usability evidence must be supplied from completed study artifacts; they are never synthesized by this export.",
+        ],
+    }
+    (output_dir / "manifest.json").write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    return manifest

package/engine/library.py

@@ -8,6 +8,8 @@ changes an existing Project's conclusions — only an explicit import/sync
 advances the Project graph.
 """
 
+from __future__ import annotations
+
 import hashlib
 import json
 import os
@@ -197,8 +199,10 @@ class ResearchLibrary:
             outcomes.append({
                 "outcome_id": oid,
                 "name": f.get("measure", oid),
-                "outcome_type": (f.get("extensions") or {}).get(
-                    "outcome_type", "learning"),
+                # No silent default: an unlabelled finding must not be filed as a
+                # learning outcome; that is how task-performance evidence used
+                # to reach the ADOPT gate on the V2 path.
+                "outcome_type": (f.get("extensions") or {}).get("outcome_type", ""),
                 "extensions": {
                     "auto_created_from_library_import": True,
                     "library_revision": lib_rev,

package/engine/library_builtin.py

@@ -42,7 +42,9 @@ from functools import lru_cache
 from pathlib import Path
 from typing import Any
 
-ROOT = Path(__file__).resolve().parent.parent
+from engine._resources import resource_root
+
+ROOT = resource_root()
 def _resolve_library_path() -> Path:
     """Repository layout first; wheel-installed share/ layout as fallback."""
     repo = ROOT / "benchmarks" / "evidence-library.json"

package/engine/living.py

@@ -43,7 +43,8 @@ from scripts.validate_schema import SchemaError, validate
 def _resolve_v4_schema_dir() -> Path:
     """Repository layout first; wheel-installed share/ layout as fallback
     (same pattern as engine/contracts._resolve_schema_dir)."""
-    repo = Path(__file__).resolve().parent.parent / "schemas" / "v4"
+    from engine._resources import resource_root
+    repo = resource_root() / "schemas" / "v4"
     if repo.is_dir():
         return repo
     import sys
@@ -226,6 +227,26 @@ def set_subscription_status(project: ProjectWorkspace, subscription_id: str,
     return subscription
 
 
+def _validated_outcome_type(value, domain: str) -> str:
+    """Outcome token from a refresh payload, validated against the registry.
+
+    A missing or unknown token raises: the living path used to default to
+    a learning outcome, which silently promoted task-performance evidence.
+    """
+    from engine.taxonomy import category_of, tokens as taxonomy_tokens
+
+    token = str(value or "").strip()
+    if not token:
+        raise ValueError(
+            "living evidence record must declare outcome_type; the engine "
+            "will not guess a category")
+    if token not in taxonomy_tokens(domain):
+        raise ValueError(
+            f"outcome_type {token!r} is not registered for domain {domain!r}")
+    category_of(domain, token)  # fail closed on a malformed taxonomy
+    return token
+
+
 def refresh(project: ProjectWorkspace, subscription_id: str, *,
             new_evidence: list[dict] | None = None,
             retriever: Callable[[dict], list[dict]] | None = None) -> dict:
@@ -298,8 +319,10 @@ def refresh(project: ProjectWorkspace, subscription_id: str, *,
 
     # ---- normalize + validate fresh evidence ---------------------------
     next_revision = store.active_revision() + 1
+    domain = str((project.manifest() or {}).get("domain") or "education")
     mutation, new_hashes, finding_ids, summary_parts = _build_mutation(
-        project, store, subscription, fresh_packets, claims, next_revision)
+        project, store, subscription, fresh_packets, claims, next_revision,
+        domain=domain)
 
     revision = store.commit(
         run_id=new_run_id(),
@@ -369,7 +392,7 @@ def _existing_drift_ids(project: ProjectWorkspace) -> set[str]:
 
 
 def _build_mutation(project, store, subscription, fresh_packets, claims,
-                    next_revision) -> tuple[GraphMutation, set[str], set[str], list[str]]:
+                    next_revision, domain: str = "education") -> tuple[GraphMutation, set[str], set[str], list[str]]:
     """Normalize + validate each fresh record and assemble one GraphMutation."""
     existing = {t: {row[_ID_KEY[t]] for row in store.read_table(t)}
                 for t in _GRAPH_TABLES}
@@ -417,6 +440,8 @@ def _build_mutation(project, store, subscription, fresh_packets, claims,
             source_upserted = True
             upserts["sources"].append(src)
 
+        # Outcome tokens are validated against the project domain registry
+        # rather than defaulted; see _validated_outcome_type().
         # --- outcome (optional; reused when the id already exists) -------
         outcome_upserted = False
         outcome = None
@@ -438,7 +463,7 @@ def _build_mutation(project, store, subscription, fresh_packets, claims,
             outcome = {
                 "outcome_id": out_id,
                 "name": outcome_pkt.get("name") or out_id[len("OUT-"):],
-                "outcome_type": outcome_pkt.get("outcome_type", "learning"),
+                "outcome_type": _validated_outcome_type(outcome_pkt.get("outcome_type"), domain),
                 "extensions": outcome_pkt.get("extensions") or {},
             }
             existing["outcomes"].add(out_id)
@@ -502,7 +527,13 @@ def _build_mutation(project, store, subscription, fresh_packets, claims,
                 f"{label}: relation_to_claim must be one of "
                 f"{sorted(_RELATION_TO_IMPLICATION)}, got {relation!r}")
         link.setdefault("decision_implication", _RELATION_TO_IMPLICATION[relation])
-        link.setdefault("directness", 2)
+        # directness decides whether this link can carry an ADOPT claim.
+        # Defaulting it to 2 (direct) would let an unclassified refresh
+        # assert direct evidence it never established, so it is required.
+        if "directness" not in link:
+            raise ValueError(
+                f"{label}: directness is required for a living-evidence link "
+                "(2 = direct evidence for the claim; supply it explicitly)")
         link.setdefault("applicability", {"scope_match": "direct"})
         link.setdefault("reasoning_note",
                         f"living evidence refresh: {subscription['subscription_id']}")

package/engine/meta_synthesis.py

@@ -21,7 +21,9 @@ from engine.ids import new_local_id
 from engine.library import ResearchLibrary
 from scripts.validate_schema import SchemaError, validate
 
-_SYNTHESIS_SCHEMA = (Path(__file__).resolve().parent.parent / "schemas" / "v3"
+from engine._resources import resource_root
+
+_SYNTHESIS_SCHEMA = (resource_root() / "schemas" / "v3"
                      / "synthesis.schema.json")
 
 

package/engine/migration.py

@@ -30,6 +30,15 @@ from engine.versions import (
 
 OUTCOME_TYPES = ("learning", "task_performance", "process", "risk")
 
+#: V1 D5 Directness (0/1/2) -> V2 link directness + applicability scope_match.
+#: Directness decides whether a link can carry an ADOPT claim, so a flat
+#: hard-coded value silently capped every migrated pack at PILOT.
+_D5_TO_DIRECTNESS = {
+    2: (2, "direct"),
+    1: (1, "partial"),
+    0: (1, "mismatch"),
+}
+
 _CLAIM_TO_IMPLICATION = {
     "support": "support_adoption",
     "contradict": "oppose_adoption",
@@ -75,6 +84,71 @@ def _map_decision_implication(ev: dict) -> str:
     return _CLAIM_TO_IMPLICATION[_map_relation(ev.get("relation_to_claim") or ev.get("direction"))]
 
 
+def _v1_effect_estimate(ev: dict) -> dict | None:
+    """Effect magnitude from a V1 record, or None when it recorded none.
+
+    V1 kept numbers either on a top-level effect_size field or inside
+    extensions.raw_result; both are real sources, and absence stays None.
+    The V2 contract is narrow (metric + raw_text required, no extra keys), so
+    a V1 magnitude is normalized instead of copied verbatim: ci_lower/ci_upper
+    become ci_low/ci_high and keys the V2 contract does not declare are kept in
+    the raw_text so nothing recorded is silently lost.
+    """
+    value = ev.get("effect_size")
+    if isinstance(value, dict) and value.get("value") is not None:
+        return _normalize_effect_estimate(value)
+    if isinstance(value, (int, float)):
+        return {"value": float(value), "source": "v1_effect_size"}
+    raw = (ev.get("extensions") or {}).get("raw_result")
+    if isinstance(raw, dict) and raw.get("value") is not None:
+        return _normalize_effect_estimate(raw)
+    return None
+
+
+def _normalize_effect_estimate(raw: dict) -> dict:
+    """Project a V1 magnitude onto the V2 effect_estimate contract."""
+    known = ("metric", "value", "unit", "ci_low", "ci_high", "p_value")
+    out: dict = {}
+    for key in known:
+        if key in raw and raw[key] is not None:
+            out[key] = raw[key]
+    for legacy, canonical in (("ci_lower", "ci_low"), ("ci_upper", "ci_high")):
+        if canonical not in out and raw.get(legacy) is not None:
+            out[canonical] = raw[legacy]
+    out.setdefault("metric", str(raw.get("source") or "v1_effect_size"))
+    extra = {k: v for k, v in raw.items()
+             if k not in known and k not in ("ci_lower", "ci_upper")
+             and v is not None}
+    text = raw.get("raw_text")
+    if not text:
+        text = json.dumps(extra, ensure_ascii=False, sort_keys=True) if extra else ""
+    out["raw_text"] = str(text)
+    return out
+
+
+def _v1_directness(ev: dict) -> tuple[int, str, bool]:
+    """Carry V1 D5 Directness across as (link directness, scope_match, recorded).
+
+    D5 is a 0/1/2 axis in the V1 evidence contract and the V2 ADOPT gate reads
+    the link's directness, so the mapping has to be explicit:
+
+        2 -> directness 2 / scope_match "direct"
+        1 -> directness 1 / scope_match "partial"
+        0 -> directness 1 / scope_match "mismatch"  (0 can never gate an ADOPT)
+
+    A missing or non-integer D5 is not silently promoted: it migrates as
+    directness 1 / scope_match "partial" and the caller records a downgrade.
+    """
+    dims = ev.get("quality_dimensions")
+    raw = dims.get("D5_directness") if isinstance(dims, dict) else None
+    if isinstance(raw, bool) or not isinstance(raw, int):
+        return 1, "partial", False
+    mapped = _D5_TO_DIRECTNESS.get(raw)
+    if mapped is None:
+        return 1, "partial", False
+    return mapped[0], mapped[1], True
+
+
 def migrate_v1_pack(pack_dir: Path, *, home: Path,
                     title: str | None = None) -> MigrationResult:
     """Import a V1 pack directory into a new V2 Project graph.
@@ -273,7 +347,10 @@ def migrate_v1_pack(pack_dir: Path, *, home: Path,
             "measure": ev.get("outcome_type") or "outcome",
             "timepoint": None,
             "effect_direction": _map_effect_direction(ev.get("effect_direction")),
-            "effect_estimate": None,
+            # Carry the magnitude across the hop instead of dropping it:
+            # a migrated pack used to report 100% not_extractable, which
+            # reads as "no evidence" rather than "not migrated".
+            "effect_estimate": _v1_effect_estimate(ev),
             "raw_result_text": ev.get("claim") or "unavailable",
             "source_locator": ev.get("source_location") or "unavailable",
             "extensions": {"v1_legacy": True},
@@ -281,6 +358,14 @@ def migrate_v1_pack(pack_dir: Path, *, home: Path,
         claim_id = claim_by_evidence.get(ev["evidence_id"], f"CLM-{ev['evidence_id']}")
         link_id = f"LNK-{ev['evidence_id']}"
 
+        directness, scope_match, d5_recorded = _v1_directness(ev)
+        if not d5_recorded:
+            report["downgrades"].append({
+                "evidence_id": ev["evidence_id"],
+                "from": "V1 quality_dimensions.D5_directness (absent or unreadable)",
+                "to": f"directness={directness}, scope_match={scope_match!r}",
+            })
+
         links.append({
 
             "evidence_link_id": link_id,
@@ -289,8 +374,8 @@ def migrate_v1_pack(pack_dir: Path, *, home: Path,
             "relation_to_claim": _map_relation(
                 ev.get("relation_to_claim") or ev.get("direction")),
             "decision_implication": _map_decision_implication(ev),
-            "directness": 1,
-            "applicability": {"scope_match": "direct"},
+            "directness": directness,
+            "applicability": {"scope_match": scope_match},
             "reasoning_note": "migrated from V1 Evidence Object",
             "created_in_revision": 1,
             "extensions": {"v1_legacy": True},