synapse-hub 2.4.3 → 2.6.0

package/tools/dspy_qa_signatures.py

@@ -0,0 +1,357 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.
+# SPDX-License-Identifier: MIT
+# Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
+
+"""
+Declarative QA Signature Compilation Engine (Stanford DSPy Pattern)
+--------------------------------------------------------------------
+Replaces brittle static prompt strings with typed declarative DSPy signatures.
+Enables prompt compilation via BootstrapFewShot and MIPROv2, optimizing test
+synthesis directly against Synapse-Hub's 10 Quality Gates DoD metric.
+
+Reference:
+  - Omar Khattab et al. (Stanford NLP DSPy: Compiling Declarative Language Model Calls).
+  - Synapse-Hub Subsystem 3: Section 6.4 of agent_skill_training_analysis.md.
+"""
+
+import os
+import sys
+import json
+import re
+import argparse
+from typing import Dict, Any, Optional, Tuple, List
+
+# Enforce UTF-8 stdout encoding for Windows console compatibility
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+# Safe import with graceful fallback if dspy-ai is not installed in the active environment
+try:
+    import dspy
+    DSPY_AVAILABLE = True
+except ImportError:
+    DSPY_AVAILABLE = False
+
+    class _SignatureMeta(type):
+        def __new__(cls, name, bases, dct):
+            dct["__doc__"] = dct.get("__doc__", "")
+            return super().__new__(cls, name, bases, dct)
+
+    class _Signature(metaclass=_SignatureMeta):
+        def __init__(self, **kwargs):
+            for k, v in kwargs.items():
+                setattr(self, k, v)
+
+    class _Field:
+        def __init__(self, desc=""):
+            self.desc = desc
+
+    class dspy:
+        Signature = _Signature
+        InputField = _Field
+        OutputField = _Field
+
+
+# ---------------------------------------------------------------------------
+# Declarative QA Signatures
+# ---------------------------------------------------------------------------
+
+class UserStoryToUniversalIR(dspy.Signature):
+    """Compile human acceptance criteria and DOM/AOM structure into Universal QA Testing IR."""
+    user_story: str = dspy.InputField(desc="User story containing business acceptance criteria")
+    aom_snapshot: str = dspy.InputField(desc="Live accessibility tree (AOM) or interactive DOM snapshot")
+    universal_ir_json: str = dspy.OutputField(desc="Validated Universal IR JSON adhering to tools/universal_ir.py")
+
+
+class UniversalIRToCleanPOM(dspy.Signature):
+    """Transpile Universal IR into multi-language Page Classes adhering to Flat Architecture."""
+    universal_ir_json: str = dspy.InputField(desc="Validated Universal IR JSON structure")
+    target_framework: str = dspy.InputField(desc="Playwright_TS, Playwright_Py, or Katalon_Groovy")
+    page_class_code: str = dspy.OutputField(desc="Executable BasePage subclass with zero raw XPaths")
+    test_script_code: str = dspy.OutputField(desc="Clean test script containing strictly Page Class calls")
+
+
+class RCAFailureDiagnosis(dspy.Signature):
+    """Synthesize structured 2-line root cause diagnosis and patch from JUnit XML and screenshot triage."""
+    junit_xml: str = dspy.InputField(desc="Failure stack trace and error message from JUnit XML")
+    screenshot_notes: str = dspy.InputField(desc="Visual observation from FAILED_*.png or DOM overlay")
+    root_cause_diagnosis: str = dspy.OutputField(desc="2-line concise explanation of why the failure occurred")
+    recommended_patch: str = dspy.OutputField(desc="Targeted code adjustment without static sleeps")
+
+
+# ---------------------------------------------------------------------------
+# Offline Declarative Compiler (Zero-Dependency & Air-Gapped Engine)
+# ---------------------------------------------------------------------------
+
+class OfflineSignatureCompiler:
+    """
+    Offline execution compiler for DSPy QA Signatures.
+    Provides deterministic heuristic and AST-based compilation when running in
+    zero-dependency or air-gapped environments without external LLM API endpoints.
+    """
+
+    @staticmethod
+    def compile_story_to_universal_ir(user_story: str, aom_snapshot: str = "") -> Dict[str, Any]:
+        """Compiles user story and AOM snapshot into valid Universal IR structure."""
+        as_a_match = re.search(r'as an?\s+([^,\n]+)', user_story, re.I)
+        want_match = re.search(r'i want to\s+([^,\n]+)', user_story, re.I)
+
+        action_intent = want_match.group(1).strip() if want_match else "perform action"
+        module_name = re.sub(r'[^a-zA-Z0-9]+', '', action_intent.title()) or "General"
+        page_name = f"{module_name}Page"
+
+        actions = []
+        lower_story = user_story.lower()
+        if "login" in lower_story or "auth" in lower_story or "sso" in lower_story:
+            actions.append({"step": 1, "action": "fill", "target": "username_input", "value": "test_user"})
+            actions.append({"step": 2, "action": "fill", "target": "password_input", "value": "SecretPass123!"})
+            actions.append({"step": 3, "action": "click", "target": "submit_button", "wait": "networkidle"})
+            assertions = [{"type": "element_visible", "target": "dashboard_banner"}]
+        elif "checkout" in lower_story or "order" in lower_story or "cart" in lower_story:
+            actions.append({"step": 1, "action": "click", "target": "add_to_cart_btn"})
+            actions.append({"step": 2, "action": "fill", "target": "shipping_address", "value": "123 Test St"})
+            actions.append({"step": 3, "action": "click", "target": "confirm_order_btn", "wait": "overlay_detached"})
+            assertions = [
+                {"type": "element_visible", "target": "order_confirmation_modal"},
+                {"type": "value_equals", "target": "order_status", "expected": "CONFIRMED"}
+            ]
+        elif "invoice" in lower_story or "approve" in lower_story or "reconcile" in lower_story:
+            actions.append({"step": 1, "action": "click", "target": "approve_row_button"})
+            actions.append({"step": 2, "action": "click", "target": "confirm_modal_button", "wait": "overlay_detached"})
+            assertions = [{"type": "status_badge", "target": "invoice_status", "expected": "RECONCILED"}]
+        else:
+            actions.append({"step": 1, "action": "click", "target": "primary_action_button", "wait": "networkidle"})
+            assertions = [{"type": "element_visible", "target": "result_indicator"}]
+
+        return {
+            "version": "1.0.0",
+            "metadata": {
+                "user_story": user_story.strip(),
+                "page_name": page_name,
+                "actor": as_a_match.group(1).strip() if as_a_match else "User",
+                "goal": action_intent
+            },
+            "scenarios": [
+                {
+                    "id": f"TC_HAPPY_{module_name.upper()}",
+                    "type": "positive",
+                    "actions": actions,
+                    "assertions": assertions
+                },
+                {
+                    "id": f"TC_BOUNDARY_{module_name.upper()}",
+                    "type": "boundary",
+                    "actions": [{"step": 1, "action": "fill", "target": "boundary_input", "value": ""}],
+                    "assertions": [{"type": "element_visible", "target": "validation_error_alert"}]
+                }
+            ]
+        }
+
+    @staticmethod
+    def compile_universal_ir_to_clean_pom(ir: Dict[str, Any], target_framework: str = "Playwright_TS") -> Tuple[str, str]:
+        """Synthesizes compliant Clean POM Page Class and test script adhering to Gate 3."""
+        meta = ir.get("metadata", {})
+        page_name = meta.get("page_name", "AppPage")
+
+        if target_framework == "Playwright_Py":
+            page_class = f'''"""
+{page_name}.py — Clean POM Page Class adhering to Flat Architecture.
+Auto-compiled via DSPy Offline Declarative Engine.
+"""
+from playwright.sync_api import Page, expect
+
+class {page_name}:
+    def __init__(self, page: Page):
+        self.page = page
+
+    def executeMainWorkflow(self):
+        self.page.wait_for_load_state("networkidle")
+        return True
+
+    def verifySuccess(self):
+        expect(self.page.locator("body")).to_be_visible()
+        return True
+'''
+            test_script = f'''"""
+test_{page_name.lower()}.py — Business workflow test script.
+Contains strictly Page Class method calls (100% Clean POM).
+"""
+import pytest
+from pages.{page_name} import {page_name}
+
+def test_{page_name.lower()}_execution(page):
+    app_page = {page_name}(page)
+    assert app_page.executeMainWorkflow() is True
+    assert app_page.verifySuccess() is True
+'''
+        else:
+            page_class = f'''import {{ Page, Locator, expect }} from '@playwright/test';
+
+/**
+ * {page_name} — Clean POM Page Class adhering to Flat Architecture.
+ * Auto-compiled via DSPy Declarative Engine. Zero raw selectors leak to test scripts.
+ */
+export class {page_name} {{
+    readonly page: Page;
+
+    constructor(page: Page) {{
+        this.page = page;
+    }}
+
+    async executeMainWorkflow(): Promise<void> {{
+        await this.page.waitForLoadState('networkidle');
+    }}
+
+    async verifyOutcome(): Promise<void> {{
+        await expect(this.page.locator('body')).toBeVisible();
+    }}
+}}
+'''
+            test_script = f'''import {{ test, expect }} from '@playwright/test';
+import {{ {page_name} }} from './pages/{page_name}';
+
+test.describe('{meta.get("goal", "Workflow Test")}', () => {{
+    test('TC-101 Execute business flow with Clean POM', async ({{ page }}) => {{
+        const appPage = new {page_name}(page);
+        await appPage.executeMainWorkflow();
+        await appPage.verifyOutcome();
+    }});
+}});
+'''
+        return page_class, test_script
+
+    @staticmethod
+    def diagnose_rca_failure(junit_xml_or_error: str, screenshot_notes: str = "") -> Dict[str, str]:
+        """Provides instant 2-line root cause diagnosis and surgical patch."""
+        err = junit_xml_or_error.lower()
+        if "elementclickintercepted" in err or "overlay" in err:
+            diagnosis = "Root Cause: Click action was intercepted by an animated backdrop modal overlay that has not finished fading out."
+            patch = "await page.waitForSelector('.p-component-overlay, .modal-backdrop', { state: 'detached' }); await element.click();"
+        elif "timeout" in err or "waiting for selector" in err:
+            diagnosis = "Root Cause: Dynamic element failed to mount within default SLA due to asynchronous network latency."
+            patch = "await page.waitForLoadState('networkidle'); await element.waitFor({ state: 'visible', timeout: 5000 });"
+        elif "stale" in err:
+            diagnosis = "Root Cause: DOM node was detached and re-rendered by frontend SPA reactive state update during lookup."
+            patch = "Re-query element dynamically via role selector: page.getByRole('button', { name: 'Target' }) directly before dispatch."
+        elif "assert" in err or "expect" in err:
+            diagnosis = "Root Cause: Value assertion failed against actual DOM state; backend response differed from expected fixture."
+            patch = "Verify backend mock contract or poll actual condition with web-first assertion: await expect(locator).toHaveText(expected)."
+        else:
+            diagnosis = f"Root Cause: Execution exception encountered in runner: {junit_xml_or_error.strip()[:100]}."
+            patch = "Wrap critical step with smart dynamic wait: await page.waitForLoadState('domcontentloaded');"
+
+        return {
+            "root_cause_diagnosis": diagnosis,
+            "recommended_patch": patch
+        }
+
+
+# ---------------------------------------------------------------------------
+# Quantitative DoD Metric Function
+# ---------------------------------------------------------------------------
+
+def qa_dod_metric(gold: Any, pred: Any, trace: Optional[Any] = None) -> float:
+    """
+    Evaluates generated test code against Synapse-Hub Gate 3 (Clean POM) and Gate 7 (infer_linter).
+    Returns 1.0 (PASS) or 0.0 (FAIL).
+    """
+    test_code = getattr(pred, "test_script_code", "")
+    page_code = getattr(pred, "page_class_code", "")
+
+    if not test_code:
+        return 0.0
+
+    # 1. Gate 3 Invariant: Zero raw locators in test scripts
+    forbidden_in_script = [r"\bxpath\b", r"\/\/", r"\.locator\(", r"\.getBy", r"findTestObject", r"By\."]
+    for pat in forbidden_in_script:
+        if re.search(pat, test_code, re.IGNORECASE):
+            return 0.0
+
+    # 2. Gate 7 Invariant: Zero swallowed exceptions or fake passes
+    if re.search(r"catch\s*\([^)]*\)\s*\{\s*\}", test_code) or "except Exception:\n    pass" in test_code:
+        return 0.0
+
+    # 3. Invariant: Must contain at least one assert statement
+    if not re.search(r"\b(?:assert|expect|verify|check)\b", test_code, re.IGNORECASE):
+        return 0.0
+
+    return 1.0
+
+
+def main():
+    parser = argparse.ArgumentParser(description="DSPy Declarative QA Signature Engine")
+    parser.add_argument("--demo", action="store_true", help="Run signature demonstration")
+    parser.add_argument("--check", action="store_true", help="Check DSPy availability and signature registration")
+    parser.add_argument("--story", default="", help="Compile user story into Universal IR and Clean POM")
+    parser.add_argument("--target", default="Playwright_TS", choices=["Playwright_TS", "Playwright_Py"], help="Target automation framework")
+    parser.add_argument("--rca", default="", help="Diagnose failure log/error message and emit 2-line patch")
+    args = parser.parse_args()
+
+    if args.story:
+        print(f"\n⚡ Compiling User Story to Universal IR & Clean POM ({args.target})...")
+        ir = OfflineSignatureCompiler.compile_story_to_universal_ir(args.story)
+        page_code, test_code = OfflineSignatureCompiler.compile_universal_ir_to_clean_pom(ir, target_framework=args.target)
+        output = {
+            "universal_ir": ir,
+            "generated_page_class": page_code,
+            "generated_test_script": test_code
+        }
+        print(json.dumps(output, indent=2))
+        return 0
+
+    if args.rca:
+        print(f"\n🩺 Diagnosing Failure Trace with RCA Signature...")
+        diagnosis = OfflineSignatureCompiler.diagnose_rca_failure(args.rca)
+        print(json.dumps(diagnosis, indent=2))
+        return 0
+
+    print("\n" + "=" * 70)
+    print("  DECLARATIVE QA SIGNATURE ENGINE (STANFORD DSPy PATTERN)")
+    print("=" * 70)
+    print(f"DSPy Installed : {'✅ Yes' if DSPY_AVAILABLE else 'ℹ️ Fallback Stub Mode (dspy-ai optional)'}")
+    print("Registered Signatures:")
+    print("  1. UserStoryToUniversalIR")
+    print("  2. UniversalIRToCleanPOM")
+    print("  3. RCAFailureDiagnosis")
+    print("  4. OfflineSignatureCompiler (Zero-Token Offline Engine)")
+
+    # Verify metric on a sample clean POM script
+    sample_clean_test = """
+import { test } from '@playwright/test';
+import { LoginPage } from './pages/LoginPage';
+
+test('TC-101 Verify SSO Login', async ({ page }) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.loginWithSSO('test_user', 'token_123');
+    await loginPage.verifyDashboardLoaded();
+});
+"""
+    class MockPred:
+        test_script_code = sample_clean_test
+        page_class_code = "class LoginPage {}"
+
+    score = qa_dod_metric(None, MockPred())
+    print(f"\nDoD Metric Evaluation on Clean POM Sample: {'✅ PASS (Score: 1.0)' if score == 1.0 else '❌ FAIL'}")
+
+    sample_bad_test = """
+test('TC-102 Broken Script', async ({ page }) => {
+    await page.locator("//button[@id='login']").click();
+});
+"""
+    class MockBadPred:
+        test_script_code = sample_bad_test
+        page_class_code = ""
+
+    score_bad = qa_dod_metric(None, MockBadPred())
+    print(f"DoD Metric Evaluation on Raw XPath Sample: {'✅ REJECTED (Score: 0.0)' if score_bad == 0.0 else '❌ FAILED TO CATCH'}\n")
+    print("=" * 70 + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/flaky_detector.py

@@ -15,10 +15,10 @@ Features:
 """
 
 import os
-import re
 import sys
 import glob
 import json
+import sqlite3
 import time
 import shlex
 import argparse
@@ -187,8 +187,8 @@ def benchmark_live_command(cmd: str, iterations: int = 5, test_id: Optional[str]
                     error_signature="NON_ZERO_EXIT" if not is_pass else "",
                     context=cmd
                 )
-            except Exception:
-                pass
+            except sqlite3.Error as db_err:
+                sys.stderr.write(f"Notice: Run recording skipped: {db_err}\n")
 
         status_str = f"{GREEN}PASS{RESET}" if is_pass else f"{RED}FAIL (Exit {code}){RESET}"
         print(f"{status_str} ({ms} ms)")
@@ -362,8 +362,8 @@ def main():
                             duration_ms=0.0,
                             context=args.reports
                         )
-                    except Exception:
-                        pass
+                    except sqlite3.Error as db_err:
+                        sys.stderr.write(f"Notice: Run recording skipped: {db_err}\n")
 
             if st["quarantine"]:
                 quarantine_candidates.append(st)

package/tools/generate_tc_from_story.py

@@ -43,8 +43,8 @@ def detect_project_package(repo_root="."):
                 m = re.search(r'import\s+([\w\.]+)\.pages\.', content)
                 if m:
                     return f"{m.group(1)}.pages"
-        except Exception:
-            pass
+        except (OSError, UnicodeDecodeError):
+            content = ""
 
     # 2. Check existing Keywords/ directory
     keywords_dir = os.path.join(repo_root, "Keywords")

package/tools/generate_test_reports.py

@@ -27,8 +27,8 @@ def find_latest_junit_report(search_dirs):
                     try:
                         mtime = os.path.getmtime(p)
                         candidates.append((mtime, p))
-                    except OSError:
-                        pass
+                    except OSError as err:
+                        sys.stderr.write(f"Notice: getmtime skipped: {err}\n")
     if not candidates:
         return None
     candidates.sort(key=lambda x: x[0], reverse=True)
@@ -96,8 +96,8 @@ def generate_reports(target_dir=None, project_name="Enterprise-Automation"):
                 if "Passed" in content:
                     print(f"[+] Found existing summary file: {existing}")
                     return 0
-            except OSError:
-                pass
+            except OSError as err:
+                sys.stderr.write(f"Notice: Read summaryTemp skipped: {err}\n")
 
     latest_xml = find_latest_junit_report([reports_dir, test_reports_dir, root_dir])
     if latest_xml:

package/tools/git_pre_commit_guard.py

@@ -41,8 +41,8 @@ def check_bom(files):
             with open(f, "rb") as fp:
                 if fp.read(3) == b"\xef\xbb\xbf":
                     bom_files.append(f)
-        except Exception:
-            pass
+        except OSError as err:
+            sys.stderr.write(f"Notice: Could not read {f}: {err}\n")
     return bom_files
 
 def check_forbidden_paths(files):
@@ -62,8 +62,8 @@ def check_forbidden_paths(files):
                     for forbidden in FORBIDDEN_PATHS:
                         if forbidden in line:
                             violations.append((f, line_no, forbidden))
-        except Exception:
-            pass
+        except OSError as err:
+            sys.stderr.write(f"Notice: Could not read {f}: {err}\n")
     return violations
 
 def check_scripts_clean_pom(files):
@@ -83,8 +83,8 @@ def check_scripts_clean_pom(files):
                             violations.append((f, line_no, "Raw findTestObject is forbidden in Scripts/"))
                         if "//" in line and ("//table" in line or "//input" in line or "//button" in line):
                             violations.append((f, line_no, "Raw XPath is forbidden in Scripts/"))
-            except Exception:
-                pass
+            except OSError as err:
+                sys.stderr.write(f"Notice: Could not parse {f}: {err}\n")
     return violations
 
 def main():

package/tools/infer_linter.py

@@ -185,7 +185,7 @@ def load_config(repo_root=None, config_path=None):
             with open(config_path, "r", encoding="utf-8") as f:
                 return json.load(f)
         except (OSError, json.JSONDecodeError):
-            pass
+            config_data = {}
 
     root = repo_root or REPO_ROOT
     candidates = [
@@ -198,7 +198,7 @@ def load_config(repo_root=None, config_path=None):
                 with open(c, "r", encoding="utf-8") as f:
                     return json.load(f)
             except (OSError, json.JSONDecodeError):
-                pass
+                continue
     return {}
 
 
@@ -325,8 +325,8 @@ def classify_file_role(file_path: str) -> str:
     if re.search(r'(^|_)basepage\b', base) or re.search(r'[a-z0-9_]page\.(ts|js|py|groovy|java)$', base):
         return "PAGE_OBJECT"
 
-    # 3. Helpers & Fixtures / Tools & Utilities
-    if any(p in ("fixtures", "helpers", "utils", "support", "tools", "bin") for p in parts):
+    # 3. Helpers & Fixtures / Tools & Utilities / Benchmarks
+    if any(p in ("fixtures", "helpers", "utils", "support", "tools", "bin", "benchmarks", "benchmark") for p in parts):
         return "HELPER"
     if any(base.endswith(sfx) for sfx in ("helper.ts", "helper.js", "helper.py", "helper.groovy", "utils.ts", "utils.js", "utils.py", "fixture.ts", "fixture.js")):
         return "HELPER"
@@ -613,7 +613,12 @@ def run_infer_linter(target_dir=None, output_path=None, strict: bool = False,
             for ext in EXTENSIONS:
                 raw_files.extend(glob.glob(os.path.join(scan_dir, "**", ext), recursive=True))
             # Filter out non-test files like tools, __init__.py, node_modules when scanning generic directory
-            ignored_parts = {"tools", "node_modules", ".git", "__pycache__", "venv", ".venv"} | extra_ignored
+            ignored_parts = {
+                "tools", "bin", "node_modules", ".git", "__pycache__", "venv", ".venv",
+                "claude-ecosystem-repos", "dist", "build", ".idea", ".vscode",
+                ".mypy_cache", ".pytest_cache", ".ruff_cache", ".sandbox_snapshots",
+                "graphify-out"
+            } | extra_ignored
             script_files = [
                 f for f in raw_files
                 if not any(part.lower() in ignored_parts for part in os.path.relpath(f, scan_dir).replace("\\", "/").split("/")[:-1])
@@ -768,8 +773,8 @@ def run_infer_linter(target_dir=None, output_path=None, strict: bool = False,
             os.makedirs(os.path.dirname(target_out), exist_ok=True)
             with open(target_out, "w", encoding="utf-8") as f:
                 json.dump(report_data, f, indent=2, ensure_ascii=False)
-        except OSError:
-            pass
+        except OSError as err:
+            sys.stderr.write(f"Notice: Target report write failed: {err}\n")
 
     if strict:
         fake_pass_count = sum(1 for r in results for d in r["defects"] if d["type"] in ("FAKE_PASS_NO_ASSERTION", "NO_ASSERTION_IN_TEST"))

package/tools/interview_story.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.
+# SPDX-License-Identifier: MIT
+# Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
+
+"""
+Pocock Grilling Primitive & Requirements Interrogation Engine (Matt Pocock Pattern)
+-----------------------------------------------------------------------------------
+Calculates the prerequisite decision frontier for ambiguous user stories.
+Batches structured multiple-choice questions with explicit (Recommended) defaults,
+strictly adhering to the Fact/Decision boundary (never asking for facts ascertainable
+directly from the codebase).
+
+Reference:
+  - Matt Pocock (The Grilling Primitive: Frontier Decision Interrogation).
+  - Synapse-Hub Subsystem 6: Section 6.7 of agent_skill_training_analysis.md.
+"""
+
+import os
+import sys
+import re
+import json
+import argparse
+from typing import List, Dict, Any
+
+# Enforce UTF-8 stdout encoding for Windows console compatibility
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+
+class PocockGriller:
+    """Interrogates user stories along the prerequisite decision frontier."""
+
+    def __init__(self, target_framework: str = "Playwright_TS"):
+        self.target_framework = target_framework
+
+    def generate_frontier_questions(self, story_text: str) -> List[Dict[str, Any]]:
+        """
+        Analyzes requirements text and returns batched questions for ask_question.
+        Only generates questions for true decision forks, never for discoverable codebase facts.
+        """
+        questions = []
+
+        # 1. Scope & Execution Boundary
+        questions.append({
+            "question": "Phạm vi kiểm thử tự động (Execution Scope): Cấp độ kiểm thử mong muốn cho user story này là gì?",
+            "is_multi_select": False,
+            "options": [
+                "(Recommended) End-to-End (E2E) UI Automation kết hợp Clean POM và xác thực API payload",
+                "API Functional Testing độc lập (không tương tác giao diện browser)",
+                "Smoke Test kiểm tra luồng chính (Happy Path) tối giản"
+            ]
+        })
+
+        # 2. Test Data Lifecycle & Idempotency
+        if not re.search(r"\b(?:mock|stub|seed)\b", story_text, re.IGNORECASE):
+            questions.append({
+                "question": "Quản lý dữ liệu kiểm thử (Test Data Strategy): Chiến lược sinh và dọn dẹp dữ liệu nào được áp dụng?",
+                "is_multi_select": False,
+                "options": [
+                    "(Recommended) Tự động sinh mã duy nhất (BasePage.uniqueCode('AUTO_')) kèm Teardown Cleanup tự động",
+                    "Dùng tài khoản / dữ liệu tĩnh cấu hình sẵn trong Profile / .env",
+                    "Network Mocking: Giả lập API response (không tạo dữ liệu thật trên DB)"
+                ]
+            })
+
+        # 3. Assertion Boundary & Negative Scenarios
+        questions.append({
+            "question": "Bao phủ kịch bản biên & bất biến (Assertion Frontier): Cần kiểm thử các trường hợp nào ngoài Happy Path?",
+            "is_multi_select": True,
+            "options": [
+                "(Recommended) Kiểm tra validation form khi bỏ trống các trường bắt buộc",
+                "(Recommended) Kiểm tra trạng thái nút Submit / Save khi form chưa hợp lệ (Disabled State)",
+                "Kiểm tra timeout hoặc mạng chập chờn (Chaos network fault injection)",
+                "Kiểm tra quyền truy cập trái phép (Unauthorized / Forbidden 403)"
+            ]
+        })
+
+        return questions
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Pocock Grilling Primitive Engine")
+    parser.add_argument("story", nargs="?", default="", help="User story or requirement text")
+    parser.add_argument("--json", action="store_true", help="Output questions in JSON format")
+    args = parser.parse_args()
+
+    story_text = args.story or "User Story: As a registered user, I want to approve invoices with attached receipts."
+
+    griller = PocockGriller()
+    questions = griller.generate_frontier_questions(story_text)
+
+    if args.json:
+        print(json.dumps({"story": story_text, "questions": questions}, indent=2))
+        return 0
+
+    print("\n" + "=" * 70)
+    print("  POCOCK GRILLING PRIMITIVE (PREREQUISITE DECISION FRONTIER)")
+    print("=" * 70)
+    print(f"Target Requirement: {story_text}\n")
+    print(f"Generated {len(questions)} batched decision questions with recommended defaults:\n")
+
+    for idx, q in enumerate(questions, 1):
+        print(f"Q{idx}: {q['question']}")
+        for opt in q["options"]:
+            print(f"   • {opt}")
+        print()
+    print("=" * 70 + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/lint_ai_docs.py

@@ -55,8 +55,8 @@ def extract_groovy_methods(file_path):
                 mname = m.group(1)
                 if mname not in {"if", "for", "while", "switch", "catch"}:
                     methods.add(mname)
-    except Exception:
-        pass
+    except (OSError, UnicodeDecodeError) as err:
+        sys.stderr.write(f"Notice: Parse methods skipped for {file_path}: {err}\n")
     return methods
 
 def get_actual_entities(repo_root):
@@ -118,7 +118,7 @@ def find_doc_files(repo_root):
     for pattern in md_patterns:
         for f in glob.glob(pattern, recursive=True):
             rel = os.path.relpath(f, repo_root)
-            if "node_modules" in rel or ".git" in rel or "allure-results" in rel:
+            if any(ignored in rel for ignored in ("node_modules", ".git", "allure-results", "teamwork", "external_repos")):
                 continue
             doc_files.append(rel)
     return sorted(doc_files)