qa-engineer 0.9.2 → 0.11.0

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/conflict.mjs

@@ -6,7 +6,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { hashFile } from './hash.mjs';
+import { entryDigest, entryPresent } from './integrity.mjs';
 
 /**
  * @param {object}   args
@@ -19,10 +19,11 @@ export function detectConflicts({ projectRoot, planned, priorLock }) {
   const owned = new Set((priorLock?.files ?? []).map((f) => f.path));
   const conflicts = [];
   for (const entry of planned) {
-    const abs = path.join(projectRoot, entry.path);
-    if (!fs.existsSync(abs)) continue; // brand-new file, no conflict
+    // `entryPresent` rather than `existsSync`: a link whose target is gone still
+    // occupies the path, and overwriting it blind would lose where it pointed.
+    if (!entryPresent(projectRoot, entry)) continue; // brand-new path, no conflict
     if (owned.has(entry.path)) continue; // pack-owned, safe to update
-    if (hashFile(abs) === entry.sha256) continue; // identical content, no-op
+    if (entryDigest(projectRoot, entry) === entry.sha256) continue; // already correct, no-op
     conflicts.push({ path: entry.path, reason: 'exists and is not owned by a previous install' });
   }
   return conflicts;

package/packages/installer/lib/core/fs-safe.mjs

@@ -109,6 +109,80 @@ function ensureDir(dir, createdDirs) {
   }
 }
 
+/**
+ * The target of a symlink at `abs`, or null when there is no link there.
+ *
+ * `lstat` rather than `exists`, because a link pointing at something that has been
+ * deleted still exists as a link and still has to be replaced rather than written over.
+ */
+export function readLinkTarget(abs) {
+  try {
+    const stat = fs.lstatSync(abs);
+    if (!stat.isSymbolicLink()) return null;
+    return fs.readlinkSync(abs);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Create a directory link, choosing the kind the platform will allow.
+ *
+ * On Windows a symbolic link needs either administrator rights or Developer Mode, while
+ * a *junction* needs neither and behaves the same for reading a directory. Preferring a
+ * junction there is the difference between a global install that works for every Windows
+ * developer and one that works only for those running an elevated shell.
+ */
+export function createLink(abs, target) {
+  const type = process.platform === 'win32' ? 'junction' : 'dir';
+  fs.symlinkSync(target, abs, type);
+}
+
+/**
+ * Can this filesystem hold a directory link at all?
+ *
+ * Asked once, before planning, rather than discovered halfway through a transaction.
+ * The answer is no more often than it looks: a FAT- or exFAT-formatted volume supports
+ * neither symlinks nor junctions, some container and network mounts refuse them, and a
+ * Windows host without Developer Mode refuses symlinks (which is why `createLink` asks
+ * for a junction there instead).
+ *
+ * When the answer is no the installer copies instead. A global install that fails
+ * outright on a USB stick would be a worse tool than one that uses more disk.
+ */
+export function canLink(root) {
+  const probe = path.join(root, `.qa-linkprobe-${process.pid}`);
+  const target = path.join(root, `.qa-linktarget-${process.pid}`);
+  try {
+    fs.mkdirSync(target, { recursive: true });
+    createLink(probe, target);
+    const ok = readLinkTarget(probe) !== null;
+    fs.unlinkSync(probe);
+    fs.rmdirSync(target);
+    return ok;
+  } catch {
+    // Clean up whatever got as far as existing, then report no.
+    try {
+      if (readLinkTarget(probe) !== null) fs.unlinkSync(probe);
+    } catch { /* nothing to undo */ }
+    try {
+      if (fs.existsSync(target)) fs.rmdirSync(target);
+    } catch { /* nothing to undo */ }
+    return false;
+  }
+}
+
+/** True when the file already holds exactly these bytes. */
+function sameContent(file, content) {
+  try {
+    const stat = fs.statSync(file);
+    if (!stat.isFile() || stat.size !== content.length) return false;
+    return fs.readFileSync(file).equals(content);
+  } catch {
+    return false;
+  }
+}
+
 /** Write content to file via a temp file + rename, so readers never see a partial write. */
 function atomicWrite(file, content) {
   const tmp = `${file}.qa-tmp-${process.pid}`;
@@ -134,6 +208,24 @@ export class Transaction {
     this.ops.push({ kind: 'delete', rel: relPath });
   }
 
+  /**
+   * Stage a symbolic link at `relPath` pointing at `targetAbs`.
+   *
+   * Links are how a global install serves an agent without copying the skills again.
+   * They go through the transaction rather than around it so a half-linked install
+   * rolls back like a half-written one — and because replacing a link silently would
+   * lose where the old one pointed.
+   *
+   * Only a link may be replaced by a link. A real directory at the target path belongs
+   * to someone else, and the conflict detector is what decides whether the user wants it
+   * overwritten; reaching here with one is a bug, so it throws rather than deleting a
+   * directory nobody agreed to lose.
+   */
+  link(relPath, targetAbs) {
+    resolveInside(this.root, relPath);
+    this.ops.push({ kind: 'link', rel: relPath, target: targetAbs });
+  }
+
   /** Directories the transaction will need to write into, deduplicated. */
   targetDirs() {
     const dirs = new Set();
@@ -169,6 +261,8 @@ export class Transaction {
     const created = []; // files that did not exist before (remove on rollback)
     const createdDirs = []; // directories we made (remove on rollback if empty)
     const backups = []; // { abs, backup } for files that existed (restore on rollback)
+    let unchanged = 0; // already byte-identical: neither written nor backed up
+    const replacedLinks = []; // { abs, target } symlinks removed (recreate on rollback)
     let backedUp = 0;
 
     const backup = (abs, rel) => {
@@ -185,21 +279,65 @@ export class Transaction {
         // other code, and containment is cheap to reassert.
         const abs = resolveInside(this.root, op.rel);
         if (op.kind === 'write') {
-          if (fs.existsSync(abs)) backup(abs, op.rel);
-          else created.push(abs);
+          if (fs.existsSync(abs)) {
+            // Reinstalling identical content is the common case for update and repair.
+            // Backing it up copies the whole install into a dated directory on every
+            // run — three copies of the engine after two commands — and restoring a
+            // byte-identical file on rollback achieves nothing.
+            if (sameContent(abs, op.content)) {
+              unchanged += 1;
+              continue;
+            }
+            backup(abs, op.rel);
+          } else {
+            created.push(abs);
+          }
           ensureDir(path.dirname(abs), createdDirs);
           atomicWrite(abs, op.content);
         } else if (op.kind === 'delete') {
-          if (fs.existsSync(abs)) {
+          // A link is deleted by unlinking it, and "backed up" by remembering where it
+          // pointed. Copying it would follow the link and try to copy a directory as a
+          // file, which is how uninstall crashed on a global install.
+          const linkTarget = readLinkTarget(abs);
+          if (linkTarget !== null) {
+            replacedLinks.push({ abs, target: linkTarget });
+            fs.unlinkSync(abs);
+          } else if (fs.existsSync(abs)) {
             backup(abs, op.rel);
             fs.rmSync(abs);
           }
+        } else if (op.kind === 'link') {
+          const existing = readLinkTarget(abs);
+          if (existing !== null) {
+            replacedLinks.push({ abs, target: existing });
+            fs.unlinkSync(abs);
+          } else if (fs.existsSync(abs)) {
+            throw environmentError(
+              `refusing to replace ${abs} with a link: it is a real file or directory, not a link ` +
+                'this installer created',
+            );
+          } else {
+            created.push(abs);
+          }
+          ensureDir(path.dirname(abs), createdDirs);
+          createLink(abs, op.target);
         }
       }
     } catch (error) {
-      // Roll back: remove created files, restore backups, drop created dirs.
+      // Roll back: remove created files and links, restore backups and replaced links,
+      // drop created dirs.
       for (const abs of created) {
-        if (fs.existsSync(abs)) fs.rmSync(abs, { force: true });
+        if (readLinkTarget(abs) !== null) fs.unlinkSync(abs);
+        else if (fs.existsSync(abs)) fs.rmSync(abs, { force: true });
+      }
+      for (const { abs, target } of replacedLinks) {
+        if (!fs.existsSync(abs) && readLinkTarget(abs) === null) {
+          try {
+            createLink(abs, target);
+          } catch {
+            /* best effort: the original error is what matters */
+          }
+        }
       }
       for (const { abs, backup: from } of backups) {
         fs.copyFileSync(from, abs);
@@ -215,8 +353,10 @@ export class Transaction {
     }
 
     return {
-      written: this.ops.filter((o) => o.kind === 'write').length,
+      written: this.ops.filter((o) => o.kind === 'write').length - unchanged,
+      unchanged,
       deleted: this.ops.filter((o) => o.kind === 'delete').length,
+      linked: this.ops.filter((o) => o.kind === 'link').length,
       backedUp,
       backupDir: backedUp > 0 ? this.backupDir : null,
       dryRun: false,

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

@@ -0,0 +1,59 @@
+// What a lockfile entry should hash to on disk, whatever kind of entry it is.
+//
+// Four commands independently asked "does this file still match its recorded hash?" —
+// validate, verify, uninstall, and the conflict detector — and each did it by calling
+// `hashFile` directly. That was correct while every entry was a file. The moment a
+// global install started recording links, all four tried to read a directory and threw
+// EISDIR, which is a crash rather than a diagnosis.
+//
+// So the question moves here and is asked once. A link's identity is *where it points*,
+// not what is behind it: hashing the target means `verify` catches a link repointed at
+// something else, and does not report drift merely because the canonical skill it points
+// at was legitimately updated.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { hashFile, hashString } from './hash.mjs';
+import { readLinkTarget } from './fs-safe.mjs';
+import { toPosix } from './paths.mjs';
+
+/**
+ * The digest of an installed entry, or `null` when it is not there.
+ *
+ * `null` means missing, which every caller already treats as drift — so a link whose
+ * path now holds a real directory reads as drift rather than as a match, which is what
+ * it is.
+ */
+export function entryDigest(root, entry) {
+  const absolute = path.join(root, entry.path);
+
+  if (entry.owner === 'link') {
+    const target = readLinkTarget(absolute);
+    if (target === null) return null;
+    // Relative to the scope root, so a lockfile stays valid when the whole tree moves —
+    // a home directory that changes name should not invalidate every link in it.
+    return hashString(toPosix(path.relative(root, path.resolve(path.dirname(absolute), target))));
+  }
+
+  if (!fs.existsSync(absolute)) return null;
+  try {
+    return hashFile(absolute);
+  } catch {
+    // A path that exists but cannot be read as a file — a directory where a file was
+    // recorded — is drift, not a crash.
+    return null;
+  }
+}
+
+/** True when the entry on disk matches what the lockfile recorded. */
+export function entryMatches(root, entry) {
+  const digest = entryDigest(root, entry);
+  return digest !== null && digest === entry.sha256;
+}
+
+/** True when anything at all occupies the entry's path, link or file. */
+export function entryPresent(root, entry) {
+  const absolute = path.join(root, entry.path);
+  return fs.existsSync(absolute) || readLinkTarget(absolute) !== null;
+}

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

@@ -20,8 +20,19 @@ export function lockPath(projectRoot) {
   return path.join(projectRoot, LOCKFILE);
 }
 
-export function readLock(projectRoot) {
-  const file = lockPath(projectRoot);
+/**
+ * The lockfile for a scope.
+ *
+ * A global install keeps its lockfile inside `~/.qa-engineer/`, never loose in the home
+ * directory — the whole point of owning a directory is that everything the tool wrote is
+ * in one place a user can inspect and delete.
+ */
+export function scopeLockPath(scope) {
+  return path.join(scope.root, scope.lockfile);
+}
+
+export function readLock(projectRoot, relative = LOCKFILE) {
+  const file = path.join(projectRoot, relative);
   if (!fs.existsSync(file)) return null;
   let raw;
   try {
@@ -40,12 +51,17 @@ export function readLock(projectRoot) {
  * Assemble a lockfile object. `now` is injected so tests are deterministic;
  * the CLI passes the real time.
  */
-export function buildLock({ agents, files, now }) {
+export function buildLock({ agents, files, now, scope = null }) {
   const lock = {
     lockfileVersion: LOCKFILE_VERSION,
     pack: { name: PACK_NAME, version: VERSION, specRevision: SPEC_REVISION },
     installer: VERSION,
     generatedAt: now,
+    // Recorded so every later command knows what it is operating on without being told
+    // again. Omitted for a project install, which is what a lockfile without one means.
+    ...(scope && scope.kind !== 'project'
+      ? { scope: { kind: scope.kind, qaRoot: scope.qaRootRelative, sharedEngine: scope.shareEngine } }
+      : {}),
     agents: agents.map((a) => ({
       id: a.id,
       name: a.name,

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

@@ -1,74 +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-explore renders its HTML report with qa_analysis.report_html rather than
-  // typing it, so every required finding field reaches the page.
-  'qa-explore': Object.freeze({ packages: ['qa_analysis'], 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/). */
@@ -82,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);