open-research-protocol 0.4.7 → 0.4.9

package/cli/orp.py

@@ -30,6 +30,7 @@ import argparse
 import datetime as dt
 import getpass
 import hashlib
+import html
 import json
 import os
 import platform
@@ -45,6 +46,7 @@ import uuid
 from urllib import error as urlerror
 from urllib import parse as urlparse
 from urllib import request as urlrequest
+import xml.etree.ElementTree as ET
 
 RUNNER_LEASE_STALE_SECONDS = 120
 
@@ -111,6 +113,8 @@ ORP_PACKAGE_NAME = _tool_package_name()
 DEFAULT_DISCOVER_PROFILE = "orp.profile.default.json"
 DEFAULT_DISCOVER_SCAN_ROOT = "orp/discovery/github"
 DEFAULT_HOSTED_BASE_URL = "https://orp.earth"
+KERNEL_SCHEMA_VERSION = "1.0.0"
+YOUTUBE_SOURCE_SCHEMA_VERSION = "1.0.0"
 
 
 class HostedApiError(RuntimeError):
@@ -335,6 +339,442 @@ def _request_hosted_sse_event(
         ) from exc
 
 
+def _http_get_text(url: str, *, headers: dict[str, str] | None = None, timeout_sec: int = 20) -> str:
+    request = urlrequest.Request(url, headers=headers or {}, method="GET")
+    try:
+        with urlrequest.urlopen(request, timeout=timeout_sec) as response:
+            return response.read().decode("utf-8", errors="replace")
+    except urlerror.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace").strip()
+        raise RuntimeError(f"HTTP {exc.code} while fetching {url}: {body or exc.reason}") from exc
+    except urlerror.URLError as exc:
+        raise RuntimeError(f"Could not reach {url}: {exc.reason}") from exc
+
+
+def _http_get_json(url: str, *, headers: dict[str, str] | None = None, timeout_sec: int = 20) -> dict[str, Any]:
+    text = _http_get_text(url, headers=headers, timeout_sec=timeout_sec)
+    try:
+        payload = json.loads(text)
+    except Exception as exc:
+        raise RuntimeError(f"Response from {url} was not valid JSON.") from exc
+    if isinstance(payload, dict):
+        return payload
+    raise RuntimeError(f"Response from {url} was not a JSON object.")
+
+
+def _youtube_request_headers() -> dict[str, str]:
+    return {
+        "User-Agent": (
+            "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+            "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0 Safari/537.36"
+        ),
+        "Accept-Language": "en-US,en;q=0.9",
+    }
+
+
+def _youtube_source_schema_path() -> Path:
+    return Path(__file__).resolve().parent.parent / "spec" / "v1" / "youtube-source.schema.json"
+
+
+def _youtube_video_id_from_url(raw_url: str) -> str:
+    text = str(raw_url or "").strip()
+    if not text:
+        raise RuntimeError("YouTube URL is required.")
+    if re.fullmatch(r"[\w-]{11}", text):
+        return text
+
+    parsed = urlparse.urlparse(text)
+    host = parsed.netloc.lower()
+    path_parts = [part for part in parsed.path.split("/") if part]
+    if host.endswith("youtu.be"):
+        if path_parts:
+            return path_parts[0]
+    if any(host.endswith(suffix) for suffix in ("youtube.com", "youtube-nocookie.com", "music.youtube.com")):
+        if parsed.path == "/watch":
+            video_id = urlparse.parse_qs(parsed.query).get("v", [""])[0].strip()
+            if video_id:
+                return video_id
+        if len(path_parts) >= 2 and path_parts[0] in {"embed", "shorts", "live", "v"}:
+            return path_parts[1]
+    raise RuntimeError(f"Could not extract a YouTube video id from: {text}")
+
+
+def _youtube_canonical_url(video_id: str) -> str:
+    return f"https://www.youtube.com/watch?v={video_id}"
+
+
+def _extract_json_object_after_marker(text: str, marker: str) -> dict[str, Any] | None:
+    index = text.find(marker)
+    if index < 0:
+        return None
+    start = text.find("{", index)
+    if start < 0:
+        return None
+    depth = 0
+    in_string = False
+    escaped = False
+    for pos in range(start, len(text)):
+        ch = text[pos]
+        if in_string:
+            if escaped:
+                escaped = False
+            elif ch == "\\":
+                escaped = True
+            elif ch == '"':
+                in_string = False
+            continue
+        if ch == '"':
+            in_string = True
+            continue
+        if ch == "{":
+            depth += 1
+            continue
+        if ch == "}":
+            depth -= 1
+            if depth == 0:
+                candidate = text[start : pos + 1]
+                try:
+                    payload = json.loads(candidate)
+                except Exception:
+                    return None
+                return payload if isinstance(payload, dict) else None
+    return None
+
+
+def _youtube_track_label(track: dict[str, Any]) -> str:
+    name = track.get("name")
+    if isinstance(name, dict):
+        simple = str(name.get("simpleText", "")).strip()
+        if simple:
+            return simple
+        runs = name.get("runs")
+        if isinstance(runs, list):
+            pieces = [
+                str(row.get("text", "")).strip()
+                for row in runs
+                if isinstance(row, dict) and str(row.get("text", "")).strip()
+            ]
+            if pieces:
+                return "".join(pieces)
+    return str(track.get("languageCode", "")).strip()
+
+
+def _pick_youtube_caption_track(tracks: list[dict[str, Any]], preferred_lang: str = "") -> dict[str, Any] | None:
+    if not tracks:
+        return None
+    preferred = str(preferred_lang or "").strip().lower()
+
+    def score(track: dict[str, Any]) -> tuple[int, int]:
+        code = str(track.get("languageCode", "")).strip().lower()
+        kind = str(track.get("kind", "")).strip().lower()
+        auto = 1 if kind == "asr" else 0
+        exact = 1 if preferred and code == preferred else 0
+        prefix = 1 if preferred and code.startswith(preferred + "-") else 0
+        english = 1 if code.startswith("en") else 0
+        return (exact * 100 + prefix * 80 + english * 20 - auto * 5, -auto)
+
+    ranked = sorted(tracks, key=score, reverse=True)
+    return ranked[0] if ranked else None
+
+
+def _youtube_add_query_param(url: str, key: str, value: str) -> str:
+    parsed = urlparse.urlsplit(url)
+    query = dict(urlparse.parse_qsl(parsed.query, keep_blank_values=True))
+    query[key] = value
+    return urlparse.urlunsplit(
+        (
+            parsed.scheme,
+            parsed.netloc,
+            parsed.path,
+            urlparse.urlencode(query),
+            parsed.fragment,
+        )
+    )
+
+
+def _parse_youtube_transcript_json3(payload: dict[str, Any]) -> tuple[str, list[dict[str, Any]]]:
+    events = payload.get("events")
+    if not isinstance(events, list):
+        return ("", [])
+    segments: list[dict[str, Any]] = []
+    for event in events:
+        if not isinstance(event, dict):
+            continue
+        segs = event.get("segs")
+        if not isinstance(segs, list):
+            continue
+        pieces: list[str] = []
+        for seg in segs:
+            if not isinstance(seg, dict):
+                continue
+            text = html.unescape(str(seg.get("utf8", "")))
+            if text:
+                pieces.append(text)
+        merged = re.sub(r"\s+", " ", "".join(pieces)).strip()
+        if not merged:
+            continue
+        segments.append(
+            {
+                "start_ms": int(event.get("tStartMs", 0) or 0),
+                "duration_ms": int(event.get("dDurationMs", 0) or 0),
+                "text": merged,
+            }
+        )
+    transcript_text = "\n".join(str(row["text"]) for row in segments)
+    return transcript_text, segments
+
+
+def _parse_youtube_transcript_xml(text: str) -> tuple[str, list[dict[str, Any]]]:
+    try:
+        root = ET.fromstring(text)
+    except Exception:
+        return ("", [])
+    segments: list[dict[str, Any]] = []
+    for node in root.findall(".//text"):
+        body = html.unescape("".join(node.itertext() or []))
+        body = re.sub(r"\s+", " ", body).strip()
+        if not body:
+            continue
+        start = float(node.attrib.get("start", "0") or "0")
+        duration = float(node.attrib.get("dur", "0") or "0")
+        segments.append(
+            {
+                "start_ms": int(start * 1000),
+                "duration_ms": int(duration * 1000),
+                "text": body,
+            }
+        )
+    transcript_text = "\n".join(str(row["text"]) for row in segments)
+    return transcript_text, segments
+
+
+def _youtube_fetch_oembed(canonical_url: str) -> dict[str, Any]:
+    endpoint = "https://www.youtube.com/oembed?" + urlparse.urlencode({"url": canonical_url, "format": "json"})
+    try:
+        return _http_get_json(endpoint, headers=_youtube_request_headers(), timeout_sec=20)
+    except Exception:
+        return {}
+
+
+def _youtube_fetch_watch_state(video_id: str) -> dict[str, Any]:
+    url = _youtube_canonical_url(video_id) + "&hl=en&persist_hl=1"
+    html_text = _http_get_text(url, headers=_youtube_request_headers(), timeout_sec=25)
+    markers = [
+        "var ytInitialPlayerResponse = ",
+        "ytInitialPlayerResponse = ",
+        "window['ytInitialPlayerResponse'] = ",
+        'window["ytInitialPlayerResponse"] = ',
+    ]
+    player_response: dict[str, Any] | None = None
+    for marker in markers:
+        player_response = _extract_json_object_after_marker(html_text, marker)
+        if player_response:
+            break
+    if not player_response:
+        raise RuntimeError("Could not parse YouTube player response from the watch page.")
+    captions = (
+        player_response.get("captions", {})
+        .get("playerCaptionsTracklistRenderer", {})
+        .get("captionTracks", [])
+    )
+    return {
+        "player_response": player_response,
+        "video_details": player_response.get("videoDetails", {}) if isinstance(player_response.get("videoDetails"), dict) else {},
+        "microformat": (
+            player_response.get("microformat", {}).get("playerMicroformatRenderer", {})
+            if isinstance(player_response.get("microformat"), dict)
+            else {}
+        ),
+        "playability_status": (
+            player_response.get("playabilityStatus", {})
+            if isinstance(player_response.get("playabilityStatus"), dict)
+            else {}
+        ),
+        "caption_tracks": captions if isinstance(captions, list) else [],
+    }
+
+
+def _youtube_fetch_transcript_from_track(track: dict[str, Any]) -> tuple[str, list[dict[str, Any]], str]:
+    base_url = str(track.get("baseUrl", "")).strip()
+    if not base_url:
+        return ("", [], "missing_track_url")
+    json3_url = _youtube_add_query_param(base_url, "fmt", "json3")
+    try:
+        payload = _http_get_json(json3_url, headers=_youtube_request_headers(), timeout_sec=25)
+        transcript_text, segments = _parse_youtube_transcript_json3(payload)
+        if transcript_text:
+            return transcript_text, segments, "json3"
+    except Exception:
+        pass
+    try:
+        xml_text = _http_get_text(base_url, headers=_youtube_request_headers(), timeout_sec=25)
+        transcript_text, segments = _parse_youtube_transcript_xml(xml_text)
+        if transcript_text:
+            return transcript_text, segments, "xml"
+    except Exception:
+        pass
+    return ("", [], "unavailable")
+
+
+def _youtube_text_bundle(payload: dict[str, Any]) -> str:
+    parts: list[str] = []
+    title = str(payload.get("title", "")).strip()
+    if title:
+        parts.append(f"Title: {title}")
+    author_name = str(payload.get("author_name", "")).strip()
+    if author_name:
+        parts.append(f"Author: {author_name}")
+    duration_seconds = payload.get("duration_seconds")
+    if isinstance(duration_seconds, int) and duration_seconds > 0:
+        parts.append(f"Duration seconds: {duration_seconds}")
+    description = str(payload.get("description", "")).strip()
+    if description:
+        parts.append("Description:\n" + description)
+    transcript_text = str(payload.get("transcript_text", "")).strip()
+    if transcript_text:
+        parts.append("Transcript:\n" + transcript_text)
+    return "\n\n".join(parts)
+
+
+def _youtube_inspect_payload(raw_url: str, preferred_lang: str = "") -> dict[str, Any]:
+    video_id = _youtube_video_id_from_url(raw_url)
+    canonical_url = _youtube_canonical_url(video_id)
+    warnings: list[str] = []
+    oembed = _youtube_fetch_oembed(canonical_url)
+
+    watch_state: dict[str, Any] = {}
+    try:
+        watch_state = _youtube_fetch_watch_state(video_id)
+    except Exception as exc:
+        warnings.append(str(exc))
+
+    video_details = watch_state.get("video_details", {}) if isinstance(watch_state.get("video_details"), dict) else {}
+    microformat = watch_state.get("microformat", {}) if isinstance(watch_state.get("microformat"), dict) else {}
+    playability = watch_state.get("playability_status", {}) if isinstance(watch_state.get("playability_status"), dict) else {}
+    tracks = [row for row in watch_state.get("caption_tracks", []) if isinstance(row, dict)]
+    chosen_track = _pick_youtube_caption_track(tracks, preferred_lang)
+    transcript_text = ""
+    transcript_segments: list[dict[str, Any]] = []
+    transcript_fetch_mode = "none"
+    transcript_available = False
+    transcript_language = ""
+    transcript_track_name = ""
+    transcript_kind = "none"
+    if chosen_track is not None:
+        transcript_text, transcript_segments, transcript_fetch_mode = _youtube_fetch_transcript_from_track(chosen_track)
+        transcript_available = bool(transcript_text.strip())
+        transcript_language = str(chosen_track.get("languageCode", "")).strip()
+        transcript_track_name = _youtube_track_label(chosen_track)
+        transcript_kind = "auto" if str(chosen_track.get("kind", "")).strip().lower() == "asr" else "manual"
+        if not transcript_available:
+            warnings.append("A caption track was found, but transcript text could not be fetched.")
+    elif watch_state:
+        warnings.append("No caption tracks were available for this video.")
+
+    title = str(video_details.get("title") or oembed.get("title") or "").strip()
+    author_name = str(video_details.get("author") or oembed.get("author_name") or "").strip()
+    author_url = str(oembed.get("author_url") or "").strip()
+    thumbnail_url = str(oembed.get("thumbnail_url") or "").strip()
+    description = str(video_details.get("shortDescription") or microformat.get("description", {}).get("simpleText", "") or "").strip()
+    channel_id = str(video_details.get("channelId") or "").strip()
+    duration_seconds = 0
+    raw_duration = video_details.get("lengthSeconds")
+    if isinstance(raw_duration, str) and raw_duration.isdigit():
+        duration_seconds = int(raw_duration)
+    published_at = str(microformat.get("publishDate") or "").strip()
+    payload = {
+        "schema_version": YOUTUBE_SOURCE_SCHEMA_VERSION,
+        "kind": "youtube_source",
+        "retrieved_at_utc": _now_utc(),
+        "source_url": str(raw_url).strip(),
+        "canonical_url": canonical_url,
+        "video_id": video_id,
+        "title": title,
+        "author_name": author_name,
+        "author_url": author_url,
+        "thumbnail_url": thumbnail_url,
+        "channel_id": channel_id,
+        "description": description,
+        "duration_seconds": duration_seconds or None,
+        "published_at": published_at,
+        "playability_status": str(playability.get("status", "")).strip(),
+        "transcript_available": transcript_available,
+        "transcript_language": transcript_language,
+        "transcript_track_name": transcript_track_name,
+        "transcript_kind": transcript_kind,
+        "transcript_fetch_mode": transcript_fetch_mode,
+        "transcript_text": transcript_text,
+        "transcript_segments": transcript_segments,
+        "warnings": _unique_strings(warnings),
+    }
+    payload["text_bundle"] = _youtube_text_bundle(payload)
+    return payload
+
+
+def _default_youtube_artifact_path(repo_root: Path, video_id: str) -> Path:
+    return repo_root / "orp" / "external" / "youtube" / f"{video_id}.json"
+
+
+def cmd_youtube_inspect(args: argparse.Namespace) -> int:
+    repo_root = Path(args.repo_root).resolve()
+    preferred_lang = str(getattr(args, "lang", "") or "").strip()
+    payload = _youtube_inspect_payload(args.url, preferred_lang=preferred_lang)
+
+    out_raw = str(getattr(args, "out", "") or "").strip()
+    should_save = bool(getattr(args, "save", False) or out_raw)
+    out_path: Path | None = None
+    emitted_format = ""
+    if should_save:
+        if out_raw:
+            out_path = _resolve_cli_path(out_raw, repo_root)
+        else:
+            _ensure_dirs(repo_root)
+            out_path = _default_youtube_artifact_path(repo_root, str(payload.get("video_id", "")).strip())
+        if out_path.exists() and not bool(getattr(args, "force", False)):
+            raise RuntimeError(
+                f"output path already exists: {_path_for_state(out_path, repo_root)}. Use --force to overwrite."
+            )
+        emitted_format = _write_structured_payload(out_path, payload, format_hint=str(getattr(args, "format", "") or ""))
+
+    result = {
+        "ok": True,
+        "saved": out_path is not None,
+        "path": _path_for_state(out_path, repo_root) if out_path is not None else "",
+        "format": emitted_format,
+        "schema_path": "spec/v1/youtube-source.schema.json",
+        "source": payload,
+    }
+    if args.json_output:
+        _print_json(result)
+    else:
+        _print_pairs(
+            [
+                ("ok", "true"),
+                ("video.id", str(payload.get("video_id", "")).strip()),
+                ("video.title", str(payload.get("title", "")).strip()),
+                ("video.author", str(payload.get("author_name", "")).strip()),
+                ("video.duration_seconds", payload.get("duration_seconds") or ""),
+                ("transcript.available", str(bool(payload.get("transcript_available", False))).lower()),
+                ("transcript.language", str(payload.get("transcript_language", "")).strip()),
+                ("transcript.kind", str(payload.get("transcript_kind", "")).strip()),
+                ("saved", str(bool(out_path is not None)).lower()),
+                ("path", _path_for_state(out_path, repo_root) if out_path is not None else ""),
+            ]
+        )
+        bundle = str(payload.get("text_bundle", "")).strip()
+        warnings = payload.get("warnings", []) if isinstance(payload.get("warnings"), list) else []
+        if bundle:
+            print("")
+            print(bundle)
+        if warnings:
+            print("")
+            for warning in warnings:
+                text = str(warning).strip()
+                if text:
+                    print(f"warning={text}")
+    return 0
+
+
 def _runner_transport_mode(args: argparse.Namespace) -> str:
     mode = str(getattr(args, "transport", "auto") or "auto").strip().lower()
     if mode in {"poll", "sse"}:
