@qa-gentic/agents 1.1.2

package/skills/qa-stlc/AGENT-BEHAVIOR.md

@@ -0,0 +1,373 @@
+# Agent Behavior Contract — QA STLC Agents
+
+> **This file is authoritative for all coding agents (Claude Code, GitHub Copilot, Cursor,
+> Windsurf, and any LLM operating on this repo).**
+> It defines what agents are and are not permitted to do. Every rule here overrides any
+> inference, "reasonable assumption", or pattern learned from prior context.
+>
+> Version: 1.1 — all rules are explicit; none are inferred.
+> Change log: see bottom of this file.
+
+---
+
+## 1. Scope Delimitation — What This Repo Does and Does Not Do
+
+### What the agents in this repo do
+
+| Agent | What it does | What it produces |
+|---|---|---|
+| `qa-test-case-manager` | Fetches ADO work items; creates and links manual test cases | ADO test case work items linked via `TestedBy-Forward` |
+| `qa-gherkin-generator` | Fetches ADO work item hierarchies; validates and attaches `.feature` files | `.feature` files attached to ADO work items |
+| `qa-playwright-generator` | Generates TypeScript Playwright code from Gherkin; attaches files to ADO | `locators.ts`, `*Page.ts`, `*.steps.ts` attached to ADO work items |
+| `qa-helix-writer` | Writes already-generated files to disk at Helix-QA paths | Files on disk — no ADO writes |
+
+### What the agents do NOT do
+
+- Do NOT make any product decisions (scope, priority, what to test).
+- Do NOT infer missing acceptance criteria, test data, or screen names.
+- Do NOT carry forward any decision from one artifact to the next.
+- Do NOT create local files unless the user explicitly requests a download.
+- Do NOT attach anything to ADO unless the explicit rule for that artifact type is satisfied.
+- Do NOT proceed past a gap or ambiguity — they stop and ask.
+
+---
+
+## 2. Zero-Inference Rule
+
+**An agent must never substitute inference for an explicit instruction.**
+
+This applies specifically to:
+
+| Situation | Prohibited inference | Required behaviour |
+|---|---|---|
+| User provides a work item ID but no type | Guessing whether it is Epic / Feature / PBI / Bug | Call the fetch tool; let the response `work_item_type` field determine routing |
+| User says "generate everything" | Assuming delivery destinations for each artifact type | Ask per artifact: "Attach Gherkin to ADO? Attach Playwright to ADO? Save locally?" |
+| User confirms Gherkin ADO attachment | Inferring Playwright code should also be attached | Wait for explicit confirmation before calling `attach_code_to_work_item` |
+| User declines creating test cases in ADO | Inferring they also decline Gherkin or Playwright ADO attachment | Treat each artifact delivery as a completely independent decision |
+| User says "yes" to one step | Carrying that "yes" forward to the next step | Seek fresh confirmation for each distinct action |
+| Navigation path not in work item | Inventing a path | Write placeholder `<!-- TODO: confirm screen name -->` and surface to user |
+| Test data not provided | Inventing emails, IDs, file contents | Stop and ask; never hardcode invented data |
+| Work item appears new | Skipping the deduplication protocol | Always run Phase 1 of deduplication-protocol.md before creating anything |
+
+---
+
+## 3. Explicit Artifact Delivery Rules
+
+Every artifact type has exactly one delivery rule. Completing one artifact does **not** trigger delivery of another.
+
+### 3A — Gherkin `.feature` files
+
+| Condition | Action |
+|---|---|
+| User asks to generate Gherkin | Generate the file; show content to user; **do not attach yet** |
+| `validate_gherkin_content` returns `valid: false` | Fix errors; do not attach |
+| `validate_gherkin_content` returns `valid: true` | **Ask the user**: "Attach this `.feature` file to ADO work item #{id}?" |
+| User confirms attachment | Call `attach_gherkin_to_feature` (Feature path) or `attach_gherkin_to_work_item` (PBI/Bug path) |
+| User declines | Save locally only if user explicitly requests; otherwise present content inline |
+| Work item type is Epic | **HARD STOP** — do not attach to Epic; tell user to specify a child Feature ID |
+
+### 3B — Playwright TypeScript files
+
+| Condition | Action |
+|---|---|
+| User asks to generate Playwright code | Generate files; show output summary; **do not attach yet** |
+| User has not explicitly requested ADO attachment | Do NOT call `attach_code_to_work_item` |
+| User explicitly requests ADO attachment | Call `attach_code_to_work_item` with net-new delta files only |
+| User previously declined test case creation | This has **no bearing** on Playwright attachment — ask separately |
+| User previously confirmed Gherkin attachment | This has **no bearing** on Playwright attachment — ask separately |
+| Work item type is Epic | **HARD STOP** — return `epic_not_supported`; do not attach |
+
+### 3C — Manual test cases (ADO)
+
+| Condition | Action |
+|---|---|
+| Work item type is Epic | **HARD STOP** — `fetch_work_item` returns `epic_not_supported`; inform user; do not call `create_and_link_test_cases` |
+| Work item type is Feature | Server returns `confirmation_required: true`; show user the proposed count + Feature title; wait for "yes" |
+| User says "yes" to Feature confirmation | Retry `create_and_link_test_cases` with the **identical arguments** plus `confirmed=true` — do NOT change `work_item_id` or any other parameter |
+| User says "no" or "cancel" to Feature confirmation | Abort entirely; report "No test cases were created." Do NOT retry with a different work item type. |
+| Work item type is PBI or Bug | Run deduplication protocol; create only net-new test cases |
+| `existing_test_cases_count > 0` | Always call `get_linked_test_cases` first to get real titles before generating |
+
+### 3D — Local file creation
+
+| Condition | Action |
+|---|---|
+| User says "save", "download", or "export to file" | Create local file as requested |
+| User has not requested a local file | Do NOT create one |
+| ADO attachment succeeded | Do NOT also create a local copy unless user asks |
+| ADO attachment failed | Offer the content inline; ask if user wants a local file |
+
+### 3E — Helix-QA disk writes
+
+| Condition | Action |
+|---|---|
+| User asks to write files to disk | Follow `write-helix-files.md` in full — never skip any step |
+| `write_helix_files` succeeds | Report the deduplication summary to the user |
+| `write_helix_files` fails | **See failure recovery rules below** — do NOT fall back to `create_file` |
+| A locator file already exists on disk (`list_helix_tree` returns it) | Extend that file via `write_helix_files` — **NEVER create a new file** |
+| A step file already exists on disk | Merge into that file via `write_helix_files` — **NEVER create a new file** |
+| User has not explicitly asked for local files | Do NOT call `create_file` or any filesystem tool |
+
+**Failure recovery for `write_helix_files`:**
+
+| Error type | Root cause | Recovery action |
+|---|---|---|
+| Parenthesis / bracket balance error in a `*.steps.ts` file | Step definitions use regex patterns (`/^I click ([^"]*)/`) — the regex preprocessor strips string literals before counting parens, so capture groups cause a nonzero delta | Call `pre_validate_cucumber_steps` on the steps file — it identifies every offending pattern and provides ready-to-paste Cucumber expression replacements. Fix all flagged patterns, then retry `write_helix_files`. |
+| `OSError` on a specific path | Path does not exist or permission denied | Report path to user; do not fall back to `create_file` |
+| Any other tool error | Unknown | Report the raw error to user verbatim; ask how to proceed |
+
+**The `create_file` tool is PROHIBITED for Helix-QA artifacts.** Every file in `src/` that
+belongs to the QA test suite — locators, page objects, step definitions, feature files,
+cucumber config — must be written exclusively via `qa-helix-writer:write_helix_files`.
+Using `create_file` bypasses deduplication, interface-adaptation rewrites, and file routing.
+If `write_helix_files` cannot be made to succeed, surface the blocker to the user rather
+than silently routing around it.
+
+| Condition | Action |
+|---|---|
+| Files to write | Always call `list_helix_tree` first to see what already exists |
+| File already exists at target path | Read it first; check for overlap; write only net-new content |
+| `generate_playwright_code` output available | Pass the `files` dict directly to `write_helix_files` — do not reformat |
+
+---
+
+## 4. Strict Input → Tool → Output Chains
+
+Each user request type has one and only one correct tool chain. Do not improvise.
+
+### Chain A — Manual test cases from PBI or Bug
+
+```
+INPUT:  PBI or Bug ID  +  org URL  +  project name
+  │
+  ├─ fetch_work_item(id)
+  │    └─ if epic_not_supported  →  STOP, inform user
+  │    └─ if confirmation_required  →  STOP, ask user; proceed only on "yes"
+  │
+  ├─ get_linked_test_cases(id)          ← always if count > 0
+  │
+  ├─ [deduplication-protocol Phase 2]
+  │
+  └─ create_and_link_test_cases(net-new only)
+
+OUTPUT: ADO test case IDs + deduplication report
+        NO local file, NO Gherkin, NO Playwright — unless user explicitly requests them
+```
+
+### Chain B — Gherkin from Feature
+
+```
+INPUT:  Feature ID  +  org URL  +  project name
+  │
+  ├─ fetch_feature_hierarchy(id)
+  │
+  ├─ [deduplication-protocol Phase 1+2]
+  │
+  ├─ [gap check — stop and ask if any G1–G7 gap found]
+  │
+  ├─ [live Playwright MCP snapshots of every screen]
+  │
+  ├─ validate_gherkin_content(content, scope="feature")
+  │    └─ if valid: false  →  fix; re-validate; do NOT attach
+  │
+  ├─ validate_gherkin_steps(content)
+  │
+  ├─ [show content to user]
+  │
+  ├─ [ASK: "Attach to ADO Feature #{id}?"]
+  │    └─ yes  →  attach_gherkin_to_feature(id)
+  │    └─ no   →  stop; offer local download only if user asks
+  │
+  └─ [STOP — do not proceed to Playwright unless user explicitly asks]
+
+OUTPUT: .feature file attached to Feature work item (or shown inline)
+        NO Playwright code unless user explicitly requests it
+        NO test case creation unless user explicitly requests it
+```
+
+### Chain C — Gherkin from PBI or Bug
+
+```
+INPUT:  PBI or Bug ID  +  org URL  +  project name
+  │
+  ├─ fetch_work_item_for_gherkin(id)
+  │
+  ├─ get_linked_test_cases(id)          ← context only
+  │
+  ├─ [deduplication-protocol Phase 1+2]
+  │
+  ├─ [gap check]
+  │
+  ├─ [live Playwright MCP snapshots]
+  │
+  ├─ validate_gherkin_content(content, scope="work_item")
+  │
+  ├─ [show content to user]
+  │
+  ├─ [ASK: "Attach to ADO work item #{id}?"]
+  │    └─ yes  →  attach_gherkin_to_work_item(id)
+  │    └─ no   →  stop
+  │
+  └─ [STOP — do not proceed to Playwright unless user explicitly asks]
+
+OUTPUT: .feature file attached to PBI/Bug work item (or shown inline)
+```
+
+### Chain D — Gherkin from Epic
+
+```
+INPUT:  Epic ID  +  org URL  +  project name
+  │
+  ├─ fetch_epic_hierarchy(id)
+  │    └─ returns: features[] each with child_work_items[] and existing_test_cases[]
+  │
+  ├─ [read ALL child Features and ALL child PBIs/Bugs before writing any Gherkin]
+  │
+  ├─ for each child Feature:
+  │    ├─ [deduplication-protocol Phase 1+2 for that Feature ID]
+  │    ├─ [gap check for that Feature]
+  │    ├─ [live snapshots for that Feature's screens]
+  │    ├─ generate .feature file (5–10 scenarios)
+  │    ├─ validate_gherkin_content(scope="feature")
+  │    ├─ [show content to user]
+  │    ├─ [ASK: "Attach .feature to Feature #{child_id}?"]
+  │    └─ yes  →  attach_gherkin_to_feature(child_id)
+  │
+  └─ [NEVER call create_and_link_test_cases on the Epic ID]
+
+OUTPUT: one .feature file per child Feature
+        test cases NOT created unless user explicitly asks for child Feature/PBI coverage
+```
+
+### Chain E — Playwright TypeScript from Gherkin
+
+```
+INPUT:  validated .feature content  +  work item ID  +  org URL  +  project name
+  │
+  ├─ [deduplication-protocol Phase 1 — read existing locators, page objects, steps]
+  │
+  ├─ [gap check — identify state-dependent screens; stop and ask if blockers found]
+  │
+  ├─ [live Playwright MCP snapshots through full flow]
+  │
+  ├─ generate_playwright_code(gherkin, context_map)
+  │
+  ├─ [apply delta filter — remove keys / methods / steps already in existing files]
+  │
+  ├─ [show delta summary to user]
+  │
+  ├─ [ASK: "Attach these Playwright files to ADO work item #{id}?"]
+  │    └─ yes  →  attach_code_to_work_item(delta files only)
+  │    └─ no   →  stop; offer local download only if user asks
+  │
+  └─ [STOP — do not trigger Helix write unless user explicitly asks]
+
+OUTPUT: delta Playwright files attached to work item (or shown inline)
+        NO Helix disk write unless user explicitly requests it
+```
+
+---
+
+## 5. Ambiguity Resolution — Stop, Don't Guess
+
+When any of the following is unclear, **stop and ask the user**. Do not proceed.
+
+| Ambiguity | What to ask |
+|---|---|
+| Work item ID given but type is unknown | Call fetch tool and surface the `work_item_type` field; do not guess |
+| "Generate everything for #123" | "Which artifacts do you want? (A) Manual test cases in ADO (B) Gherkin .feature file (C) Playwright TypeScript (D) All of the above — and which should be attached to ADO vs saved locally?" |
+| User says "attach it" after multiple artifacts generated | "Which artifact are you referring to — the Gherkin .feature file, the Playwright TypeScript files, or both?" |
+| No org URL or project name provided | "Please provide the ADO organisation URL (e.g. `https://dev.azure.com/myorg`) and project name." |
+| No screen name or navigation path available | Use `<!-- TODO: confirm screen name -->` placeholder; surface to user; do not invent |
+| No test data for a state-dependent screen | Stop; ask what file / email / record to use; do not invent |
+| User says "yes" ambiguously after a confirmation prompt | Re-read the most recent prompt; if still unclear, re-ask with the specific action being confirmed |
+
+---
+
+## 6. No Carry-Over Between Decisions
+
+Each of these decisions is **completely independent**. A prior answer to one does not answer another.
+
+```
+[1] Generate Gherkin?              → answered
+[2] Attach Gherkin to ADO?         → must ask SEPARATELY after [1]
+[3] Generate Playwright code?      → must ask SEPARATELY
+[4] Attach Playwright to ADO?      → must ask SEPARATELY after [3]
+[5] Create test cases in ADO?      → must ask SEPARATELY
+[6] Save any artifact locally?     → must ask SEPARATELY
+[7] Write to Helix-QA on disk?     → must ask SEPARATELY
+```
+
+**Declining [5] does not affect [2], [4], [6], or [7].**
+**Confirming [2] does not pre-answer [4].**
+**Saying "yes" at step [1] does not mean "yes" at any other step.**
+
+---
+
+## 7. Decision Tree — Work Item Type Routing
+
+```
+User provides work item ID
+         │
+         ▼
+  Call the fetch tool for the intended operation
+  (fetch_work_item, fetch_work_item_for_gherkin, or fetch_epic_hierarchy)
+         │
+         ▼
+  Read work_item_type from response
+         │
+    ┌────┴─────────────────────────────────────────────┐
+    │                                                  │
+  "Epic"                                          not "Epic"
+    │                                                  │
+    ▼                                            ┌─────┴────────┐
+  HARD STOP for test cases                    "Feature"    "PBI"/"Bug"
+  Use fetch_epic_hierarchy for Gherkin            │              │
+  Never call create_and_link_test_cases           │              │
+  Never call attach_code_to_work_item             │              │
+  on the Epic ID                             Feature path   PBI/Bug path
+                                            (5–10 scenarios) (3–9 scenarios)
+                                            attach_gherkin_to_feature
+                                                        attach_gherkin_to_work_item
+```
+
+```
+Feature path for test cases
+         │
+         ▼
+  create_and_link_test_cases returns confirmation_required: true
+         │
+         ▼
+  STOP — show user: Feature title + proposed TC count
+         │
+    ┌────┴────┐
+  "yes"     "no"/"cancel"
+    │              │
+    ▼           ABORT — report "No test cases created"
+  retry create_and_link_test_cases
+  with identical args + confirmed=true
+  (do NOT change work_item_id or pivot to a child PBI)
+```
+
+---
+
+## 8. Versioning — Explicit vs Inferred
+
+All rules in this file are **explicitly stated**. None are inferred from code patterns,
+prior conversation, or training data.
+
+When a rule is changed:
+
+1. Update the rule in this file with a dated entry in the change log below.
+2. Update the corresponding skill file in `skills/` to match.
+3. Run `./scripts/install-skills.sh vscode` to sync `.github/copilot-instructions/`.
+4. Update `CLAUDE.md` if the rule affects a key rule number.
+
+### Change log
+
+| Date | Version | Change | Author |
+|---|---|---|---|
+| 2025-01-01 | 1.0 | Initial explicit rule set — all 8 sections | repo init |
+| 2026-04-03 | 1.1 | 3C: added `confirmed=true` retry protocol for Feature confirmation gate | repo update |
+| 2026-04-03 | 1.1 | 3E: paren error recovery now references `pre_validate_cucumber_steps` as first diagnostic step | repo update |
+| 2026-04-03 | 1.1 | §7: Feature decision tree clarifies retry mechanism (`confirmed=true`, no pivot to child PBI) | repo update |

package/skills/qa-stlc/deduplication-protocol.md

@@ -0,0 +1,303 @@
+---
+name: deduplication-protocol
+description: >
+  MANDATORY pre-flight protocol for every QA STLC agent run. Must be read and applied BEFORE
+  creating any test cases, Gherkin feature files, Playwright locators, page objects, or step
+  definitions in Azure DevOps. Prevents duplicate test cases, duplicate feature file attachments,
+  and duplicate Playwright code being created across multiple runs or agents on the same work item.
+  Triggers on any task involving: ADO work items, test cases, feature files, Gherkin BDD, Playwright
+  automation, locators, page objects, step definitions, qa-gherkin-generator, qa-test-case-manager,
+  qa-playwright-generator tools.
+compatibility:
+  tools:
+    - qa-test-case-manager:get_linked_test_cases
+    - qa-test-case-manager:fetch_work_item
+    - qa-test-case-manager:create_and_link_test_cases
+    - qa-gherkin-generator:fetch_feature_hierarchy
+    - qa-gherkin-generator:attach_gherkin_to_feature
+    - qa-playwright-generator:generate_playwright_code
+    - qa-playwright-generator:attach_code_to_work_item
+    - qa-playwright-generator:validate_gherkin_steps
+---
+
+# QA Deduplication Protocol
+
+> **Read `AGENT-BEHAVIOR.md` before this protocol.**
+> This protocol is a pre-flight gate only — it does not authorise creating anything.
+> All creation decisions require separate explicit user confirmation per artifact type.
+
+> **This protocol is mandatory. No artifact may be created or attached to ADO without completing
+> the READ → DIFF → CREATE-ONLY-WHAT-IS-MISSING pipeline below.**
+>
+> Any agent that skips this protocol and creates duplicates has violated the QA STLC workflow.
+
+---
+
+## Why This Exists
+
+When QA STLC agents run more than once on the same work item — or when multiple agents run in
+sequence on the same item — they have no memory of what previous runs created. Without this
+protocol every run blindly creates new test cases, attaches new feature files, and generates new
+Playwright code that duplicates existing artifacts. This produces:
+
+- 2–5× the intended number of ADO test cases per work item
+- Multiple `.feature` files on the same work item covering identical scenarios
+- Multiple versions of `locators.ts` / `PageObject.ts` / `steps.ts` that diverge silently
+- Test suites that fail because the same step definition is registered twice
+
+This skill codifies the fix as a durable, enforceable protocol that any agent can read and follow.
+
+---
+
+## The Three-Phase Mandatory Workflow
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│  PHASE 1 — READ (always first, no exceptions)                 │
+│  PHASE 2 — DIFF (semantic matching, not just string equality) │
+│  PHASE 3 — CREATE only what has no existing coverage          │
+└───────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## PHASE 1 — READ Everything That Already Exists
+
+Before touching any artifact, make all of the following calls **in this order**.
+
+This protocol handles **any work item type** — PBI, Bug, or Feature — as follows:
+
+| Work item type passed | Step 1A | Step 1B |
+|---|---|---|
+| **PBI or Bug** | `fetch_work_item(id)` → get parent Feature id | `fetch_feature_hierarchy(parent_feature_id)` |
+| **Feature** | Skip `fetch_work_item` | `fetch_feature_hierarchy(id)` directly |
+
+### 1A — Fetch the work item (PBI or Bug only)
+
+```
+qa-test-case-manager:fetch_work_item(
+  organization_url, project_name, work_item_id
+)
+```
+
+Extract and store:
+- Title, description, acceptance_criteria
+- **Parent Feature ID** — used in Step 1B
+- Story points, priority, state
+
+Skip this step if the ID passed is already a Feature.
+
+### 1B — Fetch the parent Feature hierarchy
+
+```
+qa-gherkin-generator:fetch_feature_hierarchy(
+  organization_url, project_name, feature_id   ← parent Feature ID from 1A, or the ID itself if Feature
+)
+```
+
+Extract and store:
+- Feature title, description, acceptance criteria
+- **All child PBIs and Bugs** with their titles + acceptance criteria
+- All existing test cases across the whole feature
+- All `.feature` file attachments already on the feature
+- Build the **flow map** from sibling work items (see generate-gherkin.md Step 1D)
+
+> **Why sibling PBIs matter:** A PBI is one slice of a larger flow defined across multiple
+> work items. Siblings often represent prerequisite or downstream steps. Without reading all
+> of them the agent invents navigation steps and test data already defined elsewhere.
+
+### 1C — get_linked_test_cases on the specific work item
+
+```
+qa-test-case-manager:get_linked_test_cases(
+  organization_url, project_name, work_item_id   ← the original ID (PBI, Bug, or Feature)
+)
+```
+
+Extract and store:
+- All existing test case IDs, titles (normalised), priority values
+
+### 1D — Check for existing Playwright attachments
+
+From the feature hierarchy response, check for:
+- `locators.ts` — extract all locator keys already defined
+- `*Page.ts` — extract all method names already defined
+- `*.steps.ts` — extract all step definition strings already registered
+
+> If you cannot read an attachment's content, treat it as fully covering its domain and
+> produce NO new file of that type unless you can prove a gap.
+
+---
+
+## PHASE 2 — DIFF Using Semantic Matching
+
+String equality is not enough. Two test cases are **semantically equivalent** (duplicates)
+if they test the same condition on the same subject, even when worded differently.
+
+### Normalisation algorithm (apply before comparing)
+
+1. Lowercase the full title
+2. Strip tag prefixes: `[smoke]`, `[regression]`, `[a11y]`, `[negative]`, `[boundary]`, etc.
+3. Strip filler words: `the`, `a`, `an`, `is`, `are`, `should`, `will`, `when`, `after`, `during`
+4. Extract the **subject noun** (what is being tested: button, CSV, backend, upload, template…)
+5. Extract the **condition** (visible, absent, downloaded, cleared, rejected, correct…)
+6. If subject + condition match an existing case → **DUPLICATE**, do not create
+
+### Semantic coverage matrix
+
+```
+For each proposed test case:
+  normalise(proposed.title) → (subject, condition)
+  for each existing test case:
+    normalise(existing.title) → (subject, condition)
+    if subject matches AND condition matches → DUPLICATE → skip
+  if no match found → NET-NEW → add to creation list
+```
+
+Only pass the **net-new** list to `create_and_link_test_cases`.
+
+### Gherkin scenario deduplication
+
+For each proposed Gherkin scenario:
+1. Extract the scenario title
+2. Apply the same normalisation algorithm
+3. Compare against all scenario titles in existing `.feature` attachments AND existing ADO test case titles
+4. Semantic match → skip; zero net-new → do not attach; some net-new → attach delta file only
+
+### Playwright code deduplication
+
+- `locators.ts`: only emit keys not already in existing file; if delta empty → skip; if non-empty → attach as `locators.delta.ts`
+- `*Page.ts`: only emit methods not already present; if delta empty → skip; if non-empty → attach as `*Page.delta.ts`
+- `*.steps.ts`: only emit step strings not already registered; NEVER re-register an existing step (causes `Ambiguous step definition` runtime error)
+
+---
+
+## PHASE 3 — CREATE Only What Is Missing
+
+| Diff result | Action |
+|---|---|
+| Zero net-new | **Skip.** Log: `✅ Already fully covered — nothing to create.` |
+| Some net-new, some duplicates | **Create only net-new.** Log which were skipped and why. |
+| All net-new (first run) | **Create all.** Normal flow. |
+
+### Mandatory deduplication report
+
+Output after every run regardless of whether anything was created:
+
+```
+## Deduplication Report — Work Item #<id>
+
+### Test Cases
+- Existing: <count> linked
+- Proposed: <count>
+- Duplicates skipped: <count> (<titles>)
+- Net-new created: <count> (<IDs if created>)
+
+### Gherkin Feature File
+- Existing attachments: <filenames or "none">
+- Proposed scenarios: <count>
+- Duplicate scenarios skipped: <count> (<titles>)
+- Net-new scenarios: <count>
+- Action: <"Skipped — fully covered" | "Attached delta" | "Attached full (first run)">
+
+### Playwright Code
+- Existing locators.ts: <"found — N keys" | "not found">
+- Net-new locator keys: <count> (<list or "none">)
+- Existing page object: <"found — N methods" | "not found">
+- Net-new page methods: <count> (<list or "none">)
+- Existing steps file: <"found — N steps" | "not found">
+- Net-new step definitions: <count> (<list or "none">)
+- Action per file: <"Skipped" | "Attached delta" | "Attached full (first run)">
+```
+
+---
+
+## Hard Rules — Never Violate These
+
+1. **NEVER call `create_and_link_test_cases` without first calling `get_linked_test_cases`** on the same work item.
+2. **NEVER attach a `.feature` file without first checking for existing feature file attachments.**
+3. **NEVER attach a `steps.ts` that re-registers an existing step string** — causes `Ambiguous step definition` at runtime.
+4. **NEVER treat tag differences as meaningful.** `[REGRESSION] Export List downloads CSV` is a duplicate of `[SMOKE] Clicking Export List downloads a valid CSV file`.
+5. **NEVER create more than one test case covering the same (subject, condition) pair.**
+6. **NEVER skip this protocol because the work item appears new.** `existing_test_cases_count: 0` in the hierarchy can still have cases via `get_linked_test_cases` — always call both.
+
+---
+
+## Integration With Other QA Skills
+
+This protocol is a **work-item-scoped pre-flight gate**.
+
+- **Each unique `work_item_id` gets exactly one PHASE 1 run.** Findings are cached and reused by every subsequent agent operating on the same item.
+- **A different `work_item_id` always triggers a fresh PHASE 1.** Cache from item A must never be used for item B.
+
+```
+work_item_id = 111  →  PHASE 1 runs in full → CACHE[111] populated
+  generate-gherkin on 111      →  reads CACHE[111], skips PHASE 1
+  generate-playwright on 111   →  reads CACHE[111], skips PHASE 1
+
+work_item_id = 222  →  PHASE 1 runs in full → CACHE[222] populated (CACHE[111] untouched)
+```
+
+Skills that delegate here:
+```
+skills/generate-gherkin.md          →  delegates here; reads work-item cache
+skills/generate-playwright-code.md  →  delegates here; reads work-item cache
+```
+
+### Work-Item Cache Schema
+
+```
+CACHE[work_item_id] = {
+  work_item:            { id, type, title, acceptance_criteria },  # PBI/Bug/Feature
+  parent_feature:       { id, title, description },
+  sibling_pbis:         [{ id, type, title, acceptance_criteria, state }],
+  flow_map:             <assembled string describing the full user journey>,
+  existing_test_cases:  [{ id, title, priority }],
+  existing_attachments: {
+    feature_files: [{ name, content }],
+    locators_ts:   { found: bool, keys: [] },
+    page_objects:  [{ name, methods: [] }],
+    steps_files:   [{ name, step_strings: [] }],
+  },
+  gap_check_completed:  bool,   # set true after generate-gherkin Step 2 passes
+  phase1_completed:     true,
+}
+```
+
+**Before running PHASE 1**, check `CACHE[work_item_id].phase1_completed`:
+- If **true** → skip PHASE 1 entirely; use cached data for PHASE 2.
+- If **false / not set** → run PHASE 1 in full and populate the cache.
+
+---
+
+## Examples
+
+### Multiple work items in one session
+
+```
+► PBI #111 processed:
+  CACHE[111] not found → PHASE 1 in full → CACHE[111].phase1_completed = true
+  generate-gherkin on 111    → reads CACHE[111]
+  generate-playwright on 111 → reads CACHE[111], skips all ADO reads
+
+► Bug #222 processed:
+  CACHE[222] not found → PHASE 1 in full → CACHE[222].phase1_completed = true
+  (CACHE[111] untouched — completely independent)
+```
+
+### Second run on a fully covered item
+
+```
+PHASE 1: get_linked_test_cases(273440) → 35 cases; fetch_feature_hierarchy → .feature attached
+PHASE 2: 14 proposed → 14/14 duplicates; 0 net-new locators, methods, steps
+PHASE 3: Skip all
+REPORT:  ✅ Work item #273440 fully covered. Nothing to create.
+```
+
+### Partial gap run
+
+```
+PHASE 1: 3 cases found, no .feature, no Playwright attachments
+PHASE 2: 5 proposed → 3 duplicates → 2 net-new
+PHASE 3: create 2 test cases; attach full .feature (first run); attach full Playwright files
+```