@teevee98/synapse-hub 4.1.3 → 4.2.0

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 (206) hide show
  1. package/.agents/rules/git-push-protocol.md +2 -2
  2. package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +6 -1
  3. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +6 -1
  4. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +8 -3
  5. package/.agents/skills/01-web-automation/clean-pom-crafter/examples/standard_test_case.groovy +3 -0
  6. package/.agents/skills/01-web-automation/clean-pom-crafter/references/pom_patterns.groovy +3 -0
  7. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +6 -1
  8. package/.agents/skills/01-web-automation/e2e-testing-patterns/examples/playwright_sharded_config.ts +3 -0
  9. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +6 -1
  10. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +6 -1
  11. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +6 -1
  12. package/.agents/skills/01-web-automation/mobile-appium-som/examples/BaseScreen.java +2 -2
  13. package/.agents/skills/01-web-automation/mobile-appium-som/examples/LoginScreen.java +2 -2
  14. package/.agents/skills/01-web-automation/mobile-appium-som/examples/TC_MobileLogin.java +2 -2
  15. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +7 -2
  16. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +6 -1
  17. package/.agents/skills/01-web-automation/playwright-webapp-testing/examples/server_lifecycle_playwright.py +3 -0
  18. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +6 -1
  19. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +6 -1
  20. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +6 -1
  21. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +6 -1
  22. package/.agents/skills/02-test-design/review-spec/SKILL.md +4 -1
  23. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +6 -1
  24. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +6 -1
  25. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +6 -1
  26. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +7 -2
  27. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +7 -2
  28. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +4 -1
  29. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +6 -1
  30. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/examples/playwright_cwv_profiler_fixture.ts +3 -0
  31. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +6 -1
  32. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/references/dast_recipes.ts +3 -0
  33. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +6 -1
  34. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +6 -1
  35. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +6 -1
  36. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +6 -1
  37. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +7 -2
  38. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +6 -1
  39. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +6 -1
  40. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +6 -1
  41. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +6 -1
  42. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +6 -1
  43. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +6 -1
  44. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +6 -1
  45. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +6 -1
  46. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +6 -1
  47. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +6 -1
  48. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/examples/refactored_page_sample.groovy +3 -0
  49. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/examples/refactored_playwright_pom.ts +3 -0
  50. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +6 -1
  51. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +6 -1
  52. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +4 -1
  53. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +4 -1
  54. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +6 -1
  55. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +4 -1
  56. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +6 -1
  57. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +6 -1
  58. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +6 -1
  59. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +6 -1
  60. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +6 -1
  61. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +6 -1
  62. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +6 -1
  63. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +6 -1
  64. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +6 -1
  65. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/examples/surgical_code_window_walkthrough.md +1 -1
  66. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +6 -1
  67. package/AGENTS.md +7 -1
  68. package/LICENSE +5 -5
  69. package/NOTICE +1 -1
  70. package/README.en.md +4 -4
  71. package/README.md +4 -4
  72. package/agentskills.json +1 -1
  73. package/docs/ARCHITECTURE.en.md +2 -2
  74. package/docs/ARCHITECTURE.md +11 -2
  75. package/docs/CLI_REFERENCE.en.md +6 -4
  76. package/docs/CLI_REFERENCE.md +1 -1
  77. package/docs/CONTRIBUTING.en.md +1 -1
  78. package/docs/CONTRIBUTING.md +2 -2
  79. package/docs/PERFORMANCE_AUDIT_REPORT.md +2 -2
  80. package/docs/TOOL_CATALOG.md +6 -2
  81. package/docs/research/agent_skill_training_analysis.md +1 -1
  82. package/package.json +1 -1
  83. package/plugin.json +1 -1
  84. package/scripts/generate_skill_examples.py +3 -0
  85. package/scripts/package_dist.py +3 -0
  86. package/skills_manifest.json +320 -55
  87. package/synapse.config.json +1 -1
  88. package/templates/ui/index.html +2 -2
  89. package/tools/.infer_baseline.json +3 -796
  90. package/tools/TOOL_CATALOG.json +63 -3
  91. package/tools/__init__.py +4 -1
  92. package/tools/agent_canary.py +3 -0
  93. package/tools/analyze_project.py +3 -0
  94. package/tools/api_drift_sentinel.py +3 -0
  95. package/tools/api_fuzzer.py +182 -118
  96. package/tools/ast_cache.py +4 -2
  97. package/tools/author_integrity.py +174 -12
  98. package/tools/auto_heal.py +7 -2
  99. package/tools/autogen_qa_broker.py +14 -15
  100. package/tools/benchmark_swarm_context.py +119 -18
  101. package/tools/break_ui_generator.py +233 -0
  102. package/tools/browser_helpers.js +2 -2
  103. package/tools/bug_reporter.py +3 -0
  104. package/tools/build_consolidated_report.py +3 -0
  105. package/tools/bump_version.py +4 -1
  106. package/tools/cache_resolver.py +7 -3
  107. package/tools/check_env.py +3 -0
  108. package/tools/check_version_sync.py +21 -50
  109. package/tools/ci_healing_hook.py +3 -0
  110. package/tools/cli.py +116 -22
  111. package/tools/config_decoupler.py +3 -0
  112. package/tools/core/__init__.py +3 -0
  113. package/tools/core/bm25_retriever.py +218 -0
  114. package/tools/core/file_lock.py +23 -14
  115. package/tools/core/i18n.py +13 -11
  116. package/tools/core/memory_bus.py +6 -3
  117. package/tools/core/process_supervisor.py +28 -18
  118. package/tools/core/provider_usage_adapter.py +317 -0
  119. package/tools/core/token_estimator.py +83 -18
  120. package/tools/count_tokens.py +16 -7
  121. package/tools/coverage_reporter.py +245 -0
  122. package/tools/create_mock_docx.py +3 -0
  123. package/tools/dashboard_generator.py +17 -15
  124. package/tools/db_sandbox.py +150 -5
  125. package/tools/debt_harvester.py +2 -2
  126. package/tools/diagram_architect.py +3 -0
  127. package/tools/distill_log.py +22 -2
  128. package/tools/distill_skill.py +191 -0
  129. package/tools/e2e_flow_prober.py +3 -0
  130. package/tools/export_postman_collection.py +3 -0
  131. package/tools/flaky_detector.py +3 -0
  132. package/tools/fsm_enforcer.py +2 -2
  133. package/tools/fuzz_payloads.py +3 -0
  134. package/tools/generate_allure_report.py +3 -0
  135. package/tools/generate_api_matrix.py +3 -0
  136. package/tools/generate_jmx_plan.py +3 -0
  137. package/tools/generate_tc_from_story.py +3 -0
  138. package/tools/generate_test_reports.py +3 -0
  139. package/tools/git_pre_commit_guard.py +25 -3
  140. package/tools/git_worktree_manager.py +3 -0
  141. package/tools/heal/__init__.py +3 -0
  142. package/tools/heal_pr_automator.py +3 -0
  143. package/tools/heuristic_locator_matcher.py +3 -0
  144. package/tools/hub_publisher.py +3 -3
  145. package/tools/humanize_linter.py +3 -0
  146. package/tools/infer_linter.py +19 -9
  147. package/tools/init_config.py +6 -9
  148. package/tools/jtl_analyzer.py +3 -0
  149. package/tools/lint/__init__.py +3 -0
  150. package/tools/lint_ai_docs.py +3 -0
  151. package/tools/lookup_tc.py +3 -0
  152. package/tools/lookup_xpath.py +3 -0
  153. package/tools/matrix_sharder.py +3 -0
  154. package/tools/mcp/__init__.py +3 -0
  155. package/tools/mcp_docx_server.py +1 -1
  156. package/tools/mcp_excel_server.py +4 -1
  157. package/tools/mcp_server.py +78 -15
  158. package/tools/md_to_xlsx.py +3 -0
  159. package/tools/mechanical_ui_gate.py +3 -0
  160. package/tools/micro_mutator.py +93 -19
  161. package/tools/network_mock_shield.py +3 -0
  162. package/tools/newman_analyzer.py +3 -0
  163. package/tools/omni_emitter.py +3 -0
  164. package/tools/omni_parser.py +3 -0
  165. package/tools/omni_transpiler.py +3 -0
  166. package/tools/output_formatter.py +3 -0
  167. package/tools/package_release.py +6 -6
  168. package/tools/pairwise_generator.py +3 -0
  169. package/tools/pentest_scope_guard.py +401 -58
  170. package/tools/perf/__init__.py +3 -0
  171. package/tools/perf/benchmark_perf_runner.py +42 -0
  172. package/tools/pinpoint_failure.py +3 -0
  173. package/tools/project_state.py +3 -0
  174. package/tools/repo_map.py +3 -0
  175. package/tools/report/__init__.py +3 -0
  176. package/tools/rules_router.py +426 -34
  177. package/tools/runaway_stopper.py +3 -0
  178. package/tools/safety_firewall.py +3 -0
  179. package/tools/security_scanner.py +80 -0
  180. package/tools/senior_code_review.py +14 -0
  181. package/tools/setup_project.py +9 -4
  182. package/tools/skill_canonical_digest.py +244 -0
  183. package/tools/skill_collision_guard.py +2 -2
  184. package/tools/skill_profiles.py +77 -7
  185. package/tools/skillspector.py +2 -1
  186. package/tools/slide_deck_exporter.py +477 -0
  187. package/tools/smart_visual_masker.py +3 -0
  188. package/tools/sync_skills_manifest.py +166 -0
  189. package/tools/task_memory_manager.py +260 -0
  190. package/tools/telemetry_correlator.py +3 -0
  191. package/tools/template_excel_exporter.py +2 -2
  192. package/tools/test_impact.py +3 -0
  193. package/tools/trace_data_flow.py +3 -0
  194. package/tools/traffic_session_converter.py +3 -0
  195. package/tools/ui_server.py +2 -2
  196. package/tools/universal_ir.py +3 -0
  197. package/tools/update_sentinel.py +15 -9
  198. package/tools/validate_groovy_scripts.py +3 -0
  199. package/tools/validate_host_interop.py +485 -0
  200. package/tools/validate_skills_schema.py +282 -0
  201. package/tools/verify_all.py +600 -63
  202. package/tools/visual_diff_canvas.py +3 -0
  203. package/tools/visual_som_helper.py +3 -0
  204. package/tools/watch_mode.py +4 -4
  205. package/tools/wcag_audit.py +3 -0
  206. package/tools/welcome_page.py +2 -2
@@ -21,9 +21,12 @@ from __future__ import annotations
21
21
 
22
22
  import argparse
23
23
  import json
24
+ import logging
24
25
  import os
25
26
  import sys
26
- from typing import Any, Dict, List, Set, Tuple
27
+
28
+ logger = logging.getLogger("rules_router")
29
+ from typing import Any, Dict, List, Optional, Set, Tuple
27
30
 
28
31
  if hasattr(sys.stdout, "reconfigure"):
29
32
  try:
@@ -166,6 +169,174 @@ DEFAULT_CORE_SKILLS = [
166
169
  ]
167
170
 
168
171
 
172
+ class TokenCapExceededError(ValueError):
173
+ """
174
+ Raised when the aggregated token payload exceeds the configured token_cap
175
+ and cannot be satisfied even after priority pruning of lower-priority skills.
176
+ """
177
+ def __init__(
178
+ self,
179
+ message: str,
180
+ required_tokens: int = 0,
181
+ token_cap: int = 0,
182
+ item_type: str = "payload",
183
+ ):
184
+ super().__init__(message)
185
+ self.required_tokens = required_tokens
186
+ self.token_cap = token_cap
187
+ self.item_type = item_type
188
+
189
+
190
+ TASK_TYPE_CONFIGS: Dict[str, Dict[str, Any]] = {
191
+ "locator": {
192
+ "rules": ["mandatory-playwright-live.md", "systematic-debugging.md"],
193
+ "primary_skills": ["clean-pom-crafter"],
194
+ "secondary_skills": ["self-healing-locator"],
195
+ "default_token_cap": 6000,
196
+ },
197
+ "triage": {
198
+ "rules": ["systematic-debugging.md"],
199
+ "primary_skills": ["failure-autopsy-and-healing"],
200
+ "secondary_skills": ["systematic-debugging"],
201
+ "default_token_cap": 6000,
202
+ },
203
+ "api": {
204
+ "rules": ["systematic-debugging.md"],
205
+ "primary_skills": ["api-spec-to-e2e-matrix", "api-network-mocking-interception"],
206
+ "secondary_skills": ["consumer-driven-contract-testing"],
207
+ "default_token_cap": 6000,
208
+ },
209
+ "perf": {
210
+ "rules": ["performance_testing_rules.md"],
211
+ "primary_skills": ["backend-load-and-stress-patterns", "web-vitals-and-performance-profiler"],
212
+ "secondary_skills": ["lean-impact-scoreboard"],
213
+ "default_token_cap": 6000,
214
+ },
215
+ "security": {
216
+ "rules": ["security_testing_rules.md"],
217
+ "primary_skills": ["security-dast-sentinel", "skillspector-security-guard"],
218
+ "secondary_skills": ["wcag-audit-patterns"],
219
+ "default_token_cap": 6000,
220
+ },
221
+ }
222
+
223
+
224
+ def prune_payload_to_cap(
225
+ repo_root: str,
226
+ rules: List[str],
227
+ skills: List[str],
228
+ token_cap: Optional[int],
229
+ primary_skills: Optional[List[str]] = None,
230
+ mandatory_skills: Optional[List[str]] = None,
231
+ task_rules: Optional[List[str]] = None,
232
+ allow_partial: bool = False,
233
+ ) -> Tuple[List[str], List[str], List[str], Dict[str, Any]]:
234
+ """
235
+ Enforces token_cap against total_hydrated_tokens using priority-based pruning.
236
+
237
+ Priority Hierarchy:
238
+ CORE_BASE_RULES (Hard Floor) > Mandatory Skills > Task Rules > Non-Task Rules > Secondary Skills
239
+
240
+ Returns:
241
+ (final_rules, final_skills, pruned_skills, final_payload)
242
+ Raises:
243
+ TokenCapExceededError: When minimal mandatory floor exceeds token_cap (and allow_partial is False).
244
+ """
245
+ if token_cap is None:
246
+ payload = calculate_hydration_payload(repo_root, rules, skills)
247
+ return rules, skills, [], payload
248
+
249
+ if not isinstance(token_cap, int) or token_cap <= 0:
250
+ raise TokenCapExceededError(
251
+ f"Insufficient token_cap: {token_cap}. Must be a positive integer greater than 0.",
252
+ required_tokens=0,
253
+ token_cap=token_cap if isinstance(token_cap, int) else 0,
254
+ item_type="cap_validation",
255
+ )
256
+
257
+ # 1. Hard Floor Validation: CORE_BASE_RULES and mandatory_skills cannot be pruned
258
+ mand_list = list(mandatory_skills) if mandatory_skills is not None else []
259
+ floor_payload = calculate_hydration_payload(repo_root, sorted(CORE_BASE_RULES), mand_list)
260
+ hard_floor_tokens = floor_payload["total_hydrated_tokens"]
261
+
262
+ if token_cap < hard_floor_tokens:
263
+ if not allow_partial:
264
+ item_type = "mandatory_skills" if mand_list else "core_rules"
265
+ detail = f"with mandatory skills {mand_list}" if mand_list else "core rules"
266
+ raise TokenCapExceededError(
267
+ f"Insufficient token_cap: {token_cap}. Mandatory floor ({detail}) requires {hard_floor_tokens} tokens, which exceeds token_cap ({token_cap}).",
268
+ required_tokens=hard_floor_tokens,
269
+ token_cap=token_cap,
270
+ item_type=item_type,
271
+ )
272
+
273
+ current_rules = list(rules)
274
+ current_skills = list(skills)
275
+ pruned_skills: List[str] = []
276
+
277
+ current_payload = calculate_hydration_payload(repo_root, current_rules, current_skills)
278
+ if current_payload["total_hydrated_tokens"] <= token_cap:
279
+ return current_rules, current_skills, pruned_skills, current_payload
280
+
281
+ # Determine primary set for priority ordering
282
+ if mand_list:
283
+ primary_set = set(mand_list)
284
+ elif primary_skills is not None:
285
+ primary_set = set(primary_skills)
286
+ else:
287
+ primary_set = set(skills[:1]) if skills else set()
288
+
289
+ # Step 1: Drop secondary skills first (down to 0 secondary skills) while total tokens > token_cap
290
+ while current_payload["total_hydrated_tokens"] > token_cap:
291
+ sec_skills = [s for s in current_skills if s not in primary_set]
292
+ if not sec_skills:
293
+ break
294
+ dropped = sec_skills[-1]
295
+ current_skills.remove(dropped)
296
+ pruned_skills.append(dropped)
297
+ current_payload = calculate_hydration_payload(repo_root, current_rules, current_skills)
298
+
299
+ # Step 2: If still exceeding cap, drop non-task non-core rules first, then task rules
300
+ if current_payload["total_hydrated_tokens"] > token_cap:
301
+ task_rule_set = set(task_rules) if task_rules is not None else set()
302
+ # Drop external/other stack rules before dropping task-specific rules
303
+ other_rules = [r for r in current_rules if r not in CORE_BASE_RULES and r not in task_rule_set]
304
+ while current_payload["total_hydrated_tokens"] > token_cap and len(other_rules) > 0:
305
+ dropped_rule = other_rules.pop()
306
+ current_rules.remove(dropped_rule)
307
+ current_payload = calculate_hydration_payload(repo_root, current_rules, current_skills)
308
+
309
+ # If still exceeding cap after dropping all other rules, drop task rules
310
+ if current_payload["total_hydrated_tokens"] > token_cap:
311
+ t_rules = [r for r in current_rules if r in task_rule_set and r not in CORE_BASE_RULES]
312
+ while current_payload["total_hydrated_tokens"] > token_cap and len(t_rules) > 0:
313
+ dropped_rule = t_rules.pop()
314
+ current_rules.remove(dropped_rule)
315
+ current_payload = calculate_hydration_payload(repo_root, current_rules, current_skills)
316
+
317
+ # 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
+ 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)
324
+
325
+ # Step 4: If still exceeding cap (e.g. when allow_partial=True), raise or return
326
+ if current_payload["total_hydrated_tokens"] > token_cap:
327
+ if not allow_partial:
328
+ required = current_payload["total_hydrated_tokens"]
329
+ raise TokenCapExceededError(
330
+ f"Aggregated payload requires {required} tokens, exceeding token_cap ({token_cap}) even after pruning all lower-priority components.",
331
+ required_tokens=required,
332
+ token_cap=token_cap,
333
+ item_type="payload",
334
+ )
335
+
336
+ return current_rules, current_skills, pruned_skills, current_payload
337
+
338
+
339
+
169
340
  def _find_repo_root() -> str:
170
341
  """Finds the root of Synapse-Hub repository."""
171
342
  curr = os.path.abspath(os.path.dirname(__file__))
@@ -225,7 +396,7 @@ def _scan_directory_markers(target_dir: str, prefix: str = "") -> Tuple[Dict[str
225
396
  detected["performance"].append(f"{prefix}package.json (perf)")
226
397
  confidence["performance"] = max(confidence["performance"], 0.90)
227
398
  except Exception as err:
228
- _ = err
399
+ logger.debug("Failed to inspect package.json: %s", err)
229
400
 
230
401
  # 2. Inspect Python requirements / pyproject / Pipfile
231
402
  for py_cfg_name in ("requirements.txt", "requirements-dev.txt", "pyproject.toml", "Pipfile", "setup.py"):
@@ -253,7 +424,8 @@ def _scan_directory_markers(target_dir: str, prefix: str = "") -> Tuple[Dict[str
253
424
  detected["security"].append(f"{prefix}{py_cfg_name} (security)")
254
425
  confidence["security"] = max(confidence["security"], 0.80)
255
426
  except Exception as err:
256
- _ = err
427
+ logger.debug("Failed to inspect configuration: %s", err)
428
+ continue
257
429
 
258
430
  # 3. Inspect JVM build markers (build.gradle, pom.xml)
259
431
  for jvm_cfg_name in ("build.gradle", "build.gradle.kts", "pom.xml"):
@@ -278,7 +450,8 @@ def _scan_directory_markers(target_dir: str, prefix: str = "") -> Tuple[Dict[str
278
450
  detected["performance"].append(f"{prefix}{jvm_cfg_name} (perf)")
279
451
  confidence["performance"] = max(confidence["performance"], 0.85)
280
452
  except Exception as err:
281
- _ = err
453
+ logger.debug("Failed to inspect configuration: %s", err)
454
+ continue
282
455
 
283
456
  # 4. Walk directory structure up to depth 2
284
457
  ignored = {".git", "node_modules", ".venv", "venv", "__pycache__", "dist", "build", "target", ".gradle"}
@@ -320,7 +493,8 @@ def _scan_directory_markers(target_dir: str, prefix: str = "") -> Tuple[Dict[str
320
493
  detected["selenium"].append(full_evidence_path)
321
494
  confidence["selenium"] = max(confidence["selenium"], 0.80)
322
495
  except Exception as err:
323
- _ = err
496
+ logger.debug("Failed to inspect file: %s", err)
497
+ continue
324
498
  else:
325
499
  detected["selenium"].append(full_evidence_path)
326
500
  confidence["selenium"] = max(confidence["selenium"], 0.95)
@@ -357,7 +531,8 @@ def _scan_directory_markers(target_dir: str, prefix: str = "") -> Tuple[Dict[str
357
531
  detected["selenium"].append(full_evidence_path)
358
532
  confidence["selenium"] = max(confidence["selenium"], 0.80)
359
533
  except Exception as err:
360
- _ = err
534
+ logger.debug("Failed to inspect python file: %s", err)
535
+ continue
361
536
 
362
537
  # Directory-level markers (Katalon Keywords/Profiles)
363
538
  for d in dirs:
@@ -389,7 +564,7 @@ def detect_workspace_stacks(workspace_dir: str) -> Dict[str, Any]:
389
564
  if "include" in f.read().lower():
390
565
  is_monorepo = True
391
566
  except Exception as err:
392
- _ = err
567
+ logger.debug("Failed to read settings.gradle: %s", err)
393
568
 
394
569
  if is_monorepo:
395
570
  # Traverse subpackages in packages/, apps/, services/, modules/
@@ -406,7 +581,7 @@ def detect_workspace_stacks(workspace_dir: str) -> Dict[str, Any]:
406
581
  detected[stack].extend(evs)
407
582
  confidence[stack] = max(confidence[stack], sub_conf[stack])
408
583
  except OSError as err:
409
- _ = err
584
+ logger.debug("Failed to inspect subpackage: %s", err)
410
585
 
411
586
  # Filter active stacks where confidence >= 0.50
412
587
  active_stacks = [s for s, evs in detected.items() if evs and confidence[s] >= 0.50]
@@ -419,10 +594,16 @@ def detect_workspace_stacks(workspace_dir: str) -> Dict[str, Any]:
419
594
  }
420
595
 
421
596
 
422
- def route_rules(workspace_dir: str = ".") -> Dict[str, Any]:
597
+ def route_rules(
598
+ workspace_dir: str = ".",
599
+ minimal: bool = False,
600
+ task_type: Optional[str] = None,
601
+ token_cap: Optional[int] = None,
602
+ allow_partial: bool = False,
603
+ ) -> Dict[str, Any]:
423
604
  """
424
605
  Determines minimal rules and skills for target workspace, with dual-tier token hydration
425
- accounting and strict truth-anchoring for unknown stacks.
606
+ accounting, priority pruning under token_cap, and strict truth-anchoring for unknown stacks.
426
607
  """
427
608
  repo_root = _find_repo_root()
428
609
  stack_info = detect_workspace_stacks(workspace_dir)
@@ -430,25 +611,63 @@ def route_rules(workspace_dir: str = ".") -> Dict[str, Any]:
430
611
 
431
612
  is_unknown_stack = len(active_stacks) == 0
432
613
 
614
+ if task_type is not None:
615
+ if task_type not in TASK_TYPE_CONFIGS:
616
+ raise ValueError(f"Unknown task_type: '{task_type}'. Valid choices: {list(TASK_TYPE_CONFIGS.keys())}")
617
+
618
+ # Determine effective task_mode and cap
619
+ is_minimal_mode = minimal or (task_type is not None)
620
+ effective_cap = token_cap
621
+ if effective_cap is None and is_minimal_mode:
622
+ if task_type is not None:
623
+ effective_cap = TASK_TYPE_CONFIGS[task_type]["default_token_cap"]
624
+ else:
625
+ effective_cap = 6000
626
+
433
627
  # Compile rules
434
628
  rules_set: Set[str] = set(CORE_BASE_RULES)
435
629
  for stack in active_stacks:
436
630
  for r in STACK_RULE_MAPPINGS.get(stack, []):
437
631
  rules_set.add(r)
438
632
 
439
- # Compile skills
440
- skills_set: Set[str] = set(DEFAULT_CORE_SKILLS)
441
- for stack in active_stacks:
442
- for s in STACK_SKILL_MAPPINGS.get(stack, []):
443
- skills_set.add(s)
633
+ # Compile candidate skills in priority order
634
+ ordered_skills: List[str] = []
635
+ mandatory_skills_list: List[str] = []
636
+ task_rules_list: List[str] = []
444
637
 
445
- # Resolve rules directory
446
- rules_dir = os.path.join(repo_root, ".agents", "rules")
447
- valid_rules = sorted(rules_set)
448
- valid_skills = sorted(skills_set)
638
+ if task_type is not None:
639
+ cfg = TASK_TYPE_CONFIGS[task_type]
640
+ task_rules_list = list(cfg.get("rules", []))
641
+ for r in task_rules_list:
642
+ rules_set.add(r)
643
+
644
+ mandatory_skills_list = list(cfg.get("primary_skills", []))
645
+ # Primary skills first, then secondary skills
646
+ for s in mandatory_skills_list:
647
+ if s not in ordered_skills:
648
+ ordered_skills.append(s)
649
+ for s in cfg.get("secondary_skills", []):
650
+ if s not in ordered_skills:
651
+ ordered_skills.append(s)
652
+ else:
653
+ # Stack-specific skills first, then default core skills
654
+ for stack in active_stacks:
655
+ for s in STACK_SKILL_MAPPINGS.get(stack, []):
656
+ if s not in ordered_skills:
657
+ ordered_skills.append(s)
658
+ for s in DEFAULT_CORE_SKILLS:
659
+ if s not in ordered_skills:
660
+ ordered_skills.append(s)
449
661
 
450
- # Calculate dual-tier hydration payloads
451
- routed_payload = calculate_hydration_payload(repo_root, valid_rules, valid_skills)
662
+ if minimal:
663
+ ordered_skills = ordered_skills[:2]
664
+
665
+ candidate_rules = sorted(rules_set)
666
+
667
+ # Hard Floor measurement: CORE_BASE_RULES + mandatory skills for specific task
668
+ floor_payload = calculate_hydration_payload(repo_root, sorted(CORE_BASE_RULES), mandatory_skills_list)
669
+ hard_floor_tokens = floor_payload["total_hydrated_tokens"]
670
+ core_floor_tokens = floor_payload["rule_tokens"]
452
671
 
453
672
  # Calculate full unrouted baseline dynamically by enumerating 100% of skills & rules
454
673
  baseline = get_full_unrouted_baseline(repo_root)
@@ -457,49 +676,125 @@ def route_rules(workspace_dir: str = ".") -> Dict[str, Any]:
457
676
  unrouted_full_bytes = baseline["total_full_bytes"]
458
677
  estimator_info = baseline.get("estimator_info", get_estimator_info())
459
678
 
460
- # If workspace is unclassified (no stack detected), report honest fallback metrics
461
- if is_unknown_stack:
679
+ measurement_kind = "synthetic" if estimator_info.get("is_exact") else "static_estimate"
680
+ tokenizer_name = estimator_info.get("encoding", "cl100k_base")
681
+
682
+ # If workspace is unclassified (no stack detected) and no task_type was specified, report honest fallback metrics
683
+ if is_unknown_stack and task_type is None:
684
+ # Validate cap against core base rules even on unclassified workspaces
685
+ final_rules, final_skills, pruned_skills, routed_payload = prune_payload_to_cap(
686
+ repo_root=repo_root,
687
+ rules=sorted(CORE_BASE_RULES),
688
+ skills=[],
689
+ token_cap=effective_cap,
690
+ mandatory_skills=[],
691
+ allow_partial=allow_partial,
692
+ )
693
+
462
694
  return {
463
695
  "workspace": os.path.abspath(workspace_dir),
696
+ "task_mode": "minimal" if is_minimal_mode else "full",
697
+ "token_cap": effective_cap,
698
+ "token_cap_enforced": effective_cap is not None,
699
+ "pruned_skills": pruned_skills,
700
+ "task_type": task_type,
464
701
  "status": "UNCLASSIFIED_WORKSPACE",
465
702
  "detected_stacks": ["unknown"],
466
703
  "classification": "UNCLASSIFIED_WORKSPACE (Fallback Core Base Rules)",
467
704
  "confidence_score": 0.0,
468
705
  "evidence": {},
469
- "recommended_rules": valid_rules,
470
- "recommended_skills": valid_skills,
706
+ "recommended_rules": final_rules,
707
+ "recommended_skills": final_skills,
471
708
  "estimator_info": estimator_info,
472
709
  "token_metrics": {
473
710
  "unrouted_baseline_tokens": unrouted_summary_baseline,
474
711
  "routed_tokens": routed_payload["total_summary_tokens"],
712
+ "catalog_summary_tokens": routed_payload["total_summary_tokens"],
713
+ "estimated_payload_tokens": routed_payload["total_hydrated_tokens"],
714
+ "estimated_hydration_tokens": routed_payload["total_hydrated_tokens"],
715
+ "static_estimated_tokens": routed_payload["total_hydrated_tokens"],
716
+ "synthetic_tokens": None,
717
+ "provider_reported_input_tokens": None,
718
+ "provider_reported_output_tokens": None,
719
+ "provider_cached_tokens": None,
720
+ "token_cap": effective_cap,
721
+ "provider_reported_tokens": None,
722
+ "measurement_kind": measurement_kind,
723
+ "tokenizer_or_model": tokenizer_name,
724
+ "measurement_source": "offline_token_estimator",
725
+ "context_scope": "hydrated_documentation_and_rules",
726
+ "avoided_disk_bytes": 0,
475
727
  "tokens_saved": 0,
476
728
  "reduction_percentage": 0.0,
477
- "note": "Stack unclassified; routed to core base profile without claiming workload-specific token reduction.",
729
+ "core_rule_tokens": core_floor_tokens,
730
+ "hard_floor_tokens": hard_floor_tokens,
731
+ "pruned_items_count": len(pruned_skills),
732
+ "cap_excludes_system_prompt_and_wrapper": True,
733
+ "note": "Stack unclassified; routed to core base profile without claiming workload-specific token reduction. Cap applies to hydrated documentation, not host context.",
478
734
  },
479
735
  "hydration_contracts": {
480
736
  "catalog_summary": {
481
737
  "baseline_tokens": unrouted_summary_baseline,
482
738
  "routed_tokens": routed_payload["total_summary_tokens"],
739
+ "catalog_summary_tokens": routed_payload["total_summary_tokens"],
740
+ "estimated_payload_tokens": routed_payload["total_summary_tokens"],
741
+ "measurement_kind": measurement_kind,
742
+ "tokenizer_or_model": tokenizer_name,
743
+ "measurement_source": "offline_token_estimator",
483
744
  "tokens_saved": 0,
484
745
  "reduction_pct": 0.0,
746
+ "scope": "Skill registry metadata for Front-Door Orchestrator",
485
747
  },
486
748
  "full_hydration": {
487
749
  "baseline_tokens": unrouted_full_baseline,
488
750
  "routed_tokens": routed_payload["total_hydrated_tokens"],
751
+ "static_estimated_tokens": routed_payload["total_hydrated_tokens"],
752
+ "estimated_hydration_tokens": routed_payload["total_hydrated_tokens"],
753
+ "estimated_payload_tokens": routed_payload["total_hydrated_tokens"],
754
+ "provider_reported_input_tokens": None,
755
+ "provider_reported_output_tokens": None,
756
+ "provider_cached_tokens": None,
757
+ "token_cap": effective_cap,
758
+ "cap_excludes_system_prompt_and_wrapper": True,
759
+ "provider_reported_tokens": None,
760
+ "measurement_kind": measurement_kind,
761
+ "tokenizer_or_model": tokenizer_name,
762
+ "measurement_source": "offline_token_estimator",
489
763
  "tokens_saved": 0,
490
764
  "reduction_pct": 0.0,
765
+ "scope": "Complete SKILL.md bodies injected into Specialized Subagents",
491
766
  },
492
767
  "retrieval_footprint": {
493
768
  "full_catalog_bytes": unrouted_full_bytes,
494
769
  "routed_catalog_bytes": routed_payload["total_hydrated_bytes"],
495
770
  "avoided_bytes": 0,
771
+ "avoided_disk_bytes": 0,
496
772
  "io_reduction_pct": 0.0,
773
+ "measurement_kind": "synthetic",
774
+ "measurement_source": "disk_file_stat",
497
775
  "label": "Disk Read I/O Footprint Avoided (Disk File Size, Not Context Tokens)",
498
776
  },
499
777
  },
500
778
  }
501
779
 
502
- # Classified stacks: compute honest savings for both tiers
780
+ # Classified stacks or task-directed profiles: priority pruning & token cap enforcement
781
+ primary_skills_list: Optional[List[str]] = None
782
+ if task_type is not None:
783
+ primary_skills_list = mandatory_skills_list
784
+ elif ordered_skills:
785
+ primary_skills_list = ordered_skills[:1]
786
+
787
+ final_rules, final_skills, pruned_skills, routed_payload = prune_payload_to_cap(
788
+ repo_root=repo_root,
789
+ rules=candidate_rules,
790
+ skills=ordered_skills,
791
+ token_cap=effective_cap,
792
+ primary_skills=primary_skills_list,
793
+ mandatory_skills=mandatory_skills_list,
794
+ task_rules=task_rules_list,
795
+ allow_partial=allow_partial,
796
+ )
797
+
503
798
  summary_saved = max(0, unrouted_summary_baseline - routed_payload["total_summary_tokens"])
504
799
  summary_pct = round((summary_saved / max(1, unrouted_summary_baseline)) * 100, 1)
505
800
 
@@ -509,28 +804,83 @@ def route_rules(workspace_dir: str = ".") -> Dict[str, Any]:
509
804
  avoided_io_bytes = max(0, unrouted_full_bytes - routed_payload["total_hydrated_bytes"])
510
805
  io_reduction_pct = round((avoided_io_bytes / max(1, unrouted_full_bytes)) * 100, 1)
511
806
 
512
- avg_conf = sum(stack_info["confidence"].values()) / max(1, len(stack_info["confidence"]))
807
+ partial_reason = None
808
+ if effective_cap is not None and routed_payload["total_hydrated_tokens"] > effective_cap:
809
+ avg_conf = 0.0
810
+ status_label = "PARTIAL_CAP_EXCEEDED"
811
+ class_label = f"PARTIAL_CAP_EXCEEDED (Mandatory floor {hard_floor_tokens} exceeds cap {effective_cap})"
812
+ partial_reason = (
813
+ f"Token cap ({effective_cap}) is below mandatory floor ({hard_floor_tokens}) "
814
+ f"for task '{task_type}'."
815
+ )
816
+ elif active_stacks:
817
+ avg_conf = sum(stack_info["confidence"].values()) / max(1, len(stack_info["confidence"]))
818
+ status_label = "CLASSIFIED"
819
+ class_label = f"CLASSIFIED ({', '.join(active_stacks)})"
820
+ else:
821
+ avg_conf = 0.0
822
+ status_label = "UNCLASSIFIED_WORKSPACE"
823
+ class_label = f"UNCLASSIFIED_WORKSPACE (Task: {task_type})"
824
+
825
+ routing_note = (
826
+ f"Workspace stack unclassified; task-specific profile for '{task_type}' retained and hydrated under token cap. "
827
+ "Cap applies strictly to router-managed rules and hydrated documentation; it does not include host system prompt or provider request wrappers."
828
+ if is_unknown_stack
829
+ else "Stack classified; rule and skill subsets hydrated under token cap. "
830
+ "Cap applies strictly to router-managed rules and hydrated documentation; it does not include host system prompt or provider request wrappers."
831
+ )
513
832
 
514
833
  return {
515
834
  "workspace": os.path.abspath(workspace_dir),
516
- "status": "CLASSIFIED",
517
- "detected_stacks": active_stacks,
518
- "classification": f"CLASSIFIED ({', '.join(active_stacks)})",
835
+ "task_mode": "minimal" if is_minimal_mode else "full",
836
+ "token_cap": effective_cap,
837
+ "token_cap_enforced": effective_cap is not None,
838
+ "pruned_skills": pruned_skills,
839
+ "task_type": task_type,
840
+ "status": status_label,
841
+ "detected_stacks": active_stacks if active_stacks else ["unknown"],
842
+ "classification": class_label,
519
843
  "confidence_score": round(avg_conf, 2),
520
844
  "evidence": stack_info["evidence"],
521
- "recommended_rules": valid_rules,
522
- "recommended_skills": valid_skills,
845
+ "recommended_rules": final_rules,
846
+ "recommended_skills": final_skills,
523
847
  "estimator_info": estimator_info,
524
848
  "token_metrics": {
525
849
  "unrouted_baseline_tokens": unrouted_summary_baseline,
526
850
  "routed_tokens": routed_payload["total_summary_tokens"],
851
+ "catalog_summary_tokens": routed_payload["total_summary_tokens"],
852
+ "estimated_payload_tokens": routed_payload["total_hydrated_tokens"],
853
+ "estimated_hydration_tokens": routed_payload["total_hydrated_tokens"],
854
+ "static_estimated_tokens": routed_payload["total_hydrated_tokens"],
855
+ "synthetic_tokens": None,
856
+ "provider_reported_input_tokens": None,
857
+ "provider_reported_output_tokens": None,
858
+ "provider_cached_tokens": None,
859
+ "token_cap": effective_cap,
860
+ "provider_reported_tokens": None,
861
+ "measurement_kind": measurement_kind,
862
+ "tokenizer_or_model": tokenizer_name,
863
+ "measurement_source": "offline_token_estimator",
864
+ "context_scope": "hydrated_documentation_and_rules",
865
+ "avoided_disk_bytes": avoided_io_bytes,
527
866
  "tokens_saved": summary_saved,
528
867
  "reduction_percentage": summary_pct,
868
+ "core_rule_tokens": core_floor_tokens,
869
+ "hard_floor_tokens": hard_floor_tokens,
870
+ "pruned_items_count": len(pruned_skills),
871
+ "cap_excludes_system_prompt_and_wrapper": True,
872
+ **({"partial_reason": partial_reason} if partial_reason else {}),
873
+ "note": routing_note,
529
874
  },
530
875
  "hydration_contracts": {
531
876
  "catalog_summary": {
532
877
  "baseline_tokens": unrouted_summary_baseline,
533
878
  "routed_tokens": routed_payload["total_summary_tokens"],
879
+ "catalog_summary_tokens": routed_payload["total_summary_tokens"],
880
+ "estimated_payload_tokens": routed_payload["total_summary_tokens"],
881
+ "measurement_kind": measurement_kind,
882
+ "tokenizer_or_model": tokenizer_name,
883
+ "measurement_source": "offline_token_estimator",
534
884
  "tokens_saved": summary_saved,
535
885
  "reduction_pct": summary_pct,
536
886
  "scope": "Skill registry metadata for Front-Door Orchestrator",
@@ -538,6 +888,18 @@ def route_rules(workspace_dir: str = ".") -> Dict[str, Any]:
538
888
  "full_hydration": {
539
889
  "baseline_tokens": unrouted_full_baseline,
540
890
  "routed_tokens": routed_payload["total_hydrated_tokens"],
891
+ "static_estimated_tokens": routed_payload["total_hydrated_tokens"],
892
+ "estimated_hydration_tokens": routed_payload["total_hydrated_tokens"],
893
+ "estimated_payload_tokens": routed_payload["total_hydrated_tokens"],
894
+ "provider_reported_input_tokens": None,
895
+ "provider_reported_output_tokens": None,
896
+ "provider_cached_tokens": None,
897
+ "token_cap": effective_cap,
898
+ "cap_excludes_system_prompt_and_wrapper": True,
899
+ "provider_reported_tokens": None,
900
+ "measurement_kind": measurement_kind,
901
+ "tokenizer_or_model": tokenizer_name,
902
+ "measurement_source": "offline_token_estimator",
541
903
  "tokens_saved": hydrated_saved,
542
904
  "reduction_pct": hydrated_pct,
543
905
  "scope": "Complete SKILL.md bodies injected into Specialized Subagents",
@@ -546,7 +908,10 @@ def route_rules(workspace_dir: str = ".") -> Dict[str, Any]:
546
908
  "full_catalog_bytes": unrouted_full_bytes,
547
909
  "routed_catalog_bytes": routed_payload["total_hydrated_bytes"],
548
910
  "avoided_bytes": avoided_io_bytes,
911
+ "avoided_disk_bytes": avoided_io_bytes,
549
912
  "io_reduction_pct": io_reduction_pct,
913
+ "measurement_kind": "synthetic",
914
+ "measurement_source": "disk_file_stat",
550
915
  "label": "Disk Read I/O Footprint Avoided (Disk File Size, Not Context Tokens)",
551
916
  },
552
917
  },
@@ -620,9 +985,36 @@ def main():
620
985
  action="store_true",
621
986
  help="Print single-line summary of routed rules and tokens saved",
622
987
  )
988
+ parser.add_argument(
989
+ "--minimal",
990
+ action="store_true",
991
+ help="Enforce minimal mode payload <= 6,000 tokens",
992
+ )
993
+ parser.add_argument(
994
+ "--task-type",
995
+ choices=["locator", "triage", "api", "perf", "security"],
996
+ help="Target task intent profile",
997
+ )
998
+ parser.add_argument(
999
+ "--token-cap",
1000
+ type=int,
1001
+ default=None,
1002
+ help="Enforce custom token cap ceiling",
1003
+ )
1004
+ parser.add_argument(
1005
+ "--allow-partial",
1006
+ action="store_true",
1007
+ help="Permit partial routing status instead of raising TokenCapExceededError when cap < floor",
1008
+ )
623
1009
  args = parser.parse_args()
624
1010
 
625
- result = route_rules(args.workspace)
1011
+ result = route_rules(
1012
+ args.workspace,
1013
+ minimal=args.minimal,
1014
+ task_type=args.task_type,
1015
+ token_cap=args.token_cap,
1016
+ allow_partial=args.allow_partial,
1017
+ )
626
1018
 
627
1019
  if args.json:
628
1020
  print(format_routing_report(result, fmt="json"))
@@ -1,4 +1,7 @@
1
1
  #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: © 2026 Thế Vị (@TeeVee98) <https://github.com/TeeVee98/Synapse-Hub>
3
+ # SPDX-License-Identifier: MIT
4
+
2
5
  # -*- coding: utf-8 -*-
3
6
  """
4
7
  tools/runaway_stopper.py — Agent Runaway & Token Loop Sentinel
@@ -1,4 +1,7 @@
1
1
  #!/usr/bin/env python3
2
+ # SPDX-FileCopyrightText: © 2026 Thế Vị (@TeeVee98) <https://github.com/TeeVee98/Synapse-Hub>
3
+ # SPDX-License-Identifier: MIT
4
+
2
5
  """
3
6
  Enterprise Action Safety Firewall & Blast Radius Containment Engine
4
7
  --------------------------------------------------------------------