@qa-gentic/stlc-agents 1.0.27 → 1.0.29

package/src/stlc_agents/agent_migration/_migrate.py

@@ -0,0 +1,1398 @@
+"""
+Core migration pipeline — shared by both the MCP server and the CLI.
+
+Pipeline per file:
+  1. JS → TS conversion     (only when source is .js)
+  2. Locator modernisation  (locators, page objects, step defs)
+  3. Healer injection       (page objects and step defs)
+  4. Import path fixing     (all .ts files)
+
+Config files are handled separately via merge helpers.
+"""
+from __future__ import annotations
+import json
+import shutil
+import sys
+from pathlib import Path
+
+from .transformer.js_to_ts import convert_js_to_ts
+from .transformer.locator_moderniser import modernise_locators
+from .transformer.locator_registrar import transform_locator_file, collect_object_keys, fix_selector_accesses
+from .transformer.local_var_hoister import (
+    HoistAction,
+    hoist_inline_locators,
+    append_entries_to_locator_file,
+)
+from .transformer.healer_injector import inject_healers
+from .transformer.import_fixer import fix_imports
+from .transformer.spec_to_bdd import convert_spec_to_bdd
+from .transformer.js_to_ts import _fix_tobe_typo, _cast_intl_format_options  # type: ignore
+from .transformer.config_merger import (
+    merge_playwright_config,
+    merge_cucumber_config,
+    merge_package_json,
+    merge_tsconfig_json,
+)
+from .reporter import generate_report
+
+_TRANSFORM_ROLES = {"locator", "page_object", "step_def"}
+
+# Roles that are TypeScript/JavaScript code but don't need locator/healer transformation —
+# they just need JS→TS conversion (if .js) and import-path rewriting.
+_CODE_COPY_ROLES = {"helper", "hook", "fixture", "support", "api_client"}
+
+# Roles that are copied byte-for-byte (no source transformation).
+# "unknown" is the catch-all: any file the mapper didn't classify (README.md,
+# LICENSE, .gitignore, vrt-baselines, arbitrary docs) lands here and is
+# preserved at its original relative path so the migration never silently
+# drops content from the source project.
+_RAW_COPY_ROLES = {"docker", "env", "ci", "script", "unknown"}
+
+
+def run_migration(
+    source_dir: str,
+    helix_root: str,
+    file_mappings: list[dict],
+    conflict_strategy: str = "interactive",
+    framework: str = "playwright-bdd-ts",
+    integration: str = "both",
+) -> dict:
+    """
+    Execute the full migration for a list of file mappings.
+
+    conflict_strategy:
+        "overwrite"   — always replace existing Helix files
+        "skip"        — never touch existing Helix files
+        "interactive" — report conflicts in result; caller decides per file
+
+    integration:
+        "ado"   — install ADO skills (qa-test-case-manager + shared)
+        "jira"  — install Jira skills (qa-jira-manager + shared)
+        "both"  — install everything (default — every agent reachable)
+
+    Returns {
+        written:    list[dict],
+        skipped:    list[dict],
+        conflicts:  list[dict],
+        todo_count: int,
+        todos:      list[str],
+        report_path: str | None,
+    }
+    """
+    written:    list[dict] = []
+    skipped:    list[dict] = []
+    conflicts:  list[dict] = []
+    todos:      list[str]  = []
+    root = Path(helix_root)
+
+    # Authoritative lookup so import_fixer can rewrite imports against the
+    # mapper's real output paths instead of re-predicting them (which would
+    # drift apart after disambiguation, kebab tweaks, etc.). Keyed by the
+    # resolved absolute source path; value is the helix-relative target.
+    source_to_target: dict[str, str] = {
+        str(Path(m["source"]).resolve()): m["target"]
+        for m in file_mappings
+        if m.get("target")
+    }
+
+    # Accumulator for HoistActions emitted while transforming page_object /
+    # step_def files. Applied to locator files in a post-pass so all hoisted
+    # entries land in their target xxxLocators block.
+    hoist_buffer: dict[str, list[HoistAction]] = {}
+
+    # Pre-pass: scan every locator-source file so we know which keys are
+    # object-valued ({selector, intent, stability}) versus string-valued
+    # (display labels, URLs). The healer must not wrap references whose key
+    # is string-valued — `.selector` would not exist on the plain string.
+    object_keys_by_name: dict[str, set[str]] = {}
+    for mp in file_mappings:
+        if mp.get("role") != "locator":
+            continue
+        try:
+            src_content = Path(mp["source"]).read_text(encoding="utf-8")
+            # modernise_locators returns (content, changes, todo_count) —
+            # only the first matters here. transform_locator_file returns
+            # (content, changes). Use `*_` to absorb any future trailing
+            # values so a signature change can't silently re-break this.
+            modernised, *_ = modernise_locators(src_content)
+            transformed, *_ = transform_locator_file(modernised)
+            for name, keys in collect_object_keys(transformed).items():
+                object_keys_by_name.setdefault(name, set()).update(keys)
+        except Exception as exc:
+            # Surface the failure: a silent `pass` here was hiding a tuple
+            # unpacking bug for who knows how long, which left every
+            # consumer's `object_keys` map empty (so the healer wrapped
+            # everything indiscriminately, including string-valued labels).
+            import sys
+            print(f"warning: object_keys pre-pass failed for {mp['relative']}: {exc}", file=sys.stderr)
+
+    for mapping in file_mappings:
+        role = mapping["role"]
+
+        if role.startswith("config_"):
+            _process_config(mapping, source_dir, helix_root, written, skipped)
+            continue
+
+        source_path = Path(mapping["source"])
+        target_rel  = mapping["target"]
+        if not target_rel:
+            skipped.append({"source": mapping["relative"], "reason": f"no target for role={role}"})
+            continue
+
+        # Per-app `.env.<APP>` files are NOT raw-copied — their values are
+        # folded into the single `.env.example` at helix-qa root by the
+        # _write_root_env_example post-pass below. Skipping prevents stale
+        # per-app files from sticking around alongside the consolidated file.
+        if role == "env" and source_path.name.startswith(".env.") and source_path.name != ".env.example":
+            skipped.append({
+                "source": mapping["relative"],
+                "reason": "per-app .env folded into single .env.example",
+            })
+            continue
+
+        # ── Playwright spec → feature + steps split ─────────────────────────
+        # Non-BDD Playwright spec files are converted into a Gherkin .feature
+        # file plus a Cucumber .steps.ts file. The .steps.ts goes to the
+        # target_rel computed by the mapper; the .feature is derived from it.
+        if role == "playwright_spec":
+            try:
+                content = source_path.read_text(encoding="utf-8")
+                feature_content, steps_content, changes = convert_spec_to_bdd(
+                    content, Path(target_rel).stem.replace(".steps", ""),
+                )
+                if not steps_content:
+                    skipped.append({
+                        "source": mapping["relative"],
+                        "reason": "no test() or test.describe() blocks found",
+                    })
+                    continue
+                # Run import_fixer on the generated step file so imports of
+                # page_objects/helpers (preserved from the source's require())
+                # get rewritten to the new Helix locations.
+                steps_content, imp_changes = fix_imports(
+                    steps_content, mapping["source"], target_rel, source_dir,
+                    source_to_target=source_to_target,
+                )
+                # Apply the targeted JS→TS fixes that also matter inside step
+                # bodies (typo normalisation, Intl.* option casts). The other
+                # js_to_ts passes are skipped because they're aimed at class
+                # bodies, not free-standing step callbacks.
+                steps_content, tobe_changes = _fix_tobe_typo(steps_content)
+                steps_content, intl_changes2 = _cast_intl_format_options(steps_content)
+                changes.extend(tobe_changes)
+                changes.extend(intl_changes2)
+                # Steps file
+                steps_path = root / target_rel
+                steps_path.parent.mkdir(parents=True, exist_ok=True)
+                steps_path.write_text(steps_content, encoding="utf-8")
+                # Feature file — derive from steps target.
+                feature_rel = target_rel.replace("src/test/steps/", "src/test/features/", 1)
+                feature_rel = feature_rel.replace(".steps.ts", ".feature")
+                feature_path = root / feature_rel
+                feature_path.parent.mkdir(parents=True, exist_ok=True)
+                feature_path.write_text(feature_content, encoding="utf-8")
+                written.append({
+                    "source": mapping["relative"],
+                    "target": target_rel,
+                    "role":   "step_def",
+                    "change_count": len(changes) + len(imp_changes),
+                })
+                written.append({
+                    "source": mapping["relative"],
+                    "target": feature_rel,
+                    "role":   "feature",
+                    "change_count": len(changes),
+                })
+            except Exception as exc:
+                skipped.append({
+                    "source": mapping["relative"],
+                    "reason": f"spec→BDD conversion error: {exc}",
+                })
+            continue
+
+        # ── Raw-copy roles: Dockerfile, .env, CI yaml, shell scripts ────────
+        # Also raw-copy JSON data files under helper/ (test data, fixtures).
+        is_raw_copy = role in _RAW_COPY_ROLES or (
+            role in _CODE_COPY_ROLES and source_path.suffix == ".json"
+        )
+        if is_raw_copy:
+            try:
+                _copy_raw(source_path, root / target_rel)
+                written.append({
+                    "source": mapping["relative"],
+                    "target": target_rel,
+                    "role":   role,
+                    "change_count": 0,
+                })
+            except Exception as exc:
+                skipped.append({"source": mapping["relative"], "reason": f"raw-copy error: {exc}"})
+            continue
+
+        try:
+            content = source_path.read_text(encoding="utf-8")
+        except Exception as exc:
+            skipped.append({"source": mapping["relative"], "reason": f"read error: {exc}"})
+            continue
+
+        # ── Transformation pipeline ─────────────────────────────────────
+        change_count = 0
+        file_todos:  list[str] = []
+
+        # 1. JS → TS
+        if mapping.get("needs_js_to_ts"):
+            content, js_changes = convert_js_to_ts(content)
+            change_count += len(js_changes)
+
+        # 2. Locator modernisation
+        if role in _TRANSFORM_ROLES:
+            content, loc_changes, loc_todos = modernise_locators(content)
+            change_count += len(loc_changes)
+            for _ in range(loc_todos):
+                file_todos.append(
+                    f"`{target_rel}` — locator needs manual review (complex CSS/XPath kept as-is)"
+                )
+
+        # 2b. Locator registration — convert plain string values to { selector, intent, stability }
+        if role == "locator":
+            content, reg_changes = transform_locator_file(content)
+            change_count += len(reg_changes)
+
+        # 2c. Hoist inline-string locators from local variables into the
+        # centralised xxxLocators. Buffered; applied to locator files in a
+        # post-pass. Must run BEFORE healer injection so the rewritten RHS
+        # (xxxLocators.foo.selector) is visible to healer_injector's var_map.
+        if role in ("page_object", "step_def"):
+            content, hoist_actions, hoist_changes = hoist_inline_locators(content)
+            change_count += len(hoist_changes)
+            for action in hoist_actions:
+                hoist_buffer.setdefault(action.locator_object, []).append(action)
+                # Hoisted entries are by construction object-valued, so register
+                # them in object_keys_by_name immediately. Without this, the
+                # healer call below would not recognise them as wrappable.
+                object_keys_by_name.setdefault(action.locator_object, set()).add(action.entry_name)
+
+        # 3. Healer injection
+        if role in ("page_object", "step_def"):
+            content, heal_changes, heal_todos = inject_healers(
+                content, role, object_keys=object_keys_by_name,
+            )
+            change_count += len(heal_changes)
+            if heal_todos:
+                file_todos.append(
+                    f"`{target_rel}` — healer init needed (see inline TODO comment)"
+                )
+
+        # 4. Import path fixing (applies to all code roles, including helper/hook/fixture/support)
+        content, imp_changes = fix_imports(
+            content, mapping["source"], target_rel, source_dir,
+            source_to_target=source_to_target,
+        )
+        change_count += len(imp_changes)
+
+        todos.extend(file_todos)
+
+        # ── Conflict check ──────────────────────────────────────────────
+        target_path = root / target_rel
+
+        if target_path.exists():
+            if conflict_strategy == "skip":
+                skipped.append({
+                    "source": mapping["relative"],
+                    "reason": "target already exists (skipped per strategy)",
+                })
+                continue
+            elif conflict_strategy == "overwrite":
+                conflicts.append({"path": target_rel, "resolution": "overwritten"})
+            else:  # interactive
+                conflicts.append({
+                    "path":       target_rel,
+                    "source":     mapping["relative"],
+                    "resolution": "pending — awaiting user decision",
+                })
+                # In interactive mode we still write; MCP callers can re-invoke
+                # with conflict_strategy="skip" for specific files if desired.
+
+        # ── Write ──────────────────────────────────────────────────────
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+        target_path.write_text(content, encoding="utf-8")
+
+        written.append({
+            "source":       mapping["relative"],
+            "target":       target_rel,
+            "role":         role,
+            "change_count": change_count,
+        })
+
+    # ── Post-pass: ensure tsconfig.json exists ──────────────────────────────
+    # JS source projects (e.g. playwright-js) don't ship a tsconfig.json, but
+    # the migrated tree is always TypeScript — synthesise one so the user can
+    # `tsc` / `cucumber-js` against the migrated code without manual setup.
+    _ensure_tsconfig(root)
+
+    # ── Post-pass: flush buffered hoist actions into the centralised locator files ──
+    # During the per-file loop we rewrote local-var RHS to reference xxxLocators
+    # entries that don't exist yet. This post-pass appends those entries to the
+    # right xxxLocators block in the right .locators.ts file on disk.
+    _flush_hoist_buffer(root, hoist_buffer)
+
+    # ── Post-pass: fix locator .selector accesses in page objects / step defs ──
+    # Locator files are already written with { selector, intent, stability } format.
+    # Now read them all to collect which keys are objects, then update page objects.
+    _fix_selector_accesses_in_tree(root, written)
+
+    # ── Post-pass: emit single `.env.example` at helix-qa root ───────────────
+    # Folds any source per-app `.env.<APP>` files into KEY_<APP>=… entries so
+    # the framework runs from one consolidated env file.
+    _write_root_env_example(root, written, source_dir, conflict_strategy)
+
+    # ── Post-pass: install the single-source env loader ──────────────────────
+    # Replaces the migrated `environment.util.ts` with one that reads root .env
+    # and resolves APP-suffixed vars (DOMAIN_<APP> → DOMAIN) at runtime.
+    _patch_environment_util(root)
+
+    # ── Post-pass: scaffold the self-healing locator infrastructure ─────────
+    # All migrated page objects / step defs import from @utils/locators/* — they
+    # need LocatorHealer, LocatorRepository, TimingHealer, VisualIntentChecker
+    # and HealingDashboard to be present in the target tree. The scaffold
+    # honors the same conflict strategy as the main migration loop so users
+    # who pass --conflict overwrite get a fresh scaffold that picks up
+    # tool-side enhancements (new env-var wiring, new strategies, etc.).
+    _scaffold_locators(root, written, conflict_strategy)
+
+    # ── Scaffold pageFixture.ts when missing ────────────────────────────────
+    # Spec→BDD-generated step files import `fixture` from `@hooks/pageFixture`.
+    # When the source didn't carry its own hook (typical for non-BDD Playwright
+    # projects), drop in a minimal fixture so the generated steps resolve.
+    _scaffold_page_fixture(root)
+
+    # ── Scaffold globals.d.ts for browser-context identifiers ───────────────
+    # page.evaluate() callbacks run in the browser and may reference functions
+    # defined by the SUT (e.g. `toggleGridFiltersMenu()`). TypeScript can't
+    # see those — emit `declare const` shims so tsc doesn't flag them.
+    _scaffold_browser_globals(root)
+
+    # ── Fill in the full Helix-QA boilerplate ──────────────────────────────
+    # The qa-helix-writer / qa-playwright-generator agents expect a fully
+    # populated Helix-QA tree (base page, base locators, AI assistant
+    # helpers, retry/wait/logger utils, auth manager, templates, ...). The
+    # tool's own scaffold only emits the 6 core locator-infra files; the
+    # remaining ~25 files come from agent_helix_writer.boilerplate.BOILERPLATE,
+    # which is the authoritative source the agents themselves use when they
+    # bootstrap a fresh project. Fill in any file that the migration hasn't
+    # already produced (and never clobber the enhanced scaffold variants).
+    _fill_helix_boilerplate(root, written, conflict_strategy)
+
+    # ── Install agent skills + MCP config + governance docs ─────────────────
+    # The migration's whole point is to produce a tree the QA STLC agents
+    # (qa-test-case-manager, qa-gherkin-generator, qa-playwright-generator,
+    # qa-helix-writer, qa-jira-manager) can operate against. Drop in:
+    #   • .claude/skills/<name>/SKILL.md  — instructions consumed by Claude Code
+    #   • .mcp.json                       — MCP server registry (auto-discovered)
+    #   • AGENT-BEHAVIOR.md / ORCHESTRATION_RULES.md — governance documents
+    # Honors the same conflict strategy so re-migrations refresh stale files.
+    _install_agent_assets(root, written, integration, conflict_strategy)
+
+    # ── Report ─────────────────────────────────────────────────────────────
+    report_path: str | None = None
+    try:
+        report_path = generate_report(
+            helix_root=helix_root,
+            source_dir=source_dir,
+            framework=framework,
+            written=written,
+            skipped=skipped,
+            conflicts=conflicts,
+            todos=todos,
+        )
+    except Exception:
+        pass
+
+    return {
+        "written":     written,
+        "skipped":     skipped,
+        "conflicts":   conflicts,
+        "todo_count":  len(todos),
+        "todos":       todos,
+        "report_path": report_path,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Config helpers
+# ---------------------------------------------------------------------------
+
+def _process_config(
+    mapping: dict,
+    source_dir: str,
+    helix_root: str,
+    written: list[dict],
+    skipped: list[dict],
+) -> None:
+    role        = mapping["role"]
+    source_path = Path(mapping["source"])
+
+    try:
+        content = source_path.read_text(encoding="utf-8")
+    except Exception as exc:
+        skipped.append({"source": mapping["relative"], "reason": f"read error: {exc}"})
+        return
+
+    try:
+        if role == "config_playwright":
+            # The migrated tree is always cucumber-js BDD (runner = cucumber-js,
+            # not @playwright/test). The Playwright Test runner config is dead
+            # weight and confuses tsc, so skip emitting it.
+            skipped.append({
+                "source": mapping["relative"],
+                "reason": "playwright.config not needed in cucumber-js BDD output",
+            })
+            return
+        elif role == "config_cucumber":
+            result = merge_cucumber_config(content, helix_root)
+        elif role == "config_package":
+            result = merge_package_json(content, helix_root)
+        elif role == "config_tsconfig":
+            result = merge_tsconfig_json(content, helix_root)
+        else:
+            skipped.append({"source": mapping["relative"], "reason": f"config type '{role}' not handled"})
+            return
+
+        target = Path(helix_root) / result["target"]
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(result["content"], encoding="utf-8")
+
+        written.append({
+            "source":       mapping["relative"],
+            "target":       result["target"],
+            "role":         role,
+            "change_count": len(result.get("changes", [])),
+        })
+    except Exception as exc:
+        skipped.append({"source": mapping["relative"], "reason": f"config merge error: {exc}"})
+
+
+# ---------------------------------------------------------------------------
+# Raw-copy helper (Docker, .env, CI yaml, scripts)
+# ---------------------------------------------------------------------------
+
+def _copy_raw(source: Path, target: Path) -> None:
+    """Byte-for-byte copy preserving file mode (e.g. executable bit for .sh)."""
+    import shutil
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(source, target)
+
+
+# ---------------------------------------------------------------------------
+# Project-root .env.example template
+# ---------------------------------------------------------------------------
+
+_ENV_EXAMPLE_HEADER = """\
+# ──────────────────────────────────────────────────────────────────────────────
+# Helix-QA — runtime configuration (single source of truth)
+#
+# Copy this file to `.env` and fill in the values you need.
+# Variables prefixed with the active APP (e.g. DOMAIN_AMPLIFY) are resolved to
+# their canonical names (DOMAIN) automatically by environment.util.ts based on
+# the APP env var supplied by the npm script.
+# Lines starting with # are comments — do NOT put inline comments after values.
+# ──────────────────────────────────────────────────────────────────────────────
+"""
+
+_ENV_EXAMPLE_TAIL = """\
+
+# ── Azure Key Vault (test data + secret resolution) ──────────────────────────
+# Required by `currentFixture.azureKeyVault.getSecrets(...)` calls in helpers.
+# In CI, these are typically set by the npm scripts via cross-env. Locally:
+# AZURE_TENANT_ID=
+# AZURE_CLIENT_ID=
+# AZURE_CLIENT_SECRET=
+
+
+# ── Self-healing AI vision (strategy 6 of LocatorHealer) ─────────────────────
+#
+# ENABLE_AI_HEALING
+#   true  (default) — strategy 6 is active; calls the provider below on failure
+#   false           — strategy 6 is skipped entirely; strategies 7 & 8
+#                     (CDPSession AX tree + bounding box) still run
+#
+# AI_HEALING_PROVIDER
+#   anthropic   (default) — direct Anthropic API; requires AI_HEALING_API_KEY
+#   copilot               — GitHub Copilot chat completions; requires GITHUB_TOKEN
+#   claude-code           — Claude Code local proxy; requires ANTHROPIC_API_KEY
+ENABLE_AI_HEALING=true
+AI_HEALING_PROVIDER=anthropic
+
+# Required when AI_HEALING_PROVIDER=anthropic
+# AI_HEALING_API_KEY=sk-ant-...
+
+# Required when AI_HEALING_PROVIDER=copilot
+# GITHUB_TOKEN=ghp_...
+
+# Required when AI_HEALING_PROVIDER=claude-code
+# (also set automatically inside a `claude` CLI session — no manual key needed)
+# ANTHROPIC_API_KEY=sk-ant-...
+
+
+# ── Healing Dashboard ────────────────────────────────────────────────────────
+# Set HEALING_DASHBOARD_PORT=0 to disable the HTTP dashboard in CI pipelines.
+# HEALIX_REVIEW_PORT, when set, starts a second READ-ONLY HTTP server that
+# mirrors the dashboard's GET endpoints but rejects POST. Use it for QA leads
+# / managers / external dashboards that need to inspect heals without write
+# access. Off by default (0 = disabled).
+# HEALING_DASHBOARD_PORT=7890
+# HEALIX_REVIEW_PORT=7891
+
+
+# ── LocatorRepository (heal store) ───────────────────────────────────────────
+# HEAL_STORE_PATH        Path to the heal-store JSON. The LocatorRepository
+#                        reads it on startup and writes (debounced) on every
+#                        successful heal. Default: ./self-heals/healed-locators.json
+# HEAL_LOG_PATH          One-line-per-heal audit log (tab-separated:
+#                        timestamp / key / strategy / selector). Defaults to
+#                        ./self-heals/heal.log next to the heal store.
+# HEAL_LOG_DISABLED      Set to "true" to skip the audit log entirely.
+# ENV / HELIX_ENV        When either is set, the heal store path is auto-
+#                        suffixed with the env slug — `healed-locators.json`
+#                        → `healed-locators.qa4.json`. Stops parallel runs
+#                        against different test envs from trampling each
+#                        other's healed selectors.
+# ENABLE_LOCATOR_VERSIONING  "true" (default) keeps the full healingHistory[]
+#                            per locator. "false" keeps only the latest heal
+#                            entry (smaller file).
+# HEAL_HISTORY_CAP       Cap on healingHistory length when versioning is on
+#                        (default 50; set to 0 for unlimited).
+# HEAL_STORE_PATH=./self-heals/healed-locators.json
+# HEAL_LOG_PATH=./self-heals/heal.log
+# ENABLE_LOCATOR_VERSIONING=true
+# HEAL_HISTORY_CAP=50
+
+
+# ── LocatorHealer chain tuning ───────────────────────────────────────────────
+# LOCATOR_TIMEOUT        Per-strategy attach-probe timeout (ms). Overrides
+#                        the default 3000ms. Higher values give slow pages
+#                        more headroom; lower values fail faster.
+# LOCATOR_HEAL_ATTEMPTS  Max probes the resolver runs across the chain
+#                        before falling through to AI Vision. 0 = unlimited
+#                        (default, original behaviour).
+# HEAL_STRATEGY_ORDER    CSV of strategy names to run, in order. Valid names:
+#                          attribute, type-hint, role, label, text
+#                        Default order is the same five strategies left-to-
+#                        right. Omit a name to disable it, or reorder to
+#                        prioritise a strategy your app favours.
+# LOCATOR_TIMEOUT=3000
+# LOCATOR_HEAL_ATTEMPTS=0
+# HEAL_STRATEGY_ORDER=attribute,type-hint,role,label,text
+
+
+# ── Visual Regression Testing ────────────────────────────────────────────────
+# VRT_MODE              baseline | test      — overridden by `npm run vrt:*`
+# VRT_SPRINT            sprint identifier appended to baseline filenames
+# VRT_THRESHOLD         pixelmatch threshold (0.0–1.0, default 0.1)
+# VRT_FAILURE_THRESHOLD percentage of diff pixels above which a test fails
+# VRT_STABILISATION_DELAY  ms to wait before screenshot (default 500)
+# VRT_MODE=test
+# VRT_SPRINT=
+# VRT_THRESHOLD=0.1
+# VRT_FAILURE_THRESHOLD=1.0
+# VRT_STABILISATION_DELAY=500
+
+
+# ── Browser / runtime flags ──────────────────────────────────────────────────
+# Usually set by the npm script via cross-env. These are fallbacks for ad-hoc runs.
+# APP=amplify              # amplify | parishsoft
+# ENV=dev1                 # dev1 | test1 | stg | prod | localhost
+# BROWSER=chrome           # chrome | firefox | webkit | edge
+# DOCKER=false
+# CI=false
+"""
+
+# Single-source-of-truth env.util.ts template. The migration tool always
+# replaces the migrated copy with this so the loader semantics match the
+# generated .env.example.
+_ENV_UTIL_TEMPLATE = '''\
+import * as dotenv from "dotenv";
+import * as path from "path";
+
+/**
+ * Single source of truth: project-root `.env`.
+ *
+ * Per-app values live in the same file with `_<APP>` suffixes
+ * (e.g. DOMAIN_AMPLIFY=..., DOMAIN_PARISHSOFT=...). After loading, the
+ * APP-suffixed variant for the active app is resolved into its canonical
+ * unsuffixed name (DOMAIN, HEADLESS, ...) so existing helpers keep working.
+ *
+ * Cross-env / shell-exported values are NEVER overridden — they win over
+ * the .env file in all cases.
+ */
+const _APP_SCOPED_VARS = ["DOMAIN", "HEADLESS"] as const;
+
+export const getEnvFile = (): void => {
+  dotenv.config({ path: path.resolve(process.cwd(), ".env"), override: false });
+
+  if (!process.env.ENV) {
+    console.error("NO ENV PASSED!");
+  }
+
+  const app = (process.env.APP || "amplify").toUpperCase();
+  for (const key of _APP_SCOPED_VARS) {
+    const scoped = `${key}_${app}`;
+    if (process.env[scoped] !== undefined && !process.env[key]) {
+      process.env[key] = process.env[scoped];
+    }
+  }
+};
+'''
+
+
+def _patch_environment_util(root: Path) -> None:
+    """
+    Replace `src/helper/environment/environment.util.ts` with the
+    single-source-of-truth loader template.
+
+    Idempotent: skips files already matching the template.
+    """
+    target = root / "src" / "helper" / "environment" / "environment.util.ts"
+    if not target.exists():
+        return
+    try:
+        existing = target.read_text(encoding="utf-8")
+    except Exception:
+        return
+    if existing == _ENV_UTIL_TEMPLATE:
+        return
+    target.write_text(_ENV_UTIL_TEMPLATE, encoding="utf-8")
+
+
+def _harvest_per_app_env(source_dir: str) -> list[tuple[str, dict[str, str]]]:
+    """
+    Find any `.env.<APP>` files in the source tree and return their values as
+    [(app, {KEY: VALUE, ...}), ...]. App is upper-cased.
+    Used to fold legacy per-app env into the single-file .env.example.
+    """
+    src = Path(source_dir)
+    if not src.exists():
+        return []
+    results: list[tuple[str, dict[str, str]]] = []
+    for p in src.rglob(".env.*"):
+        if not p.is_file():
+            continue
+        app = p.name[len(".env."):]
+        if not app or app == "example":
+            continue
+        try:
+            text = p.read_text(encoding="utf-8")
+        except Exception:
+            continue
+        kv: dict[str, str] = {}
+        for line in text.splitlines():
+            stripped = line.strip()
+            if not stripped or stripped.startswith("#") or "=" not in stripped:
+                continue
+            k, _, v = stripped.partition("=")
+            kv[k.strip()] = v.strip()
+        if kv:
+            results.append((app.upper(), kv))
+    return results
+
+
+def _scaffold_locators(
+    root: Path,
+    written: list[dict],
+    conflict_strategy: str = "interactive",
+) -> None:
+    """
+    Emit the LocatorHealer / LocatorRepository / TimingHealer / VisualIntentChecker
+    / HealingDashboard scaffolds into src/utils/locators/.
+
+    All migrated page objects + step defs reference these modules — without the
+    scaffold, the project fails to compile with TS2307 "Cannot find module
+    '@utils/locators/...'".
+
+    Conflict handling:
+      • "overwrite"   — replace every scaffold file with the freshly generated
+                        version. Lets users pick up generator improvements
+                        (new env-var wiring, expanded strategy chain, etc.).
+      • "skip"        — only write scaffold files that are missing.
+      • "interactive" — same as "skip" but appended to the conflicts list so
+                        the caller can decide per-file.
+
+    Defaults are conservative: AI vision + timing healing + visual checker all on,
+    repository persisted under ./self-heals/healed-locators.json, dashboard on port 7890.
+    """
+    try:
+        from stlc_agents.agent_playwright_generator.server import _scaffold_locator_repository
+    except Exception:
+        return
+
+    try:
+        result = _scaffold_locator_repository(
+            output_dir="src/utils/locators",
+            enable_ai_vision=True,
+            repository_path="./self-heals/healed-locators.json",
+            dashboard_port=7890,
+            enable_timing_healing=True,
+            enable_visual_regression=True,
+        )
+    except Exception:
+        return
+
+    for rel_path, body in result.get("files", {}).items():
+        target = root / rel_path
+        already_exists = target.exists()
+        if already_exists and conflict_strategy != "overwrite":
+            # Skip (matches the historical "missing-only" behaviour). The
+            # caller stays in charge of when to refresh the scaffold.
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(body, encoding="utf-8")
+        written.append({
+            "source":       "(scaffold)",
+            "target":       rel_path,
+            "role":         "scaffold",
+            "change_count": 0,
+        })
+
+
+def _write_root_env_example(
+    root: Path,
+    written: list[dict],
+    source_dir: str | None = None,
+    conflict_strategy: str = "interactive",
+) -> None:
+    """
+    Emit a single `.env.example` at the helix-qa root.
+
+    If the source project has per-app `.env.<APP>` files, their values are
+    folded into the template as `KEY_<APP>` entries — preserving the existing
+    project's app-specific config in the single new file.
+
+    Conflict handling matches the main migration loop:
+      • "overwrite"   — refresh the file so users pick up new template keys
+                        (e.g. new healing env vars).
+      • else          — skip when the file already exists.
+    """
+    target = root / ".env.example"
+    if target.exists() and conflict_strategy != "overwrite":
+        return
+
+    per_app_section = ""
+    if source_dir:
+        harvested = _harvest_per_app_env(source_dir)
+        if harvested:
+            # Collect every key seen across all apps so we can group nicely.
+            apps_sorted = sorted({app for app, _ in harvested})
+            keys_sorted: list[str] = []
+            seen: set[str] = set()
+            for _, kv in harvested:
+                for k in kv:
+                    if k not in seen:
+                        keys_sorted.append(k)
+                        seen.add(k)
+
+            lines = ["# ── Per-app overrides ────────────────────────────────────────────────────────",
+                     "# Resolved to the canonical name (DOMAIN, HEADLESS, ...) by environment.util.ts",
+                     "# based on the active APP. Each row is grouped by the original variable name.",
+                     ""]
+            for k in keys_sorted:
+                for app in apps_sorted:
+                    val = dict(harvested).get(app, {}).get(k)
+                    if val is not None:
+                        lines.append(f"{k}_{app}={val}")
+                lines.append("")
+            per_app_section = "\n".join(lines).rstrip() + "\n\n"
+
+    body = _ENV_EXAMPLE_HEADER + "\n" + per_app_section + _ENV_EXAMPLE_TAIL
+    target.write_text(body, encoding="utf-8")
+    written.append({
+        "source":       "(generated)",
+        "target":       ".env.example",
+        "role":         "env",
+        "change_count": 0,
+    })
+
+
+# ---------------------------------------------------------------------------
+# Post-pass: fix locator .selector accesses
+# ---------------------------------------------------------------------------
+
+def _scaffold_browser_globals(root: Path) -> None:
+    """
+    Walk every migrated .ts file, find `page.evaluate(...)` callbacks, and
+    collect any bare identifier function calls inside them. These reference
+    browser-context functions defined by the SUT — TypeScript can't see them
+    without ambient declarations. Emit `src/types/browser-globals.d.ts` with
+    `declare const <name>: any;` for each name.
+
+    Idempotent: rewrites the file each run with the union of discovered names.
+    """
+    import re as _re
+
+    # Recurse over .ts files under the migrated tree (skip node_modules etc.).
+    skip_dirs = {"node_modules", "dist", "build", ".git", "test-results"}
+    files: list[Path] = []
+    for ts_file in root.rglob("*.ts"):
+        if any(s in ts_file.parts for s in skip_dirs):
+            continue
+        files.append(ts_file)
+    if not files:
+        return
+
+    # Always include Playwright Test runner fixtures that the converted steps
+    # may reference (request, testInfo) — there's no clean Cucumber equivalent
+    # to inject them, but declaring them as `any` makes tsc happy and the user
+    # can wire them through later.
+    seed_names: set[str] = {"request", "testInfo"}
+
+    # Collect names called as functions inside page.evaluate callbacks. We use
+    # a balanced-paren scan to extract the callback text, then look for bare
+    # `<ident>(` calls in it.
+    evaluate_open_re = _re.compile(r"\.evaluate\s*\(")
+    call_re          = _re.compile(r"\b([A-Za-z_$][\w$]*)\s*\(")
+    builtin_blacklist = {
+        "if", "for", "while", "return", "switch", "case", "throw", "new",
+        "typeof", "instanceof", "delete", "void", "await", "async", "function",
+        "Array", "Object", "Math", "JSON", "Promise", "Date", "Number", "String",
+        "Boolean", "RegExp", "Error", "Map", "Set", "Symbol", "console",
+        "window", "document", "globalThis", "parseInt", "parseFloat",
+        "isNaN", "isFinite", "encodeURIComponent", "decodeURIComponent",
+        "setTimeout", "setInterval", "clearTimeout", "clearInterval",
+        "fetch", "btoa", "atob", "alert", "confirm", "prompt",
+        "Array", "Object", "Boolean", "Number", "String", "Symbol",
+        "Reflect", "Proxy", "WeakMap", "WeakSet", "DataView",
+        "Int8Array", "Uint8Array", "Float32Array", "Float64Array",
+    }
+
+    names: set[str] = set(seed_names)
+    for f in files:
+        try:
+            txt = f.read_text(encoding="utf-8")
+        except Exception:
+            continue
+        # Walk each .evaluate( call; extract its callback body via paren-counting.
+        for m in evaluate_open_re.finditer(txt):
+            paren_open = m.end() - 1
+            depth = 1
+            i = paren_open + 1
+            in_str: str | None = None
+            n = len(txt)
+            while i < n and depth > 0:
+                c = txt[i]
+                if in_str:
+                    if c == "\\":
+                        i += 2; continue
+                    if c == in_str:
+                        in_str = None
+                    i += 1; continue
+                if c in ("'", '"', "`"):
+                    in_str = c
+                    i += 1; continue
+                if c == "(":
+                    depth += 1
+                elif c == ")":
+                    depth -= 1
+                i += 1
+            if depth != 0:
+                continue
+            callback = txt[paren_open + 1 : i - 1]
+            for cm in call_re.finditer(callback):
+                name = cm.group(1)
+                if name in builtin_blacklist:
+                    continue
+                # Skip names that are clearly local: declared with `function`,
+                # `let`, `const`, `var` immediately preceding them, OR named
+                # exports / class member calls (`.foo()`).
+                start = cm.start()
+                # Skip member-access calls — `foo.bar(`.
+                if start > 0 and callback[start - 1] == ".":
+                    continue
+                names.add(name)
+
+    if not names:
+        return
+
+    types_dir = root / "src" / "types"
+    types_dir.mkdir(parents=True, exist_ok=True)
+    out_path = types_dir / "browser-globals.d.ts"
+    body = "// Auto-generated by stlc-migrate.\n"
+    body += "// Ambient declarations for identifiers referenced inside\n"
+    body += "// page.evaluate(...) callbacks. These functions live in the\n"
+    body += "// browser context (defined by the SUT), not the Node test code,\n"
+    body += "// so TypeScript can't see them — declare them as `any` shims.\n"
+    body += "//\n"
+    body += "// Safe to edit: replace `any` with real signatures, or remove\n"
+    body += "// entries whose underlying call sites have been rewritten.\n\n"
+    for name in sorted(names):
+        body += f"declare const {name}: any;\n"
+    out_path.write_text(body, encoding="utf-8")
+
+
+def _scaffold_page_fixture(root: Path) -> None:
+    """
+    Drop a minimal `src/hooks/pageFixture.ts` (and matching Before/After hooks
+    in `src/hooks/hooks.ts`) when neither already exists. Generated step files
+    import `fixture` from `@hooks/pageFixture`; without this scaffold those
+    imports fail to resolve.
+
+    Idempotent: skips both files if they already exist.
+    """
+    hooks_dir = root / "src" / "hooks"
+    fixture_path = hooks_dir / "pageFixture.ts"
+    hooks_path   = hooks_dir / "hooks.ts"
+    if fixture_path.exists() and hooks_path.exists():
+        return
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    if not fixture_path.exists():
+        fixture_path.write_text(
+            'import { Page, Browser, BrowserContext } from "@playwright/test";\n'
+            "\n"
+            "export interface PageFixture {\n"
+            "  page: Page;\n"
+            "  browser?: Browser;\n"
+            "  context?: BrowserContext;\n"
+            "  logger?: { info: (m: string) => void; error: (m: string) => void };\n"
+            "}\n"
+            "\n"
+            "let _current: PageFixture | undefined;\n"
+            "\n"
+            "export function setFixture(f: PageFixture): void {\n"
+            "  _current = f;\n"
+            "}\n"
+            "\n"
+            "export function fixture(): PageFixture {\n"
+            '  if (!_current) throw new Error("PageFixture not initialised — Before hook must call setFixture(...)");\n'
+            "  return _current;\n"
+            "}\n",
+            encoding="utf-8",
+        )
+    if not hooks_path.exists():
+        hooks_path.write_text(
+            'import { Before, After, BeforeAll, AfterAll } from "@cucumber/cucumber";\n'
+            'import { chromium, Browser, Page } from "@playwright/test";\n'
+            'import { setFixture } from "./pageFixture";\n'
+            "\n"
+            "let browser: Browser;\n"
+            "let page:    Page;\n"
+            "\n"
+            "BeforeAll(async () => {\n"
+            "  browser = await chromium.launch({ headless: process.env.HEADLESS !== 'false' });\n"
+            "});\n"
+            "\n"
+            "Before(async function () {\n"
+            "  const context = await browser.newContext();\n"
+            "  page = await context.newPage();\n"
+            "  setFixture({ page, browser, context });\n"
+            "});\n"
+            "\n"
+            "After(async function () {\n"
+            "  await page.context().close();\n"
+            "});\n"
+            "\n"
+            "AfterAll(async () => {\n"
+            "  await browser.close();\n"
+            "});\n",
+            encoding="utf-8",
+        )
+
+
+def _ensure_tsconfig(root: Path) -> None:
+    """
+    If the migrated tree has no tsconfig.json (e.g. when the source was a
+    pure-JS Playwright project), write a minimal one that wires the same
+    Helix path aliases used elsewhere in the migrator. Idempotent: no-op
+    when a tsconfig already exists.
+    """
+    target = root / "tsconfig.json"
+    if target.exists():
+        return
+    cfg = {
+        "compilerOptions": {
+            "target":              "ES2021",
+            "module":              "commonjs",
+            "lib":                 ["dom", "es2021"],
+            "esModuleInterop":     True,
+            "resolveJsonModule":   True,
+            "skipLibCheck":        True,
+            # Pragmatic defaults for a synthesised tsconfig — most source
+            # projects we migrate are JS-flavoured Playwright/cucumber repos
+            # that wouldn't survive `strict: true`. The user can tighten any
+            # of these once they've added explicit types.
+            "strict":              False,
+            "noImplicitAny":       False,
+            "strictNullChecks":    False,
+            "allowJs":             True,
+            "checkJs":             False,
+            "baseUrl":             "src",
+            "paths": {
+                "@pages/*":    ["pages/*"],
+                "@steps/*":    ["test/steps/*"],
+                "@features/*": ["test/features/*"],
+                "@locators/*": ["locators/*"],
+                "@config/*":   ["config/*"],
+                "@utils/*":    ["utils/*"],
+                "@helper/*":   ["helper/*"],
+                "@hooks/*":    ["hooks/*"],
+            },
+        },
+        # The migrated tree may have raw-copied helpers/page_objects/scripts
+        # at the project root (not under src/), so use a broad include with an
+        # explicit exclude list rather than the default `["src"]`.
+        "include": ["**/*.ts", "**/*.js"],
+        "exclude": ["node_modules", "dist", "build", "test-results"],
+        "ts-node": {
+            "transpileOnly": True,
+            "require": ["tsconfig-paths/register"],
+        },
+    }
+    import json as _json
+    target.write_text(_json.dumps(cfg, indent=2) + "\n", encoding="utf-8")
+
+
+def _flush_hoist_buffer(root: Path, hoist_buffer: dict[str, list[HoistAction]]) -> None:
+    """
+    Append buffered HoistActions to the .locators.ts file(s) on disk that
+    contain the matching xxxLocators block.
+
+    Strategy: walk every .locators.ts under <root>/src/locators/, look for
+    `export const xxxLocators = {` blocks, and pass through any actions
+    whose `locator_object` matches.
+    """
+    if not hoist_buffer:
+        return
+
+    locator_dir = root / "src" / "locators"
+    if not locator_dir.exists():
+        return
+
+    for locator_path in locator_dir.glob("*.ts"):
+        try:
+            content = locator_path.read_text(encoding="utf-8")
+        except Exception:
+            continue
+        # Skip files that don't define any of our target xxxLocators.
+        relevant = {
+            name: actions
+            for name, actions in hoist_buffer.items()
+            if f"export const {name}" in content
+        }
+        if not relevant:
+            continue
+        new_content, _changes = append_entries_to_locator_file(content, relevant)
+        if new_content != content:
+            try:
+                locator_path.write_text(new_content, encoding="utf-8")
+            except Exception:
+                pass
+
+
+def _fix_selector_accesses_in_tree(root: Path, written: list[dict]) -> None:
+    """
+    After all files are written, collect structured keys from locator files and
+    rewrite page_object / step_def files so that `locatorGroup.key` becomes
+    `locatorGroup.key.selector` wherever the key is now a { selector, intent, stability } object.
+    """
+    # Collect object keys from all written locator files
+    object_keys_by_name: dict[str, set[str]] = {}
+    for entry in written:
+        if entry.get("role") != "locator":
+            continue
+        locator_path = root / entry["target"]
+        try:
+            lc = locator_path.read_text(encoding="utf-8")
+            object_keys_by_name.update(collect_object_keys(lc))
+        except Exception:
+            pass
+
+    if not object_keys_by_name:
+        return
+
+    # Apply fixes to every TS/JS code role that may reference locators
+    _FIXABLE_ROLES = {"page_object", "step_def", "helper", "hook", "fixture", "support", "api_client"}
+    for entry in written:
+        if entry.get("role") not in _FIXABLE_ROLES:
+            continue
+        target_path = root / entry["target"]
+        try:
+            content = target_path.read_text(encoding="utf-8")
+            new_content, changes = fix_selector_accesses(content, object_keys_by_name)
+            if changes:
+                target_path.write_text(new_content, encoding="utf-8")
+                entry["change_count"] = entry.get("change_count", 0) + len(changes)
+        except Exception:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Fill missing files from agent_helix_writer's BOILERPLATE
+# ---------------------------------------------------------------------------
+
+# Allow-list of BOILERPLATE entries that drop cleanly into a migrated tree
+# without depending on APIs the user's existing source code may not expose.
+# Everything else is held back because:
+#
+#   • `src/pages/BasePage.ts` / `src/templates/_TemplatePage.ts` — assume a
+#     `fixture.locatorRepository` property and a 3-arg LocatorHealer
+#     constructor that the enhanced scaffold doesn't expose.
+#   • `src/utils/locators/index.ts` / `PlaywrightHealerLogger.ts` /
+#     `LocatorManager.ts` — re-export `HealerLogger` / `HealEvent` symbols
+#     that exist only in the BOILERPLATE scaffold variant, not in the
+#     enhanced one written by `_scaffold_locator_repository`.
+#   • `src/utils/ai-assistant/*`, `src/utils/storage-state/*`,
+#     `src/utils/helpers/*`, `src/config/*` — depend on the `@config/*`
+#     tsconfig path mapping pointing at `src/config`, but most existing
+#     migrated trees have `@config/*` pointing at `../config` (root-level).
+#     Filling them in would surface a wall of TS2307 module-not-found
+#     errors instead of "all features working".
+#
+# Files held back are listed in MIGRATION-REPORT.md so the operator knows
+# they're available and what adaptation is needed before enabling them.
+_BOILERPLATE_FILL_ALLOWLIST = frozenset({
+    # Base locator file referenced by generated page objects from
+    # qa-playwright-generator. Pure addition; doesn't conflict.
+    "src/locators/base.locators.ts",
+    # Healing-infrastructure layer the agents reference but the enhanced
+    # scaffold doesn't replace — pure additions, each independently
+    # compilable against the enhanced LocatorHealer / LocatorRepository.
+    "src/utils/locators/ElementContextHelper.ts",
+    "src/utils/locators/HealApplicator.ts",
+    "src/utils/locators/LocatorRules.ts",
+    "src/utils/locators/LocatorStrategy.ts",
+    "src/utils/locators/healix-ci-apply.ts",
+    "src/utils/locators/review-server.ts",
+    # Helpers the locator-strategy layer depends on. Logger imports the
+    # config module via a *relative* path, so we ship environment.ts in
+    # the same drop — without depending on any `@config/*` tsconfig alias.
+    "src/config/environment.ts",
+    "src/utils/helpers/Logger.ts",
+    "src/utils/helpers/RetryHandler.ts",
+    "src/utils/helpers/WaitHelper.ts",
+})
+
+
+def _fill_helix_boilerplate(
+    root: Path,
+    written: list[dict],
+    conflict_strategy: str,
+) -> None:
+    """
+    Drop in every file the qa-helix-writer / qa-playwright-generator agents
+    expect a fully-populated Helix-QA tree to contain — base classes,
+    AI-assistant helpers, locator strategy primitives, auth setup, retry /
+    wait / logger utilities, templates, example specs.
+
+    Source of truth: `agent_helix_writer.tools.boilerplate.BOILERPLATE` (the
+    same map the agents use when bootstrapping a fresh project). The
+    migration's own scaffold takes precedence for files we've enhanced
+    (LocatorHealer, LocatorRepository, TimingHealer, VisualIntentChecker,
+    HealingDashboard, dashboard-server) — those land first and we never
+    overwrite them with the BOILERPLATE version.
+
+    Top-level config files (package.json, tsconfig.json, .env, etc.) are
+    skipped here — they're already produced by the merge passes.
+
+    Honors `--conflict overwrite` for everything else: missing files always
+    get written; existing files are only refreshed when overwrite is on.
+    """
+    try:
+        from stlc_agents.agent_helix_writer.tools.boilerplate import BOILERPLATE
+    except Exception:
+        # Boilerplate package not importable — nothing to fill.
+        return
+
+    # FILL-ONLY: never overwrite an existing file regardless of
+    # conflict_strategy. Only files in the allowlist are even considered,
+    # because the broader BOILERPLATE set contains components that assume
+    # API surfaces the user's migrated code doesn't expose.
+    for rel_path, body in BOILERPLATE.items():
+        if rel_path not in _BOILERPLATE_FILL_ALLOWLIST:
+            continue
+        target = root / rel_path
+        if target.exists():
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(body, encoding="utf-8")
+        written.append({
+            "source":       "(boilerplate) agent_helix_writer",
+            "target":       rel_path,
+            "role":         "boilerplate",
+            "change_count": 0,
+        })
+
+
+# ---------------------------------------------------------------------------
+# Agent-asset installation (skills, .mcp.json, governance docs)
+# ---------------------------------------------------------------------------
+
+_ADO_SKILL_DIRS = (
+    "generate-test-cases",
+    "generate-gherkin",
+    "generate-playwright-code",
+    "write-helix-files",
+    "deduplication-protocol",
+    "migrate-framework",
+)
+_JIRA_SKILL_DIRS = (
+    "qa-jira-manager",
+    "generate-gherkin",
+    "generate-playwright-code",
+    "write-helix-files",
+    "deduplication-protocol",
+    "migrate-framework",
+)
+
+
+def _stlc_agents_root() -> Path:
+    """
+    Absolute path to the stlc-agents package install — used to locate the
+    skill source tree, governance docs, and agent binaries. We resolve from
+    *this* file's location so the same code works whether stlc-agents is
+    installed editable (`pip install -e .`) or from a wheel.
+    """
+    # _migrate.py lives at <root>/src/stlc_agents/agent_migration/_migrate.py
+    return Path(__file__).resolve().parents[3]
+
+
+def _agent_binary_path(name: str) -> str:
+    """
+    Locate an installed agent's console-script binary. Falls back to a bare
+    name (which only works when the user has stlc-agents' venv on PATH) so
+    the .mcp.json is always emittable.
+    """
+    venv_bin = Path(sys.executable).parent
+    candidate = venv_bin / name
+    return str(candidate) if candidate.exists() else name
+
+
+def _install_agent_assets(
+    root: Path,
+    written: list[dict],
+    integration: str,
+    conflict_strategy: str,
+) -> None:
+    """
+    Drop in the assets every QA-STLC agent expects to find in a Helix-QA tree:
+
+      • `.claude/skills/<name>/SKILL.md`   per integration (ado / jira / both)
+      • `.claude/AGENT-BEHAVIOR.md`        zero-inference contract
+      • `AGENT-BEHAVIOR.md` (root)         readable from the project root
+      • `ORCHESTRATION_RULES.md`           multi-step workflow rules (if present)
+      • `.mcp.json`                        MCP server registry — Claude Code,
+                                           Cursor, and other MCP-aware clients
+                                           auto-discover agents from this file
+      • `.github/copilot-instructions/`    same skills, flattened for VS Code
+
+    Behavior is gated on conflict_strategy:
+      "overwrite" → always refresh (picks up tool-side improvements)
+      else        → only write missing files
+    """
+    stlc_root  = _stlc_agents_root()
+    skills_dir = stlc_root / "skills"
+    if not skills_dir.exists():
+        # stlc-agents not installed editable & wheel didn't ship skills/ —
+        # nothing to do (no warning since this path is rare).
+        return
+
+    overwrite = conflict_strategy == "overwrite"
+    chosen: tuple[str, ...]
+    if integration == "jira":
+        chosen = _JIRA_SKILL_DIRS
+    elif integration == "ado":
+        chosen = _ADO_SKILL_DIRS
+    else:  # "both" / default
+        chosen = tuple(dict.fromkeys((*_ADO_SKILL_DIRS, *_JIRA_SKILL_DIRS)))
+
+    # 1. Claude Code: nested SKILL.md inside .claude/skills/<name>/
+    claude_skills = root / ".claude" / "skills"
+    claude_skills.mkdir(parents=True, exist_ok=True)
+    for name in chosen:
+        src = skills_dir / name / "SKILL.md"
+        if not src.exists():
+            continue
+        dst = claude_skills / name / "SKILL.md"
+        if dst.exists() and not overwrite:
+            continue
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(src, dst)
+        written.append({
+            "source":       f"(stlc-agents) skills/{name}/SKILL.md",
+            "target":       str(dst.relative_to(root)),
+            "role":         "skill",
+            "change_count": 0,
+        })
+
+    # 2. VS Code: flat .github/copilot-instructions/<name>.md
+    vscode_skills = root / ".github" / "copilot-instructions"
+    vscode_skills.mkdir(parents=True, exist_ok=True)
+    for name in chosen:
+        src = skills_dir / name / "SKILL.md"
+        if not src.exists():
+            continue
+        dst = vscode_skills / f"{name}.md"
+        if dst.exists() and not overwrite:
+            continue
+        shutil.copyfile(src, dst)
+        written.append({
+            "source":       f"(stlc-agents) skills/{name}/SKILL.md",
+            "target":       str(dst.relative_to(root)),
+            "role":         "skill",
+            "change_count": 0,
+        })
+
+    # 3. Governance docs (AGENT-BEHAVIOR.md, ORCHESTRATION_RULES.md)
+    for doc_name in ("AGENT-BEHAVIOR.md", "ORCHESTRATION_RULES.md"):
+        src = stlc_root / doc_name
+        # AGENT-BEHAVIOR.md actually lives under skills/ — try both paths.
+        if not src.exists():
+            src = skills_dir / doc_name
+        if not src.exists():
+            continue
+        for dst in (root / doc_name, root / ".claude" / doc_name,
+                    root / ".github" / "copilot-instructions" / doc_name):
+            if dst.exists() and not overwrite:
+                continue
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copyfile(src, dst)
+            written.append({
+                "source":       f"(stlc-agents) {src.relative_to(stlc_root)}",
+                "target":       str(dst.relative_to(root)),
+                "role":         "agent-doc",
+                "change_count": 0,
+            })
+
+    # 4. .mcp.json — MCP server registry (Claude Code / Cursor pick this up)
+    mcp_path = root / ".mcp.json"
+    if not mcp_path.exists() or overwrite:
+        mcp_path.write_text(_render_mcp_config(integration), encoding="utf-8")
+        written.append({
+            "source":       "(stlc-agents) auto-generated",
+            "target":       ".mcp.json",
+            "role":         "mcp-config",
+            "change_count": 0,
+        })
+
+
+def _render_mcp_config(integration: str) -> str:
+    """
+    Emit a .mcp.json listing the agent MCP servers for the selected
+    integration. Always includes the shared agents (gherkin / playwright /
+    helix / migration) and the Playwright MCP. ADO/Jira-specific entries
+    are added based on `integration`.
+    """
+    servers: dict[str, dict] = {
+        "qa-gherkin-generator":    {"command": _agent_binary_path("qa-gherkin-generator")},
+        "qa-playwright-generator": {"command": _agent_binary_path("qa-playwright-generator")},
+        "qa-helix-writer":         {"command": _agent_binary_path("qa-helix-writer")},
+        "qa-migration":            {"command": _agent_binary_path("stlc-migrate")},
+        "playwright":              {"command": "npx", "args": ["@playwright/mcp@latest", "--isolated"]},
+    }
+    if integration in ("ado", "both"):
+        servers["qa-test-case-manager"] = {"command": _agent_binary_path("qa-test-case-manager")}
+    if integration in ("jira", "both"):
+        servers["qa-jira-manager"] = {
+            "command": _agent_binary_path("qa-jira-manager"),
+            "env": {
+                "JIRA_CLIENT_ID":     "${JIRA_CLIENT_ID}",
+                "JIRA_CLIENT_SECRET": "${JIRA_CLIENT_SECRET}",
+                "JIRA_CLOUD_ID":      "${JIRA_CLOUD_ID}",
+            },
+        }
+    return json.dumps({"mcpServers": servers}, indent=2) + "\n"