@qa-gentic/stlc-agents 1.0.27 → 1.0.28

package/QUICKSTART-JIRA.md

@@ -0,0 +1,334 @@
+# @qa-gentic/stlc-agents — Jira Cloud Quick Start
+
+> Jira Cloud pipeline: issue → test cases → Gherkin → Playwright TypeScript → Helix-QA.
+> For Azure DevOps see [QUICKSTART-ADO.md](QUICKSTART-ADO.md).
+
+
+Works with **GitHub Copilot** (VS Code Agent mode), **Claude Code**, **Cursor**, and **Windsurf**.
+
+[![npm version](https://img.shields.io/npm/v/@qa-gentic/stlc-agents)](https://www.npmjs.com/package/@qa-gentic/stlc-agents)
+[![PyPI version](https://img.shields.io/pypi/v/qa-gentic-stlc-agents)](https://pypi.org/project/qa-gentic-stlc-agents/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+
+## What the Jira Pipeline Does
+
+Six Python MCP servers. The Jira pipeline uses `qa-jira-manager` as its entry point, then the three shared agents, with `qa-migration` / `stlc-migrate` available for converting existing Playwright projects:
+
+| Step | Agent | What happens |
+|---|---|---|
+| 1 | `qa-jira-manager` | Fetch Jira issue + analyse acceptance criteria |
+| 2 | `qa-jira-manager` | Generate test cases → create in Jira with `is tested by` links |
+| 3 | `qa-gherkin-generator` | Generate Gherkin `.feature` file |
+| 4 | `qa-playwright-generator` | Gherkin + live browser → self-healing Playwright TypeScript |
+| 5 | `qa-helix-writer` | Write generated files to Helix-QA project on disk |
+| — | `qa-migration` / `stlc-migrate` | Existing Playwright project → fully agent-ready Helix-QA tree (Jira `.mcp.json`, skills, healer scaffold, BOILERPLATE infra) |
+
+The Playwright MCP server (`http://localhost:8931/mcp`) is required for browser-driven code generation. It is not part of this package and must be started separately.
+
+---
+
+## Install
+
+```bash
+npm install -g @qa-gentic/stlc-agents
+qa-stlc init --vscode --integration jira
+```
+
+
+`qa-stlc init --integration jira` performs:
+1. `pip install qa-gentic-stlc-agents` — installs all six Python MCP servers + `stlc-migrate` CLI
+2. Copies skill files (including `qa-jira-manager/`, `generate-gherkin/`, `generate-playwright-code/`, `write-helix-files/`, `migrate-framework/`) to your coding agent directory
+3. Writes `.vscode/mcp.json` with all required servers configured (`qa-jira-manager` + shared Agents 2–4 + `qa-migration` + `playwright`)
+
+
+Start the Playwright MCP server before your first session:
+
+```bash
+npx @playwright/mcp@latest --port 8931
+```
+
+---
+
+
+## Requirements
+
+- Node.js ≥ 18
+- Python ≥ 3.10, < 3.14
+- Jira Cloud site with OAuth 2.0 credentials (see [Authentication Setup](#authentication-setup))
+- A `.env` file containing:
+
+
+```env
+# Jira Cloud credentials
+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
+
+# Application under test
+APP_BASE_URL=https://your-app.example.com
+APP_EMAIL=your-test-email@example.com
+APP_PASSWORD=your-test-password
+```
+
+---
+
+## Authentication Setup
+
+### Step 1 — Create an Atlassian OAuth 2.0 (3LO) app
+
+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**, add Jira API scopes: `read:jira-user`, `read:jira-work`, `write:jira-work`
+5. Copy the **Client ID** and **Secret**
+
+### Step 2 — Find your Cloud ID
+
+```bash
+curl -H "Authorization: Bearer <any-valid-token>" \
+  https://api.atlassian.com/oauth/token/accessible-resources
+```
+
+Copy the `id` field for your Jira site.
+
+### Step 3 — Add to `.env`
+
+```env
+JIRA_CLIENT_ID=your-client-id
+JIRA_CLIENT_SECRET=your-client-secret
+JIRA_CLOUD_ID=your-cloud-id
+```
+
+### Step 4 — First run
+
+On first use a browser opens once for sign-in. The token is cached at `~/.jira-cache/jira-token.json` and silently refreshed for ~60 days.
+
+---
+
+
+## Commands
+
+All `qa-stlc` commands accept `--integration jira`:
+
+```bash
+qa-stlc init [--vscode] [--python <path>] --integration jira
+# Full bootstrap: pip install + Jira skills + MCP config with all 5 agents
+
+qa-stlc mcp-config [--vscode] [--print] [--python <path>] --integration jira
+# Write MCP config including qa-jira-manager + shared agents
+
+qa-stlc skills [--target claude|vscode|cursor|windsurf|both|print] --integration jira
+# Install Jira + shared skill files (excludes ADO-only generate-test-cases/)
+
+qa-stlc verify --integration jira
+# Check all 6 MCP servers are installed + Jira auth cache exists
+
+qa-stlc scaffold [--name <n>] [--dir <path>]
+# Scaffold a new Playwright + Cucumber + TypeScript QA project (same as ADO)
+
+stlc-migrate --source <existing> --helix <target> --integration jira [--conflict overwrite|skip|interactive] [--dry-run] [--json]
+# Migrate an existing Playwright (with or without Cucumber) project into the
+# Helix-QA layout, Jira variant. Installs Jira-only skills + .mcp.json with
+# qa-jira-manager (incl. JIRA_CLIENT_ID/SECRET/CLOUD_ID env passthrough),
+# the enhanced healer scaffold (LocatorHealer 8-strategy chain, LocatorRepository
+# schema v1, HealingDashboard with write-back), AGENT-BEHAVIOR.md,
+# ORCHESTRATION_RULES.md, and the 11-file BOILERPLATE allowlist. See
+# `skills/migrate-framework/SKILL.md` for the full pipeline reference.
+```
+
+### Makefile shortcuts
+
+```bash
+make bootstrap-jira                                       # one-shot: Jira skills + .mcp.json
+make migrate-jira SOURCE=<old> HELIX=<new>                # Jira migration with sensible defaults
+make migrate-jira SOURCE=<old> HELIX=<new> CONFLICT=overwrite   # re-migrate in place
+make audit-migration HELIX=<new>                          # framework_state + skills + healer scaffold + heal-store report
+```
+
+---
+
+## Usage
+
+Open your AI coding agent and use natural language:
+
+```
+# Full Jira pipeline — single prompt
+Run the full STLC pipeline for Jira issue PROJ-123
+
+# Step by step
+Fetch Jira issue PROJ-123 and analyse acceptance criteria
+Generate test cases for PROJ-123 and create them in Jira
+Generate Gherkin feature file for PROJ-123
+Generate Playwright TypeScript for the Gherkin I just created. The login page is at /auth/login
+Write the generated files to my Helix-QA project at /workspace/my-qa-project
+```
+
+---
+
+## Tool Reference
+
+
+### qa-jira-manager
+
+| Tool | Description |
+|---|---|
+| `fetch_jira_issue` | Fetch a Story, Bug, Task, or Sub-task with acceptance criteria and coverage hints. Routes Epics to `fetch_jira_epic_hierarchy`. |
+| `fetch_jira_epic_hierarchy` | Fetch an Epic and 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 ADF table — no Xray required. Returns `confirmation_required: true` for Epics. |
+| `get_linked_test_cases` | Return all test cases already linked to a Jira issue. Call before generating to power the deduplication gate. |
+
+### qa-gherkin-generator (shared)
+
+| Tool | Description |
+|---|---|
+| `fetch_work_item_for_gherkin` | Fetch a work item with AC context for Gherkin generation (pass Jira issue key). |
+| `validate_gherkin_content` | Structural validation — tags, scenario count, navigation steps. Returns `valid: bool` + `errors` + `warnings`. |
+| `attach_gherkin_to_work_item` | Validate and attach a `.feature` file (for Jira pipeline: saves locally or attaches via Jira REST). |
+
+### qa-playwright-generator (shared)
+
+| Tool | Description |
+|---|---|
+| `generate_playwright_code` | Generate `locators.ts`, `*Page.ts`, `*.steps.ts` from validated Gherkin + live AX-tree `context_map`. Blocks if `context_map` is absent. |
+| `scaffold_locator_repository` | Generate the six Helix-QA healing infrastructure files. |
+| `validate_gherkin_steps` | Check for duplicate step strings and missing `When` steps. |
+
+### qa-helix-writer (shared)
+
+| 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 for overlap detection. |
+| `write_helix_files` | Write generated files to the correct Helix-QA paths. |
+
+### playwright (external)
+
+| 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. |
+
+---
+
+## MCP Config
+
+### VS Code / GitHub Copilot (`.vscode/mcp.json`)
+
+```json
+{
+  "servers": {
+    "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}" } },
+    "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-migration":            { "command": "/path/to/.venv/bin/stlc-migrate" },
+    "playwright": { "type": "http", "url": "http://localhost:8931/mcp" }
+  }
+}
+```
+
+### Claude Code (`.mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "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}" } },
+    "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-migration":            { "command": "/path/to/.venv/bin/stlc-migrate" },
+    "playwright": { "command": "npx", "args": ["@playwright/mcp@latest", "--isolated"] }
+  }
+}
+```
+
+> Run `qa-stlc mcp-config --integration jira [--vscode]` to generate this
+> manually, or run `stlc-migrate --integration jira` and the migration emits
+> `.mcp.json` automatically with absolute binary paths discovered from the
+> active venv.
+
+---
+
+
+## Skills Installed (Jira integration)
+
+| Skill | Purpose |
+|---|---|
+| `AGENT-BEHAVIOR.md` | Zero-inference contract. Read first. Always. |
+| `qa-jira-manager/` | Jira fetch, test case creation, and full pipeline orchestration |
+| `generate-gherkin/` | Gherkin generation from issue AC |
+| `generate-playwright-code/` | Gherkin + live browser → self-healing Playwright TypeScript |
+| `write-helix-files/` | Generated files → Helix-QA disk layout |
+| `deduplication-protocol/` | READ → DIFF → CREATE mandatory pre-flight gate |
+
+> `generate-test-cases/` is excluded for Jira-only installs — it is ADO work-item-scoped.
+
+---
+
+## Three-Layer Self-Healing Architecture
+
+Same as the ADO pipeline — the generated Playwright code uses identical healing infrastructure:
+
+| Layer | Class | What it heals |
+|---|---|---|
+| 1 — Locator | `LocatorHealer` | 8-strategy chain: cached → primary → **attribute** → **type-hint** → role → label → text → AI Vision. After match, introspects the live element and persists a specific single-attribute selector (`#id`, `[data-testid=…]`, etc.). |
+| 2 — Timing | `TimingHealer` | Network-trace drift → auto-adjusted timeouts → HealingDashboard |
+| 3 — Visual | `VisualIntentChecker` | Element screenshot diff at assertions → HealingDashboard |
+
+Refer to [ARCHITECTURE-ADO.md § Three-Layer Self-Healing Architecture](ARCHITECTURE-ADO.md#three-layer-self-healing-architecture) for full strategy ordering, env-var tuning (`HEAL_STRATEGY_ORDER`, `LOCATOR_TIMEOUT`, `LOCATOR_HEAL_ATTEMPTS`, etc.), and HealingDashboard write-back behaviour.
+
+---
+
+## Run Tests
+
+```bash
+ENABLE_SELF_HEALING=true \
+HEALING_DASHBOARD_PORT=7890 \
+APP_BASE_URL=<your-app-base-url> \
+APP_EMAIL=<email> \
+APP_PASSWORD=<password> \
+cucumber-js --config=config/cucumber.js -p <feature_profile>
+```
+
+### Inspect healed locators (migrated projects only)
+
+```bash
+ENV=qa4 npm run healix:dashboard   # http://localhost:7890 — Confirm / Revert
+ENV=qa4 npm run healix:review      # http://localhost:7891 — read-only mirror
+cat self-heals/healed-locators.qa4.json | jq .
+tail self-heals/heal.log
+```
+
+Confirm on a healed entry rewrites the source `*.locators.ts` file's
+`selector:` field — future runs use it as the primary probe.
+
+---
+
+## 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)
+
+---
+
+## License
+
+MIT

package/README.md

@@ -136,6 +136,55 @@ qa-stlc scaffold --name my-qa-project
 npx @playwright/mcp@latest --port 8931
 ```
 
+### Migrating an existing Playwright project
+
+If you have an existing Playwright (with or without Cucumber) project and want
+to bring it onto the agent rails, use `stlc-migrate`:
+
+```bash
+# Preview without writing
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --dry-run
+
+# Full migration — every agent skill, .mcp.json, healer scaffold, agent docs
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration both
+
+# ADO-only or Jira-only
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration ado
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration jira
+
+# Refresh scaffold/skills on an existing migrated tree
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --conflict overwrite
+```
+
+The tool emits a complete agent-ready tree:
+
+| Layer | What lands |
+|---|---|
+| **Code** | Page objects + step files + locator files in `{selector, intent, stability}` format; every locator interaction routed through `LocatorHealer.*WithHealing`; non-BDD `.spec.*` files losslessly converted to one-scenario-per-test BDD |
+| **Healing infra** | 8-strategy `LocatorHealer` (attribute / type-hint / role / label / text / AI Vision), `LocatorRepository` with schema-versioned heal-only persist + per-env file suffix, `HealingDashboard` (read/write at 7890 + read-only mirror at `HEALIX_REVIEW_PORT`), `TimingHealer`, `VisualIntentChecker` |
+| **Agent assets** | `.mcp.json` (all 6 MCP servers + Playwright MCP), `.claude/skills/<name>/SKILL.md` per integration, `.github/copilot-instructions/<name>.md` flat copies, `AGENT-BEHAVIOR.md` + `ORCHESTRATION_RULES.md` at root + `.claude/` + `.github/` |
+| **Configs** | `cucumber.js` with `dotenv/config` as first `requireModule`, `package.json` with `dotenv` + `@types/*` companions, `tsconfig.json` aliases, `.env.example` documenting every healing knob |
+
+See `skills/migrate-framework/SKILL.md` for the full pipeline + environment variable reference.
+
+### Healing dashboard
+
+Once a migrated project has run any test that triggers healing, inspect the
+results via the dashboard:
+
+```bash
+ENV=qa4 npm run healix:dashboard     # full UI at http://localhost:7890
+ENV=qa4 npm run healix:review        # read-only mirror at http://localhost:7891
+```
+
+The dashboard shows each healed locator with its original selector, the
+specific selector that actually matched on the live page (introspected from
+the matched element — e.g. `#login-username`, not the generic search union),
+and **Confirm / Revert** buttons. **Confirm rewrites the original locator
+`.ts` file's `selector:` field** so the next run uses the verified selector
+as the primary probe — no healing chain required until the page changes
+again.
+
 ### Cost Tracking Activation
 
 **npm install** (`npm install -g @qa-gentic/stlc-agents`): Cost tracking is activated automatically after the Python servers are installed. No manual step required.

package/package.json

@@ -1,22 +1,29 @@
 {
   "name": "@qa-gentic/stlc-agents",
-  "version": "1.0.27",
-  "description": "QA STLC Agents — five MCP servers + skills for AI-powered test case, Gherkin, Playwright generation, and Helix-QA file writing against Azure DevOps and Jira Cloud. Full pipeline for both: fetch → test cases → Gherkin → Playwright → Helix-QA. Works with Claude Code, GitHub Copilot, Cursor, Windsurf.",
+  "version": "1.0.28",
+  "description": "QA STLC Agents — six MCP servers + skills for AI-powered test case, Gherkin, self-healing Playwright generation, Helix-QA file writing, and existing-framework migration against Azure DevOps and Jira Cloud. Includes an 8-strategy LocatorHealer with a live HealingDashboard (write-back-to-source) and a one-shot `stlc-migrate` CLI that converts an existing Playwright project into a fully agent-ready Helix-QA tree. Works with Claude Code, GitHub Copilot, Cursor, Windsurf.",
   "keywords": [
     "playwright",
+    "playwright-migration",
+    "framework-migration",
     "mcp",
+    "mcp-server",
     "azure-devops",
+    "jira",
     "gherkin",
     "bdd",
+    "cucumber",
     "qa",
     "test-automation",
+    "self-healing",
+    "healing-dashboard",
+    "locator-healer",
     "claude",
-    "copilot",
     "claude-code",
-    "mcp-server",
-    "self-healing",
+    "copilot",
     "helix",
     "scaffold",
+    "stlc-migrate",
     "cursor",
     "windsurf"
   ],
@@ -38,7 +45,12 @@
     "skills/",
     ".github/agents/",
     "README.md",
-    "ORCHESTRATION_RULES.md"
+    "ORCHESTRATION_RULES.md",
+    "AGENT-BEHAVIOR.md",
+    "ARCHITECTURE-ADO.md",
+    "ARCHITECTURE-JIRA.md",
+    "QUICKSTART-ADO.md",
+    "QUICKSTART-JIRA.md"
   ],
   "scripts": {
     "postinstall": "node ./bin/postinstall.js"

package/skills/migrate-framework/SKILL.md

@@ -0,0 +1,207 @@
+# Skill: migrate-framework
+
+Migrate an existing Playwright test framework into the Helix-QA layout so every
+QA STLC agent (qa-test-case-manager, qa-gherkin-generator, qa-playwright-generator,
+qa-helix-writer, qa-jira-manager) can operate against it. The migration ships
+self-healing locator infrastructure, an HTTP healing dashboard, agent skill
+files, an `.mcp.json`, and every other asset the agents expect.
+
+## When to use this skill
+
+Trigger on any of:
+- "migrate my Playwright tests"
+- "convert existing tests to Helix"
+- "migrate playwright+cucumber project"
+- "bring old tests into the agent framework"
+- "stlc-migrate", "qa-migration", "migrate_framework" tool names
+
+## Supported source frameworks
+
+| Framework | Detection |
+|-----------|-----------|
+| Plain Playwright JS | `playwright.config.js`, no `.feature` files |
+| Plain Playwright TS | `playwright.config.ts`, no `.feature` files |
+| Playwright + Cucumber JS | `playwright.config.js` + `.feature` files or `@cucumber/cucumber` in package.json |
+| Playwright + Cucumber TS | `playwright.config.ts` + `.feature` files or `@cucumber/cucumber` in package.json |
+
+## Step-by-step workflow
+
+### Step 1 — Confirm source and target directories
+
+Ask the user for:
+- **Source directory** — root of the existing Playwright project (must exist)
+- **Helix root** — root of the Helix-QA project to migrate into (must exist unless dry-run)
+- **Integration** (optional) — `ado`, `jira`, or `both` (default `both`). Controls which agent skills + MCP entries get installed.
+
+### Step 2 — Detect the framework
+
+```
+detect_framework(source_dir=<source>)
+```
+
+Report back:
+- `framework` — one of: `playwright-bdd-ts`, `playwright-bdd-js`, `playwright-ts`, `playwright-js`
+- `language` — `typescript` or `javascript`
+- `bdd` — whether BDD/Cucumber files were found
+- `file_counts` — number of `.ts`, `.js`, `.feature` files found
+
+### Step 3 — Preview the migration plan
+
+```
+preview_migration(source_dir=<source>, helix_root=<helix>)
+```
+
+Show the user:
+- Total mappable files and their roles
+- Any conflicts (files already existing in Helix)
+- Files with unknown/unrecognised roles that will be skipped
+
+Ask the user to confirm before proceeding if there are conflicts.
+
+### Step 4 — Run the migration
+
+```
+migrate_framework(
+  source_dir=<source>,
+  helix_root=<helix>,
+  conflict_strategy="interactive",   # "overwrite" | "skip" | "interactive"
+  integration="both",                # "ado" | "jira" | "both"
+  dry_run=false,
+)
+```
+
+The tool applies this pipeline to each file:
+
+| Step | What happens |
+|------|-------------|
+| **JS → TS** | `require(...)` → `import`, `module.exports` → `export default`, async return types added |
+| **Locator modernisation** | `[data-testid]` → `getByTestId`, `text=` → `getByText`, `[aria-label]` → `getByLabel`, `[placeholder]` → `getByPlaceholder`, `role=X[name=Y]` → `getByRole`. Complex XPath/CSS flagged with `// TODO`. **Multi-line string-concat selectors** (`"a" + "b"`) are registered as a single `{selector, intent, stability}` entry preserving the concatenation. |
+| **Healer injection** | EVERY locator interaction (regardless of caller shape) is routed through `_healer.clickWithHealing` / `_healer.fillWithHealing` / `_healer.assertVisibleWithHealing`. Covered patterns: raw `page.click/fill`, chained `page.locator(X).click()`, custom wrappers (`base.waitAndClick`, `base.waitAndFill`, `*ByTestId` variants), non-awaited calls inside `Promise.all([...])`, `currentFixture.page.*` receivers, aliased references (`this.Elements.foo`, `const E = fooLocators`), inline class-field locator dictionaries (`private MassInviteElements = { ... }`), and dynamic selectors (auto-wrapped with `dyn.<prefix>.<n>` keys). Arguments are extracted by **balanced-paren scan** so calls like `fill(X, String(visitorCount))` extract the full second arg. |
+| **Locator registration** | Every page-object constructor gets `Object.entries(xxxLocators).forEach(([k, v]) => { this._repo.register(\`xxxPage.${k}\`, ...); this._repo.register(k, ...); })` so the runtime store knows about every key. Registers under both **namespaced** and **bare** key conventions so legacy hand-written `_healer.<…>("usernameInput", …)` and freshly-emitted `_healer.<…>("loginPage.usernameInput", …)` both resolve. |
+| **Import fixing** | Relative imports remapped to the **mapper's authoritative target paths** (no more "predicted" alias names that don't match what was actually written). Source-project `@pages/scweb/locators` → `@locators/locators.locators` exactly as the mapper renamed it. |
+| **Spec → BDD** | See "Zero-inference guarantees" below. |
+| **Config merge** | `playwright.config` settings merged. `cucumber.js` is rewritten with `dotenv/config` injected as the FIRST `requireModule` entry — so `.env` is loaded before any TS file is compiled. `package.json` gets `dotenv` runtime dep, `@types/*` companions for known JS-only deps (fs-extra, lodash, glob, mkdirp, rimraf, uuid, js-yaml, jsonwebtoken, module-alias, cookie, express, cors, node-fetch, minimist, yargs, semver), and two new scripts: `healix:dashboard` and `healix:review`. |
+| **tsconfig merge** | Adds path aliases (`@pages`, `@steps`, `@features`, `@locators`, `@hooks`, `@helper`, `@utils`, `@config`). Does **not** fabricate `strict: true` / `strictNullChecks` — the source's strictness setting is preserved verbatim (introducing strictness the source didn't have would surface cascading errors on code that compiled fine before). |
+
+#### Zero-inference guarantees for spec → BDD
+
+The converter is intentionally **lossless** and **non-fabricating**:
+
+- **No generic step text.** Step text is always the literal `test()` name (prefixed with the file slug for cross-file uniqueness). The tool does NOT invent `"I run step #N"`, `"I prepare state #N"`, or `"I execute if block #N"` text.
+- **One step per test.** The full original body of each `test('name', body)` is placed inside a single step definition. No per-statement splitting; no Given/When/Then reclassification.
+- **Hooks become real Cucumber hooks.** `test.beforeEach`/`afterEach`/`beforeAll`/`afterAll` → real `Before`/`After`/`BeforeAll`/`AfterAll`. `test.skip`/`only`/`fixme`/`fail`/`slow` modifiers → `@skip`/`@only`/… tags on the scenario.
+- **Nothing is dropped.** Module-level helpers, suite-scope `let`/`const`/`var`, comments, and hook bodies are all preserved. `test.use(...)`/`test.step(...)` and other runner-only calls are commented out as `// MIGRATION TODO:` rather than silently removed.
+- **Source bugs surface, not papered over.** If the original source references a non-existent property (e.g. `GlobalVars.Api.Username` when the class only exposes `username`), the migrated step keeps the original reference. `tsc` will flag it; the tool does not "fix" what it cannot verify.
+- **Step text with `/`, `(`, `)`, `{`, `}`** is rendered as a RegExp step definition automatically so Cucumber Expression parsing doesn't reject the test name.
+
+### Step 5 — Scaffold & assets installed automatically
+
+In addition to file-by-file migration, the tool emits a complete agent-ready
+tree:
+
+| Asset | What it does |
+|---|---|
+| `src/utils/locators/LocatorHealer.ts` | 8-strategy healing chain: cached-healed → primary → **attribute** → **type-hint** → role → label → text → AI Vision. After each successful strategy, the matched element is introspected and the **specific stable selector** (data-testid > id > name > placeholder > aria-label > autocomplete > input[type]) is persisted — not the search union. Strategy order tunable via `HEAL_STRATEGY_ORDER` CSV. |
+| `src/utils/locators/LocatorRepository.ts` | Heal store: schema v1 envelope (`{_version, _writtenAt, entries}`), heal-only persist filter (baseline-only entries don't get written), debounced writes (500ms), singleton process exit hook, read-modify-write merge for multi-instance safety, ENV-suffixed file path (`healed-locators.qa4.json` when ENV=qa4), capped `healingHistory` (default 50, env-tunable). |
+| `src/utils/locators/TimingHealer.ts` / `VisualIntentChecker.ts` | Network-trace timing healer + visual-regression checker. |
+| `src/utils/locators/HealingDashboard.ts` | Two-server HTTP UI. Primary at `HEALING_DASHBOARD_PORT` (default 7890) has Healed-locators + Pending-suggestions tables with Confirm/Revert / Approve/Reject buttons. Read-only mirror at `HEALIX_REVIEW_PORT` (opt-in, default 0). Auto-discovers all sibling heal-store files in the directory (so `healix:dashboard` without an ENV picks up `*.qa4.json` automatically). **Confirm on a healed entry writes the healed selector back to the locator `.ts` file** so the next run uses it as the primary. |
+| `src/utils/locators/dashboard-server.ts` | Standalone launcher for the dashboard. Wired via `healix:dashboard` and `healix:review` npm scripts. |
+| `src/utils/locators/{ElementContextHelper, HealApplicator, LocatorRules, LocatorStrategy, healix-ci-apply, review-server}.ts` | Filled from `agent_helix_writer.tools.boilerplate.BOILERPLATE` — purely additive infrastructure that integrates with the enhanced LocatorHealer. |
+| `src/utils/helpers/{Logger, RetryHandler, WaitHelper}.ts` | Filled from BOILERPLATE — helpers the strategy layer depends on. |
+| `src/config/environment.ts` | Filled from BOILERPLATE — referenced by Logger. |
+| `src/locators/base.locators.ts` | Filled from BOILERPLATE — base locator file. |
+| `.claude/skills/<name>/SKILL.md` + `.github/copilot-instructions/<name>.md` | Per-integration skill files (ado / jira / both). |
+| `AGENT-BEHAVIOR.md` + `ORCHESTRATION_RULES.md` | Copied to project root, `.claude/`, and `.github/copilot-instructions/`. |
+| `.mcp.json` | Auto-generated entries for every agent + Playwright MCP, with absolute binary paths. |
+| `.env.example` | Documents every healing env var: `HEAL_STORE_PATH`, `HEAL_LOG_PATH`, `HEAL_LOG_DISABLED`, `ENABLE_LOCATOR_VERSIONING`, `HEAL_HISTORY_CAP`, `LOCATOR_TIMEOUT`, `LOCATOR_HEAL_ATTEMPTS`, `HEAL_STRATEGY_ORDER`, `HEALING_DASHBOARD_PORT`, `HEALIX_REVIEW_PORT`, `ENABLE_AI_HEALING`, `AI_HEALING_PROVIDER`, `AI_HEALING_API_KEY`, `ENV` / `HELIX_ENV`. |
+
+### Step 6 — Review the migration report
+
+The tool writes `MIGRATION-REPORT.md` to the Helix root. Report back to the user:
+- Number of files written / skipped / conflicted
+- TODO count (locators needing manual review)
+- Path to `MIGRATION-REPORT.md`
+
+### Step 7 — Post-migration steps (tell the user)
+
+After migration, the user should:
+
+1. `npm install` — picks up new deps (`dotenv`, `@types/fs-extra`, etc.).
+2. `npx tsc --noEmit` — should be clean (any remaining errors are source bugs the migration preserved verbatim per the zero-inference contract).
+3. Review `// TODO: convert to getByRole` comments in locator files (complex XPath/CSS the tool wouldn't auto-rewrite).
+4. Fill in `.env` — at minimum, set `HEADLESS=false` if you want a visible browser.
+5. Verify `inspect_helix_project` reports `framework_state: "present"` against the migrated tree.
+6. Run the existing test suite (e.g. `npm test`) — healing fires automatically on broken primary selectors and writes to `self-heals/healed-locators[.<env>].json`.
+7. Inspect heals visually:
+   - `npm run healix:dashboard` → http://localhost:7890 (full UI with Confirm / Revert)
+   - `npm run healix:review`    → http://localhost:7891 (read-only mirror)
+8. When ready, click **Confirm** on a heal — the migration rewrites the source locator file's `selector:` field with the verified healed value. Future runs use it as the primary; the healing chain only fires if the page changes again.
+
+## Helix-QA file layout
+
+| Source role | Helix target |
+|-------------|-------------|
+| Locators (`*Locators.ts`, `*selectors.ts`) | `src/locators/<kebab>.locators.ts` |
+| Page objects (`*Page.ts`, `*.page.ts`) | `src/pages/<kebab>.page.ts` |
+| Step definitions (`*.steps.ts`, `step_definitions/**`) | `src/test/steps/<kebab>.steps.ts` |
+| Feature files (`*.feature`) | `src/test/features/<kebab>.feature` |
+| Playwright config | `playwright.config.ts` (merged) |
+| Cucumber config | `config/cucumber.js` (merged, with `dotenv/config` injected) |
+| Heal-store JSON | `self-heals/healed-locators[.<env>].json` (heal-only) |
+| Heal audit log | `self-heals/heal.log` (tab-separated `timestamp / key / strategy / selector`) |
+
+## CLI usage (terminal)
+
+```bash
+# Preview migration without writing
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --dry-run
+
+# Full migration (interactive conflict handling, every agent reachable)
+stlc-migrate --source ./my-old-tests --helix ./helix-qa
+
+# ADO-only integration (no Jira skill / MCP entry)
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration ado
+
+# Jira-only
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration jira
+
+# Overwrite all existing files (refreshes scaffold + skill files)
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --conflict overwrite
+
+# JSON output for scripting
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --json
+
+# Makefile shortcut
+make migrate-preview SOURCE=./my-old-tests HELIX=./helix-qa
+```
+
+## Runtime environment variables
+
+Every knob has a sensible default. Override per-run in `.env` or via `cross-env` in npm scripts.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `HEAL_STORE_PATH` | `./self-heals/healed-locators.json` | Where the heal-store JSON is read/written. |
+| `HEAL_LOG_PATH` | sibling `heal.log` | Tab-separated audit log per heal. |
+| `HEAL_LOG_DISABLED` | `false` | Set `true` to skip the audit log. |
+| `ENV` / `HELIX_ENV` | unset | When set, auto-suffixes the heal-store path: `healed-locators.qa4.json`. |
+| `ENABLE_LOCATOR_VERSIONING` | `true` | When `false`, keeps only the latest heal entry (no `healingHistory[]` accumulation). |
+| `HEAL_HISTORY_CAP` | `50` | Max heals retained per locator. `0` = unlimited. |
+| `LOCATOR_TIMEOUT` | `3000` | Per-strategy attach-probe timeout (ms). |
+| `LOCATOR_HEAL_ATTEMPTS` | `0` (unlimited) | Bound on the total number of probes before AI Vision fallback. |
+| `HEAL_STRATEGY_ORDER` | `attribute,type-hint,role,label,text` | CSV — omit names to disable; reorder to prioritise. |
+| `HEALING_DASHBOARD_PORT` | `7890` | Dashboard server port. `0` to disable. |
+| `HEALIX_REVIEW_PORT` | `0` (disabled) | Read-only review server port (rejects POSTs with 403). |
+| `ENABLE_AI_HEALING` | `true` | When `false`, AI Vision strategy is skipped. |
+| `AI_HEALING_PROVIDER` | `anthropic` | One of `anthropic` / `copilot` / `claude-code`. |
+| `AI_HEALING_API_KEY` (or `ANTHROPIC_API_KEY`) | unset | Required when AI Vision is enabled and primary fails. |
+
+## Key rules
+
+1. **Always run `preview_migration` first** — review the plan and conflicts before writing.
+2. **Never infer conflict decisions** — ask the user whether to overwrite, skip, or abort.
+3. **TODO comments are not errors** — complex locators flagged with `// TODO` are valid output; inform the user they need manual review.
+4. **Feature files are copied as-is** — no Gherkin transformation is applied to `.feature` files during migration (the spec→BDD conversion is only for non-BDD `.spec.*` sources).
+5. **BOILERPLATE fill is allowlisted** — `_BOILERPLATE_FILL_ALLOWLIST` in `_migrate.py` lists exactly which boilerplate entries are dropped in (the rest are held back because they assume APIs the enhanced scaffold doesn't expose).
+6. **Config merge is non-destructive** — existing settings in Helix configs are never overwritten; only missing settings are added. `--conflict overwrite` refreshes `.mcp.json`, `.env.example`, generated scaffolds, and the cucumber config to pick up tool-side improvements.
+7. **Healing scaffold takes precedence over BOILERPLATE** — the enhanced `LocatorHealer.ts` / `LocatorRepository.ts` / `TimingHealer.ts` / `VisualIntentChecker.ts` / `HealingDashboard.ts` are written first by `_scaffold_locator_repository`; the BOILERPLATE versions of the same files are never written.