master-skill 0.10.0 → 0.11.0

package/scripts/validate-routing.py

@@ -0,0 +1,254 @@
+#!/usr/bin/env python3
+"""Validate routing.json — the machine-readable master/mode routing table.
+
+`master-skill recommend` and the `/master-help` skill both route off this
+file. It exists because the routing knowledge used to live only as prose:
+a weighted-match paragraph and a 24-row pairing table inside
+prebuilt/compare-masters/SKILL.md, plus a decision tree in
+references/teaching-modes.md. Prose cannot be executed and cannot drift-check
+itself — the original pairing table shipped three key collisions (`戒律`,
+`道次第`, `中观/空性` each matched two or three rows), so which pairing a
+query landed on depended on iteration order.
+
+The central invariant this script enforces is therefore **pairwise
+disjointness**: within `mode_rules`, and within `topic_pairings`, no keyword
+may appear in two rows, and no keyword may be a substring of a keyword in
+another row. Substring matters because `recommend` matches by containment —
+if row A had `道次第` and row B had `菩提道次第`, a query mentioning the
+latter would match both and the winner would be positional. Making that a CI
+error forces collisions to be resolved when the data is authored.
+
+Keyword data for personas is deliberately NOT duplicated into routing.json;
+it stays in each prebuilt/<slug>/meta.json `search_scope.keywords`, so this
+script also checks that every persona still carries usable keywords.
+
+Checks
+------
+  1. version == 1 and the three top-level sections are well-formed
+  2. every mode in `mode_rules` is a `kind: teaching-mode` skill in
+     skill-catalog.json
+  3. every master slug in `topic_pairings` / `default_pairing` is a
+     `kind: persona` skill in skill-catalog.json
+  4. `mode_rules` keyword sets are pairwise disjoint (incl. substrings)
+  5. `topic_pairings` keyword sets are pairwise disjoint (incl. substrings)
+  6. `mode_rules` `order` values are exactly 1..N with no gaps or ties
+  7. every catalog persona is reachable from at least one pairing or the
+     default pairing (no master can become unrecommendable)
+  8. every catalog persona has a non-empty search_scope.keywords
+
+Usage
+-----
+    python scripts/validate-routing.py            # exit 1 on any problem
+    python scripts/validate-routing.py --json
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+ROUTING_PATH = ROOT / "routing.json"
+CATALOG_PATH = ROOT / "skill-catalog.json"
+PREBUILT = ROOT / "prebuilt"
+
+
+def _read_json(p: Path):
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as err:
+        return {"__error__": f"{p.name}: {err}"}
+
+
+def _disjoint_problems(section: str, rows: list) -> list:
+    """Report keyword collisions across rows.
+
+    Two keywords collide when they are equal or one contains the other.
+    Collisions inside a single row are fine (`观智` alongside `十六观智`
+    is a deliberate broadening); collisions across rows are not, because
+    they make the match order-dependent.
+    """
+    problems = []
+    flat = []
+    for row in rows:
+        label = row.get("id") or row.get("mode") or "<unnamed>"
+        for kw in row.get("keywords", []):
+            flat.append((label, kw))
+
+    for i, (label_a, kw_a) in enumerate(flat):
+        for label_b, kw_b in flat[i + 1:]:
+            if label_a == label_b:
+                continue
+            if kw_a == kw_b:
+                problems.append(
+                    f"{section}: keyword {kw_a!r} appears in both "
+                    f"{label_a!r} and {label_b!r}"
+                )
+            elif kw_a in kw_b or kw_b in kw_a:
+                shorter, longer = sorted((kw_a, kw_b), key=len)
+                problems.append(
+                    f"{section}: keyword {shorter!r} ({label_a!r}) is a "
+                    f"substring of {longer!r} ({label_b!r}) — a query "
+                    f"matching the longer one would match both"
+                )
+    return problems
+
+
+def validate(root: Path = ROOT) -> list:
+    problems = []
+
+    routing = _read_json(root / "routing.json")
+    if "__error__" in routing:
+        return [f"cannot read routing.json ({routing['__error__']})"]
+    catalog = _read_json(root / "skill-catalog.json")
+    if "__error__" in catalog:
+        return [f"cannot read skill-catalog.json ({catalog['__error__']})"]
+
+    # 1 — shape
+    if routing.get("version") != 1:
+        problems.append("routing.json: version must be 1")
+
+    mode_rules = routing.get("mode_rules")
+    pairings = routing.get("topic_pairings")
+    default_pairing = routing.get("default_pairing")
+    if not isinstance(mode_rules, list) or not mode_rules:
+        problems.append("routing.json: mode_rules must be a non-empty array")
+        mode_rules = []
+    if not isinstance(pairings, list) or not pairings:
+        problems.append("routing.json: topic_pairings must be a non-empty array")
+        pairings = []
+    if not isinstance(default_pairing, list) or not default_pairing:
+        problems.append("routing.json: default_pairing must be a non-empty array")
+        default_pairing = []
+
+    skills = catalog.get("skills", [])
+    personas = {s["name"] for s in skills if s.get("kind") == "persona"}
+    modes = {s["name"] for s in skills if s.get("kind") == "teaching-mode"}
+
+    # 2 — modes resolve
+    for rule in mode_rules:
+        mode = rule.get("mode")
+        if mode not in modes:
+            problems.append(
+                f"mode_rules: {mode!r} is not a kind:teaching-mode skill in "
+                f"skill-catalog.json (known: {sorted(modes)})"
+            )
+        if not rule.get("keywords"):
+            problems.append(f"mode_rules: {mode!r} has no keywords")
+
+    # 3 — masters resolve
+    situations = routing.get("situations") or []
+    if not isinstance(situations, list):
+        problems.append("routing.json: situations must be an array")
+        situations = []
+
+    referenced = set()
+    for section, rows in (("topic_pairings", pairings), ("situations", situations)):
+        for row in rows:
+            rid = row.get("id", "<unnamed>")
+            if not row.get("keywords"):
+                problems.append(f"{section}: {rid!r} has no keywords")
+            row_masters = row.get("masters", [])
+            if not row_masters:
+                problems.append(f"{section}: {rid!r} has no masters")
+            for slug in row_masters:
+                referenced.add(slug)
+                if slug not in personas:
+                    problems.append(
+                        f"{section}: {rid!r} references {slug!r}, which is "
+                        f"not a kind:persona skill in skill-catalog.json"
+                    )
+    for slug in default_pairing:
+        referenced.add(slug)
+        if slug not in personas:
+            problems.append(
+                f"default_pairing: {slug!r} is not a kind:persona skill in "
+                f"skill-catalog.json"
+            )
+
+    # 4 / 5 — disjointness within each section
+    problems += _disjoint_problems("mode_rules", mode_rules)
+    problems += _disjoint_problems("topic_pairings", pairings)
+    problems += _disjoint_problems("situations", situations)
+
+    # 5b — a situation keyword that also triggers a mode is dead code: the
+    # mode layer short-circuits first, so the situation row can never fire.
+    mode_kws = {kw for r in mode_rules for kw in r.get("keywords", [])}
+    for row in situations:
+        rid = row.get("id", "<unnamed>")
+        for kw in row.get("keywords", []):
+            for mkw in mode_kws:
+                if kw == mkw or kw in mkw or mkw in kw:
+                    problems.append(
+                        f"situations: {rid!r} keyword {kw!r} collides with "
+                        f"mode_rules keyword {mkw!r} — mode_rules is evaluated "
+                        f"first, so this situation row is unreachable"
+                    )
+
+    # 6 — order is a clean 1..N
+    orders = [r.get("order") for r in mode_rules]
+    if sorted(o for o in orders if isinstance(o, int)) != list(
+        range(1, len(mode_rules) + 1)
+    ):
+        problems.append(
+            f"mode_rules: order values must be exactly 1..{len(mode_rules)} "
+            f"with no gaps or ties (got {orders})"
+        )
+
+    # 7 — no unreachable persona
+    for slug in sorted(personas - referenced):
+        problems.append(
+            f"coverage: persona {slug!r} appears in no topic_pairing or "
+            f"situation and is not in default_pairing — it can never be "
+            f"recommended"
+        )
+
+    # 8 — persona keywords still exist (recommend scores off them)
+    for slug in sorted(personas):
+        meta_path = PREBUILT / slug / "meta.json"
+        if not meta_path.exists():
+            problems.append(f"keywords: {slug} has no meta.json")
+            continue
+        meta = _read_json(meta_path)
+        if "__error__" in meta:
+            problems.append(f"keywords: {slug} meta.json unreadable")
+            continue
+        kws = (meta.get("search_scope") or {}).get("keywords")
+        if not kws:
+            problems.append(
+                f"keywords: {slug} has empty search_scope.keywords — "
+                f"`recommend` cannot score it"
+            )
+
+    return problems
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    args = ap.parse_args()
+
+    problems = validate()
+
+    if args.json:
+        print(json.dumps({"ok": not problems, "problems": problems}, indent=2))
+    elif problems:
+        print(f"routing.json validation failed ({len(problems)} problem(s)):\n")
+        for p in problems:
+            print(f"  ✗ {p}")
+        print()
+    else:
+        routing = _read_json(ROUTING_PATH)
+        print(
+            f"routing.json ok — {len(routing.get('mode_rules', []))} mode rules, "
+            f"{len(routing.get('situations', []))} situations, "
+            f"{len(routing.get('topic_pairings', []))} topic pairings, "
+            f"all keyword sets pairwise disjoint."
+        )
+
+    return 1 if problems else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/validate.py

@@ -14,10 +14,11 @@ from __future__ import annotations
 
 import argparse
 import json
-import re
 import sys
 from pathlib import Path
 
+import yaml
+
 PREBUILT_DIR = Path(__file__).resolve().parent.parent / "prebuilt"
 
 # --- Required and recommended fields ---
@@ -48,41 +49,20 @@ def parse_frontmatter(path: Path) -> tuple[dict, str, list[str]]:
     if end is None:
         return {}, text, lines
 
-    # Minimal YAML parse (no pyyaml dependency)
-    fm: dict = {}
-    current_key = None
-    current_list: list | None = None
-    for line in lines[1:end]:
-        # list item
-        if line.startswith("  - ") and current_key:
-            if current_list is None:
-                current_list = []
-            item = line.strip().lstrip("- ").strip()
-            # Try inline dict (title: xxx)
-            if ":" in item:
-                parts = item.split(":", 1)
-                if current_list and isinstance(current_list[-1], dict):
-                    current_list[-1][parts[0].strip()] = parts[1].strip()
-                else:
-                    current_list.append({parts[0].strip(): parts[1].strip()})
-            else:
-                current_list.append(item)
-            continue
-        # Save accumulated list
-        if current_list is not None and current_key:
-            fm[current_key] = current_list
-            current_list = None
-        # key: value
-        match = re.match(r"^(\w[\w_-]*):\s*(.*)", line)
-        if match:
-            current_key = match.group(1)
-            value = match.group(2).strip().strip('"').strip("'")
-            if value:
-                fm[current_key] = value
-            # If empty value, might be a list starting next line
-    # Flush last list
-    if current_list is not None and current_key:
-        fm[current_key] = current_list
+    # This was a hand-rolled parser, from back when pyyaml was not a
+    # dependency. It matched list items only as `  - `, so a 4-space
+    # continuation line like `    cbeta_id: T48n2008` matched neither that nor
+    # the `key:` regex (which is anchored at column 0) and fell through to the
+    # list-flush branch — clearing the accumulated list on every continuation
+    # and letting the next `  - ` overwrite it. Every master kept exactly one
+    # source and no cbeta_id at all, so the sources[] rules below inspected
+    # data that was never in the file.
+    try:
+        fm = yaml.safe_load("\n".join(lines[1:end])) or {}
+    except yaml.YAMLError as exc:
+        raise ValueError(f"{path}: invalid YAML frontmatter — {exc}") from exc
+    if not isinstance(fm, dict):
+        raise ValueError(f"{path}: frontmatter is not a mapping")
 
     body = "\n".join(lines[end + 1 :])
     return fm, body, lines
@@ -274,6 +254,32 @@ def _run_promptfoo_configs_subcheck() -> list[str]:
         return [f"promptfoo-configs sub-check failed to run: {exc}"]
 
 
+def _run_curriculum_sources_subcheck() -> list[str]:
+    """Run the curriculum source validator as a sub-check.
+
+    master-curriculum/SKILL.md claims CI enforces this, but the script was
+    wired into no workflow, no npm script and no sub-check — only its own unit
+    tests, which build synthetic trees under tmp_path. It has never run against
+    the real references/, so a curriculum recommending a sutra no master
+    declares would have shipped unnoticed. Returns a list of error strings.
+    """
+    curriculum_dir = PREBUILT_DIR / "master-curriculum"
+    if not curriculum_dir.exists():
+        return []
+    try:
+        import importlib.util
+
+        spec_path = (
+            Path(__file__).resolve().parent / "validate-curriculum-sources.py"
+        )
+        spec = importlib.util.spec_from_file_location("vcs", spec_path)
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        return mod.validate(PREBUILT_DIR)
+    except Exception as exc:  # pragma: no cover — surfaces to user
+        return [f"curriculum-sources sub-check failed to run: {exc}"]
+
+
 def main():
     parser = argparse.ArgumentParser(description="Master-skill SKILL.md linter")
     parser.add_argument("--master", type=str, help="Lint a specific master only")
@@ -294,6 +300,11 @@ def main():
         action="store_true",
         help="Skip the v0.8 manifest version-drift gate",
     )
+    parser.add_argument(
+        "--skip-curriculum-sources",
+        action="store_true",
+        help="Skip the curriculum source gate",
+    )
     parser.add_argument(
         "--skip-lore-triggers-content",
         action="store_true",
@@ -340,6 +351,13 @@ def main():
         if manifest_errors:
             has_errors = True
 
+    # --- curriculum source gate (full-tree only, HARD gate) ---
+    curriculum_errors: list[str] = []
+    if not args.master and not args.skip_curriculum_sources:
+        curriculum_errors = _run_curriculum_sources_subcheck()
+        if curriculum_errors:
+            has_errors = True
+
     # --- v0.8 lore_triggers-content advisory sub-check ---
     # ADVISORY ONLY: warnings printed but never affect has_errors.
     lore_warnings: list[str] = []
@@ -354,6 +372,8 @@ def main():
             out["promptfoo_configs"] = promptfoo_errors
         if manifest_errors:
             out["manifest_versions"] = manifest_errors
+        if curriculum_errors:
+            out["curriculum_sources"] = curriculum_errors
         if lore_warnings:
             out["lore_triggers_content_advisory"] = lore_warnings
         print(json.dumps(out, indent=2, ensure_ascii=False))
@@ -363,6 +383,7 @@ def main():
             and not persona_errors
             and not promptfoo_errors
             and not manifest_errors
+            and not curriculum_errors
             and not lore_warnings
         )
         if nothing_to_report:
@@ -386,6 +407,11 @@ def main():
                 print("Manifest version-drift gate (v0.8):")
                 for e in manifest_errors:
                     print(f"  [ERROR] {e}")
+            if curriculum_errors:
+                print()
+                print("Curriculum source gate:")
+                for e in curriculum_errors:
+                    print(f"  [ERROR] {e}")
             if lore_warnings:
                 print()
                 print(
@@ -401,6 +427,7 @@ def main():
                 len(persona_errors)
                 + len(promptfoo_errors)
                 + len(manifest_errors)
+                + len(curriculum_errors)
             )
             total_warns += len(lore_warnings)
             print(

package/scripts/verify_citations.py

@@ -33,7 +33,14 @@ _SAFE_MASTER = re.compile(r"^[A-Za-z0-9_-]+$")
 
 # CBETA id 形态:T48n2008 / T08n0235(藏经卷+n+编号),及 API 返回的 X1218 / X0303
 # (无卷号)。无 `n` 的形态只认 T/X 两个集合,避免误吞 Wikidata 的 Q1234 / P5008。
-_CBETA_ID = re.compile(r"\b(?:[A-Z]{1,2}\d+n\d+|[TX]\d{3,})\b")
+#
+# 边界不能用 \b:Python 的 \w 覆盖 CJK,故「卷一T99n9999」的「一」与「T」之间
+# 没有 \b,整块引文会被 audit_answer 当作无 id 跳过 —— 而格式跑偏正是模型最可能
+# 编造经号的时候。改判「前后不是拉丁字母或数字」:汉字紧邻属真实引文形态,须命中;
+# 拉丁字母紧邻(FakeSutraT99n9999)通常意味着它只是更长 token 的一部分,不算引文。
+_CBETA_ID = re.compile(
+    r"(?<![0-9A-Za-z])(?:[A-Z]{1,2}\d+n\d+|[TX]\d{3,})(?![0-9A-Za-z])"
+)
 # 引文块 【…】
 _CITATION_BLOCK = re.compile(r"【([^】]*)】")
 # live 链接 fojin.app/texts/<数字>

package/skill-catalog.json

@@ -0,0 +1,210 @@
+{
+  "version": 1,
+  "skills": [
+    {
+      "name": "master-nagarjuna",
+      "kind": "persona",
+      "source": "prebuilt/master-nagarjuna",
+      "install_dir": "master-nagarjuna",
+      "aliases": [
+        "nagarjuna",
+        "master-nagarjuna"
+      ]
+    },
+    {
+      "name": "master-xuanzang",
+      "kind": "persona",
+      "source": "prebuilt/master-xuanzang",
+      "install_dir": "master-xuanzang",
+      "aliases": [
+        "xuanzang",
+        "master-xuanzang"
+      ]
+    },
+    {
+      "name": "master-kumarajiva",
+      "kind": "persona",
+      "source": "prebuilt/master-kumarajiva",
+      "install_dir": "master-kumarajiva",
+      "aliases": [
+        "kumarajiva",
+        "master-kumarajiva"
+      ]
+    },
+    {
+      "name": "master-huineng",
+      "kind": "persona",
+      "source": "prebuilt/master-huineng",
+      "install_dir": "master-huineng",
+      "aliases": [
+        "huineng",
+        "master-huineng"
+      ]
+    },
+    {
+      "name": "master-zhiyi",
+      "kind": "persona",
+      "source": "prebuilt/master-zhiyi",
+      "install_dir": "master-zhiyi",
+      "aliases": [
+        "zhiyi",
+        "master-zhiyi"
+      ]
+    },
+    {
+      "name": "master-fazang",
+      "kind": "persona",
+      "source": "prebuilt/master-fazang",
+      "install_dir": "master-fazang",
+      "aliases": [
+        "fazang",
+        "master-fazang"
+      ]
+    },
+    {
+      "name": "master-yinguang",
+      "kind": "persona",
+      "source": "prebuilt/master-yinguang",
+      "install_dir": "master-yinguang",
+      "aliases": [
+        "yinguang",
+        "master-yinguang"
+      ]
+    },
+    {
+      "name": "master-ouyi",
+      "kind": "persona",
+      "source": "prebuilt/master-ouyi",
+      "install_dir": "master-ouyi",
+      "aliases": [
+        "ouyi",
+        "master-ouyi"
+      ]
+    },
+    {
+      "name": "master-xuyun",
+      "kind": "persona",
+      "source": "prebuilt/master-xuyun",
+      "install_dir": "master-xuyun",
+      "aliases": [
+        "xuyun",
+        "master-xuyun"
+      ]
+    },
+    {
+      "name": "master-atisha",
+      "kind": "persona",
+      "source": "prebuilt/master-atisha",
+      "install_dir": "master-atisha",
+      "aliases": [
+        "atisha",
+        "master-atisha"
+      ]
+    },
+    {
+      "name": "master-tsongkhapa",
+      "kind": "persona",
+      "source": "prebuilt/master-tsongkhapa",
+      "install_dir": "master-tsongkhapa",
+      "aliases": [
+        "tsongkhapa",
+        "master-tsongkhapa"
+      ]
+    },
+    {
+      "name": "master-milarepa",
+      "kind": "persona",
+      "source": "prebuilt/master-milarepa",
+      "install_dir": "master-milarepa",
+      "aliases": [
+        "milarepa",
+        "master-milarepa"
+      ]
+    },
+    {
+      "name": "master-buddhaghosa",
+      "kind": "persona",
+      "source": "prebuilt/master-buddhaghosa",
+      "install_dir": "master-buddhaghosa",
+      "aliases": [
+        "buddhaghosa",
+        "master-buddhaghosa"
+      ]
+    },
+    {
+      "name": "master-mahasi-sayadaw",
+      "kind": "persona",
+      "source": "prebuilt/master-mahasi-sayadaw",
+      "install_dir": "master-mahasi-sayadaw",
+      "aliases": [
+        "mahasi-sayadaw",
+        "master-mahasi-sayadaw"
+      ]
+    },
+    {
+      "name": "master-ajahn-chah",
+      "kind": "persona",
+      "source": "prebuilt/master-ajahn-chah",
+      "install_dir": "master-ajahn-chah",
+      "aliases": [
+        "ajahn-chah",
+        "master-ajahn-chah"
+      ]
+    },
+    {
+      "name": "compare-masters",
+      "kind": "teaching-mode",
+      "source": "prebuilt/compare-masters",
+      "install_dir": "compare-masters",
+      "aliases": [
+        "compare-masters"
+      ]
+    },
+    {
+      "name": "master-debate",
+      "kind": "teaching-mode",
+      "source": "prebuilt/master-debate",
+      "install_dir": "master-debate",
+      "aliases": [
+        "master-debate"
+      ]
+    },
+    {
+      "name": "master-curriculum",
+      "kind": "teaching-mode",
+      "source": "prebuilt/master-curriculum",
+      "install_dir": "master-curriculum",
+      "aliases": [
+        "master-curriculum"
+      ]
+    },
+    {
+      "name": "master-help",
+      "kind": "teaching-mode",
+      "source": "prebuilt/master-help",
+      "install_dir": "master-help",
+      "aliases": [
+        "help",
+        "master-help"
+      ]
+    },
+    {
+      "name": "create-master",
+      "kind": "generator",
+      "source": ".",
+      "install_dir": "create-master",
+      "aliases": [
+        "create-master"
+      ],
+      "bundle_paths": [
+        "SKILL.md",
+        "tools",
+        "prompts",
+        "references",
+        "requirements.txt",
+        "ETHICS.md",
+        "masters"
+      ]
+    }
+  ]
+}