@teevee98/synapse-hub 0.0.0-stage → 3.8.3

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 (369) hide show
  1. package/.agents/agents/api-engineer.md +67 -0
  2. package/.agents/agents/failure-analyst.md +75 -0
  3. package/.agents/agents/live-explorer.md +70 -0
  4. package/.agents/agents/orchestrator.md +104 -0
  5. package/.agents/agents/perf-engineer.md +74 -0
  6. package/.agents/agents/pom-crafter.md +112 -0
  7. package/.agents/agents/quality-gatekeeper.md +87 -0
  8. package/.agents/agents/test-designer.md +73 -0
  9. package/.agents/agents/test-runner.md +67 -0
  10. package/.agents/rules/author-integrity-guard.md +33 -0
  11. package/.agents/rules/communication-style.md +18 -0
  12. package/.agents/rules/context-engineering.md +37 -0
  13. package/.agents/rules/git-push-protocol.md +33 -0
  14. package/.agents/rules/graphify.md +14 -0
  15. package/.agents/rules/lessons-learned.md +25 -0
  16. package/.agents/rules/mandatory-playwright-live.md +25 -0
  17. package/.agents/rules/mobile_appium_rules.md +43 -0
  18. package/.agents/rules/performance_testing_rules.md +35 -0
  19. package/.agents/rules/skill-precedence.md +29 -0
  20. package/.agents/rules/systematic-debugging.md +36 -0
  21. package/.agents/skills/actor-qa-swarm/SKILL.md +77 -0
  22. package/.agents/skills/actor-qa-swarm/examples/broker_sharding_sample.json +12 -0
  23. package/.agents/skills/agent-orchestration-multi-agent-optimize/SKILL.md +88 -0
  24. package/.agents/skills/agent-orchestration-multi-agent-optimize/examples/swarm_workload_config.json +15 -0
  25. package/.agents/skills/agentless-qa-repair/SKILL.md +69 -0
  26. package/.agents/skills/agentless-qa-repair/examples/healing_report_sample.json +17 -0
  27. package/.agents/skills/agentless-qa-repair/examples/three_phase_repair_workflow.md +40 -0
  28. package/.agents/skills/antigravity-test-sentinel/SKILL.md +63 -0
  29. package/.agents/skills/antigravity-test-sentinel/examples/dod_gate_policy.json +11 -0
  30. package/.agents/skills/antigravity-test-sentinel/examples/sprint_dod_enforcement.md +47 -0
  31. package/.agents/skills/api-network-mocking-interception/SKILL.md +142 -0
  32. package/.agents/skills/api-network-mocking-interception/examples/network_route_stub.json +9 -0
  33. package/.agents/skills/api-spec-to-e2e-matrix/SKILL.md +80 -0
  34. package/.agents/skills/api-spec-to-e2e-matrix/examples/sample_openapi.json +19 -0
  35. package/.agents/skills/architecture-decision-records/SKILL.md +64 -0
  36. package/.agents/skills/architecture-decision-records/examples/0001-record-architecture-decisions.md +12 -0
  37. package/.agents/skills/auth-session-and-cookie-manager/SKILL.md +75 -0
  38. package/.agents/skills/auth-session-and-cookie-manager/examples/multi_role_auth_matrix.md +70 -0
  39. package/.agents/skills/auth-session-and-cookie-manager/examples/storage_state_sample.json +11 -0
  40. package/.agents/skills/backend-load-and-stress-patterns/SKILL.md +85 -0
  41. package/.agents/skills/backend-load-and-stress-patterns/examples/k6_load_test_sample.js +13 -0
  42. package/.agents/skills/backend-load-and-stress-patterns/references/k6_load_template.js +82 -0
  43. package/.agents/skills/bats-testing-patterns/SKILL.md +100 -0
  44. package/.agents/skills/bats-testing-patterns/examples/cli_runner_test.bats +6 -0
  45. package/.agents/skills/bats-testing-patterns/resources/implementation-playbook.md +614 -0
  46. package/.agents/skills/clean-pom-crafter/SKILL.md +110 -0
  47. package/.agents/skills/clean-pom-crafter/examples/standard_test_case.groovy +28 -0
  48. package/.agents/skills/clean-pom-crafter/references/pom_patterns.groovy +138 -0
  49. package/.agents/skills/code-refactoring-refactor-clean/SKILL.md +64 -0
  50. package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_page_sample.groovy +9 -0
  51. package/.agents/skills/code-refactoring-refactor-clean/examples/refactored_playwright_pom.ts +52 -0
  52. package/.agents/skills/code-refactoring-refactor-clean/resources/implementation-playbook.md +881 -0
  53. package/.agents/skills/consumer-driven-contract-testing/SKILL.md +147 -0
  54. package/.agents/skills/consumer-driven-contract-testing/examples/order_service_pact.json +45 -0
  55. package/.agents/skills/db-state-verifier-and-seeder/SKILL.md +123 -0
  56. package/.agents/skills/db-state-verifier-and-seeder/examples/db_fixture_seed.json +12 -0
  57. package/.agents/skills/e2e-testing-patterns/SKILL.md +103 -0
  58. package/.agents/skills/e2e-testing-patterns/examples/playwright_sharded_config.ts +12 -0
  59. package/.agents/skills/e2e-testing-patterns/resources/implementation-playbook.md +522 -0
  60. package/.agents/skills/event-stream-qa-orchestrator/SKILL.md +79 -0
  61. package/.agents/skills/event-stream-qa-orchestrator/examples/timeline_sample.jsonl +2 -0
  62. package/.agents/skills/failure-autopsy-and-healing/SKILL.md +66 -0
  63. package/.agents/skills/failure-autopsy-and-healing/examples/closed_loop_healing_walkthrough.md +48 -0
  64. package/.agents/skills/failure-autopsy-and-healing/examples/sample_junit_failure.xml +8 -0
  65. package/.agents/skills/failure-autopsy-and-healing/references/healing_matrix.md +64 -0
  66. package/.agents/skills/failure-autopsy-and-healing/references/qa_investigation_protocol.md +56 -0
  67. package/.agents/skills/failure-autopsy-and-healing/scripts/triage_failures.sh +83 -0
  68. package/.agents/skills/file-and-report-validator/SKILL.md +90 -0
  69. package/.agents/skills/file-and-report-validator/examples/sample_export_schema.json +14 -0
  70. package/.agents/skills/flaky-test-sentinel-and-quarantine/SKILL.md +114 -0
  71. package/.agents/skills/flaky-test-sentinel-and-quarantine/examples/quarantine_registry.json +11 -0
  72. package/.agents/skills/gherkin-to-suite/SKILL.md +103 -0
  73. package/.agents/skills/gherkin-to-suite/examples/checkout.feature +39 -0
  74. package/.agents/skills/gherkin-to-suite/examples/suite_report_sample.json +334 -0
  75. package/.agents/skills/github-actions-templates/SKILL.md +77 -0
  76. package/.agents/skills/github-actions-templates/examples/matrix_test_pipeline.yml +8 -0
  77. package/.agents/skills/graphify-impact-analyzer/SKILL.md +76 -0
  78. package/.agents/skills/graphify-impact-analyzer/examples/dependency_blast_radius.json +8 -0
  79. package/.agents/skills/katalon-cli-runner/SKILL.md +76 -0
  80. package/.agents/skills/katalon-cli-runner/examples/headless_kre_exec.sh +3 -0
  81. package/.agents/skills/katalon-cli-runner/references/groovy-patterns.md +209 -0
  82. package/.agents/skills/katalon-cli-runner/references/katalon-api.md +155 -0
  83. package/.agents/skills/katalon-cli-runner/references/runner_commands.md +67 -0
  84. package/.agents/skills/lam-script-generator/SKILL.md +123 -0
  85. package/.agents/skills/lam-script-generator/examples/user_story_sample.md +8 -0
  86. package/.agents/skills/lean-code-ladder/SKILL.md +94 -0
  87. package/.agents/skills/lean-code-ladder/examples/ladder_walkthrough.md +37 -0
  88. package/.agents/skills/lean-impact-scoreboard/SKILL.md +48 -0
  89. package/.agents/skills/lean-impact-scoreboard/examples/sample_benchmark_gain.md +20 -0
  90. package/.agents/skills/lean-impact-scoreboard/examples/sample_scoreboard.md +15 -0
  91. package/.agents/skills/meta-prompt-crafter/SKILL.md +107 -0
  92. package/.agents/skills/meta-prompt-crafter/examples/qa_prompt_template.md +35 -0
  93. package/.agents/skills/mipro-prompt-compiler/SKILL.md +59 -0
  94. package/.agents/skills/mipro-prompt-compiler/examples/compiled_module_sample.json +22 -0
  95. package/.agents/skills/mipro-prompt-compiler/examples/dspy_assertion_optimizer_case.md +46 -0
  96. package/.agents/skills/mobile-appium-som/SKILL.md +88 -0
  97. package/.agents/skills/mobile-appium-som/examples/BaseScreen.java +88 -0
  98. package/.agents/skills/mobile-appium-som/examples/LoginScreen.java +46 -0
  99. package/.agents/skills/mobile-appium-som/examples/TC_MobileLogin.java +43 -0
  100. package/.agents/skills/persistent-planning-files/SKILL.md +108 -0
  101. package/.agents/skills/persistent-planning-files/examples/task_plan_example.md +56 -0
  102. package/.agents/skills/playwright-live-interaction/SKILL.md +131 -0
  103. package/.agents/skills/playwright-live-interaction/examples/live_probe_script.js +5 -0
  104. package/.agents/skills/playwright-live-interaction/references/advanced_superpowers.md +160 -0
  105. package/.agents/skills/playwright-live-interaction/references/compact_accessibility_snapshots.md +75 -0
  106. package/.agents/skills/playwright-live-interaction/references/recipes.md +388 -0
  107. package/.agents/skills/playwright-live-interaction/references/swarm_orchestration.md +134 -0
  108. package/.agents/skills/playwright-webapp-testing/SKILL.md +93 -0
  109. package/.agents/skills/playwright-webapp-testing/examples/server_lifecycle_playwright.py +63 -0
  110. package/.agents/skills/qa-aci-interface/SKILL.md +67 -0
  111. package/.agents/skills/qa-aci-interface/examples/surgical_code_window_walkthrough.md +40 -0
  112. package/.agents/skills/qa-aci-interface/examples/surgical_edit_sample.json +12 -0
  113. package/.agents/skills/qa-memory-os/SKILL.md +80 -0
  114. package/.agents/skills/qa-memory-os/examples/archival_memory_sample.json +21 -0
  115. package/.agents/skills/rbt-manual-testing/SKILL.md +137 -0
  116. package/.agents/skills/rbt-manual-testing/examples/checkout_rbt_manual_suite.md +25 -0
  117. package/.agents/skills/rbt-manual-testing/references/field_validation_checklist.md +29 -0
  118. package/.agents/skills/repo-quality-audit/SKILL.md +68 -0
  119. package/.agents/skills/repo-quality-audit/examples/sample_audit_walkthrough.md +15 -0
  120. package/.agents/skills/repo-quality-audit/examples/sample_repo_audit.md +33 -0
  121. package/.agents/skills/review-spec/SKILL.md +60 -0
  122. package/.agents/skills/review-spec/examples/pocock_grilling_decision_rubric.md +40 -0
  123. package/.agents/skills/review-spec/examples/sample_spec_review.md +33 -0
  124. package/.agents/skills/security-dast-sentinel/SKILL.md +119 -0
  125. package/.agents/skills/security-dast-sentinel/examples/dast_scan_config.json +10 -0
  126. package/.agents/skills/security-dast-sentinel/references/AI-AND-LLM.md +113 -0
  127. package/.agents/skills/security-dast-sentinel/references/ATTACK-CLASSES.md +89 -0
  128. package/.agents/skills/security-dast-sentinel/references/dast_recipes.ts +33 -0
  129. package/.agents/skills/self-healing-locator/SKILL.md +86 -0
  130. package/.agents/skills/self-healing-locator/examples/aom_diff_sample.json +16 -0
  131. package/.agents/skills/senior-code-review/SKILL.md +108 -0
  132. package/.agents/skills/senior-code-review/examples/sample_review_walkthrough.md +29 -0
  133. package/.agents/skills/skillspector-security-guard/SKILL.md +57 -0
  134. package/.agents/skills/skillspector-security-guard/examples/audit_threat_vectors_report.json +35 -0
  135. package/.agents/skills/skillspector-security-guard/examples/safe_mcp_config.json +12 -0
  136. package/.agents/skills/surgical-coding-principles/SKILL.md +89 -0
  137. package/.agents/skills/surgical-coding-principles/examples/surgical_vs_scope_creep.md +46 -0
  138. package/.agents/skills/synthetic-test-data-generator/SKILL.md +135 -0
  139. package/.agents/skills/synthetic-test-data-generator/examples/idempotent_data_recipe.json +9 -0
  140. package/.agents/skills/systematic-debugging/SKILL.md +100 -0
  141. package/.agents/skills/systematic-debugging/examples/four_phase_case.md +44 -0
  142. package/.agents/skills/technical-debt-harvester/SKILL.md +70 -0
  143. package/.agents/skills/technical-debt-harvester/examples/sample_debt_ledger.md +25 -0
  144. package/.agents/skills/technical-debt-harvester/examples/sample_ledger_output.md +20 -0
  145. package/.agents/skills/test-driven-development/SKILL.md +114 -0
  146. package/.agents/skills/test-driven-development/examples/red_green_refactor_qa.md +78 -0
  147. package/.agents/skills/token-and-context-optimizer/SKILL.md +70 -0
  148. package/.agents/skills/token-and-context-optimizer/examples/distilled_log_sample.txt +3 -0
  149. package/.agents/skills/token-and-context-optimizer/references/context_engineering_guide.md +49 -0
  150. package/.agents/skills/tot-exploratory-testing/SKILL.md +59 -0
  151. package/.agents/skills/tot-exploratory-testing/examples/payment_gateway_tot_tree.json +62 -0
  152. package/.agents/skills/tot-exploratory-testing/examples/tot_graph_sample.json +35 -0
  153. package/.agents/skills/verification-before-completion/SKILL.md +100 -0
  154. package/.agents/skills/verification-before-completion/examples/evidence_log_example.md +46 -0
  155. package/.agents/skills/visual-regression-sentinel/SKILL.md +82 -0
  156. package/.agents/skills/visual-regression-sentinel/examples/visual_mask_rules.json +9 -0
  157. package/.agents/skills/wcag-audit-patterns/SKILL.md +77 -0
  158. package/.agents/skills/wcag-audit-patterns/examples/wcag_compliance_checklist.json +10 -0
  159. package/.agents/skills/wcag-audit-patterns/resources/implementation-playbook.md +541 -0
  160. package/.agents/skills/web-agent-gym-benchmarking/SKILL.md +62 -0
  161. package/.agents/skills/web-agent-gym-benchmarking/examples/benchmark_report_sample.json +22 -0
  162. package/.agents/skills/web-agent-gym-benchmarking/examples/enterprise_tasks_suite.json +38 -0
  163. package/.agents/skills/web-vitals-and-performance-profiler/SKILL.md +65 -0
  164. package/.agents/skills/web-vitals-and-performance-profiler/examples/cwv_budget_policy.json +6 -0
  165. package/.agents/skills/web-vitals-and-performance-profiler/examples/playwright_cwv_profiler_fixture.ts +118 -0
  166. package/.agents/templates/completion_report.md +57 -0
  167. package/.agents/workflows/analyze_requirement_document.md +18 -0
  168. package/.agents/workflows/export_testcases_excel.md +32 -0
  169. package/.agents/workflows/generate_combinatorial_test_data.md +28 -0
  170. package/.agents/workflows/generate_cross_module_test_plan.md +37 -0
  171. package/.agents/workflows/generate_manual_testcases_rbt.md +56 -0
  172. package/.agents/workflows/generate_requirements_from_website.md +25 -0
  173. package/.agents/workflows/generate_testcases_from_requirements.md +21 -0
  174. package/.agents/workflows/graphify.md +10 -0
  175. package/.agents/workflows/test-impact.md +15 -0
  176. package/.agents/workflows/verify.md +34 -0
  177. package/.cursor/rules/agents.mdc +16 -0
  178. package/.cursor/rules/language.mdc +7 -0
  179. package/.cursor/rules/synapse-qa.mdc +24 -0
  180. package/.cursorrules +27 -0
  181. package/.dockerignore +53 -0
  182. package/.pre-commit-hooks.yaml +14 -0
  183. package/.windsurfrules +26 -0
  184. package/AGENTS.md +86 -0
  185. package/CLAUDE.md +54 -0
  186. package/Dockerfile +81 -0
  187. package/LICENSE +52 -0
  188. package/NOTICE +264 -0
  189. package/README.en.md +171 -0
  190. package/README.md +170 -2
  191. package/action.yml +51 -0
  192. package/agentskills.json +16 -0
  193. package/bin/agent-qa.js +138 -0
  194. package/docker-compose.yml +74 -0
  195. package/docs/ARCHITECTURE.en.md +198 -0
  196. package/docs/ARCHITECTURE.md +199 -0
  197. package/docs/CI_CD_INTEGRATION.en.md +170 -0
  198. package/docs/CI_CD_INTEGRATION.md +170 -0
  199. package/docs/CLI_REFERENCE.en.md +174 -0
  200. package/docs/CLI_REFERENCE.md +176 -0
  201. package/docs/CONTRIBUTING.en.md +49 -0
  202. package/docs/CONTRIBUTING.md +49 -0
  203. package/docs/PERFORMANCE_AUDIT_REPORT.md +783 -0
  204. package/docs/PLUGIN_DEVELOPMENT_GUIDE.md +127 -0
  205. package/docs/QUALITY_GATES.en.md +118 -0
  206. package/docs/QUALITY_GATES.md +118 -0
  207. package/docs/TOKEN_QUOTA_PLAYBOOK.md +41 -0
  208. package/docs/TOOL_CATALOG.md +129 -0
  209. package/docs/adopted-ecosystem-tools.md +96 -0
  210. package/docs/research/EXTERNAL_AGENT_SKILLS_SURVEY.md +1062 -0
  211. package/docs/research/agent_skill_training_analysis.md +1358 -0
  212. package/docs/schemas/synapse.config.schema.json +86 -0
  213. package/package.json +94 -4
  214. package/plugin.json +31 -0
  215. package/scripts/generate_skill_examples.py +244 -0
  216. package/scripts/install.ps1 +112 -0
  217. package/scripts/install_global_plugin.ps1 +94 -0
  218. package/scripts/install_global_plugin.sh +49 -0
  219. package/scripts/lint_skills.ps1 +57 -0
  220. package/scripts/package_dist.py +337 -0
  221. package/scripts/setup.sh +59 -0
  222. package/scripts/update_hub.ps1 +19 -0
  223. package/scripts/update_hub.sh +15 -0
  224. package/skills_manifest.json +854 -0
  225. package/synapse.config.json +31 -0
  226. package/templates/PROJECT_AI_GUIDE_TEMPLATE.md +111 -0
  227. package/templates/PROJECT_STATE_TEMPLATE.md +20 -0
  228. package/templates/ai_bridges/CLAUDE.md +54 -0
  229. package/templates/ai_bridges/copilot-instructions.md +20 -0
  230. package/templates/ai_bridges/cursor_synapse_qa.mdc +24 -0
  231. package/templates/ai_bridges/windsurfrules +26 -0
  232. package/templates/ci/github-actions-synapse.yml +95 -0
  233. package/templates/ci/gitlab-ci-synapse.yml +16 -0
  234. package/templates/ui/index.html +1069 -0
  235. package/templates/welcome.html.tmpl +2074 -0
  236. package/tools/.infer_baseline.json +30 -0
  237. package/tools/TOOLS_RUNBOOK.md +1553 -0
  238. package/tools/TOOL_CATALOG.json +1769 -0
  239. package/tools/__init__.py +43 -0
  240. package/tools/_openapi_parser.py +158 -0
  241. package/tools/agent_canary.py +525 -0
  242. package/tools/agentless_patcher.py +417 -0
  243. package/tools/analyze_project.py +262 -0
  244. package/tools/api_drift_sentinel.py +208 -0
  245. package/tools/api_fuzzer.py +762 -0
  246. package/tools/author_integrity.py +190 -0
  247. package/tools/auto_heal.py +271 -0
  248. package/tools/auto_heal_reflexion.py +532 -0
  249. package/tools/autogen_qa_broker.py +844 -0
  250. package/tools/benchmark_swarm_context.py +394 -0
  251. package/tools/browser_helpers.js +746 -0
  252. package/tools/browsergym_eval.py +236 -0
  253. package/tools/bug_reporter.py +252 -0
  254. package/tools/bump_version.py +423 -0
  255. package/tools/cache_resolver.py +1214 -0
  256. package/tools/check_env.py +426 -0
  257. package/tools/check_version_sync.py +256 -0
  258. package/tools/ci_healing_hook.py +126 -0
  259. package/tools/cli.py +1598 -0
  260. package/tools/config_decoupler.py +253 -0
  261. package/tools/contract_validator.py +141 -0
  262. package/tools/core/__init__.py +70 -0
  263. package/tools/core/adapters.py +431 -0
  264. package/tools/core/circuit_breaker.py +263 -0
  265. package/tools/core/cli_runtime.py +66 -0
  266. package/tools/core/file_lock.py +159 -0
  267. package/tools/core/i18n.py +394 -0
  268. package/tools/core/memory_bus.py +905 -0
  269. package/tools/core/process_supervisor.py +332 -0
  270. package/tools/core/telemetry.py +329 -0
  271. package/tools/count_tokens.py +1267 -0
  272. package/tools/create_mock_docx.py +104 -0
  273. package/tools/dashboard_generator.py +2403 -0
  274. package/tools/db_sandbox.py +675 -0
  275. package/tools/debt_harvester.py +237 -0
  276. package/tools/distill_log.py +161 -0
  277. package/tools/dspy_qa_signatures.py +356 -0
  278. package/tools/e2e_flow_prober.py +132 -0
  279. package/tools/export_postman_collection.py +945 -0
  280. package/tools/flaky_detector.py +389 -0
  281. package/tools/fsm_enforcer.py +450 -0
  282. package/tools/fsm_middleware.py +401 -0
  283. package/tools/fuzz_payloads.py +197 -0
  284. package/tools/generate_allure_report.py +88 -0
  285. package/tools/generate_api_matrix.py +193 -0
  286. package/tools/generate_jmx_plan.py +1322 -0
  287. package/tools/generate_sbom.py +252 -0
  288. package/tools/generate_tc_from_story.py +203 -0
  289. package/tools/generate_test_reports.py +133 -0
  290. package/tools/generate_tool_catalog.py +482 -0
  291. package/tools/gherkin_suite.py +758 -0
  292. package/tools/git_pre_commit_guard.py +298 -0
  293. package/tools/goldfish_review.py +366 -0
  294. package/tools/heal/__init__.py +28 -0
  295. package/tools/heal_pr_automator.py +220 -0
  296. package/tools/heuristic_locator_matcher.py +351 -0
  297. package/tools/hub_publisher.py +623 -0
  298. package/tools/humanize_linter.py +438 -0
  299. package/tools/infer_linter.py +977 -0
  300. package/tools/init_config.py +306 -0
  301. package/tools/interview_story.py +116 -0
  302. package/tools/jira_sync.py +566 -0
  303. package/tools/jtl_analyzer.py +474 -0
  304. package/tools/lint/__init__.py +30 -0
  305. package/tools/lint_ai_docs.py +374 -0
  306. package/tools/lookup_tc.py +165 -0
  307. package/tools/lookup_xpath.py +167 -0
  308. package/tools/matrix_sharder.py +148 -0
  309. package/tools/mcp/__init__.py +18 -0
  310. package/tools/mcp_docx_server.ps1 +13 -0
  311. package/tools/mcp_docx_server.py +851 -0
  312. package/tools/mcp_excel_server.ps1 +13 -0
  313. package/tools/mcp_excel_server.py +441 -0
  314. package/tools/mcp_server.py +725 -0
  315. package/tools/md_to_xlsx.py +327 -0
  316. package/tools/micro_mutator.py +887 -0
  317. package/tools/mipro_assertion_tuner.py +210 -0
  318. package/tools/network_mock_shield.py +311 -0
  319. package/tools/newman_analyzer.py +384 -0
  320. package/tools/omni_emitter.py +579 -0
  321. package/tools/omni_parser.py +450 -0
  322. package/tools/omni_transpiler.py +168 -0
  323. package/tools/openxml_guard.py +438 -0
  324. package/tools/output_formatter.py +182 -0
  325. package/tools/package_release.py +325 -0
  326. package/tools/perf/__init__.py +24 -0
  327. package/tools/pinpoint_failure.py +190 -0
  328. package/tools/project_state.py +171 -0
  329. package/tools/qa_event_stream.py +358 -0
  330. package/tools/repo_map.py +346 -0
  331. package/tools/report/__init__.py +32 -0
  332. package/tools/reversible_sandbox.py +344 -0
  333. package/tools/safety_firewall.py +437 -0
  334. package/tools/security_coverage_ledger.py +538 -0
  335. package/tools/security_scanner.py +229 -0
  336. package/tools/senior_code_review.py +393 -0
  337. package/tools/setup_project.py +770 -0
  338. package/tools/skill_collision_guard.py +304 -0
  339. package/tools/skill_profiles.py +217 -0
  340. package/tools/skill_vault.py +481 -0
  341. package/tools/skillspector.py +1278 -0
  342. package/tools/smart_visual_masker.py +132 -0
  343. package/tools/spec_drift_sentinel.py +438 -0
  344. package/tools/swe_qa_aci.py +369 -0
  345. package/tools/synapse_observer.py +485 -0
  346. package/tools/synapse_qa_bench.py +190 -0
  347. package/tools/sync_agent_rules.py +274 -0
  348. package/tools/telemetry_correlator.py +397 -0
  349. package/tools/template_excel_exporter.py +514 -0
  350. package/tools/templates/jmeter-distributed/README.md +54 -0
  351. package/tools/templates/jmeter-distributed/docker-compose.yml +83 -0
  352. package/tools/test_impact.py +419 -0
  353. package/tools/test_memory_os.py +462 -0
  354. package/tools/textgrad_mutation_optimizer.py +237 -0
  355. package/tools/tms_sync_bridge.py +834 -0
  356. package/tools/tot_exploratory_tester.py +239 -0
  357. package/tools/trace_data_flow.py +240 -0
  358. package/tools/traffic_session_converter.py +256 -0
  359. package/tools/trend_analytics.py +314 -0
  360. package/tools/ui_server.py +401 -0
  361. package/tools/universal_ir.py +488 -0
  362. package/tools/update_sentinel.py +383 -0
  363. package/tools/validate_groovy_scripts.py +173 -0
  364. package/tools/verify_all.py +1271 -0
  365. package/tools/visual_diff_canvas.py +143 -0
  366. package/tools/visual_som_helper.py +550 -0
  367. package/tools/watch_mode.py +308 -0
  368. package/tools/wcag_audit.py +239 -0
  369. package/tools/welcome_page.py +290 -0
