@kernaut/kernaut-resources 0.1.17-beta.1 → 0.1.18

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/scripts/_retrieval.py

@@ -1,601 +0,0 @@
-#!/usr/bin/env python3
-"""Shared keyword-retrieval core: alias expansion, BM25F ranking, filters.
-
-`query.py` (CLI) and `wiki_query_service.py` (MCP server) must rank and filter
-the same corpus the same way. They used to hold two copies of this logic, which
-drifted: the CLI gained BM25F, architecture families and the vendor-scoping
-rule while the MCP server kept a weighted-substring scorer and searched every
-vendor by default. An agent asking the same question through the two paths got
-two different answers, and only one of them was the answer the wiki had been
-tuned to give.
-
-So the logic lives here once. The two callers differ only in what they are
-allowed to read and how they report a refusal:
-
-  * `guard` -- an optional ``Path -> bool`` predicate. The MCP server passes
-    its symlink-containment check so a page or artifact that resolves outside
-    WIKI_ROOT is never read; the CLI passes nothing, because a local shell
-    already has whatever the filesystem grants it.
-  * vendor refusal -- `_axes.resolve_vendor` returns the detail, and each
-    caller renders it (usage text vs. JSON-RPC error).
-"""
-
-import math
-import re
-import sys
-from collections import Counter, defaultdict
-from pathlib import Path
-
-import yaml
-
-sys.path.insert(0, str(Path(__file__).resolve().parent))
-from _axes import (  # noqa: E402
-    architecture_matches,
-    axis_matches,
-    declares_generic,
-    vendor_matches,
-    vendor_registry,
-)
-from _wiki_root import WIKI_ROOT  # noqa: E402
-
-
-# ---------------------------------------------------------------------------
-# Alias expansion
-# ---------------------------------------------------------------------------
-
-_ALIAS_CACHE = None
-
-
-def load_alias_expansions():
-    """Return a dict mapping lowercased alias -> canonical term, loaded from data/aliases.yaml.
-
-    Each canonical is also mapped to itself, so lookups always return something
-    sensible when the user already types the canonical form.
-    """
-    global _ALIAS_CACHE
-    if _ALIAS_CACHE is not None:
-        return _ALIAS_CACHE
-    out = {}
-    aliases_path = WIKI_ROOT / "data" / "aliases.yaml"
-    try:
-        raw = yaml.safe_load(aliases_path.read_text(encoding="utf-8")) or {}
-    except Exception:
-        _ALIAS_CACHE = {}
-        return _ALIAS_CACHE
-    for canonical, variants in raw.items():
-        if not isinstance(canonical, str):
-            continue
-        out.setdefault(canonical.lower(), canonical)
-        for v in (variants or []):
-            if isinstance(v, str):
-                out.setdefault(v.lower(), canonical)
-    _ALIAS_CACHE = out
-    return out
-
-
-def expand_keyword(kw):
-    """Return a list of search variants for a keyword: the original plus any
-    canonical term the alias map points to."""
-    aliases = load_alias_expansions()
-    canonical = aliases.get(kw.lower())
-    if canonical and canonical.lower() != kw.lower():
-        return [kw, canonical]
-    return [kw]
-
-
-# ---------------------------------------------------------------------------
-# Page loading
-# ---------------------------------------------------------------------------
-
-# Resident "read-first" digests (Layer 3a): fetchable via get_page, but excluded
-# from the search index so their technique-name-dense bodies don't displace real pages.
-NON_INDEXED_BASENAMES = {"CORE_DIGEST.md"}
-
-_FRONTMATTER_RE = re.compile(r'^---\s*\r?\n(.*?)\r?\n---\s*\r?\n(.*)', re.DOTALL)
-
-
-def load_frontmatter(path, guard=None):
-    """Parse YAML frontmatter from a markdown file. Returns (fm_dict, body_str) or (None, None)."""
-    if guard is not None and not guard(path):
-        return None, None
-    try:
-        content = path.read_text(encoding="utf-8")
-    except Exception:
-        return None, None
-    m = _FRONTMATTER_RE.match(content)
-    if not m:
-        return None, None
-    try:
-        fm = yaml.safe_load(m.group(1))
-        if not isinstance(fm, dict):
-            return None, None
-        return fm, m.group(2)
-    except yaml.YAMLError:
-        return None, None
-
-
-def iter_page_files():
-    """Every indexable markdown path under sources/ and wiki/."""
-    for subdir in ["sources", "wiki"]:
-        base = WIKI_ROOT / subdir
-        if not base.exists():
-            continue
-        for md in base.rglob("*.md"):
-            if md.name in NON_INDEXED_BASENAMES:
-                continue
-            yield md
-
-
-def load_all_pages(guard=None):
-    """Load frontmatter + body for every indexable sources/*.md and wiki/*.md file."""
-    pages = []
-    for md in iter_page_files():
-        fm, body = load_frontmatter(md, guard=guard)
-        if fm is None:
-            continue
-        pages.append({
-            "path": str(md.relative_to(WIKI_ROOT)),
-            "fm": fm,
-            "body": body or "",
-        })
-    return pages
-
-
-def detect_page_type(fm, path):
-    """Return a page-type label for filtering: source-pr/source-blog/..., wiki-hardware/..."""
-    parts = path.split("/")
-    if parts[0] == "sources" and len(parts) > 1:
-        # Source-side experience records also carry `type: experience`.
-        # Prefer the physical corpus role here so output/filtering makes it
-        # clear that these are evidence records, not synthesized wiki pages.
-        if parts[1] == "experience":
-            return "source-experience"
-        if "type" not in fm:
-            return f"source-{parts[1].rstrip('s')}"  # prs -> source-pr
-    if "type" in fm:
-        return f"wiki-{fm['type']}"
-    return "unknown"
-
-
-def flatten_meta_values(value):
-    """Yield strings from nested frontmatter structures for search/filtering."""
-    if value is None:
-        return
-    if isinstance(value, (str, int, float, bool)):
-        yield str(value)
-    elif isinstance(value, dict):
-        for k, v in value.items():
-            yield str(k)
-            yield from flatten_meta_values(v)
-    elif isinstance(value, (list, tuple, set)):
-        for item in value:
-            yield from flatten_meta_values(item)
-
-
-# ---- Field-weighted BM25 (BM25F) ranking ----
-#
-# Replaces the earlier weighted-substring scorer. The substring scorer had
-# field weighting (title +10 / tag +5 / body +count) but no IDF and no length
-# normalization: rare, discriminative terms scored no higher than common ones,
-# so symptom/phenomenon queries often ranked the right concept page 2nd-5th
-# behind a sibling page that merely mentioned a common word more times.
-#
-# BM25F keeps the field weighting (so a title hit still beats a body mention)
-# AND adds Okapi IDF + length normalization. Measured on the retrieval goldset
-# (analyze/kw_retrieval_goldset.json), swapping substring->BM25F lifts overall
-# MRR 0.807->0.869 and R@1 0.714->0.796, and the hard phenomenon-word group
-# 0.400->0.688 -- while the concept-sanity guard holds. NOTE: *plain* BM25 (no
-# field weighting) regresses to 0.754 because it throws the field weighting
-# away; the field boosts below are what make it a net win. Full A/B + per-query
-# diff: analyze/kw_bm25_ablation.md.
-_BM25_K1 = 1.5
-_BM25_B = 0.75
-# Field boosts echo the old title>tag>meta>body ordering (integer approximation,
-# not tuned per-query). tag and metadata regions use the same field lists the
-# old scorer read, so any frontmatter padding (symptoms/aliases) is visible to
-# BM25 too.
-_FIELD_BOOST = {"title": 3, "tag": 2, "meta": 2, "body": 1}
-_BM25_TAG_FIELDS = ("tags", "techniques", "hardware_features", "kernel_types",
-                    "languages", "aliases", "symptoms")
-_BM25_META_FIELDS = ("repo", "upstream_repo", "source_refs", "source", "sources",
-                     "artifacts", "artifact_dir", "api", "namespace", "func_name",
-                     "operator", "applies_to", "applies_to_ops", "requires_features",
-                     "related", "related_apis", "related_skills", "probe_slug")
-_TOKEN_RE = re.compile(r"[a-z0-9_]+")
-# CJK runs carry no spaces, so the ASCII token regex above drops them entirely and a
-# Chinese query scores against nothing. Index each run as overlapping bigrams plus its
-# single characters: bigrams give the discrimination, single characters keep
-# one-character terms and the tail of an odd-length run reachable.
-#
-# Write the bounds as escapes, never as literal glyphs. 豈 exists twice in
-# Unicode -- U+8C48 (CJK Unified) and U+F900 (CJK Compatibility) -- and the two
-# are visually identical, so pasting the glyph silently picks whichever one the
-# editor produced. Getting U+8C48 here turns the last range into
-# U+8C48-U+FAFF and sweeps in 22,784 extra codepoints: all of Hangul, Yi and
-# the Private Use Area.
-#
-# `CJK_IDEOGRAPH_RE` is the same character class without the `+`, exported so
-# the MCP server's pattern-selectivity gate weights the same characters this
-# tokenizer splits on. One definition, so the two cannot drift.
-_CJK_RANGES = "\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff"
-CJK_IDEOGRAPH_RE = re.compile(f"[{_CJK_RANGES}]")
-_CJK_RUN_RE = re.compile(f"[{_CJK_RANGES}]+")
-
-
-def _cjk_tokens(text):
-    out = []
-    for run in _CJK_RUN_RE.findall(text):
-        out.extend(run)
-        out.extend(run[i:i + 2] for i in range(len(run) - 1))
-    return out
-
-
-def _tokenize(text):
-    low = text.lower()
-    return _TOKEN_RE.findall(low) + _cjk_tokens(low)
-
-
-def _page_field_tokens(fm, body):
-    """Bucket a page's searchable text into title/tag/meta/body token lists --
-    the same fields the previous substring scorer read."""
-    title_txt = str(fm.get("title", ""))
-    tag_txt = " ".join(str(v) for k in _BM25_TAG_FIELDS for v in (fm.get(k) or []))
-    meta_txt = " ".join(s for k in _BM25_META_FIELDS for s in flatten_meta_values(fm.get(k)))
-    return {"title": _tokenize(title_txt), "tag": _tokenize(tag_txt),
-            "meta": _tokenize(meta_txt), "body": _tokenize(body)}
-
-
-def build_bm25_index(pages):
-    """Compute global IDF + avgdl over the corpus and attach each page's
-    field-weighted term frequencies (p['_bm25_tf'], p['_bm25_len']).
-    Returns (idf_dict, avgdl). Call once over the full corpus before filtering."""
-    n = len(pages)
-    df = defaultdict(int)
-    total_len = 0
-    for p in pages:
-        tf = Counter()
-        length = 0
-        for fld, toks in _page_field_tokens(p["fm"], p["body"]).items():
-            w = _FIELD_BOOST[fld]
-            for t in toks:
-                tf[t] += w
-            length += w * len(toks)  # weighted length, same scale as weighted tf
-        p["_bm25_tf"] = tf
-        p["_bm25_len"] = length
-        total_len += length
-        for term in tf:
-            df[term] += 1
-    avgdl = (total_len / n) if n else 0.0
-    idf = {t: math.log((n - d + 0.5) / (d + 0.5) + 1.0) for t, d in df.items()}
-    return idf, avgdl
-
-
-def build_query_terms(keywords):
-    """Expand each keyword through the alias map (so 'UMMA'->'tcgen05', etc.),
-    tokenize, and return the deduped query term set."""
-    terms = set()
-    for kw in keywords:
-        for variant in expand_keyword(kw):
-            terms.update(_tokenize(variant))
-    return terms
-
-
-def bm25f_score(page, q_terms, idf, avgdl):
-    """Okapi BM25 over the page's field-weighted term frequencies."""
-    tf = page.get("_bm25_tf")
-    if not tf:
-        return 0.0
-    dl = page.get("_bm25_len", 0)
-    denom_norm = _BM25_K1 * (1 - _BM25_B + _BM25_B * (dl / avgdl if avgdl else 0.0))
-    score = 0.0
-    for term in q_terms:
-        f = tf.get(term, 0)
-        if not f:
-            continue
-        score += idf.get(term, 0.0) * (f * (_BM25_K1 + 1)) / (f + denom_norm)
-    return score
-
-
-def split_keywords(query_values):
-    """Flatten multi-word query values into individual tokens.
-
-    So `query.py "how to fuse dual GEMM"` behaves like
-    `query.py how to fuse dual GEMM`.
-    """
-    keywords = []
-    for q in (query_values or []):
-        for tok in re.split(r"\s+", str(q).strip()):
-            if tok:
-                keywords.append(tok)
-    return keywords
-
-
-# ---------------------------------------------------------------------------
-# Filtering
-# ---------------------------------------------------------------------------
-
-# NOTE: `.patch` is deliberately excluded. --has-code is documented as "at
-# least one source file", so a PR bundle that only shipped diff.patch (no
-# captured key-files/) should NOT surface here -- a raw diff is not browsable
-# source. See: get_page.py --include-code still prints diff.patch for bundles
-# that have one.
-#
-# `.txt` IS counted: scripts/extract_blog_code.py writes unlabeled fenced
-# blocks under artifacts/blogs/<slug>/code/NN-<name>.txt via the
-# EXT_MAP.get(lang, "txt") fallback. These are real code snippets whose fence
-# just lacked a language tag (R20 widening).
-#
-# `.sh`, `.yaml`, `.json` are also counted (R33) to match
-# extract_blog_code.py's EXT_MAP mappings for bash / shell / yaml / json
-# fences. Keep this set in sync with validate.py's ASSET_SOURCE_EXTS and
-# get_page.py's --include-code exts; the three together form the Phase-3
-# asset-source contract.
-CODE_EXTS = {".cu", ".cuh", ".ptx", ".py", ".cpp", ".h", ".hpp", ".inl",
-             ".pyx", ".cxx", ".cc", ".txt",
-             ".sh", ".yaml", ".json"}
-
-
-def _has_code(page, fm, path, guard=None):
-    candidate_dirs = []
-
-    def allowed(p):
-        return guard is None or guard(p)
-
-    # Primary: explicit page-level artifact_dir.
-    ad = fm.get("artifact_dir")
-    if ad:
-        ad_path = WIKI_ROOT / ad
-        if allowed(ad_path):
-            candidate_dirs.append(ad_path)
-
-    # New merged pages often use an `artifacts:` mapping (code/build/profile/
-    # etc.) instead of a single artifact_dir. Treat any source file referenced
-    # by that mapping as code-backed, and also add its containing directories
-    # as scan candidates.
-    explicit_artifact_files = []
-    for art in flatten_meta_values(fm.get("artifacts")):
-        art_path = WIKI_ROOT / art
-        if not allowed(art_path):
-            continue
-        if art_path.is_file():
-            explicit_artifact_files.append(art_path)
-            candidate_dirs.append(art_path.parent)
-        elif art_path.is_dir():
-            candidate_dirs.append(art_path)
-
-    # Fallback 1: conventional bundle locations per page type.
-    # A source-blog's extracted code lives at artifacts/blogs/<slug>/code/;
-    # a source-contest's reconstructed bundles live under
-    # artifacts/contests/<contest>/<problem>/submissions/**.
-    # This lets --has-code still work for pages whose artifact_dir hasn't been
-    # backfilled yet (Codex R8 finding #1).
-    ptype = page["_ptype"]
-    if ptype == "source-blog":
-        candidate_dirs.append(WIKI_ROOT / "artifacts" / "blogs" / Path(path).stem / "code")
-    elif ptype == "source-contest":
-        contest_dir_name = Path(path).parent.name
-        problem_stem = Path(path).stem
-        candidate_dirs.append(WIKI_ROOT / "artifacts" / "contests" / contest_dir_name / problem_stem)
-
-    # Fallback 2: for source-pr pages, infer the conventional
-    # artifacts/prs/<repo-short>/PR-<N>/ location from frontmatter repo+pr.
-    if ptype == "source-pr" and fm.get("repo") and fm.get("pr"):
-        repo_short = str(fm["repo"]).split("/")[-1].lower()
-        candidate_dirs.append(WIKI_ROOT / "artifacts" / "prs" / repo_short / f"PR-{fm['pr']}")
-
-    for f in explicit_artifact_files:
-        if allowed(f) and f.suffix.lower() in CODE_EXTS:
-            return True
-    for cand in candidate_dirs:
-        if not allowed(cand) or not cand.is_dir():
-            continue
-        for f in cand.rglob("*"):
-            if f.is_file() and allowed(f) and f.suffix.lower() in CODE_EXTS:
-                return True
-    return False
-
-
-def filter_pages(pages, params, guard=None):
-    """Narrow the page set by the retrieval filters.
-
-    ``params`` is a plain dict with optional keys: type, tag, vendor, repo,
-    language, architecture, symptom, confidence, has_code. Missing keys mean
-    "no filter". A dict rather than an argparse.Namespace so the MCP server can
-    call it with the JSON params it already has.
-    """
-    f_type = params.get("type")
-    f_tag = params.get("tag")
-    f_vendor = params.get("vendor")
-    f_repo = params.get("repo")
-    f_language = params.get("language")
-    f_architecture = params.get("architecture")
-    f_symptom = params.get("symptom")
-    f_confidence = params.get("confidence")
-    f_has_code = params.get("has_code", False)
-
-    out = []
-    for p in pages:
-        fm = p["fm"]
-        path = p["path"]
-        ptype = detect_page_type(fm, path)
-        p["_ptype"] = ptype
-
-        if f_type and not ptype.endswith(f_type):
-            # --type kernel matches wiki-kernel, --type pr matches source-pr
-            if ptype != f_type:
-                continue
-
-        if f_tag:
-            all_tags = set()
-            for k in ("tags", "techniques", "hardware_features", "kernel_types", "languages"):
-                all_tags.update(fm.get(k) or [])
-            tag_variants = {v.lower() for v in expand_keyword(f_tag)}
-            if not any(t.lower() in tag_variants for t in all_tags):
-                continue
-
-        if f_vendor and f_vendor != "all":
-            fm_vendor = fm.get("vendor", "")
-            path_parts = path.split("/")
-            path_vendor = path_parts[1] if path_parts[0] == "wiki" and len(path_parts) > 2 else ""
-            vendor_values = []
-            if isinstance(fm_vendor, (list, tuple, set)):
-                vendor_values.extend(str(v) for v in fm_vendor)
-            elif fm_vendor:
-                vendor_values.append(str(fm_vendor))
-            if path_vendor:
-                vendor_values.append(path_vendor)
-
-            # Generic cross-vendor pages often carry concrete architectures
-            # or stack/language tags (e.g. ascend910b, triton-ascend) while
-            # keeping vendor: generic to match their wiki/generic path. Treat
-            # those metadata fields as vendor applicability for filtering.
-            reg = vendor_registry()
-            for k in ("architectures", "languages", "tags", "hardware_features", "kernel_types"):
-                for value in fm.get(k) or []:
-                    inferred_vendor = reg.get(str(value).lower())
-                    if inferred_vendor:
-                        vendor_values.append(inferred_vendor)
-
-            # `generic` satisfies any vendor filter: it means "every vendor",
-            # not "a fourth vendor". Without this a wiki/generic page that is
-            # genuinely vendor-agnostic (architectures/languages both `*`) is
-            # invisible to every real query, which is the opposite of the point.
-            if not vendor_matches(vendor_values, f_vendor,
-                                  declares_generic(fm, path)):
-                continue
-
-        if f_repo:
-            repo_text = " ".join(
-                flatten_meta_values({
-                    "repo": fm.get("repo"),
-                    "upstream_repo": fm.get("upstream_repo"),
-                    "source_refs": fm.get("source_refs"),
-                    "source": fm.get("source"),
-                })
-            ).lower()
-            if f_repo.lower() not in repo_text:
-                continue
-
-        if f_language:
-            langs = list(fm.get("languages") or []) + list(fm.get("tags") or [])
-            if not axis_matches(langs, f_language):
-                continue
-
-        if f_architecture:
-            # Both sides collapse to the architecture family, so a 910C query
-            # reaches the 910B corpus and an ascend910b query reaches the pages
-            # tagged with a die bin. Aliases first, so "910C" resolves too.
-            archs = fm.get("architectures") or []
-            if not any(architecture_matches(archs, v)
-                       for v in expand_keyword(f_architecture)):
-                continue
-
-        if f_symptom:
-            symptoms = set(fm.get("symptoms") or [])
-            if f_symptom not in symptoms:
-                continue
-
-        if f_confidence:
-            if str(fm.get("confidence", "")) != f_confidence:
-                continue
-
-        if f_has_code and not _has_code(p, fm, path, guard=guard):
-            continue
-
-        out.append(p)
-    return out
-
-
-def count_blind_pages(pages, key):
-    """How many pages carry no value at all for one axis.
-
-    A field-based filter silently drops every page that has no value for that
-    field, so both callers report this rather than letting an empty result read
-    as "the wiki has nothing on this".
-    """
-    return sum(1 for pg in pages if not (pg["fm"].get(key) or []))
-
-
-# ---------------------------------------------------------------------------
-# Vendor inference
-# ---------------------------------------------------------------------------
-
-def infer_vendor_candidates(params):
-    """Every vendor implied by architecture / language / tag / keywords.
-
-    Returned as a set so the caller can tell "nothing implied a vendor" apart
-    from "the query straddles two vendors" -- the two cases need different
-    advice, and neither may silently fall through to a corpus-wide search.
-    """
-    reg = vendor_registry()
-    aliases = load_alias_expansions()
-
-    candidates = set()
-
-    if params.get("architecture"):
-        for variant in expand_keyword(params["architecture"]):
-            v = reg.get(variant.lower())
-            if v:
-                candidates.add(v)
-
-    if params.get("language"):
-        v = reg.get(str(params["language"]).lower())
-        if v:
-            candidates.add(v)
-
-    if params.get("tag"):
-        for variant in expand_keyword(params["tag"]):
-            v = reg.get(variant.lower())
-            if v:
-                candidates.add(v)
-
-    for q in (params.get("query") or []):
-        for tok in re.split(r"\s+", str(q).strip()):
-            tok_l = tok.lower()
-            v = reg.get(tok_l)
-            if v:
-                candidates.add(v)
-            canonical = aliases.get(tok_l)
-            if canonical:
-                v = reg.get(canonical.lower())
-                if v:
-                    candidates.add(v)
-
-    return candidates
-
-
-# ---------------------------------------------------------------------------
-# Formatting
-# ---------------------------------------------------------------------------
-
-def format_result(page, compact=False):
-    """Format a single page as a readable line."""
-    fm = page["fm"]
-    title = fm.get("title", "Untitled")
-    path = page["path"]
-    pid = fm.get("id", "")
-    ptype = page.get("_ptype", "?")
-
-    if compact:
-        return f"  [{ptype}] {pid}: {title}  ({path})"
-
-    # Rich: include key metadata
-    lines = [f"## {title}"]
-    lines.append(f"- **id**: `{pid}`")
-    lines.append(f"- **type**: `{ptype}`")
-    lines.append(f"- **path**: `{path}`")
-    if "architectures" in fm:
-        lines.append(f"- **architectures**: {fm['architectures']}")
-    for k in ("confidence", "reproducibility"):
-        if k in fm:
-            lines.append(f"- **{k}**: {fm[k]}")
-    for k in ("tags", "techniques", "hardware_features", "kernel_types", "languages"):
-        v = fm.get(k)
-        if v:
-            lines.append(f"- **{k}**: {v}")
-    if "performance_claims" in fm and isinstance(fm["performance_claims"], list):
-        for claim in fm["performance_claims"][:2]:
-            lines.append(f"- **perf**: {claim.get('value')} {claim.get('metric')} on {claim.get('gpu')} ({claim.get('dtype')}, {claim.get('shape')})")
-    if "sources" in fm:
-        lines.append(f"- **sources**: {fm['sources'][:5]}")
-    return "\n".join(lines)

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/scripts/_wiki_root.py

