@teevee98/synapse-hub 4.0.0 → 4.1.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 (46) hide show
  1. package/.agents/rules/context-engineering.md +3 -3
  2. package/.agents/rules/security_testing_rules.md +8 -5
  3. package/README.en.md +4 -4
  4. package/README.md +4 -4
  5. package/agentskills.json +1 -1
  6. package/docs/ARCHITECTURE.en.md +2 -2
  7. package/docs/ARCHITECTURE.md +2 -2
  8. package/docs/CONTRIBUTING.en.md +1 -1
  9. package/docs/CONTRIBUTING.md +1 -1
  10. package/docs/TOOL_CATALOG.md +14 -4
  11. package/package.json +1 -1
  12. package/plugin.json +1 -1
  13. package/skills_manifest.json +162 -54
  14. package/synapse.config.json +17 -1
  15. package/tools/TOOL_CATALOG.json +156 -6
  16. package/tools/__init__.py +1 -1
  17. package/tools/ast_cache.py +1 -3
  18. package/tools/author_integrity.py +7 -2
  19. package/tools/benchmark_swarm_context.py +242 -151
  20. package/tools/browser_helpers.js +2 -2
  21. package/tools/build_consolidated_report.py +5 -5
  22. package/tools/check_version_sync.py +56 -0
  23. package/tools/cli.py +3 -3
  24. package/tools/core/file_lock.py +81 -6
  25. package/tools/core/telemetry.py +139 -1
  26. package/tools/core/token_estimator.py +144 -0
  27. package/tools/count_tokens.py +28 -0
  28. package/tools/dashboard_generator.py +6 -6
  29. package/tools/debt_harvester.py +20 -9
  30. package/tools/diagram_architect.py +0 -1
  31. package/tools/distill_log.py +266 -89
  32. package/tools/git_worktree_manager.py +1 -1
  33. package/tools/mcp_docx_server.py +1 -1
  34. package/tools/mcp_excel_server.py +1 -1
  35. package/tools/mcp_server.py +1 -1
  36. package/tools/mechanical_ui_gate.py +1 -1
  37. package/tools/micro_mutator.py +51 -10
  38. package/tools/pairwise_generator.py +0 -1
  39. package/tools/pentest_scope_guard.py +328 -0
  40. package/tools/perf/benchmark_perf_runner.py +225 -0
  41. package/tools/rules_router.py +326 -103
  42. package/tools/token_telemetry.py +224 -0
  43. package/tools/ui_server.py +1 -1
  44. package/tools/update_sentinel.py +3 -3
  45. package/tools/verify_all.py +24 -6
  46. package/tools/welcome_page.py +1 -1
@@ -6,20 +6,24 @@
6
6
  """
7
7
  tools/rules_router.py — Progressive Rules Router & Context Optimizer (Boost B2)
8
8
  --------------------------------------------------------------------------------
9
- Dynamically inspects workspace markers (Playwright, Cypress, Appium, K6, Security,
10
- API) to route and emit ONLY the minimal necessary rule files and skill subset.
11
- Prevents 4,000+ tokens of rule/skill bloat per agent turn while ensuring 100%
12
- quality gate compliance.
9
+ Dynamically inspects workspace markers (Playwright, Cypress, Katalon, Pytest-API,
10
+ Selenium, Appium, K6, Security, Monorepo) to route and emit ONLY the minimal
11
+ necessary rule files and skill subset.
12
+
13
+ Guarantees:
14
+ 1. High-accuracy multi-stack detection (depth 2 + monorepo subpackages).
15
+ 2. Truth Anchor confidence scoring (no fake 86% savings on unknown stacks).
16
+ 3. Dual-tier Token Hydration reporting (Catalog Summary vs Full Body Hydration).
17
+ 4. Byte retrieval vs Prompt token distinction.
13
18
  """
14
19
 
15
20
  from __future__ import annotations
16
21
 
17
22
  import argparse
18
- import glob
19
23
  import json
20
24
  import os
21
25
  import sys
22
- from typing import Any, Dict, List, Set
26
+ from typing import Any, Dict, List, Set, Tuple
23
27
 
24
28
  if hasattr(sys.stdout, "reconfigure"):
25
29
  try:
@@ -28,8 +32,35 @@ if hasattr(sys.stdout, "reconfigure"):
28
32
  except Exception:
29
33
  pass
30
34
 