@@ -4802,6 +5242,11 @@ def _unique_strings(values: list[str]) -> list[str]:
     return out
 
 
+def _slug_token(text: str, *, fallback: str = "item") -> str:
+    token = re.sub(r"[^a-z0-9]+", "-", str(text or "").strip().lower()).strip("-")
+    return token or fallback
+
+
 def _resolve_config_paths(raw_paths: Any, repo_root: Path, vars_map: dict[str, str]) -> list[str]:
     out: list[str] = []
     if not isinstance(raw_paths, list):
@@ -5138,6 +5583,9 @@ def _about_payload() -> dict[str, Any]:
             "config": "spec/v1/orp.config.schema.json",
             "packet": "spec/v1/packet.schema.json",
             "kernel": "spec/v1/kernel.schema.json",
+            "kernel_proposal": "spec/v1/kernel-proposal.schema.json",
+            "kernel_extension": "spec/v1/kernel-extension.schema.json",
+            "youtube_source": "spec/v1/youtube-source.schema.json",
             "profile_pack": "spec/v1/profile-pack.schema.json",
             "link_project": "spec/v1/link-project.schema.json",
             "link_session": "spec/v1/link-session.schema.json",
@@ -5147,10 +5595,20 @@ def _about_payload() -> dict[str, Any]:
         "abilities": [
             {
                 "id": "kernel",
-                "description": "Reasoning-kernel artifact scaffolding and validation for promotable repository truth.",
+                "description": "Reasoning-kernel artifact scaffolding, validation, observation, proposal, and migration for promotable repository truth.",
                 "entrypoints": [
                     ["kernel", "validate"],
                     ["kernel", "scaffold"],
+                    ["kernel", "stats"],
+                    ["kernel", "propose"],
+                    ["kernel", "migrate"],
+                ],
+            },
+            {
+                "id": "youtube",
+                "description": "Public YouTube metadata and transcript ingestion for agent-readable external source context.",
+                "entrypoints": [
+                    ["youtube", "inspect"],
                 ],
             },
             {
@@ -5243,6 +5701,10 @@ def _about_payload() -> dict[str, Any]:
             {"name": "about", "path": ["about"], "json_output": True},
             {"name": "kernel_validate", "path": ["kernel", "validate"], "json_output": True},
             {"name": "kernel_scaffold", "path": ["kernel", "scaffold"], "json_output": True},
+            {"name": "kernel_stats", "path": ["kernel", "stats"], "json_output": True},
+            {"name": "kernel_propose", "path": ["kernel", "propose"], "json_output": True},
+            {"name": "kernel_migrate", "path": ["kernel", "migrate"], "json_output": True},
+            {"name": "youtube_inspect", "path": ["youtube", "inspect"], "json_output": True},
             {"name": "auth_login", "path": ["auth", "login"], "json_output": True},
             {"name": "auth_verify", "path": ["auth", "verify"], "json_output": True},
             {"name": "auth_logout", "path": ["auth", "logout"], "json_output": True},
@@ -5311,6 +5773,8 @@ def _about_payload() -> dict[str, Any]:
             "Canonical evidence lives in repo artifact paths outside ORP docs.",
             "Default CLI output is human-readable; listed commands with json_output=true also support --json.",
             "Reasoning-kernel artifacts shape promotable repository truth for tasks, decisions, hypotheses, experiments, checkpoints, policies, and results.",
+            "Kernel evolution in ORP should stay explicit: observe real usage, propose changes, and migrate artifacts through versioned CLI surfaces rather than silent agent mutation.",
+            "YouTube inspection is a built-in ORP ability exposed through `orp youtube inspect`, returning public metadata and caption transcript text when available.",
             "Discovery profiles in ORP are portable search-intent files managed directly by ORP.",
             "Collaboration is a built-in ORP ability exposed through `orp collaborate ...`.",
             "Project/session linking is a built-in ORP ability exposed through `orp link ...` and stored machine-locally under `.git/orp/link/`.",
@@ -5420,6 +5884,10 @@ def _home_payload(repo_root: Path, config_arg: str) -> dict[str, Any]:
             "label": "Inspect the current hosted workspace identity",
             "command": "orp whoami --json",
         },
+        {
+            "label": "Inspect a YouTube video and public transcript for agent context",
+            "command": "orp youtube inspect https://www.youtube.com/watch?v=<video_id> --json",
+        },
         {
             "label": "List hosted ideas in the current workspace",
             "command": "orp ideas list --json",
@@ -5507,13 +5975,20 @@ def _home_payload(repo_root: Path, config_arg: str) -> dict[str, Any]:
         )
         quick_actions.insert(
             5,
+            {
+                "label": "Inspect kernel validation pressure across recorded runs",
+                "command": "orp kernel stats --json",
+            },
+        )
+        quick_actions.insert(
+            6,
             {
                 "label": "Mark the repo locally ready after validation",
                 "command": "orp ready --json",
             },
         )
         quick_actions.insert(
-            6,
+            7,
             {
                 "label": "Inspect local project/session link state",
                 "command": "orp link status --json",
@@ -7256,27 +7731,280 @@ def _gate_map(config: dict[str, Any]) -> dict[str, dict[str, Any]]:
     return out
 
 
-KERNEL_ARTIFACT_CLASS_REQUIREMENTS: dict[str, list[str]] = {
-    "task": ["object", "goal", "boundary", "constraints", "success_criteria"],
-    "decision": ["question", "chosen_path", "rejected_alternatives", "rationale", "consequences"],
-    "hypothesis": ["claim", "boundary", "assumptions", "test_path", "falsifiers"],
-    "experiment": ["objective", "method", "inputs", "outputs", "evidence_expectations", "interpretation_limits"],
-    "checkpoint": ["completed_unit", "current_state", "risks", "next_handoff_target", "artifact_refs"],
-    "policy": ["scope", "rule", "rationale", "invariants", "enforcement_surface"],
-    "result": ["claim", "evidence_paths", "status", "interpretation_limits", "next_follow_up"],
-}
+def _kernel_schema_path() -> Path:
+    return Path(__file__).resolve().parent.parent / "spec" / "v1" / "kernel.schema.json"
 
 
-def _kernel_field_present(value: Any) -> bool:
-    if isinstance(value, str):
-        return bool(value.strip())
-    if isinstance(value, list):
-        return any(_kernel_field_present(item) for item in value)
-    if isinstance(value, dict):
-        return len(value) > 0
+def _kernel_proposal_schema_path() -> Path:
+    return Path(__file__).resolve().parent.parent / "spec" / "v1" / "kernel-proposal.schema.json"
+
+
+def _kernel_extension_schema_path() -> Path:
+    return Path(__file__).resolve().parent.parent / "spec" / "v1" / "kernel-extension.schema.json"
+
+
+def _load_kernel_schema() -> dict[str, Any]:
+    path = _kernel_schema_path()
+    if not path.exists():
+        raise RuntimeError(f"kernel schema is missing: {path}")
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise RuntimeError("kernel schema root must be an object")
+    return payload
+
+
+def _kernel_schema_metadata() -> tuple[dict[str, list[str]], dict[str, dict[str, Any]], set[str], list[str]]:
+    schema = _load_kernel_schema()
+    properties = schema.get("properties")
+    if not isinstance(properties, dict):
+        raise RuntimeError("kernel schema is missing object properties")
+    ordered_fields = [str(field).strip() for field in properties.keys() if str(field).strip()]
+
+    field_kinds: dict[str, dict[str, Any]] = {}
+    for field, raw in properties.items():
+        if not isinstance(raw, dict):
+            continue
+        if "const" in raw:
+            field_kinds[field] = {"kind": "const", "value": raw.get("const")}
+            continue
+        if "enum" in raw and isinstance(raw.get("enum"), list):
+            field_kinds[field] = {"kind": "enum", "value": list(raw.get("enum", []))}
+            continue
+        ref = raw.get("$ref")
+        if isinstance(ref, str) and ref.startswith("#/$defs/"):
+            field_kinds[field] = {"kind": ref.split("/")[-1]}
+
+    requirements: dict[str, list[str]] = {}
+    raw_all_of = schema.get("allOf")
+    if isinstance(raw_all_of, list):
+        for clause in raw_all_of:
+            if not isinstance(clause, dict):
+                continue
+            raw_if = clause.get("if")
+            raw_then = clause.get("then")
+            if not isinstance(raw_if, dict) or not isinstance(raw_then, dict):
+                continue
+            const = (
+                raw_if.get("properties", {})
+                .get("artifact_class", {})
+                .get("const")
+            )
+            required_fields = raw_then.get("required")
+            if isinstance(const, str) and isinstance(required_fields, list):
+                requirements[const] = [
+                    str(field).strip()
+                    for field in required_fields
+                    if isinstance(field, str) and str(field).strip()
+                ]
+    return requirements, field_kinds, set(field_kinds.keys()), ordered_fields
+
+
+(
+    KERNEL_ARTIFACT_CLASS_REQUIREMENTS,
+    KERNEL_FIELD_KINDS,
+    KERNEL_ALLOWED_FIELDS,
+    KERNEL_FIELD_ORDER,
+) = _kernel_schema_metadata()
+
+
+def _kernel_ordered_fields_for_class(artifact_class: str, present_fields: Sequence[str] | None = None) -> list[str]:
+    ordered: list[str] = ["schema_version", "artifact_class"]
+    required_fields = KERNEL_ARTIFACT_CLASS_REQUIREMENTS.get(str(artifact_class).strip(), [])
+    for field in required_fields:
+        if field not in ordered:
+            ordered.append(field)
+    for field in KERNEL_FIELD_ORDER:
+        if field not in ordered:
+            ordered.append(field)
+    if present_fields is None:
+        return ordered
+    present_set = {str(field).strip() for field in present_fields if str(field).strip()}
+    return [field for field in ordered if field in present_set]
+
+
+def _kernel_text_valid(value: Any) -> bool:
+    return isinstance(value, str) and bool(value.strip())
+
+
+def _kernel_text_list_valid(value: Any) -> bool:
+    return isinstance(value, list) and len(value) > 0 and all(_kernel_text_valid(item) for item in value)
+
+
+def _kernel_field_present(field: str, value: Any) -> bool:
+    kind = str(KERNEL_FIELD_KINDS.get(field, {}).get("kind", ""))
+    if kind == "non_empty_text":
+        return _kernel_text_valid(value)
+    if kind == "text_list":
+        return _kernel_text_list_valid(value)
+    if kind == "text_or_text_list":
+        return _kernel_text_valid(value) or _kernel_text_list_valid(value)
+    if kind == "const":
+        return value is not None
+    if kind == "enum":
+        return value is not None
     return value is not None
 
 
+def _kernel_field_shape_issues(field: str, value: Any) -> list[str]:
+    meta = KERNEL_FIELD_KINDS.get(field, {})
+    kind = str(meta.get("kind", ""))
+    if kind == "const":
+        expected = meta.get("value")
+        return [] if value == expected else [f"must equal `{expected}`."]
+    if kind == "enum":
+        allowed = [str(x) for x in meta.get("value", [])]
+        return [] if value in allowed else [f"must be one of: {', '.join(allowed)}."]
+    if kind == "non_empty_text":
+        return [] if _kernel_text_valid(value) else ["must be a non-empty string."]
+    if kind == "text_list":
+        return [] if _kernel_text_list_valid(value) else ["must be a non-empty list of non-empty strings."]
+    if kind == "text_or_text_list":
+        return [] if (_kernel_text_valid(value) or _kernel_text_list_valid(value)) else [
+            "must be a non-empty string or a non-empty list of non-empty strings."
+        ]
+    return []
+
+
+def _validate_kernel_payload(
+    payload: dict[str, Any],
+    *,
+    expected_class: str = "",
+    extra_required_fields: Sequence[str] = (),
+) -> dict[str, Any]:
+    artifact_issues: list[str] = []
+    missing_fields: list[str] = []
+
+    for field in sorted(str(key) for key in payload.keys() if str(key) not in KERNEL_ALLOWED_FIELDS):
+        artifact_issues.append(f"unexpected field: `{field}`.")
+
+    schema_version = payload.get("schema_version")
+    artifact_issues.extend(
+        [f"field `schema_version` {issue}" for issue in _kernel_field_shape_issues("schema_version", schema_version)]
+    )
+
+    actual_class = str(payload.get("artifact_class", "")).strip()
+    artifact_issues.extend(
+        [f"field `artifact_class` {issue}" for issue in _kernel_field_shape_issues("artifact_class", payload.get("artifact_class"))]
+    )
+    if actual_class not in KERNEL_ARTIFACT_CLASS_REQUIREMENTS:
+        artifact_issues.append(f"unsupported artifact_class: {actual_class or '(missing)'}.")
+
+    if expected_class and actual_class and expected_class != actual_class:
+        artifact_issues.append(
+            f"artifact_class mismatch: expected `{expected_class}`, found `{actual_class}`."
+        )
+
+    field_class = actual_class or expected_class
+    required_fields = list(KERNEL_ARTIFACT_CLASS_REQUIREMENTS.get(field_class, []))
+    for field in _unique_strings([str(x).strip() for x in extra_required_fields if str(x).strip()]):
+        if field not in required_fields:
+            required_fields.append(field)
+    for field, value in payload.items():
+        if not isinstance(field, str) or field not in KERNEL_ALLOWED_FIELDS:
+            continue
+        for issue in _kernel_field_shape_issues(field, value):
+            artifact_issues.append(f"field `{field}` {issue}")
+    for field in required_fields:
+        if not _kernel_field_present(field, payload.get(field)):
+            missing_fields.append(field)
+    if missing_fields:
+        artifact_issues.append("missing required fields: " + ", ".join(missing_fields))
+
+    return {
+        "artifact_class": actual_class,
+        "expected_artifact_class": expected_class,
+        "valid": not artifact_issues,
+        "missing_fields": missing_fields,
+        "issues": artifact_issues,
+    }
+
+
+def _kernel_canonical_payload(
+    payload: dict[str, Any],
+    *,
+    drop_unknown_fields: bool,
+) -> tuple[dict[str, Any], list[str]]:
+    unknown_fields = sorted(str(key) for key in payload.keys() if str(key) not in KERNEL_ALLOWED_FIELDS)
+    if unknown_fields and not drop_unknown_fields:
+        raise RuntimeError(
+            "kernel artifact has unknown fields: " + ", ".join(unknown_fields) + ". Re-run with --drop-unknown-fields to discard them."
+        )
+
+    artifact_class = str(payload.get("artifact_class", "")).strip()
+    if artifact_class not in KERNEL_ARTIFACT_CLASS_REQUIREMENTS:
+        raise RuntimeError(f"unsupported artifact_class: {artifact_class or '(missing)'}")
+
+    known_payload = {
+        str(key): value
+        for key, value in payload.items()
+        if str(key) in KERNEL_ALLOWED_FIELDS
+    }
+    known_payload["schema_version"] = KERNEL_SCHEMA_VERSION
+    known_payload["artifact_class"] = artifact_class
+
+    ordered_fields = _kernel_ordered_fields_for_class(artifact_class, present_fields=list(known_payload.keys()))
+    canonical: dict[str, Any] = {}
+    for field in ordered_fields:
+        if field in known_payload:
+            canonical[field] = known_payload[field]
+    return canonical, unknown_fields
+
+
+def _kernel_proposal_template(
+    *,
+    proposal_kind: str,
+    title: str,
+    target_artifact_classes: Sequence[str],
+    target_fields: Sequence[str],
+) -> dict[str, Any]:
+    clean_classes = _unique_strings([str(x).strip() for x in target_artifact_classes if str(x).strip()])
+    clean_fields = _unique_strings([str(x).strip() for x in target_fields if str(x).strip()])
+    return {
+        "schema_version": KERNEL_SCHEMA_VERSION,
+        "proposal_kind": proposal_kind,
+        "title": title,
+        "status": "draft",
+        "summary": "describe the kernel evolution being proposed",
+        "target_scope": {
+            "artifact_classes": clean_classes,
+            "fields": clean_fields,
+        },
+        "proposed_change": [
+            "describe the exact structural change",
+        ],
+        "rationale": [
+            "describe why the current kernel is insufficient",
+        ],
+        "evidence_refs": [
+            "docs/ORP_REASONING_KERNEL_EVIDENCE_MATRIX.md",
+        ],
+        "compatibility_notes": [
+            "describe backward-compatibility expectations",
+        ],
+        "migration_plan": [
+            "describe how existing artifacts will be preserved or migrated",
+        ],
+        "evaluation_plan": [
+            "describe what new evidence should justify promotion into the core kernel",
+        ],
+    }
+
+
+def _kernel_observation_stats_from_run(run: dict[str, Any]) -> dict[str, Any]:
+    results = run.get("results", [])
+    if not isinstance(results, list):
+        results = []
+    kernel_rows = [
+        row.get("kernel_validation")
+        for row in results
+        if isinstance(row, dict) and isinstance(row.get("kernel_validation"), dict)
+    ]
+    return {
+        "run_id": str(run.get("run_id", "")).strip(),
+        "kernel_validations": kernel_rows,
+    }
+
+
 def _kernel_validation_mode(gate: dict[str, Any]) -> str:
     kernel_cfg = gate.get("kernel") if isinstance(gate.get("kernel"), dict) else {}
     default_mode = "hard" if str(gate.get("phase", "")).strip() == "structure_kernel" else "soft"
@@ -7371,31 +8099,14 @@ def _validate_kernel_gate(
 
         actual_class = ""
         if payload:
-            schema_version = str(payload.get("schema_version", "")).strip()
-            if schema_version != "1.0.0":
-                artifact_issues.append("schema_version must be `1.0.0`.")
-
-            actual_class = str(payload.get("artifact_class", "")).strip()
-            if actual_class not in KERNEL_ARTIFACT_CLASS_REQUIREMENTS:
-                artifact_issues.append(
-                    f"unsupported artifact_class: {actual_class or '(missing)'}."
-                )
-
-            if expected_class and actual_class and expected_class != actual_class:
-                artifact_issues.append(
-                    f"artifact_class mismatch: expected `{expected_class}`, found `{actual_class}`."
-                )
-
-            field_class = actual_class or expected_class
-            required_fields = list(KERNEL_ARTIFACT_CLASS_REQUIREMENTS.get(field_class, []))
-            for field in extra_required_fields:
-                if field not in required_fields:
-                    required_fields.append(field)
-            for field in required_fields:
-                if not _kernel_field_present(payload.get(field)):
-                    missing_fields.append(field)
-            if missing_fields:
-                artifact_issues.append("missing required fields: " + ", ".join(missing_fields))
+            validation = _validate_kernel_payload(
+                payload,
+                expected_class=expected_class,
+                extra_required_fields=extra_required_fields,
+            )
+            actual_class = str(validation.get("artifact_class", "")).strip()
+            missing_fields = list(validation.get("missing_fields", []))
+            artifact_issues.extend([str(issue) for issue in validation.get("issues", []) if isinstance(issue, str)])
 
         valid = optional_skipped or (exists and not artifact_issues)
         path_state = _path_for_state(path, repo_root)
@@ -7576,6 +8287,273 @@ def cmd_kernel_scaffold(args: argparse.Namespace) -> int:
     return 0
 
 
+def _resolve_kernel_run_json_paths(
+    *,
+    repo_root: Path,
+    run_ids: Sequence[str],
+    run_jsons: Sequence[str],
+) -> list[Path]:
+    resolved: list[Path] = []
+    if run_jsons:
+        for raw in run_jsons:
+            if not str(raw).strip():
+                continue
+            _, path = _resolve_run_json_path(repo_root=repo_root, run_id_arg="", run_json_arg=str(raw))
+            resolved.append(path)
+        return resolved
+    if run_ids:
+        for raw in run_ids:
+            if not str(raw).strip():
+                continue
+            _, path = _resolve_run_json_path(repo_root=repo_root, run_id_arg=str(raw), run_json_arg="")
+            resolved.append(path)
+        return resolved
+
+    seen: set[Path] = set()
+    state_path = repo_root / "orp" / "state.json"
+    if state_path.exists():
+        try:
+            state = _read_json(state_path)
+        except Exception:
+            state = {}
+        runs = state.get("runs")
+        if isinstance(runs, dict):
+            for value in runs.values():
+                if not isinstance(value, str) or not value.strip():
+                    continue
+                candidate = (repo_root / value).resolve()
+                if candidate.exists() and candidate not in seen:
+                    seen.add(candidate)
+                    resolved.append(candidate)
+    artifacts_root = repo_root / "orp" / "artifacts"
+    if artifacts_root.exists():
+        for candidate in sorted(artifacts_root.glob("*/RUN.json")):
+            candidate = candidate.resolve()
+            if candidate not in seen:
+                seen.add(candidate)
+                resolved.append(candidate)
+    return resolved
+
+
+def _kernel_stats_payload(
+    repo_root: Path,
+    run_json_paths: Sequence[Path],
+) -> dict[str, Any]:
+    runs_scanned = 0
+    runs_with_kernel_validation = 0
+    gate_rows_total = 0
+    artifacts_total = 0
+    artifacts_valid = 0
+    artifacts_invalid = 0
+    mode_counts: dict[str, int] = {}
+    artifact_class_counts: dict[str, int] = {}
+    missing_field_counts: dict[str, int] = {}
+    issue_counts: dict[str, int] = {}
+    path_counts: dict[str, int] = {}
+    per_run: list[dict[str, Any]] = []
+
+    for run_json in run_json_paths:
+        run = _read_json(run_json)
+        stats = _kernel_observation_stats_from_run(run)
+        kernel_rows = stats["kernel_validations"]
+        runs_scanned += 1
+        if kernel_rows:
+            runs_with_kernel_validation += 1
+        per_run.append(
+            {
+                "run_id": stats["run_id"] or run_json.parent.name,
+                "run_json": _path_for_state(run_json, repo_root),
+                "kernel_validations": len(kernel_rows),
+            }
+        )
+        for row in kernel_rows:
+            if not isinstance(row, dict):
+                continue
+            gate_rows_total += 1
+            mode = str(row.get("mode", "")).strip() or "unknown"
+            mode_counts[mode] = mode_counts.get(mode, 0) + 1
+            for artifact in row.get("artifacts", []) if isinstance(row.get("artifacts"), list) else []:
+                if not isinstance(artifact, dict):
+                    continue
+                artifacts_total += 1
+                if artifact.get("valid"):
+                    artifacts_valid += 1
+                else:
+                    artifacts_invalid += 1
+                artifact_class = str(
+                    artifact.get("artifact_class") or artifact.get("expected_artifact_class") or "unknown"
+                ).strip() or "unknown"
+                artifact_class_counts[artifact_class] = artifact_class_counts.get(artifact_class, 0) + 1
+                artifact_path = str(artifact.get("path", "")).strip()
+                if artifact_path:
+                    path_counts[artifact_path] = path_counts.get(artifact_path, 0) + 1
+                for field in artifact.get("missing_fields", []) if isinstance(artifact.get("missing_fields"), list) else []:
+                    key = str(field).strip()
+                    if key:
+                        missing_field_counts[key] = missing_field_counts.get(key, 0) + 1
+                for issue in artifact.get("issues", []) if isinstance(artifact.get("issues"), list) else []:
+                    key = str(issue).strip()
+                    if key:
+                        issue_counts[key] = issue_counts.get(key, 0) + 1
+
+    top_missing_fields = [
+        {"field": key, "count": count}
+        for key, count in sorted(missing_field_counts.items(), key=lambda item: (-item[1], item[0]))[:10]
+    ]
+    top_issue_signals = [
+        {"issue": key, "count": count}
+        for key, count in sorted(issue_counts.items(), key=lambda item: (-item[1], item[0]))[:10]
+    ]
+    top_paths = [
+        {"path": key, "count": count}
+        for key, count in sorted(path_counts.items(), key=lambda item: (-item[1], item[0]))[:10]
+    ]
+    observations: list[str] = []
+    if runs_scanned == 0:
+        observations.append("No RUN.json artifacts were found. Run `orp gate run` with a structure_kernel gate to collect kernel observations.")
+    elif runs_with_kernel_validation == 0:
+        observations.append("RUN.json artifacts exist, but none recorded kernel_validation. Add a structure_kernel gate with a kernel.artifacts block.")
+    else:
+        if top_missing_fields:
+            focus = ", ".join(f"{row['field']} ({row['count']})" for row in top_missing_fields[:5])
+            observations.append(f"Most repeated missing fields: {focus}.")
+        if artifacts_invalid == 0:
+            observations.append("All observed kernel artifacts validated successfully across scanned runs.")
+        else:
+            observations.append(
+                f"{artifacts_invalid} of {artifacts_total} observed kernel artifacts failed validation."
+            )
+    return {
+        "ok": True,
+        "repo_root": str(repo_root),
+        "runs_scanned": runs_scanned,
+        "runs_with_kernel_validation": runs_with_kernel_validation,
+        "kernel_validation_rows": gate_rows_total,
+        "artifacts_total": artifacts_total,
+        "artifacts_valid": artifacts_valid,
+        "artifacts_invalid": artifacts_invalid,
+        "artifact_validation_rate": round((artifacts_valid / artifacts_total), 3) if artifacts_total else None,
+        "mode_counts": mode_counts,
+        "artifact_class_counts": artifact_class_counts,
+        "top_missing_fields": top_missing_fields,
+        "top_issue_signals": top_issue_signals,
+        "top_paths": top_paths,
+        "observations": observations,
+        "runs": per_run,
+    }
+
+
+def cmd_kernel_stats(args: argparse.Namespace) -> int:
+    repo_root = Path(args.repo_root).resolve()
+    run_json_paths = _resolve_kernel_run_json_paths(
+        repo_root=repo_root,
+        run_ids=list(getattr(args, "run_id", []) or []),
+        run_jsons=list(getattr(args, "run_json", []) or []),
+    )
+    payload = _kernel_stats_payload(repo_root, run_json_paths)
+    if args.json_output:
+        _print_json(payload)
+    else:
+        print(f"runs_scanned={payload['runs_scanned']}")
+        print(f"runs_with_kernel_validation={payload['runs_with_kernel_validation']}")
+        print(f"artifacts_total={payload['artifacts_total']}")
+        print(f"artifacts_valid={payload['artifacts_valid']}")
+        print(f"artifacts_invalid={payload['artifacts_invalid']}")
+        for row in payload.get("top_missing_fields", []):
+            print(f"missing_field={row['field']} count={row['count']}")
+        for note in payload.get("observations", []):
+            print(f"note={note}")
+    return 0
+
+
+def cmd_kernel_propose(args: argparse.Namespace) -> int:
+    repo_root = Path(args.repo_root).resolve()
+    title = str(args.title or "").strip()
+    if not title:
+        raise RuntimeError("proposal title is required.")
+    slug = _slug_token(getattr(args, "slug", "") or title, fallback="kernel-proposal")
+    out_raw = str(getattr(args, "out", "") or "").strip()
+    if out_raw:
+        out_path = _resolve_cli_path(out_raw, repo_root)
+    else:
+        out_path = repo_root / "analysis" / "kernel-proposals" / f"{slug}.yml"
+    if out_path.exists() and not args.force:
+        raise RuntimeError(
+            f"kernel proposal already exists: {_path_for_state(out_path, repo_root)}. Use --force to overwrite."
+        )
+    payload = _kernel_proposal_template(
+        proposal_kind=str(args.kind).strip(),
+        title=title,
+        target_artifact_classes=list(getattr(args, "artifact_class", []) or []),
+        target_fields=list(getattr(args, "field", []) or []),
+    )
+    emitted_format = _write_structured_payload(out_path, payload, format_hint=args.format)
+    result = {
+        "ok": True,
+        "path": _path_for_state(out_path, repo_root),
+        "format": emitted_format,
+        "proposal_kind": payload["proposal_kind"],
+        "title": payload["title"],
+    }
+    if args.json_output:
+        _print_json(result)
+    else:
+        print(f"path={result['path']}")
+        print(f"proposal_kind={result['proposal_kind']}")
+        print(f"title={result['title']}")
+        print(f"format={result['format']}")
+    return 0
+
+
+def cmd_kernel_migrate(args: argparse.Namespace) -> int:
+    repo_root = Path(args.repo_root).resolve()
+    artifact_path = _resolve_cli_path(args.artifact, repo_root)
+    if not artifact_path.exists():
+        raise RuntimeError(f"kernel artifact not found: {_path_for_state(artifact_path, repo_root)}")
+    loaded_payload = _load_config(artifact_path)
+    if not isinstance(loaded_payload, dict):
+        raise RuntimeError("kernel artifact root must be an object.")
+    out_raw = str(getattr(args, "out", "") or "").strip()
+    out_path = _resolve_cli_path(out_raw, repo_root) if out_raw else artifact_path
+    if out_path.exists() and out_path != artifact_path and not args.force:
+        raise RuntimeError(
+            f"output path already exists: {_path_for_state(out_path, repo_root)}. Use --force to overwrite."
+        )
+
+    original_schema_version = str(loaded_payload.get("schema_version", "") or "").strip()
+    canonical_payload, dropped_unknown_fields = _kernel_canonical_payload(
+        loaded_payload,
+        drop_unknown_fields=bool(getattr(args, "drop_unknown_fields", False)),
+    )
+    emitted_format = _write_structured_payload(out_path, canonical_payload, format_hint=args.format)
+    validation = _validate_kernel_payload(canonical_payload, expected_class=str(canonical_payload.get("artifact_class", "")).strip())
+    result = {
+        "ok": True,
+        "artifact": _path_for_state(artifact_path, repo_root),
+        "path": _path_for_state(out_path, repo_root),
+        "format": emitted_format,
+        "schema_version_before": original_schema_version or "(missing)",
+        "schema_version_after": str(canonical_payload.get("schema_version", "")),
+        "schema_version_updated": (original_schema_version or "") != str(canonical_payload.get("schema_version", "")),
+        "artifact_class": str(canonical_payload.get("artifact_class", "")),
+        "dropped_unknown_fields": dropped_unknown_fields,
+        "validation": validation,
+    }
+    if args.json_output:
+        _print_json(result)
+    else:
+        print(f"path={result['path']}")
+        print(f"artifact_class={result['artifact_class']}")
+        print(f"schema_version_before={result['schema_version_before']}")
+        print(f"schema_version_after={result['schema_version_after']}")
+        if dropped_unknown_fields:
+            print("dropped_unknown_fields=" + ",".join(dropped_unknown_fields))
+        print(f"valid={'true' if validation.get('valid') else 'false'}")
+        for issue in validation.get("issues", []):
+            print(f"issue={issue}")
+    return 0
+
+
 def cmd_gate_run(args: argparse.Namespace) -> int:
     repo_root = Path(args.repo_root).resolve()
     _ensure_dirs(repo_root)
@@ -11732,6 +12710,43 @@ def build_parser() -> argparse.ArgumentParser:
     add_json_flag(s_world_bind)
     s_world_bind.set_defaults(func=cmd_world_bind, json_output=False)
 
+    s_youtube = sub.add_parser("youtube", help="Public YouTube metadata and transcript inspection")
+    youtube_sub = s_youtube.add_subparsers(dest="youtube_cmd", required=True)
+
+    s_youtube_inspect = youtube_sub.add_parser(
+        "inspect",
+        help="Inspect a YouTube video and fetch public metadata plus transcript text when captions are available",
+    )
+    s_youtube_inspect.add_argument("url", help="YouTube watch/share URL or 11-character video id")
+    s_youtube_inspect.add_argument(
+        "--lang",
+        default="",
+        help="Preferred caption language code, for example en or es",
+    )
+    s_youtube_inspect.add_argument(
+        "--save",
+        action="store_true",
+        help="Save the inspected source artifact under orp/external/youtube/<video_id>.json",
+    )
+    s_youtube_inspect.add_argument(
+        "--out",
+        default="",
+        help="Optional output path for the source artifact (.json, .yml, or .yaml)",
+    )
+    s_youtube_inspect.add_argument(
+        "--format",
+        default="",
+        choices=["", "json", "yaml"],
+        help="Optional explicit output format when saving",
+    )
+    s_youtube_inspect.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing saved artifact",
+    )
+    add_json_flag(s_youtube_inspect)
+    s_youtube_inspect.set_defaults(func=cmd_youtube_inspect, json_output=False)
+
     s_secrets = sub.add_parser("secrets", help="Hosted secret store and project binding operations")
     secrets_sub = s_secrets.add_subparsers(dest="secrets_cmd", required=True)
 
@@ -12658,6 +13673,106 @@ def build_parser() -> argparse.ArgumentParser:
     add_json_flag(s_kernel_scaffold)
     s_kernel_scaffold.set_defaults(func=cmd_kernel_scaffold, json_output=False)
 
+    s_kernel_stats = kernel_sub.add_parser(
+        "stats",
+        help="Summarize observed kernel validation pressure from RUN.json artifacts",
+    )
+    s_kernel_stats.add_argument(
+        "--run-id",
+        action="append",
+        default=[],
+        help="Specific run id to include (repeatable). Defaults to all discovered runs.",
+    )
+    s_kernel_stats.add_argument(
+        "--run-json",
+        action="append",
+        default=[],
+        help="Explicit RUN.json path to include (repeatable). Defaults to all discovered runs.",
+    )
+    add_json_flag(s_kernel_stats)
+    s_kernel_stats.set_defaults(func=cmd_kernel_stats, json_output=False)
+
+    s_kernel_propose = kernel_sub.add_parser(
+        "propose",
+        help="Scaffold a governed kernel-evolution proposal artifact",
+    )
+    s_kernel_propose.add_argument(
+        "--kind",
+        required=True,
+        choices=["add_field", "new_class", "requirement_change", "deprecate_field"],
+        help="Type of kernel evolution proposal",
+    )
+    s_kernel_propose.add_argument(
+        "--title",
+        required=True,
+        help="Proposal title",
+    )
+    s_kernel_propose.add_argument(
+        "--artifact-class",
+        action="append",
+        default=[],
+        choices=sorted(KERNEL_ARTIFACT_CLASS_REQUIREMENTS.keys()),
+        help="Affected kernel artifact class (repeatable)",
+    )
+    s_kernel_propose.add_argument(
+        "--field",
+        action="append",
+        default=[],
+        help="Affected kernel field name (repeatable)",
+    )
+    s_kernel_propose.add_argument(
+        "--slug",
+        default="",
+        help="Optional output slug override",
+    )
+    s_kernel_propose.add_argument(
+        "--out",
+        default="",
+        help="Optional output path (default: analysis/kernel-proposals/<slug>.yml)",
+    )
+    s_kernel_propose.add_argument(
+        "--format",
+        default="",
+        choices=["", "yaml", "json"],
+        help="Optional explicit output format",
+    )
+    s_kernel_propose.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing proposal at the output path",
+    )
+    add_json_flag(s_kernel_propose)
+    s_kernel_propose.set_defaults(func=cmd_kernel_propose, json_output=False)
+
+    s_kernel_migrate = kernel_sub.add_parser(
+        "migrate",
+        help="Rewrite a kernel artifact into the current canonical field order and schema version",
+    )
+    s_kernel_migrate.add_argument("artifact", help="Kernel artifact path (.yml, .yaml, or .json)")
+    s_kernel_migrate.add_argument(
+        "--out",
+        default="",
+        help="Optional output path (default: rewrite in place)",
+    )
+    s_kernel_migrate.add_argument(
+        "--format",
+        default="",
+        choices=["", "yaml", "json"],
+        help="Optional explicit output format",
+    )
+    s_kernel_migrate.add_argument(
+        "--drop-unknown-fields",
+        action="store_true",
+        help="Drop unknown fields instead of failing migration",
+    )
+    s_kernel_migrate.add_argument(
+        "--force",
+        action="store_true",
+        help="Allow overwriting an existing --out path",
+    )
+    add_json_flag(s_kernel_migrate)
+    s_kernel_migrate.set_defaults(func=cmd_kernel_migrate, json_output=False)
+
     s_gate = sub.add_parser("gate", help="Gate operations")
     gate_sub = s_gate.add_subparsers(dest="gate_cmd", required=True)
     s_run = gate_sub.add_parser("run", help="Run configured gates for a profile")