@@ -1,67 +0,0 @@
-"""Shared wiki-root resolution for skill scripts.
-
-The skill is a flat repository — SKILL.md, data/, wiki/, sources/, queries/
-all live at the same root. So by default the wiki root is this file's
-grandparent directory:
-
-    <wiki-root>/scripts/_wiki_root.py  ->  <wiki-root>
-
-No environment variable is required for the common case. An optional
-BLACKWELL_WIKI_ROOT override is honored for advanced setups (e.g. scripts
-running from a separate checkout). Any detected root is validated; misconfig
-hard-errors rather than silently returning wrong results.
-"""
-
-from __future__ import annotations
-
-import os
-import sys
-from pathlib import Path
-
-
-def _looks_like_wiki_root(p: Path) -> bool:
-    return (p / "data" / "tags.yaml").is_file() and (p / "wiki").is_dir()
-
-
-def _error(msg: str) -> None:
-    print(f"ERROR: {msg}", file=sys.stderr)
-    sys.exit(2)
-
-
-def resolve_wiki_root() -> Path:
-    # 1. explicit env override (advanced use)
-    env = os.environ.get("BLACKWELL_WIKI_ROOT")
-    if env:
-        p = Path(env).expanduser().resolve()
-        if _looks_like_wiki_root(p):
-            return p
-        _error(
-            f"BLACKWELL_WIKI_ROOT={env!r} does not point at a valid "
-            f"Blackwell kernel wiki (missing data/tags.yaml or wiki/)."
-        )
-
-    # 2. default: script-file grandparent == skill/wiki root
-    default_root = Path(__file__).resolve().parent.parent
-    if _looks_like_wiki_root(default_root):
-        return default_root
-
-    # 3. legacy: walk up from script location and from cwd
-    seen = set()
-    for start in (Path(__file__).resolve().parent, Path.cwd().resolve()):
-        for candidate in [start, *start.parents]:
-            if candidate in seen:
-                continue
-            seen.add(candidate)
-            if _looks_like_wiki_root(candidate):
-                return candidate
-
-    _error(
-        "Could not locate the Blackwell kernel wiki root.\n"
-        "       Expected a directory containing `data/tags.yaml` and `wiki/`.\n"
-        "       Fix: run scripts from inside the cloned skill directory, or\n"
-        "       set BLACKWELL_WIKI_ROOT to its absolute path."
-    )
-    return Path()  # unreachable
-
-
-WIKI_ROOT = resolve_wiki_root()