@teevee98/synapse-hub 4.1.4 → 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 (116) 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/e2e-testing-patterns/SKILL.md +6 -1
  6. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +6 -1
  7. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +6 -1
  8. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +6 -1
  9. package/.agents/skills/01-web-automation/mobile-appium-som/examples/BaseScreen.java +2 -2
  10. package/.agents/skills/01-web-automation/mobile-appium-som/examples/LoginScreen.java +2 -2
  11. package/.agents/skills/01-web-automation/mobile-appium-som/examples/TC_MobileLogin.java +2 -2
  12. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +7 -2
  13. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +6 -1
  14. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +6 -1
  15. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +6 -1
  16. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +6 -1
  17. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +6 -1
  18. package/.agents/skills/02-test-design/review-spec/SKILL.md +4 -1
  19. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +6 -1
  20. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +6 -1
  21. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +6 -1
  22. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +7 -2
  23. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +7 -2
  24. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +4 -1
  25. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +6 -1
  26. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +6 -1
  27. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +6 -1
  28. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +6 -1
  29. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +6 -1
  30. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +6 -1
  31. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +7 -2
  32. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +6 -1
  33. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +6 -1
  34. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +6 -1
  35. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +6 -1
  36. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +6 -1
  37. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +6 -1
  38. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +6 -1
  39. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +6 -1
  40. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +6 -1
  41. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +6 -1
  42. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +6 -1
  43. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +6 -1
  44. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +4 -1
  45. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +4 -1
  46. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +6 -1
  47. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +4 -1
  48. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +6 -1
  49. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +6 -1
  50. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +6 -1
  51. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +6 -1
  52. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +6 -1
  53. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +6 -1
  54. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +6 -1
  55. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +6 -1
  56. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +6 -1
  57. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +6 -1
  58. package/AGENTS.md +7 -1
  59. package/LICENSE +5 -5
  60. package/NOTICE +1 -1
  61. package/README.en.md +4 -4
  62. package/README.md +4 -4
  63. package/agentskills.json +1 -1
  64. package/docs/ARCHITECTURE.en.md +2 -2
  65. package/docs/ARCHITECTURE.md +11 -2
  66. package/docs/CLI_REFERENCE.en.md +6 -4
  67. package/docs/CLI_REFERENCE.md +1 -1
  68. package/docs/CONTRIBUTING.en.md +1 -1
  69. package/docs/CONTRIBUTING.md +2 -2
  70. package/docs/TOOL_CATALOG.md +6 -2
  71. package/docs/research/agent_skill_training_analysis.md +1 -1
  72. package/package.json +1 -1
  73. package/plugin.json +1 -1
  74. package/skills_manifest.json +320 -55
  75. package/synapse.config.json +1 -1
  76. package/templates/ui/index.html +2 -2
  77. package/tools/TOOL_CATALOG.json +63 -3
  78. package/tools/__init__.py +1 -1
  79. package/tools/api_fuzzer.py +179 -118
  80. package/tools/author_integrity.py +121 -11
  81. package/tools/benchmark_swarm_context.py +119 -18
  82. package/tools/break_ui_generator.py +233 -0
  83. package/tools/browser_helpers.js +2 -2
  84. package/tools/check_version_sync.py +18 -50
  85. package/tools/cli.py +109 -18
  86. package/tools/core/bm25_retriever.py +218 -0
  87. package/tools/core/i18n.py +4 -4
  88. package/tools/core/provider_usage_adapter.py +317 -0
  89. package/tools/core/token_estimator.py +42 -14
  90. package/tools/count_tokens.py +5 -0
  91. package/tools/coverage_reporter.py +245 -0
  92. package/tools/dashboard_generator.py +6 -6
  93. package/tools/db_sandbox.py +146 -4
  94. package/tools/distill_skill.py +191 -0
  95. package/tools/git_pre_commit_guard.py +12 -0
  96. package/tools/humanize_linter.py +3 -0
  97. package/tools/mcp_docx_server.py +1 -1
  98. package/tools/mcp_excel_server.py +1 -1
  99. package/tools/mcp_server.py +75 -15
  100. package/tools/micro_mutator.py +84 -14
  101. package/tools/pentest_scope_guard.py +399 -56
  102. package/tools/perf/benchmark_perf_runner.py +42 -0
  103. package/tools/rules_router.py +401 -41
  104. package/tools/security_scanner.py +80 -0
  105. package/tools/senior_code_review.py +14 -0
  106. package/tools/skill_canonical_digest.py +244 -0
  107. package/tools/skill_profiles.py +77 -7
  108. package/tools/slide_deck_exporter.py +477 -0
  109. package/tools/sync_skills_manifest.py +166 -0
  110. package/tools/task_memory_manager.py +260 -0
  111. package/tools/ui_server.py +1 -1
  112. package/tools/update_sentinel.py +3 -3
  113. package/tools/validate_host_interop.py +485 -0
  114. package/tools/validate_skills_schema.py +282 -0
  115. package/tools/verify_all.py +572 -42
  116. package/tools/welcome_page.py +2 -2
@@ -169,6 +169,174 @@ DEFAULT_CORE_SKILLS = [
169
169
  ]
170
170
 
171
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
+
172
340
  def _find_repo_root() -> str:
173
341
  """Finds the root of Synapse-Hub repository."""
174
342
  curr = os.path.abspath(os.path.dirname(__file__))
@@ -426,10 +594,16 @@ def detect_workspace_stacks(workspace_dir: str) -> Dict[str, Any]:
426
594
  }
427
595
 
428
596
 
429
- def route_rules(workspace_dir: str = ".", minimal: bool = False, task_type: Optional[str] = None) -> 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]:
430
604
  """
431
605
  Determines minimal rules and skills for target workspace, with dual-tier token hydration
432
- accounting and strict truth-anchoring for unknown stacks.
606
+ accounting, priority pruning under token_cap, and strict truth-anchoring for unknown stacks.
433
607
  """
434
608
  repo_root = _find_repo_root()
435
609
  stack_info = detect_workspace_stacks(workspace_dir)
@@ -437,34 +611,63 @@ def route_rules(workspace_dir: str = ".", minimal: bool = False, task_type: Opti
437
611
 
438
612
  is_unknown_stack = len(active_stacks) == 0
439
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
+
440
627
  # Compile rules
441
628
  rules_set: Set[str] = set(CORE_BASE_RULES)
442
629
  for stack in active_stacks:
443
630
  for r in STACK_RULE_MAPPINGS.get(stack, []):
444
631
  rules_set.add(r)
445
632
 
446
- # Compile skills
447
- skills_set: Set[str] = set(DEFAULT_CORE_SKILLS)
448
- for stack in active_stacks:
449
- for s in STACK_SKILL_MAPPINGS.get(stack, []):
450
- skills_set.add(s)
451
-
452
- if task_type == "locator":
453
- minimal = True
454
- skills_set = {"clean-pom-crafter", "self-healing-locator"}
455
- elif task_type == "triage":
456
- minimal = True
457
- skills_set = {"failure-autopsy-and-healing", "systematic-debugging"}
458
- elif minimal:
459
- skills_set = set(sorted(skills_set)[:1])
460
-
461
- # Resolve rules directory
462
- rules_dir = os.path.join(repo_root, ".agents", "rules")
463
- valid_rules = sorted(rules_set)
464
- valid_skills = sorted(skills_set)
465
-
466
- # Calculate dual-tier hydration payloads
467
- routed_payload = calculate_hydration_payload(repo_root, valid_rules, valid_skills)
633
+ # Compile candidate skills in priority order
634
+ ordered_skills: List[str] = []
635
+ mandatory_skills_list: List[str] = []
636
+ task_rules_list: List[str] = []
637
+
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)
661
+
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"]
468
671
 
469
672
  # Calculate full unrouted baseline dynamically by enumerating 100% of skills & rules
470
673
  baseline = get_full_unrouted_baseline(repo_root)
@@ -473,52 +676,125 @@ def route_rules(workspace_dir: str = ".", minimal: bool = False, task_type: Opti
473
676
  unrouted_full_bytes = baseline["total_full_bytes"]
474
677
  estimator_info = baseline.get("estimator_info", get_estimator_info())
475
678
 
476
- # If workspace is unclassified (no stack detected), report honest fallback metrics
477
- 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
+
478
694
  return {
479
695
  "workspace": os.path.abspath(workspace_dir),
480
- "task_mode": "minimal" if (minimal or task_type) else "full",
481
- "token_cap": 6000 if (minimal or task_type) else None,
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,
482
700
  "task_type": task_type,
483
701
  "status": "UNCLASSIFIED_WORKSPACE",
484
702
  "detected_stacks": ["unknown"],
485
703
  "classification": "UNCLASSIFIED_WORKSPACE (Fallback Core Base Rules)",
486
704
  "confidence_score": 0.0,
487
705
  "evidence": {},
488
- "recommended_rules": valid_rules,
489
- "recommended_skills": valid_skills,
706
+ "recommended_rules": final_rules,
707
+ "recommended_skills": final_skills,
490
708
  "estimator_info": estimator_info,
491
709
  "token_metrics": {
492
710
  "unrouted_baseline_tokens": unrouted_summary_baseline,
493
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,
494
727
  "tokens_saved": 0,
495
728
  "reduction_percentage": 0.0,
496
- "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.",
497
734
  },
498
735
  "hydration_contracts": {
499
736
  "catalog_summary": {
500
737
  "baseline_tokens": unrouted_summary_baseline,
501
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",
502
744
  "tokens_saved": 0,
503
745
  "reduction_pct": 0.0,
746
+ "scope": "Skill registry metadata for Front-Door Orchestrator",
504
747
  },
505
748
  "full_hydration": {
506
749
  "baseline_tokens": unrouted_full_baseline,
507
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",
508
763
  "tokens_saved": 0,
509
764
  "reduction_pct": 0.0,
765
+ "scope": "Complete SKILL.md bodies injected into Specialized Subagents",
510
766
  },
511
767
  "retrieval_footprint": {
512
768
  "full_catalog_bytes": unrouted_full_bytes,
513
769
  "routed_catalog_bytes": routed_payload["total_hydrated_bytes"],
514
770
  "avoided_bytes": 0,
771
+ "avoided_disk_bytes": 0,
515
772
  "io_reduction_pct": 0.0,
773
+ "measurement_kind": "synthetic",
774
+ "measurement_source": "disk_file_stat",
516
775
  "label": "Disk Read I/O Footprint Avoided (Disk File Size, Not Context Tokens)",
517
776
  },
518
777
  },
519
778
  }
520
779
 
521
- # 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
+
522
798
  summary_saved = max(0, unrouted_summary_baseline - routed_payload["total_summary_tokens"])
523
799
  summary_pct = round((summary_saved / max(1, unrouted_summary_baseline)) * 100, 1)
524
800
 
@@ -528,31 +804,83 @@ def route_rules(workspace_dir: str = ".", minimal: bool = False, task_type: Opti
528
804
  avoided_io_bytes = max(0, unrouted_full_bytes - routed_payload["total_hydrated_bytes"])
529
805
  io_reduction_pct = round((avoided_io_bytes / max(1, unrouted_full_bytes)) * 100, 1)
530
806
 
531
- 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
+ )
532
832
 
533
833
  return {
534
834
  "workspace": os.path.abspath(workspace_dir),
535
- "task_mode": "minimal" if (minimal or task_type) else "full",
536
- "token_cap": 6000 if (minimal or task_type) else None,
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,
537
839
  "task_type": task_type,
538
- "status": "CLASSIFIED",
539
- "detected_stacks": active_stacks,
540
- "classification": f"CLASSIFIED ({', '.join(active_stacks)})",
840
+ "status": status_label,
841
+ "detected_stacks": active_stacks if active_stacks else ["unknown"],
842
+ "classification": class_label,
541
843
  "confidence_score": round(avg_conf, 2),
542
844
  "evidence": stack_info["evidence"],
543
- "recommended_rules": valid_rules,
544
- "recommended_skills": valid_skills,
845
+ "recommended_rules": final_rules,
846
+ "recommended_skills": final_skills,
545
847
  "estimator_info": estimator_info,
546
848
  "token_metrics": {
547
849
  "unrouted_baseline_tokens": unrouted_summary_baseline,
548
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,
549
866
  "tokens_saved": summary_saved,
550
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,
551
874
  },
552
875
  "hydration_contracts": {
553
876
  "catalog_summary": {
554
877
  "baseline_tokens": unrouted_summary_baseline,
555
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",
556
884
  "tokens_saved": summary_saved,
557
885
  "reduction_pct": summary_pct,
558
886
  "scope": "Skill registry metadata for Front-Door Orchestrator",
@@ -560,6 +888,18 @@ def route_rules(workspace_dir: str = ".", minimal: bool = False, task_type: Opti
560
888
  "full_hydration": {
561
889
  "baseline_tokens": unrouted_full_baseline,
562
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",
563
903
  "tokens_saved": hydrated_saved,
564
904
  "reduction_pct": hydrated_pct,
565
905
  "scope": "Complete SKILL.md bodies injected into Specialized Subagents",
@@ -568,7 +908,10 @@ def route_rules(workspace_dir: str = ".", minimal: bool = False, task_type: Opti
568
908
  "full_catalog_bytes": unrouted_full_bytes,
569
909
  "routed_catalog_bytes": routed_payload["total_hydrated_bytes"],
570
910
  "avoided_bytes": avoided_io_bytes,
911
+ "avoided_disk_bytes": avoided_io_bytes,
571
912
  "io_reduction_pct": io_reduction_pct,
913
+ "measurement_kind": "synthetic",
914
+ "measurement_source": "disk_file_stat",
572
915
  "label": "Disk Read I/O Footprint Avoided (Disk File Size, Not Context Tokens)",
573
916
  },
574
917
  },
@@ -652,9 +995,26 @@ def main():
652
995
  choices=["locator", "triage", "api", "perf", "security"],
653
996
  help="Target task intent profile",
654
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
+ )
655
1009
  args = parser.parse_args()
656
1010
 
657
- result = route_rules(args.workspace, minimal=args.minimal, task_type=args.task_type)
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
+ )
658
1018
 
659
1019
  if args.json:
660
1020
  print(format_routing_report(result, fmt="json"))
@@ -163,6 +163,78 @@ def audit_threat_model_firewall() -> Tuple[bool, List[str]]:
163
163
  return (len(findings) == 0), findings
164
164
 
165
165
 
166
+ def format_sarif(report: Dict[str, Any]) -> Dict[str, Any]:
167
+ """Formats security scan report into OASIS SARIF v2.1.0 JSON format."""
168
+ rules = [
169
+ {
170
+ "id": "SEC001-CWE-798",
171
+ "name": "HardcodedCredentialCheck",
172
+ "shortDescription": {"text": "Hard-coded credentials or secret token exposure (CWE-798)"},
173
+ "defaultConfiguration": {"level": "error"}
174
+ },
175
+ {
176
+ "id": "SEC002-CWE-1104",
177
+ "name": "DependencyVulnerabilityCheck",
178
+ "shortDescription": {"text": "Vulnerable third-party dependency (CWE-1104)"},
179
+ "defaultConfiguration": {"level": "warning"}
180
+ },
181
+ {
182
+ "id": "SEC003-CWE-284",
183
+ "name": "ThreatModelFirewallBypass",
184
+ "shortDescription": {"text": "Improper access control or destructive action bypass (CWE-284)"},
185
+ "defaultConfiguration": {"level": "error"}
186
+ }
187
+ ]
188
+
189
+ results = []
190
+ checks = report.get("checks", {})
191
+
192
+ # Check python dependencies findings
193
+ for finding in checks.get("python_dependencies", {}).get("findings", []):
194
+ results.append({
195
+ "ruleId": "SEC002-CWE-1104",
196
+ "level": "warning",
197
+ "message": {"text": str(finding)},
198
+ "locations": [{"physicalLocation": {"artifactLocation": {"uri": "requirements.txt"}}}]
199
+ })
200
+
201
+ # Check npm dependencies findings
202
+ for finding in checks.get("npm_dependencies", {}).get("findings", []):
203
+ results.append({
204
+ "ruleId": "SEC002-CWE-1104",
205
+ "level": "warning",
206
+ "message": {"text": str(finding)},
207
+ "locations": [{"physicalLocation": {"artifactLocation": {"uri": "package.json"}}}]
208
+ })
209
+
210
+ # Check threat model firewall findings
211
+ for finding in checks.get("threat_model_firewall", {}).get("findings", []):
212
+ results.append({
213
+ "ruleId": "SEC003-CWE-284",
214
+ "level": "error",
215
+ "message": {"text": str(finding)},
216
+ "locations": [{"physicalLocation": {"artifactLocation": {"uri": "tools/safety_firewall.py"}}}]
217
+ })
218
+
219
+ return {
220
+ "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
221
+ "version": "2.1.0",
222
+ "runs": [
223
+ {
224
+ "tool": {
225
+ "driver": {
226
+ "name": "Synapse-Hub Security Sentinel",
227
+ "version": "1.0.0",
228
+ "informationUri": "https://github.com/TeeVee98/Synapse-Hub",
229
+ "rules": rules
230
+ }
231
+ },
232
+ "results": results
233
+ }
234
+ ]
235
+ }
236
+
237
+
166
238
  def run_security_scan(repo_root: str = REPO_ROOT) -> Dict[str, Any]:
167
239
  """Runs complete security scan suite."""
168
240
  py_ok, py_findings = audit_python_dependencies(repo_root)
@@ -185,11 +257,19 @@ def run_security_scan(repo_root: str = REPO_ROOT) -> Dict[str, Any]:
185
257
  def main() -> int:
186
258
  parser = argparse.ArgumentParser(description="Comprehensive Enterprise Security Sentinel for Synapse Hub")
187
259
  parser.add_argument("--json", action="store_true", help="Output results in JSON format")
260
+ parser.add_argument("--sarif", type=str, default="", help="Path to write OASIS SARIF v2.1.0 output file")
188
261
  parser.add_argument("--strict", action="store_true", help="Enforce zero warnings")
189
262
  args = parser.parse_args()
190
263
 
191
264
  report = run_security_scan()
192
265
 
266
+ if args.sarif:
267
+ sarif_doc = format_sarif(report)
268
+ os.makedirs(os.path.dirname(os.path.abspath(args.sarif)), exist_ok=True)
269
+ with open(args.sarif, "w", encoding="utf-8") as sf:
270
+ json.dump(sarif_doc, sf, indent=2)
271
+ print(f"📄 SARIF v2.1.0 security report written to: {args.sarif}")
272
+
193
273
  if args.json:
194
274
  print(json.dumps(report, indent=2))
195
275
  return 0 if report["status"] == "PASS" else 1