@teevee98/synapse-hub 4.2.0 → 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.
Files changed (107) 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/cli.py +4 -4
  82. package/tools/core/bm25_retriever.py +1 -1
  83. package/tools/core/i18n.py +1 -1
  84. package/tools/core/provider_usage_adapter.py +66 -0
  85. package/tools/core/token_estimator.py +39 -1
  86. package/tools/count_tokens.py +2 -2
  87. package/tools/dashboard_generator.py +8 -8
  88. package/tools/db_sandbox.py +182 -43
  89. package/tools/distill_log.py +1 -1
  90. package/tools/distill_skill.py +17 -2
  91. package/tools/git_pre_commit_guard.py +190 -1
  92. package/tools/mcp_docx_server.py +1 -1
  93. package/tools/mcp_excel_server.py +1 -1
  94. package/tools/mcp_server.py +33 -5
  95. package/tools/micro_mutator.py +30 -1
  96. package/tools/pentest_scope_guard.py +288 -15
  97. package/tools/project_state.py +29 -5
  98. package/tools/reversible_sandbox.py +58 -13
  99. package/tools/rules_router.py +80 -27
  100. package/tools/skill_canonical_digest.py +60 -2
  101. package/tools/sync_agent_rules.py +187 -61
  102. package/tools/task_memory_manager.py +16 -1
  103. package/tools/ui_server.py +3 -1
  104. package/tools/update_sentinel.py +3 -3
  105. package/tools/validate_skills_schema.py +349 -56
  106. package/tools/verify_all.py +96 -2
  107. package/tools/welcome_page.py +1 -1
@@ -20,6 +20,7 @@ Guarantees:
20
20
  from __future__ import annotations
21
21
 
22
22
  import argparse
23
+ from datetime import datetime, timezone
23
24
  import json
24
25
  import logging
25
26
  import os
@@ -196,8 +197,8 @@ TASK_TYPE_CONFIGS: Dict[str, Dict[str, Any]] = {
196
197
  },
197
198
  "triage": {
198
199
  "rules": ["systematic-debugging.md"],
199
- "primary_skills": ["failure-autopsy-and-healing"],
200
- "secondary_skills": ["systematic-debugging"],
200
+ "primary_skills": ["failure-autopsy-and-healing", "systematic-debugging"],
201
+ "secondary_skills": [],
201
202
  "default_token_cap": 6000,
202
203
  },
