@bugzy-ai/bugzy 1.13.0 → 1.14.0

package/dist/index.cjs

@@ -90,31 +90,6 @@ var MCP_SERVERS = {
       }
     }
   },
-  playwright: {
-    provider: "playwright",
-    name: "Playwright",
-    description: "Playwright MCP server for browser automation",
-    requiresCredentials: false,
-    npmPackages: ["@playwright/mcp"],
-    config: {
-      command: "playwright-mcp",
-      args: [
-        "--browser",
-        "chromium",
-        "--secrets",
-        ".env",
-        "--no-sandbox",
-        "--viewport-size",
-        "1280x720"
-      ]
-    },
-    containerExtensions: {
-      args: ["--headless"],
-      env: {
-        PLAYWRIGHT_BROWSERS_PATH: "/opt/ms-playwright"
-      }
-    }
-  },
   notion: {
     provider: "notion",
     name: "Notion",
@@ -473,6 +448,9 @@ Before invoking the agent, identify the test cases for the current area:
 - Existing automated tests: ./tests/specs/
 - Existing Page Objects: ./tests/pages/
 
+**Knowledge Base Patterns (MUST APPLY):**
+Include ALL relevant testing patterns from the knowledge base that apply to this area. For example, if the KB documents timing behaviors (animation delays, loading states), selector gotchas, or recommended assertion approaches \u2014 list them here explicitly and instruct the agent to use the specific patterns described (e.g., specific assertion methods with specific timeouts). The test-code-generator does not have access to the knowledge base, so you MUST relay the exact patterns and recommended code approaches.
+
 **The agent should:**
 1. Read the manual test case files for this area
 2. Check existing Page Object infrastructure for this area
@@ -481,6 +459,7 @@ Before invoking the agent, identify the test cases for the current area:
 5. For each test case marked \`automated: true\`:
    - Create automated Playwright test in ./tests/specs/
    - Update the manual test case file to reference the automated test path
+   - Apply ALL knowledge base patterns listed above (timing, selectors, assertions)
 6. Run and iterate on each test until it passes or fails with a product bug
 7. Update .env.testdata with any new variables
 
@@ -1661,6 +1640,40 @@ The input format determines the trigger source and context extraction strategy.`
 Store the detected trigger for use in output routing:
 - Set variable: \`TRIGGER_SOURCE\` = [GITHUB_PR | SLACK_MESSAGE | CI_CD | MANUAL]
 - This determines output formatting and delivery channel`
+    },
+    // Step 5c: Coverage Gap vs. Ambiguity (inline)
+    {
+      inline: true,
+      title: "Coverage Gap vs. Ambiguity",
+      content: `### Coverage Gap vs. Ambiguity
+
+When the trigger indicates a feature has been implemented and is ready for testing (Jira "Ready to Test", PR merged, CI/CD pipeline):
+
+**Missing test coverage for the referenced feature is a COVERAGE GAP, not an ambiguity.**
+
+- The developer/team is asserting the feature exists and is ready for testing
+- "Not yet explored" or "out of scope" in the test plan means the QA team hasn't tested it yet \u2014 it does NOT mean the feature doesn't exist
+- Do NOT classify as CRITICAL based on stale documentation or knowledge base gaps
+- If project-context.md or the Jira issue references the feature, assume it exists until browser exploration proves otherwise
+- Coverage gaps are handled in the "Create Tests for Coverage Gaps" step below \u2014 do NOT block here
+
+### If You Browse the App and Cannot Find the Referenced Feature
+
+Apply the Clarification Protocol's **"Execution Obstacle vs. Requirement Ambiguity"** principle:
+
+This is an **execution obstacle**, NOT a requirement ambiguity \u2014 because the authoritative trigger source (Jira issue, PR, team request) asserts the feature exists. Common causes for not finding it:
+- **Missing role/tier**: You're logged in as a basic user but the feature requires admin/premium access
+- **Missing test data**: Required test accounts or data haven't been configured in \`.env.testdata\`
+- **Feature flags**: The feature is behind a flag not enabled in the test environment
+- **Environment config**: The feature requires specific environment variables or deployment settings
+
+**Action: PROCEED to "Create Tests for Coverage Gaps".** Do NOT BLOCK.
+- Create test cases and specs that reference the feature as described in the trigger
+- Add placeholder env vars to \`.env.testdata\` for any missing credentials
+- Notify the team (via team-communicator) about the access obstacle and what needs to be configured
+- Tests may fail until the obstacle is resolved \u2014 this is expected and acceptable
+
+**Only classify as CRITICAL (and BLOCK) if NO authoritative trigger source claims the feature exists** \u2014 e.g., a vague manual request with no Jira/PR backing.`
     },
     // Step 6: Clarification Protocol (library)
     "clarification-protocol",
@@ -2338,7 +2351,7 @@ var CONTENT = `You are an expert automated test execution specialist with deep e
 
 3. **Environment Setup**: Before test execution:
    - Read \`.env.testdata\` to get non-secret environment variable values (TEST_BASE_URL, TEST_OWNER_EMAIL, etc.)
-   - For secrets, variable names will be passed to Playwright MCP which reads them from .env at runtime
+   - For secrets, variable names are available as environment variables (playwright-cli inherits the process environment)
 
 4. **Test Case Parsing**: You will receive a test case file path. Parse the test case to extract:
    - Test steps and actions to perform
@@ -2346,16 +2359,16 @@ var CONTENT = `You are an expert automated test execution specialist with deep e
    - Test data and input values (replace any \${TEST_*} or $TEST_* variables with actual values from .env)
    - Preconditions and setup requirements
 
-5. **Browser Automation Execution**: Using the Playwright MCP server:
-   - Launch a browser instance with appropriate configuration
-   - Execute each test step sequentially
+5. **Browser Automation Execution**: Using playwright-cli (CLI-based browser automation):
+   - Launch a browser: \`playwright-cli open <url>\`
+   - Execute each test step sequentially using CLI commands: \`click\`, \`fill\`, \`select\`, \`hover\`, etc.
+   - Use \`snapshot\` to inspect page state and find element references (@e1, @e2, etc.)
    - Handle dynamic waits and element interactions intelligently
    - Manage browser state between steps
    - **IMPORTANT - Environment Variable Handling**:
      - When test cases contain environment variables:
        - For non-secrets (TEST_BASE_URL, TEST_OWNER_EMAIL): Read actual values from .env.testdata and use them directly
-       - For secrets (TEST_OWNER_PASSWORD, API keys): Pass variable name to Playwright MCP for runtime substitution
-       - Playwright MCP automatically reads .env for secrets and injects them at runtime
+       - For secrets (TEST_OWNER_PASSWORD, API keys): playwright-cli inherits environment variables from the process
        - Example: Test says "Navigate to TEST_BASE_URL/login" \u2192 Read TEST_BASE_URL from .env.testdata, use the actual URL
 
 6. **Evidence Collection at Each Step**:
@@ -2380,7 +2393,7 @@ var CONTENT = `You are an expert automated test execution specialist with deep e
    - \`steps.json\`: Structured steps with timestamps, video time synchronization, and detailed descriptions (see schema)
 
    Video handling:
-   - Playwright automatically saves videos to \`.playwright-mcp/\` folder
+   - Videos are automatically saved to \`.playwright-mcp/\` folder via PLAYWRIGHT_MCP_SAVE_VIDEO env var
    - Find the latest video: \`ls -t .playwright-mcp/*.webm 2>/dev/null | head -1\`
    - Store ONLY the filename in summary.json: \`{ "video": { "filename": "basename.webm" } }\`
    - Do NOT copy, move, or delete video files - external service handles uploads
@@ -2419,8 +2432,7 @@ var CONTENT = `You are an expert automated test execution specialist with deep e
    - Identify all TEST_* variable references (e.g., TEST_BASE_URL, TEST_OWNER_EMAIL, TEST_OWNER_PASSWORD)
    - Read .env.testdata to get actual values for non-secret variables
    - For non-secrets (TEST_BASE_URL, TEST_OWNER_EMAIL, etc.): Use actual values from .env.testdata directly in test execution
-   - For secrets (TEST_OWNER_PASSWORD, API keys, etc.): Pass variable names to Playwright MCP for runtime injection from .env
-   - Playwright MCP will read .env and inject secret values during browser automation
+   - For secrets (TEST_OWNER_PASSWORD, API keys, etc.): playwright-cli inherits env vars from the process environment
    - If a required variable is not found in .env.testdata, log a warning but continue
 
 5. Extract execution ID from the execution environment:
@@ -2434,7 +2446,7 @@ var CONTENT = `You are an expert automated test execution specialist with deep e
    - Describe what action will be performed (communicate to user)
    - Log the step being executed with timestamp
    - Calculate elapsed time from test start (for videoTimeSeconds)
-   - Execute the action using Playwright's robust selectors
+   - Execute the action using playwright-cli commands (click, fill, select, etc. with element refs)
    - Wait for page stability
    - Validate expected behavior
    - Record findings and actual behavior
@@ -2509,12 +2521,11 @@ var CONTENT = `You are an expert automated test execution specialist with deep e
 **Environment Variable Handling:**
 - Read .env.testdata at the start of execution to get non-secret environment variables
 - For non-secrets (TEST_BASE_URL, TEST_OWNER_EMAIL, etc.): Use actual values from .env.testdata directly
-- For secrets (TEST_OWNER_PASSWORD, API keys): Pass variable names to Playwright MCP for runtime injection
-- Playwright MCP reads .env for secrets and injects them during browser automation
+- For secrets (TEST_OWNER_PASSWORD, API keys): playwright-cli inherits env vars from the process environment
 - DO NOT read .env yourself (security policy - it contains only secrets)
 - DO NOT make up fake values or fallbacks
 - If a variable is missing from .env.testdata, log a warning
-- If Playwright MCP reports a secret is missing/empty, that indicates .env is misconfigured
+- If a secret env var is missing/empty, that indicates .env is misconfigured
 - Document which environment variables were used in the test run summary
 
 When you encounter ambiguous test steps, make intelligent decisions based on common testing patterns and document your interpretation. Always prioritize capturing evidence over speed of execution. Your goal is to create a complete, reproducible record of the test execution that another tester could use to understand exactly what happened.`;
@@ -2561,7 +2572,7 @@ var CONTENT2 = `You are an expert Playwright test automation engineer specializi
    - Update the manual test case file with the automated_test reference
    - Create supporting artifacts: Page Objects, fixtures, helpers, components, types
 
-5. **Mandatory Application Exploration**: NEVER generate Page Objects without exploring the live application first using Playwright MCP tools:
+5. **Mandatory Application Exploration**: NEVER generate Page Objects without exploring the live application first using playwright-cli:
    - Navigate to pages, authenticate, inspect elements
    - Capture screenshots for documentation
    - Document exact role names, labels, text, URLs
@@ -2592,7 +2603,7 @@ var CONTENT2 = `You are an expert Playwright test automation engineer specializi
 
    **STEP 2: Build Missing Infrastructure** (if needed)
 
-   - **Explore feature under test**: Use Playwright MCP tools to:
+   - **Explore feature under test**: Use playwright-cli to:
      * Navigate to the feature's pages
      * Inspect elements and gather selectors (role, label, text)
      * Document actual URLs from the browser
@@ -2799,8 +2810,8 @@ var CONTENT2 = `You are an expert Playwright test automation engineer specializi
 - Create test interdependencies - tests must be independent
 
 \u2705 **ALWAYS**:
-- Explore application using Playwright MCP before generating code
-- Verify selectors in live browser using browser_select tool
+- Explore application using playwright-cli before generating code
+- Verify selectors in live browser using playwright-cli snapshot
 - Document actual URLs from browser address bar
 - Take screenshots for documentation
 - Use role-based selectors as first priority
@@ -2872,7 +2883,7 @@ var CONTENT3 = `You are an expert Playwright test debugger and fixer with deep e
    - Brittle selectors (CSS classes, IDs that change)
 
 4. **Debug Using Browser**: When needed, explore the application manually:
-   - Use Playwright MCP to open browser
+   - Use playwright-cli to open browser (\`playwright-cli open <url>\`)
    - Navigate to the relevant page
    - Inspect elements to find correct selectors
    - Manually perform test steps to understand actual behavior
@@ -2982,7 +2993,7 @@ var CONTENT3 = `You are an expert Playwright test debugger and fixer with deep e
    - Check for screenshot/trace file references
 
    **Step 3: Reproduce and Debug**
-   - Open browser via Playwright MCP if needed
+   - Open browser via playwright-cli if needed (\`playwright-cli open <url>\`)
    - Navigate to relevant page
    - Manually execute test steps
    - Identify discrepancy between test expectations and actual behavior
@@ -3105,13 +3116,14 @@ var CONTENT3 = `You are an expert Playwright test debugger and fixer with deep e
    - NEVER read \`.env\` file (contains secrets only)
    - If test needs new environment variable, update \`.env.testdata\`
 
-9. **Using Playwright MCP for Debugging**:
-   - You have direct access to Playwright MCP
-   - Open browser: Request to launch Playwright
-   - Navigate: Go to URLs relevant to failing test
-   - Inspect elements: Find correct selectors
-   - Execute test steps manually: Understand actual behavior
-   - Close browser when done
+9. **Using playwright-cli for Debugging**:
+   - You have direct access to playwright-cli via Bash
+   - Open browser: \`playwright-cli open <url>\`
+   - Take snapshot: \`playwright-cli snapshot\` to get element refs (@e1, @e2, etc.)
+   - Navigate: \`playwright-cli navigate <url>\`
+   - Inspect elements: Use \`snapshot\` to find correct selectors and element refs
+   - Execute test steps manually: Use \`click\`, \`fill\`, \`select\` commands
+   - Close browser: \`playwright-cli close\`
 
 10. **Test Stability Best Practices**:
     - Replace all \`waitForTimeout()\` with specific waits
@@ -3406,6 +3418,24 @@ var CONTENT5 = `You are a Team Communication Specialist who communicates like a
 
 **Key Principle:** If it takes more than 30 seconds to read, it's too long.
 
+## CRITICAL: Always Post Messages
+
+When you are invoked, your job is to POST a message to Slack \u2014 not just compose one.
+
+**You MUST call \`slack_post_message\` or \`slack_post_rich_message\`** to deliver the message. Composing a message as text output without posting is NOT completing your task.
+
+**NEVER:**
+- Return a draft without posting it
+- Ask "should I post this?" \u2014 if you were invoked, the answer is yes
+- Compose text and wait for approval before posting
+
+**ALWAYS:**
+1. Identify the correct channel (from project-context.md or the invocation context)
+2. Compose the message following the guidelines below
+3. Call the Slack API tool to POST the message
+4. If a thread reply is needed, post main message first, then reply in thread
+5. Report back: channel name, message timestamp, and confirmation it was posted
+
 ## Message Type Detection
 
 Before composing, identify the message type:
@@ -5844,7 +5874,7 @@ var INTEGRATIONS = {
     id: "playwright",
     name: "Playwright",
     provider: "playwright",
-    requiredMCP: "mcp__playwright__*",
+    // No requiredMCP — uses playwright-cli (CLI tool), not MCP server
     isLocal: true,
     // Playwright runs locally, no external connector needed
     integrationType: "local"
@@ -6148,6 +6178,8 @@ Before proceeding, read the curated knowledge base to inform your work:
    - Build on existing understanding
    - Maintain consistency with established practices
 
+3. **Relay to subagents**: Subagents do NOT read the knowledge base directly. When delegating work, you MUST include relevant KB patterns in your delegation message \u2014 especially testing patterns (timing, selectors, assertion approaches) that affect test reliability.
+
 **Note:** The knowledge base may not exist yet or may be empty. If it doesn't exist or is empty, proceed without this context and help build it as you work.`,
   tags: ["setup", "context"]
 };
@@ -6294,7 +6326,9 @@ If the Clarification Protocol determined project maturity, adjust exploration de
 - **Growing project**: Use requirement clarity as-is (standard protocol)
 - **Mature project**: Trust knowledge base \u2014 can stay at suggested depth or go one level shallower if KB covers the feature
 
-**Always verify features exist before testing them.** If exploration reveals that a referenced page or feature does not exist in the application, this is CRITICAL severity \u2014 escalate via the Clarification Protocol regardless of maturity level. Do NOT silently adapt or work around the missing feature.
+**Always verify features exist before testing them.** If exploration reveals that a referenced page or feature does not exist in the application, apply the Clarification Protocol's "Execution Obstacle vs. Requirement Ambiguity" principle:
+- If an authoritative trigger source (Jira issue, PR, team request) asserts the feature exists, this is likely an **execution obstacle** (missing credentials, feature flags, environment config) \u2014 proceed with test artifact creation and notify the team about the access issue. Do NOT BLOCK.
+- If NO authoritative source claims the feature exists, this is **CRITICAL severity** \u2014 escalate via the Clarification Protocol regardless of maturity level. Do NOT silently adapt or work around the missing feature.
 
 ### Quick Exploration (1-2 min)
 
@@ -6580,11 +6614,56 @@ If ambiguity is detected, assess its severity:
 
 | Severity | Characteristics | Examples | Action |
 |----------|----------------|----------|--------|
-| **CRITICAL** | Expected behavior undefined/contradictory; test outcome unpredictable; core functionality unclear; success criteria missing; multiple interpretations = different strategies; **referenced page/feature does not exist in the application** | "Fix the issue" (what issue?), "Improve performance" (which metrics?), "Fix sorting in todo list" (by date? priority? completion status?), "Test the Settings page" (no Settings page exists), "Verify the checkout flow" (no checkout page found) | **STOP** - You MUST ask via team-communicator before proceeding |
+| **CRITICAL** | Expected behavior undefined/contradictory; test outcome unpredictable; core functionality unclear; success criteria missing; multiple interpretations = different strategies; **referenced page/feature confirmed absent after browser verification AND no authoritative trigger source (Jira, PR, team request) asserts the feature exists** | "Fix the issue" (what issue?), "Improve performance" (which metrics?), "Fix sorting in todo list" (by date? priority? completion status?), "Test the Settings page" (browsed app \u2014 no Settings page exists, and no Jira/PR claims it was built) | **STOP** - You MUST ask via team-communicator before proceeding |
 | **HIGH** | Core underspecified but direction clear; affects majority of scenarios; vague success criteria; assumptions risky | "Fix ordering" (sequence OR visibility?), "Add validation" (what? messages?), "Update dashboard" (which widgets?) | **STOP** - You MUST ask via team-communicator before proceeding |
 | **MEDIUM** | Specific details missing; general requirements clear; affects subset of cases; reasonable low-risk assumptions possible; wrong assumption = test updates not strategy overhaul | Missing field labels, unclear error message text, undefined timeouts, button placement not specified, date formats unclear | **PROCEED** - (1) Moderate exploration, (2) Document assumptions: "Assuming X because Y", (3) Proceed with creation/execution, (4) Async clarification (team-communicator), (5) Mark [ASSUMED: description] |
 | **LOW** | Minor edge cases; documentation gaps don't affect execution; optional/cosmetic elements; minimal impact | Tooltip text, optional field validation, icon choice, placeholder text, tab order | **PROCEED** - (1) Mark [TO BE CLARIFIED: description], (2) Proceed, (3) Mention in report "Minor Details", (4) No blocking/async clarification |
 
+### Execution Obstacle vs. Requirement Ambiguity
+
+Before classifying something as CRITICAL, distinguish between these two fundamentally different situations:
+
+**Requirement Ambiguity** = *What* to test is unclear \u2192 severity assessment applies normally
+- No authoritative source describes the feature
+- The task description is vague or contradictory
+- You cannot determine what "correct" behavior looks like
+- \u2192 Apply severity table above. CRITICAL/HIGH \u2192 BLOCK.
+
+**Execution Obstacle** = *What* to test is clear, but *how* to access/verify has obstacles \u2192 NEVER BLOCK
+- An authoritative trigger source (Jira issue, PR, team message) asserts the feature exists
+- You browsed the app but couldn't find/access the feature
+- The obstacle is likely: wrong user role/tier, missing test data, feature flags, environment config
+- \u2192 PROCEED with artifact creation (test cases, test specs). Notify team about the obstacle.
+
+**The key test:** Does an authoritative trigger source (Jira, PR, team request) assert the feature exists?
+- **YES** \u2192 It's an execution obstacle. The feature exists but you can't access it. Proceed: create test artifacts, add placeholder env vars, notify team about access issues.
+- **NO** \u2192 It may genuinely not exist. Apply CRITICAL severity, ask what was meant.
+
+| Scenario | Trigger Says | Browser Shows | Classification | Action |
+|----------|-------------|---------------|----------------|--------|
+| Jira says "test premium dashboard", you log in as test_user and don't see it | Feature exists | Can't access | **Execution obstacle** | Create tests, notify team re: missing premium credentials |
+| PR says "verify new settings page", you browse and find no settings page | Feature exists | Can't find | **Execution obstacle** | Create tests, notify team re: possible feature flag/env issue |
+| Manual request "test the settings page", no Jira/PR, you browse and find no settings page | No source claims it | Can't find | **Requirement ambiguity (CRITICAL)** | BLOCK, ask what was meant |
+| Jira says "fix sorting", but doesn't specify sort criteria | Feature exists | Feature exists | **Requirement ambiguity (HIGH)** | BLOCK, ask which sort criteria |
+
+**Partial Feature Existence \u2014 URL found but requested functionality absent:**
+
+A common edge case: a page/route loads successfully, but the SPECIFIC FUNCTIONALITY you were asked to test doesn't exist on it.
+
+**Rule:** Evaluate whether the REQUESTED FUNCTIONALITY exists, not just whether a URL resolves.
+
+| Page Exists | Requested Features Exist | Authoritative Trigger | Classification |
+|-------------|--------------------------|----------------------|----------------|
+| Yes | Yes | Any | Proceed normally |
+| Yes | No | Yes (Jira/PR says features built) | Execution obstacle \u2014 features behind flag/env |
+| Yes | No | No (manual request only) | **Requirement ambiguity (CRITICAL)** \u2014 ask what's expected |
+| No | N/A | Yes | Execution obstacle \u2014 page not deployed yet |
+| No | N/A | No | **Requirement ambiguity (CRITICAL)** \u2014 ask what was meant |
+
+**Example:** Prompt says "Test the checkout payment form with credit card 4111..." You browse to /checkout and find an information form (first name, last name, postal code) but NO payment form, NO shipping options, NO Place Order button. No Jira/PR claims these features exist. \u2192 **CRITICAL requirement ambiguity.** Ask: "I found a checkout information form at /checkout but no payment form or shipping options. Can you clarify what checkout features you'd like tested?"
+
+**Key insight:** Finding a URL is not the same as finding the requested functionality. Do NOT classify this as an "execution obstacle" just because the page loads.
+
 ### Check Memory for Similar Clarifications
 
 Before asking, check if similar question was answered:
@@ -6730,7 +6809,7 @@ When reporting test results, always include an "Ambiguities" section if clarific
 ## Remember
 
 - **STOP means STOP** - When you hit a STOP threshold, you MUST call team-communicator to ask via Slack. Do NOT silently adapt, skip, or work around the issue
-- **Non-existent features = CRITICAL** - If a page, component, or feature referenced in the task does not exist, this is always CRITICAL severity \u2014 ask what was meant
+- **Non-existent features \u2014 check context first** - If a page/feature doesn't exist in the browser, check whether an authoritative trigger (Jira, PR, team request) asserts it exists. If YES \u2192 execution obstacle (proceed with artifact creation, notify team). If NO authoritative source claims it exists \u2192 CRITICAL severity, ask what was meant
 - **Ask correctly > guess poorly** - Specific questions lead to specific answers
 - **Never invent success criteria** - If the task says "improve" or "fix" without metrics, ask what "done" looks like
 - **Check memory first** - Avoid re-asking previously answered questions
@@ -7697,8 +7776,10 @@ function buildComposedTaskDefinition(taskSlug, projectSubAgents) {
     const configured = projectSubAgents.find((sa) => sa.role === role);
     if (configured) {
       const integrationMeta = getIntegration(configured.integration);
-      const mcpProvider = integrationMeta?.provider || configured.integration;
-      requiredMCPs.add(mcpProvider);
+      if (integrationMeta?.requiredMCP) {
+        const mcpProvider = integrationMeta.provider || configured.integration;
+        requiredMCPs.add(mcpProvider);
+      }
     }
   }
   const content = contentParts.join("\n\n");