@teevee98/synapse-hub 4.1.4 ā 4.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/rules/git-push-protocol.md +2 -2
- package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +52 -3
- package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +55 -5
- package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +62 -67
- package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +54 -4
- package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +62 -12
- package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +55 -8
- package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +60 -12
- package/.agents/skills/01-web-automation/mobile-appium-som/examples/BaseScreen.java +2 -2
- package/.agents/skills/01-web-automation/mobile-appium-som/examples/LoginScreen.java +2 -2
- package/.agents/skills/01-web-automation/mobile-appium-som/examples/TC_MobileLogin.java +2 -2
- package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +54 -91
- package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +59 -11
- package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +50 -4
- package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +55 -9
- package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +55 -9
- package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +55 -8
- package/.agents/skills/02-test-design/review-spec/SKILL.md +50 -6
- package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +50 -4
- package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +56 -5
- package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +53 -7
- package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +86 -36
- package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +54 -6
- package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +50 -6
- package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +50 -3
- package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +63 -14
- package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +51 -5
- package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +54 -4
- package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +51 -5
- package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +53 -6
- package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +54 -8
- package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +60 -24
- package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +52 -6
- package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +56 -10
- package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +58 -12
- package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +58 -12
- package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +53 -5
- package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +56 -5
- package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +53 -4
- package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +58 -5
- package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +57 -11
- package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +83 -34
- package/.agents/skills/08-code-quality/graphify-impact-analyzer/examples/dependency_blast_radius.json +3 -4
- package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +55 -10
- package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +49 -6
- package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +52 -7
- package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +55 -10
- package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +51 -5
- package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +54 -17
- package/.agents/skills/09-ci-and-devops/github-actions-templates/examples/matrix_test_pipeline.yml +2 -1
- package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +50 -4
- package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +53 -7
- package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +50 -4
- package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +58 -13
- package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +51 -5
- package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +57 -10
- package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +50 -4
- package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +50 -4
- package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +55 -9
- package/.cursor/rules/synapse-qa.mdc +20 -7
- package/.cursorrules +19 -5
- package/.windsurfrules +18 -3
- package/AGENTS.md +51 -59
- package/CLAUDE.md +38 -24
- package/LICENSE +5 -5
- package/NOTICE +1 -1
- package/README.en.md +4 -4
- package/README.md +4 -4
- package/agentskills.json +1 -1
- package/docs/ARCHITECTURE.en.md +2 -2
- package/docs/ARCHITECTURE.md +11 -2
- package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
- package/docs/CLI_REFERENCE.en.md +6 -4
- package/docs/CLI_REFERENCE.md +1 -1
- package/docs/CONTRIBUTING.en.md +1 -1
- package/docs/CONTRIBUTING.md +2 -2
- package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
- package/docs/TOOL_CATALOG.md +6 -2
- package/docs/research/agent_skill_training_analysis.md +1 -1
- package/package.json +1 -1
- package/plugin.json +1 -1
- package/skills_manifest.json +320 -55
- package/synapse.config.json +1 -1
- package/templates/ai_bridges/CLAUDE.md +29 -26
- package/templates/ai_bridges/copilot-instructions.md +14 -5
- package/templates/ai_bridges/cursor_synapse_qa.mdc +16 -7
- package/templates/ai_bridges/windsurfrules +14 -3
- package/templates/ui/index.html +2 -2
- package/tools/TOOLS_RUNBOOK.md +1 -1
- package/tools/TOOL_CATALOG.json +63 -3
- package/tools/__init__.py +1 -1
- package/tools/api_fuzzer.py +447 -132
- package/tools/author_integrity.py +121 -11
- package/tools/benchmark_swarm_context.py +130 -22
- package/tools/break_ui_generator.py +233 -0
- package/tools/browser_helpers.js +2 -2
- package/tools/check_version_sync.py +18 -50
- package/tools/cli.py +110 -19
- package/tools/core/bm25_retriever.py +218 -0
- package/tools/core/i18n.py +5 -5
- package/tools/core/provider_usage_adapter.py +383 -0
- package/tools/core/token_estimator.py +81 -15
- package/tools/count_tokens.py +7 -2
- package/tools/coverage_reporter.py +245 -0
- package/tools/dashboard_generator.py +8 -8
- package/tools/db_sandbox.py +290 -9
- package/tools/distill_log.py +1 -1
- package/tools/distill_skill.py +206 -0
- package/tools/git_pre_commit_guard.py +202 -1
- package/tools/humanize_linter.py +3 -0
- package/tools/mcp_docx_server.py +1 -1
- package/tools/mcp_excel_server.py +1 -1
- package/tools/mcp_server.py +104 -16
- package/tools/micro_mutator.py +114 -15
- package/tools/pentest_scope_guard.py +674 -58
- package/tools/perf/benchmark_perf_runner.py +42 -0
- package/tools/project_state.py +29 -5
- package/tools/reversible_sandbox.py +58 -13
- package/tools/rules_router.py +473 -60
- package/tools/security_scanner.py +80 -0
- package/tools/senior_code_review.py +14 -0
- package/tools/skill_canonical_digest.py +302 -0
- package/tools/skill_profiles.py +77 -7
- package/tools/slide_deck_exporter.py +477 -0
- package/tools/sync_agent_rules.py +187 -61
- package/tools/sync_skills_manifest.py +166 -0
- package/tools/task_memory_manager.py +275 -0
- package/tools/ui_server.py +3 -1
- package/tools/update_sentinel.py +3 -3
- package/tools/validate_host_interop.py +485 -0
- package/tools/validate_skills_schema.py +575 -0
- package/tools/verify_all.py +668 -44
- package/tools/welcome_page.py +2 -2
|
@@ -0,0 +1,575 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
# SPDX-FileCopyrightText: Copyright (c) 2026 Thįŗæ Vį» (@TeeVee98). All rights reserved.
|
|
3
|
+
# SPDX-License-Identifier: MIT
|
|
4
|
+
# Project: Synapse-Hub (https://github.com/TeeVee98/Synapse-Hub)
|
|
5
|
+
|
|
6
|
+
"""
|
|
7
|
+
tools/validate_skills_schema.py ā Standalone Skill Schema & Policy Validator
|
|
8
|
+
Validates all skills against:
|
|
9
|
+
- Layer 1: Upstream Schema Conformance (Agent Skills Specification v1.0)
|
|
10
|
+
- Layer 2: Synapse Policy Extensions (Policies, 5 Sections, Code Blocks, Links & Pinning)
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
import sys
|
|
14
|
+
import re
|
|
15
|
+
import json
|
|
16
|
+
import argparse
|
|
17
|
+
import importlib.util
|
|
18
|
+
from dataclasses import dataclass
|
|
19
|
+
from pathlib import Path
|
|
20
|
+
from typing import Dict, Any, List, Tuple, Optional
|
|
21
|
+
|
|
22
|
+
# Enforce UTF-8 stdout encoding for Windows console compatibility
|
|
23
|
+
if hasattr(sys.stdout, "reconfigure"):
|
|
24
|
+
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
|
|
25
|
+
if hasattr(sys.stderr, "reconfigure"):
|
|
26
|
+
sys.stderr.reconfigure(encoding="utf-8", errors="replace")
|
|
27
|
+
|
|
28
|
+
ALLOWED_CATEGORIES = {
|
|
29
|
+
"test_automation_and_execution",
|
|
30
|
+
"architecture_and_analysis",
|
|
31
|
+
"verification_and_resilience",
|
|
32
|
+
"context_and_optimization",
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
ALLOWED_POLICIES = {
|
|
36
|
+
"network": {"none", "localhost-only", "sandbox-only"},
|
|
37
|
+
"shell": {"none", "read-only", "workspace-sandbox"},
|
|
38
|
+
"filesystem": {"read-only", "workspace-sandbox"},
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
SEMVER_REGEX = re.compile(r"^\d+\.\d+\.\d+$")
|
|
42
|
+
SKILL_NAME_REGEX = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
|
|
43
|
+
MD_LINK_REGEX = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
|
|
44
|
+
GITHUB_ACTION_REGEX = re.compile(r"uses:\s*actions/([a-zA-Z0-9_-]+)@([^\s#]+)")
|
|
45
|
+
COMMIT_SHA_40_REGEX = re.compile(r"^[0-9a-f]{40}$")
|
|
46
|
+
|
|
47
|
+
# Unproven quantitative / superlative claims patterns
|
|
48
|
+
UNPROVEN_CLAIMS_PATTERNS = [
|
|
49
|
+
re.compile(r"98%\s+of\s+all\s+risky\s+logic", re.IGNORECASE),
|
|
50
|
+
re.compile(r"80%\s+of\s+daily\s+test\s+automation\s+defects", re.IGNORECASE),
|
|
51
|
+
re.compile(r"100%\s+selector\s+hit\s+rate", re.IGNORECASE),
|
|
52
|
+
re.compile(r"100%\s+in\s+200ms", re.IGNORECASE),
|
|
53
|
+
re.compile(r"Infinite\s+CI/CD\s+replays\s+with\s+0\s+LLM\s+Tokens", re.IGNORECASE),
|
|
54
|
+
re.compile(r"100%\s+stable\s+tests\s*\(Zero\s+Flaky\s+Disruptions\)", re.IGNORECASE),
|
|
55
|
+
]
|
|
56
|
+
|
|
57
|
+
REQUIRED_SECTION_PATTERNS = [
|
|
58
|
+
(1, re.compile(r"^##\s+1\.\s+Trigger\s*&\s*Activation", re.IGNORECASE | re.MULTILINE), "1. Trigger & Activation ('Use when...')"),
|
|
59
|
+
(2, re.compile(r"^##\s+2\.\s+Non-Goals?\s*&\s*Boundary\s*Constraints?", re.IGNORECASE | re.MULTILINE), "2. Non-Goals & Boundary Constraints"),
|
|
60
|
+
(3, re.compile(r"^##\s+3\.\s+Ordered\s+Execution\s+Workflow", re.IGNORECASE | re.MULTILINE), "3. Ordered Execution Workflow"),
|
|
61
|
+
(4, re.compile(r"^##\s+4\.\s+Verification\s+Points?\s*&\s*DoD", re.IGNORECASE | re.MULTILINE), "4. Verification Points & DoD"),
|
|
62
|
+
(5, re.compile(r"^##\s+5\.\s+Handoff\s+Protocol", re.IGNORECASE | re.MULTILINE), "5. Handoff Protocol"),
|
|
63
|
+
]
|
|
64
|
+
|
|
65
|
+
# Backtick reference path pattern: matches backtick paths like `dir/file.ext` or `reports/file.json`
|
|
66
|
+
BACKTICK_PATH_REGEX = re.compile(r"`([a-zA-Z0-9_.-]+/[a-zA-Z0-9_./-]+\.[a-zA-Z0-9_-]+)`")
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
@dataclass
|
|
70
|
+
class CodeBlockInfo:
|
|
71
|
+
language: str
|
|
72
|
+
classification: str # "runnable" | "pseudocode" | "illustrative" | "unclassified"
|
|
73
|
+
code: str
|
|
74
|
+
start_line: int
|
|
75
|
+
has_prerequisites: bool = False
|
|
76
|
+
has_test_data: bool = False
|
|
77
|
+
has_expected_output: bool = False
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def classify_code_blocks(file_content: str) -> List[CodeBlockInfo]:
|
|
81
|
+
"""
|
|
82
|
+
Parses markdown content and extracts all fenced code blocks with language,
|
|
83
|
+
classification (runnable, pseudocode, illustrative), and metadata.
|
|
84
|
+
"""
|
|
85
|
+
blocks: List[CodeBlockInfo] = []
|
|
86
|
+
lines = file_content.splitlines()
|
|
87
|
+
in_block = False
|
|
88
|
+
current_lang = ""
|
|
89
|
+
current_lines: List[str] = []
|
|
90
|
+
block_start_line = 0
|
|
91
|
+
preceding_comment_classification: Optional[str] = None
|
|
92
|
+
preceding_comment_line = -10
|
|
93
|
+
|
|
94
|
+
for idx, line in enumerate(lines, 1):
|
|
95
|
+
stripped = line.strip()
|
|
96
|
+
|
|
97
|
+
# Check for HTML comment classification tag immediately preceding code block
|
|
98
|
+
comment_match = re.search(
|
|
99
|
+
r"<!--\s*classification:\s*(runnable|pseudocode|illustrative)\s*-->",
|
|
100
|
+
stripped,
|
|
101
|
+
re.IGNORECASE,
|
|
102
|
+
)
|
|
103
|
+
if comment_match:
|
|
104
|
+
preceding_comment_classification = comment_match.group(1).lower()
|
|
105
|
+
preceding_comment_line = idx
|
|
106
|
+
continue
|
|
107
|
+
|
|
108
|
+
if stripped.startswith("```"):
|
|
109
|
+
if not in_block:
|
|
110
|
+
# Starting a code block
|
|
111
|
+
in_block = True
|
|
112
|
+
current_lang = stripped[3:].strip()
|
|
113
|
+
current_lines = []
|
|
114
|
+
block_start_line = idx
|
|
115
|
+
else:
|
|
116
|
+
# Ending a code block
|
|
117
|
+
in_block = False
|
|
118
|
+
code_text = "\n".join(current_lines)
|
|
119
|
+
|
|
120
|
+
# Determine classification
|
|
121
|
+
classification = "unclassified"
|
|
122
|
+
# 1. Check preceding HTML comment if it was within 2 lines
|
|
123
|
+
if preceding_comment_classification and (block_start_line - preceding_comment_line <= 2):
|
|
124
|
+
classification = preceding_comment_classification
|
|
125
|
+
|
|
126
|
+
# 2. Check if first few lines inside code block specify classification
|
|
127
|
+
if classification == "unclassified":
|
|
128
|
+
for c_line in current_lines[:3]:
|
|
129
|
+
inline_match = re.search(
|
|
130
|
+
r"(?:#|//|--|<!--)\s*classification:\s*(runnable|pseudocode|illustrative)",
|
|
131
|
+
c_line,
|
|
132
|
+
re.IGNORECASE,
|
|
133
|
+
)
|
|
134
|
+
if inline_match:
|
|
135
|
+
classification = inline_match.group(1).lower()
|
|
136
|
+
break
|
|
137
|
+
|
|
138
|
+
# 3. Check runnable metadata
|
|
139
|
+
has_prereq = bool(
|
|
140
|
+
re.search(r"(?i)(?:#|//|--)\s*(?:prerequisites?|requirements?):", code_text)
|
|
141
|
+
)
|
|
142
|
+
has_data = bool(
|
|
143
|
+
re.search(
|
|
144
|
+
r"(?i)(?:#|//|--)\s*(?:test\s*data|sample\s*payload|seed\s*data|sample\s*data):",
|
|
145
|
+
code_text,
|
|
146
|
+
)
|
|
147
|
+
)
|
|
148
|
+
has_output = bool(
|
|
149
|
+
re.search(
|
|
150
|
+
r"(?i)(?:#|//|--)\s*(?:expected\s*output|expected\s*result|expected\s*response):",
|
|
151
|
+
code_text,
|
|
152
|
+
)
|
|
153
|
+
)
|
|
154
|
+
|
|
155
|
+
blocks.append(
|
|
156
|
+
CodeBlockInfo(
|
|
157
|
+
language=current_lang,
|
|
158
|
+
classification=classification,
|
|
159
|
+
code=code_text,
|
|
160
|
+
start_line=block_start_line,
|
|
161
|
+
has_prerequisites=has_prereq,
|
|
162
|
+
has_test_data=has_data,
|
|
163
|
+
has_expected_output=has_output,
|
|
164
|
+
)
|
|
165
|
+
)
|
|
166
|
+
|
|
167
|
+
# Reset preceding comment tracking
|
|
168
|
+
preceding_comment_classification = None
|
|
169
|
+
preceding_comment_line = -10
|
|
170
|
+
elif in_block:
|
|
171
|
+
current_lines.append(line)
|
|
172
|
+
else:
|
|
173
|
+
# If line is non-empty and not a comment, invalidate distant preceding comment
|
|
174
|
+
if stripped and not comment_match:
|
|
175
|
+
if idx - preceding_comment_line > 2:
|
|
176
|
+
preceding_comment_classification = None
|
|
177
|
+
|
|
178
|
+
return blocks
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
def parse_yaml_frontmatter(content: str) -> Tuple[Optional[Dict[str, Any]], str, List[str]]:
|
|
182
|
+
"""
|
|
183
|
+
Extracts and parses YAML frontmatter without external pyyaml dependency.
|
|
184
|
+
Falls back to yaml.safe_load if pyyaml is installed.
|
|
185
|
+
"""
|
|
186
|
+
errors: List[str] = []
|
|
187
|
+
if not content.startswith("---"):
|
|
188
|
+
return None, "", ["File does not start with '---' delimiter on line 1"]
|
|
189
|
+
|
|
190
|
+
match = re.match(r"^---\s*\n(.*?)\n---\s*\n(.*)$", content, re.DOTALL)
|
|
191
|
+
if not match:
|
|
192
|
+
return None, "", ["Frontmatter missing closing '---' delimiter"]
|
|
193
|
+
|
|
194
|
+
fm_text = match.group(1)
|
|
195
|
+
body = match.group(2)
|
|
196
|
+
|
|
197
|
+
# If PyYAML is available, use it directly
|
|
198
|
+
if importlib.util.find_spec("yaml") is not None:
|
|
199
|
+
import yaml
|
|
200
|
+
try:
|
|
201
|
+
data = yaml.safe_load(fm_text)
|
|
202
|
+
if isinstance(data, dict):
|
|
203
|
+
return data, body, []
|
|
204
|
+
errors.append("PyYAML failed to parse frontmatter as a dictionary")
|
|
205
|
+
return None, "", errors
|
|
206
|
+
except yaml.YAMLError as y_err:
|
|
207
|
+
errors.append(f"PyYAML syntax error: {y_err}")
|
|
208
|
+
return None, "", errors
|
|
209
|
+
|
|
210
|
+
# Pure Python stdlib parser for frontmatter
|
|
211
|
+
data: Dict[str, Any] = {}
|
|
212
|
+
current_section: Optional[str] = None
|
|
213
|
+
|
|
214
|
+
for line_no, raw_line in enumerate(fm_text.splitlines(), 1):
|
|
215
|
+
line = raw_line.rstrip()
|
|
216
|
+
if not line or line.strip().startswith("#"):
|
|
217
|
+
continue
|
|
218
|
+
|
|
219
|
+
indent = len(line) - len(line.lstrip())
|
|
220
|
+
stripped = line.strip()
|
|
221
|
+
|
|
222
|
+
if indent == 0:
|
|
223
|
+
if ":" not in stripped:
|
|
224
|
+
errors.append(f"Line {line_no}: Invalid YAML key-value syntax: '{stripped}'")
|
|
225
|
+
continue
|
|
226
|
+
key, val = stripped.split(":", 1)
|
|
227
|
+
key, val = key.strip(), val.strip()
|
|
228
|
+
if not val:
|
|
229
|
+
current_section = key
|
|
230
|
+
data[current_section] = {}
|
|
231
|
+
else:
|
|
232
|
+
current_section = None
|
|
233
|
+
data[key] = val.strip("\"'")
|
|
234
|
+
elif indent >= 2 and current_section:
|
|
235
|
+
if ":" not in stripped:
|
|
236
|
+
errors.append(f"Line {line_no}: Invalid child YAML syntax in '{current_section}': '{stripped}'")
|
|
237
|
+
continue
|
|
238
|
+
ckey, cval = stripped.split(":", 1)
|
|
239
|
+
ckey, cval = ckey.strip(), cval.strip().strip("\"'")
|
|
240
|
+
if isinstance(data.get(current_section), dict):
|
|
241
|
+
data[current_section][ckey] = cval
|
|
242
|
+
|
|
243
|
+
return data, body, errors
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
def validate_upstream_schema(skill_data: Dict[str, Any], file_content: Optional[str] = None) -> Tuple[bool, List[str]]:
|
|
247
|
+
"""
|
|
248
|
+
Layer 1: Upstream Schema Conformance (Agent Skills Specification v1.0).
|
|
249
|
+
Validates name, description, and markdown AST heading structure.
|
|
250
|
+
"""
|
|
251
|
+
errors: List[str] = []
|
|
252
|
+
|
|
253
|
+
# 1. Name check
|
|
254
|
+
name = skill_data.get("name")
|
|
255
|
+
if not name or not str(name).strip():
|
|
256
|
+
errors.append("Missing required field: 'name'")
|
|
257
|
+
else:
|
|
258
|
+
name_str = str(name).strip()
|
|
259
|
+
if len(name_str) > 64:
|
|
260
|
+
errors.append(f"Field 'name' length ({len(name_str)}) exceeds 64 characters")
|
|
261
|
+
if not SKILL_NAME_REGEX.match(name_str):
|
|
262
|
+
errors.append(f"Invalid 'name' format: '{name_str}' (must be lowercase alphanumeric + hyphens)")
|
|
263
|
+
|
|
264
|
+
# 2. Description check
|
|
265
|
+
desc = skill_data.get("description")
|
|
266
|
+
if not desc or not str(desc).strip():
|
|
267
|
+
errors.append("Missing required field: 'description'")
|
|
268
|
+
else:
|
|
269
|
+
desc_str = str(desc).strip()
|
|
270
|
+
if len(desc_str) > 1024:
|
|
271
|
+
errors.append(f"Description length ({len(desc_str)}) exceeds 1024 characters")
|
|
272
|
+
if "use when" not in desc_str.lower():
|
|
273
|
+
errors.append("Description missing mandatory activation trigger clause ('Use when...')")
|
|
274
|
+
|
|
275
|
+
# 3. Heading check if content provided
|
|
276
|
+
if file_content is not None:
|
|
277
|
+
if not re.search(r"^##?\s+", file_content, re.MULTILINE):
|
|
278
|
+
errors.append("Body missing standard markdown section headings ('## ...')")
|
|
279
|
+
|
|
280
|
+
return (len(errors) == 0, errors)
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
def find_repo_root(start_path: Path) -> Path:
|
|
284
|
+
"""Finds repository root by searching for .git, pyproject.toml, or tools directory."""
|
|
285
|
+
current = start_path.resolve()
|
|
286
|
+
for parent in [current] + list(current.parents):
|
|
287
|
+
if (parent / ".git").exists() or (parent / "pyproject.toml").exists() or (parent / "tools").exists():
|
|
288
|
+
return parent
|
|
289
|
+
return current.parents[3] if len(current.parents) >= 4 else current
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
def validate_synapse_policy_extensions(
|
|
293
|
+
skill_data: Dict[str, Any],
|
|
294
|
+
file_content: str,
|
|
295
|
+
file_path: str,
|
|
296
|
+
check_links: bool = True,
|
|
297
|
+
) -> Tuple[bool, List[str]]:
|
|
298
|
+
"""
|
|
299
|
+
Layer 2: Synapse Policy Extensions.
|
|
300
|
+
Validates category, version, policies, examples/ directory, 5 required sections,
|
|
301
|
+
code block classification, GitHub Actions SHA pinning, unproven claims heuristic,
|
|
302
|
+
and link & backtick reference resolution.
|
|
303
|
+
"""
|
|
304
|
+
errors: List[str] = []
|
|
305
|
+
skill_file = Path(file_path).resolve()
|
|
306
|
+
skill_dir = skill_file.parent
|
|
307
|
+
repo_root = find_repo_root(skill_dir)
|
|
308
|
+
|
|
309
|
+
# 1. Category check
|
|
310
|
+
category = skill_data.get("category")
|
|
311
|
+
if not category:
|
|
312
|
+
errors.append("Missing required field: 'category'")
|
|
313
|
+
elif category not in ALLOWED_CATEGORIES:
|
|
314
|
+
errors.append(f"Invalid category '{category}'. Must be one of: {sorted(ALLOWED_CATEGORIES)}")
|
|
315
|
+
|
|
316
|
+
# 2. Version check
|
|
317
|
+
version = skill_data.get("version")
|
|
318
|
+
if not version:
|
|
319
|
+
errors.append("Missing required field: 'version'")
|
|
320
|
+
elif not SEMVER_REGEX.match(str(version).strip("\"'")):
|
|
321
|
+
errors.append(f"Invalid version format '{version}'. Must conform to SemVer (e.g. '1.0.0')")
|
|
322
|
+
|
|
323
|
+
# 3. Policies check
|
|
324
|
+
policies = skill_data.get("policies")
|
|
325
|
+
if policies is None:
|
|
326
|
+
errors.append("Missing required field: 'policies'")
|
|
327
|
+
elif not isinstance(policies, dict):
|
|
328
|
+
errors.append(f"'policies' must be a dictionary object, got {type(policies).__name__}")
|
|
329
|
+
else:
|
|
330
|
+
for pol_key, allowed_vals in ALLOWED_POLICIES.items():
|
|
331
|
+
val = policies.get(pol_key)
|
|
332
|
+
if not val:
|
|
333
|
+
errors.append(f"Missing required policy: 'policies.{pol_key}'")
|
|
334
|
+
elif val not in allowed_vals:
|
|
335
|
+
errors.append(f"Invalid value '{val}' for 'policies.{pol_key}'. Must be one of: {sorted(allowed_vals)}")
|
|
336
|
+
|
|
337
|
+
# 4. Mandatory examples/ directory check
|
|
338
|
+
examples_dir = skill_dir / "examples"
|
|
339
|
+
if not examples_dir.is_dir():
|
|
340
|
+
errors.append("Missing mandatory 'examples/' directory (Progressive Disclosure L3)")
|
|
341
|
+
elif not list(examples_dir.iterdir()):
|
|
342
|
+
errors.append("'examples/' directory is empty")
|
|
343
|
+
|
|
344
|
+
for l2_name in ("references", "resources"):
|
|
345
|
+
l2_dir = skill_dir / l2_name
|
|
346
|
+
if l2_dir.is_dir() and not list(l2_dir.iterdir()):
|
|
347
|
+
errors.append(f"Progressive disclosure directory '{l2_name}/' exists but is empty")
|
|
348
|
+
|
|
349
|
+
# 5. Standard 5 Required Sections Check
|
|
350
|
+
for sec_num, pattern, sec_title in REQUIRED_SECTION_PATTERNS:
|
|
351
|
+
if not pattern.search(file_content):
|
|
352
|
+
errors.append(f"Missing required section: '## {sec_title}'")
|
|
353
|
+
|
|
354
|
+
# 6. Code Block Classification and Language Tag Audit
|
|
355
|
+
blocks = classify_code_blocks(file_content)
|
|
356
|
+
for b in blocks:
|
|
357
|
+
# Ignore mermaid diagrams for code language tag enforcement
|
|
358
|
+
if not b.language.strip():
|
|
359
|
+
errors.append(f"Line {b.start_line}: Code block missing language identifier tag (bare ```)")
|
|
360
|
+
elif b.language.lower() != "mermaid":
|
|
361
|
+
if b.classification not in ("runnable", "pseudocode", "illustrative"):
|
|
362
|
+
errors.append(
|
|
363
|
+
f"Line {b.start_line}: Code block not classified. Must be tagged with "
|
|
364
|
+
"<!-- classification: runnable -->, <!-- classification: pseudocode -->, "
|
|
365
|
+
"or <!-- classification: illustrative -->"
|
|
366
|
+
)
|
|
367
|
+
elif b.classification == "runnable":
|
|
368
|
+
missing_meta = []
|
|
369
|
+
if not b.has_prerequisites:
|
|
370
|
+
missing_meta.append("# Prerequisites:")
|
|
371
|
+
if not b.has_test_data:
|
|
372
|
+
missing_meta.append("# Test Data:")
|
|
373
|
+
if not b.has_expected_output:
|
|
374
|
+
missing_meta.append("# Expected Output:")
|
|
375
|
+
if missing_meta:
|
|
376
|
+
errors.append(
|
|
377
|
+
f"Line {b.start_line}: Runnable code block missing required execution metadata: "
|
|
378
|
+
+ ", ".join(missing_meta)
|
|
379
|
+
)
|
|
380
|
+
|
|
381
|
+
# 7. GitHub Actions Commit SHA Pinning Check
|
|
382
|
+
for match in GITHUB_ACTION_REGEX.finditer(file_content):
|
|
383
|
+
action_name = match.group(1)
|
|
384
|
+
ref = match.group(2)
|
|
385
|
+
if not COMMIT_SHA_40_REGEX.match(ref):
|
|
386
|
+
errors.append(
|
|
387
|
+
f"Unpinned GitHub Action detected: 'actions/{action_name}@{ref}'. "
|
|
388
|
+
"Must be pinned to immutable 40-character commit SHA with version tag comment"
|
|
389
|
+
)
|
|
390
|
+
|
|
391
|
+
# 8. Unproven Quantitative Claims Check
|
|
392
|
+
for pat in UNPROVEN_CLAIMS_PATTERNS:
|
|
393
|
+
claim_match = pat.search(file_content)
|
|
394
|
+
if claim_match:
|
|
395
|
+
errors.append(
|
|
396
|
+
f"Unproven quantitative/superlative claim detected: '{claim_match.group(0)}'. "
|
|
397
|
+
"Must be replaced with contextual engineering heuristic"
|
|
398
|
+
)
|
|
399
|
+
|
|
400
|
+
# 9. Link and Backtick Reference Resolution
|
|
401
|
+
if check_links:
|
|
402
|
+
# Markdown links
|
|
403
|
+
for match in MD_LINK_REGEX.finditer(file_content):
|
|
404
|
+
target = match.group(2).strip()
|
|
405
|
+
if target.startswith(("http://", "https://", "mailto:", "#")):
|
|
406
|
+
continue
|
|
407
|
+
# Check depth-4 excessive parent traversal link
|
|
408
|
+
if "../../../../" in target:
|
|
409
|
+
errors.append(
|
|
410
|
+
f"Excessive root-escaping parent traversal in relative link: '{target}'. "
|
|
411
|
+
"Use direct or intra-skill relative references"
|
|
412
|
+
)
|
|
413
|
+
continue
|
|
414
|
+
clean_target = target.split("#")[0].split("?")[0].strip()
|
|
415
|
+
if not clean_target:
|
|
416
|
+
continue
|
|
417
|
+
resolved = (skill_dir / clean_target).resolve()
|
|
418
|
+
if not resolved.exists():
|
|
419
|
+
errors.append(f"Broken relative link: '{target}' (resolved to non-existent path: {resolved})")
|
|
420
|
+
|
|
421
|
+
# Backtick references: check paths matching repository or skill files
|
|
422
|
+
for match in BACKTICK_PATH_REGEX.finditer(file_content):
|
|
423
|
+
ref_path = match.group(1).strip()
|
|
424
|
+
# Skip generated output directories and target project artifacts
|
|
425
|
+
if any(ref_path.startswith(prefix) for prefix in ("graphify-out/", "reports/", "Reports/", "Keywords/", "build/", "dist/", "Screenshots/", ".sandbox")):
|
|
426
|
+
continue
|
|
427
|
+
# Only validate references that target files in known source/config directories
|
|
428
|
+
if any(ref_path.startswith(prefix) for prefix in (".github/", "templates/")):
|
|
429
|
+
# Check against repo root
|
|
430
|
+
resolved_repo_file = (repo_root / ref_path).resolve()
|
|
431
|
+
if not resolved_repo_file.exists():
|
|
432
|
+
errors.append(
|
|
433
|
+
f"Broken internal file reference in backticks: '`{ref_path}`' "
|
|
434
|
+
f"(resolved to non-existent path: {resolved_repo_file})"
|
|
435
|
+
)
|
|
436
|
+
|
|
437
|
+
return (len(errors) == 0, errors)
|
|
438
|
+
|
|
439
|
+
|
|
440
|
+
def validate_skill(
|
|
441
|
+
skill_md_path: Path,
|
|
442
|
+
check_links: bool = True,
|
|
443
|
+
layer: str = "all",
|
|
444
|
+
) -> List[str]:
|
|
445
|
+
"""Validates a single SKILL.md file against the specification and selected layer."""
|
|
446
|
+
errors: List[str] = []
|
|
447
|
+
try:
|
|
448
|
+
content = skill_md_path.read_text(encoding="utf-8")
|
|
449
|
+
except Exception as e:
|
|
450
|
+
return [f"Cannot read file: {e}"]
|
|
451
|
+
|
|
452
|
+
fm, body, parse_errors = parse_yaml_frontmatter(content)
|
|
453
|
+
if parse_errors:
|
|
454
|
+
return parse_errors
|
|
455
|
+
if fm is None:
|
|
456
|
+
return ["Failed to parse frontmatter"]
|
|
457
|
+
|
|
458
|
+
expected_name = skill_md_path.parent.name
|
|
459
|
+
actual_name = fm.get("name")
|
|
460
|
+
|
|
461
|
+
# Layer 1: Upstream Schema Conformance
|
|
462
|
+
if layer in ("upstream", "all"):
|
|
463
|
+
if actual_name and actual_name != expected_name:
|
|
464
|
+
errors.append(f"Field 'name' ('{actual_name}') does not match directory name ('{expected_name}')")
|
|
465
|
+
ok_up, up_errs = validate_upstream_schema(fm, file_content=body)
|
|
466
|
+
errors.extend(up_errs)
|
|
467
|
+
|
|
468
|
+
# Layer 2: Synapse Policy Extensions
|
|
469
|
+
if layer in ("policy", "all"):
|
|
470
|
+
ok_pol, pol_errs = validate_synapse_policy_extensions(
|
|
471
|
+
skill_data=fm,
|
|
472
|
+
file_content=content,
|
|
473
|
+
file_path=str(skill_md_path),
|
|
474
|
+
check_links=check_links,
|
|
475
|
+
)
|
|
476
|
+
errors.extend(pol_errs)
|
|
477
|
+
|
|
478
|
+
return errors
|
|
479
|
+
|
|
480
|
+
|
|
481
|
+
def run_validation(
|
|
482
|
+
skills_dir: Path,
|
|
483
|
+
check_links: bool = True,
|
|
484
|
+
layer: str = "all",
|
|
485
|
+
) -> Tuple[int, Dict[str, List[str]]]:
|
|
486
|
+
"""Scans all skills under skills_dir and validates each SKILL.md for the given layer."""
|
|
487
|
+
results: Dict[str, List[str]] = {}
|
|
488
|
+
skill_files = sorted(skills_dir.glob("*/*/SKILL.md"))
|
|
489
|
+
for sf in skill_files:
|
|
490
|
+
rel_path = sf.as_posix()
|
|
491
|
+
errs = validate_skill(sf, check_links=check_links, layer=layer)
|
|
492
|
+
if errs:
|
|
493
|
+
results[rel_path] = errs
|
|
494
|
+
return len(skill_files), results
|
|
495
|
+
|
|
496
|
+
|
|
497
|
+
def main() -> int:
|
|
498
|
+
parser = argparse.ArgumentParser(
|
|
499
|
+
description="Validate Agent Skills frontmatter schema and Synapse policies across layers."
|
|
500
|
+
)
|
|
501
|
+
parser.add_argument(
|
|
502
|
+
"--skills-dir",
|
|
503
|
+
type=str,
|
|
504
|
+
default=".agents/skills",
|
|
505
|
+
help="Path to the .agents/skills directory (default: .agents/skills)",
|
|
506
|
+
)
|
|
507
|
+
parser.add_argument(
|
|
508
|
+
"--layer",
|
|
509
|
+
choices=["upstream", "policy", "all"],
|
|
510
|
+
default="all",
|
|
511
|
+
help="Validation layer to execute: 'upstream' (Agent Skills v1.0 schema), 'policy' (Synapse extensions), or 'all' (default: all)",
|
|
512
|
+
)
|
|
513
|
+
parser.add_argument(
|
|
514
|
+
"--check-links",
|
|
515
|
+
action="store_true",
|
|
516
|
+
default=True,
|
|
517
|
+
help="Verify existence of relative markdown resource links and backtick paths (default: True)",
|
|
518
|
+
)
|
|
519
|
+
parser.add_argument(
|
|
520
|
+
"--no-check-links",
|
|
521
|
+
action="store_false",
|
|
522
|
+
dest="check_links",
|
|
523
|
+
help="Disable relative markdown resource link checking",
|
|
524
|
+
)
|
|
525
|
+
parser.add_argument(
|
|
526
|
+
"--json",
|
|
527
|
+
action="store_true",
|
|
528
|
+
default=False,
|
|
529
|
+
help="Output results in JSON format",
|
|
530
|
+
)
|
|
531
|
+
|
|
532
|
+
args = parser.parse_args()
|
|
533
|
+
skills_path = Path(args.skills_dir).resolve()
|
|
534
|
+
|
|
535
|
+
if not skills_path.exists():
|
|
536
|
+
print(f"Error: Skills directory not found at {skills_path}", file=sys.stderr)
|
|
537
|
+
return 1
|
|
538
|
+
|
|
539
|
+
total_scanned, failures = run_validation(
|
|
540
|
+
skills_path,
|
|
541
|
+
check_links=args.check_links,
|
|
542
|
+
layer=args.layer,
|
|
543
|
+
)
|
|
544
|
+
|
|
545
|
+
if args.json:
|
|
546
|
+
output_payload = {
|
|
547
|
+
"total_skills": total_scanned,
|
|
548
|
+
"layer": args.layer,
|
|
549
|
+
"valid_skills": total_scanned - len(failures),
|
|
550
|
+
"failed_skills": len(failures),
|
|
551
|
+
"passed": len(failures) == 0,
|
|
552
|
+
"failures": failures,
|
|
553
|
+
}
|
|
554
|
+
print(json.dumps(output_payload, indent=2))
|
|
555
|
+
return 0 if len(failures) == 0 else 1
|
|
556
|
+
|
|
557
|
+
print(f"\nš Validating {total_scanned} skills in {skills_path} [Layer: {args.layer}]...")
|
|
558
|
+
if args.check_links and args.layer in ("policy", "all"):
|
|
559
|
+
print("š Checking relative markdown links and backtick references...")
|
|
560
|
+
|
|
561
|
+
if not failures:
|
|
562
|
+
print(f"ā
100% Verified: All {total_scanned} skills conform to layer '{args.layer}'.")
|
|
563
|
+
return 0
|
|
564
|
+
|
|
565
|
+
print(f"ā Validation failed: {len(failures)}/{total_scanned} skills have errors in layer '{args.layer}':\n")
|
|
566
|
+
for file_path, err_list in failures.items():
|
|
567
|
+
print(f" ⢠{file_path}:")
|
|
568
|
+
for err in err_list:
|
|
569
|
+
print(f" - {err}")
|
|
570
|
+
print()
|
|
571
|
+
return 1
|
|
572
|
+
|
|
573
|
+
|
|
574
|
+
if __name__ == "__main__":
|
|
575
|
+
sys.exit(main())
|