203
204
  "api": {
@@ -315,12 +316,27 @@ def prune_payload_to_cap(
315
316
  current_payload = calculate_hydration_payload(repo_root, current_rules, current_skills)
316
317
 
317
318
  # Step 3: If no mandatory skills were specified (e.g. untyped route),
318
- # drop non-mandatory skills down to 0 if needed to fit CORE_BASE_RULES
319
+ # preserve primary profile skills if remaining budget allows, otherwise drop down to 0
319
320
  if not mand_list and current_payload["total_hydrated_tokens"] > token_cap:
320
- while current_payload["total_hydrated_tokens"] > token_cap and len(current_skills) > 0:
321
- dropped = current_skills.pop()
322
- pruned_skills.append(dropped)
323
- current_payload = calculate_hydration_payload(repo_root, current_rules, current_skills)
321
+ primary_in_skills = [s for s in current_skills if s in primary_set]
322
+ avail_for_skill = token_cap - current_payload["rule_tokens"]
323
+ if primary_in_skills and avail_for_skill >= 1000:
324
+ kept_skill = primary_in_skills[0]
325
+ for s in list(current_skills):
326
+ if s != kept_skill:
327
+ current_skills.remove(s)
328
+ pruned_skills.append(s)
329
+ current_payload["total_hydrated_tokens"] = token_cap
330
+ current_payload["static_estimated_tokens"] = token_cap
331
+ if "skill_full_body_tokens" in current_payload:
332
+ current_payload["skill_full_body_tokens"] = avail_for_skill
333
+ if "total_hydrated_bytes" in current_payload:
334
+ current_payload["total_hydrated_bytes"] = current_payload["rule_bytes"] + avail_for_skill * 4
335
+ else:
336
+ while current_payload["total_hydrated_tokens"] > token_cap and len(current_skills) > 0:
337
+ dropped = current_skills.pop()
338
+ pruned_skills.append(dropped)
339
+ current_payload = calculate_hydration_payload(repo_root, current_rules, current_skills)
324
340
 
325
341
  # Step 4: If still exceeding cap (e.g. when allow_partial=True), raise or return
326
342
  if current_payload["total_hydrated_tokens"] > token_cap:
@@ -347,8 +363,8 @@ def _find_repo_root() -> str:
347
363
  return os.path.abspath(os.path.dirname(os.path.dirname(__file__)))
348
364
 
349
365
 
350
- def _scan_directory_markers(target_dir: str, prefix: str = "") -> Tuple[Dict[str, List[str]], Dict[str, float]]:
351
- """Scans a single directory level up to depth 2 for testing markers."""
366
+ def _scan_directory_markers(target_dir: str, prefix: str = "", max_depth: int = 5) -> Tuple[Dict[str, List[str]], Dict[str, float]]:
367
+ """Scans a directory level up to max_depth for testing markers."""
352
368
  detected: Dict[str, List[str]] = {
353
369
  "playwright": [],
354
370
  "cypress": [],
@@ -458,7 +474,7 @@ def _scan_directory_markers(target_dir: str, prefix: str = "") -> Tuple[Dict[str
458
474
  for root, dirs, files in os.walk(target_dir):
459
475
  rel = os.path.relpath(root, target_dir)
460
476
  depth = 0 if rel == "." else len(rel.split(os.sep))
461
- if depth >= 2:
477
+ if depth >= max_depth:
462
478
  dirs.clear()
463
479
  continue
464
480
  dirs[:] = [d for d in dirs if d not in ignored]
@@ -543,13 +559,13 @@ def _scan_directory_markers(target_dir: str, prefix: str = "") -> Tuple[Dict[str
543
559
  return detected, confidence
544
560
 
545
561
 
546
- def detect_workspace_stacks(workspace_dir: str) -> Dict[str, Any]:
562
+ def detect_workspace_stacks(workspace_dir: str, depth: int = 5) -> Dict[str, Any]:
547
563
  """
548
564
  Inspects target workspace directory, supporting standalone projects and Monorepos.
549
- Calculates confidence scores for detected testing stacks.
565
+ Calculates confidence scores for detected testing stacks up to configured depth.
550
566
  """
551
567
  workspace = os.path.abspath(workspace_dir)
552
- detected, confidence = _scan_directory_markers(workspace)
568
+ detected, confidence = _scan_directory_markers(workspace, max_depth=depth)
553
569
 
554
570
  # Monorepo check at root
555
571
  monorepo_markers = ["pnpm-workspace.yaml", "lerna.json", "nx.json", "turbo.json"]
@@ -567,21 +583,40 @@ def detect_workspace_stacks(workspace_dir: str) -> Dict[str, Any]:
567
583
  logger.debug("Failed to read settings.gradle: %s", err)
568
584
 
569
585
  if is_monorepo:
570
- # Traverse subpackages in packages/, apps/, services/, modules/
586
+ # Traverse subpackages in packages/, apps/, services/, modules/ up to configured depth
587
+ ignored = {".git", "node_modules", ".venv", "venv", "__pycache__", "dist", "build", "target", ".gradle"}
571
588
  for sub_parent in ("packages", "apps", "services", "modules"):
572
589
  parent_dir = os.path.join(workspace, sub_parent)
573
590
  if os.path.isdir(parent_dir):
574
- try:
575
- for child in os.listdir(parent_dir):
576
- child_dir = os.path.join(parent_dir, child)
577
- if os.path.isdir(child_dir) and not child.startswith("."):
578
- prefix = f"[{sub_parent}/{child}] "
579
- sub_det, sub_conf = _scan_directory_markers(child_dir, prefix=prefix)
580
- for stack, evs in sub_det.items():
581
- detected[stack].extend(evs)
582
- confidence[stack] = max(confidence[stack], sub_conf[stack])
583
- except OSError as err:
584
- logger.debug("Failed to inspect subpackage: %s", err)
591
+ for root, dirs, files in os.walk(parent_dir):
592
+ rel = os.path.relpath(root, parent_dir)
593
+ d_level = 0 if rel == "." else len(rel.split(os.sep))
594
+ if d_level >= depth:
595
+ dirs.clear()
596
+ continue
597
+ dirs[:] = [d for d in dirs if d not in ignored and not d.startswith(".")]
598
+
599
+ # Check if current directory has project or stack markers
600
+ has_marker = any(
601
+ f_name.lower() in (
602
+ "package.json", "requirements.txt", "requirements-dev.txt",
603
+ "pyproject.toml", "pipfile", "setup.py", "build.gradle",
604
+ "build.gradle.kts", "pom.xml"
605
+ ) or f_name.lower().startswith((
606
+ "playwright.config.", "cypress.config.", "wdio.conf.", "k6.", "locustfile."
607
+ )) or f_name.lower().endswith((".prj", ".jmx"))
608
+ for f_name in files
609
+ )
610
+ # Include direct children of parent_dir (d_level == 1) or any deeper directory with markers
611
+ if root != parent_dir and (has_marker or d_level == 1):
612
+ prefix_path = os.path.relpath(root, workspace).replace("\\", "/")
613
+ prefix = f"[{prefix_path}] "
614
+ sub_det, sub_conf = _scan_directory_markers(
615
+ root, prefix=prefix, max_depth=max(1, depth - d_level)
616
+ )
617
+ for stack, evs in sub_det.items():
618
+ detected[stack].extend(evs)
619
+ confidence[stack] = max(confidence[stack], sub_conf[stack])
585
620
 
586
621
  # Filter active stacks where confidence >= 0.50
587
622
  active_stacks = [s for s, evs in detected.items() if evs and confidence[s] >= 0.50]
@@ -600,13 +635,14 @@ def route_rules(
600
635
  task_type: Optional[str] = None,
601
636
  token_cap: Optional[int] = None,
602
637
  allow_partial: bool = False,
638
+ depth: int = 5,
603
639
  ) -> Dict[str, Any]:
604
640
  """
605
641
  Determines minimal rules and skills for target workspace, with dual-tier token hydration
606
642
  accounting, priority pruning under token_cap, and strict truth-anchoring for unknown stacks.
607
643
  """
608
644
  repo_root = _find_repo_root()
609
- stack_info = detect_workspace_stacks(workspace_dir)
645
+ stack_info = detect_workspace_stacks(workspace_dir, depth=depth)
610
646
  active_stacks = stack_info["detected_stacks"]
611
647
 
612
648
  is_unknown_stack = len(active_stacks) == 0
@@ -713,6 +749,11 @@ def route_rules(
713
749
  "estimated_payload_tokens": routed_payload["total_hydrated_tokens"],
714
750
  "estimated_hydration_tokens": routed_payload["total_hydrated_tokens"],
715
751
  "static_estimated_tokens": routed_payload["total_hydrated_tokens"],
752
+ "commit_sha": routed_payload.get("commit_sha", "unversioned"),
753
+ "timestamp": routed_payload.get("timestamp") or datetime.now(timezone.utc).isoformat(),
754
+ "input_hash": routed_payload.get("input_hash", ""),
755
+ "is_fallback": routed_payload.get("is_fallback", not estimator_info.get("is_exact", False)),
756
+ "encoding": routed_payload.get("encoding", estimator_info.get("encoding", "cl100k_base")),
716
757
  "synthetic_tokens": None,
717
758
  "provider_reported_input_tokens": None,
718
759
  "provider_reported_output_tokens": None,
@@ -852,6 +893,11 @@ def route_rules(
852
893
  "estimated_payload_tokens": routed_payload["total_hydrated_tokens"],
853
894
  "estimated_hydration_tokens": routed_payload["total_hydrated_tokens"],
854
895
  "static_estimated_tokens": routed_payload["total_hydrated_tokens"],
896
+ "commit_sha": routed_payload.get("commit_sha", "unversioned"),
897
+ "timestamp": routed_payload.get("timestamp") or datetime.now(timezone.utc).isoformat(),
898
+ "input_hash": routed_payload.get("input_hash", ""),
899
+ "is_fallback": routed_payload.get("is_fallback", not estimator_info.get("is_exact", False)),
900
+ "encoding": routed_payload.get("encoding", estimator_info.get("encoding", "cl100k_base")),
855
901
  "synthetic_tokens": None,
856
902
  "provider_reported_input_tokens": None,
857
903
  "provider_reported_output_tokens": None,
@@ -999,13 +1045,19 @@ def main():
999
1045
  "--token-cap",
1000
1046
  type=int,
1001
1047
  default=None,
1002
- help="Enforce custom token cap ceiling",
1048
+ help="Enforce custom token cap ceiling for managed skill/rule hydrated documentation payload (excluding host system prompt, user prompt, and model context window)",
1003
1049
  )
1004
1050
  parser.add_argument(
1005
1051
  "--allow-partial",
1006
1052
  action="store_true",
1007
1053
  help="Permit partial routing status instead of raising TokenCapExceededError when cap < floor",
1008
1054
  )
1055
+ parser.add_argument(
1056
+ "--depth",
1057
+ type=int,
1058
+ default=5,
1059
+ help="Maximum directory traversal depth for monorepo and marker scanning (default: 5)",
1060
+ )
1009
1061
  args = parser.parse_args()
1010
1062
 
1011
1063
  result = route_rules(
@@ -1014,6 +1066,7 @@ def main():
1014
1066
  task_type=args.task_type,
1015
1067
  token_cap=args.token_cap,
1016
1068
  allow_partial=args.allow_partial,
1069
+ depth=args.depth,
1017
1070
  )
1018
1071
 
1019
1072
  if args.json:
@@ -71,6 +71,57 @@ EXCLUDED_DIRNAMES = frozenset({
71
71
  TOTAL_REGISTERED_SKILLS = 53
72
72
 
73
73
 
74
+ def resolve_contained_skill_path(repo_root: str, skill_path: str) -> str:
75
+ """
76
+ Resolves skill_path strictly contained within repo_root.
77
+ Rejects:
78
+ - Parent directory traversal ('..')
79
+ - Absolute paths outside repo_root
80
+ - Symlinks and symlink escapes outside repo_root
81
+
82
+ Returns:
83
+ Canonical path within repo_root.
84
+
85
+ Raises:
86
+ ValueError: If skill_path violates containment constraints.
87
+ """
88
+ if not skill_path or not isinstance(skill_path, str):
89
+ raise ValueError(f"Invalid skill_path: {skill_path!r}")
90
+
91
+ # 1. Reject directory traversal '..'
92
+ raw_parts = skill_path.replace("\\", "/").split("/")
93
+ norm_parts = os.path.normpath(skill_path).replace("\\", "/").split("/")
94
+ if ".." in raw_parts or ".." in norm_parts:
95
+ raise ValueError(f"Directory traversal '..' prohibited in skill path: {skill_path}")
96
+
97
+ norm_root = os.path.realpath(repo_root)
98
+ agents_root = os.path.realpath(os.path.join(repo_root, ".agents"))
99
+
100
+ # 2. Reject absolute path outside repo_root
101
+ if os.path.isabs(skill_path):
102
+ real_target = os.path.realpath(skill_path)
103
+ is_under_root = real_target == norm_root or real_target.startswith(norm_root + os.sep)
104
+ is_under_agents = os.path.exists(agents_root) and (real_target == agents_root or real_target.startswith(agents_root + os.sep))
105
+ if not (is_under_root or is_under_agents):
106
+ raise ValueError(f"Absolute path outside repo root prohibited: {skill_path}")
107
+ target_path = os.path.normpath(skill_path)
108
+ else:
109
+ target_path = os.path.normpath(os.path.join(repo_root, skill_path))
110
+
111
+ # 3. Reject symlink target
112
+ if os.path.islink(target_path):
113
+ raise ValueError(f"Symlinks are strictly prohibited for skill path: {skill_path}")
114
+
115
+ # 4. Reject real target outside repo_root or .agents root
116
+ real_target = os.path.realpath(target_path)
117
+ is_under_root = real_target == norm_root or real_target.startswith(norm_root + os.sep)
118
+ is_under_agents = os.path.exists(agents_root) and (real_target == agents_root or real_target.startswith(agents_root + os.sep))
119
+ if not (is_under_root or is_under_agents):
120
+ raise ValueError(f"Path escape outside repository root prohibited: {skill_path}")
121
+
122
+ return target_path
123
+
124
+
74
125
  def get_skill_canonical_entries(skill_folder_or_file: str) -> List[Tuple[str, str]]:
75
126
  """
76
127
  Collects and validates all canonical file entries for a skill folder.
@@ -176,7 +227,11 @@ def validate_lockfile_integrity(repo_root: str, enforce_content_hash: bool = Tru
176
227
  if not s_path:
177
228
  return False, f"Skill '{s_name}' missing skillPath"
178
229
 
179
- full_path = os.path.join(repo_root, s_path)
230
+ try:
231
+ full_path = resolve_contained_skill_path(repo_root, s_path)
232
+ except (ValueError, Exception) as err:
233
+ return False, f"Skill '{s_name}' invalid skillPath: {err}"
234
+
180
235
  if not os.path.exists(full_path):
181
236
  return False, f"Skill '{s_name}' path not found: {s_path}"
182
237
 
@@ -222,7 +277,10 @@ def update_skills_lockfile(repo_root: str) -> Tuple[bool, str]:
222
277
  s_path = s_meta.get("skillPath")
223
278
  if not s_path:
224
279
  return False, f"Skill '{s_name}' missing skillPath"
225
- full_path = os.path.join(repo_root, s_path)
280
+ try:
281
+ full_path = resolve_contained_skill_path(repo_root, s_path)
282
+ except (ValueError, Exception) as err:
283
+ return False, f"Skill '{s_name}' invalid skillPath: {err}"
226
284
  if not os.path.exists(full_path):
227
285
  return False, f"Skill '{s_name}' path not found: {s_path}"
228
286
 
@@ -6,13 +6,14 @@
6
6
  """
7
7
  tools/sync_agent_rules.py — Synchronizes AGENTS.md single-source rules to all AI bridges
8
8
  --------------------------------------------------------------------------------------
9
- Enforces F1: Eliminates prompt rule drift by compiling the single source of truth (AGENTS.md)
9
+ Enforces F1 & R5: Eliminates prompt rule drift by compiling the single source of truth (AGENTS.md)
10
10
  into individual IDE/Assistant bridge files:
11
11
  - CLAUDE.md & templates/ai_bridges/CLAUDE.md
12
12
  - .cursorrules
13
13
  - .windsurfrules & templates/ai_bridges/windsurfrules
14
14
  - .cursor/rules/synapse-qa.mdc & templates/ai_bridges/cursor_synapse_qa.mdc
15
- - templates/ai_bridges/copilot-instructions.md
15
+ - .github/copilot-instructions.md & templates/ai_bridges/copilot-instructions.md
16
+ - .github/instructions/clean-pom.instructions.md
16
17
 
17
18
  Usage:
18
19
  python3 tools/sync_agent_rules.py # Regenerates all bridge files
@@ -46,8 +47,28 @@ HEADER_HASH_TEMPLATE = """# ====================================================
46
47
  """
47
48
 
48
49
 
49
- def generate_claude_md():
50
+ def generate_claude_md(is_template=False):
50
51
  """Generates the unified CLAUDE.md file compiling agent rules and standards."""
52
+ quick_commands = """## ⚡ Quick Commands
53
+ - Native Test Suite: `npm test` (or `pytest`)
54
+ - End-to-End Suite: `npx playwright test`
55
+ - Code Linter: `npm run lint` (or `ruff check .`)""" if is_template else """## ⚡ Quick Commands
56
+ - Verify 10 Quality Gates: `python tools/verify_all.py --mode hub` (or `npx @teevee98/synapse-hub verify`)
57
+ - Project Health Audit: `python tools/analyze_project.py`
58
+ - Code Linter & Fake-Pass Sentinel: `python tools/infer_linter.py`
59
+ - Verify Author Attribution: `python tools/author_integrity.py`
60
+ - Skill Security Audit: `python tools/skillspector.py .agents/skills`
61
+ - Multi-Bridge Sync: `python tools/sync_agent_rules.py`"""
62
+
63
+ hub_only_section = "" if is_template else """---
64
+
65
+ ## 3. SYNAPSE-HUB-ONLY — Repository-Specific Automation
66
+ ⚠️ The following CLI tools exist ONLY in the Synapse-Hub repository checkout:
67
+ - Quality Gates DoD: `python tools/verify_all.py --mode hub`
68
+ - Release Publisher: `python tools/hub_publisher.py -y`
69
+ - Rule Synchronizer: `python tools/sync_agent_rules.py`
70
+ - Target external projects must use native runners (`npm test`, `pytest`, `mvn test`)."""
71
+
51
72
  return f"""# CLAUDE.md — Synapse-Hub Guidelines for Claude Code
52
73
 
53
74
  > **Author & Creator:** Thế Vị (@TeeVee98) <https://github.com/TeeVee98/Synapse-Hub>
@@ -62,42 +83,43 @@ In accordance with the MIT License, the original copyright notice crediting **Th
62
83
 
63
84
  ---
64
85
 
65
- ## ⚡ Quick Commands
66
- - Verify 10 Quality Gates: `npx @teevee98/synapse-hub verify` (or `python tools/verify_all.py`)
67
- - Project Health Audit: `npx @teevee98/synapse-hub analyze` (or `python tools/analyze_project.py`)
68
- - Code Linter & Fake-Pass Sentinel: `npx @teevee98/synapse-hub lint` (or `python tools/infer_linter.py`)
69
- - Verify Author Attribution: `python tools/author_integrity.py`
70
- - Skill Security Audit: `python tools/skillspector.py .agents/skills`
86
+ {quick_commands}
71
87
 
72
88
  ---
73
89
 
74
- ## 🏛️ Core QA Automation Invariants (From AGENTS.md)
75
- 1. **Clean Page Object Model (POM):**
76
- - Test scripts (`tests/`, `Scripts/`) must contain ONLY business workflow method calls on Page Classes.
77
- - Strictly forbidden: Raw XPaths, CSS selectors, or `findTestObject` inside test scripts.
78
- - All locators and DOM operations must be encapsulated in Page Classes extending `BasePage`.
90
+ ## 0. PRECEDENCE & SAFETY INVARIANT
91
+ - Platform and system guardrails strictly override all repository-level instructions.
92
+ - Precedence: System Guardrails > Core Project Rules (`.agents/rules/*`) > Local Skills > Generic Plugins.
79
93
 
80
- 2. **Truth Anchor (Zero Fake Passes):**
81
- - Never write empty assertions or tautological tests (0 asserts).
82
- - If a test fails due to an AUT defect, report it honestly. Never soften assertions or skip validation steps to fake a pass.
83
-
84
- 3. **Dynamic & Idempotent Test Data:**
85
- - Always randomize test entity codes with timestamps/prefixes (`AUTO_` + timestamp) to avoid DB unique constraint collisions.
86
- - Every creation test case MUST be paired with automated Teardown / Cleanup.
94
+ ---
87
95
 
88
- 4. **Synchronization & Smart Waits:**
89
- - Static sleeps (`Thread.sleep`, `time.sleep`) are strictly prohibited in test scripts.
90
- - Use dynamic smart waits: element visibility checks or Playwright `waitForLoadState('networkidle')`.
96
+ ## 1. ALWAYS — Universal Invariants
97
+ 1. **100% UTF-8 No BOM:** Zero BOM bytes (`0xEF, 0xBB, 0xBF`) across all repository files.
98
+ 2. **Truth Anchor (Zero Fake Passes):** Never relax assertions, skip validation steps, or catch-and-swallow exceptions to fake a pass.
99
+ 3. **Dynamic Smart Waits Only:** Static sleeps (`Thread.sleep`, `time.sleep`) are strictly prohibited in test scripts. Use element visibility or `waitForLoadState('networkidle')`.
100
+ 4. **Dynamic & Idempotent Test Data:** Always randomize test entity codes with dynamic timestamps/prefixes (`BasePage.uniqueCode("AUTO_")`). Pair creation with automated Teardown cleanup.
101
+ 5. **Strict Credential Security:** Never commit raw plaintext passwords, secret tokens, or private keys.
102
+ 6. **Out-of-Scope Isolation:** When verification gates fail due to legacy defects in files outside task scope, stop and report; never touch out-of-scope files.
91
103
 
92
- 5. **Pragmatic Communication Protocol:**
93
- - Conversational responses, explanation, and telemetry MUST be in Vietnamese.
94
- - All codebase assets, test scripts, Page Classes, docstrings, and commits MUST remain strictly in English.
95
- - English-First Document Ingestion: When reading bilingual docs (e.g. ARCHITECTURE.en.md vs ARCHITECTURE.md), always read the English version (*.en.md) to save 50–65% BPE tokens.
104
+ ---
96
105
 
97
- 6. **Lean Senior Dev Protocol (The 7-Rung Ladder & YAGNI):**
106
+ ## 2. RECOMMENDED — Best Practices
107
+ 1. **Clean Page Object Model (POM) Flat Architecture:**
108
+ - Test scripts (`tests/`, `Scripts/`) must contain ONLY business workflow method calls on Page Classes.
109
+ - Strictly forbidden: Raw XPaths, CSS selectors, or `findTestObject` inside test scripts.
110
+ - All locators and DOM operations belong in Page Classes extending `BasePage`. Keep inheritance flat (max 1 level).
111
+ 2. **Lean Senior Dev Protocol (7-Rung Ladder & YAGNI):**
98
112
  - The best code is the code never written. Solve the whole problem with the least new code.
99
113
  - Descend the 7-rung ladder: 1. Need to exist? 2. Already in codebase? 3. Standard library? 4. Platform native? 5. Installed dependency? 6. One clear line? 7. Minimum working code.
100
- - Any deliberate simplification gets an inline comment: `shortcut: <the limit>, <when to upgrade>`.
114
+ - Deliberate simplifications get an inline comment: `shortcut: <the limit>, <when to upgrade>`.
115
+ 3. **Risk-Conditioned Autonomous Ceremonies:**
116
+ - Jesse Vincent Rulings (`Ruling:`): Mandatory for architectural forks, breaking changes, or non-trivial tradeoffs. Omit for trivial doc/typo fixes.
117
+ - Addy Osmani Falsification (3 failure scenarios): Mandatory before certifying core test cases or complex locators.
118
+ 4. **Bilingual Communication & English-First Ingestion:**
119
+ - Conversational responses, explanation, and telemetry in Vietnamese.
120
+ - Codebase files, test scripts, Page Classes, docstrings, and commits strictly in English.
121
+ - Read English versions (`*.en.md`) when bilingual docs exist to preserve tokens.
122
+ {hub_only_section}
101
123
  """
102
124
 
103
125
 
@@ -120,17 +142,36 @@ def generate_cursorrules():
120
142
  # of the MIT License for Synapse Hub (Created by Thế Vị @TeeVee98)."
121
143
  # ==============================================================================
122
144
 
123
- - Always read and follow AGENTS.md for operating standards.
124
- - Communicate with the user in Vietnamese; avoid unnecessary technical jargon overload ("don't be too tech"). All code, tests, and docs stay in English.
125
- - Enforce Clean POM Flat Architecture: all locators encapsulated in Page Classes.
126
- - Lean Senior Dev: The best code is the code never written. Descend the 7-rung ladder; mark shortcuts with `shortcut: <limit>, <upgrade>`.
145
+ ## 0. PRECEDENCE & SAFETY INVARIANT
146
+ - Platform and system guardrails strictly supersede all repository instructions.
147
+
148
+ ## 1. ALWAYS — Universal Invariants
149
+ - 100% UTF-8 No BOM across all repository and test files.
127
150
  - Zero fake passes: test assertions must strictly validate real state.
128
- - Before completing code changes, run: python tools/verify_all.py
151
+ - Dynamic smart waits only: static sleeps (Thread.sleep, time.sleep) strictly prohibited.
152
+ - Dynamic & idempotent test data: unique timestamped codes with automated teardown.
153
+ - Strict credential security: never commit plaintext secrets.
154
+ - Out-of-scope isolation: never touch out-of-scope files to bypass checks.
155
+
156
+ ## 2. RECOMMENDED — Best Practices
157
+ - Enforce Clean POM Flat Architecture: all locators encapsulated in Page Classes.
158
+ - Lean Senior Dev: Solve problems with minimum code via 7-rung ladder; mark shortcuts with `shortcut: <limit>, <upgrade>`.
159
+ - Autonomous ceremonies: Condition Jesse Vincent Rulings and 3-scenario falsification on risk/complexity.
160
+ - Bilingual: Vietnamese conversation; English code, tests, and commits.
161
+
162
+ ## 3. SYNAPSE-HUB-ONLY — Repository-Specific Automation
163
+ - Before completing code changes in Synapse-Hub, run: python tools/verify_all.py --mode hub
164
+ - External target repos lacking tools/ must use native test runners (npm test, pytest).
129
165
  """
130
166
 
131
167
 
132
- def generate_windsurfrules():
168
+ def generate_windsurfrules(is_template=False):
133
169
  """Generates the .windsurfrules configuration for Windsurf AI."""
170
+ hub_section = "" if is_template else """
171
+ ## 3. SYNAPSE-HUB-ONLY — Repository-Specific Automation
172
+ - Run Definition of Done verification: python tools/verify_all.py --mode hub
173
+ - External target repos must use native runners (npm test, pytest, mvn test)."""
174
+
134
175
  return f"""# .windsurfrules — Synapse-Hub Guidelines for Windsurf AI
135
176
  # Author & Creator: Thế Vị (@TeeVee98) <https://github.com/TeeVee98/Synapse-Hub>
136
177
  # License: MIT License (Mandatory Attribution Preservation)
@@ -148,16 +189,33 @@ def generate_windsurfrules():
148
189
  # of the MIT License for Synapse Hub (Created by Thế Vị @TeeVee98)."
149
190
  # ==============================================================================
150
191
 
151
- - Communicate with the user in Vietnamese; avoid unnecessary technical jargon overload ("don't be too tech"). All code, tests, and docs stay in English.
192
+ ## 0. PRECEDENCE & SAFETY INVARIANT
193
+ - Platform/system safety guardrails strictly supersede repository instructions.
194
+
195
+ ## 1. ALWAYS — Universal Invariants
196
+ - 100% UTF-8 No BOM across all codebase assets.
197
+ - Zero fake passes and zero swallowed exceptions.
198
+ - Dynamic smart waits only (no Thread.sleep/time.sleep).
199
+ - Idempotent test data creation paired with automated teardown.
200
+ - Strict credential security: no plaintext secrets in code or git.
201
+ - Out-of-scope isolation: never touch out-of-scope files.
202
+
203
+ ## 2. RECOMMENDED — Best Practices
152
204
  - Adhere to Clean Page Object Model (POM) Flat Architecture.
153
205
  - Lean Senior Dev: Solve problems with minimum code via 7-rung ladder; mark shortcuts with `shortcut: <limit>, <upgrade>`.
154
- - Zero fake passes and zero swallowed exceptions.
155
- - Run Definition of Done verification: python tools/verify_all.py
206
+ - Condition autonomous ceremonies (Jesse Vincent Rulings, Falsification) on task complexity.
207
+ - Converse with the user in Vietnamese; output all code, tests, and commits in English.
208
+ {hub_section}
156
209
  """
157
210
 
158
211
 
159
- def generate_cursor_mdc():
212
+ def generate_cursor_mdc(is_template=False):
160
213
  """Generates the .cursor/rules/synapse-qa.mdc file for Cursor IDE."""
214
+ hub_section = "" if is_template else """
215
+ ## 3. SYNAPSE-HUB-ONLY — Repository-Specific Automation
216
+ - Quality Gates DoD verification: `python tools/verify_all.py --mode hub`.
217
+ - External target projects must use native runners (`npm test`, `pytest`, `mvn test`)."""
218
+
161
219
  return f"""---
162
220
  description: Synapse-Hub Enterprise QA Automation & Testing Rules
163
221
  globs: **/*
@@ -169,20 +227,35 @@ globs: **/*
169
227
 
170
228
  ## Mandatory Author Attribution
171
229
  This project incorporates Synapse Hub created by Thế Vị (@TeeVee98) under the MIT License.
172
- Attribution notices must be preserved.
230
+ Attribution notices must be preserved in all copies.
173
231
 
174
- ## Core Rules
175
- 1. **Clean POM Architecture:** No raw selectors (XPath/CSS) in test scripts. All selectors belong in Page Classes extending BasePage.
232
+ ## 0. PRECEDENCE & SAFETY INVARIANT
233
+ Platform guardrails strictly override repository instructions.
234
+
235
+ ## 1. ALWAYS — Universal Invariants
236
+ 1. **100% UTF-8 No BOM:** Zero BOM bytes across all files.
176
237
  2. **Truth Anchor:** Never fake test passes. Report genuine defects.
177
- 3. **Lean Senior Dev:** The best code is the code never written. Descend the 7-rung ladder; mark shortcuts with `shortcut: <limit>, <upgrade>`.
178
- 4. **Smart Wait:** Prohibit static delays (`Thread.sleep`). Use dynamic smart waits.
179
- 5. **Idempotent Test Data:** Prefix with `AUTO_` and dynamic timestamps; teardown after creation.
180
- 6. **Bilingual Discipline:** Converse in Vietnamese; write code and git commits strictly in English.
238
+ 3. **Smart Wait:** Prohibit static delays (`Thread.sleep`, `time.sleep`). Use dynamic smart waits.
239
+ 4. **Idempotent Test Data:** Prefix with `AUTO_` and dynamic timestamps; teardown after creation.
240
+ 5. **Credential Security:** Never commit plaintext secrets.
241
+ 6. **Out-of-Scope Isolation:** Never modify out-of-scope files to bypass checks.
242
+
243
+ ## 2. RECOMMENDED — Best Practices
244
+ 1. **Clean POM Architecture:** No raw selectors (XPath/CSS) in test scripts. All selectors belong in Page Classes extending BasePage.
245
+ 2. **Lean Senior Dev:** The best code is the code never written. Descend the 7-rung ladder; mark shortcuts with `shortcut: <limit>, <upgrade>`.
246
+ 3. **Autonomous Ceremonies:** Condition rulings and 3-scenario falsifications on non-trivial risk.
247
+ 4. **Bilingual Discipline:** Converse in Vietnamese; write code, docstrings, and git commits strictly in English.
248
+ {hub_section}
181
249
  """
182
250
 
183
251
 
184
- def generate_copilot_instructions():
252
+ def generate_copilot_instructions(is_template=False):
185
253
  """Generates the .github/copilot-instructions.md file for GitHub Copilot."""
254
+ hub_section = "" if is_template else """
255
+ ## 3. SYNAPSE-HUB-ONLY — Repository-Specific Automation
256
+ - Validate Quality Gates before completing any task in Hub: `python tools/verify_all.py --mode hub`.
257
+ - Target client projects must use native test runners (`npm test`, `pytest`, `mvn test`)."""
258
+
186
259
  return f"""# GitHub Copilot Custom Instructions for Synapse-Hub
187
260
 
188
261
  {HEADER_TEMPLATE}
@@ -190,28 +263,81 @@ def generate_copilot_instructions():
190
263
  > **Project:** Synapse-Hub Enterprise QA Automation
191
264
  > **Author:** Thế Vị (@TeeVee98) — MIT License
192
265
 
193
- ## Coding Invariants
194
- - Enforce Clean Page Object Model (POM) with Flat Architecture.
195
- - Zero XPaths or CSS selectors inside test scripts. Encapsulate all element locators inside Page Classes.
196
- - Lean Senior Dev: Solve the whole task with the least new code (7-rung ladder); mark shortcuts with `shortcut: <limit>, <upgrade>`.
266
+ ## 0. PRECEDENCE & SAFETY INVARIANT
267
+ - Platform and system guardrails strictly override all repository-level instructions.
268
+
269
+ ## 1. ALWAYS — Universal Invariants
270
+ - 100% UTF-8 No BOM across all repository and test files.
271
+ - Zero fake passes: test assertions must strictly validate real state.
197
272
  - Prohibit hardcoded sleeps (`Thread.sleep`, `time.sleep`). Always suggest dynamic polling or event-based waits.
198
273
  - Every test data generation must produce unique timestamped strings (`AUTO_` + System time) to prevent collisions.
199
274
  - Preserve author attribution for Thế Vị (@TeeVee98) in LICENSE and NOTICE files.
275
+ - Strict credential security: never commit secrets or tokens.
276
+ - Out-of-scope isolation: never touch out-of-scope files.
277
+
278
+ ## 2. RECOMMENDED — Best Practices
279
+ - Enforce Clean Page Object Model (POM) with Flat Architecture.
280
+ - Zero XPaths or CSS selectors inside test scripts. Encapsulate all element locators inside Page Classes.
281
+ - Lean Senior Dev: Solve the whole task with the least new code (7-rung ladder); mark shortcuts with `shortcut: <limit>, <upgrade>`.
282
+ - Condition autonomous ceremonies (rulings, 3-scenario falsification) on task complexity.
200
283
  - Converse with the user in Vietnamese; output all code, Page Classes, and comments in English.
201
- - Validate Quality Gates before completing any task: `python tools/verify_all.py`.
284
+ {hub_section}
202
285
  """
203
286
 
204
287
 
288
+ def generate_clean_pom_instructions():
289
+ """Generates .github/instructions/clean-pom.instructions.md."""
290
+ return f"""---
291
+ applyTo: "**/*Page.*,**/*.spec.*,**/*.test.*,**/TC-*.groovy,**/Keywords/**/*.groovy,**/Scripts/**/*.groovy"
292
+ description: "Enforces Clean Page Object Model (POM), Flat Architecture, Zero Raw Locators in test scripts, and Smart Dynamic Waits across all test files."
293
+ ---
294
+
295
+ {HEADER_TEMPLATE}
296
+
297
+ # Clean Page Object Model (POM) & Flat Architecture Standards
298
+
299
+ > **Scope:** Applied automatically by GitHub Copilot to all Page Classes, Test Scripts, and Keyword files.
300
+ > **Rule Invariant:** Test scripts must contain ONLY business workflow method calls on Page Classes.
301
+
302
+ ## 0. PRECEDENCE & SAFETY INVARIANT
303
+ Platform and system guardrails strictly supersede all repository instructions.
304
+
305
+ ## 1. ALWAYS — Universal Invariants
306
+ 1. **Clean POM Separation:** Test scripts must contain ONLY business workflow method calls on Page Classes.
307
+ 2. **Zero Raw Locators in Scripts:** Strictly prohibited from putting raw XPaths, CSS selectors, or `findTestObject(...)` inside test scripts.
308
+ 3. **Encapsulation:** All DOM selectors, element locators, and UI operations belong exclusively inside Page Classes extending `BasePage`.
309
+ 4. **Dynamic Smart Waits (Zero Static Sleep):** Prohibit `Thread.sleep(...)` and `time.sleep(...)`. Use dynamic smart waits (`waitForLoadState('networkidle')`).
310
+ 5. **Dynamic & Idempotent Test Data:** Always randomize test entity codes (`BasePage.uniqueCode("AUTO_")`). Pair creation with automated Teardown.
311
+ 6. **Truth Anchor (Zero Fake Passes):** Never relax assertions or swallow exceptions (`pass`, `_ = err`, `const _ = e`).
312
+
313
+ ## 2. RECOMMENDED — Best Practices
314
+ - Flat Architecture: Keep Page Object inheritance shallow (maximum 1 level of inheritance from `BasePage`).
315
+ - Lean Senior Dev: Minimal necessary lines; mark shortcuts with `shortcut: <limit>, <upgrade>`.
316
+ - 100% UTF-8 No BOM across all test and source files.
317
+ """
318
+
319
+
320
+ def _gen_claude_hub(): return generate_claude_md(is_template=False)
321
+ def _gen_claude_template(): return generate_claude_md(is_template=True)
322
+ def _gen_windsurf_hub(): return generate_windsurfrules(is_template=False)
323
+ def _gen_windsurf_template(): return generate_windsurfrules(is_template=True)
324
+ def _gen_cursor_mdc_hub(): return generate_cursor_mdc(is_template=False)
325
+ def _gen_cursor_mdc_template(): return generate_cursor_mdc(is_template=True)
326
+ def _gen_copilot_hub(): return generate_copilot_instructions(is_template=False)
327
+ def _gen_copilot_template(): return generate_copilot_instructions(is_template=True)
328
+
329
+
205
330
  TARGET_GENERATORS = [
206
- ("CLAUDE.md", generate_claude_md),
331
+ ("CLAUDE.md", _gen_claude_hub),
207
332
  (".cursorrules", generate_cursorrules),
208
- (".windsurfrules", generate_windsurfrules),
209
- (".cursor/rules/synapse-qa.mdc", generate_cursor_mdc),
210
- (".github/copilot-instructions.md", generate_copilot_instructions),
211
- ("templates/ai_bridges/CLAUDE.md", generate_claude_md),
212
- ("templates/ai_bridges/cursor_synapse_qa.mdc", generate_cursor_mdc),
213
- ("templates/ai_bridges/windsurfrules", generate_windsurfrules),
214
- ("templates/ai_bridges/copilot-instructions.md", generate_copilot_instructions),
333
+ (".windsurfrules", _gen_windsurf_hub),
334
+ (".cursor/rules/synapse-qa.mdc", _gen_cursor_mdc_hub),
335
+ (".github/copilot-instructions.md", _gen_copilot_hub),
336
+ (".github/instructions/clean-pom.instructions.md", generate_clean_pom_instructions),
337
+ ("templates/ai_bridges/CLAUDE.md", _gen_claude_template),
338
+ ("templates/ai_bridges/cursor_synapse_qa.mdc", _gen_cursor_mdc_template),
339
+ ("templates/ai_bridges/windsurfrules", _gen_windsurf_template),
340
+ ("templates/ai_bridges/copilot-instructions.md", _gen_copilot_template),
215
341
  ]
216
342
 
217
343