@@ -0,0 +1,1553 @@
1
+ # TOOLS RUNBOOK — Automated Tools Handbook for AI Agents
2
+
3
+ > **Standard reference guide for AI Agents (Google Antigravity, Cursor, Claude Code, Windsurf)**
4
+ > Every script in the `tools/` directory has an explicit purpose, CLI syntax, and mandatory dispatch trigger. Guessing syntax is strictly prohibited.
5
+
6
+ ---
7
+
8
+ ## 1. SITUATIONAL TOOL DISPATCH MATRIX
9
+
10
+ | Practical Agent Context | Required Tool | Typical Execution Command |
11
+ | :--- | :--- | :--- |
12
+ | **Autonomous Bootstrap (New project / "setup project")** | `tools/setup_project.py` | `python tools/setup_project.py [target]` (or `agent-qa setup`).<br/>*Autonomous:* Detects stack, generates `PROJECT_AI_GUIDE.md`, installs `pre-push` Git hook, runs initial audit. |
13
+ | **Prerequisites & Environment Health Diagnostic ("doctor")** | `tools/check_env.py` | `agent-qa doctor` (or `npx synapse-hub doctor`) |
14
+ | **Visual Product Landing Page & Interactive Guide ("welcome")** | `tools/welcome_page.py` | `agent-qa welcome` (or `npx synapse-hub welcome`) |
15
+ | **Flaky Test Detection & Quarantine Governance ("flaky")** | `tools/flaky_detector.py` | `agent-qa flaky --detect` (or `npx synapse-hub flaky`) |
16
+ | **Executive Project Health & Quality Dashboard ("dashboard")** | `tools/dashboard_generator.py` | `agent-qa dashboard` (or `npx synapse-hub dashboard`) |
17
+ | **Clean Uninstall of AI Bridges & Global Plugins ("uninstall")** | `tools/cli.py` | `agent-qa uninstall` (or `npx synapse-hub uninstall`) |
18
+ | **Comprehensive Health & AST Analysis ("analyze project")** | `tools/analyze_project.py` | `python tools/analyze_project.py [target]` (or `agent-qa analyze`).<br/>*Post-Audit:* Stages and commits `PROJECT_HEALTH_REPORT.md` & `repo_map.txt` locally; confirms with user before pushing to remote. |
19
+ | **Action Safety Firewall (Environment Protection)** | `tools/safety_firewall.py` | `python tools/safety_firewall.py --text "Delete" --action click` (or `agent-qa safety-check`) |
20
+ | **API Contract Drift (Breaking Change Detection)** | `tools/api_drift_sentinel.py` | `python tools/api_drift_sentinel.py --old base.json --new curr.json` (or `agent-qa contract-drift`) |
21
+ | **Autonomous API Fuzzing & Chaos Breaker** | `tools/api_fuzzer.py` | `agent-qa fuzz-api --base-url <url> --spec <swagger.json>` (Catches 500, DB leaks, SLA breach) |
22
+ | **FastMCP JSON-RPC Server (Cursor/Claude/Antigravity)** | `tools/mcp_server.py` | `python tools/mcp_server.py` (or `agent-qa mcp-serve`) |
23
+ | **Syntactic Micro-Mutation (Assertion Quality Verification)** | `tools/micro_mutator.py` | `python tools/micro_mutator.py [target]` (or `agent-qa mutate`) |
24
+ | **Gherkin BDD Suite Compiler (Natural-Language Ingestion, 0-token)** | `tools/gherkin_suite.py` | `python tools/gherkin_suite.py tests/bdd/` (or `agent-qa gherkin`; `--emit-ir` for Universal IR) |
25
+ | **Self-Healing PR Automator (Trace & Visual Diff Proof)** | `tools/heal_pr_automator.py` | `python tools/heal_pr_automator.py --page P.groovy --old "//a" --new "//b" --trace-zip trace.zip` (or `agent-qa heal-pr`) |
26
+ | **Duration-Balanced Matrix Sharder (CI/CD Load Balancing)** | `tools/matrix_sharder.py` | `python tools/matrix_sharder.py [target] --shards 4` (or `agent-qa shard`) |
27
+ | **Enterprise ALM & TMS Sync Bridge (Jira/Xray/TestRail)** | `tools/tms_sync_bridge.py` | `python tools/tms_sync_bridge.py pull PROJ-1042` / `report-bug` |
28
+ | **Zero-Pollution DB Sandbox (Ephemeral Teardown)** | `tools/db_sandbox.py` | `python tools/db_sandbox.py snapshot` / `restore` / `rollback-test` |
29
+ | **Shift-Right Traffic Replay (HAR / RUM to Test)** | `tools/traffic_session_converter.py` | `python tools/traffic_session_converter.py session.har -o test.ts` |
30
+ | **Multimodal Vision Grounding & Zero-Token Cache (SoM)** | `tools/visual_som_helper.py` | `python tools/visual_som_helper.py --image shot.png --component "Submit" --cache-lookup` |
31
+ | **Edge-Case Fuzzing & Input Sanitization Suite** | `tools/fuzz_payloads.py` | `python tools/fuzz_payloads.py --field username --type string` |
32
+ | **Starting task / Querying Page Class methods** | `tools/repo_map.py` | `python tools/repo_map.py` (Reads `tools/repo_map.txt`) |
33
+ | **Pre-Commit / Completing Task** | `tools/verify_all.py` | `python tools/verify_all.py` |
34
+ | **After creating/editing Test Script (Fake-Pass scan)**| `tools/infer_linter.py` | `python tools/infer_linter.py` |
35
+ | **After modifying Page Class (Impact Analysis)** | `tools/test_impact.py` | `python tools/test_impact.py --git-diff` |
36
+ | **When Test FAILS (Pinpoint line & error in 0.1s)** | `tools/pinpoint_failure.py` | `python tools/pinpoint_failure.py <report.xml>` (or `agent-qa pinpoint-failure report.xml`) |
37
+ | **When CLI/Gradle logs are verbose (Observation Masking)**| `tools/distill_log.py` | `python tools/distill_log.py <path_to_log>` |
38
+ | **When encountering UI error / Overlay / Stale Element**| `tools/cache_resolver.py` | `python tools/cache_resolver.py query "<error_msg>"` |
39
+ | **Before authoring test for Page/Flow** | `tools/cache_resolver.py` | `python tools/cache_resolver.py get-lessons --context "<page>"` (or `agent-qa heal get-lessons --context "<page>"`) |
40
+ | **After healing a test failure** | `tools/cache_resolver.py` | `python tools/cache_resolver.py record-lesson --context "<page>" --error "<sig>" --lesson "<summary>"` |
41
+ | **Generating test scripts from Natural Language Story** | `tools/generate_tc_from_story.py`| `python tools/generate_tc_from_story.py "<story>"` (or `agent-qa generate-tc story.md`) |
42
+ | **Generating E2E matrix from OpenAPI/Swagger** | `tools/generate_api_matrix.py` | `python tools/generate_api_matrix.py --spec <swagger.json>` |
43
+ | **Exporting API tests to Postman Collection v2.1** | `tools/export_postman_collection.py` | `agent-qa export-postman --spec <swagger.json> -o col.json` |
44
+ | **Analyzing Newman Results & CI/CD Gatekeeper** | `tools/newman_analyzer.py` | `agent-qa analyze-newman report.json --max-failures 0` |
45
+ | **Generating JMeter Performance Test Plan (.jmx)** | `tools/generate_jmx_plan.py` | `agent-qa generate-jmx --spec <swagger.json> --vus 100 -o plan.jmx` |
46
+ | **Analyzing JMeter JTL & Enforcing CI/CD SLA Gate** | `tools/jtl_analyzer.py` | `agent-qa analyze-jtl results.jtl --sla-p95 500 --max-error-rate 1.0` |
47
+ | **Full-Stack APM & Server Telemetry RCA Correlator** | `tools/telemetry_correlator.py` | `agent-qa correlate-telemetry --jtl results.jtl --server-metrics srv.csv` |
48
+ | **Auditing Web Accessibility (WCAG 2.2)** | `tools/wcag_audit.py` | `python tools/wcag_audit.py <path_to_html_or_url>` (or `agent-qa wcag-audit`) |
49
+ | **0-Token Polyglot Test Transpilation** | `tools/omni_transpiler.py` | `agent-qa transpile <file> --to <target>` (Playwright TS, Python, Java, Katalon, Cypress) |
50
+ | **0-Token Repository Polyglot AST Scan** | `tools/omni_transpiler.py` | `agent-qa omni-scan [path]` (Instant inventory of Pages, Locators, Tests across languages) |
51
+ | **Sync Single-Source Agent Rules ("sync-rules")** | `tools/sync_agent_rules.py` | `agent-qa sync-rules` (or `python tools/sync_agent_rules.py --check`) |
52
+ | **Lookup Test Case Identifier Index ("lookup-tc")** | `tools/lookup_tc.py` | `agent-qa lookup-tc [query]` (or `python tools/lookup_tc.py [query]`) |
53
+ | **Lookup Cached Element XPaths / AOM ("lookup-xpath")** | `tools/lookup_xpath.py` | `agent-qa lookup-xpath [query]` (or `python tools/lookup_xpath.py [query]`) |
54
+ | **Trace Data Flow & Teardown Verification ("trace-data-flow")** | `tools/trace_data_flow.py` | `agent-qa trace-data-flow ./tests` (or `python tools/trace_data_flow.py`) |
55
+ | **Autonomous Legacy Suite Migration** | `tools/cli.py` | `agent-qa migrate --src ./katalon_project --dest ./playwright_ts` |
56
+ | **Environment & Secret Decoupling Engine** | `tools/config_decoupler.py` | `agent-qa decouple-config [target] --fix` (Extracts env.default.json & .env.example) |
57
+ | **Single Portable Binary Distribution** | `scripts/package_dist.py` | `python scripts/package_dist.py --binary` (Builds standalone omni-qc.exe) |
58
+ | **Autonomous Bug Report & Jira/Allure Ticket** | `tools/bug_reporter.py` | `agent-qa report-bug --title "<title>" --error "<msg>"` |
59
+ | **API Network Mocking & Chaos Shield** | `tools/network_mock_shield.py` | `agent-qa mock-shield --preset payment_success` |
60
+ | **Smart Visual Masking (Anti-Flake)** | `tools/smart_visual_masker.py` | `agent-qa visual-mask --playwright-snippet` |
61
+ | **CI/CD Silent Self-Healing Hook & Auto-PR** | `tools/ci_healing_hook.py` | `agent-qa ci-hook --file <f> --old-loc <old> --new-loc <new>` |
62
+ | **Checking DB data leaks (Taint Analysis)** | `tools/trace_data_flow.py` | `python tools/trace_data_flow.py` |
63
+ | **Detecting Canvas / GIS Map visual regression** | `tools/visual_diff_canvas.py` | `python tools/visual_diff_canvas.py compare <b> <a> --diff <d>` (or `agent-qa canvas-diff`) |
64
+ | **Universal Release Version Synchronization Audit** | `tools/check_version_sync.py` | `python tools/check_version_sync.py` (or `agent-qa check-version`) |
65
+ | **Groovy Scripts & Keywords Syntax Pre-check** | `tools/validate_groovy_scripts.py` | `python tools/validate_groovy_scripts.py` (or `agent-qa validate-groovy`) |
66
+ | **Cognitive Observer & Tradeoff Sentinel** | `tools/synapse_observer.py` | `python tools/synapse_observer.py [--diff \| --text <txt>]` (Anthropic Observer pattern) |
67
+ | **Anti-AI Slop & Human-Centric Writing Linter** | `tools/humanize_linter.py` | `python tools/humanize_linter.py [--file <f> \| --text <txt>]` (Scans buzzwords & cliches) |
68
+ | **Mathematical Security Coverage Ledger** | `tools/security_coverage_ledger.py` | `python tools/security_coverage_ledger.py [init\|add\|validate\|summary]` (Cloudflare pattern) |
69
+ | **Model Context Protocol (MCP) Excel Server** | `tools/mcp_excel_server.py` | `python tools/mcp_excel_server.py` (or `agent-qa mcp-excel`) |
70
+ | **3-Layer Heuristic Locator Matcher (0-Token Recovery)** | `tools/heuristic_locator_matcher.py` | `python tools/heuristic_locator_matcher.py` (Internal autonomous fallback engine) |
71
+ | **Output Formatter & Exit Code Spec (NO_COLOR standard)** | `tools/output_formatter.py` | `from output_formatter import is_color_enabled, EXIT_SUCCESS` |
72
+ | **Canary Self-Healing Audit** | `tools/agent_canary.py` | `python tools/agent_canary.py --run` |
73
+ | **Lookup XPath Locator in cached memory** | `tools/lookup_xpath.py` | `python tools/lookup_xpath.py "<keyword>"` |
74
+ | **Lookup Test Case metadata** | `tools/lookup_tc.py` | `python tools/lookup_tc.py "<keyword_or_id>"` |
75
+ | **Linting Markdown documentation quality** | `tools/lint_ai_docs.py` | `python tools/lint_ai_docs.py` |
76
+ | **Auditing AI Agent Skills & MCP Security** | `tools/skillspector.py` | `python tools/skillspector.py [path]` (or `agent-qa skillspector [path]` / `npx synapse-hub skillspector`) |
77
+ | **Author Provenance & Anti-Tamper Integrity Guard** | `tools/author_integrity.py` | `python tools/author_integrity.py` (or `agent-qa verify-author` / `verify_all pre-flight`) |
78
+ | **Cross-Platform Token & Cost Auditor (Antigravity / Cursor / Claude)** | `tools/count_tokens.py` | `python tools/count_tokens.py` (or `--platform cursor` / `--platform all --list` / `--file <path>`) |
79
+ | **Standalone Executive HTML Dashboard Generator** | `tools/dashboard_generator.py` | `python tools/dashboard_generator.py` (or `agent-qa dashboard [--open]`) |
80
+ | **Real-Time Incremental Watch Mode Sentinel** | `tools/watch_mode.py` | `python tools/watch_mode.py` (or `agent-qa watch [--once]`) |
81
+ | **Technical Debt & Shortcut Harvester ("debt")** | `tools/debt_harvester.py` | `agent-qa debt [path]` (or `python tools/debt_harvester.py --scan`).<br/>*Autonomous:* Scans `shortcut:` markers across repo, generates tracked markdown ledger. |
82
+ | **6-Pillar Senior Git Diff Reviewer ("review")** | `tools/senior_code_review.py` | `agent-qa review [--staged]` (or `python tools/senior_code_review.py`).<br/>*Autonomous:* Reviews diff across Bugs, Security, Concurrency, Missing Tests, Speed, Bloat. |
83
+ | **Upstream Version Check & 1-Click Self-Update** | `tools/update_sentinel.py` | `python tools/update_sentinel.py --check / --update` (or `agent-qa update` / `npx synapse-hub update`) |
84
+ | **Tier-2 Skill Routing & Collision Guard (Gate 9)** | `tools/skill_collision_guard.py` | `python tools/skill_collision_guard.py` (or `verify_all Gate 9` / `--route "<intent>"`) |
85
+ | **GoEx Reversible Sandbox Teardown Stack** | `tools/reversible_sandbox.py` | `python tools/reversible_sandbox.py run --cmd "<cmd>" --rollback "<cleanup>"` |
86
+ | **Multi-Trial Episodic Reflexion Loop (K=3)** | `tools/auto_heal_reflexion.py` | `python tools/auto_heal_reflexion.py --test-cmd "<cmd>" --max-trials 3` |
87
+ | **Voyager Lifelong Page Class SQLite Vault** | `tools/skill_vault.py` | `python tools/skill_vault.py query "<keyword>"` / `stats` / `store` |
88
+ | **Stanford DSPy Declarative QA Signatures** | `tools/dspy_qa_signatures.py` | `python tools/dspy_qa_signatures.py compile-suite --spec <file>` |
89
+ | **Pocock Grilling Primitive & Requirement Interrogation** | `tools/interview_story.py` | `python tools/interview_story.py analyze <story.md>` / `interactive` |
90
+ | **Mutant-Directed Textual Loss Optimizer (TextGrad)** | `tools/textgrad_mutation_optimizer.py` | `python tools/textgrad_mutation_optimizer.py optimize --test-file <path>` |
91
+ | **Tool Function Calling Benchmark (Gorilla BFCL)** | `tools/synapse_qa_bench.py` | `python tools/synapse_qa_bench.py benchmark --top-k 5` |
92
+ | **Shared OpenAPI & Swagger Specification Parser** | `tools/_openapi_parser.py` | `python tools/_openapi_parser.py <spec>` |
93
+ | **Agentless 3-Stage Deterministic Patcher** | `tools/agentless_patcher.py` | `python tools/agentless_patcher.py --file <f> --error "<msg>"` |
94
+ | **Closed-Loop Locator Self-Healing Engine** | `tools/auto_heal.py` | `python tools/auto_heal.py --file <f> --broken "<loc>"` (or `agent-qa heal`) |
95
+ | **Asynchronous Actor QA Message Broker** | `tools/autogen_qa_broker.py` | `python tools/autogen_qa_broker.py --topic <t> --payload <data>` |
96
+ | **Swarm Context Token Benchmark Harness** | `tools/benchmark_swarm_context.py` | `python tools/benchmark_swarm_context.py --iterations 10` |
97
+ | **BrowserGym Web Agent Benchmark Harness** | `tools/browsergym_eval.py` | `python tools/browsergym_eval.py --task "<t>"` |
98
+ | **Atomic Universal Version Bumper** | `tools/bump_version.py` | `python tools/bump_version.py <patch\|minor\|major>` |
99
+ | **Swarm Data Contract Validator** | `tools/contract_validator.py` | `python tools/contract_validator.py --contract <c.json>` |
100
+ | **Enterprise E2E Flow Prober & Crawler** | `tools/e2e_flow_prober.py` | `python tools/e2e_flow_prober.py --url <url>` |
101
+ | **5-Stage QA Multi-Agent FSM Enforcer** | `tools/fsm_enforcer.py` | `python tools/fsm_enforcer.py transition <stage>` |
102
+ | **Runtime FSM Interceptor & Tool Proxy** | `tools/fsm_middleware.py` | `python tools/fsm_middleware.py --check-tool <tool>` |
103
+ | **Enterprise Allure HTML Report Generator** | `tools/generate_allure_report.py` | `python tools/generate_allure_report.py --results ./allure-results` |
104
+ | **SPDX 2.3 Software Bill of Materials (SBOM)** | `tools/generate_sbom.py` | `python tools/generate_sbom.py -o Reports/sbom.json` |
105
+ | **Enterprise Test Report Aggregator** | `tools/generate_test_reports.py` | `python tools/generate_test_reports.py --reports-dir ./Reports` |
106
+ | **Enterprise Tooling Ecosystem Catalog Generator** | `tools/generate_tool_catalog.py` | `python tools/generate_tool_catalog.py --output tools/TOOL_CATALOG.json` |
107
+ | **Enterprise Git Pre-Commit Architecture Guard** | `tools/git_pre_commit_guard.py` | `python tools/git_pre_commit_guard.py [--staged]` |
108
+ | **Zero-Context Test Specification Reviewer** | `tools/goldfish_review.py` | `python tools/goldfish_review.py <spec.md>` |
109
+ | **Autonomous 1-Click 5-Step Hub Release** | `tools/hub_publisher.py` | `python tools/hub_publisher.py` |
110
+ | **Project Configuration Bootstrapper** | `tools/init_config.py` | `python tools/init_config.py [--target-dir .]` |
111
+ | **Jira / Xray / Zephyr Enterprise 2-Way Sync** | `tools/jira_sync.py` | `python tools/jira_sync.py pull <id>` / `push-results` |
112
+ | **FastMCP Word .docx Document Server** | `tools/mcp_docx_server.py` | `python tools/mcp_docx_server.py` (or `agent-qa mcp-docx`) |
113
+ | **MIPROv2 Bayesian Assertion Tuner** | `tools/mipro_assertion_tuner.py` | `python tools/mipro_assertion_tuner.py --trials 20` |
114
+ | **Universal Polyglot Clean POM Code Emitter** | `tools/omni_emitter.py` | `python tools/omni_emitter.py --ir suite.json --lang typescript` |
115
+ | **Deterministic Polyglot AST Parser** | `tools/omni_parser.py` | `python tools/omni_parser.py --src ./tests --emit-ir suite.json` |
116
+ | **OpenXML Security & Protocol Defense Guard** | `tools/openxml_guard.py` | `python tools/openxml_guard.py audit <file.xlsx>` |
117
+ | **Enterprise Release Packager & Checksum Guard** | `tools/package_release.py` | `python tools/package_release.py --version <ver>` |
118
+ | **Enterprise Project State Machine & Memory Anchor** | `tools/project_state.py` | `python tools/project_state.py get` / `set` |
119
+ | **Immutable QA Event Stream Engine** | `tools/qa_event_stream.py` | `python tools/qa_event_stream.py record` / `verify-chain` |
120
+ | **Enterprise Security Sentinel & Scanner** | `tools/security_scanner.py` | `python tools/security_scanner.py [--strict]` |
121
+ | **Spec-to-Code Drift Sentinel** | `tools/spec_drift_sentinel.py` | `python tools/spec_drift_sentinel.py --spec <api.json>` |
122
+ | **QA Agent-Computer Interface (SWE-agent)** | `tools/swe_qa_aci.py` | `python tools/swe_qa_aci.py view` / `edit` |
123
+ | **Template-Driven Excel Test Case Exporter** | `tools/template_excel_exporter.py` | `python tools/template_excel_exporter.py <cases.md> -o <out.xlsx>` |
124
+ | **Enterprise Markdown-to-Excel Test Case Exporter** | `tools/md_to_xlsx.py` | `python tools/md_to_xlsx.py <input.md> [output.xlsx]` (or `agent-qa md-to-xlsx`) |
125
+ | **Hierarchical QA Test Memory OS (MemGPT)** | `tools/test_memory_os.py` | `python tools/test_memory_os.py core-get` / `recall-search` |
126
+ | **Tree-of-Thoughts Exploratory Testing Engine** | `tools/tot_exploratory_tester.py` | `python tools/tot_exploratory_tester.py --story <story.md>` |
127
+ | **Historical Quality Trend & Flakiness Analytics** | `tools/trend_analytics.py` | `python tools/trend_analytics.py --history ./Reports/history` |
128
+ | **Interactive QA Mission Control UI Server** | `tools/ui_server.py` | `python tools/ui_server.py` (or `agent-qa ui`) |
129
+ | **Universal Intermediate Representation AST Model** | `tools/universal_ir.py` | `python tools/universal_ir.py validate suite.json` |
130
+
131
+ ---
132
+
133
+ ## 2. DETAILED TOOL USAGE
134
+
135
+ ### 0. `tools/update_sentinel.py` (Upstream Update & Drift Sentinel)
136
+ Checks upstream releases on NPM Registry and GitHub, displaying non-blocking update notifications when a new version is published. Supports 1-click self-updating across local git repos and global plugins.
137
+
138
+ ```bash
139
+ # Check if update is available without applying
140
+ python tools/update_sentinel.py --check
141
+ # or via CLI
142
+ agent-qa update --check
143
+
144
+ # Perform 1-click self-update (pulls git, syncs memory cache, verifies DoD)
145
+ python tools/update_sentinel.py --update
146
+ # or via CLI
147
+ agent-qa update
148
+ ```
149
+
150
+ ### 1. `tools/generate_api_matrix.py`
151
+ - **Purpose:** Ingests OpenAPI / Swagger JSON schemas and automatically computes comprehensive E2E test matrices: Positive, Boundary Value (min/max length, special characters, XSS payloads), and Negative (invalid types, missing required fields).
152
+ - **CLI Syntax:**
153
+ ```bash
154
+ # Generate Markdown matrix
155
+ python tools/generate_api_matrix.py --spec path/to/swagger.json --format md -o api_matrix.md
156
+
157
+ # Generate JSON matrix
158
+ python tools/generate_api_matrix.py --spec path/to/swagger.json --format json -o api_matrix.json
159
+
160
+ # Generate sample matrix using built-in schema
161
+ python tools/generate_api_matrix.py --sample
162
+ ```
163
+
164
+ ---
165
+
166
+ ### 2. `tools/wcag_audit.py`
167
+ - **Purpose:** Automated Web Accessibility auditor checking WCAG 2.2 Level A and AA criteria (missing alt tags, unlabeled form controls, table header structure, heading hierarchy gaps H1-H6, empty action buttons).
168
+ - **CLI Syntax:**
169
+ ```bash
170
+ # Audit local HTML snapshot
171
+ python tools/wcag_audit.py path/to/page.html -o wcag_report.md
172
+
173
+ # Audit live URL directly
174
+ python tools/wcag_audit.py https://staging.example.com/dashboard --url -o wcag_report.md
175
+ ```
176
+
177
+ ---
178
+
179
+ ### 3. `tools/verify_all.py`
180
+ - **Purpose:** Supreme Definition of Done (DoD) verification gate running all 10 Quality Gates (including Syntactic Micro-Mutation >= 80% and SLA Sentinel) prior to completing tasks or git commits. Supports dual operational modes (`hub` vs `target`) and dynamic target project resolution.
181
+ - **CLI Syntax:**
182
+ ```bash
183
+ # Auto-detection (automatically targets CWD if inside a test project, otherwise falls back to QA Hub)
184
+ python tools/verify_all.py
185
+
186
+ # Target a specific test project repository (positional or --repo / --path)
187
+ python tools/verify_all.py "D:/katalon-project"
188
+ python tools/verify_all.py --repo "D:/katalon-project"
189
+
190
+ # Explicit mode execution
191
+ python tools/verify_all.py --mode hub # QA Hub integrity validation
192
+ python tools/verify_all.py --mode target # Enterprise target test suite validation
193
+ ```
194
+
195
+ ---
196
+
197
+ ### 4. `tools/infer_linter.py`
198
+ - **Purpose:** AST static code analyzer detecting Fake-Pass anti-patterns (test cases without assertions or containing empty try-catch blocks swallowing errors).
199
+ - **CLI Syntax:**
200
+ ```bash
201
+ python tools/infer_linter.py
202
+ ```
203
+
204
+ ---
205
+
206
+ ### 5. `tools/test_impact.py`
207
+ - **Purpose:** Analyzes `git diff` against codebase dependency graphs to identify the exact subset of affected test cases, preventing redundant suite execution.
208
+ - **CLI Syntax:**
209
+ ```bash
210
+ python tools/test_impact.py --git-diff
211
+ ```
212
+
213
+ ---
214
+
215
+ ### 6. `tools/pinpoint_failure.py`
216
+ - **Purpose:** Extracts failing line numbers, exception names, and stack traces from JUnit XML reports in 0.1s without opening heavy files.
217
+ - **CLI Syntax:**
218
+ ```bash
219
+ python tools/pinpoint_failure.py
220
+ ```
221
+
222
+ ---
223
+
224
+ ### 7. `tools/distill_log.py`
225
+ - **Purpose:** Distills verbose CLI / KRE / Gradle logs by 95%, extracting only actionable exceptions, failing lines, and file pointers to prevent token degradation.
226
+ - **CLI Syntax:**
227
+ ```bash
228
+ python tools/distill_log.py path/to/execution.log
229
+ ```
230
+
231
+ ---
232
+
233
+ ### 8. `tools/cache_resolver.py`
234
+ - **Purpose:** Queries SQLite error cache (`tools/memory_cache.db`) via cosine similarity or pattern match for 0-token instant defect resolution.
235
+ - **CLI Syntax:**
236
+ ```bash
237
+ python tools/cache_resolver.py query "ElementClickInterceptedException"
238
+ python tools/cache_resolver.py add --pattern "Timeout waiting for primeNG" --fix "BasePage.waitForAngular()"
239
+ ```
240
+
241
+ ---
242
+
243
+ ### 9. `tools/generate_tc_from_story.py`
244
+ - **Purpose:** Large Action Model (LAM) parser converting natural language acceptance criteria into Clean POM script scaffolds.
245
+ - **CLI Syntax:**
246
+ ```bash
247
+ python tools/generate_tc_from_story.py "User navigates to login, inputs valid credentials, and verifies dashboard table loaded"
248
+ ```
249
+
250
+ ---
251
+
252
+ ### 10. `tools/visual_diff_canvas.py`
253
+ - **Purpose:** Pixel-level and SSIM perceptual comparison for GIS / Canvas elements lacking standard DOM locators.
254
+ - **CLI Syntax:**
255
+ ```bash
256
+ python tools/visual_diff_canvas.py --baseline baseline.png --actual actual.png --diff diff.png
257
+ ```
258
+
259
+ ---
260
+
261
+ ### 11. `tools/analyze_project.py`
262
+ - **Purpose:** Comprehensive 5-in-1 Project Health & AST Intelligence Suite. Aggregates environment checks (`check_env`), Page Class AST mapping (`repo_map`), Static Defect Sentinel (`infer_linter`), Teardown Data Flow (`trace_data_flow`), and 10 Quality Gates (`verify_all`). Generates `reports/PROJECT_HEALTH_REPORT.md` and synchronizes all AI data context in < 1 second.
263
+ - **Trigger:** Whenever user says: "analyze project", "re-analyze project", "audit project", or during initial project onboarding.
264
+ - **CLI Syntax:**
265
+ ```bash
266
+ # Analyze current working directory or QA Hub
267
+ python tools/analyze_project.py
268
+ # Or use CLI shortcut
269
+ agent-qa analyze
270
+
271
+ # Analyze specific target project
272
+ python tools/analyze_project.py "D:/katalon-project"
273
+ python tools/analyze_project.py --repo "D:/katalon-project"
274
+ ```
275
+
276
+
277
+ ---
278
+
279
+ ### 12. `tools/tms_sync_bridge.py`
280
+ - **Purpose:** Bi-directional Enterprise ALM Bridge connecting autonomous agents with Jira REST API v3 (live mode) and TestRail/Xray (mock simulation mode). Pulls Given-When-Then Acceptance Criteria from User Stories to seed tests, and automatically creates Bug Tickets with complete reproduction steps and screenshot attachments upon test failure.
281
+ - **CLI Syntax:**
282
+ ```bash
283
+ # Pull Acceptance Criteria from Jira Story
284
+ python tools/tms_sync_bridge.py pull PROJ-1042
285
+
286
+ # Create Bug Ticket with repro steps and failure screenshots (Jira live, or Mock preview)
287
+ python tools/tms_sync_bridge.py report-bug --project BILLING --tc-id TC-01 --summary "Payment failed" --error "Timeout" --screenshot "Screenshots/FAILED_TC-01.png"
288
+
289
+ # Sync execution batch (mock simulation / live Jira)
290
+ python tools/tms_sync_bridge.py sync-run --plan-key XRAY-PLAN-1 --json
291
+ ```
292
+
293
+ ---
294
+
295
+ ### 13. `tools/db_sandbox.py`
296
+ - **Purpose:** Zero-Pollution Database Sandbox and Ephemeral Teardown Engine. Takes pristine database baseline snapshots, instantly restores clean states (< 0.1s), runs tests inside transactional savepoints (automatic rollback), and safely audits/purges orphan test data junk with literal prefix matching (escaped SQL wildcards) and dry-run preview.
297
+ - **CLI Syntax:**
298
+ ```bash
299
+ # Snapshot database before suite execution
300
+ python tools/db_sandbox.py snapshot --id baseline
301
+
302
+ # Restore pristine clean database after suite execution
303
+ python tools/db_sandbox.py restore --id baseline
304
+
305
+ # Preview orphan test junk without deleting (Dry-Run)
306
+ python tools/db_sandbox.py audit --dry-run
307
+
308
+ # Purge orphan test records matching literal prefixes (AUTO_, TEST_, TEMP_)
309
+ python tools/db_sandbox.py audit
310
+ ```
311
+ python tools/db_sandbox.py rollback-test
312
+
313
+ # Audit database for orphan test junk and purge
314
+ python tools/db_sandbox.py audit
315
+ ```
316
+
317
+
318
+ ---
319
+
320
+ ### 14. `tools/traffic_session_converter.py`
321
+ - **Purpose:** Shift-Right production traffic and user session converter. Converts recorded `.har` files or RUM network traces into executable Playwright test scripts, automatically sanitizing PII (passwords, tokens, credit cards) and eliminating static noise.
322
+ - **CLI Syntax:**
323
+ ```bash
324
+ # Convert HAR file into Playwright test script
325
+ python tools/traffic_session_converter.py prod_session.har -o tests/e2e_replay.spec.ts
326
+
327
+ # Output parsed network requests as JSON
328
+ python tools/traffic_session_converter.py prod_session.har --json
329
+ ```
330
+
331
+ ---
332
+
333
+ ### 15. `tools/visual_som_helper.py`
334
+ - **Purpose:** Multimodal Vision Grounding and Set-of-Marks (SoM) fallback engine. When standard DOM locators fail on HTML5 Canvas, GIS maps, WebGL charts, or deeply nested Shadow DOM, it autonomously detects interactive visual contours using PIL edge clustering, overlays numbered bounding box badges on screenshots, resolves target coordinates `(x, y)`, caches coordinates via 64-bit dHash in SQLite, and dispatches physical Playwright mouse clicks (`await page.mouse.click(x, y)`).
335
+ - **CLI Syntax:**
336
+ ```bash
337
+ # Autonomous Canvas contour detection without DOM
338
+ python tools/visual_som_helper.py --image canvas_map.png --detect-only
339
+
340
+ # Generate Set-of-Marks overlay and resolve target coordinates
341
+ python tools/visual_som_helper.py --image screenshot.png --label "Execute Trade"
342
+
343
+ # Zero-Token Visual Cache lookup (Similarity > 98%)
344
+ python tools/visual_som_helper.py --image screenshot.png --component "TradeButton" --cache-lookup
345
+ ```
346
+
347
+ ---
348
+
349
+ ### 16. `tools/api_fuzzer.py`
350
+ - **Purpose:** Autonomous runtime API fuzzer and chaos breaker. Ingests OpenAPI 3.x / Swagger 2.0 schemas, generates dynamic boundary, type-inverted, and adversarial fuzzing payloads from `tools/fuzz_payloads.py`, executes live HTTP/S requests against staging/test APIs, and evaluates three-alarm defect Oracle: HTTP 500 crashes, database stacktrace leaks, and SLA latency timeouts (> 3000ms).
351
+ - **CLI Syntax:**
352
+ ```bash
353
+ # Execute active fuzzing against staging API
354
+ agent-qa fuzz-api --base-url "https://staging.api.enterprise.com" --spec swagger.json --token "JWT_SECRET"
355
+
356
+ # Air-gapped / deterministic dry-run mode for CI/CD
357
+ agent-qa fuzz-api --dry-run
358
+ ```
359
+
360
+ ---
361
+
362
+ ### 17. `tools/omni_transpiler.py`
363
+ - **Purpose:** Universal Polyglot AST Engine & Cross-Framework Transpiler. Allows a single QA engineer to parse, inventory, and transpile test automation code across Java (Selenium), TypeScript (Playwright), Python, Groovy (Katalon Clean POM), and Cypress in 0 tokens without network calls or LLM hallucinations.
364
+ - **CLI Syntax:**
365
+ ```bash
366
+ # Transpile legacy Java Selenium Page Object into Playwright TypeScript
367
+ agent-qa transpile src/test/java/pages/LoginPage.java --to playwright-ts --out src/
368
+
369
+ # Transpile Katalon Groovy script into Selenium Java
370
+ agent-qa transpile Keywords/pages/CheckoutPage.groovy --to selenium-java
371
+
372
+ # 0-Token Polyglot AST Inventory of entire repository (regardless of language)
373
+ agent-qa omni-scan .
374
+ ```
375
+
376
+ ---
377
+
378
+ ### 18. `tools/bug_reporter.py`
379
+ - **Purpose:** Auto-Bug Reporter & Root Cause Analysis (RCA) Ticket Generator. Automatically distinguishes AUT bugs (server 500, JS exceptions) from test maintenance issues, distills stack traces, formats reproduction steps, and exports ready-to-paste Jira markup or GitHub Markdown.
380
+ - **CLI Syntax:**
381
+ ```bash
382
+ agent-qa report-bug --title "Checkout payment fails" --error "500 Internal Server Error" --format jira
383
+ ```
384
+
385
+ ---
386
+
387
+ ### 19. `tools/network_mock_shield.py`
388
+ - **Purpose:** API Network Mocking & Chaos Shield Generator. Generates zero-token route interception code and chaos fault injection (Stripe/VNPAY payment success/fail, 401/403 auth, 500 server crash, network latency) for Playwright, Cypress, and Python.
389
+ - **CLI Syntax:**
390
+ ```bash
391
+ agent-qa mock-shield --preset payment_success --url "**/api/checkout"
392
+ agent-qa mock-shield --preset server_crash_500 --delay 2000
393
+ ```
394
+
395
+ ---
396
+
397
+ ### 20. `tools/smart_visual_masker.py`
398
+ - **Purpose:** Smart Visual Masker & Anti-Flake Engine. Eliminates 99% of false alarms in visual regression testing by disabling CSS animations, freezing SVG spinners, and masking dynamic timestamps, clocks, and avatars.
399
+ - **CLI Syntax:**
400
+ ```bash
401
+ agent-qa visual-mask --playwright-snippet
402
+ agent-qa visual-mask --css
403
+ ```
404
+
405
+ ---
406
+
407
+ ### 21. `tools/ci_healing_hook.py`
408
+ - **Purpose:** CI/CD Silent Self-Healing Pipeline Hook. Executes inside GitHub Actions / GitLab CI when a locator fails, applies in-place auto-heal, and generates an automated Pull Request draft with diff and confidence score.
409
+ - **CLI Syntax:**
410
+ ```bash
411
+ agent-qa ci-hook --file LoginPage.ts --old-loc "//button[@id='old']" --new-loc "//button[@id='new']"
412
+ ```
413
+
414
+ ---
415
+
416
+ ### 22. `tools/export_postman_collection.py`
417
+ - **Purpose:** Enterprise OpenAPI/Swagger, HAR & Zero-Input Domain Postman Collection v2.1.0 Exporter (Postman Pinnacle Suite). Generates fully structured Postman collections with dynamic pre-request scripts, SLA latency tests, response code assertions, autonomous token/entity chaining, native **AJV JSON Schema Validation**, companion **Data-Driven Testing (DDT) CSV matrix**, and **Autonomous Zero-Input Domain Synthesis** (`--domain [ecommerce|banking|saas]`).
418
+ - **CLI Syntax:**
419
+ ```bash
420
+ # 1. Ingest OpenAPI spec and export Postman collection + environment + AJV Schema asserts
421
+ agent-qa export-postman --spec swagger.json -o collection.json --env-output env.json
422
+
423
+ # 2. Autonomous Zero-Input Synthesis (No file provided! Synthesizes complete Banking/Ecom suite)
424
+ agent-qa export-postman --domain banking -o banking_col.json --env-output env.json --ddt-output ddt_data.csv
425
+ agent-qa export-postman --domain ecommerce -o ecom_col.json --ddt-output ecom_data.csv
426
+
427
+ # 3. Replay production HAR traffic as Postman requests
428
+ agent-qa export-postman --har session.har -o har_collection.json
429
+ ```
430
+
431
+ ---
432
+
433
+ ### 23. `tools/generate_jmx_plan.py`
434
+ - **Purpose:** Apache JMeter 5.x Performance Test Plan XML (.jmx) Generator (JMeter 360° Pinnacle Suite). Ingests OpenAPI specifications, Postman Collections, or HAR recordings to output production-ready JMeter load, stress, spike, and soak test plans with HTTP Cookie & Cache Managers, CSV Data Set Config, Transaction Controllers, Pareto Traffic Shaping (`--weighted-mix`), Deep Data Correlation (CSRF regex & random dynamic selectors), JSR223 Groovy HMAC payload signers, InfluxDB live APM telemetry, PerfMon server agent monitoring, and Multi-Protocol support (HTTP, JDBC, WebSocket, gRPC, Kafka).
435
+ - **CLI Syntax:**
436
+ ```bash
437
+ # 1. Generate JMeter plan with Pareto traffic shaping (70% Browse, 20% Cart, 10% Checkout)
438
+ agent-qa generate-jmx --spec swagger.json -o load_plan.jmx --weighted-mix "70:Browse,20:Cart,10:Checkout"
439
+
440
+ # 2. Convert existing Postman collection with CSV data & Deep Correlation (CSRF + random items)
441
+ agent-qa generate-jmx --postman collection.json -o perf_plan.jmx --csv-data users.csv --deep-correlation
442
+
443
+ # 3. Generate multi-protocol test plans (WebSocket, gRPC, Kafka, JDBC)
444
+ agent-qa generate-jmx --ws-sample -o websocket_plan.jmx
445
+ agent-qa generate-jmx --grpc-sample -o grpc_plan.jmx
446
+ agent-qa generate-jmx --kafka-sample -o kafka_plan.jmx
447
+ agent-qa generate-jmx --jdbc-sample -o jdbc_plan.jmx
448
+
449
+ # 4. Generate with live InfluxDB streaming & PerfMon Server Agent
450
+ agent-qa generate-jmx --spec swagger.json -o perf_plan.jmx --influxdb-url http://influxdb:8086/write?db=jmeter --perfmon-server 192.168.1.50:4444
451
+
452
+ # 5. Run headless JMeter CLI
453
+ jmeter -n -t load_plan.jmx -l results.jtl -e -o ./html_report
454
+ ```
455
+
456
+ ---
457
+
458
+ ### 24. `tools/jtl_analyzer.py`
459
+ - **Purpose:** Apache JMeter JTL Results Analyzer & CI/CD SLA Quality Gatekeeper. Parses `.jtl` (CSV or XML), computes statistical percentiles ($P_{50}, P_{90}, P_{95}, P_{99}$, Throughput, Error Rate), evaluates user SLA thresholds, supports server telemetry correlation (`--telemetry`), and returns deterministic exit code `0` (Pass) or `1` (Fail) to enforce quality gates in automated pipelines.
460
+ - **CLI Syntax:**
461
+ ```bash
462
+ # 1. Enforce CI/CD Quality Gate with P95 Latency SLA (< 500ms) and max error rate (< 1%)
463
+ agent-qa analyze-jtl results.jtl --sla-p95 500 --max-error-rate 1.0
464
+
465
+ # 2. Correlate with Server-Side APM Telemetry directly in Quality Gate
466
+ agent-qa analyze-jtl results.jtl --sla-p95 500 --telemetry server_metrics.csv --markdown pr_report.md
467
+
468
+ # 3. Dry-run sample benchmark verification
469
+ agent-qa analyze-jtl --sample --sla-p95 500
470
+ ```
471
+
472
+ ---
473
+
474
+ ### 25. `tools/author_integrity.py` (Author Provenance & Anti-Tamper Integrity Guard)
475
+ - **Purpose:** Cryptographic and textual provenance validator enforcing the mandatory author attribution condition of the MIT License:
476
+ *"The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software."*
477
+ Protects original creator **Thế Vị (@TeeVee98)** against unauthorized author stripping or copyright tampering across `LICENSE`, `package.json`, `README.md`, and `pyproject.toml`.
478
+ - **Trigger Condition:** Runs autonomously as pre-flight engine check in `tools/verify_all.py`, pre-dispatch in `agent-qa` CLI, or on-demand via `agent-qa verify-author`.
479
+ - **CLI Syntax:**
480
+ ```bash
481
+ # 1. Verify author attribution and provenance
482
+ python tools/author_integrity.py
483
+ agent-qa verify-author
484
+
485
+ # 2. Enforced autonomously during Quality Gate verification
486
+ python tools/verify_all.py
487
+ agent-qa verify
488
+ ```
489
+
490
+ ---
491
+
492
+ ### 26. `tools/md_to_xlsx.py` (Enterprise Markdown-to-Excel Converter)
493
+ - **Purpose:** Parses Markdown Test Case tables and converts them into professional, styled Excel workbooks (`.xlsx`) with Navy Blue headers, frozen header panes (`A2`), auto-filters, color-coded badges for Risk Level (High/Med/Low) and Priority (Critical/High/Med/Low), and multi-line wrapping.
494
+ - **CLI Syntax:**
495
+ ```bash
496
+ # 1. Convert markdown test cases to styled Excel (.xlsx)
497
+ agent-qa export-excel test_cases_crm.md
498
+
499
+ # 2. Specify custom output path and sheet title
500
+ agent-qa export-excel test_cases_crm.md -o CRM_TestCases_v1.xlsx --sheet-name "CRM Login"
501
+
502
+ # 3. Direct python execution
503
+ python3 tools/md_to_xlsx.py path/to/cases.md -o export.xlsx
504
+ ```
505
+
506
+ ---
507
+
508
+ ### 27. `tools/count_tokens.py` (Cross-Platform Token & Cost Auditor)
509
+ - **Purpose:** Audits and calculates token usage (Uncached Input, KV Cache Read, and Output/Thinking tokens) and estimated API costs across **Google Antigravity, Cursor Agent, and Claude Code**. Supports turn-by-turn breakdown, per-prompt profiling, multi-client session discovery, and cache hit rate tracking.
510
+ - **Trigger Condition:** On-demand after completing a task, turn, or test run to monitor context efficiency, detect token bloat, or calculate LLM cost across any supported AI client.
511
+ - **CLI Syntax:**
512
+ ```bash
513
+ # 1. Audit active Antigravity session
514
+ agent-qa tokens
515
+ python3 tools/count_tokens.py
516
+
517
+ # 2. Audit Cursor Agent sessions (parses ~/.cursor/projects/*/agent-transcripts/*/*.jsonl)
518
+ python3 tools/count_tokens.py --platform cursor
519
+ python3 tools/count_tokens.py --platform cursor --last-task
520
+ python3 tools/count_tokens.py --platform cursor --turns
521
+
522
+ # 3. List recent sessions across all platforms (Antigravity, Cursor, Claude)
523
+ python3 tools/count_tokens.py --platform all --list
524
+
525
+ # 4. Direct audit of any transcript file with auto-format detection
526
+ python3 tools/count_tokens.py --file /path/to/transcript.jsonl
527
+
528
+ # 5. Audit current active session (Antigravity)
529
+ agent-qa tokens --current
530
+
531
+ # 6. Show 5-hour and 7-day rolling window quota usage
532
+ agent-qa tokens --rolling
533
+
534
+ # 7. Benchmark Hub vs. Vanilla token & cost savings
535
+ agent-qa tokens --savings
536
+
537
+ # 8. Calculate cost with specific pricing model (gemini-flash, gemini-pro, claude-sonnet, claude-opus, gpt-4o, gpt-4o-mini)
538
+ agent-qa tokens --pricing claude-sonnet
539
+
540
+ # 9. Output machine-readable JSON
541
+ agent-qa tokens --json
542
+ ```
543
+
544
+ ---
545
+
546
+ ### 28. `tools/dashboard_generator.py` (Standalone Executive HTML Dashboard)
547
+ - **Purpose:** Compiles project health metrics, 10 Quality Gates status, AST repository maps, benchmark results, and skills inventory into a single, dependency-free, modern HTML dashboard (`PROJECT_DASHBOARD.html`).
548
+ - **Trigger Condition:** On-demand when presenting project status to stakeholders, QA leads, or managers, or after completing project analysis/audits.
549
+ - **CLI Syntax:**
550
+ ```bash
551
+ # 1. Generate dashboard for current project
552
+ agent-qa dashboard
553
+ python3 tools/dashboard_generator.py
554
+
555
+ # 2. Generate and open directly in browser
556
+ agent-qa dashboard --open
557
+
558
+ # 3. Output to custom path
559
+ agent-qa dashboard -o reports/custom_dashboard.html
560
+ ```
561
+
562
+ ---
563
+
564
+ ### 29. `tools/watch_mode.py` (Real-Time Incremental Watch Mode Sentinel)
565
+ - **Purpose:** Continuously monitors repository files for code changes and triggers near-instant (< 100ms) incremental verification (UTF-8 No BOM, absolute machine paths, AST Meta Infer-style fake-pass checks) with an interactive terminal Heads-Up Display (HUD).
566
+ - **Trigger Condition:** During active test development or refactoring sessions to get immediate feedback without manually running commands.
567
+ - **CLI Syntax:**
568
+ ```bash
569
+ # 1. Start real-time watch mode on current directory
570
+ agent-qa watch
571
+ python3 tools/watch_mode.py
572
+
573
+ # 2. Watch with custom debounce interval
574
+ agent-qa watch --debounce 0.5
575
+
576
+ # 3. Run incremental scan once on all files and exit (ideal for CI/CD pre-commit hooks)
577
+ agent-qa watch --once
578
+ ```
579
+
580
+ ---
581
+
582
+ ### 30. `tools/debt_harvester.py` (Technical Debt & Shortcut Harvester)
583
+ - **Purpose:** Scans code comments across multiple programming languages (`#`, `//`, `/* */`, `--`, `<!-- -->`) for `shortcut: <limit>, <when to upgrade>` annotations left by lazy senior developers, compiling them into a structured Markdown debt ledger or machine-readable JSON.
584
+ - **Trigger Condition:** On-demand when scanning accumulated technical debt, before major releases, or when user asks "scan debt" / "list shortcuts".
585
+ - **CLI Syntax:**
586
+ ```bash
587
+ # 1. Scan codebase for shortcuts and display table
588
+ agent-qa debt
589
+ python3 tools/debt_harvester.py --scan
590
+
591
+ # 2. Scan specific directory and export to markdown ledger
592
+ agent-qa debt ./src --output DEBT_LEDGER.md
593
+
594
+ # 3. Output machine-readable JSON for CI integration
595
+ agent-qa debt --json
596
+ ```
597
+
598
+ ---
599
+
600
+ ### 31. `tools/senior_code_review.py` (6-Pillar Senior Git Diff Reviewer)
601
+ - **Purpose:** Performs senior-level engineering code review on uncommitted Git diffs (or staged changes) across 6 core pillars: Bugs & Logic, Security & Boundaries, Real Concurrency & Scale, Missing Tests, Speed & Perf, and Bloat Elimination.
602
+ - **Trigger Condition:** On-demand before committing, submitting a PR, or when user asks "review diff" / "review code" / "senior review".
603
+ - **CLI Syntax:**
604
+ ```bash
605
+ # 1. Review all working tree git diff changes
606
+ agent-qa review
607
+ python3 tools/senior_code_review.py
608
+
609
+ # 2. Review staged changes only
610
+ agent-qa review --staged
611
+ python3 tools/senior_code_review.py --staged
612
+
613
+ # 3. Output review report as Markdown or JSON
614
+ agent-qa review --output-md REVIEW_REPORT.md
615
+ agent-qa review --json
616
+ ```
617
+
618
+ ---
619
+
620
+ ### 32. `tools/skill_collision_guard.py` (Tier-2 Skill Routing & Collision Guard — Gate 9)
621
+ - **Purpose:** Enforces deterministic skill dispatch and prevents routing collision across internal Hub skills (`.agents/skills/`) and external plugins based on cosine/Jaccard semantic overlap. Guarantees zero ambiguous triggers and acts as DoD Gate 9.
622
+ - **Trigger Condition:** Executed automatically during `verify_all.py` (Gate 9), pre-commit, or on-demand when auditing skill trigger uniqueness.
623
+ - **CLI Syntax:**
624
+ ```bash
625
+ # 1. Audit skill overlap and check for collision
626
+ python3 tools/skill_collision_guard.py
627
+
628
+ # 2. Audit with custom similarity threshold (default: 0.75 critical, 0.50 warning)
629
+ python3 tools/skill_collision_guard.py --threshold 0.80 --warn-threshold 0.45
630
+
631
+ # 3. Output machine-readable JSON for CI integration
632
+ python3 tools/skill_collision_guard.py --json
633
+ ```
634
+
635
+ ---
636
+
637
+ ### 33. `tools/reversible_sandbox.py` (GoEx Reversible Teardown Sandbox Stack)
638
+ - **Purpose:** Manages a deterministic LIFO undo execution stack for safe test automation and self-healing. Automatically rolls back filesystem mutations, database fixture insertions, and environment changes if a test or patch crashes.
639
+ - **Trigger Condition:** When dispatching destructive mutations, exploratory self-healing patches, or running isolated trial runs.
640
+ - **CLI Syntax:**
641
+ ```bash
642
+ # 1. Check current sandbox undo stack status
643
+ python3 tools/reversible_sandbox.py --status
644
+
645
+ # 2. Run reversible stack verification demo
646
+ python3 tools/reversible_sandbox.py --demo
647
+ ```
648
+
649
+ ---
650
+
651
+ ### 34. `tools/auto_heal_reflexion.py` (Multi-Trial Episodic Reflexion Loop — K=3)
652
+ - **Purpose:** Implements the Noah Shinn Episodic Reflexion loop for failed automated tests. Performs up to $K=3$ iterative trial-feedback cycles, updating episodic memory and self-correcting locators/code without polluting git history.
653
+ - **Trigger Condition:** When headless test suites fail in runner, or single-pass self-healing fails to resolve complex selector or timing issues.
654
+ - **CLI Syntax:**
655
+ ```bash
656
+ # 1. Run multi-trial reflexion self-healing on failing test
657
+ python3 tools/auto_heal_reflexion.py --test "TC_Checkout_01" --error "ElementClickInterceptedException"
658
+
659
+ # 2. Configure custom max trials (default: 3)
660
+ python3 tools/auto_heal_reflexion.py --test "TC_Login_02" --error "TimeoutException" --max-trials 5
661
+ ```
662
+
663
+ ---
664
+
665
+ ### 35. `tools/skill_vault.py` (Voyager Lifelong Page Class SQLite Vault)
666
+ - **Purpose:** Persists, indexes, and retrieves verified Clean POM Page Class methods, custom locators, and resilient interaction primitives in a permanent SQLite repository (`~/.agent_memory/skill_vault.db`). Prevents re-inventing known solutions across sessions.
667
+ - **Trigger Condition:** When authoring new Page Classes, searching for proven element interactions, or archiving new successful POM patterns.
668
+ - **CLI Syntax:**
669
+ ```bash
670
+ # 1. Query verified Page Class primitives by keyword
671
+ python3 tools/skill_vault.py --query "table_pagination"
672
+
673
+ # 2. List all indexed primitives in the lifelong vault
674
+ python3 tools/skill_vault.py --list
675
+
676
+ # 3. Seed initial baseline POM primitives
677
+ python3 tools/skill_vault.py --seed-samples
678
+ ```
679
+
680
+ ---
681
+
682
+ ### 36. `tools/dspy_qa_signatures.py` (Stanford DSPy Declarative QA Signature Engine)
683
+ - **Purpose:** Transforms prompt-based test generation into typed, declarative signatures (`StoryToUniversalIR`, `HealBrokenLocator`, `MutantAssertionSignature`) with formal input/output contracts, eliminating brittle prompt hacking.
684
+ - **Trigger Condition:** When compiling user stories into Universal IR, generating defensive assertions, or verifying agent signature compatibility.
685
+ - **CLI Syntax:**
686
+ ```bash
687
+ # 1. Check DSPy engine status and signature registrations
688
+ python3 tools/dspy_qa_signatures.py --check
689
+
690
+ # 2. Run declarative compilation demonstration
691
+ python3 tools/dspy_qa_signatures.py --demo
692
+ ```
693
+
694
+ ---
695
+
696
+ ### 37. `tools/interview_story.py` (Pocock Grilling Primitive & Requirement Interrogation)
697
+ - **Purpose:** Analyzes rough user stories and acceptance criteria against the Frontier Interrogation Checklist, identifying ambiguities, missing negative boundaries, unstated auth constraints, and race conditions before coding begins.
698
+ - **Trigger Condition:** Triggered autonomously when a user provides an incomplete story or uses `/grill-me` to sharpen requirements.
699
+ - **CLI Syntax:**
700
+ ```bash
701
+ # 1. Interrogate user story text directly
702
+ python3 tools/interview_story.py "As a user I want to checkout cart"
703
+
704
+ # 2. Analyze user story file and output JSON questions
705
+ python3 tools/interview_story.py docs/specs/order_flow.md --json
706
+ ```
707
+
708
+ ---
709
+
710
+ ### 38. `tools/textgrad_mutation_optimizer.py` (Mutant-Directed Textual Loss Optimizer)
711
+ - **Purpose:** Uses AST micro-mutants as a "textual loss function" to iteratively refine test assertions and Page Class validation methods until mutation score satisfies $\ge 80\%$.
712
+ - **Trigger Condition:** When newly generated tests fail Gate 8 (Mutation Score $< 80\%$), optimizing assertions to catch all logic mutations.
713
+ - **CLI Syntax:**
714
+ ```bash
715
+ # 1. Optimize test script assertions against mutants
716
+ python3 tools/textgrad_mutation_optimizer.py --file tests/test_checkout.py
717
+
718
+ # 2. Optimize with custom target score threshold
719
+ python3 tools/textgrad_mutation_optimizer.py --file tests/test_login.py --target-score 85.0
720
+
721
+ # 3. Output results as JSON
722
+ python3 tools/textgrad_mutation_optimizer.py --file tests/test_checkout.py --json
723
+ ```
724
+
725
+ ---
726
+
727
+ ### 39. `tools/synapse_qa_bench.py` (Tool Function Calling Benchmark — Gorilla BFCL)
728
+ - **Purpose:** Evaluates AI Agent tool-selection accuracy, argument validation precision, and multi-turn execution efficiency against standardized enterprise QA scenarios.
729
+ - **Trigger Condition:** On-demand when benchmarking agent model upgrades, evaluating tool prompt updates, or running QA engine evaluations.
730
+ - **CLI Syntax:**
731
+ ```bash
732
+ # 1. Run QA function-calling benchmark across all test scenarios
733
+ python3 tools/synapse_qa_bench.py
734
+
735
+ # 2. Output detailed benchmark report as JSON
736
+ python3 tools/synapse_qa_bench.py --json
737
+ ```
738
+
739
+ ---
740
+
741
+ ### 40. `tools/synapse_observer.py` (Cognitive Observer & Tradeoff Sentinel)
742
+ - **Purpose:** Autonomous out-of-band observer inspired by Anthropic Claude Code 2.1.292 (`cc-plugin-you-should-know`). Evaluates code diffs or arbitrary text to surface critical tradeoffs (Clean POM violations, pipeline flakiness from static sleeps, un-teardowned entities, and tracked shortcuts) with high interruption threshold (defaults to `learn: none`).
743
+ - **Trigger Condition:** Autonomous pre-commit sanity check, PR review, or when prompted for tradeoff evaluation.
744
+ - **CLI Syntax:**
745
+ ```bash
746
+ # 1. Analyze working tree git diff (default)
747
+ python tools/synapse_observer.py
748
+
749
+ # 2. Analyze staged git diff (pre-commit)
750
+ python tools/synapse_observer.py --staged
751
+
752
+ # 3. Analyze specific file
753
+ python tools/synapse_observer.py --file tests/test_login.py
754
+
755
+ # 4. Strict mode for CI quality gates (exit 1 on active alert)
756
+ python tools/synapse_observer.py --strict
757
+
758
+ # 5. Output JSON for tool integration
759
+ python tools/synapse_observer.py --json
760
+
761
+ # 6. Evaluate and return all matching alerts
762
+ python tools/synapse_observer.py --all
763
+
764
+ # 7. Acknowledge / Unacknowledge / Reset memory
765
+ python tools/synapse_observer.py --ack static_sleep_flakiness
766
+ python tools/synapse_observer.py --unack static_sleep_flakiness
767
+ python tools/synapse_observer.py --reset
768
+ ```
769
+ - **Sample Output:**
770
+ ```text
771
+ learn: Static sleep was introduced, which creates pipeline flakiness and slows CI runs.
772
+ tag: Heads up
773
+ explain:
774
+ **Replace Static Sleep with Dynamic Smart Wait**
775
+ - Hardcoded sleeps either wait too long (wasting CI time) or not long enough under load.
776
+ - Use dynamic element visibility checks or network idle states instead.
777
+ - Dynamic waits resume immediately once the condition is met, saving time and eliminating flakiness.
778
+ ```
779
+
780
+ ---
781
+
782
+ ### 41. `tools/humanize_linter.py` (Humanize & Anti-AI Slop Linter)
783
+ - **Purpose:** Scans documentation, docstrings, commit messages, and PR descriptions to detect and eliminate robotic AI buzzwords, cliches, pileups, and punctuation quirks, offering human plain-language replacements while statefully masking code blocks and inline backticks.
784
+ - **Trigger Condition:** Pre-commit documentation check, commit message validation, PR review, or autonomous tone scan.
785
+ - **CLI Syntax:**
786
+ ```bash
787
+ # 1. Lint text string directly
788
+ python tools/humanize_linter.py --text "We leverage AI to optimize everything."
789
+
790
+ # 2. Lint documentation or markdown file
791
+ python tools/humanize_linter.py --file docs/README.md
792
+
793
+ # 3. Strict mode for CI gates (exit 1 if issues found)
794
+ python tools/humanize_linter.py --strict --file docs/README.md
795
+
796
+ # 4. Output results as structured JSON
797
+ python tools/humanize_linter.py --json --text "This is a vibrant tapestry."
798
+ ```
799
+ - **Sample Output:**
800
+ ```text
801
+ ⚠️ docs/README.md: Found 2 writing/tone issue(s):
802
+ - L5 [BUZZWORD]: 'leveraging' -> replace with 'use'
803
+ Excerpt: "We are leveraging this helper to build test cases."
804
+ - L12 [CLICHE]: 'plays a pivotal role' -> replace with 'is key'
805
+ Excerpt: "This utility plays a pivotal role in test data generation."
806
+ ```
807
+
808
+ ---
809
+
810
+ ### 42. `tools/security_coverage_ledger.py` (Mathematical Security Coverage Ledger)
811
+ - **Purpose:** Manages and validates deterministic security audit coverage units (`Coverage Unit = Surface × Boundary × Subsystem × Attack Class [× Lifecycle]`) using RFC 3986 percent-encoded canonical IDs, 19-field Cloudflare schema, and strict state invariants.
812
+ - **Trigger Condition:** Phase 1 & 2 reconnaissance and attack surface tracking during security audits, pre-release security validation.
813
+ - **CLI Syntax:**
814
+ ```bash
815
+ # 1. Initialize a new coverage ledger (supports 'object' or 'array' format)
816
+ python tools/security_coverage_ledger.py init -f coverage-ledger.json --format object
817
+
818
+ # 2. Add an audit coverage unit
819
+ python tools/security_coverage_ledger.py add -f coverage-ledger.json -s "web_api" -b "auth" --subsystem "billing" -a "idor"
820
+
821
+ # 3. Validate ledger state machine invariants and security rules
822
+ python tools/security_coverage_ledger.py validate coverage-ledger.json
823
+
824
+ # 4. Compute mathematical coverage metrics
825
+ python tools/security_coverage_ledger.py summary coverage-ledger.json
826
+
827
+ # 5. Output metrics as JSON for CI/CD integration
828
+ python tools/security_coverage_ledger.py summary coverage-ledger.json --json
829
+ ```
830
+ - **Sample Output:**
831
+ ```text
832
+ 📊 Security Coverage Ledger Metrics (12 total units):
833
+ - In-Scope Units: 10
834
+ - Audited Coverage: 80.0% (8/10 units)
835
+ - Blocker Rate: 10.0%
836
+ Status Breakdown:
837
+ - PLANNED : 2
838
+ - IN_PROGRESS : 0
839
+ - COVERED : 7
840
+ - CANDIDATE : 1
841
+ - BLOCKED : 1
842
+ - DEFERRED : 0
843
+ - NOT_APPLICABLE: 1
844
+ - OUT_OF_SCOPE : 1
845
+ Wave Breakdown:
846
+ - Wave 1 : 9
847
+ - Wave 2 : 3
848
+ ```
849
+
850
+ ---
851
+
852
+ ### 43. `tools/_openapi_parser.py` (Shared OpenAPI & Swagger Specification Parser)
853
+ - **Purpose:** Core parsing library for Swagger 2.0 and OpenAPI 3.0/3.1 specs, extracting routes, request/response models, auth schemes, and parameters into a canonical AST.
854
+ - **Trigger Condition:** Used internally by API matrix generators, contract drift sentinels, and API fuzzers.
855
+ - **CLI Syntax:**
856
+ ```bash
857
+ python tools/_openapi_parser.py <spec_file> [--validate]
858
+ ```
859
+
860
+ ---
861
+
862
+ ### 44. `tools/agentless_patcher.py` (Agentless 3-Stage Deterministic Patcher)
863
+ - **Purpose:** Implements the OpenAutoCoder/Agentless pattern for test repairs: Stage 1 (Fault localization via AST), Stage 2 (Candidate patch synthesis), Stage 3 (Minimal diff regression validation).
864
+ - **Trigger Condition:** Automated test failures requiring targeted locator or syntax repairs without multi-agent token bloat.
865
+ - **CLI Syntax:**
866
+ ```bash
867
+ python tools/agentless_patcher.py --file <file_path> --error "<error_message>" --test-cmd "pytest tests -q"
868
+ ```
869
+
870
+ ---
871
+
872
+ ### 45. `tools/auto_heal.py` (Closed-Loop Locator Self-Healing Engine)
873
+ - **Purpose:** Analyzes broken Page Class locators against current DOM/AOM snapshots and applies verified semantic replacements (role, label, test-id hierarchy).
874
+ - **Trigger Condition:** Playwright / Katalon NoSuchElementException or ElementNotFound failure.
875
+ - **CLI Syntax:**
876
+ ```bash
877
+ python tools/auto_heal.py --file <page_file> --broken "<selector>" --live-dom <dom.html>
878
+ # or via CLI
879
+ agent-qa heal --file <page_file>
880
+ ```
881
+
882
+ ---
883
+
884
+ ### 46. `tools/autogen_qa_broker.py` (Asynchronous Actor QA Message Broker)
885
+ - **Purpose:** Provides decoupled event publish/subscribe, mailbox routing, and priority message passing between subagents in a swarm (Microsoft AutoGen v0.4+ pattern).
886
+ - **Trigger Condition:** Multi-agent distributed test execution and matrix sharding coordination.
887
+ - **CLI Syntax:**
888
+ ```bash
889
+ python tools/autogen_qa_broker.py --publish --topic "test.results" --payload results.json
890
+ ```
891
+
892
+ ---
893
+
894
+ ### 47. `tools/benchmark_swarm_context.py` (Swarm Context Token Benchmark Harness)
895
+ - **Purpose:** Measures and benchmarks token throughput, context window occupancy, and savings achieved by Clean POM Flat Architecture and progressive disclosure (proving >= 40% savings).
896
+ - **Trigger Condition:** Measuring efficiency gains, auditing swarm prompt overhead, or reporting token metrics.
897
+ - **CLI Syntax:**
898
+ ```bash
899
+ python tools/benchmark_swarm_context.py --iterations 10 --report token_savings.json
900
+ ```
901
+
902
+ ---
903
+
904
+ ### 48. `tools/browsergym_eval.py` (BrowserGym Web Agent Benchmark Harness)
905
+ - **Purpose:** Benchmarks web automation agents against standardized enterprise tasks with headless <200ms latency budgets and ground-truth DB state verification (BrowserGym / WebArena pattern).
906
+ - **Trigger Condition:** Benchmarking autonomous QA agent navigation accuracy and speed.
907
+ - **CLI Syntax:**
908
+ ```bash
909
+ python tools/browsergym_eval.py --task "form_submit" --headless --budget-ms 200
910
+ ```
911
+
912
+ ---
913
+
914
+ ### 49. `tools/bump_version.py` (Atomic Universal Version Bumper)
915
+ - **Purpose:** Atomically bumps semantic versions across all 20 manifest and code targets (package.json, pyproject.toml, plugin.json, READMEs, config, docs).
916
+ - **Trigger Condition:** Pre-release version updates before running `tools/hub_publisher.py`.
917
+ - **CLI Syntax:**
918
+ ```bash
919
+ python tools/bump_version.py patch
920
+ python tools/bump_version.py minor
921
+ python tools/bump_version.py major
922
+ ```
923
+
924
+ ---
925
+
926
+ ### 50. `tools/contract_validator.py` (Swarm Data Contract Validator)
927
+ - **Purpose:** Validates JSON data contracts exchanged between subagents (e.g. Live Explorer to Pom Crafter) against strict JSON schemas (Single Front-Door Integrity Guard).
928
+ - **Trigger Condition:** Subagent handoff verification at Stage transitions in the FSM.
929
+ - **CLI Syntax:**
930
+ ```bash
931
+ python tools/contract_validator.py --contract handoff.json --schema schemas/handoff.json
932
+ ```
933
+
934
+ ---
935
+
936
+ ### 51. `tools/e2e_flow_prober.py` (Enterprise E2E Flow Prober & XPath Crawler)
937
+ - **Purpose:** Headless Playwright crawler that probes web user flows, maps interactive elements, and generates resilient locators across platforms.
938
+ - **Trigger Condition:** Flow discovery for unmapped pages and exploratory test generation.
939
+ - **CLI Syntax:**
940
+ ```bash
941
+ python tools/e2e_flow_prober.py --url https://staging.app.local --depth 2 --output flow_map.json
942
+ ```
943
+
944
+ ---
945
+
946
+ ### 52. `tools/fsm_enforcer.py` (5-Stage QA Multi-Agent Finite State Machine Enforcer)
947
+ - **Purpose:** Enforces deterministic 5-stage workflow progression (Discovery -> Synthesis -> Execution -> Autopsy -> Quality Gate) with SHA-256 cryptographic proof tokens.
948
+ - **Trigger Condition:** Transitioning between QA subagent lifecycle stages.
949
+ - **CLI Syntax:**
950
+ ```bash
951
+ python tools/fsm_enforcer.py init --task-id TASK_001
952
+ python tools/fsm_enforcer.py transition Stage2_Synthesis --token <proof_token>
953
+ ```
954
+
955
+ ---
956
+
957
+ ### 53. `tools/fsm_middleware.py` (Runtime FSM Interceptor & Tool Proxy)
958
+ - **Purpose:** Intercepts tool execution requests, enforcing that tools are only called when their corresponding FSM stage is active.
959
+ - **Trigger Condition:** Tool-calling guard in autonomous agent swarms.
960
+ - **CLI Syntax:**
961
+ ```bash
962
+ python tools/fsm_middleware.py --check-tool tools/verify_all.py --current-stage Stage5_QualityGate
963
+ ```
964
+
965
+ ---
966
+
967
+ ### 54. `tools/generate_allure_report.py` (Enterprise Allure HTML Report Generator)
968
+ - **Purpose:** Compiles raw Allure XML/JSON test results into a standalone HTML dashboard with trend graphs, failure timelines, and step attachments.
969
+ - **Trigger Condition:** Post-test reporting in CI/CD pipelines or local test runs.
970
+ - **CLI Syntax:**
971
+ ```bash
972
+ python tools/generate_allure_report.py --results ./allure-results --output ./Reports/allure-report
973
+ ```
974
+
975
+ ---
976
+
977
+ ### 55. `tools/generate_sbom.py` (SPDX 2.3 JSON Software Bill of Materials Generator)
978
+ - **Purpose:** Scans Python, Node.js, and Java/Gradle dependencies to generate an official SPDX 2.3 JSON SBOM for software supply chain security compliance.
979
+ - **Trigger Condition:** Release pipelines, pre-release security verification, or vendor audit compliance.
980
+ - **CLI Syntax:**
981
+ ```bash
982
+ python tools/generate_sbom.py --format spdx-json -o Reports/sbom.json
983
+ ```
984
+
985
+ ---
986
+
987
+ ### 56. `tools/generate_test_reports.py` (Enterprise Test Report Aggregator)
988
+ - **Purpose:** Consolidates multi-runner test execution outputs (JUnit XML, Pytest, Katalon, Allure) into unified summary JSON and markdown reports.
989
+ - **Trigger Condition:** Aggregating test results across parallel shards or multi-platform test suites.
990
+ - **CLI Syntax:**
991
+ ```bash
992
+ python tools/generate_test_reports.py --reports-dir ./Reports --output ./Reports/summary.json
993
+ ```
994
+
995
+ ---
996
+
997
+ ### 57. `tools/generate_tool_catalog.py` (Enterprise Tooling Catalog Generator)
998
+ - **Purpose:** Introspects all Python scripts in `tools/`, extracts AST docstrings, CLI arguments, and categories, generating `tools/TOOL_CATALOG.json`.
999
+ - **Trigger Condition:** Adding or modifying tools in `tools/` to maintain the canonical catalog.
1000
+ - **CLI Syntax:**
1001
+ ```bash
1002
+ python tools/generate_tool_catalog.py --output tools/TOOL_CATALOG.json
1003
+ ```
1004
+
1005
+ ---
1006
+
1007
+ ### 58. `tools/git_pre_commit_guard.py` (Enterprise Git Pre-Commit Architecture Guard)
1008
+ - **Purpose:** Enforces pre-commit invariants: blocks commits containing raw XPaths in test scripts, hardcoded secrets, UTF-8 BOM, or hub workspace pollution.
1009
+ - **Trigger Condition:** Executed by `.git/hooks/pre-commit` before any git commit is accepted.
1010
+ - **CLI Syntax:**
1011
+ ```bash
1012
+ python tools/git_pre_commit_guard.py [--staged]
1013
+ ```
1014
+
1015
+ ---
1016
+
1017
+ ### 59. `tools/goldfish_review.py` (Zero-Context Test Specification Reviewer)
1018
+ - **Purpose:** Stress-tests user stories, BDD specs, and acceptance criteria with zero-context rigor, uncovering ambiguous edge cases, missing error paths, and unstated assumptions.
1019
+ - **Trigger Condition:** Reviewing product requirements or user stories before test code generation.
1020
+ - **CLI Syntax:**
1021
+ ```bash
1022
+ python tools/goldfish_review.py path/to/spec.md
1023
+ ```
1024
+
1025
+ ---
1026
+
1027
+ ### 60. `tools/hub_publisher.py` (Autonomous 1-Click 5-Step Hub Release Pipeline)
1028
+ - **Purpose:** Executes the end-to-end Hub release: 1. Push main -> 2. Push tag vX.Y.Z -> 3. Create GitHub Release via API -> 4. Build GitHub Package -> 5. Publish & verify NPM registry.
1029
+ - **Trigger Condition:** User requests "push hub" or "publish hub" after SemVer bump.
1030
+ - **CLI Syntax:**
1031
+ ```bash
1032
+ python tools/hub_publisher.py [--dry-run]
1033
+ ```
1034
+
1035
+ ---
1036
+
1037
+ ### 61. `tools/init_config.py` (Project Configuration Bootstrapper)
1038
+ - **Purpose:** Initializes `synapse.config.json` with production defaults (quality gates, SLA thresholds, mutation settings, test runner paths).
1039
+ - **Trigger Condition:** Initializing a new target project or re-configuring quality gates.
1040
+ - **CLI Syntax:**
1041
+ ```bash
1042
+ python tools/init_config.py [--target-dir .]
1043
+ ```
1044
+
1045
+ ---
1046
+
1047
+ ### 62. `tools/jira_sync.py` (Jira / Xray / Zephyr Enterprise 2-Way Sync Engine)
1048
+ - **Purpose:** Pulls acceptance criteria and test cases from Jira/Xray, pushes automated execution results, and files defect tickets with attachments.
1049
+ - **Trigger Condition:** TMS integration in enterprise workflows with Jira/Xray/Zephyr.
1050
+ - **CLI Syntax:**
1051
+ ```bash
1052
+ python tools/jira_sync.py pull PROJ-1234
1053
+ python tools/jira_sync.py push-results --run-id RUN_567 --report results.xml
1054
+ ```
1055
+
1056
+ ---
1057
+
1058
+ ### 63. `tools/mcp_docx_server.py` (FastMCP Word .docx Document Server)
1059
+ - **Purpose:** Zero-dependency FastMCP server enabling AI agents to read, inspect, and extract text and tables from Word (`.docx`) documents without external Office dependencies.
1060
+ - **Trigger Condition:** When agent needs to inspect or extract requirements from `.docx` files.
1061
+ - **CLI Syntax:**
1062
+ ```bash
1063
+ python tools/mcp_docx_server.py
1064
+ # or via CLI
1065
+ agent-qa mcp-docx
1066
+ ```
1067
+
1068
+ ---
1069
+
1070
+ ### 64. `tools/mipro_assertion_tuner.py` (MIPROv2 Bayesian Prompt Assertion Tuner)
1071
+ - **Purpose:** Uses Bayesian teleprompter optimization (DSPy v2 + Optuna TPE) to tune few-shot assertion generators against mutation kill scores.
1072
+ - **Trigger Condition:** Optimizing QA prompt instructions and few-shot examples when mutation score < 80%.
1073
+ - **CLI Syntax:**
1074
+ ```bash
1075
+ python tools/mipro_assertion_tuner.py --trials 20 --min-kill 85.0
1076
+ ```
1077
+
1078
+ ---
1079
+
1080
+ ### 65. `tools/omni_emitter.py` (Universal Polyglot Clean POM Code Emitter)
1081
+ - **Purpose:** Generates Clean POM Page Classes and test scripts across Playwright TypeScript, Python Pytest, Java TestNG, and Katalon Groovy from Universal IR.
1082
+ - **Trigger Condition:** Stage 2 Code Synthesis by `pom-crafter` subagent.
1083
+ - **CLI Syntax:**
1084
+ ```bash
1085
+ python tools/omni_emitter.py --ir suite_ir.json --lang typescript -o tests/
1086
+ ```
1087
+
1088
+ ---
1089
+
1090
+ ### 66. `tools/omni_parser.py` (Deterministic Polyglot AST Parser)
1091
+ - **Purpose:** Parses existing Page Classes and test files into Universal IR with 0 LLM tokens, extracting locators, actions, and assertion flows.
1092
+ - **Trigger Condition:** Reverse-engineering existing test suites or preparing migration to another framework.
1093
+ - **CLI Syntax:**
1094
+ ```bash
1095
+ python tools/omni_parser.py --src ./tests --emit-ir ./suite_ir.json
1096
+ ```
1097
+
1098
+ ---
1099
+
1100
+ ### 67. `tools/openxml_guard.py` (OpenXML Security & Protocol Defense Guard)
1101
+ - **Purpose:** Audits generated and parsed Excel/Word OpenXML packages for zip-bomb attacks, external entity injection (XXE), and macro risks.
1102
+ - **Trigger Condition:** Pre-flight validation before opening or exporting `.xlsx` / `.docx` files.
1103
+ - **CLI Syntax:**
1104
+ ```bash
1105
+ python tools/openxml_guard.py audit path/to/document.xlsx
1106
+ ```
1107
+
1108
+ ---
1109
+
1110
+ ### 68. `tools/package_release.py` (Enterprise Release Packager & Provenance Generator)
1111
+ - **Purpose:** Packages distribution archives (zip, tar.gz), creates SHA-256 checksum manifests, and verifies release file cleanliness.
1112
+ - **Trigger Condition:** Building release distribution bundles during CI/CD.
1113
+ - **CLI Syntax:**
1114
+ ```bash
1115
+ python tools/package_release.py --version 3.7.2 --output-dir dist/
1116
+ ```
1117
+
1118
+ ---
1119
+
1120
+ ### 69. `tools/project_state.py` (Enterprise Project State Machine & Memory Anchor)
1121
+ - **Purpose:** Maintains persistent session state, active subagent roles, completed checkpoints, and token-capped recall memory across long multi-turn sessions.
1122
+ - **Trigger Condition:** Session resumption, context compaction recovery, and multi-agent state coordination.
1123
+ - **CLI Syntax:**
1124
+ ```bash
1125
+ python tools/project_state.py get
1126
+ python tools/project_state.py set --key "active_role" --val "pom-crafter"
1127
+ ```
1128
+
1129
+ ---
1130
+
1131
+ ### 70. `tools/qa_event_stream.py` (Immutable QA Event Stream Engine)
1132
+ - **Purpose:** Records append-only deterministic action/observation timelines with SHA-256 hash chains, enabling reversible checkpoint rollbacks and full execution tracing (OpenHands pattern).
1133
+ - **Trigger Condition:** Tracing complex multi-step test executions and audit trails.
1134
+ - **CLI Syntax:**
1135
+ ```bash
1136
+ python tools/qa_event_stream.py record --event-type ACTION --payload '{"action":"click"}'
1137
+ python tools/qa_event_stream.py verify-chain
1138
+ ```
1139
+
1140
+ ---
1141
+
1142
+ ### 71. `tools/security_scanner.py` (Enterprise Security Sentinel & Vulnerability Scanner)
1143
+ - **Purpose:** Scans Python and NPM dependency trees against known CVE advisory databases (Pip-Audit / NPM Audit) and audits dangerous system call sinks.
1144
+ - **Trigger Condition:** Security gating during pre-commit, CI/CD, or `verify_all Gate 6`.
1145
+ - **CLI Syntax:**
1146
+ ```bash
1147
+ python tools/security_scanner.py [--strict]
1148
+ ```
1149
+
1150
+ ---
1151
+
1152
+ ### 72. `tools/spec_drift_sentinel.py` (Spec-to-Code Drift Sentinel)
1153
+ - **Purpose:** Analyzes drift between OpenAPI / BDD specs and implementation test suites, reporting untested endpoints, removed parameters, and schema mismatches.
1154
+ - **Trigger Condition:** Pre-merge CI checks to detect API contract changes unreflected in test code.
1155
+ - **CLI Syntax:**
1156
+ ```bash
1157
+ python tools/spec_drift_sentinel.py --spec api.json --tests ./tests
1158
+ ```
1159
+
1160
+ ---
1161
+
1162
+ ### 73. `tools/swe_qa_aci.py` (QA Agent-Computer Interface — SWE-agent Pattern)
1163
+ - **Purpose:** Provides a token-efficient code inspection and surgical editing interface for AI agents, limiting window reads to 40-50 lines and performing pre-commit AST checks.
1164
+ - **Trigger Condition:** Safe inspection and modification of large Page Classes without context blowout.
1165
+ - **CLI Syntax:**
1166
+ ```bash
1167
+ python tools/swe_qa_aci.py view --file path/to/Page.groovy --start 10 --end 50
1168
+ python tools/swe_qa_aci.py edit --file path/to/Page.groovy --line 25 --replace "..."
1169
+ ```
1170
+
1171
+ ---
1172
+
1173
+ ### 74. `tools/template_excel_exporter.py` (Template-Driven Excel Test Case Exporter)
1174
+ - **Purpose:** Exports Markdown test matrices into enterprise Excel workbooks formatted with cell styles, AutoFilters, and dropdown Data Validation (Risk Level, Priority, Automatable).
1175
+ - **Trigger Condition:** Generating formal client test deliverables from manual test suites.
1176
+ - **CLI Syntax:**
1177
+ ```bash
1178
+ python tools/template_excel_exporter.py test_cases.md -o output.xlsx --sheet-name "Regression"
1179
+ ```
1180
+
1181
+ ---
1182
+
1183
+ ### 75. `tools/test_memory_os.py` (Hierarchical QA Test Memory OS)
1184
+ - **Purpose:** Implements a 3-tier memory operating system (Core memory, Recall step logs, Archival semantic store) scoped by AUT version to prevent context rot (Letta / MemGPT pattern).
1185
+ - **Trigger Condition:** Long-running test campaigns, multi-suite session management, and persistent auth token reuse.
1186
+ - **CLI Syntax:**
1187
+ ```bash
1188
+ python tools/test_memory_os.py core-get --key "auth_token"
1189
+ python tools/test_memory_os.py recall-search "login failure"
1190
+ ```
1191
+
1192
+ ---
1193
+
1194
+ ### 76. `tools/tot_exploratory_tester.py` (Tree-of-Thoughts Exploratory Testing Engine)
1195
+ - **Purpose:** Decomposes complex user stories into a non-linear Tree-of-Thoughts with Happy Path, Boundary/Race, and Negative/Chaos branches scored via Beam Search.
1196
+ - **Trigger Condition:** Designing high-coverage exploratory charters and fuzzing scenarios for ambiguous features.
1197
+ - **CLI Syntax:**
1198
+ ```bash
1199
+ python tools/tot_exploratory_tester.py --story user_story.md --beam-width 3 -o exploratory_tree.json
1200
+ ```
1201
+
1202
+ ---
1203
+
1204
+ ### 77. `tools/trend_analytics.py` (Historical Quality Trend & Flakiness Analytics)
1205
+ - **Purpose:** Computes rolling historical pass/fail trends, flakiness entropy scores, and MTTR (mean time to repair) metrics across test suites over time.
1206
+ - **Trigger Condition:** Generating executive QA health reports and CI/CD quality dashboards.
1207
+ - **CLI Syntax:**
1208
+ ```bash
1209
+ python tools/trend_analytics.py --history ./Reports/history --output ./Reports/trends.json
1210
+ ```
1211
+
1212
+ ---
1213
+
1214
+ ### 78. `tools/ui_server.py` (Interactive QA Mission Control UI Server)
1215
+ - **Purpose:** Fast lightweight HTTP server providing an interactive browser UI for running audits, inspecting 10 Quality Gates, viewing test matrices, and monitoring swarm state.
1216
+ - **Trigger Condition:** User requests "ui", "mission control", or visual web interface for Synapse Hub.
1217
+ - **CLI Syntax:**
1218
+ ```bash
1219
+ python tools/ui_server.py [--port 8080] [--open]
1220
+ # or via CLI
1221
+ agent-qa ui
1222
+ ```
1223
+
1224
+ ---
1225
+
1226
+ ### 79. `tools/universal_ir.py` (Universal Intermediate Representation AST Model)
1227
+ - **Purpose:** Defines the language-agnostic JSON AST schema representing Page Classes, selectors, actions, assertions, and test suites for 0-token transpilation.
1228
+ - **Trigger Condition:** Framework transpilation, test suite serialization, and cross-platform codegen.
1229
+ - **CLI Syntax:**
1230
+ ```bash
1231
+ python tools/universal_ir.py validate suite_ir.json
1232
+ ```
1233
+
1234
+ ---
1235
+
1236
+ ### 80. `tools/agent_canary.py` (Autonomous Agent Canary & Mutation Testing Arena)
1237
+ - **Purpose:** Headless sandbox arena evaluating autonomous AI agents against controlled adversarial mutations, prompt injection probes, and canary traps before production deployment.
1238
+ - **Trigger Condition:** Validating agent resilience, testing new prompt signatures, or auditing agent workflows against behavioral drift.
1239
+ - **CLI Syntax:**
1240
+ ```bash
1241
+ python tools/agent_canary.py [--arena <name>] [--runs <N>]
1242
+ ```
1243
+
1244
+ ---
1245
+
1246
+ ### 81. `tools/api_drift_sentinel.py` (Enterprise API Contract Drift & Breaking Change Sentinel)
1247
+ - **Purpose:** Continuously compares live API responses with OpenAPI/Swagger contracts, detecting breaking schema mutations, removed properties, type alterations, and undocumented endpoints.
1248
+ - **Trigger Condition:** Pre-deployment CI/CD regression gates, scheduled API health checks, and CDC contract drift detection.
1249
+ - **CLI Syntax:**
1250
+ ```bash
1251
+ python tools/api_drift_sentinel.py --spec <swagger.json> --url <base_url>
1252
+ ```
1253
+
1254
+ ---
1255
+
1256
+ ### 82. `tools/check_env.py` (Enterprise QA Environment Diagnostic & Dependency Sentinel)
1257
+ - **Purpose:** Diagnostic health runner verifying the host execution environment: Python version, Node.js, Java runtime, Playwright headless browsers, active workspace structure, and missing CLI packages.
1258
+ - **Trigger Condition:** First-time onboarding, diagnosing runtime failures, or validating CI/CD runner environments.
1259
+ - **CLI Syntax:**
1260
+ ```bash
1261
+ python tools/check_env.py
1262
+ # or via CLI
1263
+ agent-qa doctor
1264
+ ```
1265
+
1266
+ ---
1267
+
1268
+ ### 83. `tools/check_version_sync.py` (Universal Version Synchronization Sentinel)
1269
+ - **Purpose:** Audits and enforces 100% version synchronization across all 20 repository manifest targets (`package.json`, `pyproject.toml`, `README.md`, `agentskills.json`, `tools/__init__.py`, etc.).
1270
+ - **Trigger Condition:** Pre-release verification, gate checking, and automated version bump audits.
1271
+ - **CLI Syntax:**
1272
+ ```bash
1273
+ python tools/check_version_sync.py [--fix]
1274
+ ```
1275
+
1276
+ ---
1277
+
1278
+ ### 84. `tools/cli.py` (Enterprise Agent-QA CLI Entrypoint)
1279
+ - **Purpose:** Unified CLI front-door providing human- and agent-friendly dispatch (`agent-qa` / `synapse`) routing subcommands across all specialized Hub tools.
1280
+ - **Trigger Condition:** Primary terminal entrypoint for all verification, auditing, testing, and healing commands.
1281
+ - **CLI Syntax:**
1282
+ ```bash
1283
+ python tools/cli.py <command> [args]
1284
+ # or via installed package
1285
+ agent-qa <command>
1286
+ ```
1287
+
1288
+ ---
1289
+
1290
+ ### 85. `tools/config_decoupler.py` (Environment & Secret Decoupling Engine)
1291
+ - **Purpose:** Scans test suites for hardcoded credentials, IP addresses, and URLs, automatically extracting them into decoupled `.env` files and environment-agnostic configuration templates.
1292
+ - **Trigger Condition:** Legacy test refactoring, open-source sanitization, or multi-environment pipeline migration.
1293
+ - **CLI Syntax:**
1294
+ ```bash
1295
+ python tools/config_decoupler.py --source <test_dir> --env-file .env
1296
+ ```
1297
+
1298
+ ---
1299
+
1300
+ ### 86. `tools/flaky_detector.py` (Enterprise Flaky Test Detector & Quarantine Sentinel)
1301
+ - **Purpose:** Runs candidate test suites across multiple repeated iterations to calculate flakiness probability, isolating non-deterministic tests into quarantine before pipeline poisoning.
1302
+ - **Trigger Condition:** Triage of non-deterministic CI failures or certifying test suite stability before release.
1303
+ - **CLI Syntax:**
1304
+ ```bash
1305
+ python tools/flaky_detector.py --test-cmd "<test_command>" --iterations 5 --threshold 0.2
1306
+ ```
1307
+
1308
+ ---
1309
+
1310
+ ### 87. `tools/fuzz_payloads.py` (Edge-Case Fuzzing & Input Sanitization Payload Catalog)
1311
+ - **Purpose:** Generates boundary value, negative, SQLi, XSS, unicode overflow, and surrogate pair fuzz payloads across 15 standard web input field types.
1312
+ - **Trigger Condition:** Boundary testing, automated security testing, synthetic test data generation, and form input validation.
1313
+ - **CLI Syntax:**
1314
+ ```bash
1315
+ python tools/fuzz_payloads.py --type <string|number|date|xss|sqli> [--count N]
1316
+ ```
1317
+
1318
+ ---
1319
+
1320
+ ### 88. `tools/gherkin_suite.py` (Gherkin BDD Suite Compiler — 0-Token Matrix Ingestion)
1321
+ - **Purpose:** Compiles Gherkin `.feature` files into expanded test execution matrices, coverage-gap reports, and Universal IR representations without LLM token cost.
1322
+ - **Trigger Condition:** Ingesting business requirements and BDD user stories into automated Clean POM test cases.
1323
+ - **CLI Syntax:**
1324
+ ```bash
1325
+ python tools/gherkin_suite.py --feature <file.feature> [-o <matrix.json>]
1326
+ ```
1327
+
1328
+ ---
1329
+
1330
+ ### 89. `tools/heal_pr_automator.py` (Self-Healing Confidence Scorer & PR Automator)
1331
+ - **Purpose:** Evaluates locator repair confidence scores, regression impact, and automatically constructs GitHub pull requests containing self-healed Page Class diffs.
1332
+ - **Trigger Condition:** Stage 5 closed-loop test self-healing pipeline upon successful locator repair.
1333
+ - **CLI Syntax:**
1334
+ ```bash
1335
+ python tools/heal_pr_automator.py --patch <patch_file> --min-confidence 0.85
1336
+ ```
1337
+
1338
+ ---
1339
+
1340
+ ### 90. `tools/heuristic_locator_matcher.py` (3-Layer Heuristic Locator Matcher)
1341
+ - **Purpose:** Fast 3-layer deterministic heuristic locator recovery (Exact Role/Name -> Structural AOM Hierarchy -> Fuzzy Levenshtein) delivering 0-token locator repairs under 10ms.
1342
+ - **Trigger Condition:** Instant autonomous recovery when a UI selector fails during live headless test runs.
1343
+ - **CLI Syntax:**
1344
+ ```bash
1345
+ python tools/heuristic_locator_matcher.py --broken-sel "<selector>" --dom <dom_snapshot.html>
1346
+ ```
1347
+
1348
+ ---
1349
+
1350
+ ### 91. `tools/lint_ai_docs.py` (Enterprise AI Documentation & Artifact Linter — Gate 4)
1351
+ - **Purpose:** Gate 4 Anti-Drift Guard auditing project documentation, ensuring zero hallucinated PageClasses, zero broken file links, and 100% alignment with real codebase symbols.
1352
+ - **Trigger Condition:** Definition of Done Gate 4 in `verify_all.py` and pre-commit checks.
1353
+ - **CLI Syntax:**
1354
+ ```bash
1355
+ python tools/lint_ai_docs.py [--strict]
1356
+ ```
1357
+
1358
+ ---
1359
+
1360
+ ### 92. `tools/lookup_tc.py` (Sub-Second Test Case Metadata Lookup Utility)
1361
+ - **Purpose:** Performs sub-second indexed search across all test suites, locating test cases by ID, tag (`@Smoke`, `@Regression`), name, or author.
1362
+ - **Trigger Condition:** Quick navigation to specific test scripts or finding test coverage for a requirement.
1363
+ - **CLI Syntax:**
1364
+ ```bash
1365
+ python tools/lookup_tc.py <TC_ID_or_keyword>
1366
+ ```
1367
+
1368
+ ---
1369
+
1370
+ ### 93. `tools/lookup_xpath.py` (Fast XPath & Selector Lookup Utility)
1371
+ - **Purpose:** Scans all Page Classes and object repositories to find occurrences of specific locators, identifying duplicates, fragile XPaths, or selector collision risks.
1372
+ - **Trigger Condition:** Refactoring Page Classes or investigating selector collisions.
1373
+ - **CLI Syntax:**
1374
+ ```bash
1375
+ python tools/lookup_xpath.py "<selector_or_text>"
1376
+ ```
1377
+
1378
+ ---
1379
+
1380
+ ### 94. `tools/matrix_sharder.py` (Duration-Balanced Test Matrix Sharder)
1381
+ - **Purpose:** Partitions test suites across $N$ parallel CI runners using historical execution durations (K-way number partitioning), minimizing total build completion time.
1382
+ - **Trigger Condition:** CI/CD matrix build setup and parallel test runner dispatch.
1383
+ - **CLI Syntax:**
1384
+ ```bash
1385
+ python tools/matrix_sharder.py --suite-dir <dir> --shards <N> [--history <durations.json>]
1386
+ ```
1387
+
1388
+ ---
1389
+
1390
+ ### 95. `tools/mcp_excel_server.py` (Enterprise FastMCP Excel Server — Zero-Dependency XLSX)
1391
+ - **Purpose:** Zero-dependency FastMCP server exposing tool endpoints for reading, writing, merging, and styling Excel spreadsheets directly through the Model Context Protocol.
1392
+ - **Trigger Condition:** AI agents inspecting, updating, or formatting enterprise Excel test suites without COM or MS Excel.
1393
+ - **CLI Syntax:**
1394
+ ```bash
1395
+ python tools/mcp_excel_server.py
1396
+ ```
1397
+
1398
+ ---
1399
+
1400
+ ### 96. `tools/mcp_server.py` (Synapse Hub Standard Model Context Protocol Server)
1401
+ - **Purpose:** Production MCP server exposing Synapse Hub QA intelligence, Page Class generation, test running, and diagnostic tools to Claude Desktop, Cursor, and Antigravity.
1402
+ - **Trigger Condition:** IDE integration and autonomous AI agent tool dispatch.
1403
+ - **CLI Syntax:**
1404
+ ```bash
1405
+ python tools/mcp_server.py
1406
+ ```
1407
+
1408
+ ---
1409
+
1410
+ ### 97. `tools/micro_mutator.py` (Assertion Sensitivity & Syntactic Micro-Mutation Sentinel — Gate 8)
1411
+ - **Purpose:** Gate 8 sentinel applying syntactic AST mutations (negating conditionals, removing assertions, swapping boolean flags) to measure test sensitivity and kill fake passes (threshold >= 80%).
1412
+ - **Trigger Condition:** Mandatory DoD Gate 8 in `verify_all.py`, PR quality gate, and test quality auditing.
1413
+ - **CLI Syntax:**
1414
+ ```bash
1415
+ python tools/micro_mutator.py [target_dir] [--min-score 80] [--test-cmd "<cmd>"]
1416
+ # or via CLI
1417
+ agent-qa mutate
1418
+ ```
1419
+
1420
+ ---
1421
+
1422
+ ### 98. `tools/newman_analyzer.py` (Postman/Newman Results Analyzer & CI/CD Gatekeeper)
1423
+ - **Purpose:** Sub-0.1s Postman/Newman JSON test execution report analyzer parsing assertions, timings, and failures to enforce CI/CD quality gates.
1424
+ - **Trigger Condition:** Post-execution Newman API test reporting in CI/CD pipelines.
1425
+ - **CLI Syntax:**
1426
+ ```bash
1427
+ python tools/newman_analyzer.py <run_results.json> [--max-failures 0] [--p95-sla 500]
1428
+ ```
1429
+
1430
+ ---
1431
+
1432
+ ### 99. `tools/output_formatter.py` (Standardized Output Formatter & Exit Code Specification)
1433
+ - **Purpose:** Formats CLI tool outputs into structured ANSI colored text, JSON, or JUnit XML with standardized exit codes across all Hub tools.
1434
+ - **Trigger Condition:** Standardized output rendering and machine-readable CI integrations.
1435
+ - **CLI Syntax:**
1436
+ ```bash
1437
+ python tools/output_formatter.py --format <text|json|junit>
1438
+ ```
1439
+
1440
+ ---
1441
+
1442
+ ### 100. `tools/repo_map.py` (Enterprise Repository Map Compressor & Context Optimizer)
1443
+ - **Purpose:** Builds compressed AST repository maps ranking Page Classes, helper methods, and entrypoints to give agents high-density context under 2,000 tokens.
1444
+ - **Trigger Condition:** Context optimization, agent exploration, anti-context-blowout guard.
1445
+ - **CLI Syntax:**
1446
+ ```bash
1447
+ python tools/repo_map.py [output_file] [--max-tokens 2048]
1448
+ ```
1449
+
1450
+ ---
1451
+
1452
+ ### 101. `tools/safety_firewall.py` (Action Safety Firewall & Blast Radius Containment Engine)
1453
+ - **Purpose:** Non-bypassable action firewall intercepting and blocking destructive operations (`DROP DATABASE`, `rm -rf`, `git push --force`) in agent workflows.
1454
+ - **Trigger Condition:** Safety guardrail during tool dispatch and command execution.
1455
+ - **CLI Syntax:**
1456
+ ```bash
1457
+ python tools/safety_firewall.py check "<command>"
1458
+ ```
1459
+
1460
+ ---
1461
+
1462
+ ### 102. `tools/setup_project.py` (Enterprise Autonomous Project Setup & Bootstrap Engine)
1463
+ - **Purpose:** Zero-command autonomous project bootstrapper tailoring AI agent guides, rules, and pre-commit hooks to the target repository stack.
1464
+ - **Trigger Condition:** Onboarding new repositories to Synapse Hub QA standards.
1465
+ - **CLI Syntax:**
1466
+ ```bash
1467
+ python tools/setup_project.py [target_directory]
1468
+ # or via CLI
1469
+ agent-qa setup
1470
+ ```
1471
+
1472
+ ---
1473
+
1474
+ ### 103. `tools/skillspector.py` (Enterprise SkillSpector AI Agent & MCP Security Scanner)
1475
+ - **Purpose:** Security scanner inspecting agent skill markdown files, prompts, and MCP configurations against 71 vulnerability vectors (prompt injection, obfuscation, dangerous commands).
1476
+ - **Trigger Condition:** Gate 9 pre-flight, skill auditing, hub publishing verification.
1477
+ - **CLI Syntax:**
1478
+ ```bash
1479
+ python tools/skillspector.py <skills_dir_or_file>
1480
+ # or via CLI
1481
+ agent-qa skillspector [path]
1482
+ ```
1483
+
1484
+ ---
1485
+
1486
+ ### 104. `tools/sync_agent_rules.py` (Unified AGENTS.md Rule Synchronizer for AI IDE Bridges)
1487
+ - **Purpose:** Single-source-of-truth compiler generating bridge rule files (`CLAUDE.md`, `.cursorrules`, `.windsurfrules`, `.cursor/rules/synapse-qa.mdc`) from `AGENTS.md`.
1488
+ - **Trigger Condition:** Updating `AGENTS.md`, pre-push verification (`--check`), IDE bridge generation.
1489
+ - **CLI Syntax:**
1490
+ ```bash
1491
+ python tools/sync_agent_rules.py [--check]
1492
+ ```
1493
+
1494
+ ---
1495
+
1496
+ ### 105. `tools/telemetry_correlator.py` (Full-Stack APM & Server Telemetry Performance Correlator)
1497
+ - **Purpose:** Correlates client-side test execution latencies with server hardware telemetry (CPU, RAM, DB pool) to pinpoint performance bottlenecks.
1498
+ - **Trigger Condition:** Performance testing analysis, spike triage, load testing correlation.
1499
+ - **CLI Syntax:**
1500
+ ```bash
1501
+ python tools/telemetry_correlator.py --jtl <results.jtl> --telemetry <metrics.csv>
1502
+ ```
1503
+
1504
+ ---
1505
+
1506
+ ### 106. `tools/trace_data_flow.py` (Universal Data Flow & Teardown Tracer)
1507
+ - **Purpose:** Taint analysis tracer mapping test entity creation to teardown deletion paths, ensuring zero database pollution.
1508
+ - **Trigger Condition:** Verifying idempotent test teardown compliance and entity lifecycles.
1509
+ - **CLI Syntax:**
1510
+ ```bash
1511
+ python tools/trace_data_flow.py <test_file_or_dir>
1512
+ ```
1513
+
1514
+ ---
1515
+
1516
+ ### 107. `tools/validate_groovy_scripts.py` (Pre-Check AST Validator for Groovy Scripts & Keywords)
1517
+ - **Purpose:** Static AST syntax and pattern validator for Katalon/Groovy test scripts, ensuring clean POM adherence, valid imports, and no forbidden patterns.
1518
+ - **Trigger Condition:** Pre-commit Katalon validation and CI pipeline gate.
1519
+ - **CLI Syntax:**
1520
+ ```bash
1521
+ python tools/validate_groovy_scripts.py <script_dir>
1522
+ ```
1523
+
1524
+ ---
1525
+
1526
+ ### 108. `tools/welcome_page.py` (Interactive Visual Landing Page & Hub Command Launcher)
1527
+ - **Purpose:** Generates and serves the interactive HTML landing page showcasing Synapse Hub features, quick-start guides, and command palettes.
1528
+ - **Trigger Condition:** Launching the Hub welcome dashboard for human users.
1529
+ - **CLI Syntax:**
1530
+ ```bash
1531
+ python tools/welcome_page.py [--open-browser]
1532
+ ```
1533
+
1534
+ ---
1535
+
1536
+ ### 109. `tools/skill_profiles.py` (AI Agent Skill Capability Profile Manager)
1537
+ - **Purpose:** Filters, lists, and exports the 53 standardized AI Agent skills across the 4 core capability profiles (`core-web-qa`, `perf-and-load`, `api-security`, `enterprise-rbt`).
1538
+ - **Trigger Condition:** Filtering skill catalogs, inspecting capability profiles, or executing `agent-qa skills` / `synapse-hub skills`.
1539
+ - **CLI Syntax:**
1540
+ ```bash
1541
+ # 1. List all 4 core capability profiles with descriptions and skill counts
1542
+ python tools/skill_profiles.py --list-profiles
1543
+
1544
+ # 2. Filter skills in a capability profile (text table or JSON)
1545
+ python tools/skill_profiles.py --profile core-web-qa
1546
+ python tools/skill_profiles.py --profile api-security --format json
1547
+
1548
+ # 3. Via central CLI
1549
+ agent-qa skills --list-profiles
1550
+ agent-qa skills -p perf-and-load
1551
+ ```
1552
+
1553
+