junsier9/quant-alpha-research-skill / skills/quant-alpha-research
quant-alpha-research
VerifiedFail-closed crypto quant alpha research for repo-native Stage 0/0.5 validation, falsification, provider concordance, and promotion decisions. Use to find/validate alpha, execute quant research roadmaps, audit promotion evidence, turn market commentary into hypotheses, or decide if alpha reruns are allowed; Chinese triggers include 寻找新alpha、验证这个alpha、执行量化研究路线图 and synonyms. Do not use for generic finance, CSV/charting, product Stage 0, unrelated provider debugging, or GitHub/frontend work.
| File | Kind | Size |
|---|---|---|
| .skillignore-secrets | other | 337 B |
| SKILL.md | skill md | 5.7 KB |
| agents/openai.yaml | config | 358 B |
| references/output_templates.md | markdown | 1.9 KB |
| references/patterns.md | markdown | 4.3 KB |
| references/stage0_and_falsification.md | markdown | 3.0 KB |
| scripts/score_eval_cases.py | script | 9.7 KB |
| scripts/validate_skill_package.py | script | 20.5 KB |
scripts/validate_skill_package.py
View on GitHub#!/usr/bin/env python3
"""Validate the quant-alpha-research skill package and optional evidence repo."""
from __future__ import annotations
import argparse
import hashlib
import json
import math
import re
import shutil
import subprocess
from pathlib import Path
from typing import Iterable
SCRIPT_PATH = Path(__file__).resolve()
SKILL_DIR = SCRIPT_PATH.parents[1]
DEFAULT_SCAN_ROOT = SKILL_DIR
MAX_SCAN_BYTES = 5_000_000
MAX_EVIDENCE_DOCS = 16
COMMON_EXCLUDED_DIRS = {
".git",
"__pycache__",
".pytest_cache",
".ruff_cache",
".mypy_cache",
".venv",
"venv",
"node_modules",
"artifacts",
"reports",
"dist",
"build",
}
SECRET_PATTERNS = {
"private_windows_user_path": re.compile(r"\b[A-Z]:[\\/]+Users[\\/]+[^\\/\s\"']+", re.IGNORECASE),
"private_unix_user_path": re.compile(r"(?<!\w)/(?:Users|home)/[A-Za-z0-9._-]+(?:/[^\s\"']*)?", re.IGNORECASE),
"email_address": re.compile(r"\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b", re.IGNORECASE),
"openai_api_key": re.compile(r"\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b"),
"github_token": re.compile(r"\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b|\bgithub_pat_[A-Za-z0-9_]{40,}\b"),
"aws_access_key": re.compile(r"\b(?:AKIA|ASIA)[A-Z0-9]{16}\b"),
# Parse PEM labels separately so certificates are not treated as private keys.
# Digits and hyphens also cover algorithm-specific labels.
"private_key_block": re.compile(r"-----BEGIN (?P<pem_label>[A-Z0-9 -]+?)-----"),
"secret_assignment": re.compile(
r"(?im)^\s*(?:export\s+)?[A-Z0-9_]*(?:API[_-]?KEY|TOKEN|SECRET|PASSWORD|PRIVATE[_-]?KEY|ACCESS[_-]?KEY)[A-Z0-9_]*\s*[:=]\s*['\"]?[^'\"\s#]{12,}"
),
}
TOKEN_CANDIDATE = re.compile(r"(?<![A-Za-z0-9_/+=-])[A-Za-z0-9_/+=-]{32,}(?![A-Za-z0-9_/+=-])")
CHINESE_TRIGGER_MARKERS = {
"find_new_alpha": ("寻找新alpha",),
"validate_this_alpha": ("验证这个alpha",),
"execute_quant_roadmap": ("执行量化研究路线图",),
}
EVIDENCE_PROFILES = {
"generic": [],
}
def read_text(path: Path) -> str:
return path.read_text(encoding="utf-8-sig")
def rel(path: Path, root: Path = DEFAULT_SCAN_ROOT) -> str:
try:
return path.relative_to(root).as_posix()
except ValueError:
return str(path)
def load_evidence_profiles(profile_dir: Path | None = None) -> dict[str, list[str]]:
profiles = {name: list(docs) for name, docs in EVIDENCE_PROFILES.items()}
candidate_dirs = []
if profile_dir is not None:
candidate_dirs.append(profile_dir)
local_profile_dir = SKILL_DIR / "profiles"
if local_profile_dir.exists():
candidate_dirs.append(local_profile_dir)
for directory in candidate_dirs:
if not directory.exists():
continue
for path in sorted(directory.glob("*.json")):
data = json.loads(read_text(path))
name = str(data.get("name") or path.stem).strip()
docs = data.get("required_docs", data.get("docs", []))
if not name:
raise SystemExit(f"profile {path} missing name")
if not isinstance(docs, list) or not all(isinstance(item, str) for item in docs):
raise SystemExit(f"profile {path} must define required_docs as a list of strings")
profiles[name] = docs
return profiles
def parse_skill_description(skill_md_text: str) -> str:
# Single-line YAML subset: JSON-compatible double-quoted strings, YAML
# single-quoted strings (doubled apostrophes), or plain text. Reject malformed
# quoting and unsupported block scalars instead of silently repairing input.
lines = skill_md_text.splitlines()
if not lines or lines[0].strip() != "---":
return ""
try:
end = next(index for index, line in enumerate(lines[1:], start=1) if line.strip() == "---")
except StopIteration:
return ""
for line in lines[1:end]:
if not line.startswith("description:"):
continue
raw = line.split(":", 1)[1].strip()
if not raw:
return ""
if raw.startswith('"'):
try:
parsed = json.loads(raw)
except (json.JSONDecodeError, ValueError):
return ""
return parsed if isinstance(parsed, str) else ""
if raw.startswith("'"):
if not re.fullmatch(r"'(?:[^']|'')*'", raw):
return ""
return raw[1:-1].replace("''", "'")
if raw.startswith(("|", ">")):
return ""
return raw
return ""
def load_excluded_dirs(scan_root: Path) -> set[str]:
excluded = set(COMMON_EXCLUDED_DIRS)
gitignore = scan_root / ".gitignore"
if not gitignore.exists():
return excluded
for line in read_text(gitignore).splitlines():
stripped = line.strip()
if not stripped or stripped.startswith("#") or stripped.startswith("!"):
continue
if not stripped.endswith("/"):
continue
clean = stripped.rstrip("/")
if clean and "/" not in clean and not re.search(r"[*?\[\]]", clean):
excluded.add(clean)
return excluded
def should_scan_file(path: Path, scan_root: Path, excluded_dirs: set[str]) -> bool:
try:
parts = path.relative_to(scan_root).parts
except ValueError:
return False
if any(part in excluded_dirs for part in parts[:-1]):
return False
return path.suffix != ".pyc"
def load_allowed_secret_patterns(extra_patterns: list[str]) -> list[re.Pattern[str]]:
expressions: list[str] = []
ignore_file = SKILL_DIR / ".skillignore-secrets"
if ignore_file.exists():
expressions.extend(
line.strip()
for line in read_text(ignore_file).splitlines()
if line.strip() and not line.lstrip().startswith("#")
)
expressions.extend(extra_patterns)
return [re.compile(expression) for expression in expressions]
def line_at(content: str, position: int) -> str:
line_start = content.rfind("\n", 0, position) + 1
line_end = content.find("\n", position)
if line_end == -1:
line_end = len(content)
return content[line_start:line_end]
def is_allowed_secret_match(
path: Path,
content: str,
position: int,
pattern_name: str,
scan_root: Path,
allowed_patterns: list[re.Pattern[str]],
) -> bool:
if not allowed_patterns:
return False
payload = f"{rel(path, scan_root)}:{pattern_name}:{line_at(content, position)}"
return any(pattern.search(payload) for pattern in allowed_patterns)
def redact_path(path: Path, verbose: bool) -> str:
resolved = path.resolve()
if verbose:
return str(resolved)
return f"<redacted:{resolved.name}>"
def scan_text(path: Path, scan_root: Path) -> tuple[str | None, str | None]:
try:
data = path.read_bytes()
except OSError as exc:
return None, f"could not read {rel(path, scan_root)}: {exc}"
if len(data) > MAX_SCAN_BYTES:
return None, f"skipped oversized file {rel(path, scan_root)}"
if b"\x00" in data[:4096]:
return None, None
return data.decode("utf-8-sig", errors="replace"), None
def shannon_entropy(value: str) -> float:
if not value:
return 0.0
counts = {char: value.count(char) for char in set(value)}
total = len(value)
return -sum((count / total) * math.log2(count / total) for count in counts.values())
def high_entropy_tokens(text: str) -> list[str]:
matches = []
for token in TOKEN_CANDIDATE.findall(text):
if "/" in token or "\\" in token:
continue
if len(set(token)) < 12:
continue
if shannon_entropy(token) >= 4.4:
matches.append(token[:8] + "...redacted")
return matches
def is_detector_definition(path: Path, content: str, position: int) -> bool:
if path.resolve() != SCRIPT_PATH:
return False
line = line_at(content, position)
if "allowed_secret_patterns" in line or "load_allowed_secret_patterns" in line:
return True
return "re.compile" in line or line.strip().startswith("r\"") or line.strip().startswith("r'")
def run_external_secret_scan(required: bool, scan_root: Path) -> tuple[list[str], dict]:
failures: list[str] = []
details = {"requested": required, "scanner": None, "available": False, "passed": None}
gitleaks = shutil.which("gitleaks")
if not gitleaks:
if required:
failures.append("required external secret scanner not found: gitleaks")
return failures, details
details["scanner"] = "gitleaks"
details["available"] = True
result = subprocess.run(
[gitleaks, "detect", "--no-git", "--source", str(scan_root), "--redact", "--exit-code", "1"],
check=False,
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=120,
)
details["passed"] = result.returncode == 0
if result.returncode != 0:
failures.append("gitleaks detected potential secrets")
details["stderr_tail"] = result.stderr[-1000:]
details["stdout_tail"] = result.stdout[-1000:]
return failures, details
def git_status(path: Path, *, ignored: bool = False) -> str | None:
command = ["git", "status", "--short"]
if ignored:
command.append("--ignored")
try:
result = subprocess.run(
command,
cwd=path,
check=False,
capture_output=True,
text=True,
timeout=30,
)
except (OSError, subprocess.SubprocessError):
return None
if result.returncode != 0:
return None
return result.stdout
def summarize_git_status(status: str | None) -> dict:
if status is None:
return {"available": False}
lines = [line for line in status.splitlines() if line.strip()]
counts: dict[str, int] = {}
for line in lines:
code = line[:2].strip() or "tracked"
counts[code] = counts.get(code, 0) + 1
digest = hashlib.sha256(status.encode("utf-8")).hexdigest() if status else None
return {"available": True, "line_count": len(lines), "counts": counts, "digest": digest}
def path_state(paths: Iterable[Path], *, verbose: bool) -> dict[str, dict[str, int | str | bool]]:
state: dict[str, dict[str, int | str | bool]] = {}
for path in paths:
key = redact_path(path, verbose)
try:
stat = path.stat()
except OSError:
state[key] = {"exists": False}
continue
state[key] = {"exists": True, "size": stat.st_size, "mtime_ns": stat.st_mtime_ns}
return state
def select_evidence_docs(
root: Path,
profile: str,
requested_docs: list[str],
profiles: dict[str, list[str]],
) -> tuple[list[Path], list[str], list[str]]:
failures: list[str] = []
warnings: list[str] = []
docs_root = root / "docs" / "quant_research"
if not docs_root.exists():
if not (root / "artifacts" / "quant_research").exists():
failures.append("evidence root lacks docs/quant_research and artifacts/quant_research")
return [], failures, warnings
required = list(profiles[profile])
required.extend(requested_docs)
selected: list[Path] = []
if required:
for doc in required:
path = docs_root / doc
if path.exists():
selected.append(path)
else:
failures.append(f"missing requested quant doc: {doc}")
return selected, failures, warnings
name_pattern = re.compile(r"(alpha|roadmap|factor|stage|provider|falsification|concordance)", re.IGNORECASE)
selected = [
path
for path in sorted(docs_root.glob("*.md"))
if name_pattern.search(path.name)
][:MAX_EVIDENCE_DOCS]
if not selected:
warnings.append("no high-signal quant docs matched generic evidence patterns")
selected = sorted(docs_root.glob("*.md"))[:MAX_EVIDENCE_DOCS]
if not selected:
failures.append("evidence root has docs/quant_research but no markdown docs")
return selected, failures, warnings
def validate_skill_files(
require_external_secret_scan: bool,
*,
scan_root: Path,
allow_patterns: list[str],
) -> tuple[list[str], dict]:
failures: list[str] = []
details: dict = {}
skill_md = SKILL_DIR / "SKILL.md"
if not skill_md.exists():
return ["missing SKILL.md"], details
text = read_text(skill_md)
details["skill_md_lines"] = len(text.splitlines())
if details["skill_md_lines"] > 500:
failures.append("SKILL.md exceeds 500 lines")
if not text.startswith("---"):
failures.append("SKILL.md missing YAML frontmatter")
if "name: quant-alpha-research" not in text:
failures.append("SKILL.md frontmatter missing expected name")
if "description:" not in text:
failures.append("SKILL.md frontmatter missing description")
description = parse_skill_description(text)
details["description_chars"] = len(description)
for phrase in ["alpha", "Stage 0", "falsification", "concordance", "Do not use"]:
if phrase.lower() not in description.lower():
failures.append(f"description missing trigger/boundary phrase: {phrase}")
for name, markers in CHINESE_TRIGGER_MARKERS.items():
if not any(marker in description for marker in markers):
failures.append(f"description missing Chinese trigger marker: {name}")
linked_refs = sorted(set(re.findall(r"`(references/[^`]+\.md)`", text)))
details["linked_references"] = linked_refs
for ref in linked_refs:
if not (SKILL_DIR / ref).exists():
failures.append(f"missing linked reference: {ref}")
openai_yaml = SKILL_DIR / "agents" / "openai.yaml"
if not openai_yaml.exists():
failures.append("missing agents/openai.yaml")
elif "$quant-alpha-research" not in read_text(openai_yaml):
failures.append("openai.yaml default_prompt must mention $quant-alpha-research")
excluded_dirs = load_excluded_dirs(scan_root)
allowed_secret_patterns = load_allowed_secret_patterns(allow_patterns)
scanned_files = [
path
for path in scan_root.rglob("*")
if path.is_file()
and should_scan_file(path, scan_root, excluded_dirs)
]
details["scanned_file_count"] = len(scanned_files)
details["scan_scope"] = "skill" if scan_root.resolve() == SKILL_DIR.resolve() else "explicit_repo_root"
details["excluded_dirs"] = sorted(excluded_dirs)
skipped_files: list[str] = []
for path in scanned_files:
content, warning = scan_text(path, scan_root)
if warning:
skipped_files.append(warning)
if content is None:
continue
placeholder_marker = "TO" + "DO"
if placeholder_marker in content:
failures.append(f"placeholder marker remains in {rel(path, scan_root)}")
for name, pattern in SECRET_PATTERNS.items():
for match in pattern.finditer(content):
if name == "private_key_block" and not match.group("pem_label").endswith("PRIVATE KEY"):
continue
if is_detector_definition(path, content, match.start()):
continue
if is_allowed_secret_match(path, content, match.start(), name, scan_root, allowed_secret_patterns):
continue
failures.append(f"{name} found in {rel(path, scan_root)}")
break
entropy_hits = high_entropy_tokens(content)
if entropy_hits:
failures.append(
f"high_entropy_token candidates found in {rel(path, scan_root)}: {', '.join(entropy_hits[:3])}"
)
details["scan_warnings"] = skipped_files
external_failures, external_details = run_external_secret_scan(require_external_secret_scan, scan_root)
failures.extend(external_failures)
details["external_secret_scan"] = external_details
return failures, details
def probe_evidence_root(
evidence_root: Path,
*,
profile: str,
requested_docs: list[str],
profiles: dict[str, list[str]],
verbose: bool,
) -> tuple[list[str], dict]:
failures: list[str] = []
root = evidence_root.resolve()
details: dict = {"evidence_root": redact_path(root, verbose), "profile": profile}
if not root.exists():
return [f"evidence root does not exist: {redact_path(root, verbose)}"], details
before = git_status(root)
before_ignored = git_status(root, ignored=True)
docs, doc_failures, warnings = select_evidence_docs(root, profile, requested_docs, profiles)
failures.extend(doc_failures)
details["warnings"] = warnings
details["docs_checked"] = [path.name for path in docs]
state_before = path_state(docs, verbose=verbose)
extracted: dict[str, dict[str, object]] = {}
for path in docs:
content = read_text(path)
extracted[path.name] = {
"chars": len(content),
"mentions_canonical_parent": "canonical parent" in content.lower(),
"mentions_falsification": "falsification" in content.lower(),
"mentions_stage0": "stage0" in content.lower() or "stage 0" in content.lower(),
"mentions_concordance": "concordance" in content.lower(),
}
state_after = path_state(docs, verbose=verbose)
after = git_status(root)
after_ignored = git_status(root, ignored=True)
details["doc_signal_summary"] = extracted
details["read_only_guard"] = {
"git_status_unchanged": before == after,
"git_status_with_ignored_unchanged": before_ignored == after_ignored,
"checked_path_count": len(docs),
"checked_paths_unchanged": state_before == state_after,
"git_status_before_summary": summarize_git_status(before),
"git_status_after_summary": summarize_git_status(after),
"git_status_ignored_before_summary": summarize_git_status(before_ignored),
"git_status_ignored_after_summary": summarize_git_status(after_ignored),
}
if verbose:
details["read_only_guard"]["git_status_before"] = before
details["read_only_guard"]["git_status_after"] = after
details["read_only_guard"]["git_status_ignored_before"] = before_ignored
details["read_only_guard"]["git_status_ignored_after"] = after_ignored
details["read_only_guard"]["path_state_before"] = state_before
details["read_only_guard"]["path_state_after"] = state_after
if before != after:
failures.append("evidence root git status changed during read-only probe")
if before_ignored != after_ignored:
failures.append("evidence root ignored-status changed during read-only probe")
if state_before != state_after:
failures.append("evidence root checked path state changed during read-only probe")
return failures, details
def main() -> None:
parser = argparse.ArgumentParser()
parser.add_argument(
"--repo-root",
type=Path,
help="Explicitly widen skill-package scanning beyond the installed skill directory.",
)
parser.add_argument("--evidence-root", type=Path)
parser.add_argument("--evidence-profile", default="generic")
parser.add_argument("--evidence-doc", action="append", default=[])
parser.add_argument("--profile-dir", type=Path, help="Directory of local evidence profile JSON files.")
parser.add_argument("--allow-pattern", action="append", default=[], help="Regex allowlist for a secret-scan hit.")
parser.add_argument("--require-external-secret-scan", action="store_true")
parser.add_argument("--verbose", action="store_true")
args = parser.parse_args()
scan_root = (args.repo_root or DEFAULT_SCAN_ROOT).resolve()
profiles = load_evidence_profiles(args.profile_dir)
if args.evidence_profile not in profiles:
raise SystemExit(
f"unknown evidence profile {args.evidence_profile!r}; available profiles: {', '.join(sorted(profiles))}"
)
failures, details = validate_skill_files(
args.require_external_secret_scan,
scan_root=scan_root,
allow_patterns=args.allow_pattern,
)
evidence_details = None
if args.evidence_root:
evidence_failures, evidence_details = probe_evidence_root(
args.evidence_root,
profile=args.evidence_profile,
requested_docs=args.evidence_doc,
profiles=profiles,
verbose=args.verbose,
)
failures.extend(evidence_failures)
result = {
"passed": not failures,
"failures": failures,
"skill": details,
"evidence_probe": evidence_details,
}
print(json.dumps(result, indent=2, sort_keys=True))
if failures:
raise SystemExit(1)
if __name__ == "__main__":
main()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |