master-skill 0.12.10 → 0.12.12

package/prebuilt/master-yinguang/sources/yihanbianfu-excerpts.md

@@ -1,13 +1,14 @@
-# 《一函遍復》关键片段
+# 《印光法師文鈔續編》关键片段（一函遍復、复唐能诚居士书）
 
 > 印光大师著，出自《印光法師文鈔續編》。CBETA 与 FoJin 均未收录文钞，故无经号、无在线链接。
-> 本文件为教学引用用。节选文字尚未与印本逐字核对。
+> 本文件为教学引用用。以下引文已于 2026-09-16 与殆知阁所藏《文鈔續編》全文逐字核对；
+> 此前两段是真语拼接而成的改写，并非原文，已按原书改正。
 
 ## 敦伦尽分、闲邪存诚
 
 原典（节选）：
 
-> 敦伦尽分，闲邪存诚，诸恶莫作，众善奉行。正心诚意，以立人道之本。然后以此回向净土，求生西方。在家人第一须尽各人本分。如父慈子孝，兄友弟恭，夫和妇顺。
+> 又须父慈，子孝，兄友，弟恭，夫和，妇顺，主仁，仆忠，恪尽己分。不计他对我之尽分与否，我总要尽我之分。能于家庭，及与社会，尽谊尽分，是名善人。……念佛最要紧，是敦伦尽分，闲邪存诚，诸恶莫作，众善奉行。存好心，说好话，行好事。
 
 **引用格式：**【《印光法師文鈔續編》·一函遍復】
 
@@ -23,9 +24,9 @@
 
 原典（节选）：
 
-> 因果者，圣人治天下、佛度众生之大权也。若人人深信因果，则人心自善，风俗自淳，唐虞之治不难复见。
+> 吾常曰，因果者，圣人治天下，佛度众生之大权也。
 
-**引用格式：**【《印光法師文鈔續編》·一函遍復】
+**引用格式：**【《印光法師文鈔續編》·复唐能诚居士书】
 
 **教义要点：**
 - 因果为佛法入门之基础

package/prebuilt/master-zhiyi/SKILL.md

@@ -39,7 +39,7 @@ verified_at: 2026-04-06
 - **教义询问**（一念三千 / 三谛 / 五时八教 / 性具善恶）
   → 读 `references/teaching.md` + 引用 `sources/mohezhiguan-excerpts.md`
 - **修行方法**（止观 / 一心三观 / 四种三昧 / 六即判位）
-  → 读 `sources/mohezhiguan-excerpts.md` §止觀法門 + 必要时 `references/teaching.md` §修行方法
+  → 读 `sources/mohezhiguan-excerpts.md` §圆顿止观开篇、§二十五方便、§一心三观、§六即佛 + 必要时 `references/teaching.md` §修行方法
 - **判教体系**（藏通别圆 / 化仪四教 / 五时分判）
   → 读 `references/teaching.md` §判教 + `sources/fahua-xuanyi-excerpts.md`
 - **法华经义理**（开权显实 / 会三归一 / 穷子喻）
@@ -138,7 +138,7 @@ GET https://fojin.app/api/search/semantic?q=<URL编码查询>&top_k=5   # 语义
 | 三谛圆融怎么理解 | `references/teaching.md` §三谛圆融 | 《法華玄義》卷二，T1716 |
 | 五时八教怎么分 | `references/teaching.md` §判教 | 《法華玄義》卷一，T1716 |
 | 止观怎么修 | `sources/mohezhiguan-excerpts.md` §二十五方便 | 《摩訶止觀》卷四，T1911 |
-| 一心三观 | `sources/mohezhiguan-excerpts.md` §一心三觀 | 《摩訶止觀》卷五，T1911 |
+| 一心三观 | `sources/mohezhiguan-excerpts.md` §一心三观 | 《摩訶止觀》卷五，T1911 |
 | 四种三昧 | `references/teaching.md` §四种三昧 | 《摩訶止觀》卷二，T1911 |
 | 性具善恶 | `references/teaching.md` §性具 | 《觀音玄義》卷上，T1726 |
 | 入门从哪开始 | — | 《修習止觀坐禪法要》（小止觀），T1915 |

package/references/workflow-details.md

@@ -235,7 +235,7 @@ FAIL → 自动修复后重审。
 ## Step 5：写入文件细则
 
 ```bash
-python3 ${CLAUDE_SKILL_DIR}/tools/master_builder.py --spec generated-master.json --output masters/
+python3 "${CLAUDE_SKILL_DIR}/tools/master_builder.py" --spec generated-master.json --output "${CLAUDE_SKILL_DIR}/masters/"
 ```
 
 `generated-master.json` 是审查通过后的生成规格，必含 `name`、`tradition`、`school`、`era`、
@@ -245,7 +245,7 @@ python3 ${CLAUDE_SKILL_DIR}/tools/master_builder.py --spec generated-master.json
 ### 生成后终验
 
 ```bash
-python3 ${CLAUDE_SKILL_DIR}/tools/verify_sources.py --final-check masters/master-{slug}/
+python3 "${CLAUDE_SKILL_DIR}/tools/verify_sources.py" --final-check "${CLAUDE_SKILL_DIR}/masters/master-{slug}/"
 ```
 
 `--final-check` 离线验证 persona 目录包含 `SKILL.md`、`teaching.md`、`voice.md`、`meta.json`，
@@ -255,8 +255,8 @@ python3 ${CLAUDE_SKILL_DIR}/tools/verify_sources.py --final-check masters/master
 ### 生成目录结构
 
 ```
-masters/master-{slug}/
-├── SKILL.md          # /master-{slug} 触发（完整角色定义）
+${CLAUDE_SKILL_DIR}/masters/master-{slug}/
+├── SKILL.md          # 注册后由 /master-{slug} 触发（完整角色定义）
 ├── teaching.md       # 教义体系（可单独使用）
 ├── voice.md          # 说法风格（可单独使用）
 └── meta.json         # 元数据（版本、生成时间、数据来源）
@@ -265,9 +265,27 @@ masters/master-{slug}/
 ### 角色注册（按运行环境）
 
 **Claude Code 用户**
-1. 生成的 SKILL.md 已放置在 `masters/master-{slug}/`
-2. 确保 `masters/` 在 Claude Code skill 搜索路径中（检查 `.claude/settings.json` 的 `skillDirs` 配置）
-3. 完成后自动可通过 `/master-{slug}` 触发
+
+终验通过后注册：
+
+```bash
+python3 "${CLAUDE_SKILL_DIR}/tools/master_builder.py" --register "${CLAUDE_SKILL_DIR}/masters/master-{slug}"
+```
+
+它在 `~/.claude/skills/master-{slug}` 建一个指向生成目录的链接（Windows 上建 junction），输出 JSON：
+
+- `invoke`：调用命令，照此告知用户；
+- `restart_required: true`：`~/.claude/skills/` 是这次才建的，需重启 Claude Code 才会被发现；否则当前会话内即可调用；
+- 退出码 1 且提示 `not replacing`：同名 skill 已存在（例如重新生成了一位预置祖师）。**不要删除或覆盖它**，把情况告诉用户，由用户决定改名或自行移除。
+
+为什么需要这一步：Claude Code 只加载 `<skills 目录>/<名字>/SKILL.md`，不往下扫，也没有 `skillDirs` 之类的设置。
+2026-09-16 用 Claude Code 2.1.273 在隔离配置中实测：放在 `~/.claude/skills/create-master/masters/` 下的 persona
+不出现在 `/skills` 里；注册出链接后，同一会话内即出现。生成目录留在 `masters/` 是为了让
+`master-skill update` 更新运行时的时候不丢失用户生成的 persona。
+
+以插件方式安装时，`${CLAUDE_SKILL_DIR}` 是按版本号区分的插件缓存目录：`claude plugin update` 之后
+它换到新版本目录，新目录下的 `masters/` 是空的（实测 0.12.11 → 0.12.12）。要长期保留自己生成的 persona，
+请用 `npx master-skill install create-master` 或 git clone 方式安装生成器。
 
 **OpenClaw 用户**
 1. 将 `masters/master-{slug}/` 复制到 OpenClaw 的 skills 目录
@@ -278,8 +296,8 @@ masters/master-{slug}/
 
 ```
 已生成「{master_name}」教学角色
-  目录：masters/master-{slug}/
-  调用命令：/master-{slug}
+  目录：${CLAUDE_SKILL_DIR}/masters/master-{slug}/
+  调用命令：/master-{slug}（已注册到 ~/.claude/skills/master-{slug}）
   包含文件：SKILL.md, teaching.md, voice.md, meta.json
   数据来源：{n} 条经文，{m} 个知识图谱实体
 ```

package/scripts/check-gate-liveness.py

@@ -25,6 +25,7 @@ Usage:
 from __future__ import annotations
 
 import argparse
+import ast
 import functools
 import json
 import re
@@ -168,6 +169,75 @@ ADVISORY_GATES = {
     ),
 }
 
+# A gate that runs nowhere on a pull request has never guarded a change. This repo
+# has shipped that twice: `validate-curriculum-sources.py` was "wired into no
+# workflow, no npm script and no sub-check — only its own unit tests" (see the
+# sub-check in validate.py that now runs it), and on 2026-09-16
+# `validate-citation-templates.py` and `validate-self-audit-sources.py` were found
+# to live only inside `npm test`, which only npm-publish.yml runs, on a published
+# release. Both passed — the defect was latent, which is exactly why nothing
+# surfaced it.
+#
+# Every entry script under scripts/ must therefore be reachable from a workflow
+# that triggers on `pull_request`, or be declared here with the reason it is not.
+# `check_every_gate_runs_on_a_pr` keeps this true in both directions.
+NOT_A_PR_GATE = {
+    "cite.py": (
+        "a reader-facing offline lookup tool, documented in README.md and in the "
+        "personas' own SKILL.md; not a gate over repository content"
+    ),
+    "query.py": (
+        "a reader-facing offline search tool, documented alongside cite.py; not a "
+        "gate over repository content"
+    ),
+    "check-pe-subsystem.py": (
+        "inspects a built Windows executable, which exists only after the desktop "
+        "release build — release-desktop.yml is the only place it can run"
+    ),
+    "reaudit-report.py": (
+        "re-audits a committed eval run's stored answers; run by hand after a paid "
+        "sweep, against a report that does not exist on a PR"
+    ),
+    "regrade-report.py": (
+        "re-grades a committed eval run against the current judge; same as "
+        "reaudit-report.py — it needs a report a PR does not produce"
+    ),
+}
+
+
+# `npm test` is what CONTRIBUTING tells a contributor to run before touching
+# scripts/, in its own words 「避免在 CI 才发现」. A command that exists to pre-empt CI
+# has to cover what CI checks. It has fallen behind twice: pytest was missing from it
+# until 2026-09-03, and on 2026-09-16 four content gates the PR job runs —
+# validate-citation-contract, validate-cross-critique, validate-lore-triggers-content
+# and validate-quote-attribution — were absent, so a contributor could go green
+# locally and still be failed by CI.
+#
+# Anything the per-PR job runs must therefore appear in `npm test` too, or be
+# declared here. `check_npm_test_covers_pr_gates` keeps this true in both directions.
+NOT_IN_NPM_TEST = {
+    "check-eval-sdk-surface.py": (
+        "asserts the pinned eval SDKs still expose what test-fidelity.py calls — it "
+        "needs requirements-eval.txt installed, which a content contributor has no "
+        "reason to have"
+    ),
+    "smoke-eval-sdk.py": (
+        "stands up a local server for a keyless end-to-end SDK smoke; same eval-only "
+        "dependency, and far slower than the content gates around it"
+    ),
+    "select-fidelity-smoke.py": (
+        "picks which persona the CI smoke grades from job metadata — a CI scheduling "
+        "helper, not a check over repository content"
+    ),
+    "check-audit-ignores.py": (
+        "takes the cargo-audit JSON as an argument — security-scan.yml runs "
+        "`cargo audit --file desktop/Cargo.lock --json > audit.json` first. Without a "
+        "Rust toolchain and the advisory database there is nothing for it to read; "
+        "run bare it exits 2 on argparse usage"
+    ),
+}
+
+
 # The shape of a silent skip: a step that exits 0 because a secret is missing.
 _SKIP_ON_MISSING_SECRET = re.compile(r'\[\s+-z\s+"\$\{[A-Z_]+:-\}"\s+\]')
 
@@ -251,6 +321,161 @@ def check_declared_gates_still_exist(workflow_docs: dict[str, dict]) -> list[str
 # ---------------------------------------------------------------------------
 
 
+def _script_references(source: str, scripts: set[str]) -> set[str]:
+    """Which other scripts this source actually runs — imports and loaded filenames.
+
+    Both spellings are in use: `validate.py` loads five siblings through
+    `spec_from_file_location(..., "validate-curriculum-sources.py")`, which puts the
+    literal filename in the source, while `verify_citations.py` is pulled in as
+    `from verify_citations import …`. Counting only workflow text would report both
+    as unreachable and invent a defect where there is none.
+
+    Read through `ast`, not as text. The first version matched filenames anywhere in
+    the source and reported five scripts as reachable on the strength of *comments*:
+    `verify_citations.py` mentions "scripts/query.py" in a comment about a shared
+    guard, and verify_citations is imported by a job the PR runs, so query.py came
+    out "reachable". Comments do not survive parsing, and an exact-match on string
+    constants keeps a docstring that merely names a path from counting as a call.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:  # pragma: no cover — a syntactically broken script
+        return set()
+
+    wanted = {name: {name, f"scripts/{name}"} for name in scripts}
+    modules = {name[:-3]: name for name in scripts if "-" not in name[:-3]}
+    hit: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and node.module in modules:
+            hit.add(modules[node.module])
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name in modules:
+                    hit.add(modules[alias.name])
+        elif isinstance(node, ast.Constant) and isinstance(node.value, str):
+            for name, spellings in wanted.items():
+                if node.value in spellings:
+                    hit.add(name)
+    return hit
+
+
+def pr_reachable_scripts(root: Path, workflow_docs: dict[str, dict]) -> set[str]:
+    """Scripts a pull request actually executes, following indirect calls."""
+    scripts_dir = root / "scripts"
+    names = {p.name for p in scripts_dir.glob("*.py")}
+    # This file names five scripts in NOT_A_PR_GATE, and this file runs on every PR.
+    # Counting its own source as a caller made each declared script "reachable" and
+    # then reported the declaration as stale — the checker proving its own entries
+    # wrong. Declaring a script is not calling it.
+    sources = {
+        p.name: p.read_text(encoding="utf-8")
+        for p in scripts_dir.glob("*.py")
+        if p.name != Path(__file__).name
+    }
+
+    reachable: set[str] = set()
+    for path, doc in workflow_docs.items():
+        triggers = doc.get("on", doc.get(True))
+        keys = set(triggers) if isinstance(triggers, (dict, list)) else set()
+        if "pull_request" not in keys:
+            continue
+        reachable |= {name for name in names if name in (root / path).read_text(encoding="utf-8")}
+
+    # Fixpoint: a script the PR runs may load or import others.
+    while True:
+        grown = set(reachable)
+        for name in list(reachable):
+            grown |= _script_references(sources.get(name, ""), names)
+        if grown == reachable:
+            return reachable
+        reachable = grown
+
+
+def check_every_gate_runs_on_a_pr(root: Path, workflow_docs: dict[str, dict]) -> list[str]:
+    """An entry script must run on a pull request, or say why it does not."""
+    scripts_dir = root / "scripts"
+    if not scripts_dir.is_dir():
+        return []
+    entries = {
+        p.name
+        for p in scripts_dir.glob("*.py")
+        if "def main(" in p.read_text(encoding="utf-8")
+    }
+    reachable = pr_reachable_scripts(root, workflow_docs)
+
+    problems = [
+        f"scripts/{name} runs nowhere on a pull request and is not in NOT_A_PR_GATE "
+        "— a gate whose first real execution is the release has guarded nothing"
+        for name in sorted(entries - reachable)
+        if name not in NOT_A_PR_GATE
+    ]
+    problems += [
+        f"NOT_A_PR_GATE declares {name!r}, but no such script exists — stale entry"
+        for name in sorted(NOT_A_PR_GATE)
+        if name not in entries
+    ]
+    problems += [
+        f"NOT_A_PR_GATE declares {name!r}, but a pull request does run it now "
+        "— drop the entry rather than leave a false caveat standing"
+        for name in sorted(NOT_A_PR_GATE)
+        if name in reachable
+    ]
+    return problems
+
+
+def npm_test_scripts(root: Path) -> set[str]:
+    """The scripts the documented pre-push command actually runs."""
+    package = root / "package.json"
+    if not package.exists():
+        return set()
+    data = json.loads(package.read_text(encoding="utf-8"))
+    command = str((data.get("scripts") or {}).get("test") or "")
+    return set(re.findall(r"scripts/([a-z0-9_-]+\.py)", command))
+
+
+def pr_workflow_scripts(root: Path, workflow_docs: dict[str, dict]) -> set[str]:
+    """Scripts named outright by a workflow that triggers on `pull_request`.
+
+    Direct mentions only, unlike `pr_reachable_scripts`: `npm test` runs commands, so
+    what it has to match is the commands CI runs, not everything those import.
+    """
+    named: set[str] = set()
+    for path, doc in workflow_docs.items():
+        triggers = doc.get("on", doc.get(True))
+        keys = set(triggers) if isinstance(triggers, (dict, list)) else set()
+        if "pull_request" not in keys:
+            continue
+        named |= set(re.findall(r"scripts/([a-z0-9_-]+\.py)", (root / path).read_text(encoding="utf-8")))
+    return named
+
+
+def check_npm_test_covers_pr_gates(root: Path, workflow_docs: dict[str, dict]) -> list[str]:
+    """What CI runs on a PR, `npm test` must run too — or say why it does not."""
+    if not (root / "package.json").exists():
+        return []
+    in_ci = pr_workflow_scripts(root, workflow_docs)
+    in_npm = npm_test_scripts(root)
+
+    problems = [
+        f"scripts/{name} runs on every PR in CI but is not in `npm test` and not in "
+        "NOT_IN_NPM_TEST — the command that exists to pre-empt CI does not cover it"
+        for name in sorted(in_ci - in_npm)
+        if name not in NOT_IN_NPM_TEST
+    ]
+    problems += [
+        f"NOT_IN_NPM_TEST declares {name!r}, but `npm test` runs it now — drop the "
+        "entry rather than leave a false caveat standing"
+        for name in sorted(NOT_IN_NPM_TEST)
+        if name in in_npm
+    ]
+    problems += [
+        f"NOT_IN_NPM_TEST declares {name!r}, but no PR workflow runs it — stale entry"
+        for name in sorted(NOT_IN_NPM_TEST)
+        if name not in in_ci
+    ]
+    return problems
+
+
 def discover_test_files(root: Path) -> list[str]:
     return sorted(
         str(p.relative_to(root))
@@ -356,6 +581,8 @@ def run_all(root: Path, fidelity_report: Path | None = None) -> list[str]:
     workflows = read_workflows(root)
     problems += check_advisory_gates_declared(workflows)
     problems += check_declared_gates_still_exist(workflows)
+    problems += check_every_gate_runs_on_a_pr(root, workflows)
+    problems += check_npm_test_covers_pr_gates(root, workflows)
 
     # check_graded_suites_graded_something shipped fully written and unit-tested
     # but unreferenced by run_all — the anti-fake-green script had a check that

package/scripts/validate-quote-attribution.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""Gate: every line a persona presents as a quotation must name where it is from.
+
+Steps 3h and 3i of the weekly check ask whether a quoted line exists — in CBETA,
+or in the compiled teachings CBETA does not hold. Neither asks whether the reader
+is told *which book* it came from, and that gap is where a misattribution
+survives both: master-nagarjuna's 「宁起我见积若须弥」 is real text, findable in
+CBETA, and not his — it is in 《大宝积经》. "Found in the canon" and "correctly
+attributed" are different questions, and only the first was being asked.
+
+This one is offline, so it runs on every PR instead of once a week.
+
+Attribution counts when the source is named:
+
+  - on the quoted line itself — 《书名》, 【…】, `Toh 3861`, `SC: SN 22.59`, 卷N;
+  - on a `> 出处：…` line a few lines below (the excerpt files put it there);
+  - on a sibling item of the same numbered list (one 出处 covers the block, which
+    is how master-fazang's and master-kumarajiva's voice samples are written);
+  - in the nearest section heading above (master-ajahn-chah's sutta excerpts name
+    the sutta in the `###` heading).
+
+It reuses `tools/verify_sources.collect_persona_quotes`, so the set it checks is
+exactly the set 3h and 3i judge — if the collector learns a new quotation shape,
+this gate covers it the same day.
+"""
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+
+_TOOLS = os.path.join(os.path.dirname(os.path.abspath(__file__)), os.pardir, "tools")
+if _TOOLS not in sys.path:
+    sys.path.insert(0, _TOOLS)
+
+try:
+    from verify_sources import PREBUILT_DIR, collect_persona_quotes
+except ImportError as exc:  # pragma: no cover - the gate must not pass silently
+    print(f"FAIL: cannot import the quote collector from tools/ ({exc}).")
+    print("A gate that cannot load what it checks has not checked anything.")
+    sys.exit(1)
+
+# 什么算「写明了出处」。SC:/Toh/PTS 是南传与藏传的写法，卷N 与《…》是汉传的。
+_SOURCE_NAMED = re.compile(
+    r"《[^》]{1,40}》|【|Toh[:\s]\d|SC[:：]|\b[SMAD]N \d|Vism|PTS|卷[一二三四五六七八九十百千\d]|[Ss]utta"
+)
+_NUMBERED_ITEM = re.compile(r"^\s*\d+\.\s")
+_LOOK = 8
+
+
+def attribution(lines: list[str], number: int) -> str | None:
+    """这条引文的出处写在哪儿；哪儿都没写就返回 None。"""
+    i = number - 1
+    if i < 0 or i >= len(lines):
+        return None
+    if _SOURCE_NAMED.search(lines[i]):
+        return "on the line"
+
+    # 摘录文件把「出处」写在引文下方几行。
+    for j in range(i + 1, min(len(lines), i + 1 + _LOOK)):
+        if "出处" in lines[j]:
+            return f"出处 line {j - i} below" if _SOURCE_NAMED.search(lines[j]) else None
+
+    # 编号示例句：整块共用一个出处，挂在其中一条上。
+    if _NUMBERED_ITEM.match(lines[i]):
+        low = i
+        while low - 1 >= 0 and _NUMBERED_ITEM.match(lines[low - 1]):
+            low -= 1
+        high = i
+        while high + 1 < len(lines) and _NUMBERED_ITEM.match(lines[high + 1]):
+            high += 1
+        for j in range(low, high + 1):
+            if j != i and _SOURCE_NAMED.search(lines[j]):
+                return f"sibling list item {j + 1 - low}"
+
+    # 最近的小节标题。
+    for j in range(i - 1, max(-1, i - 1 - _LOOK), -1):
+        if lines[j].startswith("#"):
+            return f"heading {i - j} above" if _SOURCE_NAMED.search(lines[j]) else None
+    return None
+
+
+def unattributed(quotes: list[tuple[str, str, str]], read) -> list[tuple[str, str]]:
+    """[(位置, 引文)]：读者无从知道出自哪部书的引文。"""
+    cache: dict[str, list[str]] = {}
+    missing: list[tuple[str, str]] = []
+    for where, _master, quote in quotes:
+        rel, _, number = where.rpartition(":")
+        if not number.isdigit():
+            continue  # meta.json 的 lore_triggers 之类，不是文档行
+        if rel not in cache:
+            cache[rel] = read(rel)
+        if attribution(cache[rel], int(number)) is None:
+            missing.append((where, quote))
+    return missing
+
+
+def main() -> int:
+    def read(rel: str) -> list[str]:
+        return Path(PREBUILT_DIR, rel).read_text(encoding="utf-8").splitlines()
+
+    quotes = collect_persona_quotes()
+    if not quotes:
+        print("FAIL: the quote collector returned nothing — this gate examined an empty set.")
+        return 1
+
+    missing = unattributed(quotes, read)
+    if missing:
+        print(f"FAIL: {len(missing)} quoted line(s) name no source:")
+        for where, quote in missing:
+            print(f"  {where}\n      「{quote[:56]}」")
+        print(
+            "\nA reader cannot check a quotation whose book is never named, and a line\n"
+            "that happens to exist somewhere in the canon passes the weekly checks while\n"
+            "still being the wrong master's words. Name the work on the line, in the\n"
+            "`> 出处：` line below it, on a sibling numbered item, or in the heading above."
+        )
+        return 1
+
+    print(f"OK: all {len(quotes)} quoted lines name the work they come from.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/validate-section-references.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""Gate: a "read `file.md` §section" instruction must land on something.
+
+Every persona's SKILL.md routes a question to material: a decision tree says
+读 `references/teaching.md` §参话头, a Quick Reference row says the same. The
+model follows those pointers literally. Nothing checked that the section they
+name exists, and the files they point into have been rewritten many times since
+the routing was written — sections renamed to a book's real chapter titles,
+material moved from references/ to sources/.
+
+2026-09-16, measured across the repo: 18 of 198 section pointers in nine personas
+named a section the target file does not have, and so did one in the generator's
+own SKILL.md. Most were renames (§戒律根本 for 戒律为根本), but not all were
+harmless:
+
+  - master-milarepa routed 那洛六法 / 拙火 / 气脉明点 to
+    `sources/grubum-excerpts.md` §拙火与气脉. That file has no such section on
+    purpose — it lists tummo among what it deliberately does not hold, with the
+    answer to give instead. The pointer sent the model to look for exactly the
+    material the persona is forbidden to supply.
+  - master-mahasi-sayadaw routed 十六观智 to §十六观智 in an excerpt file whose
+    section is 观智次第 and which says the book numbers seventeen, not sixteen.
+  - master-ajahn-chah sent 心的训练 to references/teaching.md; the section is in
+    sources/teachings-excerpts.md.
+
+A section counts as present when the name appears, ignoring punctuation and
+spacing, in a heading of the target file or in a **bold label** — the persona
+docs use bold labels (**十念法**, **数息观**) as sub-section markers, and a model
+searching for the name finds either. Parenthesised glosses are optional on both
+sides of the match, so §觉受与证悟 finds `6. 觉受 (nyams) 与证悟 (rtogs pa) 的区分`.
+Prose may run on after a name (§版权分级 Tier B/C 流程), so trailing words split
+off by spaces are dropped one at a time; the first word must still be found.
+
+A path with a directory in it must name a file that exists even with no section.
+A bare `teaching.md` without one is prose — the generator docs name the files
+they produce that way — and is not a pointer.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+PREBUILT_DIR = ROOT / "prebuilt"
+
+# The docs the model is told to follow: every persona and mode, and the
+# generator skill with its references.
+DOC_GLOBS = ("prebuilt/**/*.md", "SKILL.md", "references/*.md")
+
+_PATH = re.compile(r"`((?:[\w-]+/)*[\w.-]+\.md)`")
+# A section name ends at the next separator a routing line uses: `+`, a table
+# pipe, CJK punctuation, a backtick or an opening gloss.
+_SECTIONS = re.compile(r"(?:[ \t、]*§[^§`+＋\n，、；;|。（）()]*)+")
+_SECTION = re.compile(r"§([^§、]*)")
+_BOLD = re.compile(r"\*\*([^*\n]+)\*\*")
+_GLOSS = re.compile(r"[（(][^（）()]*[）)]")
+_NUMBERING = re.compile(r"^\s*(?:\d+\.|[①-⑳])\s*")
+_NOISE = re.compile(r"[\s·、，,。.:：—\-–《》「」\"'`*§⚠️]")
+
+
+def _norm(text: str) -> str:
+    return _NOISE.sub("", _NUMBERING.sub("", text)).lower()
+
+
+def anchor_forms(anchor: str) -> set[str]:
+    """一个标题或粗体标签可被匹配的写法：连同括注，或去掉括注。"""
+    return {_norm(re.sub(r"[（）()]", "", anchor)), _norm(_GLOSS.sub("", anchor))}
+
+
+def anchors(lines: list[str]) -> list[str]:
+    found = [line.lstrip("#").strip() for line in lines if line.startswith("#")]
+    for line in lines:
+        found.extend(_BOLD.findall(line))
+    return found
+
+
+def section_present(name: str, lines: list[str]) -> bool:
+    forms = {form for anchor in anchors(lines) for form in anchor_forms(anchor)}
+    words = name.split()
+    while words:
+        wanted = _norm(" ".join(words))
+        if wanted and any(wanted in form for form in forms):
+            return True
+        words.pop()
+    return not _norm(name)
+
+
+def references(line: str) -> list[tuple[str, list[str]]]:
+    """[(路径, [小节名…])]：这一行里的每个文件指针及其所指小节。"""
+    out = []
+    for m in _PATH.finditer(line):
+        tail = _SECTIONS.match(line, m.end())
+        names = []
+        if tail:
+            names = [n.strip() for n in _SECTION.findall(tail.group(0)) if n.strip()]
+        out.append((m.group(1), names))
+    return out
+
+
+def _skill_root(doc: Path) -> Path:
+    rel = doc.relative_to(ROOT)
+    return ROOT / rel.parts[0] / rel.parts[1] if rel.parts[0] == "prebuilt" else ROOT
+
+
+def resolve(doc: Path, rel: str) -> Path | None:
+    for base in (_skill_root(doc), doc.parent, ROOT):
+        if (base / rel).is_file():
+            return base / rel
+    return None
+
+
+def dangling(docs: list[Path]) -> tuple[int, list[str]]:
+    """(检查过的指针数, [问题…])。"""
+    examined, problems = 0, []
+    cache: dict[Path, list[str]] = {}
+    for doc in docs:
+        for number, line in enumerate(doc.read_text(encoding="utf-8").splitlines(), 1):
+            if "{" in line:
+                continue  # 模板行，如 `prebuilt/{slug}/…` 下的 `references/teaching.md`
+            where = f"{doc.relative_to(ROOT)}:{number}"
+            for rel, names in references(line):
+                if "/" not in rel and not names:
+                    continue  # 裸文件名是行文，不是指针
+                examined += 1
+                target = resolve(doc, rel)
+                if target is None:
+                    problems.append(f"{where}  `{rel}` does not exist")
+                    continue
+                if target not in cache:
+                    cache[target] = target.read_text(encoding="utf-8").splitlines()
+                for name in names:
+                    if not section_present(name, cache[target]):
+                        problems.append(f"{where}  `{rel}` has no section §{name}")
+    return examined, problems
+
+
+def model_facing_docs() -> list[Path]:
+    return sorted({p for pattern in DOC_GLOBS for p in ROOT.glob(pattern) if p.is_file()})
+
+
+def main() -> int:
+    examined, problems = dangling(model_facing_docs())
+    if examined == 0:
+        print("FAIL: found no file pointers at all — this gate examined an empty set.")
+        return 1
+    if problems:
+        print(f"FAIL: {len(problems)} of {examined} file pointer(s) do not land:")
+        for problem in problems:
+            print(f"  {problem}")
+        print(
+            "\nThe model follows these pointers literally. A section that is not there\n"
+            "leaves it to improvise the material it was sent to read. Point at a heading\n"
+            "or **bold label** the file actually has, or drop the § and name the file."
+        )
+        return 1
+    print(f"OK: all {examined} file pointers land on a file and section that exist.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())