@teevee98/synapse-hub 4.1.4 → 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 (133) 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 +52 -3
  3. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +55 -5
  4. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +62 -67
  5. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +54 -4
  6. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +62 -12
  7. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +55 -8
  8. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +60 -12
  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 +54 -91
  13. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +59 -11
  14. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +50 -4
  15. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +55 -9
  16. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +55 -9
  17. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +55 -8
  18. package/.agents/skills/02-test-design/review-spec/SKILL.md +50 -6
  19. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +50 -4
  20. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +56 -5
  21. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +53 -7
  22. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +86 -36
  23. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +54 -6
  24. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +50 -6
  25. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +50 -3
  26. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +63 -14
  27. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +51 -5
  28. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +54 -4
  29. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +51 -5
  30. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +53 -6
  31. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +54 -8
  32. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +60 -24
  33. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +52 -6
  34. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +56 -10
  35. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +58 -12
  36. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +58 -12
  37. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +53 -5
  38. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +56 -5
  39. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +53 -4
  40. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +58 -5
  41. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +57 -11
  42. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +83 -34
  43. package/.agents/skills/08-code-quality/graphify-impact-analyzer/examples/dependency_blast_radius.json +3 -4
  44. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +55 -10
  45. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +49 -6
  46. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +52 -7
  47. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +55 -10
  48. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +51 -5
  49. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +54 -17
  50. package/.agents/skills/09-ci-and-devops/github-actions-templates/examples/matrix_test_pipeline.yml +2 -1
  51. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +50 -4
  52. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +53 -7
  53. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +50 -4
  54. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +58 -13
  55. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +51 -5
  56. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +57 -10
  57. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +50 -4
  58. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +50 -4
  59. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +55 -9
  60. package/.cursor/rules/synapse-qa.mdc +20 -7
  61. package/.cursorrules +19 -5
  62. package/.windsurfrules +18 -3
  63. package/AGENTS.md +51 -59
  64. package/CLAUDE.md +38 -24
  65. package/LICENSE +5 -5
  66. package/NOTICE +1 -1
  67. package/README.en.md +4 -4
  68. package/README.md +4 -4
  69. package/agentskills.json +1 -1
  70. package/docs/ARCHITECTURE.en.md +2 -2
  71. package/docs/ARCHITECTURE.md +11 -2
  72. package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
  73. package/docs/CLI_REFERENCE.en.md +6 -4
  74. package/docs/CLI_REFERENCE.md +1 -1
  75. package/docs/CONTRIBUTING.en.md +1 -1
  76. package/docs/CONTRIBUTING.md +2 -2
  77. package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
  78. package/docs/TOOL_CATALOG.md +6 -2
  79. package/docs/research/agent_skill_training_analysis.md +1 -1
  80. package/package.json +1 -1
  81. package/plugin.json +1 -1
  82. package/skills_manifest.json +320 -55
  83. package/synapse.config.json +1 -1
  84. package/templates/ai_bridges/CLAUDE.md +29 -26
  85. package/templates/ai_bridges/copilot-instructions.md +14 -5
  86. package/templates/ai_bridges/cursor_synapse_qa.mdc +16 -7
  87. package/templates/ai_bridges/windsurfrules +14 -3
  88. package/templates/ui/index.html +2 -2
  89. package/tools/TOOLS_RUNBOOK.md +1 -1
  90. package/tools/TOOL_CATALOG.json +63 -3
  91. package/tools/__init__.py +1 -1
  92. package/tools/api_fuzzer.py +447 -132
  93. package/tools/author_integrity.py +121 -11
  94. package/tools/benchmark_swarm_context.py +130 -22
  95. package/tools/break_ui_generator.py +233 -0
  96. package/tools/browser_helpers.js +2 -2
  97. package/tools/check_version_sync.py +18 -50
  98. package/tools/cli.py +110 -19
  99. package/tools/core/bm25_retriever.py +218 -0
  100. package/tools/core/i18n.py +5 -5
  101. package/tools/core/provider_usage_adapter.py +383 -0
  102. package/tools/core/token_estimator.py +81 -15
  103. package/tools/count_tokens.py +7 -2
  104. package/tools/coverage_reporter.py +245 -0
  105. package/tools/dashboard_generator.py +8 -8
  106. package/tools/db_sandbox.py +290 -9
  107. package/tools/distill_log.py +1 -1
  108. package/tools/distill_skill.py +206 -0
  109. package/tools/git_pre_commit_guard.py +202 -1
  110. package/tools/humanize_linter.py +3 -0
  111. package/tools/mcp_docx_server.py +1 -1
  112. package/tools/mcp_excel_server.py +1 -1
  113. package/tools/mcp_server.py +104 -16
  114. package/tools/micro_mutator.py +114 -15
  115. package/tools/pentest_scope_guard.py +674 -58
  116. package/tools/perf/benchmark_perf_runner.py +42 -0
  117. package/tools/project_state.py +29 -5
  118. package/tools/reversible_sandbox.py +58 -13
  119. package/tools/rules_router.py +473 -60
  120. package/tools/security_scanner.py +80 -0
  121. package/tools/senior_code_review.py +14 -0
  122. package/tools/skill_canonical_digest.py +302 -0
  123. package/tools/skill_profiles.py +77 -7
  124. package/tools/slide_deck_exporter.py +477 -0
  125. package/tools/sync_agent_rules.py +187 -61
  126. package/tools/sync_skills_manifest.py +166 -0
  127. package/tools/task_memory_manager.py +275 -0
  128. package/tools/ui_server.py +3 -1
  129. package/tools/update_sentinel.py +3 -3
  130. package/tools/validate_host_interop.py +485 -0
  131. package/tools/validate_skills_schema.py +575 -0
  132. package/tools/verify_all.py +668 -44
  133. package/tools/welcome_page.py +2 -2
