@teevee98/synapse-hub 4.2.0 ā 4.2.2
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/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +46 -2
- package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +49 -4
- package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +56 -66
- package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +48 -3
- package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +56 -11
- package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +49 -7
- package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +54 -11
- package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +48 -90
- package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +53 -10
- package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +44 -3
- package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +49 -8
- package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +49 -8
- package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +49 -7
- package/.agents/skills/02-test-design/review-spec/SKILL.md +46 -5
- package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +44 -3
- package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +50 -4
- package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +47 -6
- package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +79 -34
- package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +47 -4
- package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +46 -5
- package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +44 -2
- package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +57 -13
- package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +45 -4
- package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +48 -3
- package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +45 -4
- package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +47 -5
- package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +48 -7
- package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +54 -23
- package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +46 -5
- package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +50 -9
- package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +52 -11
- package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +52 -11
- package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +47 -4
- package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +50 -4
- package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +47 -3
- package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +52 -4
- package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +51 -10
- package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +78 -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 +49 -9
- package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +45 -5
- package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +48 -6
- package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +49 -9
- package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +47 -4
- package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +48 -16
- 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 +44 -3
- package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +47 -6
- package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +44 -3
- package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +52 -12
- package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +45 -4
- package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +51 -9
- package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +44 -3
- package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +44 -3
- package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +49 -8
- package/.cursor/rules/synapse-qa.mdc +20 -7
- package/.cursorrules +19 -5
- package/.windsurfrules +18 -3
- package/AGENTS.md +51 -65
- package/CLAUDE.md +38 -24
- package/README.en.md +2 -2
- package/README.md +2 -2
- package/agentskills.json +1 -1
- package/docs/ARCHITECTURE.en.md +1 -1
- package/docs/ARCHITECTURE.md +1 -1
- package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
- package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
- package/package.json +1 -1
- package/plugin.json +1 -1
- package/skills_manifest.json +1 -1
- 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/tools/TOOLS_RUNBOOK.md +1 -1
- package/tools/__init__.py +1 -1
- package/tools/api_fuzzer.py +295 -41
- package/tools/benchmark_swarm_context.py +11 -4
- package/tools/browser_helpers.js +2 -2
- package/tools/bump_version.py +2 -2
- package/tools/cli.py +4 -4
- package/tools/core/bm25_retriever.py +1 -1
- package/tools/core/i18n.py +1 -1
- package/tools/core/provider_usage_adapter.py +66 -0
- package/tools/core/token_estimator.py +39 -1
- package/tools/count_tokens.py +2 -2
- package/tools/dashboard_generator.py +8 -8
- package/tools/db_sandbox.py +182 -43
- package/tools/distill_log.py +1 -1
- package/tools/distill_skill.py +17 -2
- package/tools/git_pre_commit_guard.py +190 -1
- package/tools/hub_publisher.py +2 -12
- package/tools/mcp_docx_server.py +1 -1
- package/tools/mcp_excel_server.py +1 -1
- package/tools/mcp_server.py +33 -5
- package/tools/micro_mutator.py +30 -1
- package/tools/pentest_scope_guard.py +288 -15
- package/tools/project_state.py +29 -5
- package/tools/reversible_sandbox.py +58 -13
- package/tools/rules_router.py +80 -27
- package/tools/skill_canonical_digest.py +60 -2
- package/tools/sync_agent_rules.py +187 -61
- package/tools/task_memory_manager.py +16 -1
- package/tools/ui_server.py +3 -1
- package/tools/update_sentinel.py +3 -3
- package/tools/validate_skills_schema.py +349 -56
- package/tools/verify_all.py +98 -4
- package/tools/welcome_page.py +1 -1
|
@@ -22,6 +22,7 @@ import hashlib
|
|
|
22
22
|
import json
|
|
23
23
|
import os
|
|
24
24
|
import sys
|
|
25
|
+
import time
|
|
25
26
|
from typing import Any, Dict, Optional, Tuple
|
|
26
27
|
|
|
27
28
|
DEFAULT_MEMORY_DIR = ".task_memory"
|
|
@@ -66,7 +67,21 @@ class TaskMemoryManager:
|
|
|
66
67
|
actual_tmp = f"{tmp_path}.{os.getpid()}_{id(checksums)}"
|
|
67
68
|
with open(actual_tmp, "w", encoding="utf-8") as f:
|
|
68
69
|
json.dump(checksums, f, indent=2, ensure_ascii=False)
|
|
69
|
-
|
|
70
|
+
for attempt in range(10):
|
|
71
|
+
try:
|
|
72
|
+
os.replace(actual_tmp, self.checksums_path)
|
|
73
|
+
return
|
|
74
|
+
except OSError:
|
|
75
|
+
if attempt == 9:
|
|
76
|
+
try:
|
|
77
|
+
with open(self.checksums_path, "w", encoding="utf-8") as f:
|
|
78
|
+
json.dump(checksums, f, indent=2, ensure_ascii=False)
|
|
79
|
+
if os.path.exists(actual_tmp):
|
|
80
|
+
os.remove(actual_tmp)
|
|
81
|
+
return
|
|
82
|
+
except OSError:
|
|
83
|
+
return
|
|
84
|
+
time.sleep(0.02 * (attempt + 1))
|
|
70
85
|
|
|
71
86
|
def _update_file_checksum(self, filename: str, content: str) -> None:
|
|
72
87
|
checksums = self._read_checksums()
|
package/tools/ui_server.py
CHANGED
|
@@ -202,8 +202,10 @@ class SynapseUiHandler(BaseHTTPRequestHandler):
|
|
|
202
202
|
self.send_header("Vary", "Origin")
|
|
203
203
|
self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
|
|
204
204
|
self.send_header("Access-Control-Allow-Headers", "Content-Type, Authorization")
|
|
205
|
+
self.send_header("Connection", "close")
|
|
205
206
|
self.end_headers()
|
|
206
207
|
self.wfile.write(body)
|
|
208
|
+
self.close_connection = True
|
|
207
209
|
|
|
208
210
|
def do_OPTIONS(self):
|
|
209
211
|
self.send_response(200)
|
|
@@ -236,7 +238,7 @@ class SynapseUiHandler(BaseHTTPRequestHandler):
|
|
|
236
238
|
if path == "/api/status":
|
|
237
239
|
active_target = JOB_MANAGER.target_dir or REPO_ROOT
|
|
238
240
|
self.send_json(200, {
|
|
239
|
-
"version": "4.2.
|
|
241
|
+
"version": "4.2.2",
|
|
240
242
|
"status": "ONLINE",
|
|
241
243
|
"os": sys.platform,
|
|
242
244
|
"workspace": active_target,
|
package/tools/update_sentinel.py
CHANGED
|
@@ -68,7 +68,7 @@ def get_local_version():
|
|
|
68
68
|
try:
|
|
69
69
|
with open(pkg_file, "r", encoding="utf-8") as f:
|
|
70
70
|
data = json.load(f)
|
|
71
|
-
return data.get("version", "4.2.
|
|
71
|
+
return data.get("version", "4.2.2")
|
|
72
72
|
except (OSError, json.JSONDecodeError):
|
|
73
73
|
data = {}
|
|
74
74
|
|
|
@@ -77,11 +77,11 @@ def get_local_version():
|
|
|
77
77
|
try:
|
|
78
78
|
with open(manifest_file, "r", encoding="utf-8") as f:
|
|
79
79
|
data = json.load(f)
|
|
80
|
-
return data.get("version", "4.2.
|
|
80
|
+
return data.get("version", "4.2.2")
|
|
81
81
|
except (OSError, json.JSONDecodeError):
|
|
82
82
|
data = {}
|
|
83
83
|
|
|
84
|
-
return "4.2.
|
|
84
|
+
return "4.2.2"
|
|
85
85
|
|
|
86
86
|
|
|
87
87
|
def fetch_remote_version():
|
|
@@ -5,7 +5,9 @@
|
|
|
5
5
|
|
|
6
6
|
"""
|
|
7
7
|
tools/validate_skills_schema.py ā Standalone Skill Schema & Policy Validator
|
|
8
|
-
Validates all skills against
|
|
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)
|
|
9
11
|
"""
|
|
10
12
|
|
|
11
13
|
import sys
|
|
@@ -13,6 +15,7 @@ import re
|
|
|
13
15
|
import json
|
|
14
16
|
import argparse
|
|
15
17
|
import importlib.util
|
|
18
|
+
from dataclasses import dataclass
|
|
16
19
|
from pathlib import Path
|
|
17
20
|
from typing import Dict, Any, List, Tuple, Optional
|
|
18
21
|
|
|
@@ -38,6 +41,141 @@ ALLOWED_POLICIES = {
|
|
|
38
41
|
SEMVER_REGEX = re.compile(r"^\d+\.\d+\.\d+$")
|
|
39
42
|
SKILL_NAME_REGEX = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
|
|
40
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
|
|
41
179
|
|
|
42
180
|
|
|
43
181
|
def parse_yaml_frontmatter(content: str) -> Tuple[Optional[Dict[str, Any]], str, List[str]]:
|
|
@@ -105,33 +243,26 @@ def parse_yaml_frontmatter(content: str) -> Tuple[Optional[Dict[str, Any]], str,
|
|
|
105
243
|
return data, body, errors
|
|
106
244
|
|
|
107
245
|
|
|
108
|
-
def
|
|
109
|
-
"""
|
|
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
|
+
"""
|
|
110
251
|
errors: List[str] = []
|
|
111
|
-
try:
|
|
112
|
-
content = skill_md_path.read_text(encoding="utf-8")
|
|
113
|
-
except Exception as e:
|
|
114
|
-
return [f"Cannot read file: {e}"]
|
|
115
|
-
|
|
116
|
-
fm, body, parse_errors = parse_yaml_frontmatter(content)
|
|
117
|
-
if parse_errors:
|
|
118
|
-
return parse_errors
|
|
119
|
-
if fm is None:
|
|
120
|
-
return ["Failed to parse frontmatter"]
|
|
121
|
-
|
|
122
|
-
expected_name = skill_md_path.parent.name
|
|
123
|
-
actual_name = fm.get("name")
|
|
124
252
|
|
|
125
253
|
# 1. Name check
|
|
126
|
-
|
|
254
|
+
name = skill_data.get("name")
|
|
255
|
+
if not name or not str(name).strip():
|
|
127
256
|
errors.append("Missing required field: 'name'")
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
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)")
|
|
132
263
|
|
|
133
264
|
# 2. Description check
|
|
134
|
-
desc =
|
|
265
|
+
desc = skill_data.get("description")
|
|
135
266
|
if not desc or not str(desc).strip():
|
|
136
267
|
errors.append("Missing required field: 'description'")
|
|
137
268
|
else:
|
|
@@ -141,22 +272,56 @@ def validate_skill(skill_md_path: Path, check_links: bool = True) -> List[str]:
|
|
|
141
272
|
if "use when" not in desc_str.lower():
|
|
142
273
|
errors.append("Description missing mandatory activation trigger clause ('Use when...')")
|
|
143
274
|
|
|
144
|
-
# 3.
|
|
145
|
-
|
|
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")
|
|
146
311
|
if not category:
|
|
147
312
|
errors.append("Missing required field: 'category'")
|
|
148
313
|
elif category not in ALLOWED_CATEGORIES:
|
|
149
314
|
errors.append(f"Invalid category '{category}'. Must be one of: {sorted(ALLOWED_CATEGORIES)}")
|
|
150
315
|
|
|
151
|
-
#
|
|
152
|
-
version =
|
|
316
|
+
# 2. Version check
|
|
317
|
+
version = skill_data.get("version")
|
|
153
318
|
if not version:
|
|
154
319
|
errors.append("Missing required field: 'version'")
|
|
155
320
|
elif not SEMVER_REGEX.match(str(version).strip("\"'")):
|
|
156
321
|
errors.append(f"Invalid version format '{version}'. Must conform to SemVer (e.g. '1.0.0')")
|
|
157
322
|
|
|
158
|
-
#
|
|
159
|
-
policies =
|
|
323
|
+
# 3. Policies check
|
|
324
|
+
policies = skill_data.get("policies")
|
|
160
325
|
if policies is None:
|
|
161
326
|
errors.append("Missing required field: 'policies'")
|
|
162
327
|
elif not isinstance(policies, dict):
|
|
@@ -169,64 +334,187 @@ def validate_skill(skill_md_path: Path, check_links: bool = True) -> List[str]:
|
|
|
169
334
|
elif val not in allowed_vals:
|
|
170
335
|
errors.append(f"Invalid value '{val}' for 'policies.{pol_key}'. Must be one of: {sorted(allowed_vals)}")
|
|
171
336
|
|
|
172
|
-
#
|
|
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
|
|
173
401
|
if check_links:
|
|
174
|
-
|
|
402
|
+
# Markdown links
|
|
403
|
+
for match in MD_LINK_REGEX.finditer(file_content):
|
|
175
404
|
target = match.group(2).strip()
|
|
176
405
|
if target.startswith(("http://", "https://", "mailto:", "#")):
|
|
177
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
|
|
178
414
|
clean_target = target.split("#")[0].split("?")[0].strip()
|
|
179
415
|
if not clean_target:
|
|
180
416
|
continue
|
|
181
|
-
resolved = (
|
|
417
|
+
resolved = (skill_dir / clean_target).resolve()
|
|
182
418
|
if not resolved.exists():
|
|
183
419
|
errors.append(f"Broken relative link: '{target}' (resolved to non-existent path: {resolved})")
|
|
184
420
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
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}"]
|
|
191
451
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
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"]
|
|
197
457
|
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
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)
|
|
201
477
|
|
|
202
478
|
return errors
|
|
203
479
|
|
|
204
480
|
|
|
205
|
-
def run_validation(
|
|
206
|
-
|
|
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."""
|
|
207
487
|
results: Dict[str, List[str]] = {}
|
|
208
488
|
skill_files = sorted(skills_dir.glob("*/*/SKILL.md"))
|
|
209
489
|
for sf in skill_files:
|
|
210
490
|
rel_path = sf.as_posix()
|
|
211
|
-
errs = validate_skill(sf, check_links=check_links)
|
|
491
|
+
errs = validate_skill(sf, check_links=check_links, layer=layer)
|
|
212
492
|
if errs:
|
|
213
493
|
results[rel_path] = errs
|
|
214
494
|
return len(skill_files), results
|
|
215
495
|
|
|
216
496
|
|
|
217
497
|
def main() -> int:
|
|
218
|
-
parser = argparse.ArgumentParser(
|
|
498
|
+
parser = argparse.ArgumentParser(
|
|
499
|
+
description="Validate Agent Skills frontmatter schema and Synapse policies across layers."
|
|
500
|
+
)
|
|
219
501
|
parser.add_argument(
|
|
220
502
|
"--skills-dir",
|
|
221
503
|
type=str,
|
|
222
504
|
default=".agents/skills",
|
|
223
505
|
help="Path to the .agents/skills directory (default: .agents/skills)",
|
|
224
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
|
+
)
|
|
225
513
|
parser.add_argument(
|
|
226
514
|
"--check-links",
|
|
227
515
|
action="store_true",
|
|
228
516
|
default=True,
|
|
229
|
-
help="Verify existence of relative markdown resource links (default: True)",
|
|
517
|
+
help="Verify existence of relative markdown resource links and backtick paths (default: True)",
|
|
230
518
|
)
|
|
231
519
|
parser.add_argument(
|
|
232
520
|
"--no-check-links",
|
|
@@ -248,11 +536,16 @@ def main() -> int:
|
|
|
248
536
|
print(f"Error: Skills directory not found at {skills_path}", file=sys.stderr)
|
|
249
537
|
return 1
|
|
250
538
|
|
|
251
|
-
total_scanned, failures = run_validation(
|
|
539
|
+
total_scanned, failures = run_validation(
|
|
540
|
+
skills_path,
|
|
541
|
+
check_links=args.check_links,
|
|
542
|
+
layer=args.layer,
|
|
543
|
+
)
|
|
252
544
|
|
|
253
545
|
if args.json:
|
|
254
546
|
output_payload = {
|
|
255
547
|
"total_skills": total_scanned,
|
|
548
|
+
"layer": args.layer,
|
|
256
549
|
"valid_skills": total_scanned - len(failures),
|
|
257
550
|
"failed_skills": len(failures),
|
|
258
551
|
"passed": len(failures) == 0,
|
|
@@ -261,15 +554,15 @@ def main() -> int:
|
|
|
261
554
|
print(json.dumps(output_payload, indent=2))
|
|
262
555
|
return 0 if len(failures) == 0 else 1
|
|
263
556
|
|
|
264
|
-
print(f"\nš Validating {total_scanned} skills in {skills_path}...")
|
|
265
|
-
if args.check_links:
|
|
266
|
-
print("š Checking relative markdown links...")
|
|
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...")
|
|
267
560
|
|
|
268
561
|
if not failures:
|
|
269
|
-
print(f"ā
100% Verified: All {total_scanned} skills conform to
|
|
562
|
+
print(f"ā
100% Verified: All {total_scanned} skills conform to layer '{args.layer}'.")
|
|
270
563
|
return 0
|
|
271
564
|
|
|
272
|
-
print(f"ā Validation failed: {len(failures)}/{total_scanned} skills have
|
|
565
|
+
print(f"ā Validation failed: {len(failures)}/{total_scanned} skills have errors in layer '{args.layer}':\n")
|
|
273
566
|
for file_path, err_list in failures.items():
|
|
274
567
|
print(f" ⢠{file_path}:")
|
|
275
568
|
for err in err_list:
|