@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.
Files changed (109) hide show
  1. package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +46 -2
  2. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +49 -4
  3. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +56 -66
  4. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +48 -3
  5. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +56 -11
  6. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +49 -7
  7. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +54 -11
  8. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +48 -90
  9. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +53 -10
  10. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +44 -3
  11. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +49 -8
  12. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +49 -8
  13. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +49 -7
  14. package/.agents/skills/02-test-design/review-spec/SKILL.md +46 -5
  15. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +44 -3
  16. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +50 -4
  17. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +47 -6
  18. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +79 -34
  19. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +47 -4
  20. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +46 -5
  21. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +44 -2
  22. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +57 -13
  23. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +45 -4
  24. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +48 -3
  25. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +45 -4
  26. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +47 -5
  27. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +48 -7
  28. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +54 -23
  29. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +46 -5
  30. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +50 -9
  31. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +52 -11
  32. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +52 -11
  33. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +47 -4
  34. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +50 -4
  35. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +47 -3
  36. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +52 -4
  37. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +51 -10
  38. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +78 -34
  39. package/.agents/skills/08-code-quality/graphify-impact-analyzer/examples/dependency_blast_radius.json +3 -4
  40. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +49 -9
  41. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +45 -5
  42. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +48 -6
  43. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +49 -9
  44. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +47 -4
  45. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +48 -16
  46. package/.agents/skills/09-ci-and-devops/github-actions-templates/examples/matrix_test_pipeline.yml +2 -1
  47. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +44 -3
  48. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +47 -6
  49. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +44 -3
  50. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +52 -12
  51. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +45 -4
  52. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +51 -9
  53. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +44 -3
  54. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +44 -3
  55. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +49 -8
  56. package/.cursor/rules/synapse-qa.mdc +20 -7
  57. package/.cursorrules +19 -5
  58. package/.windsurfrules +18 -3
  59. package/AGENTS.md +51 -65
  60. package/CLAUDE.md +38 -24
  61. package/README.en.md +2 -2
  62. package/README.md +2 -2
  63. package/agentskills.json +1 -1
  64. package/docs/ARCHITECTURE.en.md +1 -1
  65. package/docs/ARCHITECTURE.md +1 -1
  66. package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
  67. package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
  68. package/package.json +1 -1
  69. package/plugin.json +1 -1
  70. package/skills_manifest.json +1 -1
  71. package/synapse.config.json +1 -1
  72. package/templates/ai_bridges/CLAUDE.md +29 -26
  73. package/templates/ai_bridges/copilot-instructions.md +14 -5
  74. package/templates/ai_bridges/cursor_synapse_qa.mdc +16 -7
  75. package/templates/ai_bridges/windsurfrules +14 -3
  76. package/tools/TOOLS_RUNBOOK.md +1 -1
  77. package/tools/__init__.py +1 -1
  78. package/tools/api_fuzzer.py +295 -41
  79. package/tools/benchmark_swarm_context.py +11 -4
  80. package/tools/browser_helpers.js +2 -2
  81. package/tools/bump_version.py +2 -2
  82. package/tools/cli.py +4 -4
  83. package/tools/core/bm25_retriever.py +1 -1
  84. package/tools/core/i18n.py +1 -1
  85. package/tools/core/provider_usage_adapter.py +66 -0
  86. package/tools/core/token_estimator.py +39 -1
  87. package/tools/count_tokens.py +2 -2
  88. package/tools/dashboard_generator.py +8 -8
  89. package/tools/db_sandbox.py +182 -43
  90. package/tools/distill_log.py +1 -1
  91. package/tools/distill_skill.py +17 -2
  92. package/tools/git_pre_commit_guard.py +190 -1
  93. package/tools/hub_publisher.py +2 -12
  94. package/tools/mcp_docx_server.py +1 -1
  95. package/tools/mcp_excel_server.py +1 -1
  96. package/tools/mcp_server.py +33 -5
  97. package/tools/micro_mutator.py +30 -1
  98. package/tools/pentest_scope_guard.py +288 -15
  99. package/tools/project_state.py +29 -5
  100. package/tools/reversible_sandbox.py +58 -13
  101. package/tools/rules_router.py +80 -27
  102. package/tools/skill_canonical_digest.py +60 -2
  103. package/tools/sync_agent_rules.py +187 -61
  104. package/tools/task_memory_manager.py +16 -1
  105. package/tools/ui_server.py +3 -1
  106. package/tools/update_sentinel.py +3 -3
  107. package/tools/validate_skills_schema.py +349 -56
  108. package/tools/verify_all.py +98 -4
  109. 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
- os.replace(actual_tmp, self.checksums_path)
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()
@@ -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.0",
241
+ "version": "4.2.2",
240
242
  "status": "ONLINE",
241
243
  "os": sys.platform,
242
244
  "workspace": active_target,
@@ -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.0")
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.0")
80
+ return data.get("version", "4.2.2")
81
81
  except (OSError, json.JSONDecodeError):
82
82
  data = {}
83
83
 
84
- return "4.2.0"
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 the Agent Skills Frontmatter & Policies Specification.
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 validate_skill(skill_md_path: Path, check_links: bool = True) -> List[str]:
109
- """Validates a single SKILL.md file against the specification."""
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
- if not actual_name:
254
+ name = skill_data.get("name")
255
+ if not name or not str(name).strip():
127
256
  errors.append("Missing required field: 'name'")
128
- elif actual_name != expected_name:
129
- errors.append(f"Field 'name' ('{actual_name}') does not match directory name ('{expected_name}')")
130
- elif len(actual_name) > 64 or not SKILL_NAME_REGEX.match(actual_name):
131
- errors.append(f"Invalid 'name' format: '{actual_name}' (must be lowercase alphanumeric + hyphens, <= 64 chars)")
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 = fm.get("description")
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. Category check
145
- category = fm.get("category")
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
- # 4. Version check
152
- version = fm.get("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
- # 5. Policies check
159
- policies = fm.get("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
- # 6. Relative links check
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
- for match in MD_LINK_REGEX.finditer(body):
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 = (skill_md_path.parent / clean_target).resolve()
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
- # 7. Progressive disclosure directories check
186
- examples_dir = skill_md_path.parent / "examples"
187
- if not examples_dir.is_dir():
188
- errors.append("Missing mandatory 'examples/' directory (Progressive Disclosure L3)")
189
- elif not list(examples_dir.iterdir()):
190
- errors.append("'examples/' directory is empty")
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
- # If L2 references/ or resources/ exist, ensure they contain valid files
193
- for l2_dir_name in ("references", "resources"):
194
- l2_dir = skill_md_path.parent / l2_dir_name
195
- if l2_dir.is_dir() and not list(l2_dir.iterdir()):
196
- errors.append(f"Progressive disclosure directory '{l2_dir_name}/' exists but is empty")
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
- # 8. Progressive disclosure structure check in SKILL.md body
199
- if not re.search(r"^##?\s+", body, re.MULTILINE):
200
- errors.append("SKILL.md body missing standard markdown section headings ('## ...') for progressive disclosure")
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(skills_dir: Path, check_links: bool = True) -> Tuple[int, Dict[str, List[str]]]:
206
- """Scans all skills under skills_dir and validates each SKILL.md."""
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(description="Validate Agent Skills frontmatter schema and policies.")
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(skills_path, check_links=args.check_links)
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 Frontmatter Schema & Policies.")
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 schema or link errors:\n")
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: