agent-apprenticeship 0.1.0

package/src/agent_apprenticeship_trace/learning.py

@@ -0,0 +1,627 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .config import Settings, get_settings
+from .env import contains_secret
+from .io import read_json, read_jsonl, write_json
+
+
+PACK_STATUSES = {"draft", "active", "reverted", "removed"}
+RESULT_LABELS = {"improved", "no_observed_change", "regressed", "inconclusive"}
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def slugify(value: str, fallback: str = "experience") -> str:
+    chars = []
+    for char in value.lower():
+        if char.isalnum():
+            chars.append(char)
+        elif chars and chars[-1] != "-":
+            chars.append("-")
+    slug = "".join(chars).strip("-")
+    return (slug or fallback)[:72]
+
+
+def repo_root() -> Path:
+    configured = os.getenv("AA_ECOSYSTEM_REPO_PATH")
+    if configured:
+        path = Path(configured).expanduser()
+        if (path / "seed_dataset").exists():
+            return path
+    try:
+        settings = get_settings()
+        if settings.ecosystem_repo_path and (settings.ecosystem_repo_path / "seed_dataset").exists():
+            return settings.ecosystem_repo_path
+    except Exception:
+        pass
+    candidates = [Path.cwd(), Path(__file__).resolve().parents[2]]
+    for candidate in candidates:
+        if (candidate / "seed_dataset").exists():
+            return candidate
+    return Path.cwd()
+
+
+def seed_dataset_root() -> Path:
+    return repo_root() / "seed_dataset"
+
+
+def seed_registry_path() -> Path:
+    root = seed_dataset_root()
+    if (root / "ecosystem_registry.jsonl").exists():
+        return root / "ecosystem_registry.jsonl"
+    return root / "ecosystem_registry.json"
+
+
+def experience_root(settings: Settings | None = None) -> Path:
+    s = settings or get_settings()
+    root = s.app_home / "experience_packs"
+    root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def _load_json_or_jsonl(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    if path.suffix == ".jsonl":
+        return [row for row in read_jsonl(path) if isinstance(row, dict)]
+    data = read_json(path)
+    if isinstance(data, list):
+        return [row for row in data if isinstance(row, dict)]
+    if isinstance(data, dict):
+        entries = data.get("entries") or data.get("bundles") or data.get("items") or data.get("contributions")
+        if isinstance(entries, list):
+            return [row for row in entries if isinstance(row, dict)]
+    return []
+
+
+def load_seed_registry() -> list[dict[str, Any]]:
+    return _load_json_or_jsonl(seed_registry_path())
+
+
+def load_contribution_registry() -> list[dict[str, Any]]:
+    root = repo_root()
+    rows: list[dict[str, Any]] = []
+    for path in [
+        root / "ecosystem" / "contributions" / "index.json",
+        root / "ecosystem" / "contributions" / "index.jsonl",
+    ]:
+        rows.extend(_load_json_or_jsonl(path))
+    normalized: list[dict[str, Any]] = []
+    for row in rows:
+        bundle_id = row.get("bundle_id")
+        if not bundle_id:
+            continue
+        out = dict(row)
+        out.setdefault("source_kind", "contribution_bundle")
+        out.setdefault("experience_source_type", "contribution_bundle")
+        for key in ["local_bundle_path", "bundle_path", "bundle_path_or_url"]:
+            value = out.get(key)
+            if value:
+                candidate = Path(str(value)).expanduser()
+                out[key] = str(candidate if candidate.is_absolute() else root / candidate)
+        if not any(out.get(key) for key in ["local_bundle_path", "bundle_path", "bundle_path_or_url"]):
+            bundle_path = root / "ecosystem" / "contributions" / "bundles" / str(bundle_id)
+            if bundle_path.exists():
+                out["local_bundle_path"] = str(bundle_path)
+        normalized.append(out)
+    return normalized
+
+
+def search_learning_sources(query: str | None = None) -> list[dict[str, Any]]:
+    query_text = (query or "").strip().lower()
+    rows = load_seed_registry() + load_contribution_registry()
+    if not query_text:
+        return rows
+    terms = [term for term in query_text.split() if term]
+    matches: list[dict[str, Any]] = []
+    for row in rows:
+        haystack = " ".join(
+            [
+                str(row.get("bundle_id") or ""),
+                str(row.get("seed_task_id") or ""),
+                str(row.get("task_id") or ""),
+                str(row.get("title") or ""),
+                " ".join(map(str, row.get("domains") or [])),
+                " ".join(map(str, row.get("subdomains") or [])),
+                str(row.get("agent_apprentice_role") or ""),
+            ]
+        ).lower()
+        if all(term in haystack for term in terms):
+            matches.append(row)
+    return matches
+
+
+def _resolve_relative(path_value: str | None) -> Path | None:
+    if not path_value:
+        return None
+    path = Path(path_value)
+    if path.is_absolute():
+        return path
+    return repo_root() / path
+
+
+def _source_id(row: dict[str, Any]) -> str:
+    return str(row.get("bundle_id") or row.get("seed_task_id") or row.get("task_id") or "source")
+
+
+def _bundle_source(path: Path) -> dict[str, Any]:
+    manifest_path = path / "contribution_manifest.json"
+    manifest = read_json(manifest_path) if manifest_path.exists() else {}
+    bundle_id = str(manifest.get("bundle_id") or path.name)
+    artifacts_index = path / "outputs" / "artifacts_index.json"
+    artifact_count = 0
+    if artifacts_index.exists():
+        try:
+            data = read_json(artifacts_index)
+            if isinstance(data, list):
+                artifact_count = len(data)
+        except Exception:
+            artifact_count = 0
+    return {
+        "source_kind": "contribution_bundle",
+        "bundle_id": bundle_id,
+        "title": manifest.get("title") or bundle_id,
+        "domains": manifest.get("domains") or [],
+        "subdomains": manifest.get("subdomains") or [],
+        "agent_apprentice_role": manifest.get("agent_apprentice_role"),
+        "task_status": manifest.get("task_status"),
+        "run_status": manifest.get("run_status"),
+        "attempt_count": manifest.get("attempts") or 0,
+        "trace_count": manifest.get("traced_steps") or 0,
+        "artifact_count": artifact_count,
+        "bundle_path": str(path),
+        "manifest_path": str(manifest_path),
+        "artifact_index_path": str(artifacts_index) if artifacts_index.exists() else None,
+    }
+
+
+def resolve_learning_source(source: str, settings: Settings | None = None) -> dict[str, Any]:
+    text = source.strip()
+    path = Path(text).expanduser()
+    if path.exists():
+        if path.is_file():
+            path = path.parent
+        return _bundle_source(path)
+    rows = load_seed_registry()
+    rows.extend(load_contribution_registry())
+    for row in rows:
+        keys = {
+            str(row.get("bundle_id") or ""),
+            str(row.get("seed_task_id") or ""),
+            str(row.get("task_id") or ""),
+        }
+        if text in keys:
+            resolved = dict(row)
+            resolved["source_kind"] = resolved.get("source_kind") or (
+                "seed_task" if resolved.get("seed_task_id") or resolved.get("task_packet_path") else "contribution_bundle"
+            )
+            if resolved["source_kind"] == "contribution_bundle":
+                bundle_path = (
+                    resolved.get("local_bundle_path")
+                    or resolved.get("bundle_path")
+                    or resolved.get("bundle_path_or_url")
+                )
+                if bundle_path and Path(str(bundle_path)).expanduser().exists():
+                    return _bundle_source(Path(str(bundle_path)).expanduser())
+            return resolved
+    s = settings or get_settings()
+    pulled = s.app_home / "ecosystem" / "bundles" / text
+    if pulled.exists():
+        return _bundle_source(pulled)
+    raise FileNotFoundError(f"Ecosystem experience source not found: {source}")
+
+
+def _safe_read(path: Path | None, limit: int = 12000) -> str:
+    if not path or not path.exists() or not path.is_file():
+        return ""
+    text = path.read_text(errors="replace")
+    return text[:limit]
+
+
+def _read_task_packet(source: dict[str, Any]) -> dict[str, Any]:
+    path = _resolve_relative(source.get("task_packet_path"))
+    if path and path.exists():
+        try:
+            data = read_json(path)
+            return data if isinstance(data, dict) else {}
+        except Exception:
+            return {}
+    return {}
+
+
+def _read_learning_lessons(source: dict[str, Any]) -> list[dict[str, Any]]:
+    lessons_root = _resolve_relative(source.get("learning_signals_path"))
+    if not lessons_root or not lessons_root.exists():
+        return []
+    lessons: list[dict[str, Any]] = []
+    for path in sorted(lessons_root.glob("*.jsonl")):
+        lessons.extend([row for row in read_jsonl(path) if isinstance(row, dict)])
+    return lessons
+
+
+def _read_rubric_reminders(source: dict[str, Any]) -> list[str]:
+    path = _resolve_relative(source.get("worker_visible_rubric_path"))
+    text = _safe_read(path, limit=6000)
+    reminders: list[str] = []
+    for line in text.splitlines():
+        line = line.strip("-*# ").strip()
+        if line and len(line) <= 220:
+            reminders.append(line)
+        if len(reminders) >= 8:
+            break
+    return reminders
+
+
+def _dedupe(values: list[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for value in values:
+        clean = str(value).strip()
+        if not clean or clean in seen:
+            continue
+        seen.add(clean)
+        out.append(clean)
+    return out
+
+
+def _extend_from_lessons(lessons: list[dict[str, Any]], key: str) -> list[str]:
+    values: list[str] = []
+    for lesson in lessons:
+        item = lesson.get(key)
+        if isinstance(item, list):
+            values.extend([str(v) for v in item])
+        elif item:
+            values.append(str(item))
+    return values
+
+
+def _trace_refs(source: dict[str, Any]) -> list[dict[str, Any]]:
+    refs = []
+    for path_value in source.get("trace_paths") or []:
+        path = _resolve_relative(str(path_value))
+        refs.append({"path": str(path_value), "exists": bool(path and path.exists())})
+    return refs
+
+
+def _source_ref(source: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "source_id": _source_id(source),
+        "experience_source_type": source.get("source_kind") or "seed_task",
+        "title": source.get("title"),
+        "domains": source.get("domains") or [],
+        "subdomains": source.get("subdomains") or [],
+        "task_packet_path": source.get("task_packet_path"),
+        "worker_visible_rubric_path": source.get("worker_visible_rubric_path"),
+        "learning_signals_path": source.get("learning_signals_path"),
+        "trace_refs": _trace_refs(source),
+        "bundle_path": source.get("bundle_path"),
+    }
+
+
+def compile_experience_pack(
+    sources: list[dict[str, Any]],
+    *,
+    title: str | None = None,
+    settings: Settings | None = None,
+) -> Path:
+    if not sources:
+        raise ValueError("At least one ecosystem experience source is required.")
+    s = settings or get_settings()
+    source_ids = [_source_id(source) for source in sources]
+    first_title = str(sources[0].get("title") or source_ids[0])
+    pack_title = title or (first_title if len(sources) == 1 else f"{first_title} + {len(sources) - 1} more")
+    digest = hashlib.sha256("|".join(source_ids + [pack_title]).encode()).hexdigest()[:10]
+    pack_id = f"aa-exp-{slugify(pack_title)}-{digest}"
+    pack_path = experience_root(s) / pack_id
+    suffix = 2
+    while pack_path.exists():
+        pack_path = experience_root(s) / f"{pack_id}-{suffix}"
+        suffix += 1
+    pack_id = pack_path.name
+    domains: list[str] = []
+    subdomains: list[str] = []
+    task_patterns: list[str] = []
+    artifact_requirements: list[str] = []
+    rubric_reminders: list[str] = []
+    common_failure_modes: list[str] = []
+    strategy_lessons: list[str] = []
+    revision_lessons: list[str] = []
+    verifier_lessons: list[str] = []
+    good_bad_signals: list[str] = []
+    original_rubric_refs: list[str] = []
+    original_learning_signal_refs: list[str] = []
+    source_refs: list[dict[str, Any]] = []
+    for source in sources:
+        domains.extend(map(str, source.get("domains") or []))
+        subdomains.extend(map(str, source.get("subdomains") or []))
+        packet = _read_task_packet(source)
+        if packet.get("task_family"):
+            task_patterns.append(str(packet["task_family"]))
+        if packet.get("expected_deliverable"):
+            artifact_requirements.append(str(packet["expected_deliverable"]))
+        artifact_requirements.extend(map(str, packet.get("deliverables") or []))
+        lessons = _read_learning_lessons(source)
+        artifact_requirements.extend(_extend_from_lessons(lessons, "artifact_requirements"))
+        common_failure_modes.extend(_extend_from_lessons(lessons, "common_failure_modes"))
+        strategy_lessons.extend(_extend_from_lessons(lessons, "strategy_lessons"))
+        revision_lessons.extend(_extend_from_lessons(lessons, "revision_lessons"))
+        verifier_lessons.extend(_extend_from_lessons(lessons, "verifier_feedback_summary"))
+        for lesson in lessons:
+            if lesson.get("lesson_summary"):
+                good_bad_signals.append(str(lesson["lesson_summary"]))
+            if lesson.get("rubric_reminders"):
+                item = lesson["rubric_reminders"]
+                if isinstance(item, list):
+                    rubric_reminders.extend(map(str, item))
+        rubric_reminders.extend(_read_rubric_reminders(source))
+        if source.get("worker_visible_rubric_path"):
+            original_rubric_refs.append(str(source["worker_visible_rubric_path"]))
+        if source.get("learning_signals_path"):
+            original_learning_signal_refs.append(str(source["learning_signals_path"]))
+        source_refs.append(_source_ref(source))
+    domains = _dedupe(domains)
+    subdomains = _dedupe(subdomains)
+    task_patterns = _dedupe(task_patterns)
+    artifact_requirements = _dedupe(artifact_requirements)[:12]
+    rubric_reminders = _dedupe(rubric_reminders)[:12]
+    common_failure_modes = _dedupe(common_failure_modes)[:12]
+    strategy_lessons = _dedupe(strategy_lessons)[:12]
+    revision_lessons = _dedupe(revision_lessons)[:12]
+    verifier_lessons = _dedupe(verifier_lessons)[:12]
+    good_bad_signals = _dedupe(good_bad_signals)[:12]
+    pack = {
+        "pack_id": pack_id,
+        "title": pack_title,
+        "source_ecosystem_ids": source_ids,
+        "experience_source_types": _dedupe([str(source.get("source_kind") or "seed_task") for source in sources]),
+        "domains": domains,
+        "subdomains": subdomains,
+        "task_patterns": task_patterns,
+        "artifact_requirements": artifact_requirements,
+        "rubric_reminders": rubric_reminders,
+        "common_failure_modes": common_failure_modes,
+        "strategy_lessons": strategy_lessons,
+        "revision_lessons": revision_lessons,
+        "verifier_evaluator_lessons": verifier_lessons,
+        "examples_of_good_bad_attempt_signals": good_bad_signals,
+        "original_trace_refs": [ref for source in sources for ref in _trace_refs(source)],
+        "original_rubric_refs": original_rubric_refs,
+        "original_learning_signal_refs": original_learning_signal_refs,
+        "created_at": utc_now(),
+        "status": "draft",
+    }
+    skill = render_skill_markdown(pack)
+    summary = render_pack_summary(pack)
+    for name, text in {"skill.md": skill, "SUMMARY.md": summary}.items():
+        if contains_secret(text):
+            raise ValueError(f"Experience Pack blocked because {name} appears to contain a secret.")
+    pack_path.mkdir(parents=True)
+    write_json(pack_path / "experience_pack.json", pack)
+    write_json(pack_path / "source_refs.json", {"sources": source_refs})
+    (pack_path / "skill.md").write_text(skill)
+    (pack_path / "SUMMARY.md").write_text(summary)
+    return pack_path
+
+
+def render_skill_markdown(pack: dict[str, Any]) -> str:
+    def bullets(key: str, fallback: str = "None captured.") -> str:
+        values = pack.get(key) or []
+        if not values:
+            return f"- {fallback}"
+        return "\n".join(f"- {value}" for value in values[:8])
+
+    return (
+        f"# Experience Pack: {pack.get('title')}\n\n"
+        "Use these concise lessons when working on similar tasks. Do not treat this as hidden answer key content.\n\n"
+        "## Key Lessons\n"
+        f"{bullets('strategy_lessons')}\n\n"
+        "## Artifact Requirements\n"
+        f"{bullets('artifact_requirements')}\n\n"
+        "## Rubric Reminders\n"
+        f"{bullets('rubric_reminders')}\n\n"
+        "## Common Failure Modes To Avoid\n"
+        f"{bullets('common_failure_modes')}\n\n"
+        "## Revision Lessons\n"
+        f"{bullets('revision_lessons')}\n\n"
+        "## Source Refs\n"
+        + "\n".join(f"- {source_id}" for source_id in pack.get("source_ecosystem_ids", [])[:12])
+        + "\n"
+    )
+
+
+def render_pack_summary(pack: dict[str, Any]) -> str:
+    return (
+        f"# {pack.get('title')}\n\n"
+        f"Pack ID: {pack.get('pack_id')}\n\n"
+        f"Status: {pack.get('status')}\n\n"
+        f"Sources: {', '.join(pack.get('source_ecosystem_ids') or [])}\n\n"
+        f"Domains: {', '.join(pack.get('domains') or []) or 'not specified'}\n\n"
+        "This Experience Pack contains compact Apprentice Agent guidance plus source references for inspection.\n"
+    )
+
+
+def load_pack(pack_id_or_path: str, settings: Settings | None = None) -> tuple[Path, dict[str, Any]]:
+    s = settings or get_settings()
+    candidate = Path(pack_id_or_path).expanduser()
+    if not candidate.exists():
+        candidate = experience_root(s) / pack_id_or_path
+    if not candidate.exists() and (experience_root(s) / "_removed" / pack_id_or_path).exists():
+        candidate = experience_root(s) / "_removed" / pack_id_or_path
+    data_path = candidate / "experience_pack.json"
+    if not data_path.exists():
+        raise FileNotFoundError(f"Experience Pack not found: {pack_id_or_path}")
+    data = read_json(data_path)
+    if not isinstance(data, dict):
+        raise ValueError(f"Invalid Experience Pack: {pack_id_or_path}")
+    return candidate, data
+
+
+def list_packs(settings: Settings | None = None, include_removed: bool = False) -> list[dict[str, Any]]:
+    root = experience_root(settings)
+    paths = [path for path in root.iterdir() if path.is_dir() and path.name != "_removed"]
+    if include_removed and (root / "_removed").exists():
+        paths.extend([path for path in (root / "_removed").iterdir() if path.is_dir()])
+    packs = []
+    for path in sorted(paths):
+        data_path = path / "experience_pack.json"
+        if data_path.exists():
+            try:
+                data = read_json(data_path)
+                if isinstance(data, dict):
+                    data = dict(data)
+                    data["path"] = str(path)
+                    packs.append(data)
+            except Exception:
+                continue
+    return packs
+
+
+def update_pack_status(pack_id: str, status: str, settings: Settings | None = None) -> Path:
+    if status not in PACK_STATUSES:
+        raise ValueError(f"Unsupported Experience Pack status: {status}")
+    path, data = load_pack(pack_id, settings)
+    data["status"] = status
+    data["updated_at"] = utc_now()
+    write_json(path / "experience_pack.json", data)
+    (path / "SUMMARY.md").write_text(render_pack_summary(data))
+    return path
+
+
+def remove_pack(pack_id: str, settings: Settings | None = None) -> Path:
+    path, data = load_pack(pack_id, settings)
+    data["status"] = "removed"
+    data["updated_at"] = utc_now()
+    write_json(path / "experience_pack.json", data)
+    removed_root = experience_root(settings) / "_removed"
+    removed_root.mkdir(exist_ok=True)
+    target = removed_root / path.name
+    if target.exists():
+        shutil.rmtree(target)
+    shutil.move(str(path), str(target))
+    return target
+
+
+def active_packs(settings: Settings | None = None) -> list[dict[str, Any]]:
+    return [pack for pack in list_packs(settings) if pack.get("status") == "active"]
+
+
+def pack_prompt_section(pack: dict[str, Any]) -> str:
+    skill = render_skill_markdown(pack)
+    lines = skill.splitlines()
+    trimmed = "\n".join(lines[:80])
+    return (
+        "\n\n---\n"
+        f"Experience Pack: {pack.get('title')}\n"
+        "Apply these lessons when useful. Keep the task's original requirements authoritative.\n\n"
+        f"{trimmed}\n"
+        "---\n"
+    )
+
+
+def resolve_packs_for_run(
+    pack_ids: list[str],
+    *,
+    use_active: bool = False,
+    no_packs: bool = False,
+    settings: Settings | None = None,
+) -> tuple[list[dict[str, Any]], str]:
+    if no_packs:
+        return [], ""
+    selected: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    s = settings or get_settings()
+    for pack_id in pack_ids:
+        path, pack = load_pack(pack_id, s)
+        status = pack.get("status")
+        if status in {"reverted", "removed"}:
+            continue
+        pack = dict(pack)
+        pack["path"] = str(path)
+        if pack.get("pack_id") not in seen:
+            seen.add(str(pack.get("pack_id")))
+            selected.append(pack)
+    if use_active:
+        for pack in active_packs(s):
+            if pack.get("pack_id") not in seen:
+                seen.add(str(pack.get("pack_id")))
+                selected.append(pack)
+    guidance = "".join(pack_prompt_section(pack) for pack in selected)
+    return selected, guidance
+
+
+def pack_run_refs(packs: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    refs = []
+    for pack in packs:
+        refs.append(
+            {
+                "pack_id": pack.get("pack_id"),
+                "title": pack.get("title"),
+                "source_refs": pack.get("source_ecosystem_ids") or [],
+                "status": pack.get("status"),
+            }
+        )
+    return refs
+
+
+def replay_instruction_for_pack(pack: dict[str, Any], settings: Settings | None = None) -> str:
+    source_ids = pack.get("source_ecosystem_ids") or []
+    if source_ids:
+        try:
+            source = resolve_learning_source(str(source_ids[0]), settings)
+            packet = _read_task_packet(source)
+            instruction = packet.get("instruction") or packet.get("task_instruction") or packet.get("normalized_instruction")
+            if instruction:
+                deliverables = packet.get("deliverables") or []
+                extra = f"\n\nRequired deliverables: {', '.join(map(str, deliverables))}" if deliverables else ""
+                return str(instruction) + extra
+        except Exception:
+            pass
+    artifacts = ", ".join(pack.get("artifact_requirements") or []) or "a concise artifact summary"
+    return f"Complete a small task inspired by {pack.get('title')}. Produce {artifacts}."
+
+
+def compare_replay(before: dict[str, Any], after: dict[str, Any]) -> dict[str, Any]:
+    before_status = before.get("task_status") or before.get("run_status")
+    after_status = after.get("task_status") or after.get("run_status")
+    before_artifacts = int(before.get("artifact_count") or 0)
+    after_artifacts = int(after.get("artifact_count") or 0)
+    label = "inconclusive"
+    if before_status != "completed" and after_status == "completed":
+        label = "improved"
+    elif before_status == "completed" and after_status != "completed":
+        label = "regressed"
+    elif before_status == after_status == "completed":
+        if after_artifacts > before_artifacts:
+            label = "improved"
+        elif after_artifacts < before_artifacts:
+            label = "regressed"
+        else:
+            label = "no_observed_change"
+    elif before_status == after_status:
+        label = "no_observed_change"
+    return {
+        "result": label,
+        "before_status": before_status,
+        "after_status": after_status,
+        "before_artifact_count": before_artifacts,
+        "after_artifact_count": after_artifacts,
+        "score_available": False,
+        "score_note": "No comparable evaluator score was available; comparison used status and artifact completeness.",
+    }
+
+
+def write_before_after_result(pack_path: Path, result: dict[str, Any]) -> Path:
+    result = dict(result)
+    result["created_at"] = utc_now()
+    write_json(pack_path / "before_after_result.json", result)
+    return pack_path / "before_after_result.json"

package/src/agent_apprenticeship_trace/lesson_extractor.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+from .schemas import LessonPack, HillclimbResult
+
+def extract_lesson(h: HillclimbResult) -> LessonPack:
+    return LessonPack(lesson_id=f'lesson_{h.task_id}', task_id=h.task_id, source_attempt_ids=[h.baseline_attempt_id,h.revised_attempt_id], lesson_summary='Use verifier and grader feedback to repair missing artifacts before revision.', strategy_lessons=['Map every output requirement to a concrete file.'], common_failure_modes=h.failed_criteria_before, rubric_reminders=h.failed_criteria_after, artifact_requirements=['Preserve package-relative artifact paths.'], verifier_feedback_summary=h.hillclimb_evidence_strength, hidden_reference_leaked=False, metadata_json={})