master-skill 0.10.0 → 0.11.0

package/scripts/tests/test_validate_fidelity.py

@@ -20,7 +20,7 @@ def _write_fixture(tmp_path: Path, master_name: str, cases: list[dict]) -> Path:
 def test_compare_requires_framework_output_sections(tmp_path):
     master_dir = _write_fixture(
         tmp_path,
-        "compare",
+        "compare-masters",
         [
             {
                 "q": "禅和净怎么比较？",
@@ -52,7 +52,7 @@ def test_compare_accepts_required_framework_output_sections(tmp_path):
             "must_not_contain": ["更好"],
         }
     )
-    master_dir = _write_fixture(tmp_path, "compare", cases)
+    master_dir = _write_fixture(tmp_path, "compare-masters", cases)
 
     errors = validate_fidelity.validate_master(master_dir)
 

package/scripts/tests/test_validate_workflow.py

@@ -0,0 +1,284 @@
+"""Structural and behavior checks for the repository validation workflow."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+import pytest
+import yaml
+
+
+ROOT = Path(__file__).resolve().parents[2]
+WORKFLOW_PATH = ROOT / ".github" / "workflows" / "validate-and-test.yml"
+WORKFLOW_TEXT = WORKFLOW_PATH.read_text(encoding="utf-8")
+
+
+def _load_workflow_text(text: str) -> dict:
+    workflow = yaml.safe_load(text)
+    assert isinstance(workflow, dict)
+    assert isinstance(workflow.get("jobs"), dict)
+    return workflow
+
+
+def _job(workflow: dict, job_name: str) -> dict:
+    job = workflow["jobs"].get(job_name)
+    assert isinstance(job, dict), f"missing workflow job: {job_name}"
+    assert isinstance(job.get("steps"), list), f"job has no steps: {job_name}"
+    return job
+
+
+def _step(workflow: dict, job_name: str, step_name: str) -> dict:
+    matches = [
+        step
+        for step in _job(workflow, job_name)["steps"]
+        if step.get("name") == step_name
+    ]
+    assert len(matches) == 1, f"expected one {job_name}/{step_name} step, got {len(matches)}"
+    return matches[0]
+
+
+def _assert_hard(step: dict) -> None:
+    assert step.get("continue-on-error") not in (True, "true")
+
+
+WORKFLOW = _load_workflow_text(WORKFLOW_TEXT)
+
+
+def test_free_text_tokens_cannot_substitute_for_workflow_structure():
+    fake = _load_workflow_text(
+        """\
+name: fake
+jobs:
+  validate:
+    steps:
+      - name: comments only
+        run: echo 'python -m pytest tests/ scripts/tests/ -v'
+"""
+    )
+
+    with pytest.raises(AssertionError, match="Run Python tests"):
+        _step(fake, "validate", "Run Python tests")
+
+
+def test_workflow_has_no_softened_steps():
+    for job_name, job in WORKFLOW["jobs"].items():
+        for step in job.get("steps", []):
+            assert step.get("continue-on-error") not in (True, "true"), (
+                f"softened workflow step in {job_name}: {step.get('name', step.get('uses'))}"
+            )
+
+
+@pytest.mark.parametrize(
+    ("step_name", "command"),
+    [
+        ("Run Python tests", "python -m pytest tests/ scripts/tests/ -v"),
+        ("Validate citation contracts", "python scripts/validate-citation-contract.py"),
+        (
+            "Validate lore_triggers content (v0.8 — hard gate)",
+            "python scripts/validate-lore-triggers-content.py --strict",
+        ),
+    ],
+)
+def test_validate_job_contains_hard_gate_commands(step_name: str, command: str):
+    step = _step(WORKFLOW, "validate", step_name)
+    assert step.get("run") == command
+    _assert_hard(step)
+
+
+@pytest.mark.parametrize(
+    ("step_name", "command"),
+    [
+        ("Check desktop formatting", "cargo fmt --manifest-path desktop/Cargo.toml -- --check"),
+        (
+            "Lint desktop app",
+            "cargo clippy --locked --manifest-path desktop/Cargo.toml "
+            "--all-targets -- -D warnings",
+        ),
+        ("Test desktop app", "cargo test --locked --manifest-path desktop/Cargo.toml"),
+        ("Build desktop app", "cargo build --locked --manifest-path desktop/Cargo.toml"),
+    ],
+)
+def test_desktop_job_contains_hard_gate_commands(step_name: str, command: str):
+    step = _step(WORKFLOW, "desktop-rust", step_name)
+    assert step.get("run") == command
+    _assert_hard(step)
+
+
+def test_desktop_quality_gates_run_before_tests_and_build():
+    step_names = [step.get("name") for step in _job(WORKFLOW, "desktop-rust")["steps"]]
+    assert step_names.index("Check desktop formatting") < step_names.index("Lint desktop app")
+    assert step_names.index("Lint desktop app") < step_names.index("Test desktop app")
+    assert step_names.index("Test desktop app") < step_names.index("Build desktop app")
+
+
+def test_windows_cli_job_installs_the_generator_python_runtime():
+    job = _job(WORKFLOW, "cli-windows")
+    uses = [step.get("uses", "") for step in job["steps"]]
+    assert any(use.startswith("actions/setup-python@") for use in uses)
+    install = _step(WORKFLOW, "cli-windows", "Install generator dependencies")
+    assert install.get("run") == "python -m pip install -r requirements.txt"
+    _assert_hard(install)
+
+
+def test_python39_job_compiles_and_runs_the_four_generator_cli_steps():
+    job = _job(WORKFLOW, "python-compat")
+    setup = next(
+        step
+        for step in job["steps"]
+        if str(step.get("uses", "")).startswith("actions/setup-python@")
+    )
+    assert setup.get("with", {}).get("python-version") == "3.9"
+    smoke = _step(WORKFLOW, "python-compat", "Run Python 3.9 generator smoke")
+    command = smoke["run"]
+    assert "python -m compileall -q tools scripts" in command
+    assert "sutra_collector.py" in command
+    assert "verify_sources.py --check-links" in command
+    assert "master_builder.py" in command
+    assert "verify_sources.py --final-check" in command
+    _assert_hard(smoke)
+
+
+def _covered(target: str, patterns: set[str]) -> bool:
+    """Whether a push-paths pattern set actually triggers on `target`.
+
+    The contract is "editing this file runs CI", not "this literal string
+    appears in the list" — so a broader glob that consolidates several entries
+    (docs/PRD.md + docs/v1-framework-roadmap.md -> docs/**) still satisfies it,
+    while dropping the coverage entirely still fails.
+    """
+    if target in patterns:
+        return True
+    return any(
+        target.startswith(pattern[: -len("**")])
+        for pattern in patterns
+        if pattern.endswith("**")
+    )
+
+
+def test_push_paths_include_distribution_and_generator_runtime():
+    triggers = WORKFLOW.get("on", WORKFLOW.get(True))
+    assert isinstance(triggers, dict)
+    paths = set(triggers["push"]["paths"])
+    required = {
+        "skill-catalog.json",
+        "SKILL.md",
+        "references/**",
+        "ETHICS.md",
+        "requirements.txt",
+        "README.md",
+        "README_EN.md",
+        "CONTRIBUTING.md",
+        "CHANGELOG.md",
+        "docs/PRD.md",
+        "docs/v1-framework-roadmap.md",
+        "masters/**",
+        ".claude-plugin/**",
+        ".cursor-plugin/**",
+        "gemini-extension.json",
+        ".github/PULL_REQUEST_TEMPLATE.md",
+        ".github/ISSUE_TEMPLATE/**",
+    }
+    uncovered = sorted(t for t in required if not _covered(t, paths))
+    assert not uncovered, f"push trigger does not cover: {uncovered}"
+
+
+def test_pick_step_uses_checked_selector_without_fixed_roster():
+    checkout = next(
+        step
+        for step in _job(WORKFLOW, "fidelity-smoke")["steps"]
+        if str(step.get("uses", "")).startswith("actions/checkout@")
+    )
+    assert checkout.get("with", {}).get("fetch-depth") == 0
+    step = _step(WORKFLOW, "fidelity-smoke", "Pick smoke target")
+    script = step["run"]
+    assert "if ! CHANGED=$(python scripts/select-fidelity-smoke.py" in script
+    assert "if ! DIFF_OUTPUT=$(git diff --name-only" in script
+    assert "CHANGED_CANDIDATES" in script
+    assert "--prebuilt prebuilt" in script
+    assert '--day-of-year "$(date +%j)"' in script
+    assert "MASTERS=(" not in script
+    _assert_hard(step)
+
+
+def test_smoke_selector_producer_failure_is_not_masked(tmp_path: Path):
+    pick_step = _step(WORKFLOW, "fidelity-smoke", "Pick smoke target")
+    script = pick_step["run"].replace("${{ github.base_ref || 'main' }}", "main")
+
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    fake_python = bin_dir / "python"
+    fake_python.write_text(
+        "#!/bin/sh\nprintf 'master-partial\\n'\nexit 7\n",
+        encoding="utf-8",
+    )
+    fake_python.chmod(0o755)
+    output_path = tmp_path / "github-output"
+    env = os.environ.copy()
+    env["PATH"] = f"{bin_dir}:{env['PATH']}"
+    env["GITHUB_OUTPUT"] = str(output_path)
+
+    result = subprocess.run(
+        ["bash", "-e", "-o", "pipefail", "-c", script],
+        cwd=ROOT,
+        env=env,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+
+    assert result.returncode != 0
+    assert not output_path.exists()
+
+
+def test_smoke_git_diff_failure_is_not_masked(tmp_path: Path):
+    pick_step = _step(WORKFLOW, "fidelity-smoke", "Pick smoke target")
+    script = pick_step["run"].replace("${{ github.base_ref || 'main' }}", "main")
+
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    fake_git = bin_dir / "git"
+    fake_git.write_text("#!/bin/sh\nexit 7\n", encoding="utf-8")
+    fake_git.chmod(0o755)
+    fake_python = bin_dir / "python"
+    fake_python.write_text(
+        "#!/bin/sh\nprintf 'master-alpha\\n'\n",
+        encoding="utf-8",
+    )
+    fake_python.chmod(0o755)
+    output_path = tmp_path / "github-output"
+    env = os.environ.copy()
+    env["PATH"] = f"{bin_dir}:{env['PATH']}"
+    env["GITHUB_OUTPUT"] = str(output_path)
+
+    result = subprocess.run(
+        ["bash", "-e", "-o", "pipefail", "-c", script],
+        cwd=ROOT,
+        env=env,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+
+    assert result.returncode != 0
+    assert "git diff failed" in result.stdout
+    assert not output_path.exists()
+
+
+@pytest.mark.parametrize(
+    ("job_name", "step_name"),
+    [
+        ("fidelity-smoke", "Run fidelity smoke"),
+        ("fidelity-full", "Run fidelity tests"),
+    ],
+)
+def test_each_fidelity_no_key_branch_records_step_summary(job_name: str, step_name: str):
+    job = _job(WORKFLOW, job_name)
+    assert job.get("needs") == "validate"
+    step = _step(WORKFLOW, job_name, step_name)
+    script = step["run"]
+    assert 'if [ -z "${ANTHROPIC_API_KEY:-}" ]; then' in script
+    assert script.count('echo "### Fidelity grading skipped"') == 1
+    assert '} >> "$GITHUB_STEP_SUMMARY"' in script
+    _assert_hard(step)

package/scripts/validate-citation-contract.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""Validate source-neutral citation contracts in persona metadata."""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+
+PREBUILT_DIR = Path(__file__).resolve().parent.parent / "prebuilt"
+
+EXPECTED_PERSONA_SLUGS = (
+    "ajahn-chah",
+    "atisha",
+    "buddhaghosa",
+    "fazang",
+    "huineng",
+    "kumarajiva",
+    "mahasi-sayadaw",
+    "milarepa",
+    "nagarjuna",
+    "ouyi",
+    "tsongkhapa",
+    "xuanzang",
+    "xuyun",
+    "yinguang",
+    "zhiyi",
+)
+
+EXPECTED_REQUIRED_FOR = [
+    "doctrinal_claim",
+    "practice_guidance",
+    "text_interpretation",
+]
+EXPECTED_KEYS = {
+    "version",
+    "claim_policy",
+    "required_for",
+    "allowed_source_types",
+    "minimum_claim_coverage",
+    "live_retrieval_allowed",
+}
+
+
+def _display_path(meta_path: Path) -> str:
+    return f"{meta_path.parent.name}/meta.json"
+
+
+def _persona_count(prebuilt_dir: Path) -> int:
+    count = 0
+    for meta_path in prebuilt_dir.glob("master-*/meta.json"):
+        try:
+            data = json.loads(meta_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        if data.get("kind") != "meta-skill":
+            count += 1
+    return count
+
+
+def validate(prebuilt_dir: Path) -> list[str]:
+    """Return deterministic citation-contract errors for persona metadata."""
+    errors: list[str] = []
+
+    for meta_path in sorted(prebuilt_dir.glob("master-*/meta.json")):
+        path = _display_path(meta_path)
+        try:
+            data = json.loads(meta_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            errors.append(f"{path}: invalid metadata: {exc}")
+            continue
+
+        if data.get("kind") == "meta-skill":
+            if "citation_contract" in data:
+                errors.append(
+                    f"{path}: meta-skill must not declare citation_contract"
+                )
+            continue
+
+        sources = data.get("sources")
+        if not isinstance(sources, list) or not sources:
+            errors.append(f"{path}: persona sources must be a non-empty list")
+            continue
+
+        source_types: list[str] = []
+        for index, source in enumerate(sources):
+            source_type = source.get("type") if isinstance(source, dict) else None
+            if not isinstance(source_type, str) or not source_type.strip():
+                errors.append(
+                    f"{path}: sources[].type at index {index} must be a non-empty string"
+                )
+                continue
+            source_types.append(source_type)
+
+        contract = data.get("citation_contract")
+        if not isinstance(contract, dict):
+            errors.append(f"{path}: citation_contract must be an object")
+            continue
+
+        contract_keys = set(contract)
+        if contract_keys != EXPECTED_KEYS:
+            missing = sorted(EXPECTED_KEYS - contract_keys)
+            extra = sorted(contract_keys - EXPECTED_KEYS)
+            errors.append(
+                f"{path}: citation_contract keys must be exact; "
+                f"missing={missing}, extra={extra}"
+            )
+
+        version = contract.get("version")
+        if type(version) is not int or version != 1:
+            errors.append(f"{path}: version must be integer 1")
+
+        if contract.get("claim_policy") != "declared_sources_only":
+            errors.append(
+                f"{path}: claim_policy must be 'declared_sources_only'"
+            )
+
+        if contract.get("required_for") != EXPECTED_REQUIRED_FOR:
+            errors.append(
+                f"{path}: required_for must equal {EXPECTED_REQUIRED_FOR}"
+            )
+
+        allowed_source_types = contract.get("allowed_source_types")
+        expected_source_types = sorted(set(source_types))
+        if (
+            not isinstance(allowed_source_types, list)
+            or any(
+                not isinstance(source_type, str) or not source_type.strip()
+                for source_type in allowed_source_types
+            )
+            or allowed_source_types != expected_source_types
+        ):
+            errors.append(
+                f"{path}: allowed_source_types must equal {expected_source_types}"
+            )
+
+        coverage = contract.get("minimum_claim_coverage")
+        if (
+            isinstance(coverage, bool)
+            or not isinstance(coverage, (int, float))
+            or coverage != 0.9
+        ):
+            errors.append(f"{path}: minimum_claim_coverage must be numeric 0.9")
+
+        if contract.get("live_retrieval_allowed") is not True:
+            errors.append(f"{path}: live_retrieval_allowed must be true")
+
+    return errors
+
+
+def validate_repository(prebuilt_dir: Path) -> list[str]:
+    """Validate contracts plus the repository's fixed 15-persona roster."""
+    if not prebuilt_dir.is_dir():
+        return [f"{prebuilt_dir}: prebuilt directory not found"]
+
+    errors = validate(prebuilt_dir)
+    discovered: set[str] = set()
+    for meta_path in sorted(prebuilt_dir.glob("master-*/meta.json")):
+        try:
+            data = json.loads(meta_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        if data.get("kind") == "meta-skill":
+            continue
+        discovered.add(meta_path.parent.name.removeprefix("master-"))
+
+    expected = set(EXPECTED_PERSONA_SLUGS)
+    missing = sorted(expected - discovered)
+    unexpected = sorted(discovered - expected)
+    if missing or unexpected or len(discovered) != len(EXPECTED_PERSONA_SLUGS):
+        errors.append(
+            "persona roster must contain exactly "
+            f"{len(EXPECTED_PERSONA_SLUGS)} declared personas; "
+            f"missing={[f'master-{slug}' for slug in missing]}, "
+            f"unexpected={[f'master-{slug}' for slug in unexpected]}"
+        )
+
+    return errors
+
+
+def main() -> int:
+    errors = validate_repository(PREBUILT_DIR)
+    if errors:
+        for error in errors:
+            print(error, file=sys.stderr)
+        return 1
+
+    print(f"citation contracts OK ({_persona_count(PREBUILT_DIR)} personas)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/validate-fidelity.py

@@ -27,6 +27,11 @@ VALID_BOUNDARIES = {
     "no_winner_judgment",
     "no_strawman",
     "no_fabricated_curriculum",
+    # Router skills (/master-help) name a destination and stop. If a router
+    # answers the doctrinal question itself, it does so with none of the
+    # citation_contract / HARD-GATE machinery each persona carries — so
+    # "teaching instead of routing" is a boundary breach, not a shortcut.
+    "router_must_not_teach",
 }
 VALID_PRESSURES = {
     "citation_bypass",
@@ -133,7 +138,7 @@ def validate_master(master_dir: Path) -> list[str]:
             if field in test and not isinstance(test[field], list):
                 errors.append(f"{master_dir.name}:{i}: '{field}' must be a list")
 
-        if master_dir.name == "compare" and test_type not in {"boundary", "pressure"}:
+        if master_dir.name == "compare-masters" and test_type not in {"boundary", "pressure"}:
             sections = set(test.get("must_have_sections", []))
             missing = sorted(COMPARE_REQUIRED_SECTIONS - sections)
             if missing: