qa-engineer 0.9.1 → 0.10.0

package/packages/installer/lib/commands/install.mjs

@@ -23,6 +23,31 @@ import { INSTALL_STEPS, progressBar } from '../ui/progress.mjs';
 import { detectFrameworks } from '../detect/frameworks.mjs';
 import { getFramework } from '../../../../shared/frameworks/registry.mjs';
 
+/**
+ * Say how to reach a skill in the host that was actually detected.
+ *
+ * The invocation surface differs per host — Codex takes `$qa-explore`, Cursor
+ * matches on `/`, OpenCode's agent loads skills itself — and a user who types the
+ * wrong one concludes the install failed. The registry records each host's own
+ * convention beside the paths it reads, so this prints what will work here rather
+ * than a generic "/qa-explore" that is wrong in two of the five hosts.
+ */
+function reportInvocation(agents, logger) {
+  const named = agents.filter((a) => a.invoke && a.id !== 'agent-skills');
+  if (named.length === 0) {
+    const fallback = agents.find((a) => a.invoke);
+    if (fallback) {
+      logger.info(`  → no specific agent detected; ${fallback.invoke}`);
+      logger.info('  → the skills are on the standard Agent Skills path, which every');
+      logger.info('    supported host reads: Cursor, Codex, OpenCode, Antigravity, Gemini, Copilot');
+    }
+    return;
+  }
+  for (const agent of named) {
+    logger.info(`  → in ${agent.name}: ${agent.invoke}`);
+  }
+}
+
 /**
  * Say plainly which commands this project can actually use.
  *
@@ -60,10 +85,11 @@ function reportFrameworkFit(root, logger) {
     return;
   }
 
-  logger.warn('no supported end-to-end framework detected (Playwright, Selenium, Cypress, WebdriverIO)');
-  logger.info('  → /qa-run and /qa-generate need one; they will tell you so rather than guess');
-  logger.info('  → these work without one: /qa-review, /qa-api, /qa-report, /qa-audit, /qa-explore');
-  logger.info('  → unit tests only (Jest, Vitest, pytest)? That is expected — see the README');
+  logger.warn('no end-to-end framework detected (Playwright, Selenium, Cypress, WebdriverIO)');
+  logger.info('  → start with /qa-generate — it bootstraps a framework when none exists');
+  logger.info('  → /qa-run needs one first; it will say so rather than guess');
+  logger.info('  → these work today: /qa-review, /qa-api, /qa-audit, /qa-explore, /qa-report');
+  logger.info('  → unit tests only (Jest, Vitest, Jasmine, pytest)? That is expected');
 }
 
 /**
@@ -200,6 +226,30 @@ export async function executeInstall({
     tx.write(entry.path, entry.content);
   }
 
+  // Files the previous install owned that this one does not: remove them.
+  //
+  // Without this, anything that leaves the pack between versions stays on disk
+  // forever, and `verify` cannot see it — verify checks that lockfile entries are
+  // present and unmodified, and an orphan is in no lockfile. Upgrading 0.9.1 to
+  // 0.9.3, which replaced the Python engine with a Node one, left 154 dead Python
+  // files in the user's repository, reported as a clean install and ready to be
+  // committed.
+  //
+  // Only files the pack itself wrote are touched: the candidates come from the
+  // prior lockfile, which is the record of what this installer created. Each goes
+  // through the same Transaction as a write, so it is backed up first and restored
+  // if any later step fails.
+  const orphans = [];
+  if (priorLock && !dryRun) {
+    const stillOwned = new Set(unique.map((entry) => entry.path));
+    for (const previous of priorLock.files ?? []) {
+      if (previous.path === LOCKFILE || stillOwned.has(previous.path)) continue;
+      if (!fs.existsSync(path.join(root, previous.path))) continue;
+      orphans.push(previous.path);
+      tx.delete(previous.path);
+    }
+  }
+
   reportProgress(INSTALL_STEPS[1].label, 2);
   reportProgress(INSTALL_STEPS[2].label, 3);
 
@@ -249,7 +299,11 @@ export async function executeInstall({
     if (!json) logger.ok(`dry run: would write ${summary.written} file(s)`);
   } else if (!json) {
     logger.ok(`installed ${unique.length} file(s); lockfile ${lockPath(root)}`);
+    if (orphans.length > 0) {
+      logger.ok(`removed ${orphans.length} file(s) the previous version owned and this one does not`);
+    }
     for (const step of INSTALL_STEPS) logger.ok(step.label);
+    reportInvocation(agents, logger);
     reportFrameworkFit(root, logger);
   }
 
@@ -261,6 +315,7 @@ export async function executeInstall({
     skills: skills.length,
     files: unique.length,
     lockfile: dryRun ? null : LOCKFILE,
+    removed: orphans,
     validation,
   };
 }

package/packages/installer/lib/core/bundle.mjs

@@ -1,124 +1,101 @@
-// Bundling deterministic tooling, integrated into installation. Skills that run
-// a Python engine need that engine to travel with them (self-containment). The
-// installer materializes it by COPYING the canonical code from shared/ into the
+// Bundling the deterministic engine, integrated into installation.
+//
+// Skills that run the engine need it to travel with them (self-containment). The
+// installer materializes it by COPYING the engine from packages/engine/ into the
 // installed skill's scripts/lib/ — a pure file copy, no code executed at install
-// time, honoring the SECURITY.md guarantee. This mirrors what
-// scripts/bundle_python.py does for repository development; users never run it.
+// time, honoring the SECURITY.md guarantee.
 //
-// Deep verification (that the bundle *runs* under the user's interpreter)
-// requires running Python and therefore lives in `qa doctor`, an explicit,
-// user-invoked diagnostic — never in the install path.
+// The engine is Node, and Node is already present: the user ran `npx` to get here.
+// That removes the whole class of failure the Python bundle had, where the files
+// could be copied perfectly and still not run because the interpreter was missing,
+// the wrong version, or named `python` rather than `python3` (ADR-0012).
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import {
-  BUNDLE_MANIFEST,
-  BUNDLE_SOURCES,
-  BUNDLE_PACKAGE_DATA,
-  BUNDLE_MODULE_SOURCES,
-  BUNDLE_LAUNCHER,
-  BUNDLE_DEST,
-} from './manifest.mjs';
+import { BUNDLE_MANIFEST, ENGINE_SOURCE, ENGINE_DATA, BUNDLE_DEST } from './manifest.mjs';
 import { listFilesRelative } from './paths.mjs';
 
 /** Bundle file entries for one skill, relative to the skill directory. */
 export function bundleFilesForSkill(sourceRoot, skill) {
-  const entry = BUNDLE_MANIFEST[skill];
-  if (!entry) return [];
+  if (!BUNDLE_MANIFEST[skill]) return [];
   const entries = [];
 
-  for (const pkg of entry.packages) {
-    const src = path.join(sourceRoot, BUNDLE_SOURCES[pkg]);
-    if (!fs.existsSync(src)) {
-      throw new Error(`bundled package source missing: ${BUNDLE_SOURCES[pkg]} (needed by ${skill})`);
-    }
-    for (const rel of listFilesRelative(src)) {
-      entries.push({
-        rel: `${BUNDLE_DEST}/${pkg}/${rel}`,
-        content: fs.readFileSync(path.join(src, rel)),
-      });
+  const engineRoot = path.join(sourceRoot, ENGINE_SOURCE);
+  if (!fs.existsSync(engineRoot)) {
+    throw new Error(`engine source missing: ${ENGINE_SOURCE} (needed by ${skill})`);
+  }
+  for (const rel of listFilesRelative(engineRoot)) {
+    // Tests and the package manifest are development files; the bundle is the
+    // runtime only.
+    if (rel.startsWith('test/') || rel === 'package.json') continue;
+    entries.push({
+      rel: `${BUNDLE_DEST}/${rel}`,
+      content: fs.readFileSync(path.join(engineRoot, rel)),
+    });
+  }
+
+  // Data the engine reads at runtime: the context contract, the internal seam
+  // schemas, and the branding metadata.
+  for (const data of ENGINE_DATA) {
+    const from = path.join(sourceRoot, data.from);
+    if (!fs.existsSync(from)) {
+      throw new Error(`engine data missing: ${data.from} (needed by ${skill})`);
     }
-    // Package data the code reads at runtime (internal schemas). Without these
-    // the diagnostics engine raises on every diagnosis.
-    for (const data of BUNDLE_PACKAGE_DATA[pkg] ?? []) {
-      const dataSrc = path.join(sourceRoot, data.from);
-      if (!fs.existsSync(dataSrc)) {
-        throw new Error(`bundled package data missing: ${data.from} (needed by ${skill})`);
-      }
-      for (const rel of listFilesRelative(dataSrc)) {
+    if (fs.statSync(from).isDirectory()) {
+      for (const rel of listFilesRelative(from)) {
         entries.push({
-          rel: `${BUNDLE_DEST}/${pkg}/${data.to}/${rel}`,
-          content: fs.readFileSync(path.join(dataSrc, rel)),
+          rel: `${BUNDLE_DEST}/${data.to}/${rel}`,
+          content: fs.readFileSync(path.join(from, rel)),
         });
       }
+    } else {
+      entries.push({ rel: `${BUNDLE_DEST}/${data.to}`, content: fs.readFileSync(from) });
     }
   }
 
-  // The launcher: the documented entry point, beside lib/ rather than inside it.
-  const launcherSrc = path.join(sourceRoot, BUNDLE_LAUNCHER.from);
-  if (!fs.existsSync(launcherSrc)) {
-    throw new Error(`bundled launcher missing: ${BUNDLE_LAUNCHER.from} (needed by ${skill})`);
-  }
-  entries.push({ rel: BUNDLE_LAUNCHER.to, content: fs.readFileSync(launcherSrc) });
-
-  for (const mod of entry.modules) {
-    const src = path.join(sourceRoot, BUNDLE_MODULE_SOURCES[mod]);
-    if (!fs.existsSync(src)) {
-      throw new Error(`bundled module source missing: ${BUNDLE_MODULE_SOURCES[mod]} (needed by ${skill})`);
-    }
-    entries.push({
-      rel: `${BUNDLE_DEST}/${path.basename(src)}`,
-      content: fs.readFileSync(src),
-    });
-  }
+  // The launcher is deliberately NOT bundled. It is a *committed* file in each
+  // skill (kept in step by sync-shared), because that is what makes a skill work
+  // when a generic file copier installs it. Copying it again here produced two
+  // different contents for one path — the committed copy carries a provenance
+  // marker — and the installer's conflict detector rejected the install outright.
+  // One file, one source.
 
   return entries;
 }
 
-/** True if any skill carries bundled tooling (used to gate doctor's deep check). */
+/** True if any skill carries the bundled engine (used to gate doctor's deep check). */
 export function packHasBundles() {
   return Object.keys(BUNDLE_MANIFEST).length > 0;
 }
 
-/** Locate a Python 3 interpreter, or null. Used only by doctor. */
-export function findPython() {
-  for (const candidate of ['python3', 'python']) {
-    const probe = spawnSync(candidate, ['--version'], { encoding: 'utf8' });
-    if (probe.status === 0) {
-      const version = (probe.stdout || probe.stderr).trim();
-      return { bin: candidate, version };
-    }
-  }
-  return null;
-}
-
-// Runs inside the bundle with only the bundle on PYTHONPATH. Importing is not
-// enough: a missing data file only surfaces when the engine actually runs, which
-// is exactly the failure this check exists to catch.
-const SMOKE = `
-import json, sys
-names = json.loads(sys.argv[1])
-for name in names:
-    __import__(name)
-if "qa_diagnostics" in names:
-    from qa_diagnostics import engine
-    diagnosis = engine.diagnose({
-        "tests": {"total": 1, "passed": 0, "failed": 1, "skipped": 0},
-        "executed": [{"title": "t", "status": "failed", "message": "no such element: #cart",
-                      "file": "t.spec.ts", "retries": 0}],
-    })
-    assert diagnosis["entries"], "engine produced no diagnosis entries"
-`;
-
 /**
- * Verify bundled tooling RUNS using ONLY its own directory on PYTHONPATH —
- * proving self-containment under the user's interpreter. Doctor-only.
+ * Verify the bundled engine RUNS from its own directory, under the Node that will
+ * run it.
+ *
+ * Copying files correctly is not the same as the result working: a missing data file
+ * only surfaces when the code reads it. So this executes a real command whose whole
+ * path touches the runtime data — `classify` exercises the taxonomy, and the
+ * diagnostics report validates against the bundled internal schemas.
  */
-export function verifyImports({ pythonBin, libDir, packages }) {
-  const result = spawnSync(pythonBin, ['-c', SMOKE, JSON.stringify(packages)], {
-    env: { PYTHONPATH: libDir, PATH: process.env.PATH ?? '' },
+export function verifyEngine({ libDir }) {
+  const cli = path.join(libDir, 'bin', 'qa-engine.mjs');
+  if (!fs.existsSync(cli)) {
+    return { ok: false, stderr: `bundled engine CLI missing at ${cli}` };
+  }
+  const probe = spawnSync(process.execPath, [cli, 'analysis', 'classify', 'no such element: #cart'], {
     encoding: 'utf8',
   });
-  return { ok: result.status === 0, stderr: (result.stderr ?? '').trim() };
+  if (probe.status !== 0) {
+    return { ok: false, stderr: (probe.stderr || probe.stdout || '').trim() };
+  }
+  try {
+    const parsed = JSON.parse(probe.stdout);
+    if (parsed.classification !== 'locator-failure') {
+      return { ok: false, stderr: `engine classified a missing element as ${parsed.classification}` };
+    }
+  } catch (error) {
+    return { ok: false, stderr: `engine did not emit JSON: ${error.message}` };
+  }
+  return { ok: true, stderr: '' };
 }

package/packages/installer/lib/core/config.mjs

@@ -7,7 +7,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CONFIG_FILE } from '../constants.mjs';
 import { QaError, usageError } from './errors.mjs';
-import { validate } from './schema-validate.mjs';
+import { validate } from '../../../engine/lib/analysis/contracts.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const SCHEMA_PATH = path.join(here, '..', '..', 'schemas', 'qa.config.schema.json');

package/packages/installer/lib/core/lockfile.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from 'node:url';
 import { LOCKFILE, PACK_NAME } from '../constants.mjs';
 import { VERSION, SPEC_REVISION } from '../version.mjs';
 import { QaError } from './errors.mjs';
-import { validate } from './schema-validate.mjs';
+import { validate } from '../../../engine/lib/analysis/contracts.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const SCHEMA_PATH = path.join(here, '..', '..', 'schemas', 'qa-lock.schema.json');

package/packages/installer/lib/core/manifest.mjs

@@ -1,71 +1,65 @@
-// What the pack ships: the set of skills, the files inside each, and which
-// skills carry bundled deterministic tooling. This manifest deliberately
-// mirrors scripts/bundle_python.py — the two must agree, and a test asserts it.
+// What the pack ships: the set of skills, the files inside each, and which skills
+// carry the bundled deterministic engine.
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { listFilesRelative } from './paths.mjs';
 
-// Skills that run deterministic tooling in the consumer's repository. The
+// Every bundling skill carries the same payload, named once so the map below reads
+// as the list of skills it is.
+const ENGINE = Object.freeze({ engine: true });
+
+// Skills that run the deterministic engine in the consumer's repository. The
 // bundle is materialized at install time, never shipped pre-built.
-// qa-review is knowledge-only and bundles nothing.
 //
-//   packages — importable directories
-//   modules  — single-file framework adapters, bundled flat
+// Every one of them bundles the same thing now. Under the Python engine this was a
+// per-skill list of packages and single-file adapters, because a skill that never
+// touched a Playwright trace had no reason to carry the adapter. The Node engine is
+// one package of about 3,000 lines with no dependencies, so splitting it would save
+// nothing measurable and would give nine skills nine slightly different bundles to
+// go wrong in. qa-review, qa-generate, qa-example and the qa router remain
+// knowledge-only and bundle nothing.
 export const BUNDLE_MANIFEST = Object.freeze({
-  'qa-init': Object.freeze({ packages: ['qa_analysis'], modules: [] }),
-  'qa-run': Object.freeze({ packages: ['qa_analysis'], modules: ['playwright_analysis'] }),
-  'qa-debug': Object.freeze({ packages: ['qa_analysis', 'qa_diagnostics'], modules: ['playwright_analysis'] }),
-  'qa-fix': Object.freeze({ packages: ['qa_analysis', 'qa_diagnostics'], modules: [] }),
-  'qa-report': Object.freeze({ packages: ['qa_analysis', 'qa_diagnostics'], modules: [] }),
-  'qa-flaky': Object.freeze({ packages: ['qa_analysis', 'qa_diagnostics'], modules: [] }),
-  'qa-api': Object.freeze({ packages: ['qa_analysis', 'qa_diagnostics'], modules: [] }),
-  'qa-audit': Object.freeze({ packages: ['qa_analysis', 'qa_diagnostics'], modules: [] }),
-});
-
-// Canonical source of each bundled package, relative to the pack root.
-export const BUNDLE_SOURCES = Object.freeze({
-  qa_analysis: 'shared/analysis/lib/qa_analysis',
-  qa_diagnostics: 'shared/diagnostics/lib/qa_diagnostics',
+  'qa-init': ENGINE,
+  'qa-run': ENGINE,
+  'qa-debug': ENGINE,
+  'qa-fix': ENGINE,
+  'qa-report': ENGINE,
+  'qa-flaky': ENGINE,
+  'qa-api': ENGINE,
+  'qa-audit': ENGINE,
+  'qa-explore': ENGINE,
 });
 
-// Non-Python files a bundled package reads at runtime, relative to the pack
-// root and to the package directory. The diagnostics engine validates every
-// diagnosis against its internal schemas, so without these it cannot run.
-export const BUNDLE_PACKAGE_DATA = Object.freeze({
-  // The context CLI validates .qa/context.md against the context contract.
-  qa_analysis: Object.freeze([
-    Object.freeze({ from: 'shared/analysis/schemas', to: 'schemas' }),
-  ]),
-  qa_diagnostics: Object.freeze([
-    Object.freeze({ from: 'shared/diagnostics/schemas/internal', to: 'schemas/internal' }),
-  ]),
-});
+// The engine, copied wholesale: `lib/` for the modules and `bin/` for the CLI the
+// launcher executes.
+export const ENGINE_SOURCE = 'packages/engine';
 
-// Canonical source of each bundled single-file module.
-export const BUNDLE_MODULE_SOURCES = Object.freeze({
-  playwright_analysis: 'shared/frameworks/playwright/lib/playwright_analysis.py',
-});
+// The engine keeps the non-code files it reads at runtime — the context contract,
+// the internal seam schemas, the branding metadata — inside its own lib/, so a
+// wholesale copy of the engine directory is a complete engine. Nothing to enumerate
+// here, and no second place for a data file to be forgotten.
+export const ENGINE_DATA = Object.freeze([]);
 
-// The launcher every bundling skill carries, one level above lib/. It resolves
-// its own lib/ path, so the documented invocation needs no shell features and
-// works identically in PowerShell and cmd.exe.
+// The launcher every bundling skill carries, one level above lib/.
+//
+// It is a *committed* file in each skill rather than something the installer
+// generates — `node scripts/sync-shared.mjs --write` refreshes the copies and
+// `--check` fails on drift. That is what lets a generic file copier (`npx skills
+// add`, or a plain `git clone`) produce a working skill without running this
+// installer at all. Consequently the bundler does not copy it: two sources for one
+// destination path is a conflict, and the installer is right to refuse it.
 export const BUNDLE_LAUNCHER = Object.freeze({
-  from: 'shared/tooling/qa_tool.py',
-  to: 'scripts/qa_tool.py',
+  from: 'shared/tooling/qa-tool.mjs',
+  to: 'scripts/qa-tool.mjs',
 });
 
-// Where bundled code lands inside an installed skill.
+// Where the bundled engine lands inside an installed skill.
 export const BUNDLE_DEST = 'scripts/lib';
 
-/** Package names bundled into a skill (empty array when it bundles nothing). */
-export function bundlePackagesForSkill(skill) {
-  return BUNDLE_MANIFEST[skill]?.packages ?? [];
-}
-
-/** Module names bundled into a skill. */
-export function bundleModulesForSkill(skill) {
-  return BUNDLE_MANIFEST[skill]?.modules ?? [];
+/** True when this skill bundles the engine. */
+export function bundlesEngine(skill) {
+  return Object.prototype.hasOwnProperty.call(BUNDLE_MANIFEST, skill);
 }
 
 /** All skill names shipped by the pack (directories under skills/). */
@@ -79,9 +73,9 @@ export function listSkills(sourceRoot) {
 }
 
 /**
- * Files that make up a skill, relative to the skill directory. Excludes the
- * bundled tooling (scripts/lib): it is a generated artifact produced by the
- * bundle step at install time, not copied from source.
+ * Files that make up a skill, relative to the skill directory. Excludes the bundled
+ * engine (scripts/lib): it is a generated artifact produced by the bundle step at
+ * install time, not copied from source.
  */
 export function skillFiles(sourceRoot, skill) {
   const dir = path.join(sourceRoot, 'skills', skill);

package/packages/installer/lib/core/validate-install.mjs

@@ -5,8 +5,8 @@ import path from 'node:path';
 import { LOCKFILE, SHARED_SKILLS_DIR, CLAUDE_SKILLS_DIR } from '../constants.mjs';
 import { readLock } from './lockfile.mjs';
 import { hashFile } from './hash.mjs';
-import { findPython, verifyImports, packHasBundles } from './bundle.mjs';
-import { BUNDLE_DEST, BUNDLE_MANIFEST, bundlePackagesForSkill } from './manifest.mjs';
+import { verifyEngine, packHasBundles } from './bundle.mjs';
+import { BUNDLE_DEST, BUNDLE_MANIFEST } from './manifest.mjs';
 
 /**
  * @typedef {{ id: string, ok: boolean, hard: boolean, message: string, hint?: string }} CheckResult
@@ -114,28 +114,21 @@ export function validateInstall(projectRoot) {
       hint: bundleOk ? undefined : 'run: qa repair',
     });
 
-    const python = findPython();
-    if (bundleOk && python) {
-      const packages = bundlePackagesForSkill(bundledSkill);
-      const result = verifyImports({ pythonBin: python.bin, libDir, packages });
+    // The engine runs under the Node that is already here — no second runtime to
+    // find, and nothing to skip when it is absent.
+    if (bundleOk) {
+      const result = verifyEngine({ libDir });
       checks.push({
-        id: 'python-imports',
+        id: 'engine-runs',
         ok: result.ok,
-        hard: false,
+        hard: true,
         message: result.ok
-          ? `Python imports OK (${python.bin} ${python.version})`
-          : `Python import check failed: ${result.stderr || 'unknown error'}`,
-        hint: result.ok ? undefined : 'install Python 3.8+ or run: qa doctor',
-      });
-    } else if (bundleOk && !python) {
-      checks.push({
-        id: 'python-imports',
-        ok: false,
-        hard: false,
-        message: 'Python not found — analysis engine import check skipped',
-        hint: 'install Python 3.8+ for full diagnostics',
+          ? `bundled engine runs (node ${process.versions.node})`
+          : `bundled engine failed to run: ${result.stderr || 'unknown error'}`,
+        hint: result.ok ? undefined : 'run: qa repair',
       });
     }
+
   }
 
   const major = Number(process.versions.node.split('.')[0]);

package/packages/installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qa-engineer/installer",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "The qa-engineer installer: agent detection, copy-based install, lockfile integrity, and wrapper generation.",
   "license": "MIT",
   "type": "module",

package/shared/tooling/qa-tool.mjs

@@ -0,0 +1,125 @@
+// The launcher every skill invokes to reach the deterministic engine.
+//
+// A skill's SKILL.md documents exactly one command shape:
+//
+//     node <SKILL_DIR>/scripts/qa-tool.mjs <tool> <subcommand> [args]
+//
+// and this file finds the engine, wherever it happens to be. That indirection
+// exists because the pack is installed three different ways and the engine lands in
+// a different place each time:
+//
+//   1. `qa install` bundles the engine into the skill, at ./lib/. Offline, fastest,
+//      and pinned to the version that was installed.
+//   2. `npx skills add <owner>/<repo>` — or any generic file copier — copies the
+//      skill directory out of git and bundles nothing. The engine is then resolved
+//      from node_modules if the project happens to depend on the pack.
+//   3. Neither: fall back to `npx qa-engineer`, which fetches the published package
+//      on first use and is served from the npm cache afterwards.
+//
+// Because this file is committed rather than generated, path 2 works at all — which
+// is what makes the pack installable by the wider Agent Skills ecosystem. The
+// command a skill runs never changes; only where the engine came from does.
+//
+// Exit codes pass through unchanged: 0 success, 1 an invalid contract, 2 unreadable
+// input or bad usage.
+//
+// No shebang: the synced copies carry a provenance marker on line one, which would
+// sit above it and stop the kernel seeing it anyway. Every documented invocation is
+// `node qa-tool.mjs …`, which needs none.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+const USAGE = `usage: node qa-tool.mjs <tool> <subcommand> [args]
+
+  analysis     parse artifacts, classify errors, validate contracts, diff-guard,
+               read .qa/context.md, render an HTML report, print the footer
+  diagnostics  root cause, timeline, priority, repair plans, release readiness
+  playwright   normalize a Playwright report or summarize a trace
+
+  --where      print how the engine was resolved, and stop
+
+examples:
+  node qa-tool.mjs analysis junit test-results/results.xml
+  node qa-tool.mjs analysis report-html qa-artifacts/explore-result.json --out report.html
+  node qa-tool.mjs diagnostics report --execution-result qa-artifacts/run.json
+`;
+
+/**
+ * Where the engine is, and how we found it.
+ *
+ * Ordered by cost: a bundled copy needs no resolution and no network, a
+ * node_modules copy needs no network, and npx needs both on first use. Reporting
+ * *which* one answered matters when a skill degrades — "the engine is missing" and
+ * "the engine is being fetched" are different problems.
+ */
+function resolveEngine() {
+  const bundled = path.join(here, 'lib', 'bin', 'qa-engine.mjs');
+  if (fs.existsSync(bundled)) return { kind: 'bundled', command: [process.execPath, bundled] };
+
+  for (const base of candidateModuleRoots()) {
+    const installed = path.join(base, 'qa-engineer', 'packages', 'engine', 'bin', 'qa-engine.mjs');
+    if (fs.existsSync(installed)) {
+      return { kind: 'node_modules', command: [process.execPath, installed] };
+    }
+  }
+
+  return {
+    kind: 'npx',
+    command: [npxCommand(), '--yes', 'qa-engineer', 'engine'],
+  };
+}
+
+/** node_modules directories worth checking, nearest first. */
+function candidateModuleRoots() {
+  const roots = [];
+  let dir = here;
+  for (let depth = 0; depth < 12; depth += 1) {
+    roots.push(path.join(dir, 'node_modules'));
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  if (process.cwd() !== here) roots.push(path.join(process.cwd(), 'node_modules'));
+  return roots;
+}
+
+// `npx` is a shell script on POSIX and a .cmd shim on Windows; spawnSync needs the
+// exact name, and `shell: true` would put user-supplied arguments through a shell.
+function npxCommand() {
+  return process.platform === 'win32' ? 'npx.cmd' : 'npx';
+}
+
+function main(argv) {
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    process.stdout.write(USAGE);
+    return argv.length === 0 ? 2 : 0;
+  }
+
+  const engine = resolveEngine();
+
+  if (argv[0] === '--where') {
+    process.stdout.write(`${JSON.stringify({ resolved: engine.kind, command: engine.command }, null, 2)}\n`);
+    return 0;
+  }
+
+  const [program, ...prefix] = engine.command;
+  const run = spawnSync(program, [...prefix, ...argv], { stdio: 'inherit' });
+
+  if (run.error) {
+    // Say which path was tried and what to do, because a skill's fallback prose
+    // cannot diagnose this and the user is the one who has to fix it.
+    const advice = engine.kind === 'npx'
+      ? 'the engine is not bundled and npx is unavailable — run `npx qa-engineer install` in this project, or install Node 18+'
+      : `could not execute ${program}`;
+    process.stderr.write(`qa-tool: ${advice}\n${run.error.message}\n`);
+    return 2;
+  }
+  return run.status ?? 2;
+}
+
+process.exitCode = main(process.argv.slice(2));