@bugzy-ai/bugzy 1.12.4 → 1.13.1

package/dist/index.cjs

@@ -473,6 +473,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 +484,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
 
@@ -1442,7 +1446,9 @@ Extract the following from arguments:
     "read-knowledge-base",
     // Step 5: Test Execution Strategy (library)
     "read-test-strategy",
-    // Step 6: Identify Tests (inline - task-specific)
+    // Step 6: Clarification Protocol (library)
+    "clarification-protocol",
+    // Step 7: Identify Tests (inline - task-specific)
     {
       inline: true,
       title: "Identify Automated Tests to Run",
@@ -1660,7 +1666,9 @@ 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 6: Extract Context (inline)
+    // Step 6: Clarification Protocol (library)
+    "clarification-protocol",
+    // Step 7: Extract Context (inline)
     {
       inline: true,
       title: "Extract Context Based on Trigger",
@@ -6144,6 +6152,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"]
 };
@@ -6282,6 +6292,16 @@ Determine exploration depth based on requirement quality:
 - **Vague:** "Fix the sorting in todo list page. The items are mixed up for premium users."
 - **Unclear:** "Improve the dashboard performance. Users say it's slow."
 
+### Maturity Adjustment
+
+If the Clarification Protocol determined project maturity, adjust exploration depth:
+
+- **New project**: Default one level deeper than requirement clarity suggests (Clear \u2192 Moderate, Vague \u2192 Deep)
+- **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.
+
 ### Quick Exploration (1-2 min)
 
 **When:** Requirements CLEAR
@@ -6513,6 +6533,33 @@ Before starting, check if this task is resuming from a blocked clarification:
 
 3. **If no clarification in $ARGUMENTS:** Proceed normally with ambiguity detection below.
 
+### Assess Project Maturity
+
+Before detecting ambiguity, assess how well you know this project. Maturity determines how aggressively you should ask questions \u2014 new projects require more questions, mature projects can rely on accumulated knowledge.
+
+**Measure maturity from runtime artifacts:**
+
+| Signal | New | Growing | Mature |
+|--------|-----|---------|--------|
+| \`knowledge-base.md\` | < 80 lines (template) | 80-300 lines | 300+ lines |
+| \`memory/\` files | 0 files | 1-3 files | 4+ files, >5KB each |
+| Test cases in \`test-cases/\` | 0 | 1-6 | 7+ |
+| Exploration reports | 0 | 1 | 2+ |
+
+**Steps:**
+1. Read \`.bugzy/runtime/knowledge-base.md\` and count lines
+2. List \`.bugzy/runtime/memory/\` directory and count files
+3. List \`test-cases/\` directory and count \`.md\` files (exclude README)
+4. Count exploration reports in \`exploration-reports/\`
+5. Classify: If majority of signals = New \u2192 **New**; majority Mature \u2192 **Mature**; otherwise \u2192 **Growing**
+
+**Maturity adjusts your question threshold:**
+- **New**: Ask for CRITICAL + HIGH + MEDIUM severity (gather information aggressively)
+- **Growing**: Ask for CRITICAL + HIGH severity (standard protocol)
+- **Mature**: Ask for CRITICAL only (handle HIGH with documented assumptions)
+
+**CRITICAL severity ALWAYS triggers a question, regardless of maturity level.**
+
 ### Detect Ambiguity
 
 Scan for ambiguity signals:
@@ -6539,8 +6586,8 @@ 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 | "Fix the issue" (what issue?), "Improve performance" (which metrics?), "Fix sorting in todo list" (by date? priority? completion status?) | **STOP** - Seek clarification 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** - Seek clarification before proceeding |
+| **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 |
+| **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 |
 
@@ -6641,18 +6688,26 @@ Tasks waiting for clarification responses.
 
 ### Wait or Proceed Based on Severity
 
-**CRITICAL/HIGH \u2192 STOP and Wait:**
-- Do NOT create tests, run tests, or make assumptions
-- Wait for clarification, resume after answer
+**Use your maturity assessment to adjust thresholds:**
+- **New project**: STOP for CRITICAL + HIGH + MEDIUM
+- **Growing project**: STOP for CRITICAL + HIGH (default)
+- **Mature project**: STOP for CRITICAL only; handle HIGH with documented assumptions
+
+**When severity meets your STOP threshold:**
+- You MUST call team-communicator (Slack) to ask the question \u2014 do NOT just mention it in your text output
+- Do NOT create tests, run tests, or make assumptions about the unclear aspect
+- Do NOT silently adapt by working around the issue (e.g., running other tests instead)
+- Do NOT invent your own success criteria when none are provided
+- Register the blocked task and wait for clarification
 - *Rationale: Wrong assumptions = incorrect tests, false results, wasted time*
 
-**MEDIUM \u2192 Proceed with Documented Assumptions:**
+**When severity is below your STOP threshold \u2192 Proceed with Documented Assumptions:**
 - Perform moderate exploration, document assumptions, proceed with creation/execution
 - Ask clarification async (team-communicator), mark results "based on assumptions"
 - Update tests after clarification received
 - *Rationale: Waiting blocks progress; documented assumptions allow forward movement with later corrections*
 
-**LOW \u2192 Proceed and Mark:**
+**LOW \u2192 Always Proceed and Mark:**
 - Proceed with creation/execution, mark gaps [TO BE CLARIFIED] or [ASSUMED]
 - Mention in report but don't prioritize, no blocking
 - *Rationale: Details don't affect strategy/results significantly*
@@ -6680,11 +6735,12 @@ When reporting test results, always include an "Ambiguities" section if clarific
 
 ## Remember
 
-- **Block for CRITICAL/HIGH** - Never proceed with assumptions on unclear core requirements
+- **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
 - **Ask correctly > guess poorly** - Specific questions lead to specific answers
-- **Document MEDIUM assumptions** - Track what you assumed and why
+- **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
-- **Specific questions \u2192 specific answers** - Vague questions get vague answers`,
+- **Maturity adjusts threshold, not judgment** - Even in mature projects, CRITICAL always triggers a question`,
   tags: ["clarification", "protocol", "ambiguity"]
 };