synapse-hub 2.2.4 → 2.4.0

package/tools/check_version_sync.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+tools/check_version_sync.py — Version Synchronization Sentinel for Synapse Hub
+
+Verifies that the release version is strictly consistent across all manifest,
+package, protocol, and CLI definitions in the repository:
+  1. package.json (NPM manifest)
+  2. pyproject.toml (PEP 621 Python package metadata)
+  3. plugin.json (Antigravity plugin manifest)
+  4. skills_manifest.json (Skill Catalog index)
+  5. synapse.config.json (Hub runtime configuration)
+  6. tools/mcp_server.py (MCP server protocol version)
+  7. tools/cli.py (Agent-QA CLI hub version)
+  8. tools/__init__.py (Python package version)
+
+Usage:
+  python3 tools/check_version_sync.py
+  python3 tools/check_version_sync.py --expected-version 2.3.0
+"""
+
+import os
+import sys
+import re
+import json
+import argparse
+from typing import Dict, Optional, Tuple
+
+REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+
+
+def extract_versions(repo_root: str) -> Dict[str, str]:
+    """Extracts declared versions across all source and manifest targets."""
+    versions: Dict[str, str] = {}
+
+    # 1. package.json
+    pkg_path = os.path.join(repo_root, "package.json")
+    if os.path.exists(pkg_path):
+        with open(pkg_path, "r", encoding="utf-8") as f:
+            versions["package.json"] = json.load(f).get("version", "")
+
+    # 2. pyproject.toml
+    pyproject_path = os.path.join(repo_root, "pyproject.toml")
+    if os.path.exists(pyproject_path):
+        with open(pyproject_path, "r", encoding="utf-8") as f:
+            content = f.read()
+            m = re.search(r'(?m)^version\s*=\s*["\']([^"\']+)["\']', content)
+            if m:
+                versions["pyproject.toml"] = m.group(1)
+
+    # 3. plugin.json
+    plugin_path = os.path.join(repo_root, "plugin.json")
+    if os.path.exists(plugin_path):
+        with open(plugin_path, "r", encoding="utf-8") as f:
+            versions["plugin.json"] = json.load(f).get("version", "")
+
+    # 4. skills_manifest.json
+    manifest_path = os.path.join(repo_root, "skills_manifest.json")
+    if os.path.exists(manifest_path):
+        with open(manifest_path, "r", encoding="utf-8") as f:
+            versions["skills_manifest.json"] = json.load(f).get("version", "")
+
+    # 5. synapse.config.json
+    config_path = os.path.join(repo_root, "synapse.config.json")
+    if os.path.exists(config_path):
+        with open(config_path, "r", encoding="utf-8") as f:
+            versions["synapse.config.json"] = json.load(f).get("version", "")
+
+    # 6. tools/mcp_server.py
+    mcp_path = os.path.join(repo_root, "tools", "mcp_server.py")
+    if os.path.exists(mcp_path):
+        with open(mcp_path, "r", encoding="utf-8") as f:
+            content = f.read()
+            m = re.search(r'SERVER_VERSION\s*=\s*["\']([^"\']+)["\']', content)
+            if m:
+                versions["tools/mcp_server.py"] = m.group(1)
+
+    # 7. tools/cli.py
+    cli_path = os.path.join(repo_root, "tools", "cli.py")
+    if os.path.exists(cli_path):
+        with open(cli_path, "r", encoding="utf-8") as f:
+            content = f.read()
+            m = re.search(r'version\s*=\s*["\']([^"\']+)["\']', content)
+            if m:
+                versions["tools/cli.py"] = m.group(1)
+
+    # 8. tools/__init__.py
+    init_path = os.path.join(repo_root, "tools", "__init__.py")
+    if os.path.exists(init_path):
+        with open(init_path, "r", encoding="utf-8") as f:
+            content = f.read()
+            m = re.search(r'__version__\s*=\s*["\']([^"\']+)["\']', content)
+            if m:
+                versions["tools/__init__.py"] = m.group(1)
+
+    return versions
+
+
+def check_sync(repo_root: str, expected_version: Optional[str] = None) -> Tuple[bool, Dict[str, str], str]:
+    """
+    Checks if all version definitions match.
+    Returns (is_synced, versions_dict, canonical_version_or_error_msg).
+    """
+    versions = extract_versions(repo_root)
+    if not versions:
+        return False, {}, "No version files found in repository."
+
+    target_ver = expected_version or versions.get("package.json")
+    if not target_ver:
+        target_ver = next(iter(versions.values()))
+
+    mismatches = {path: ver for path, ver in versions.items() if ver != target_ver}
+    if mismatches:
+        return False, versions, target_ver
+    return True, versions, target_ver
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Verify universal version sync across Synapse Hub files")
+    parser.add_argument("--expected-version", "-e", help="Expected version string (e.g. from git tag)", default=None)
+    parser.add_argument("--repo-root", default=REPO_ROOT, help="Root directory of the repository")
+    args = parser.parse_args()
+
+    expected = args.expected_version
+    if expected and expected.startswith("v"):
+        expected = expected[1:]
+
+    is_synced, versions, canonical = check_sync(args.repo_root, expected)
+
+    print("======================================================================")
+    print("      SYNAPSE HUB - UNIVERSAL VERSION SYNCHRONIZATION AUDIT          ")
+    print("======================================================================")
+    print(f"Target Version: v{canonical}")
+    print("----------------------------------------------------------------------")
+
+    all_matched = True
+    for file_path, ver in sorted(versions.items()):
+        status = "[MATCH]" if ver == canonical else "[MISMATCH]"
+        if ver != canonical:
+            all_matched = False
+        print(f"  {status:<11} {file_path:<26} -> {ver}")
+
+    print("======================================================================")
+    if is_synced and all_matched:
+        print(f"[PASS] 100% Version synchronization verified across all {len(versions)} targets.")
+        return 0
+    else:
+        print(f"[FAIL] Version mismatch detected! All components must match v{canonical}.")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/ci_healing_hook.py

@@ -54,7 +54,7 @@ The Self-Healing Engine successfully located the replacement element:
 ### ✅ Verification Status
 - [x] In-place AST replacement verified
 - [x] Syntax checked across target framework
-- [x] DoD 8 Quality Gates checked
+- [x] DoD 9 Quality Gates checked
 
 ### 🚀 QA Action Required
 Review the diff above and **Merge PR** to lock the healed locator into main branch.

package/tools/cli.py

@@ -12,6 +12,7 @@ Dispatches commands to underlying specialized tools in tools/.
 
 import os
 import sys
+import json
 import argparse
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
@@ -29,23 +30,23 @@ sys.path.insert(0, SCRIPT_DIR)
 
 def cmd_version(args):
     manifest_path = os.path.join(REPO_ROOT, "skills_manifest.json")
-    version = "2.2.4"
+    version = "2.4.0"
     if os.path.exists(manifest_path):
         try:
             import json
             with open(manifest_path, "r", encoding="utf-8") as f:
                 data = json.load(f)
                 version = data.get("version", version)
-        except Exception:
+        except (OSError, json.JSONDecodeError):
             pass
     print(f"Agent-QA Hub CLI v{version}")
-    manifest_skills = 28
+    manifest_skills = 38
     if os.path.exists(manifest_path):
         try:
             import json
             with open(manifest_path, "r", encoding="utf-8") as f:
-                manifest_skills = json.load(f).get("totalSkills", 28)
-        except Exception:
+                manifest_skills = json.load(f).get("totalSkills", 37)
+        except (OSError, json.JSONDecodeError):
             pass
     print(f"Catalog: {manifest_skills} Standardized Skills | 6 Subagent Swarm Profiles")
     print("Created by: Thế Vị (@TeeVee998) <https://github.com/TeeVee998/Synapse-Hub>")
@@ -112,7 +113,7 @@ def cmd_clean(args):
                 try:
                     os.remove(os.path.join(root, f))
                     removed_count += 1
-                except Exception:
+                except OSError:
                     pass
     print(f"✅ Cleanup finished: {removed_count} build artifacts and caches removed.")
 
@@ -141,6 +142,19 @@ def cmd_setup(args):
     sys.exit(setup_main())
 
 
+def cmd_doctor(args):
+    from check_env import main as check_env_main
+    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.exit(check_env_main())
+
+
+def cmd_uninstall(args):
+    from setup_project import uninstall_setup, resolve_target_repo
+    target = getattr(args, "target", None)
+    target_repo = resolve_target_repo(cli_target=target)
+    sys.exit(uninstall_setup(target_repo))
+
+
 def cmd_auto_heal(args):
     from auto_heal import main as auto_heal_main
     sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
@@ -233,6 +247,18 @@ def cmd_visual_mask(args):
     sys.exit(mask_main())
 
 
+def cmd_review_spec(args):
+    from goldfish_review import main as review_main
+    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.exit(review_main())
+
+
+def cmd_drift_check(args):
+    from spec_drift_sentinel import main as drift_main
+    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.exit(drift_main())
+
+
 def cmd_ci_hook(args):
     from ci_healing_hook import main as hook_main
     sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
@@ -259,8 +285,8 @@ def cmd_migrate(args):
                     try:
                         transpile_file(file_path, target, output_dir=dest, hermetic=True)
                         migrated_count += 1
-                    except Exception:
-                        pass
+                    except (OSError, ValueError, SyntaxError) as e:
+                        print(f"  ⚠️ Skipping {f}: {e}")
         print(f"✅ [MIGRATION COMPLETE] {migrated_count} test files converted to {target} in '{dest}'.")
     else:
         transpile_file(src, target, output_dir=dest, hermetic=True)
@@ -285,6 +311,12 @@ def cmd_som(args):
     sys.exit(som_main())
 
 
+def cmd_gherkin(args):
+    from gherkin_suite import main as gherkin_main
+    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.exit(gherkin_main())
+
+
 def cmd_export_postman(args):
     from export_postman_collection import main as postman_main
     sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
@@ -309,6 +341,12 @@ def cmd_analyze_jtl(args):
     sys.exit(jtl_main())
 
 
+def cmd_export_excel(args):
+    from md_to_xlsx import main as excel_main
+    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.exit(excel_main())
+
+
 def cmd_correlate_telemetry(args):
     from telemetry_correlator import main as telem_main
     sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
@@ -336,17 +374,107 @@ def cmd_update(args):
     update_sentinel.perform_update()
 
 
+def cmd_tokens(args):
+    import count_tokens
+    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    count_tokens.main()
+
+
+def cmd_dashboard(args):
+    import dashboard_generator
+    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    dashboard_generator.main()
+
+
+def cmd_watch(args):
+    import watch_mode
+    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    watch_mode.main()
+
+
+def cmd_welcome(args):
+    import welcome_page
+    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    welcome_page.main()
+
+
+def cmd_wcag_audit(args):
+    from wcag_audit import main as wcag_main
+    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.exit(wcag_main())
+
+
+def cmd_lookup_tc(args):
+    from lookup_tc import main as tc_main
+    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.exit(tc_main())
+
+
+def cmd_lookup_xpath(args):
+    from lookup_xpath import main as xpath_main
+    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.exit(xpath_main())
+
+
+def cmd_trace_data_flow(args):
+    from trace_data_flow import main as tdf_main
+    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.exit(tdf_main())
+
+
+def cmd_generate_tc(args):
+    from generate_tc_from_story import main as gen_tc_main
+    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.exit(gen_tc_main())
+
+
+def cmd_pinpoint_failure(args):
+    from pinpoint_failure import main as pp_main
+    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.exit(pp_main())
+
+
+def cmd_sync_rules(args):
+    from sync_agent_rules import main as sync_rules_main
+    sys.argv = [sys.argv[0]] + (sys.argv[2:] if len(sys.argv) > 2 else [])
+    sys.exit(sync_rules_main())
+
+
+def _hub_version():
+    manifest_path = os.path.join(REPO_ROOT, "skills_manifest.json")
+    version = "2.4.0"
+    if os.path.exists(manifest_path):
+        try:
+            import json
+            with open(manifest_path, "r", encoding="utf-8") as f:
+                version = json.load(f).get("version", version)
+        except (OSError, json.JSONDecodeError):
+            pass
+    return version
+
+
 def main():
     parser = argparse.ArgumentParser(
         prog="agent-qa",
         description="Enterprise AI Agent Quality Engineering & Test Automation Hub CLI"
     )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"Agent-QA Hub CLI v{_hub_version()}"
+    )
     parser.add_argument(
         "--offline", "--offline-deterministic",
         action="store_true",
         dest="offline",
         help="Force 100%% offline air-gapped deterministic mode (zero external network / LLM API calls)"
     )
+    parser.add_argument(
+        "-q", "--quiet",
+        action="store_true",
+        dest="quiet",
+        help="Suppress informational banners and output only critical verdicts"
+    )
     subparsers = parser.add_subparsers(dest="subcommand", help="Available subcommands")
 
     # version
@@ -357,6 +485,18 @@ def main():
     p_setup = subparsers.add_parser("setup", help="Autonomous 1-click bootstrap of target project (AI guide, Git hook, AST map)")
     p_setup.set_defaults(func=cmd_setup)
 
+    # doctor
+    p_doctor = subparsers.add_parser("doctor", description="Enterprise Environment Diagnostic Tool", help="Run 1-click diagnostic check of system environment, tools, and dependencies")
+    p_doctor.add_argument("target", nargs="?", default=None, help="Target repository path to diagnose")
+    p_doctor.add_argument("--repo", "--path", dest="repo_path", default=None, help="Target repository path")
+    p_doctor.add_argument("--insecure", action="store_true", help="Allow unverified SSL certificates during connectivity checks")
+    p_doctor.set_defaults(func=cmd_doctor)
+
+    # uninstall
+    p_uninstall = subparsers.add_parser("uninstall", help="Revert and remove files installed by setup in target project")
+    p_uninstall.add_argument("target", nargs="?", default=None, help="Target repository path to revert")
+    p_uninstall.set_defaults(func=cmd_uninstall)
+
     # auto-heal
     p_auto_heal = subparsers.add_parser("auto-heal", help="Autonomous closed-loop test failure diagnosis and healing plan")
     p_auto_heal.set_defaults(func=cmd_auto_heal)
@@ -366,7 +506,7 @@ def main():
     p_heal_pr.set_defaults(func=cmd_heal_pr)
 
     # mutate
-    p_mut = subparsers.add_parser("mutate", help="Inject AST micro-mutants to verify test assertion strength")
+    p_mut = subparsers.add_parser("mutate", help="Inject syntactic micro-mutants to verify test assertion strength")
     p_mut.set_defaults(func=cmd_mutate)
 
     # shard
@@ -390,7 +530,7 @@ def main():
     p_analyze.set_defaults(func=cmd_analyze)
 
     # verify
-    p_verify = subparsers.add_parser("verify", help="Execute 7 Quality Gates DoD Verification")
+    p_verify = subparsers.add_parser("verify", help="Execute 9 Quality Gates DoD Verification")
     p_verify.set_defaults(func=cmd_verify)
 
     # lint
@@ -409,6 +549,10 @@ def main():
     p_impact = subparsers.add_parser("impact", help="Analyze code change impact using AST Knowledge Graph")
     p_impact.set_defaults(func=cmd_impact)
 
+    # gherkin
+    p_gherkin = subparsers.add_parser("gherkin", help="Compile Gherkin .feature files into test matrix, Universal IR and coverage-gap report (0-token)")
+    p_gherkin.set_defaults(func=cmd_gherkin)
+
     # canary
     p_canary = subparsers.add_parser("canary", help="Run autonomous canary resilience benchmark")
     p_canary.set_defaults(func=cmd_canary)
@@ -484,6 +628,13 @@ def main():
     p_jtl = subparsers.add_parser("analyze-jtl", help="Analyze JMeter .jtl results, evaluate P90/P95/P99 SLA, and enforce CI/CD Quality Gate")
     p_jtl.set_defaults(func=cmd_analyze_jtl)
 
+    # export-excel
+    p_excel = subparsers.add_parser("export-excel", help="Convert Markdown Test Cases into Styled Enterprise Excel (.xlsx)")
+    p_excel.add_argument("input", nargs="?", help="Path to input Markdown file (.md)")
+    p_excel.add_argument("-o", "--output", help="Path to output Excel file (.xlsx)")
+    p_excel.add_argument("--sheet-name", default="Test Cases", help="Worksheet title (default: Test Cases)")
+    p_excel.set_defaults(func=cmd_export_excel)
+
     # correlate-telemetry
     p_telemetry = subparsers.add_parser("correlate-telemetry", help="Correlate Client-Side JMeter latency with Server-Side APM CPU/RAM/DB telemetry")
     p_telemetry.set_defaults(func=cmd_correlate_telemetry)
@@ -509,6 +660,101 @@ def main():
     p_author = subparsers.add_parser("verify-author", help="Verify author attribution, provenance, and anti-tamper integrity")
     p_author.set_defaults(func=cmd_verify_author)
 
+    # tokens (Cross-Platform Token & Cost Auditor)
+    p_tokens = subparsers.add_parser("tokens", help="Audit token usage and estimated API cost across Antigravity, Cursor, and Claude Code")
+    p_tokens.add_argument("--platform", "-p", choices=["auto", "antigravity", "cursor", "claude", "all"], default="auto", help="AI platform to audit (default: auto)")
+    p_tokens.add_argument("--session", type=str, help="Specific session ID or index to audit")
+    p_tokens.add_argument("--current", action="store_true", help="Audit current active conversation")
+    p_tokens.add_argument("--last", action="store_true", help="Audit previous completed session (default)")
+    p_tokens.add_argument("--last-task", action="store_true", help="Audit specifically the last turn of target session")
+    p_tokens.add_argument("--turns", action="store_true", help="Show full turn-by-turn breakdown table")
+    p_tokens.add_argument("--rolling", "--budget", action="store_true", dest="rolling", help="Show 5-hour and 7-day rolling window quota & remaining tokens")
+    p_tokens.add_argument("--savings", action="store_true", help="Show Hub vs. Non-Hub token and cost savings comparison")
+    p_tokens.add_argument("--header", action="store_true", help="Print Pre-Flight confirmation block lines")
+    p_tokens.add_argument("--list", action="store_true", help="List recent conversations")
+    p_tokens.add_argument("--pricing", choices=["gemini-flash", "gemini-pro", "claude-sonnet", "claude-opus", "gpt-4o", "gpt-4o-mini"], default=None, help="Model pricing basis (default: auto-detected)")
+    p_tokens.add_argument("--json", action="store_true", help="Output machine-readable JSON format")
+    p_tokens.add_argument("--file", type=str, help="Direct path to a transcript.jsonl file")
+    p_tokens.set_defaults(func=cmd_tokens)
+
+    # dashboard (Standalone One-Page HTML Executive Dashboard)
+    p_dashboard = subparsers.add_parser("dashboard", help="Generate standalone one-page executive HTML dashboard (zero CDN deps)")
+    p_dashboard.add_argument("target", nargs="?", default=None, help="Target repository directory (default: current or Hub)")
+    p_dashboard.add_argument("--output", "-o", help="Output HTML file path (default: <target>/reports/PROJECT_DASHBOARD.html)")
+    p_dashboard.add_argument("--open", action="store_true", help="Automatically open generated dashboard in default browser")
+    p_dashboard.add_argument("--json", action="store_true", help="Print summary JSON to stdout")
+    p_dashboard.add_argument("--lang", choices=["vi", "en"], default="vi", help="Default display language (vi: Tiếng Việt, en: English, default: vi)")
+    p_dashboard.set_defaults(func=cmd_dashboard)
+
+    # watch (Real-Time Incremental Watch Mode Sentinel)
+    p_watch = subparsers.add_parser("watch", help="Real-Time incremental watch mode & test engineering HUD (< 100ms feedback)")
+    p_watch.add_argument("target", nargs="?", default=".", help="Directory to monitor (default: current directory)")
+    p_watch.add_argument("--debounce", type=float, default=0.8, help="Debounce interval in seconds (default: 0.8)")
+    p_watch.add_argument("--inactivity-timeout", type=float, default=0.0, help="Inactivity timeout in seconds to trigger stuck warning (default: 0 = disabled)")
+    p_watch.add_argument("--once", action="store_true", help="Run incremental scan once on all files and exit")
+    p_watch.set_defaults(func=cmd_watch)
+
+    # welcome (Interactive Visual Landing Page)
+    p_welcome = subparsers.add_parser("welcome", description="Interactive Visual Landing Page", help="Launch interactive visual landing page introducing Synapse Hub")
+    p_welcome.add_argument("target", nargs="?", default=None, help="Target repository directory (default: current directory)")
+    p_welcome.add_argument("--output", "-o", default=None, help="Output HTML file path (default: reports/WELCOME.html)")
+    p_welcome.add_argument("--lang", choices=["vi", "en"], default="vi", help="Default initial language (default: vi = Vietnamese)")
+    p_welcome.add_argument("--no-browser", action="store_true", help="Do not open the browser after generating the page")
+    p_welcome.add_argument("--open", action="store_true", help="Explicitly open the browser")
+    p_welcome.add_argument("--first-run", action="store_true", help="Only open if running for the first time (e.g. npm install or first pull)")
+    p_welcome.set_defaults(func=cmd_welcome)
+
+    # wcag-audit (WCAG 2.2 Accessibility Sentinel)
+    p_wcag = subparsers.add_parser("wcag-audit", help="Audit WCAG 2.2 accessibility conformance and contrast ratios")
+    p_wcag.add_argument("target", nargs="?", default=".", help="Target HTML file or directory to audit")
+    p_wcag.set_defaults(func=cmd_wcag_audit)
+
+    # lookup-tc (Deterministic Test Case Identifier Index)
+    p_lookup_tc = subparsers.add_parser("lookup-tc", help="Search test cases by ID, tag, priority, or flow")
+    p_lookup_tc.add_argument("query", nargs="?", default="", help="Query keyword or TC ID")
+    p_lookup_tc.set_defaults(func=cmd_lookup_tc)
+
+    # lookup-xpath (AOM & DOM Selector Lookup Cache)
+    p_lookup_xpath = subparsers.add_parser("lookup-xpath", help="Query cached resilient XPath & AOM locators")
+    p_lookup_xpath.add_argument("query", nargs="?", default="", help="Element text, test-id, or locator label")
+    p_lookup_xpath.set_defaults(func=cmd_lookup_xpath)
+
+    # trace-data-flow (Idempotent Data Flow & Taint Analysis)
+    p_trace = subparsers.add_parser("trace-data-flow", help="Trace test data lifecycles to detect DB leaks and missing teardowns")
+    p_trace.add_argument("target", nargs="?", default=".", help="Target test directory to inspect")
+    p_trace.set_defaults(func=cmd_trace_data_flow)
+
+    # generate-tc (User Story & Acceptance Criteria Compiler)
+    p_gen_tc = subparsers.add_parser("generate-tc", help="Compile natural language user stories into Clean POM test cases")
+    p_gen_tc.add_argument("story_file", nargs="?", default="", help="Path to markdown/text user story specification")
+    p_gen_tc.set_defaults(func=cmd_generate_tc)
+
+    # pinpoint-failure (Instant JUnit XML Root Cause Autopsy)
+    p_pinpoint = subparsers.add_parser("pinpoint-failure", help="Parse JUnit XML and locate exact failing line in 0.1s")
+    p_pinpoint.add_argument("report_file", nargs="?", default="", help="Path to JUnit XML test report")
+    p_pinpoint.set_defaults(func=cmd_pinpoint_failure)
+
+    # sync-rules (Single-Source Agent Rules Synchronizer)
+    p_sync_rules = subparsers.add_parser("sync-rules", help="Synchronize AGENTS.md single source of truth across all AI IDE bridges")
+    p_sync_rules.add_argument("--check", action="store_true", help="Verify all AI bridges are in sync without writing")
+    p_sync_rules.set_defaults(func=cmd_sync_rules)
+
+    # review-spec (Zero-Context Test Spec Auditor - Elephant-Goldfish Model)
+    p_review = subparsers.add_parser("review-spec", help="Zero-context stress-test for specifications and user stories (Elephant-Goldfish Model)")
+    p_review.add_argument("spec_file", nargs="?", default="", help="Path to specification file (Markdown or Gherkin .feature, use '-' for stdin)")
+    p_review.add_argument("--stdin", action="store_true", help="Read specification from standard input (stdin)")
+    p_review.add_argument("--json", action="store_true", help="Output machine-readable JSON format")
+    p_review.add_argument("--min-score", type=int, default=80, help="Minimum readiness score threshold (default: 80)")
+    p_review.set_defaults(func=cmd_review_spec)
+
+    # drift-check (Spec-to-Code Drift Sentinel)
+    p_drift = subparsers.add_parser("drift-check", help="Spec-to-Code Drift Sentinel checking Deficit & Scope Drift")
+    p_drift.add_argument("--spec", required=True, help="Path to specification file (Markdown or Gherkin .feature)")
+    p_drift.add_argument("--code", required=True, help="Path to test script or directory of test scripts")
+    p_drift.add_argument("--markdown", "-m", help="Path to export Markdown drift report (e.g. SPEC_DRIFT_REPORT.md)")
+    p_drift.add_argument("--json", action="store_true", help="Output machine-readable JSON format")
+    p_drift.set_defaults(func=cmd_drift_check)
+
     args, unknown = parser.parse_known_args()
     if getattr(args, "offline", False):
         os.environ["AGENT_QA_OFFLINE"] = "1"
@@ -516,18 +762,22 @@ def main():
 
     if not args.subcommand:
         parser.print_help()
+        print("\n💡 Tip: Run 'npx synapse-hub welcome' (or 'npm start') to launch the visual landing page.")
         sys.exit(0)
 
-    # Enforce cryptographic author attribution and anti-tamper provenance
+    # Enforce canonical author attribution and anti-tamper provenance
     from author_integrity import assert_integrity_or_raise
     assert_integrity_or_raise()
 
+    if getattr(args, "quiet", False):
+        os.environ["SYNAPSE_QUIET"] = "1"
+
     # Non-intrusive cached update notification (24h cache)
-    if args.subcommand not in ("update", "mcp-serve", "version"):
+    if args.subcommand not in ("update", "mcp-serve", "version") and not getattr(args, "quiet", False):
         try:
             import update_sentinel
             update_sentinel.check_for_updates(force=False, notify=True)
-        except Exception:
+        except (ImportError, OSError, TimeoutError):
             pass
 
     # Dispatch subcommand