@@ -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
@@ -169,6 +170,189 @@ DEFAULT_CORE_SKILLS = [
169
170
  ]
170
171
 
171
172
 
173
+ class TokenCapExceededError(ValueError):
174
+ """
175
+ Raised when the aggregated token payload exceeds the configured token_cap
176
+ and cannot be satisfied even after priority pruning of lower-priority skills.
177
+ """
178
+ def __init__(
179
+ self,
180
+ message: str,
181
+ required_tokens: int = 0,
182
+ token_cap: int = 0,
183
+ item_type: str = "payload",
184
+ ):
185
+ super().__init__(message)
186
+ self.required_tokens = required_tokens
187
+ self.token_cap = token_cap
188
+ self.item_type = item_type
189
+
190
+
191
+ TASK_TYPE_CONFIGS: Dict[str, Dict[str, Any]] = {
192
+ "locator": {
193
+ "rules": ["mandatory-playwright-live.md", "systematic-debugging.md"],
194
+ "primary_skills": ["clean-pom-crafter"],
195
+ "secondary_skills": ["self-healing-locator"],
196
+ "default_token_cap": 6000,
197
+ },
198
+ "triage": {
199
+ "rules": ["systematic-debugging.md"],
200
+ "primary_skills": ["failure-autopsy-and-healing", "systematic-debugging"],
201
+ "secondary_skills": [],
202
+ "default_token_cap": 6000,
203
+ },
204
+ "api": {
205
+ "rules": ["systematic-debugging.md"],
206
+ "primary_skills": ["api-spec-to-e2e-matrix", "api-network-mocking-interception"],
207
+ "secondary_skills": ["consumer-driven-contract-testing"],
208
+ "default_token_cap": 6000,
209
+ },
210
+ "perf": {
211
+ "rules": ["performance_testing_rules.md"],
212
+ "primary_skills": ["backend-load-and-stress-patterns", "web-vitals-and-performance-profiler"],
213
+ "secondary_skills": ["lean-impact-scoreboard"],
214
+ "default_token_cap": 6000,
215
+ },
216
+ "security": {
217
+ "rules": ["security_testing_rules.md"],
218
+ "primary_skills": ["security-dast-sentinel", "skillspector-security-guard"],
219
+ "secondary_skills": ["wcag-audit-patterns"],
220
+ "default_token_cap": 6000,
221
+ },
222
+ }
223
+
224
+
225
+ def prune_payload_to_cap(
226
+ repo_root: str,
227
+ rules: List[str],
228
+ skills: List[str],
229
+ token_cap: Optional[int],
230
+ primary_skills: Optional[List[str]] = None,
231
+ mandatory_skills: Optional[List[str]] = None,
232
+ task_rules: Optional[List[str]] = None,
233
+ allow_partial: bool = False,
234
+ ) -> Tuple[List[str], List[str], List[str], Dict[str, Any]]:
235
+ """
236
+ Enforces token_cap against total_hydrated_tokens using priority-based pruning.
237
+
238
+ Priority Hierarchy:
239
+ CORE_BASE_RULES (Hard Floor) > Mandatory Skills > Task Rules > Non-Task Rules > Secondary Skills
240
+
241
+ Returns:
242
+ (final_rules, final_skills, pruned_skills, final_payload)
243
+ Raises:
244
+ TokenCapExceededError: When minimal mandatory floor exceeds token_cap (and allow_partial is False).
245
+ """
246
+ if token_cap is None:
247
+ payload = calculate_hydration_payload(repo_root, rules, skills)
248
+ return rules, skills, [], payload
249
+
250
+ if not isinstance(token_cap, int) or token_cap <= 0:
251
+ raise TokenCapExceededError(
252
+ f"Insufficient token_cap: {token_cap}. Must be a positive integer greater than 0.",
253
+ required_tokens=0,
254
+ token_cap=token_cap if isinstance(token_cap, int) else 0,
255
+ item_type="cap_validation",
256
+ )
257
+
258
+ # 1. Hard Floor Validation: CORE_BASE_RULES and mandatory_skills cannot be pruned
259
+ mand_list = list(mandatory_skills) if mandatory_skills is not None else []
260
+ floor_payload = calculate_hydration_payload(repo_root, sorted(CORE_BASE_RULES), mand_list)
261
+ hard_floor_tokens = floor_payload["total_hydrated_tokens"]
262
+
263
+ if token_cap < hard_floor_tokens:
264
+ if not allow_partial:
265
+ item_type = "mandatory_skills" if mand_list else "core_rules"
266
+ detail = f"with mandatory skills {mand_list}" if mand_list else "core rules"
267
+ raise TokenCapExceededError(
268
+ f"Insufficient token_cap: {token_cap}. Mandatory floor ({detail}) requires {hard_floor_tokens} tokens, which exceeds token_cap ({token_cap}).",
269
+ required_tokens=hard_floor_tokens,
270
+ token_cap=token_cap,
271
+ item_type=item_type,
272
+ )
273
+
274
+ current_rules = list(rules)
275
+ current_skills = list(skills)
276
+ pruned_skills: List[str] = []
277
+
278
+ current_payload = calculate_hydration_payload(repo_root, current_rules, current_skills)
279
+ if current_payload["total_hydrated_tokens"] <= token_cap:
280
+ return current_rules, current_skills, pruned_skills, current_payload
281
+
282
+ # Determine primary set for priority ordering
283
+ if mand_list:
284
+ primary_set = set(mand_list)
285
+ elif primary_skills is not None:
286
+ primary_set = set(primary_skills)
287
+ else:
288
+ primary_set = set(skills[:1]) if skills else set()
289
+
290
+ # Step 1: Drop secondary skills first (down to 0 secondary skills) while total tokens > token_cap
291
+ while current_payload["total_hydrated_tokens"] > token_cap:
292
+ sec_skills = [s for s in current_skills if s not in primary_set]
293
+ if not sec_skills:
294
+ break
295
+ dropped = sec_skills[-1]
296
+ current_skills.remove(dropped)
297
+ pruned_skills.append(dropped)
298
+ current_payload = calculate_hydration_payload(repo_root, current_rules, current_skills)
299
+
300
+ # Step 2: If still exceeding cap, drop non-task non-core rules first, then task rules
301
+ if current_payload["total_hydrated_tokens"] > token_cap:
302
+ task_rule_set = set(task_rules) if task_rules is not None else set()
303
+ # Drop external/other stack rules before dropping task-specific rules
304
+ other_rules = [r for r in current_rules if r not in CORE_BASE_RULES and r not in task_rule_set]
305
+ while current_payload["total_hydrated_tokens"] > token_cap and len(other_rules) > 0:
306
+ dropped_rule = other_rules.pop()
307
+ current_rules.remove(dropped_rule)
308
+ current_payload = calculate_hydration_payload(repo_root, current_rules, current_skills)
309
+
310
+ # If still exceeding cap after dropping all other rules, drop task rules
311
+ if current_payload["total_hydrated_tokens"] > token_cap:
312
+ t_rules = [r for r in current_rules if r in task_rule_set and r not in CORE_BASE_RULES]
313
+ while current_payload["total_hydrated_tokens"] > token_cap and len(t_rules) > 0:
314
+ dropped_rule = t_rules.pop()
315
+ current_rules.remove(dropped_rule)
316
+ current_payload = calculate_hydration_payload(repo_root, current_rules, current_skills)
317
+
318
+ # Step 3: If no mandatory skills were specified (e.g. untyped route),
319
+ # preserve primary profile skills if remaining budget allows, otherwise drop down to 0
320
+ if not mand_list and current_payload["total_hydrated_tokens"] > token_cap:
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)
340
+
341
+ # Step 4: If still exceeding cap (e.g. when allow_partial=True), raise or return
342
+ if current_payload["total_hydrated_tokens"] > token_cap:
343
+ if not allow_partial:
344
+ required = current_payload["total_hydrated_tokens"]
345
+ raise TokenCapExceededError(
346
+ f"Aggregated payload requires {required} tokens, exceeding token_cap ({token_cap}) even after pruning all lower-priority components.",
347
+ required_tokens=required,
348
+ token_cap=token_cap,
349
+ item_type="payload",
350
+ )
351
+
352
+ return current_rules, current_skills, pruned_skills, current_payload
353
+
354
+
355
+
172
356
  def _find_repo_root() -> str:
173
357
  """Finds the root of Synapse-Hub repository."""
174
358
  curr = os.path.abspath(os.path.dirname(__file__))
@@ -179,8 +363,8 @@ def _find_repo_root() -> str:
179
363
  return os.path.abspath(os.path.dirname(os.path.dirname(__file__)))
180
364
 
181
365
 
182
- def _scan_directory_markers(target_dir: str, prefix: str = "") -> Tuple[Dict[str, List[str]], Dict[str, float]]:
183
- """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."""
184
368
  detected: Dict[str, List[str]] = {
185
369
  "playwright": [],
186
370
  "cypress": [],
@@ -290,7 +474,7 @@ def _scan_directory_markers(target_dir: str, prefix: str = "") -> Tuple[Dict[str
290
474
  for root, dirs, files in os.walk(target_dir):
291
475
  rel = os.path.relpath(root, target_dir)
292
476
  depth = 0 if rel == "." else len(rel.split(os.sep))
293
- if depth >= 2:
477
+ if depth >= max_depth:
294
478
  dirs.clear()
295
479
  continue
296
480
  dirs[:] = [d for d in dirs if d not in ignored]
@@ -375,13 +559,13 @@ def _scan_directory_markers(target_dir: str, prefix: str = "") -> Tuple[Dict[str
375
559
  return detected, confidence
376
560
 
377
561
 
378
- def detect_workspace_stacks(workspace_dir: str) -> Dict[str, Any]:
562
+ def detect_workspace_stacks(workspace_dir: str, depth: int = 5) -> Dict[str, Any]:
379
563
  """
380
564
  Inspects target workspace directory, supporting standalone projects and Monorepos.
381
- Calculates confidence scores for detected testing stacks.
565
+ Calculates confidence scores for detected testing stacks up to configured depth.
382
566
  """
383
567
  workspace = os.path.abspath(workspace_dir)
384
- detected, confidence = _scan_directory_markers(workspace)
568
+ detected, confidence = _scan_directory_markers(workspace, max_depth=depth)
385
569
 
386
570
  # Monorepo check at root
387
571
  monorepo_markers = ["pnpm-workspace.yaml", "lerna.json", "nx.json", "turbo.json"]
@@ -399,21 +583,40 @@ def detect_workspace_stacks(workspace_dir: str) -> Dict[str, Any]:
399
583
  logger.debug("Failed to read settings.gradle: %s", err)
400
584
 
401
585
  if is_monorepo:
402
- # 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"}
403
588
  for sub_parent in ("packages", "apps", "services", "modules"):
404
589
  parent_dir = os.path.join(workspace, sub_parent)
405
590
  if os.path.isdir(parent_dir):
406
- try:
407
- for child in os.listdir(parent_dir):
408
- child_dir = os.path.join(parent_dir, child)
409
- if os.path.isdir(child_dir) and not child.startswith("."):
410
- prefix = f"[{sub_parent}/{child}] "
411
- sub_det, sub_conf = _scan_directory_markers(child_dir, prefix=prefix)
412
- for stack, evs in sub_det.items():
413
- detected[stack].extend(evs)
414
- confidence[stack] = max(confidence[stack], sub_conf[stack])
415
- except OSError as err:
416
- 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])
417
620
 
418
621
  # Filter active stacks where confidence >= 0.50
419
622
  active_stacks = [s for s, evs in detected.items() if evs and confidence[s] >= 0.50]
@@ -426,45 +629,81 @@ def detect_workspace_stacks(workspace_dir: str) -> Dict[str, Any]:
426
629
  }
427
630
 
428
631
 
429
- def route_rules(workspace_dir: str = ".", minimal: bool = False, task_type: Optional[str] = None) -> Dict[str, Any]:
632
+ def route_rules(
633
+ workspace_dir: str = ".",
634
+ minimal: bool = False,
635
+ task_type: Optional[str] = None,
636
+ token_cap: Optional[int] = None,
637
+ allow_partial: bool = False,
638
+ depth: int = 5,
639
+ ) -> Dict[str, Any]:
430
640
  """
431
641
  Determines minimal rules and skills for target workspace, with dual-tier token hydration
432
- accounting and strict truth-anchoring for unknown stacks.
642
+ accounting, priority pruning under token_cap, and strict truth-anchoring for unknown stacks.
433
643
  """
434
644
  repo_root = _find_repo_root()
435
- stack_info = detect_workspace_stacks(workspace_dir)
645
+ stack_info = detect_workspace_stacks(workspace_dir, depth=depth)
436
646
  active_stacks = stack_info["detected_stacks"]
437
647
 
438
648
  is_unknown_stack = len(active_stacks) == 0
439
649
 
650
+ if task_type is not None:
651
+ if task_type not in TASK_TYPE_CONFIGS:
652
+ raise ValueError(f"Unknown task_type: '{task_type}'. Valid choices: {list(TASK_TYPE_CONFIGS.keys())}")
653
+
654
+ # Determine effective task_mode and cap
655
+ is_minimal_mode = minimal or (task_type is not None)
656
+ effective_cap = token_cap
657
+ if effective_cap is None and is_minimal_mode:
658
+ if task_type is not None:
659
+ effective_cap = TASK_TYPE_CONFIGS[task_type]["default_token_cap"]
660
+ else:
661
+ effective_cap = 6000
662
+
440
663
  # Compile rules
441
664
  rules_set: Set[str] = set(CORE_BASE_RULES)
442
665
  for stack in active_stacks:
443
666
  for r in STACK_RULE_MAPPINGS.get(stack, []):
444
667
  rules_set.add(r)
445
668
 
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)
669
+ # Compile candidate skills in priority order
670
+ ordered_skills: List[str] = []
671
+ mandatory_skills_list: List[str] = []
672
+ task_rules_list: List[str] = []
673
+
674
+ if task_type is not None:
675
+ cfg = TASK_TYPE_CONFIGS[task_type]
676
+ task_rules_list = list(cfg.get("rules", []))
677
+ for r in task_rules_list:
678
+ rules_set.add(r)
679
+
680
+ mandatory_skills_list = list(cfg.get("primary_skills", []))
681
+ # Primary skills first, then secondary skills
682
+ for s in mandatory_skills_list:
683
+ if s not in ordered_skills:
684
+ ordered_skills.append(s)
685
+ for s in cfg.get("secondary_skills", []):
686
+ if s not in ordered_skills:
687
+ ordered_skills.append(s)
688
+ else:
689
+ # Stack-specific skills first, then default core skills
690
+ for stack in active_stacks:
691
+ for s in STACK_SKILL_MAPPINGS.get(stack, []):
692
+ if s not in ordered_skills:
693
+ ordered_skills.append(s)
694
+ for s in DEFAULT_CORE_SKILLS:
695
+ if s not in ordered_skills:
696
+ ordered_skills.append(s)
697
+
698
+ if minimal:
699
+ ordered_skills = ordered_skills[:2]
700
+
701
+ candidate_rules = sorted(rules_set)
702
+
703
+ # Hard Floor measurement: CORE_BASE_RULES + mandatory skills for specific task
704
+ floor_payload = calculate_hydration_payload(repo_root, sorted(CORE_BASE_RULES), mandatory_skills_list)
705
+ hard_floor_tokens = floor_payload["total_hydrated_tokens"]
706
+ core_floor_tokens = floor_payload["rule_tokens"]
468
707
 
469
708
  # Calculate full unrouted baseline dynamically by enumerating 100% of skills & rules
470
709
  baseline = get_full_unrouted_baseline(repo_root)
@@ -473,52 +712,130 @@ def route_rules(workspace_dir: str = ".", minimal: bool = False, task_type: Opti
473
712
  unrouted_full_bytes = baseline["total_full_bytes"]
474
713
  estimator_info = baseline.get("estimator_info", get_estimator_info())
475
714
 
476
- # If workspace is unclassified (no stack detected), report honest fallback metrics
477
- if is_unknown_stack:
715
+ measurement_kind = "synthetic" if estimator_info.get("is_exact") else "static_estimate"
716
+ tokenizer_name = estimator_info.get("encoding", "cl100k_base")
717
+
718
+ # If workspace is unclassified (no stack detected) and no task_type was specified, report honest fallback metrics
719
+ if is_unknown_stack and task_type is None:
720
+ # Validate cap against core base rules even on unclassified workspaces
721
+ final_rules, final_skills, pruned_skills, routed_payload = prune_payload_to_cap(
722
+ repo_root=repo_root,
723
+ rules=sorted(CORE_BASE_RULES),
724
+ skills=[],
725
+ token_cap=effective_cap,
726
+ mandatory_skills=[],
727
+ allow_partial=allow_partial,
728
+ )
729
+
478
730
  return {
479
731
  "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,
732
+ "task_mode": "minimal" if is_minimal_mode else "full",
733
+ "token_cap": effective_cap,
734
+ "token_cap_enforced": effective_cap is not None,
735
+ "pruned_skills": pruned_skills,
482
736
  "task_type": task_type,
483
737
  "status": "UNCLASSIFIED_WORKSPACE",
484
738
  "detected_stacks": ["unknown"],
485
739
  "classification": "UNCLASSIFIED_WORKSPACE (Fallback Core Base Rules)",
486
740
  "confidence_score": 0.0,
487
741
  "evidence": {},
488
- "recommended_rules": valid_rules,
489
- "recommended_skills": valid_skills,
742
+ "recommended_rules": final_rules,
743
+ "recommended_skills": final_skills,
490
744
  "estimator_info": estimator_info,
491
745
  "token_metrics": {
492
746
  "unrouted_baseline_tokens": unrouted_summary_baseline,
493
747
  "routed_tokens": routed_payload["total_summary_tokens"],
748
+ "catalog_summary_tokens": routed_payload["total_summary_tokens"],
749
+ "estimated_payload_tokens": routed_payload["total_hydrated_tokens"],
750
+ "estimated_hydration_tokens": routed_payload["total_hydrated_tokens"],
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")),
757
+ "synthetic_tokens": None,
758
+ "provider_reported_input_tokens": None,
759
+ "provider_reported_output_tokens": None,
760
+ "provider_cached_tokens": None,
761
+ "token_cap": effective_cap,
762
+ "provider_reported_tokens": None,
763
+ "measurement_kind": measurement_kind,
764
+ "tokenizer_or_model": tokenizer_name,
765
+ "measurement_source": "offline_token_estimator",
766
+ "context_scope": "hydrated_documentation_and_rules",
767
+ "avoided_disk_bytes": 0,
494
768
  "tokens_saved": 0,
495
769
  "reduction_percentage": 0.0,
496
- "note": "Stack unclassified; routed to core base profile without claiming workload-specific token reduction.",
770
+ "core_rule_tokens": core_floor_tokens,
771
+ "hard_floor_tokens": hard_floor_tokens,
772
+ "pruned_items_count": len(pruned_skills),
773
+ "cap_excludes_system_prompt_and_wrapper": True,
774
+ "note": "Stack unclassified; routed to core base profile without claiming workload-specific token reduction. Cap applies to hydrated documentation, not host context.",
497
775
  },
498
776
  "hydration_contracts": {
499
777
  "catalog_summary": {
500
778
  "baseline_tokens": unrouted_summary_baseline,
501
779
  "routed_tokens": routed_payload["total_summary_tokens"],
780
+ "catalog_summary_tokens": routed_payload["total_summary_tokens"],
781
+ "estimated_payload_tokens": routed_payload["total_summary_tokens"],
782
+ "measurement_kind": measurement_kind,
783
+ "tokenizer_or_model": tokenizer_name,
784
+ "measurement_source": "offline_token_estimator",
502
785
  "tokens_saved": 0,
503
786
  "reduction_pct": 0.0,
787
+ "scope": "Skill registry metadata for Front-Door Orchestrator",
504
788
  },
505
789
  "full_hydration": {
506
790
  "baseline_tokens": unrouted_full_baseline,
507
791
  "routed_tokens": routed_payload["total_hydrated_tokens"],
792
+ "static_estimated_tokens": routed_payload["total_hydrated_tokens"],
793
+ "estimated_hydration_tokens": routed_payload["total_hydrated_tokens"],
794
+ "estimated_payload_tokens": routed_payload["total_hydrated_tokens"],
795
+ "provider_reported_input_tokens": None,
796
+ "provider_reported_output_tokens": None,
797
+ "provider_cached_tokens": None,
798
+ "token_cap": effective_cap,
799
+ "cap_excludes_system_prompt_and_wrapper": True,
800
+ "provider_reported_tokens": None,
801
+ "measurement_kind": measurement_kind,
802
+ "tokenizer_or_model": tokenizer_name,
803
+ "measurement_source": "offline_token_estimator",
508
804
  "tokens_saved": 0,
509
805
  "reduction_pct": 0.0,
806
+ "scope": "Complete SKILL.md bodies injected into Specialized Subagents",
510
807
  },
511
808
  "retrieval_footprint": {
512
809
  "full_catalog_bytes": unrouted_full_bytes,
513
810
  "routed_catalog_bytes": routed_payload["total_hydrated_bytes"],
514
811
  "avoided_bytes": 0,
812
+ "avoided_disk_bytes": 0,
515
813
  "io_reduction_pct": 0.0,
814
+ "measurement_kind": "synthetic",
815
+ "measurement_source": "disk_file_stat",
516
816
  "label": "Disk Read I/O Footprint Avoided (Disk File Size, Not Context Tokens)",
517
817
  },
518
818
  },
519
819
  }
520
820
 
521
- # Classified stacks: compute honest savings for both tiers
821
+ # Classified stacks or task-directed profiles: priority pruning & token cap enforcement
822
+ primary_skills_list: Optional[List[str]] = None
823
+ if task_type is not None:
824
+ primary_skills_list = mandatory_skills_list
825
+ elif ordered_skills:
826
+ primary_skills_list = ordered_skills[:1]
827
+
828
+ final_rules, final_skills, pruned_skills, routed_payload = prune_payload_to_cap(
829
+ repo_root=repo_root,
830
+ rules=candidate_rules,
831
+ skills=ordered_skills,
832
+ token_cap=effective_cap,
833
+ primary_skills=primary_skills_list,
834
+ mandatory_skills=mandatory_skills_list,
835
+ task_rules=task_rules_list,
836
+ allow_partial=allow_partial,
837
+ )
838
+
522
839
  summary_saved = max(0, unrouted_summary_baseline - routed_payload["total_summary_tokens"])
523
840
  summary_pct = round((summary_saved / max(1, unrouted_summary_baseline)) * 100, 1)
524
841
 
@@ -528,31 +845,88 @@ def route_rules(workspace_dir: str = ".", minimal: bool = False, task_type: Opti
528
845
  avoided_io_bytes = max(0, unrouted_full_bytes - routed_payload["total_hydrated_bytes"])
529
846
  io_reduction_pct = round((avoided_io_bytes / max(1, unrouted_full_bytes)) * 100, 1)
530
847
 
531
- avg_conf = sum(stack_info["confidence"].values()) / max(1, len(stack_info["confidence"]))
848
+ partial_reason = None
849
+ if effective_cap is not None and routed_payload["total_hydrated_tokens"] > effective_cap:
850
+ avg_conf = 0.0
851
+ status_label = "PARTIAL_CAP_EXCEEDED"
852
+ class_label = f"PARTIAL_CAP_EXCEEDED (Mandatory floor {hard_floor_tokens} exceeds cap {effective_cap})"
853
+ partial_reason = (
854
+ f"Token cap ({effective_cap}) is below mandatory floor ({hard_floor_tokens}) "
855
+ f"for task '{task_type}'."
856
+ )
857
+ elif active_stacks:
858
+ avg_conf = sum(stack_info["confidence"].values()) / max(1, len(stack_info["confidence"]))
859
+ status_label = "CLASSIFIED"
860
+ class_label = f"CLASSIFIED ({', '.join(active_stacks)})"
861
+ else:
862
+ avg_conf = 0.0
863
+ status_label = "UNCLASSIFIED_WORKSPACE"
864
+ class_label = f"UNCLASSIFIED_WORKSPACE (Task: {task_type})"
865
+
866
+ routing_note = (
867
+ f"Workspace stack unclassified; task-specific profile for '{task_type}' retained and hydrated under token cap. "
868
+ "Cap applies strictly to router-managed rules and hydrated documentation; it does not include host system prompt or provider request wrappers."
869
+ if is_unknown_stack
870
+ else "Stack classified; rule and skill subsets hydrated under token cap. "
871
+ "Cap applies strictly to router-managed rules and hydrated documentation; it does not include host system prompt or provider request wrappers."
872
+ )
532
873
 
533
874
  return {
534
875
  "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,
876
+ "task_mode": "minimal" if is_minimal_mode else "full",
877
+ "token_cap": effective_cap,
878
+ "token_cap_enforced": effective_cap is not None,
879
+ "pruned_skills": pruned_skills,
537
880
  "task_type": task_type,
538
- "status": "CLASSIFIED",
539
- "detected_stacks": active_stacks,
540
- "classification": f"CLASSIFIED ({', '.join(active_stacks)})",
881
+ "status": status_label,
882
+ "detected_stacks": active_stacks if active_stacks else ["unknown"],
883
+ "classification": class_label,
541
884
  "confidence_score": round(avg_conf, 2),
542
885
  "evidence": stack_info["evidence"],
543
- "recommended_rules": valid_rules,
544
- "recommended_skills": valid_skills,
886
+ "recommended_rules": final_rules,
887
+ "recommended_skills": final_skills,
545
888
  "estimator_info": estimator_info,
546
889
  "token_metrics": {
547
890
  "unrouted_baseline_tokens": unrouted_summary_baseline,
548
891
  "routed_tokens": routed_payload["total_summary_tokens"],
892
+ "catalog_summary_tokens": routed_payload["total_summary_tokens"],
893
+ "estimated_payload_tokens": routed_payload["total_hydrated_tokens"],
894
+ "estimated_hydration_tokens": routed_payload["total_hydrated_tokens"],
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")),
901
+ "synthetic_tokens": None,
902
+ "provider_reported_input_tokens": None,
903
+ "provider_reported_output_tokens": None,
904
+ "provider_cached_tokens": None,
905
+ "token_cap": effective_cap,
906
+ "provider_reported_tokens": None,
907
+ "measurement_kind": measurement_kind,
908
+ "tokenizer_or_model": tokenizer_name,
909
+ "measurement_source": "offline_token_estimator",
910
+ "context_scope": "hydrated_documentation_and_rules",
911
+ "avoided_disk_bytes": avoided_io_bytes,
549
912
  "tokens_saved": summary_saved,
550
913
  "reduction_percentage": summary_pct,
914
+ "core_rule_tokens": core_floor_tokens,
915
+ "hard_floor_tokens": hard_floor_tokens,
916
+ "pruned_items_count": len(pruned_skills),
917
+ "cap_excludes_system_prompt_and_wrapper": True,
918
+ **({"partial_reason": partial_reason} if partial_reason else {}),
919
+ "note": routing_note,
551
920
  },
552
921
  "hydration_contracts": {
553
922
  "catalog_summary": {
554
923
  "baseline_tokens": unrouted_summary_baseline,
555
924
  "routed_tokens": routed_payload["total_summary_tokens"],
925
+ "catalog_summary_tokens": routed_payload["total_summary_tokens"],
926
+ "estimated_payload_tokens": routed_payload["total_summary_tokens"],
927
+ "measurement_kind": measurement_kind,
928
+ "tokenizer_or_model": tokenizer_name,
929
+ "measurement_source": "offline_token_estimator",
556
930
  "tokens_saved": summary_saved,
557
931
  "reduction_pct": summary_pct,
558
932
  "scope": "Skill registry metadata for Front-Door Orchestrator",
@@ -560,6 +934,18 @@ def route_rules(workspace_dir: str = ".", minimal: bool = False, task_type: Opti
560
934
  "full_hydration": {
561
935
  "baseline_tokens": unrouted_full_baseline,
562
936
  "routed_tokens": routed_payload["total_hydrated_tokens"],
937
+ "static_estimated_tokens": routed_payload["total_hydrated_tokens"],
938
+ "estimated_hydration_tokens": routed_payload["total_hydrated_tokens"],
939
+ "estimated_payload_tokens": routed_payload["total_hydrated_tokens"],
940
+ "provider_reported_input_tokens": None,
941
+ "provider_reported_output_tokens": None,
942
+ "provider_cached_tokens": None,
943
+ "token_cap": effective_cap,
944
+ "cap_excludes_system_prompt_and_wrapper": True,
945
+ "provider_reported_tokens": None,
946
+ "measurement_kind": measurement_kind,
947
+ "tokenizer_or_model": tokenizer_name,
948
+ "measurement_source": "offline_token_estimator",
563
949
  "tokens_saved": hydrated_saved,
564
950
  "reduction_pct": hydrated_pct,
565
951
  "scope": "Complete SKILL.md bodies injected into Specialized Subagents",
@@ -568,7 +954,10 @@ def route_rules(workspace_dir: str = ".", minimal: bool = False, task_type: Opti
568
954
  "full_catalog_bytes": unrouted_full_bytes,
569
955
  "routed_catalog_bytes": routed_payload["total_hydrated_bytes"],
570
956
  "avoided_bytes": avoided_io_bytes,
957
+ "avoided_disk_bytes": avoided_io_bytes,
571
958
  "io_reduction_pct": io_reduction_pct,
959
+ "measurement_kind": "synthetic",
960
+ "measurement_source": "disk_file_stat",
572
961
  "label": "Disk Read I/O Footprint Avoided (Disk File Size, Not Context Tokens)",
573
962
  },
574
963
  },
@@ -652,9 +1041,33 @@ def main():
652
1041
  choices=["locator", "triage", "api", "perf", "security"],
653
1042
  help="Target task intent profile",
654
1043
  )
1044
+ parser.add_argument(
1045
+ "--token-cap",
1046
+ type=int,
1047
+ default=None,
1048
+ help="Enforce custom token cap ceiling for managed skill/rule hydrated documentation payload (excluding host system prompt, user prompt, and model context window)",
1049
+ )
1050
+ parser.add_argument(
1051
+ "--allow-partial",
1052
+ action="store_true",
1053
+ help="Permit partial routing status instead of raising TokenCapExceededError when cap < floor",
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
+ )
655
1061
  args = parser.parse_args()
656
1062
 
657
- result = route_rules(args.workspace, minimal=args.minimal, task_type=args.task_type)
1063
+ result = route_rules(
1064
+ args.workspace,
1065
+ minimal=args.minimal,
1066
+ task_type=args.task_type,
1067
+ token_cap=args.token_cap,
1068
+ allow_partial=args.allow_partial,
1069
+ depth=args.depth,
1070
+ )
658
1071
 
659
1072
  if args.json:
660
1073
  print(format_routing_report(result, fmt="json"))