@qa-gentic/stlc-agents 1.0.16 → 1.0.18

package/README.md

@@ -1,11 +1,12 @@
 # @qa-gentic/stlc-agents
 
-> AI-powered QA STLC automation — from Azure DevOps **or Jira Cloud** work item to self-healing Playwright TypeScript in a Helix-QA project.
+> AI-powered QA STLC automation — from Azure DevOps **or Jira Cloud** work item state change to self-healing Playwright TypeScript in a Helix-QA project.
 
-Works with **GitHub Copilot** (VS Code Agent mode), **Claude Code**, **Cursor**, and **Windsurf**.
+Works with **GitHub Copilot** (VS Code Agent mode), **Claude Code**, **Cursor**, and **Windsurf**.  
+Also runs fully headless via the **webhook bridge** — no human in the loop required.
 
-![npm version](https://img.shields.io/badge/npm-v1.0.10-blue)
-![PyPI version](https://img.shields.io/badge/pypi-v1.0.10-blue)
+![npm version](https://img.shields.io/badge/npm-v1.0.17-blue)
+![PyPI version](https://img.shields.io/badge/pypi-v1.0.17-blue)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 [![Python >=3.10](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://python.org)
@@ -14,350 +15,357 @@ Works with **GitHub Copilot** (VS Code Agent mode), **Claude Code**, **Cursor**,
 
 ## What It Does
 
-Five Python MCP servers cover the full QA Software Test Life Cycle:
+Five Python MCP servers cover the full QA Software Test Life Cycle. A sixth server (Playwright MCP) drives a real browser during code generation.
 
-| Agent | Input | Output |
-|---|---|---|
-| `qa-test-case-manager` | ADO PBI / Bug / Feature ID | Manual test cases created & linked via TestedBy-Forward |
-| `qa-gherkin-generator` | ADO / Jira Epic / Feature / PBI / Bug ID | `.feature` file attached to ADO work item or saved locally |
-| `qa-playwright-generator` | Gherkin + live browser | `locators.ts` + page objects + step defs attached to ADO or saved locally |
-| `qa-helix-writer` | Generated `.ts` files + `helix_root` | Files written to Helix-QA directory layout on disk |
-| `qa-jira-manager` | **Jira** Story / Bug / Task / Epic | Test cases created in Jira → Gherkin → Playwright TypeScript → Helix-QA files |
+| Agent | Server name | Input | Output |
+|---|---|---|---|
+| Agent 1 | `qa-test-case-manager` | ADO PBI / Bug / Feature | Manual test cases created & linked (TestedBy-Forward), deduped on re-trigger |
+| Agent 2 | `qa-gherkin-generator` | ADO Feature / PBI / Bug | `.feature` file validated and attached to work item |
+| Agent 3 | `qa-playwright-generator` | Gherkin + optional AX-tree `context_map` | `locators.ts` + page objects + step defs (cached, retrieved via `get_generated_files`) |
+| Agent 4 | `qa-helix-writer` | Generated `.ts` files + `helix_root` | Files written to Helix-QA directory layout, never overwrites |
+| Agent 5 | `qa-jira-manager` | Jira Story / Bug / Task | Test cases created & linked in Jira, `.feature` attached to issue, deduped on re-trigger |
+
+---
+
+## End-to-End Flow
 
-A sixth server — **Playwright MCP** (`http://localhost:8931/mcp`) — drives a real browser during code generation, replacing hand-authored locators with accessibility-tree-derived, zero-hallucination selectors.
+### Webhook-triggered (headless)
+
+A work item state change in ADO or Jira fires a webhook POST to the bridge. The bridge normalises the payload and routes it through the pipeline automatically.
+
+```
+ADO Service Hook / Jira Webhook
+        │  POST
+        ▼
+webhook_bridge/server.py  (FastAPI — qa-stlc-serve)
+        │
+        ├─ parsers.py       raw payload → normalised event dict
+        ├─ state_router.py  event → STAGE_TEST_CASES | STAGE_FULL_PIPELINE | SKIP
+        │
+        └─ ci_runner/pipeline.py
+              ├─ run_test_cases()    → Agent 1 (ADO) or Agent 5 (Jira)
+              └─ run_post_done()     → Agent 2 → Agent 3 → Agent 4
+```
+
+### State → stage mapping
+
+| Platform | Work item state | Stage | Agents called |
+|---|---|---|---|
+| ADO | `Approved` / `Committed` | `STAGE_TEST_CASES` | Agent 1 only |
+| ADO | `Done` | `STAGE_FULL_PIPELINE` | Agents 2 → 3 → 4 |
+| Jira | `In Progress` / `Selected for Development` | `STAGE_TEST_CASES` | Agent 5 only |
+| Jira | `Done` | `STAGE_FULL_PIPELINE` | Agents 2 → 3 → 4 |
+
+Any other state is silently dropped. State names are configurable in `state_router.py`.
+
+### STAGE_TEST_CASES — Agent 1 / Agent 5
+
+```
+fetch_work_item / fetch_jira_issue
+        ↓
+[LLM] generate_test_cases()        ← pipeline bridges fetch → LLM → create
+        ↓
+create_deduped_test_cases()        ← internally: get_linked → filter dupes → create_and_link
+```
 
-> **ADO or Jira?** Both pipelines now run the full STLC: fetch → analyse → test cases → Gherkin → Playwright → Helix-QA. ADO uses `qa-test-case-manager` as the entry point; Jira uses `qa-jira-manager`. Agents 2–4 (`qa-gherkin-generator`, `qa-playwright-generator`, `qa-helix-writer`) are shared by both pipelines.
+On re-trigger, titles already linked are skipped (case-insensitive, stop-word normalised). Only net-new test cases are created.
+
+### STAGE_FULL_PIPELINE — Agents 2 → 3 → 4
+
+First error stops the chain and surfaces in the result dict. Subsequent agents are not called.
+
+**Agent 2 — Gherkin**
+
+```
+ADO Feature : fetch_feature_hierarchy  →  [LLM] generate_gherkin
+ADO PBI/Bug : fetch_work_item_for_gherkin  →  [LLM] generate_gherkin
+Jira        : fetch_jira_issue (via Agent 5)  →  [LLM] generate_gherkin
+        ↓
+validate_gherkin_content()             ← structural check before attach
+        ↓  (if invalid → pipeline stops, returns validation errors)
+ADO Feature : attach_gherkin_to_feature()
+ADO PBI/Bug : attach_gherkin_to_work_item()
+Jira        : attach_gherkin_to_issue()    ← uploads via Jira attachment API
+```
+
+The `generate_and_attach_gherkin` composite tool wraps validate + attach for CI/headless callers.
+
+**Agent 3 — Playwright**
+
+```
+generate_playwright_code(gherkin_content, page_class_name)
+        ↓  returns cache_key (files held in-memory)
+get_generated_files(cache_key)
+        ↓  returns { "path/to/file.ts": "content", ... }
+```
+
+`page_class_name` is derived from `event["title"]` (ADO) or `event["summary"]` (Jira) — camel-cased, max 4 words. Without a `context_map`, locators are Gherkin-inferred (stability=0). Pass `app_url` to embed a snapshot hint comment in `locators.ts`.
+
+**Agent 4 — Helix writer**
+
+```
+inspect_helix_project(helix_root)
+        ↓  framework_state: absent | partial | present
+write_helix_files(helix_root, files, mode)
+        mode = "scaffold_and_tests"  if absent or partial
+        mode = "tests_only"          if present
+```
+
+Agent 4 handles all deduplication and conflict renaming internally. No file is ever overwritten.
 
 ---
 
 ## Install
 
-
 ```bash
 # 1. Install the CLI + npm package globally
-#    You will be prompted to choose your integration: ado / jira / both
-#    The choice is saved to ~/.qa-stlc/integration and reused by all subsequent commands.
+#    Prompted to choose integration: ado / jira / both
 npm install -g @qa-gentic/stlc-agents
-```
-
-> **Note:** On most systems, the installer will prompt you to select your integration (ADO, Jira, or both) and then automatically run `qa-stlc init` and offer to scaffold a new project. If you do **not** see the prompt (for example, if npm skips postinstall for an already-installed package, or in some non-interactive environments), simply run:
->
-> ```bash
-> qa-stlc init
-> qa-stlc scaffold
-> ```
-> 
-> This will perform the same setup steps as the postinstall script.
 
-```bash
-# 2. Bootstrap your project (installs Python agents, copies skills, writes MCP config)
-#    --integration overrides the saved preference; omit to reuse the choice from step 1.
-qa-stlc init --vscode --integration ado    # GitHub Copilot / VS Code — ADO pipeline
-qa-stlc init --vscode --integration jira   # GitHub Copilot / VS Code — Jira pipeline
-qa-stlc init --vscode --integration both   # GitHub Copilot / VS Code — both pipelines
-# or for Claude Code (no --vscode flag):
+# 2. Bootstrap your project
+qa-stlc init --vscode --integration ado    # GitHub Copilot / VS Code — ADO
+qa-stlc init --vscode --integration jira   # GitHub Copilot / VS Code — Jira
+qa-stlc init --vscode --integration both   # GitHub Copilot / VS Code — both
+# or for Claude Code:
 qa-stlc init --integration ado
 
 # 3. Scaffold a new Playwright + Cucumber + TypeScript QA project
 qa-stlc scaffold --name my-qa-project
-# or into an existing directory
-qa-stlc scaffold --name acme-e2e --dir /path/to/acme-e2e
 
-# 4. Start the Playwright browser server (required for code generation)
+# 4. Start the Playwright browser server (required for live-locator generation)
 npx @playwright/mcp@latest --port 8931
 ```
 
-`qa-stlc init` does four things:
-1. `pip install qa-gentic-stlc-agents` — installs all five Python MCP servers
-2. Copies skill files to `.github/copilot-instructions/` (and `.claude/` if not `--vscode`)
-3. Copies custom agent files to `.github/agents/` (used by GitHub Copilot and Claude's agent picker)
-4. Writes `.vscode/mcp.json` with all six servers configured
+`qa-stlc init` does five things:
 
-> **Integration flag:** `--integration` controls which agents and skill files are installed.
-> If omitted, the value saved during `npm install -g` is used.
-> You can change it at any time by re-running `qa-stlc init --integration <ado|jira|both>`.
+1. `pip install qa-gentic-stlc-agents` — installs all five Python MCP servers + rules files
+2. Copies skill files to `.github/copilot-instructions/` (and `.claude/` if not `--vscode`)
+3. Copies custom agent files to `.github/agents/`
+4. Copies `ORCHESTRATION_RULES.md` to project root for reference during multi-step tasks
+5. Writes `.vscode/mcp.json` (or `.mcp.json`) with all six servers configured
 
 ---
 
 ## Requirements
 
-- Node.js ≥ 18
-- Python ≥ 3.10, < 3.14
-- For **Azure DevOps** (Agents 1–4) — a `.env` containing:
+| Requirement | Value |
+|---|---|
+| Node.js | >= 18 |
+| Python | >= 3.10, < 3.14 |
+| ADO PAT | Required for Agents 1–4 (ADO pipeline) |
+| Jira OAuth 2.0 (3LO) | Required for Agent 5 (Jira pipeline) |
+| Playwright MCP | `npx @playwright/mcp@latest --port 8931` |
+
+**ADO `.env` vars:**
 
 ```env
 ADO_ORGANIZATION_URL=https://dev.azure.com/your-org
 ADO_PROJECT_NAME=YourProject
 ADO_PAT=your-personal-access-token
-APP_BASE_URL=your-app-base-url
-APP_EMAIL=your-test-email@example.com
-APP_PASSWORD=your-test-password
+APP_BASE_URL=https://your-app.example.com
+
+# LLM — pick one provider:
+AI_HEALING_PROVIDER=anthropic
+AI_HEALING_API_KEY=sk-ant-...
+# or: OPENAI_API_KEY / AZURE_OPENAI_API_KEY / GITHUB_TOKEN (Copilot)
 ```
 
-- For **Jira Cloud** (Agent 5) — additional `.env` vars:
+**Jira additional `.env` vars:**
 
 ```env
 JIRA_CLIENT_ID=your-atlassian-oauth-client-id
 JIRA_CLIENT_SECRET=your-atlassian-oauth-client-secret
 JIRA_CLOUD_ID=your-atlassian-cloud-id
-# Optional — defaults to http://localhost:8765/callback
-# JIRA_REDIRECT_URI=http://localhost:8765/callback
 ```
 
-See [Jira Authentication Setup](#jira-authentication-setup) for how to obtain these values.
-
----
-
-## Commands
-
-```bash
-qa-stlc init [--vscode] [--python <path>] [--integration ado|jira|both]
-# Full bootstrap: pip install + skills + agent files + MCP config
-# Integration defaults to the value saved during npm install -g (prompted at that time)
-
-qa-stlc scaffold [--name <name>] [--dir <path>] [--no-install]
-# Copy full Playwright + Cucumber + TypeScript boilerplate to a new project directory
+**Webhook bridge additional `.env` vars:**
 
-qa-stlc skills [--target claude|vscode|cursor|windsurf|both|print]
-# Copy skill files to the correct AI coding agent directory
-
-qa-stlc mcp-config [--vscode] [--print] [--python <path>] [--playwright-port <n>]
-# Write .vscode/mcp.json (--vscode) or .mcp.json (Claude Code)
-
-qa-stlc verify
-# Check that all six MCP servers are reachable
+```env
+WEBHOOK_SECRET=your-shared-secret
+HELIX_PROJECT_ROOT=/path/to/helix-qa   # where Agent 4 writes files
+PLAYWRIGHT_MCP_URL=http://localhost:8931/mcp   # leave blank to skip Agent 3
 ```
 
 ---
 
-## Usage
+## CLI Commands
 
-Open your AI coding agent and use natural language:
+| Command | Description |
+|---|---|
+| `qa-stlc init [--vscode] [--integration ado\|jira\|both]` | Full bootstrap: pip install + skills + agent files + MCP config |
+| `qa-stlc scaffold [--name n] [--dir path]` | Copy full Playwright + Cucumber + TypeScript boilerplate to a new project |
+| `qa-stlc skills [--target claude\|vscode\|cursor\|windsurf]` | Copy skill files to the correct AI coding agent directory |
+| `qa-stlc mcp-config [--vscode] [--print]` | Write `.vscode/mcp.json` or `.mcp.json` with all servers configured |
+| `qa-stlc verify` | Check that all MCP servers are reachable and auth is cached |
+| `qa-stlc-serve [--host] [--port] [--reload]` | Start the webhook bridge (FastAPI) |
 
-```
-# Azure DevOps — Generate test cases
-Generate test cases for work item #12345 in MyProject at https://dev.azure.com/myorg
+---
 
-# Azure DevOps — Generate Gherkin BDD
-Generate a Gherkin regression suite for Feature #11000 in MyProject at https://dev.azure.com/myorg
+## Orchestration Rules
 
-# Jira — Fetch issue and generate test cases
-Generate test cases for Jira issue PROJ-123
+When `qa-stlc init` is run, `ORCHESTRATION_RULES.md` is installed to your project root and placed in both npm (`node_modules/@qa-gentic/stlc-agents/`) and pip (`site-packages/stlc_agents/`) installations.
 
-# Jira — Fetch an Epic hierarchy
-Fetch the full Epic hierarchy for PROJ-10 in Jira
+Refer to this file in multi-step QA workflows to ensure:
+- **Step breakdown:** every task is decomposed into named steps with explicit inputs/outputs
+- **Pre-flight gates:** output validation runs *before* generation, not after
+- **No skipped steps:** intermediate data is structured and handed off explicitly, never inferred
+- **Countable verification:** code generation steps state expected item counts before implementation
+- **Zero stubs:** no partial outputs with TODOs or empty bodies passed downstream
 
-# Generate Playwright code (requires Playwright MCP running — works with both ADO and Jira flows)
-Generate Playwright TypeScript for the Gherkin I just created. The login page is at /auth/login
+Integration per AI coding agent:
 
-# Write to Helix-QA project
-Write the generated files to my Helix-QA project at /workspace/my-qa-project
-```
+- **GitHub Copilot (VS Code):** Add to `.github/copilot-instructions.md` or reference in your workspace prompt
+- **Claude Code:** Reference in `.claude/instructions.md` or as a project document
+- **Cursor:** Add to `.cursor/rules/orchestration.mdc` (scope: always)
+- **Windsurf:** Reference in `.windsurf/rules.md` or global rules panel
+
+See section 8 of `ORCHESTRATION_RULES.md` for agent-specific integration notes.
 
 ---
 
 ## Tool Reference
 
-### qa-test-case-manager _(Azure DevOps)_
+### Agent 1 — `qa-test-case-manager` _(Azure DevOps)_
 
 | Tool | Description |
 |---|---|
-| `fetch_work_item` | Fetch a PBI, Bug, or Feature with acceptance criteria, linked test cases, and coverage hints. Returns `epic_not_supported` for Epics. Returns `confirmation_required: true` for Features. |
-| `get_linked_test_cases` | List all test cases already linked to a work item. Call before generating to power the deduplication diff. |
-| `create_and_link_test_cases` | Create structured manual test cases in ADO and link them via TestedBy-Forward. |
+| `fetch_work_item` | Fetch a PBI, Bug, or Feature with acceptance criteria, coverage hints, and existing TC count. Returns `epic_not_supported` for Epics. |
+| `get_linked_test_cases` | List all test cases linked via TestedBy-Forward (used by dedup). |
+| `create_and_link_test_cases` | Create structured manual test cases and link to work item. Feature confirmation gate fires unless `confirmed=true`. |
+| `create_deduped_test_cases` | **Headless/webhook tool.** Internally calls `get_linked_test_cases`, filters duplicates (normalised title match), then calls `create_and_link_test_cases` on net-new only. Safe to call on every re-trigger. |
 
-### qa-gherkin-generator _(Azure DevOps)_
+### Agent 2 — `qa-gherkin-generator` _(Azure DevOps)_
 
 | Tool | Description |
 |---|---|
-| `fetch_feature_hierarchy` | Fetch a Feature and all child PBIs/Bugs with acceptance criteria and existing attachments. |
-| `fetch_work_item_for_gherkin` | Fetch a PBI or Bug with parent Feature context, suggested file name, and linked test case steps. |
-| `attach_gherkin_to_feature` | Validate and attach a `.feature` file to a Feature work item. |
-| `attach_gherkin_to_work_item` | Validate and attach a `.feature` file to a PBI or Bug work item. |
-| `validate_gherkin_content` | Structural validation — tags, scenario count, navigation steps. Returns `valid: bool` + `errors` + `warnings`. |
+| `fetch_feature_hierarchy` | Fetch a Feature + all child PBIs/Bugs + coverage hints. |
+| `fetch_work_item_for_gherkin` | Fetch a single PBI or Bug with parent Feature context. |
+| `validate_gherkin_content` | Structural check: @smoke/@regression tags, scenario count (5–10 feature / 3–9 work_item), every scenario has `When`, no duplicate titles. |
+| `attach_gherkin_to_feature` | Validate + upload + link `.feature` to a Feature work item. |
+| `attach_gherkin_to_work_item` | Validate + upload + link `.feature` to a PBI or Bug. |
+| `generate_and_attach_gherkin` | **Headless/webhook composite.** Accepts pre-generated `gherkin_content`, validates, attaches. Returns `status: validation_failed` with errors if invalid — pipeline must re-generate. |
 
-### qa-playwright-generator _(ADO + Jira)_
+### Agent 3 — `qa-playwright-generator` _(ADO + Jira)_
 
 | Tool | Description |
 |---|---|
-| `generate_playwright_code` | Generate `locators.ts`, `*Page.ts`, `*.steps.ts`, and `cucumber-profile.js` from validated Gherkin + live AX-tree `context_map`. Hard-blocks if `context_map` is absent to prevent hallucinated locators. |
-| `scaffold_locator_repository` | Generate the six Helix-QA healing infrastructure files. |
+| `generate_playwright_code` | Generate `locators.ts`, `*Page.ts`, `*.steps.ts`, `cucumber-profile.js`. Returns `cache_key`. Optional `context_map` for AX-tree-verified locators; optional `app_url` embeds snapshot hint. |
+| `get_generated_files` | Retrieve full file content by `cache_key` from Agent 3's in-memory cache. |
+| `scaffold_locator_repository` | Generate the five Helix-QA healing infrastructure files (`LocatorHealer`, `TimingHealer`, `VisualIntentChecker`, `LocatorRepository`, `HealingDashboard`). Call once per project. |
 | `validate_gherkin_steps` | Check for duplicate step strings and missing `When` steps. |
-| `attach_code_to_work_item` | Attach delta Playwright TypeScript files to an ADO work item. Pass only net-new delta files. |
-
-### qa-helix-writer _(ADO + Jira)_
-
-| Tool | Description |
-|---|---|
-| `inspect_helix_project` | Returns `framework_state` (`present` / `partial` / `absent`) and `recommendation`. |
-| `list_helix_tree` | List the full directory tree of a Helix-QA project. |
-| `read_helix_file` | Read an existing file from the Helix-QA project for overlap detection. |
-| `write_helix_files` | Write generated files to the correct Helix-QA paths. |
+| `attach_code_to_work_item` | Attach generated TypeScript delta files to an ADO work item. |
 
-### qa-jira-manager _(Jira Cloud)_
+### Agent 4 — `qa-helix-writer` _(ADO + Jira)_
 
 | Tool | Description |
 |---|---|
-| `fetch_jira_issue` | Fetch a Story, Bug, or Task with acceptance criteria, coverage hints, and existing linked test case count. Returns `epic_use_hierarchy` for Epics. |
-| `fetch_jira_epic_hierarchy` | Fetch an Epic with all child issues (Stories, Tasks, Bugs, Sub-tasks). |
-| `create_and_link_test_cases` | Create test case issues in Jira (type `Test`, falls back to `Task`) and link them via `is tested by`. Steps stored as an ADF table — no Xray required. Returns `confirmation_required: true` for Epics. |
-| `get_linked_test_cases` | List all issues linked to a Jira issue via `is tested by` / `Test` link type. Call before generating to avoid duplicates. |
+| `inspect_helix_project` | Returns `framework_state`: `present` / `partial` / `absent`. Drives `mode` selection in pipeline. |
+| `write_helix_files` | Write files to Helix-QA layout. `mode=scaffold_and_tests` for new/partial projects; `mode=tests_only` for existing. Never overwrites; deduplicates and conflict-renames. |
+| `list_helix_tree` | Full directory listing of a Helix-QA project. |
+| `read_helix_file` | Read an existing file for overlap detection. |
 
-### playwright _(external)_
+### Agent 5 — `qa-jira-manager` _(Jira Cloud)_
 
 | Tool | Description |
 |---|---|
-| `browser_navigate` | Navigate to a URL in the live browser. |
-| `browser_snapshot` | Capture the full AX tree — source for zero-hallucination locators. |
-| `browser_fill_form` | Fill multiple form fields by ref. |
-| `browser_click` | Click an element by ref. |
-| `browser_file_upload` | Upload a file to a file input by ref. |
+| `fetch_jira_issue` | Fetch a Story, Bug, or Task with acceptance criteria and coverage hints. Returns `epic_use_hierarchy` for Epics. |
+| `get_linked_test_cases` | List all issues linked via `is tested by` / `Test` link type (used by dedup). |
+| `create_and_link_test_cases` | Create test case issues in Jira (type `Test`, falls back to `Task`) and link. Steps stored as ADF table — no Xray required. Epic confirmation gate fires unless `confirmed=true`. |
+| `create_deduped_test_cases` | **Headless/webhook tool.** Internally calls `get_linked_test_cases`, filters duplicates (normalised summary match), then calls `create_and_link_test_cases` on net-new only. Safe on every re-trigger. |
+| `attach_gherkin_to_issue` | Upload a `.feature` file as an attachment to a Jira issue via the Jira attachment API. File is named `{issue_key}_{summary_kebab}_regression.feature`. |
 
 ---
 
-## MCP Config
-
-### VS Code / GitHub Copilot (`.vscode/mcp.json`)
-
-```json
-{
-  "servers": {
-    "qa-test-case-manager":    { "command": "/path/to/.venv/bin/qa-test-case-manager" },
-    "qa-gherkin-generator":    { "command": "/path/to/.venv/bin/qa-gherkin-generator" },
-    "qa-playwright-generator": { "command": "/path/to/.venv/bin/qa-playwright-generator" },
-    "qa-helix-writer":         { "command": "/path/to/.venv/bin/qa-helix-writer" },
-    "qa-jira-manager": {
-      "command": "/path/to/.venv/bin/qa-jira-manager",
-      "env": {
-        "JIRA_CLIENT_ID": "${env:JIRA_CLIENT_ID}",
-        "JIRA_CLIENT_SECRET": "${env:JIRA_CLIENT_SECRET}",
-        "JIRA_CLOUD_ID": "${env:JIRA_CLOUD_ID}"
-      }
-    },
-    "playwright": { "type": "http", "url": "http://localhost:8931/mcp" }
-  }
-}
-```
+## Three-Layer Self-Healing Architecture
 
-### Claude Code (`.mcp.json`)
-
-```json
-{
-  "mcpServers": {
-    "qa-test-case-manager":    { "command": "/path/to/.venv/bin/qa-test-case-manager" },
-    "qa-gherkin-generator":    { "command": "/path/to/.venv/bin/qa-gherkin-generator" },
-    "qa-playwright-generator": { "command": "/path/to/.venv/bin/qa-playwright-generator" },
-    "qa-helix-writer":         { "command": "/path/to/.venv/bin/qa-helix-writer" },
-    "qa-jira-manager": {
-      "command": "/path/to/.venv/bin/qa-jira-manager",
-      "env": {
-        "JIRA_CLIENT_ID": "${env:JIRA_CLIENT_ID}",
-        "JIRA_CLIENT_SECRET": "${env:JIRA_CLIENT_SECRET}",
-        "JIRA_CLOUD_ID": "${env:JIRA_CLOUD_ID}"
-      }
-    },
-    "playwright": { "type": "url", "url": "ws://localhost:8931" }
-  }
-}
-```
+| Layer | Class | What It Heals |
+|---|---|---|
+| 1 — Locator | `LocatorHealer` | primary selector → role → label → text → AI Vision → CDPSession AX tree |
+| 2 — Timing | `TimingHealer` | network-trace drift → auto-adjusted timeouts → HealingDashboard |
+| 3 — Visual | `VisualIntentChecker` | element screenshot diff at assertions → HealingDashboard |
 
-> VS Code requires `http://localhost:8931/mcp` (with `/mcp` suffix).
-> Claude Code requires `ws://localhost:8931` (WebSocket, no `/mcp`).
-> `qa-stlc mcp-config` writes the correct format automatically.
+Healed selectors persist in `LocatorRepository`. All AI suggestions require human approval at `http://localhost:7890` before entering version control.
 
 ---
 
-## Skills Installed
+## Webhook / Auto-Trigger Setup
 
-Skills follow the [Agent Skills specification](https://agentskills.io/specification) and live under `skills/<n>/SKILL.md`.
+### Local dev
 
-| Skill | Purpose |
-|---|---|
-| `AGENT-BEHAVIOR.md` | Zero-inference contract. Read first. Always. |
-| `generate-test-cases/SKILL.md` | PBI / Bug / Feature → ADO manual test cases |
-| `generate-gherkin/SKILL.md` | Epic / Feature / PBI / Bug → validated `.feature` + ADO attach |
-| `generate-playwright-code/SKILL.md` | Gherkin + live browser → three-layer self-healing Playwright TypeScript |
-| `write-helix-files/SKILL.md` | Generated files → Helix-QA disk layout, scaffold or merge |
-| `deduplication-protocol/SKILL.md` | READ → DIFF → CREATE mandatory pre-flight gate |
-| `qa-jira-manager/SKILL.md` | Jira issue → test case issues + `is tested by` links |
-
-> **Installed copies** (`.claude/skills/`, `.github/copilot-instructions/`) are generated by
-> `qa-stlc init` / `qa-stlc skills` at project bootstrap time and are gitignored.
-> The canonical source for all skills is the `skills/` directory.
+```bash
+# 1. Install webhook extras
+pip install "qa-gentic-stlc-agents[webhook]"
 
----
+# 2. Start the bridge
+make serve
 
-## Jira Authentication Setup
+# 3. Expose via ngrok
+ngrok http 8080
 
-`qa-jira-manager` uses **Jira OAuth 2.0 (3LO)** with a persistent file-based token cache
-at `~/.jira-cache/jira-token.json` — the same silent-cache / browser-fallback pattern
-used by the ADO MSAL auth module.
+# 4. Register hooks
+make register-ado-hooks  BRIDGE_URL=https://xxxx.ngrok.io
+make register-jira-hooks BRIDGE_URL=https://xxxx.ngrok.io
+```
 
-### Step 1 — Create an Atlassian OAuth 2.0 (3LO) app
+### Azure Functions deploy
 
-1. Go to <https://developer.atlassian.com/console/myapps/>
-2. Click **Create** → **OAuth 2.0 integration**
-3. Add callback URL: `http://localhost:8765/callback`
-4. Under **Permissions**, enable: `read:jira-user`, `read:jira-work`, `write:jira-work`, `offline_access`
-5. Copy the **Client ID** and **Secret**
+```bash
+make deploy-azure FUNC_APP=stlc-webhook-bridge
+make register-ado-hooks  BRIDGE_URL=https://stlc-webhook-bridge.azurewebsites.net/api
+make register-jira-hooks BRIDGE_URL=https://stlc-webhook-bridge.azurewebsites.net/api
+```
 
-### Step 2 — Find your Cloud ID
+### Docker
 
 ```bash
-curl -H "Authorization: Bearer <any-token>" \
-  https://api.atlassian.com/oauth/token/accessible-resources
+make docker-build-webhook
+make docker-run-webhook
 ```
 
-Copy the `id` field for your Jira site.
+### LLM provider selection
 
-### Step 3 — Add to `.env`
+| Provider | Env var(s) | Default model |
+|---|---|---|
+| `anthropic` | `AI_HEALING_API_KEY` or `ANTHROPIC_API_KEY` | `claude-haiku-4-5-20251001` |
+| `copilot` | `GITHUB_TOKEN` | `gpt-4o` |
+| `openai` | `OPENAI_API_KEY` | `gpt-4o-mini` |
+| `azure-openai` | `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_ENDPOINT` | `gpt-4o-mini` |
+| `ollama` | `OLLAMA_HOST` (optional) | `llama3.2` |
 
-```env
-JIRA_CLIENT_ID=your-client-id
-JIRA_CLIENT_SECRET=your-client-secret
-JIRA_CLOUD_ID=your-cloud-id
-```
+Override model at any time: `LLM_MODEL=claude-sonnet-4-6`
 
-### Step 4 — First run
+### Token cost (headless, Haiku default)
 
-The browser opens once on startup. Sign in to Jira. The token is cached silently
-and refreshed automatically for ~60 days — no re-prompting.
+| Stage | Tokens / work item | Approx cost |
+|---|---|---|
+| Test case generation (state → Approved) | ~8,000–15,000 | $0.01–$0.03 |
+| Gherkin generation (state → Done) | ~10,000–18,000 | $0.01–$0.04 |
+| Playwright TS generation (state → Done) | ~20,000–35,000 | $0.03–$0.07 |
 
 ---
 
-## Workflow Comparison: ADO vs Jira
+## ADO vs Jira — Side by Side
 
 | Step | Azure DevOps | Jira Cloud |
 |---|---|---|
+| Trigger | Service Hook: `workitem.updated` | Webhook: `jira:issue_updated` |
 | Fetch issue | `fetch_work_item` | `fetch_jira_issue` |
-| Fetch Epic hierarchy | ⛔ Not supported — warn user | ⛔ Not supported — warn user |
-| Check for duplicates | `get_linked_test_cases` | `get_linked_test_cases` |
-| Create & link test cases | `create_and_link_test_cases` | `create_and_link_test_cases` |
-| Generate Gherkin | `fetch_work_item_for_gherkin` → `attach_gherkin_to_work_item` | `qa-gherkin-generator` with Jira issue AC (save locally or attach to Jira) |
-| Generate Playwright | `generate_playwright_code` (shared) | `generate_playwright_code` (shared) |
+| Check duplicates | `get_linked_test_cases` | `get_linked_test_cases` |
+| Create test cases (interactive) | `create_and_link_test_cases` | `create_and_link_test_cases` |
+| Create test cases (headless) | `create_deduped_test_cases` | `create_deduped_test_cases` |
+| Gherkin attach | `attach_gherkin_to_feature` / `attach_gherkin_to_work_item` | `attach_gherkin_to_issue` |
+| Headless Gherkin composite | `generate_and_attach_gherkin` | `generate_and_attach_gherkin` + `attach_gherkin_to_issue` |
+| Playwright generation | `generate_playwright_code` (shared) | `generate_playwright_code` (shared) |
 | Write to disk | `write_helix_files` (shared) | `write_helix_files` (shared) |
-| Authentication | MSAL silent + browser (`~/.msal-cache/`) | OAuth 2.0 (3LO) + browser (`~/.jira-cache/`) |
-| Link relation | `TestedBy-Forward` | `is tested by` / `Test` link type |
-
----
-
-## Three-Layer Self-Healing Architecture
-
-| Layer | Class | What it heals |
-|---|---|---|
-| 1 — Locator | `LocatorHealer` | primary selector → role → label → text → AI Vision → CDPSession AX tree |
-| 2 — Timing | `TimingHealer` | network-trace drift → auto-adjusted timeouts → HealingDashboard |
-| 3 — Visual | `VisualIntentChecker` | element screenshot diff at assertions → HealingDashboard |
-
-Healed selectors persist in `LocatorRepository`. HealingDashboard: `http://localhost:7890`.
-
-All suggestions require human approval before entering version control.
+| Link relation | `TestedBy-Forward` | `is tested by` / `Test` |
+| Auth | MSAL silent + browser (`~/.msal-cache/`) | OAuth 2.0 3LO + browser (`~/.jira-cache/`) |
 
 ---
 
 ## Run Tests
 
 ```bash
+# Full suite
 ENABLE_SELF_HEALING=true \
 HEALING_DASHBOARD_PORT=7890 \
 APP_BASE_URL=<your-app-base-url> \
@@ -371,96 +379,13 @@ cucumber-js --config=config/cucumber.js -p <feature_profile> --tags "@smoke"
 
 ---
 
-## Scaffold a New QA Project
-
-The `scaffold` command copies the full Playwright + Cucumber + TypeScript boilerplate framework — including three-layer AI self-healing, BDD templates, and CI/CD integration — into a new project directory.
-
-```bash
-# Scaffold into ./my-qa-project (default name)
-qa-stlc scaffold
-
-# Custom project name and location
-qa-stlc scaffold --name acme-e2e --dir /path/to/workspace/acme-e2e
-
-# Skip npm install (e.g. to inspect files first)
-qa-stlc scaffold --name acme-e2e --no-install
-```
-
-After scaffolding:
-
-```bash
-cd my-qa-project
-npx playwright install chromium     # install browser binaries
-cp .env.example .env                # already done by scaffold
-# Edit .env — set BASE_URL and optionally AI_API_KEY
-npm test                            # run the example scenario
-```
-
-### What Gets Scaffolded
-
-| Layer | Contents |
-|---|---|
-| **Config** | `package.json`, `tsconfig.json`, `cucumber.js`, `.env.example`, `.gitignore` |
-| **CI/CD** | `Dockerfile`, `docker-compose.yml`, `azure-pipelines.yml` |
-| **Framework** | `src/hooks/`, `src/pages/BasePage.ts`, `src/locators/`, `src/config/` |
-| **Self-healing** | All healing utilities: `LocatorHealer`, `TimingHealer`, `VisualIntentChecker`, `HealingDashboard`, `review-server`, `healix-ci-apply`, etc. |
-| **AI utilities** | `AILocatorGenerator`, `AISelfHealing`, `AITestGenerator` |
-| **Auth** | `AuthManager`, `AuthSetup` |
-| **Templates** | `_template.feature`, `_template.locators.ts`, `_template.steps.ts`, `_TemplatePage.ts` |
-| **Example test** | `src/test/features/example.feature` + steps |
-
-### Healing Dashboard
-
-During a test run the live dashboard is available at **http://localhost:7890**. After the run use the review server for promote-to-source + PR creation:
-
-```bash
-npm run healix:review    # http://localhost:7891
-# or in CI:
-HEALIX_CI_AUTO_APPROVE=true npm run healix:apply-ci
-```
-
----
-
-## Development
-
-```bash
-# Install (all five agents from one pip package)
-make install-ado         # install + ADO next steps
-make install-jira        # install + Jira next steps
-make install-both        # install + Both next steps
-
-# Verify
-make verify-ado          # ADO agents + MSAL auth cache
-make verify-jira         # Jira agents + OAuth token cache
-make verify-both         # all agents + both auth caches
-
-# Skills
-make skills-ado          # ADO skill files → .claude/skills/ + copilot-instructions/
-make skills-jira         # Jira skill files
-make skills-both         # all skill files
-
-# MCP config
-make mcp-config-ado      # write .mcp.json for ADO pipeline
-make mcp-config-jira     # write .mcp.json for Jira pipeline
-make mcp-config-both     # write .mcp.json for both pipelines
-
-# Test + clean
-make test                # run pytest tests/ -v
-make clean               # remove .venv, __pycache__, dist
-```
-
----
-
 ## Documentation
 
-- [Quick Start: Azure DevOps](QUICKSTART-ADO.md)
-- [Quick Start: Jira Cloud](QUICKSTART-JIRA.md)
-- [Architecture: ADO](ARCHITECTURE-ADO.md)
-- [Architecture: Jira](ARCHITECTURE-JIRA.md)
-- [Walkthrough: ADO](WALKTHROUGH-ADO.md)
-- [Walkthrough: Jira](WALKTHROUGH-JIRA.md)
-- [Architecture Reference](docs/architecture.md)
-- [End-to-End Walkthrough](docs/walkthrough.md)
+- [ARCHITECTURE-ADO.md](ARCHITECTURE-ADO.md) — Full technical architecture, ADO pipeline
+- [ARCHITECTURE-JIRA.md](ARCHITECTURE-JIRA.md) — Full technical architecture, Jira pipeline
+- [WALKTHROUGH-ADO.md](WALKTHROUGH-ADO.md) — End-to-end walkthrough, ADO pipeline
+- [WALKTHROUGH-JIRA.md](WALKTHROUGH-JIRA.md) — End-to-end walkthrough, Jira pipeline
+- [WEBHOOK.md](WEBHOOK.md) — Webhook bridge setup, deployment, and state trigger customisation
 
 ---