31
- # Token constants for estimation (1 token ~= 4 chars)
32
- CHARS_PER_TOKEN = 4
35
+ # Import core token estimator with graceful fallback
36
+ try:
37
+ from tools.core.token_estimator import count_file_tokens, count_tokens, calculate_hydration_payload
38
+ except ImportError:
39
+ try:
40
+ from core.token_estimator import count_file_tokens, count_tokens, calculate_hydration_payload
41
+ except ImportError:
42
+ def count_tokens(text: str, model_hint: str = "cl100k") -> int:
43
+ return max(1, len(text) // 4)
44
+
45
+ def count_file_tokens(path: str) -> int:
46
+ if not os.path.isfile(path):
47
+ return 0
48
+ return max(1, os.path.getsize(path) // 4)
49
+
50
+ def calculate_hydration_payload(repo_root: str, rules: List[str], skills: List[str]) -> Dict[str, Any]:
51
+ r_tokens = len(rules) * 500
52
+ s_cat = len(skills) * 120
53
+ s_full = len(skills) * 1800
54
+ return {
55
+ "rule_tokens": r_tokens,
56
+ "rule_bytes": r_tokens * 4,
57
+ "skill_catalog_tokens": s_cat,
58
+ "skill_full_body_tokens": s_full,
59
+ "skill_full_bytes": s_full * 4,
60
+ "total_summary_tokens": r_tokens + s_cat,
61
+ "total_hydrated_tokens": r_tokens + s_full,
62
+ "total_hydrated_bytes": (r_tokens + s_full) * 4,
63
+ }
33
64
 
34
65
  # Base rules always recommended (Attribution guard, communication style, precedence)
35
66
  CORE_BASE_RULES = [
@@ -43,6 +74,8 @@ STACK_RULE_MAPPINGS = {
43
74
  "playwright": ["mandatory-playwright-live.md", "systematic-debugging.md"],
44
75
  "cypress": ["systematic-debugging.md"],
45
76
  "mobile": ["mobile_appium_rules.md", "systematic-debugging.md"],
77
+ "katalon": ["systematic-debugging.md"],
78
+ "selenium": ["systematic-debugging.md"],
46
79
  "performance": ["performance_testing_rules.md"],
47
80
  "security": ["security_testing_rules.md"],
48
81
  "api": ["systematic-debugging.md"],
@@ -67,6 +100,16 @@ STACK_SKILL_MAPPINGS = {
67
100
  "mobile-appium-som",
68
101
  "clean-pom-crafter",
69
102
  ],
103
+ "katalon": [
104
+ "clean-pom-crafter",
105
+ "failure-autopsy-and-healing",
106
+ "verification-before-completion",
107
+ ],
108
+ "selenium": [
109
+ "clean-pom-crafter",
110
+ "self-healing-locator",
111
+ "verification-before-completion",
112
+ ],
70
113
  "performance": [
71
114
  "backend-load-and-stress-patterns",
72
115
  ],
@@ -87,9 +130,6 @@ DEFAULT_CORE_SKILLS = [
87
130
  "systematic-debugging",
88
131
  ]
89
132
 
90
- # Total baseline tokens when unrouted (all rules ~15KB + 53 skill descriptions ~12KB ~= 6,750 tokens)
91
- ESTIMATED_UNROUTED_TOKENS = 6500
92
-
93
133
 
94
134
  def _find_repo_root() -> str:
95
135
  """Finds the root of Synapse-Hub repository."""
@@ -101,88 +141,114 @@ def _find_repo_root() -> str:
101
141
  return os.path.abspath(os.path.dirname(os.path.dirname(__file__)))
102
142
 
103
143
 
104
- def detect_workspace_stacks(workspace_dir: str) -> Dict[str, Any]:
105
- """
106
- Inspects workspace directory up to 2 levels deep to identify active tech stacks.
107
- Ignores heavy vendor and cache folders (.git, node_modules, build, etc.).
108
- """
109
- workspace = os.path.abspath(workspace_dir)
144
+ def _scan_directory_markers(target_dir: str, prefix: str = "") -> Tuple[Dict[str, List[str]], Dict[str, float]]:
145
+ """Scans a single directory level up to depth 2 for testing markers."""
110
146
  detected: Dict[str, List[str]] = {
111
147
  "playwright": [],
112
148
  "cypress": [],
113
149
  "mobile": [],
150
+ "katalon": [],
151
+ "selenium": [],
114
152
  "performance": [],
115
153
  "security": [],
116
154
  "api": [],
117
155
  "git": [],
118
156
  }
157
+ confidence: Dict[str, float] = {k: 0.0 for k in detected}
119
158
 
120
- if not os.path.isdir(workspace):
121
- return {"detected_stacks": [], "evidence": detected}
159
+ if not os.path.isdir(target_dir):
160
+ return detected, confidence
122
161
 
123
- # Fast check for git
124
- if os.path.isdir(os.path.join(workspace, ".git")):
125
- detected["git"].append(".git directory")
162
+ # Git marker
163
+ if os.path.isdir(os.path.join(target_dir, ".git")):
164
+ ev = f"{prefix}.git directory" if prefix else ".git directory"
165
+ detected["git"].append(ev)
166
+ confidence["git"] = max(confidence["git"], 1.0)
126
167
 
127
- # Read package.json / requirements / configs in root
128
- pkg_json = os.path.join(workspace, "package.json")
168
+ # 1. Inspect package.json
169
+ pkg_json = os.path.join(target_dir, "package.json")
129
170
  if os.path.isfile(pkg_json):
130
171
  try:
131
172
  with open(pkg_json, "r", encoding="utf-8", errors="ignore") as f:
132
173
  content = f.read().lower()
133
174
  if "playwright" in content or "@playwright/test" in content:
134
- detected["playwright"].append("package.json (playwright dependency)")
175
+ detected["playwright"].append(f"{prefix}package.json (playwright)")
176
+ confidence["playwright"] = max(confidence["playwright"], 0.90)
135
177
  if "cypress" in content:
136
- detected["cypress"].append("package.json (cypress dependency)")
178
+ detected["cypress"].append(f"{prefix}package.json (cypress)")
179
+ confidence["cypress"] = max(confidence["cypress"], 0.90)
137
180
  if "appium" in content:
138
- detected["mobile"].append("package.json (appium dependency)")
181
+ detected["mobile"].append(f"{prefix}package.json (appium)")
182
+ confidence["mobile"] = max(confidence["mobile"], 0.90)
183
+ if "selenium-webdriver" in content or "webdriverio" in content or "@wdio/" in content:
184
+ detected["selenium"].append(f"{prefix}package.json (selenium/wdio)")
185
+ confidence["selenium"] = max(confidence["selenium"], 0.90)
186
+ if "supertest" in content or "axios" in content or "pact" in content:
187
+ detected["api"].append(f"{prefix}package.json (api/contract)")
188
+ confidence["api"] = max(confidence["api"], 0.70)
139
189
  if "k6" in content or "artillery" in content:
140
- detected["performance"].append("package.json (perf dependency)")
190
+ detected["performance"].append(f"{prefix}package.json (perf)")
191
+ confidence["performance"] = max(confidence["performance"], 0.90)
141
192
  except Exception as err:
142
193
  _ = err
143
194
 
144
- # Read Python requirement / project config markers (requirements*.txt, pyproject.toml, Pipfile)
195
+ # 2. Inspect Python requirements / pyproject / Pipfile
145
196
  for py_cfg_name in ("requirements.txt", "requirements-dev.txt", "pyproject.toml", "Pipfile", "setup.py"):
146
- py_cfg = os.path.join(workspace, py_cfg_name)
197
+ py_cfg = os.path.join(target_dir, py_cfg_name)
147
198
  if os.path.isfile(py_cfg):
148
199
  try:
149
200
  with open(py_cfg, "r", encoding="utf-8", errors="ignore") as f:
150
201
  content = f.read().lower()
151
- if "playwright" in content or "pytest-playwright" in content:
152
- detected["playwright"].append(f"{py_cfg_name} (playwright dependency)")
153
- if "cypress" in content:
154
- detected["cypress"].append(f"{py_cfg_name} (cypress dependency)")
202
+ if "pytest-playwright" in content or "playwright" in content:
203
+ detected["playwright"].append(f"{prefix}{py_cfg_name} (playwright)")
204
+ confidence["playwright"] = max(confidence["playwright"], 0.90)
205
+ if "selenium" in content or "pytest-selenium" in content:
206
+ detected["selenium"].append(f"{prefix}{py_cfg_name} (selenium)")
207
+ confidence["selenium"] = max(confidence["selenium"], 0.90)
155
208
  if "appium" in content:
156
- detected["mobile"].append(f"{py_cfg_name} (appium dependency)")
209
+ detected["mobile"].append(f"{prefix}{py_cfg_name} (appium)")
210
+ confidence["mobile"] = max(confidence["mobile"], 0.90)
211
+ if any(pkg in content for pkg in ("requests", "httpx", "aiohttp", "fastapi", "pact-python")):
212
+ detected["api"].append(f"{prefix}{py_cfg_name} (api clients)")
213
+ confidence["api"] = max(confidence["api"], 0.80)
157
214
  if "locust" in content or "k6" in content:
158
- detected["performance"].append(f"{py_cfg_name} (performance dependency)")
215
+ detected["performance"].append(f"{prefix}{py_cfg_name} (perf)")
216
+ confidence["performance"] = max(confidence["performance"], 0.85)
159
217
  if "bandit" in content or "semgrep" in content:
160
- detected["security"].append(f"{py_cfg_name} (security dependency)")
218
+ detected["security"].append(f"{prefix}{py_cfg_name} (security)")
219
+ confidence["security"] = max(confidence["security"], 0.80)
161
220
  except Exception as err:
162
221
  _ = err
163
222
 
164
- # Read JVM build markers (build.gradle, build.gradle.kts, pom.xml)
223
+ # 3. Inspect JVM build markers (build.gradle, pom.xml)
165
224
  for jvm_cfg_name in ("build.gradle", "build.gradle.kts", "pom.xml"):
166
- jvm_cfg = os.path.join(workspace, jvm_cfg_name)
225
+ jvm_cfg = os.path.join(target_dir, jvm_cfg_name)
167
226
  if os.path.isfile(jvm_cfg):
168
227
  try:
169
228
  with open(jvm_cfg, "r", encoding="utf-8", errors="ignore") as f:
170
229
  content = f.read().lower()
171
230
  if "playwright" in content:
172
- detected["playwright"].append(f"{jvm_cfg_name} (playwright dependency)")
231
+ detected["playwright"].append(f"{prefix}{jvm_cfg_name} (playwright)")
232
+ confidence["playwright"] = max(confidence["playwright"], 0.90)
233
+ if "selenium" in content:
234
+ detected["selenium"].append(f"{prefix}{jvm_cfg_name} (selenium)")
235
+ confidence["selenium"] = max(confidence["selenium"], 0.90)
173
236
  if "appium" in content:
174
- detected["mobile"].append(f"{jvm_cfg_name} (appium dependency)")
237
+ detected["mobile"].append(f"{prefix}{jvm_cfg_name} (appium)")
238
+ confidence["mobile"] = max(confidence["mobile"], 0.90)
239
+ if "rest-assured" in content or "pact" in content:
240
+ detected["api"].append(f"{prefix}{jvm_cfg_name} (api)")
241
+ confidence["api"] = max(confidence["api"], 0.85)
175
242
  if "jmeter" in content or "gatling" in content:
176
- detected["performance"].append(f"{jvm_cfg_name} (performance dependency)")
177
- if "pact" in content or "rest-assured" in content:
178
- detected["api"].append(f"{jvm_cfg_name} (api contract dependency)")
243
+ detected["performance"].append(f"{prefix}{jvm_cfg_name} (perf)")
244
+ confidence["performance"] = max(confidence["performance"], 0.85)
179
245
  except Exception as err:
180
246
  _ = err
181
247
 
182
- # Scan files up to depth 2
248
+ # 4. Walk directory structure up to depth 2
183
249
  ignored = {".git", "node_modules", ".venv", "venv", "__pycache__", "dist", "build", "target", ".gradle"}
184
- for root, dirs, files in os.walk(workspace):
185
- rel = os.path.relpath(root, workspace)
250
+ for root, dirs, files in os.walk(target_dir):
251
+ rel = os.path.relpath(root, target_dir)
186
252
  depth = 0 if rel == "." else len(rel.split(os.sep))
187
253
  if depth >= 2:
188
254
  dirs.clear()
@@ -192,47 +258,143 @@ def detect_workspace_stacks(workspace_dir: str) -> Dict[str, Any]:
192
258
  for file_name in files:
193
259
  f_lower = file_name.lower()
194
260
  rel_file = os.path.join(rel, file_name) if rel != "." else file_name
261
+ full_evidence_path = f"{prefix}{rel_file}" if prefix else rel_file
262
+
263
+ # Katalon markers
264
+ if f_lower.endswith(".prj") or f_lower == "katalon_suite.prj":
265
+ detected["katalon"].append(full_evidence_path)
266
+ confidence["katalon"] = max(confidence["katalon"], 1.0)
195
267
 
196
268
  # Playwright markers
197
269
  if f_lower.startswith("playwright.config."):
198
- detected["playwright"].append(rel_file)
270
+ detected["playwright"].append(full_evidence_path)
271
+ confidence["playwright"] = max(confidence["playwright"], 1.0)
199
272
 
200
273
  # Cypress markers
201
274
  if f_lower.startswith("cypress.config.") or f_lower == "cypress.json":
202
- detected["cypress"].append(rel_file)
275
+ detected["cypress"].append(full_evidence_path)
276
+ confidence["cypress"] = max(confidence["cypress"], 1.0)
277
+
278
+ # Selenium markers
279
+ if f_lower.startswith("wdio.conf.") or f_lower in ("selenium.json", "pytest.ini"):
280
+ # If pytest.ini, inspect content for selenium
281
+ if f_lower == "pytest.ini":
282
+ try:
283
+ with open(os.path.join(root, file_name), "r", encoding="utf-8", errors="ignore") as pf:
284
+ if "selenium" in pf.read().lower():
285
+ detected["selenium"].append(full_evidence_path)
286
+ confidence["selenium"] = max(confidence["selenium"], 0.80)
287
+ except Exception as err:
288
+ _ = err
289
+ else:
290
+ detected["selenium"].append(full_evidence_path)
291
+ confidence["selenium"] = max(confidence["selenium"], 0.95)
203
292
 
204
293
  # Mobile markers
205
294
  if f_lower in ("caps.json", "androidmanifest.xml") or f_lower.endswith(".xcodeproj"):
206
- detected["mobile"].append(rel_file)
295
+ detected["mobile"].append(full_evidence_path)
296
+ confidence["mobile"] = max(confidence["mobile"], 0.95)
207
297
 
208
298
  # Performance markers
209
299
  if f_lower.endswith(".jmx") or f_lower == "locustfile.py" or ".k6." in f_lower or f_lower == "k6.js":
210
- detected["performance"].append(rel_file)
300
+ detected["performance"].append(full_evidence_path)
301
+ confidence["performance"] = max(confidence["performance"], 1.0)
211
302
 
212
303
  # Security markers
213
304
  if any(k in f_lower for k in ("zap", "burp", "nuclei", "semgrep.yml")):
214
- detected["security"].append(rel_file)
305
+ detected["security"].append(full_evidence_path)
306
+ confidence["security"] = max(confidence["security"], 0.90)
215
307
 
216
308
  # API markers
217
309
  if f_lower in ("openapi.json", "openapi.yaml", "swagger.json", "swagger.yaml") or f_lower.endswith(".pact.json"):
218
- detected["api"].append(rel_file)
310
+ detected["api"].append(full_evidence_path)
311
+ confidence["api"] = max(confidence["api"], 1.0)
312
+
313
+ # conftest.py check for api / selenium fixtures
314
+ if f_lower == "conftest.py":
315
+ try:
316
+ with open(os.path.join(root, file_name), "r", encoding="utf-8", errors="ignore") as cf:
317
+ ct = cf.read().lower()
318
+ if "requests" in ct or "client" in ct or "base_url" in ct or "api" in ct:
319
+ detected["api"].append(full_evidence_path)
320
+ confidence["api"] = max(confidence["api"], 0.75)
321
+ if "selenium" in ct or "webdriver" in ct:
322
+ detected["selenium"].append(full_evidence_path)
323
+ confidence["selenium"] = max(confidence["selenium"], 0.80)
324
+ except Exception as err:
325
+ _ = err
326
+
327
+ # Directory-level markers (Katalon Keywords/Profiles)
328
+ for d in dirs:
329
+ if d.lower() in ("keywords", "profiles", "object repository"):
330
+ detected["katalon"].append(f"{prefix}{os.path.join(rel, d) if rel != '.' else d}/")
331
+ confidence["katalon"] = max(confidence["katalon"], 0.85)
332
+
333
+ return detected, confidence
334
+
335
+
336
+ def detect_workspace_stacks(workspace_dir: str) -> Dict[str, Any]:
337
+ """
338
+ Inspects target workspace directory, supporting standalone projects and Monorepos.
339
+ Calculates confidence scores for detected testing stacks.
340
+ """
341
+ workspace = os.path.abspath(workspace_dir)
342
+ detected, confidence = _scan_directory_markers(workspace)
343
+
344
+ # Monorepo check at root
345
+ monorepo_markers = ["pnpm-workspace.yaml", "lerna.json", "nx.json", "turbo.json"]
346
+ is_monorepo = any(os.path.isfile(os.path.join(workspace, m)) for m in monorepo_markers)
347
+
348
+ if not is_monorepo:
349
+ # Check settings.gradle for multi-project include
350
+ sg = os.path.join(workspace, "settings.gradle")
351
+ if os.path.isfile(sg):
352
+ try:
353
+ with open(sg, "r", encoding="utf-8", errors="ignore") as f:
354
+ if "include" in f.read().lower():
355
+ is_monorepo = True
356
+ except Exception as err:
357
+ _ = err
358
+
359
+ if is_monorepo:
360
+ # Traverse subpackages in packages/, apps/, services/, modules/
361
+ for sub_parent in ("packages", "apps", "services", "modules"):
362
+ parent_dir = os.path.join(workspace, sub_parent)
363
+ if os.path.isdir(parent_dir):
364
+ try:
365
+ for child in os.listdir(parent_dir):
366
+ child_dir = os.path.join(parent_dir, child)
367
+ if os.path.isdir(child_dir) and not child.startswith("."):
368
+ prefix = f"[{sub_parent}/{child}] "
369
+ sub_det, sub_conf = _scan_directory_markers(child_dir, prefix=prefix)
370
+ for stack, evs in sub_det.items():
371
+ detected[stack].extend(evs)
372
+ confidence[stack] = max(confidence[stack], sub_conf[stack])
373
+ except OSError as err:
374
+ _ = err
375
+
376
+ # Filter active stacks where confidence >= 0.50
377
+ active_stacks = [s for s, evs in detected.items() if evs and confidence[s] >= 0.50]
219
378
 
220
- active_stacks = [stack for stack, evidence in detected.items() if evidence]
221
379
  return {
222
380
  "detected_stacks": active_stacks,
223
- "evidence": {k: v for k, v in detected.items() if v},
381
+ "is_monorepo": is_monorepo,
382
+ "confidence": {k: round(confidence[k], 2) for k in active_stacks},
383
+ "evidence": {k: detected[k] for k in active_stacks},
224
384
  }
225
385
 
226
386
 
227
387
  def route_rules(workspace_dir: str = ".") -> Dict[str, Any]:
228
388
  """
229
- Determines the minimal set of rules and skills for the target workspace.
230
- Calculates estimated tokens consumed versus the unrouted baseline.
389
+ Determines minimal rules and skills for target workspace, with dual-tier token hydration
390
+ accounting and strict truth-anchoring for unknown stacks.
231
391
  """
232
392
  repo_root = _find_repo_root()
233
393
  stack_info = detect_workspace_stacks(workspace_dir)
234
394
  active_stacks = stack_info["detected_stacks"]
235
395
 
396
+ is_unknown_stack = len(active_stacks) == 0
397
+
236
398
  # Compile rules
237
399
  rules_set: Set[str] = set(CORE_BASE_RULES)
238
400
  for stack in active_stacks:
@@ -245,57 +407,110 @@ def route_rules(workspace_dir: str = ".") -> Dict[str, Any]:
245
407
  for s in STACK_SKILL_MAPPINGS.get(stack, []):
246
408
  skills_set.add(s)
247
409
 
248
- # Ensure rule files exist in .agents/rules
410
+ # Resolve rules directory
249
411
  rules_dir = os.path.join(repo_root, ".agents", "rules")
250
- valid_rules: List[str] = []
251
- total_rule_bytes = 0
412
+ valid_rules = sorted(rules_set)
413
+ valid_skills = sorted(skills_set)
252
414
 
253
- for r in sorted(rules_set):
254
- rule_path = os.path.join(rules_dir, r)
255
- if os.path.isfile(rule_path):
256
- valid_rules.append(r)
257
- try:
258
- total_rule_bytes += os.path.getsize(rule_path)
259
- except OSError:
260
- total_rule_bytes += 2000
261
- else:
262
- valid_rules.append(r)
263
- total_rule_bytes += 2000
264
-
265
- # Dynamic calculation of unrouted baseline from actual rules directory + 53 skill catalogue
266
- unrouted_rule_bytes = 0
415
+ # Calculate dual-tier hydration payloads
416
+ routed_payload = calculate_hydration_payload(repo_root, valid_rules, valid_skills)
417
+
418
+ # Calculate full unrouted baseline (all rules in .agents/rules + all 53 skills in catalogue)
419
+ all_rules_in_repo: List[str] = []
267
420
  if os.path.isdir(rules_dir):
268
- for f in os.listdir(rules_dir):
421
+ for f in sorted(os.listdir(rules_dir)):
269
422
  if f.endswith(".md"):
270
- try:
271
- unrouted_rule_bytes += os.path.getsize(os.path.join(rules_dir, f))
272
- except OSError:
273
- unrouted_rule_bytes += 2500
274
- else:
275
- unrouted_rule_bytes = 30000
276
-
277
- unrouted_baseline = (unrouted_rule_bytes // CHARS_PER_TOKEN) + (53 * 120)
278
- unrouted_baseline = max(unrouted_baseline, ESTIMATED_UNROUTED_TOKENS)
279
-
280
- # Skill tokens (~120 tokens per skill metadata summary)
281
- skill_tokens = len(skills_set) * 120
282
- rule_tokens = total_rule_bytes // CHARS_PER_TOKEN
283
- total_routed_tokens = rule_tokens + skill_tokens
284
-
285
- # Ensure estimated savings calculation
286
- tokens_saved = max(0, unrouted_baseline - total_routed_tokens)
423
+ all_rules_in_repo.append(f)
424
+ if not all_rules_in_repo:
425
+ all_rules_in_repo = valid_rules
426
+
427
+ # Benchmark catalogue baseline: 53 skills
428
+ unrouted_rule_payload = calculate_hydration_payload(repo_root, all_rules_in_repo, [])
429
+ unrouted_rules_tokens = unrouted_rule_payload["rule_tokens"]
430
+ unrouted_rules_bytes = unrouted_rule_payload["rule_bytes"]
431
+
432
+ # Catalog summary baseline: all rules + 53 skill summaries (~120 tokens each)
433
+ unrouted_summary_baseline = unrouted_rules_tokens + (53 * 120)
434
+ # Full body baseline: all rules + 53 skills with full SKILL.md bodies (~65,000+ tokens)
435
+ unrouted_full_baseline = unrouted_rules_tokens + (53 * 1800)
436
+
437
+ # If workspace is unclassified (no stack detected), report honest fallback metrics
438
+ if is_unknown_stack:
439
+ return {
440
+ "workspace": os.path.abspath(workspace_dir),
441
+ "status": "UNCLASSIFIED_WORKSPACE",
442
+ "detected_stacks": ["unknown"],
443
+ "classification": "UNCLASSIFIED_WORKSPACE (Fallback Core Base Rules)",
444
+ "confidence_score": 0.0,
445
+ "evidence": {},
446
+ "recommended_rules": valid_rules,
447
+ "recommended_skills": valid_skills,
448
+ "token_metrics": {
449
+ "unrouted_baseline_tokens": unrouted_summary_baseline,
450
+ "routed_tokens": routed_payload["total_summary_tokens"],
451
+ "tokens_saved": 0,
452
+ "reduction_percentage": 0.0,
453
+ "note": "Stack unclassified; routed to core base profile without claiming workload-specific token reduction.",
454
+ },
455
+ "hydration_contracts": {
456
+ "catalog_summary": {
457
+ "baseline_tokens": unrouted_summary_baseline,
458
+ "routed_tokens": routed_payload["total_summary_tokens"],
459
+ "tokens_saved": 0,
460
+ "reduction_pct": 0.0,
461
+ },
462
+ "full_hydration": {
463
+ "baseline_tokens": unrouted_full_baseline,
464
+ "routed_tokens": routed_payload["total_hydrated_tokens"],
465
+ "tokens_saved": 0,
466
+ "reduction_pct": 0.0,
467
+ },
468
+ },
469
+ }
470
+
471
+ # Classified stacks: compute honest savings for both tiers
472
+ summary_saved = max(0, unrouted_summary_baseline - routed_payload["total_summary_tokens"])
473
+ summary_pct = round((summary_saved / max(1, unrouted_summary_baseline)) * 100, 1)
474
+
475
+ hydrated_saved = max(0, unrouted_full_baseline - routed_payload["total_hydrated_tokens"])
476
+ hydrated_pct = round((hydrated_saved / max(1, unrouted_full_baseline)) * 100, 1)
477
+
478
+ avg_conf = sum(stack_info["confidence"].values()) / max(1, len(stack_info["confidence"]))
287
479
 
288
480
  return {
289
481
  "workspace": os.path.abspath(workspace_dir),
482
+ "status": "CLASSIFIED",
290
483
  "detected_stacks": active_stacks,
484
+ "classification": f"CLASSIFIED ({', '.join(active_stacks)})",
485
+ "confidence_score": round(avg_conf, 2),
291
486
  "evidence": stack_info["evidence"],
292
487
  "recommended_rules": valid_rules,
293
- "recommended_skills": sorted(skills_set),
488
+ "recommended_skills": valid_skills,
294
489
  "token_metrics": {
295
- "unrouted_baseline_tokens": unrouted_baseline,
296
- "routed_tokens": total_routed_tokens,
297
- "tokens_saved": tokens_saved,
298
- "reduction_percentage": round((tokens_saved / unrouted_baseline) * 100, 1),
490
+ "unrouted_baseline_tokens": unrouted_summary_baseline,
491
+ "routed_tokens": routed_payload["total_summary_tokens"],
492
+ "tokens_saved": summary_saved,
493
+ "reduction_percentage": summary_pct,
494
+ },
495
+ "hydration_contracts": {
496
+ "catalog_summary": {
497
+ "baseline_tokens": unrouted_summary_baseline,
498
+ "routed_tokens": routed_payload["total_summary_tokens"],
499
+ "tokens_saved": summary_saved,
500
+ "reduction_pct": summary_pct,
501
+ "scope": "Skill registry metadata for Front-Door Orchestrator",
502
+ },
503
+ "full_hydration": {
504
+ "baseline_tokens": unrouted_full_baseline,
505
+ "routed_tokens": routed_payload["total_hydrated_tokens"],
506
+ "tokens_saved": hydrated_saved,
507
+ "reduction_pct": hydrated_pct,
508
+ "scope": "Complete SKILL.md bodies injected into Specialized Subagents",
509
+ },
510
+ "retrieval_footprint": {
511
+ "routed_hydrated_bytes": routed_payload["total_hydrated_bytes"],
512
+ "avoided_bytes": max(0, (unrouted_rules_bytes + 53 * 7500) - routed_payload["total_hydrated_bytes"]),
513
+ },
299
514
  },
300
515
  }
301
516
 
@@ -306,14 +521,16 @@ def format_routing_report(result: Dict[str, Any], fmt: str = "text") -> str:
306
521
  return json.dumps(result, indent=2, ensure_ascii=False)
307
522
 
308
523
  metrics = result["token_metrics"]
309
- stacks_str = ", ".join(result["detected_stacks"]) if result["detected_stacks"] else "Standard QA / Clean POM"
524
+ stacks_str = ", ".join(result["detected_stacks"]) if result["detected_stacks"] else "unknown"
525
+ conf = result.get("confidence_score", 0.0)
310
526
 
311
527
  lines = [
312
528
  "╔══════════════════════════════════════════════════════════════════╗",
313
529
  "║ SYNAPSE HUB — PROGRESSIVE RULES ROUTER (BOOST B2) ║",
314
530
  "╚══════════════════════════════════════════════════════════════════╝",
315
531
  f"Target Workspace: {result['workspace']}",
316
- f"Active Stacks : {stacks_str}",
532
+ f"Active Stacks : {stacks_str} (Confidence: {conf})",
533
+ f"Status : {result['status']}",
317
534
  "",
318
535
  "─── Minimal Recommended Rules ───",
319
536
  ]
@@ -326,10 +543,16 @@ def format_routing_report(result: Dict[str, Any], fmt: str = "text") -> str:
326
543
  lines.append(f" ⚡ {s}")
327
544
 
328
545
  lines.append("")
329
- lines.append("─── Token Optimization Metrics ───")
330
- lines.append(f" Unrouted Baseline : {metrics['unrouted_baseline_tokens']:,} tokens")
331
- lines.append(f" Progressive Routed: {metrics['routed_tokens']:,} tokens")
332
- lines.append(f" Tokens Saved/Turn : {metrics['tokens_saved']:,} tokens ({metrics['reduction_percentage']}%)")
546
+ lines.append("─── Dual-Tier Token Optimization Metrics ───")
547
+ if "hydration_contracts" in result:
548
+ cat = result["hydration_contracts"]["catalog_summary"]
549
+ hyd = result["hydration_contracts"]["full_hydration"]
550
+ lines.append(f" [Tier 1 - Catalog Summary] Baseline: {cat['baseline_tokens']:,} | Routed: {cat['routed_tokens']:,} | Saved: {cat['tokens_saved']:,} ({cat['reduction_pct']}%)")
551
+ lines.append(f" [Tier 2 - Full Hydration ] Baseline: {hyd['baseline_tokens']:,} | Routed: {hyd['routed_tokens']:,} | Saved: {hyd['tokens_saved']:,} ({hyd['reduction_pct']}%)")
552
+ else:
553
+ lines.append(f" Unrouted Baseline : {metrics['unrouted_baseline_tokens']:,} tokens")
554
+ lines.append(f" Progressive Routed: {metrics['routed_tokens']:,} tokens")
555
+ lines.append(f" Tokens Saved/Turn : {metrics['tokens_saved']:,} tokens ({metrics['reduction_percentage']}%)")
333
556
  lines.append("════════════════════════════════════════════════════════════════════")
334
557
 
335
558
  return "\n".join(lines)