qa-engineer 0.9.2 → 0.11.0

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

@@ -4,9 +4,9 @@ import fs from 'node:fs';
 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 { entryDigest } from './integrity.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
@@ -17,17 +17,18 @@ import { BUNDLE_DEST, BUNDLE_MANIFEST, bundlePackagesForSkill } from './manifest
  * @param {string} projectRoot
  * @returns {{ ok: boolean, checks: CheckResult[] }}
  */
-export function validateInstall(projectRoot) {
+export function validateInstall(projectRoot, { scope = null } = {}) {
   /** @type {CheckResult[]} */
   const checks = [];
 
-  const lock = readLock(projectRoot);
+  const lockRelative = scope?.lockfile ?? LOCKFILE;
+  const lock = readLock(projectRoot, lockRelative);
   if (!lock) {
     checks.push({
       id: 'lockfile',
       ok: false,
       hard: true,
-      message: `${LOCKFILE} missing`,
+      message: `${lockRelative} missing`,
       hint: 'run: qa install',
     });
     return { ok: false, checks };
@@ -37,17 +38,12 @@ export function validateInstall(projectRoot) {
     id: 'lockfile',
     ok: true,
     hard: true,
-    message: `${LOCKFILE} present (${lock.files.length} files, pack ${lock.pack?.version ?? '?'})`,
+    message: `${lockRelative} present (${lock.files.length} files, pack ${lock.pack?.version ?? '?'})`,
   });
 
   let drift = 0;
   for (const entry of lock.files) {
-    const abs = path.join(projectRoot, entry.path);
-    if (!fs.existsSync(abs)) {
-      drift += 1;
-      continue;
-    }
-    if (hashFile(abs) !== entry.sha256) drift += 1;
+    if (entryDigest(projectRoot, entry) !== entry.sha256) drift += 1;
   }
   checks.push({
     id: 'integrity',
@@ -92,7 +88,36 @@ export function validateInstall(projectRoot) {
         : 'no contract schemas found (optional for minimal installs)',
   });
 
-  if (packHasBundles()) {
+  // Where the engine should be depends on how it was installed: a shared scope has
+  // exactly one copy in its qaRoot, a project install has one inside each bundling
+  // skill. Looking only for the second is what made the first report a broken install.
+  const sharedScope = scope?.shareEngine || lock.scope?.sharedEngine;
+  if (sharedScope) {
+    const qaRootRelative = scope?.qaRootRelative ?? lock.scope?.qaRoot ?? '.';
+    const libDir = path.join(projectRoot, qaRootRelative, 'engine');
+    const bundleOk = fs.existsSync(path.join(libDir, 'bin', 'qa-engine.mjs'));
+    checks.push({
+      id: 'engine',
+      ok: bundleOk,
+      hard: true,
+      message: bundleOk
+        ? `deterministic engine shared at ${path.relative(projectRoot, libDir) || '.'}`
+        : 'shared deterministic engine missing',
+      hint: bundleOk ? undefined : 'run: qa repair',
+    });
+    if (bundleOk) {
+      const result = verifyEngine({ libDir });
+      checks.push({
+        id: 'engine-runs',
+        ok: result.ok,
+        hard: true,
+        message: result.ok
+          ? `shared engine runs (node ${process.versions.node})`
+          : `shared engine failed to run: ${result.stderr || 'unknown error'}`,
+        hint: result.ok ? undefined : 'run: qa repair',
+      });
+    }
+  } else if (packHasBundles()) {
     const bundledSkill = Object.keys(BUNDLE_MANIFEST)[0];
     let libDir = null;
     for (const base of [SHARED_SKILLS_DIR, CLAUDE_SKILLS_DIR]) {
@@ -114,28 +139,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.2",
+  "version": "0.11.0",
   "description": "The qa-engineer installer: agent detection, copy-based install, lockfile integrity, and wrapper generation.",
   "license": "MIT",
   "type": "module",

package/packages/installer/schemas/qa-lock.schema.json

@@ -5,7 +5,14 @@
   "description": "qa-lock.json records exactly what was installed and a hash per file, so an install can be verified, updated, or removed without guessing. Written by the installer; not hand-edited.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["lockfileVersion", "pack", "installer", "generatedAt", "agents", "files"],
+  "required": [
+    "lockfileVersion",
+    "pack",
+    "installer",
+    "generatedAt",
+    "agents",
+    "files"
+  ],
   "properties": {
     "lockfileVersion": {
       "type": "integer",
@@ -14,11 +21,22 @@
     "pack": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["name", "version", "specRevision"],
+      "required": [
+        "name",
+        "version",
+        "specRevision"
+      ],
       "properties": {
-        "name": { "type": "string" },
-        "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+" },
-        "specRevision": { "type": "string" }
+        "name": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+"
+        },
+        "specRevision": {
+          "type": "string"
+        }
       }
     },
     "installer": {
@@ -35,17 +53,31 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["id", "name", "tier"],
+        "required": [
+          "id",
+          "name",
+          "tier"
+        ],
         "properties": {
-          "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
-          "name": { "type": "string" },
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*$"
+          },
+          "name": {
+            "type": "string"
+          },
           "tier": {
-            "type": ["integer", "null"],
+            "type": [
+              "integer",
+              "null"
+            ],
             "minimum": 1,
             "maximum": 2,
-            "description": "Support tier, or null when the host is unknown — the shared Agent Skills path was installed without identifying a product."
+            "description": "Support tier, or null when the host is unknown \u2014 the shared Agent Skills path was installed without identifying a product."
+          },
+          "skillsDir": {
+            "type": "string"
           },
-          "skillsDir": { "type": "string" },
           "detected": {
             "type": "boolean",
             "description": "True only when project markers identified this host. False when it was requested explicitly or stands in as the unknown-agent path. Optional for lockfiles written before this field existed."
@@ -59,7 +91,12 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["path", "sha256", "bytes", "owner"],
+        "required": [
+          "path",
+          "sha256",
+          "bytes",
+          "owner"
+        ],
         "properties": {
           "path": {
             "type": "string",
@@ -67,11 +104,36 @@
             "description": "Project-relative POSIX path. Must not be absolute and must not contain a '..' segment: a lockfile travels with a cloned repository, and uninstall deletes what it lists.",
             "pattern": "^(?!/)(?!.*(^|/)\\.\\.($|/)).+$"
           },
-          "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
-          "bytes": { "type": "integer", "minimum": 0 },
-          "owner": { "type": "string", "enum": ["skill", "wrapper", "config"] },
-          "skill": { "type": "string" },
-          "agent": { "type": "string" }
+          "sha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "bytes": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "owner": {
+            "type": "string",
+            "enum": [
+              "skill",
+              "wrapper",
+              "config",
+              "engine",
+              "link"
+            ],
+            "description": "What created the entry. `engine` is the shared deterministic engine, present once per scope. `link` is a symbolic link into the canonical skill tree, whose sha256 is the hash of its scope-relative target rather than of file content \u2014 a link has no content, and hashing the target is what lets verify catch one that has been repointed."
+          },
+          "skill": {
+            "type": "string"
+          },
+          "agent": {
+            "type": "string"
+          },
+          "linkTarget": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Absolute path a `link` entry points at. Absolute because the link is created with it verbatim; the hashed form in sha256 is scope-relative so the lockfile stays machine-independent."
+          }
         }
       }
     },
@@ -79,10 +141,46 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
-        "skills": { "type": "integer", "minimum": 0 },
-        "files": { "type": "integer", "minimum": 0 },
-        "wrappers": { "type": "integer", "minimum": 0 },
-        "directories": { "type": "integer", "minimum": 0 }
+        "skills": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "files": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "wrappers": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "directories": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind"
+      ],
+      "description": "Which installation mode wrote this lockfile. Absent means `project`: before 0.11 that was the only mode, so its absence is a fact rather than a gap.",
+      "properties": {
+        "kind": {
+          "enum": [
+            "global",
+            "workspace",
+            "project"
+          ]
+        },
+        "qaRoot": {
+          "type": "string",
+          "description": "Scope-relative directory holding the shared engine and canonical skills. Absent for a project install, which shares nothing."
+        },
+        "sharedEngine": {
+          "type": "boolean"
+        }
       }
     }
   }

package/shared/tooling/qa-tool.mjs

@@ -0,0 +1,161 @@
+// 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 os from 'node:os';
+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 shared copy
+ * needs one stat per ancestor, 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.
+ *
+ * The shared lookup is what lets one skill directory serve a project, a workspace, and a
+ * machine-wide install without knowing which installed it. Walking up for
+ * `.qa-engineer/engine` finds a workspace install from a skill inside the repository,
+ * and finds a global install from a skill linked into an agent's user-level directory —
+ * `~/.claude/skills/qa-explore` walks up to `~`, where `~/.qa-engineer/engine` is.
+ */
+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 root of candidateSharedRoots()) {
+    const shared = path.join(root, 'bin', 'qa-engine.mjs');
+    if (fs.existsSync(shared)) return { kind: 'shared', command: [process.execPath, shared] };
+  }
+
+  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'],
+  };
+}
+
+/** Shared engine directories worth checking, most specific first. */
+function candidateSharedRoots() {
+  const roots = [];
+
+  // An explicit home wins over anything discovered, so a user who moved the install can
+  // rely on it rather than on whatever the walk happens to find first.
+  const override = process.env.QA_ENGINEER_HOME;
+  if (override && override.trim()) roots.push(path.join(path.resolve(override.trim()), 'engine'));
+
+  let dir = here;
+  for (let depth = 0; depth < 12; depth += 1) {
+    roots.push(path.join(dir, '.qa-engineer', 'engine'));
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // The default machine home, for the case where the skill lives outside it entirely.
+  const home = os.homedir();
+  if (home) roots.push(path.join(home, '.qa-engineer', 'engine'));
+
+  return roots;
+}
+
+/** 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));

package/skills/qa-api/SKILL.md

@@ -53,15 +53,15 @@ Do not use it to generate API tests (`/qa-generate`) or to run a suite (`/qa-run
 
 ## Tooling
 
-Invoke the bundled engine through its launcher, as documented in [references/deterministic-tooling.md](references/deterministic-tooling.md). `SKILL_DIR` below is this skill's own directory — `.agents/skills/qa-api` or `.claude/skills/qa-api`, whichever exists. The command shape is the same in bash, zsh, PowerShell, and cmd.exe; on Windows use `python` if `python3` is not on PATH.
+Invoke the bundled engine through its launcher, as documented in [references/deterministic-tooling.md](references/deterministic-tooling.md). `SKILL_DIR` below is this skill's own directory — `.agents/skills/qa-api` or `.claude/skills/qa-api`, whichever exists. The command shape is the same in bash, zsh, PowerShell, and cmd.exe, and it runs under the same Node that installed the pack — there is no second runtime to find.
 
 | Tool | Invocation | Output | Fallback |
 | --- | --- | --- | --- |
-| HAR analyzer | `python3 <SKILL_DIR>/scripts/qa_tool.py analysis har <file.har> [--slow-ms N]` | Redacted request/response summary, failures, slow calls | Assess the tests without traffic and say so |
-| Error classifier | `python3 <SKILL_DIR>/scripts/qa_tool.py analysis classify "<message>" --http-status <N>` | Taxonomy classification for a failing call | Classify from the REST/GraphQL modules and lower confidence |
-| Redaction | `python3 <SKILL_DIR>/scripts/qa_tool.py analysis redact <file>` | The file's text with credentials masked, before anything is quoted | Do not quote captured traffic at all |
+| HAR analyzer | `node <SKILL_DIR>/scripts/qa-tool.mjs analysis har <file.har> [--slow-ms N]` | Redacted request/response summary, failures, slow calls | Assess the tests without traffic and say so |
+| Error classifier | `node <SKILL_DIR>/scripts/qa-tool.mjs analysis classify "<message>" --http-status <N>` | Taxonomy classification for a failing call | Classify from the REST/GraphQL modules and lower confidence |
+| Redaction | `node <SKILL_DIR>/scripts/qa-tool.mjs analysis redact <file>` | The file's text with credentials masked, before anything is quoted | Do not quote captured traffic at all |
 
-A missing `qa_tool.py` means the engine is not installed. Never paste raw captured traffic into a report — redaction is deterministic and must not be undone.
+A missing `qa-tool.mjs` means the engine is not installed. Never paste raw captured traffic into a report — redaction is deterministic and must not be undone.
 
 ## Output
 

package/skills/qa-api/references/deterministic-tooling.md

@@ -17,7 +17,7 @@ resolves its own location. There is nothing to set up and no shell features are
 involved:
 
 ```bash
-python3 <skill-dir>/scripts/qa_tool.py <tool> <subcommand> [args]
+node <skill-dir>/scripts/qa-tool.mjs <tool> <subcommand> [args]
 ```
 
 `<skill-dir>` is wherever the host installed this skill — usually
@@ -25,19 +25,21 @@ python3 <skill-dir>/scripts/qa_tool.py <tool> <subcommand> [args]
 whichever exists.
 
 ```bash
-python3 .agents/skills/qa-run/scripts/qa_tool.py analysis junit test-results/results.xml
+node .agents/skills/qa-run/scripts/qa-tool.mjs analysis junit test-results/results.xml
 ```
 
-That line is identical in bash, zsh, PowerShell, and cmd.exe. **On Windows, use
-`python` if `python3` is not on PATH** — that is the only platform difference.
+That line is identical in bash, zsh, PowerShell, and cmd.exe, with no platform
+difference at all: it runs under the same Node the user already had to install the
+pack.
 
-An earlier version of this contract used a shell recipe
-(`QA_LIB="$(ls -d … | head -1)"` with a `PYTHONPATH=` prefix). It was POSIX-only,
-so on Windows every deterministic call failed, each skill fell back to its manual
-path, and the user silently got guesswork while believing the tooling had run.
-Never reintroduce a shell-dependent invocation.
+Two earlier versions of this contract failed the same way. The first was a shell
+recipe (`QA_LIB="$(ls -d … | head -1)"` with a `PYTHONPATH=` prefix), POSIX-only, so
+on Windows every deterministic call failed and each skill fell back to guesswork
+while appearing to have run its tooling. The second was portable but needed a Python
+interpreter the user never agreed to install. Never reintroduce a shell-dependent
+invocation, and never add a runtime the install did not already require.
 
-If `qa_tool.py` is missing, the engine is not installed: say so, recommend
+If `qa-tool.mjs` is missing, the engine is not installed: say so, recommend
 `qa repair`, use the skill's documented fallback, and mark the result degraded.
 
 Every tool writes JSON to stdout. Exit `0` means success; exit `1` means an
@@ -45,35 +47,35 @@ invalid contract; exit `2` means unreadable input, a malformed artifact, or a
 payload that failed its seam contract, and the JSON body carries `error` and
 `detail`. Treat a non-zero exit as missing evidence, never as a value to guess.
 
-Standard-library Python 3.8+ only — nothing to install.
+Dependency-free Node — nothing to install beyond the Node that ran `npx`.
 
-## 2. Analysis core — `qa_tool.py analysis`
+## 2. Analysis core — `qa-tool.mjs analysis`
 
 Framework-agnostic parsing, redaction, and validation.
 
 | Subcommand | Invocation | Returns |
 | --- | --- | --- |
-| `junit` | `python3 <skill-dir>/scripts/qa_tool.py analysis junit <report.xml>` | `{tests: {...}, executed: [...]}` normalized counts and per-test outcomes |
-| `har` | `python3 <skill-dir>/scripts/qa_tool.py analysis har <file.har> [--slow-ms N]` | Redacted request/response summary, failures, slow calls |
-| `discover` | `python3 <skill-dir>/scripts/qa_tool.py analysis discover [--root DIR] [--path P]` | Artifacts found, by type, with presence flags |
-| `diff-guard` | `python3 <skill-dir>/scripts/qa_tool.py analysis diff-guard <diff-file>` | `{issues: [...], safe: bool}` — `safe:false` blocks the change |
-| `redact` | `python3 <skill-dir>/scripts/qa_tool.py analysis redact <file>` | The file's text with credentials masked |
-| `validate` | `python3 <skill-dir>/scripts/qa_tool.py analysis validate <instance.json> <schema.json>` | `{valid: bool, errors: [...]}`; exit 1 when invalid |
-| `classify` | `python3 <skill-dir>/scripts/qa_tool.py analysis classify "<error message>" [--http-status N]` | `{classification, confidence, reason}` from the shared taxonomy |
-| `context` | `python3 <skill-dir>/scripts/qa_tool.py analysis context [--root DIR] [--path .qa/context.md]` | The parsed, schema-validated project context as JSON |
-| `report-html` | `python3 <skill-dir>/scripts/qa_tool.py analysis report-html <result.json> [--out report.html]` | The result rendered as one self-contained HTML report — every required field, footer included. Run it instead of writing HTML |
-| `branding` | `python3 <skill-dir>/scripts/qa_tool.py analysis branding --format markdown\|html\|text` | The exact attribution footer bytes for a **rendered** report (never for a JSON artifact) |
-
-## 3. Diagnostic engine — `qa_tool.py diagnostics`
+| `junit` | `node <skill-dir>/scripts/qa-tool.mjs analysis junit <report.xml>` | `{tests: {...}, executed: [...]}` normalized counts and per-test outcomes |
+| `har` | `node <skill-dir>/scripts/qa-tool.mjs analysis har <file.har> [--slow-ms N]` | Redacted request/response summary, failures, slow calls |
+| `discover` | `node <skill-dir>/scripts/qa-tool.mjs analysis discover [--root DIR] [--path P]` | Artifacts found, by type, with presence flags |
+| `diff-guard` | `node <skill-dir>/scripts/qa-tool.mjs analysis diff-guard <diff-file>` | `{issues: [...], safe: bool}` — `safe:false` blocks the change |
+| `redact` | `node <skill-dir>/scripts/qa-tool.mjs analysis redact <file>` | The file's text with credentials masked |
+| `validate` | `node <skill-dir>/scripts/qa-tool.mjs analysis validate <instance.json> <schema.json>` | `{valid: bool, errors: [...]}`; exit 1 when invalid |
+| `classify` | `node <skill-dir>/scripts/qa-tool.mjs analysis classify "<error message>" [--http-status N]` | `{classification, confidence, reason}` from the shared taxonomy |
+| `context` | `node <skill-dir>/scripts/qa-tool.mjs analysis context [--root DIR] [--path .qa/context.md]` | The parsed, schema-validated project context as JSON |
+| `report-html` | `node <skill-dir>/scripts/qa-tool.mjs analysis report-html <result.json> [--out report.html]` | The result rendered as one self-contained HTML report — every required field, footer included. Run it instead of writing HTML |
+| `branding` | `node <skill-dir>/scripts/qa-tool.mjs analysis branding --format markdown\|html\|text` | The exact attribution footer bytes for a **rendered** report (never for a JSON artifact) |
+
+## 3. Diagnostic engine — `qa-tool.mjs diagnostics`
 
 One engine, consumed by the diagnostic skills. Reasoning lives here once.
 
 | Subcommand | Invocation | Returns |
 | --- | --- | --- |
-| `diagnose` | `python3 <skill-dir>/scripts/qa_tool.py diagnostics diagnose --execution-result <path> [--analysis-result <path>]` | `{entries: [...], timeline: [...], recommendations: [...]}` |
-| `plan-repairs` | `python3 <skill-dir>/scripts/qa_tool.py diagnostics plan-repairs --diagnosis <path>` | `{plans: [...]}` — one plan per entry, escalations included |
-| `summarize` | `python3 <skill-dir>/scripts/qa_tool.py diagnostics summarize --execution-result <path> --diagnosis <path>` | `{totals, byClassification, topPriority, releaseReadiness}` |
-| `report` | `python3 <skill-dir>/scripts/qa_tool.py diagnostics report --execution-result <path> [--analysis-result <path>]` | `{diagnosis, plans, summary}` — all three in one call |
+| `diagnose` | `node <skill-dir>/scripts/qa-tool.mjs diagnostics diagnose --execution-result <path> [--analysis-result <path>]` | `{entries: [...], timeline: [...], recommendations: [...]}` |
+| `plan-repairs` | `node <skill-dir>/scripts/qa-tool.mjs diagnostics plan-repairs --diagnosis <path>` | `{plans: [...]}` — one plan per entry, escalations included |
+| `summarize` | `node <skill-dir>/scripts/qa-tool.mjs diagnostics summarize --execution-result <path> --diagnosis <path>` | `{totals, byClassification, topPriority, releaseReadiness}` |
+| `report` | `node <skill-dir>/scripts/qa-tool.mjs diagnostics report --execution-result <path> [--analysis-result <path>]` | `{diagnosis, plans, summary}` — all three in one call |
 
 **Inputs.** `--execution-result` takes a `qa-run` execution result, or the minimal
 subset (`tests` counts plus `executed[]` entries carrying `status`).
@@ -101,7 +103,7 @@ contract names:
 
 This mapping is not busywork: the strictness is what stops a skill from shipping a
 result whose shape nobody checked. Validate before completion —
-`python3 <skill-dir>/scripts/qa_tool.py analysis validate <result.json> <schema.json>` — and fix the
+`node <skill-dir>/scripts/qa-tool.mjs analysis validate <result.json> <schema.json>` — and fix the
 result, never the claim.
 
 ## 4. Framework adapters
@@ -111,11 +113,11 @@ a `--framework` flag.
 
 | Adapter | Invocation | Returns |
 | --- | --- | --- |
-| Playwright report | `python3 <skill-dir>/scripts/qa_tool.py playwright report <results.json>` | The same `{tests, executed}` shape as `junit` |
-| Playwright trace | `python3 <skill-dir>/scripts/qa_tool.py playwright trace <trace.zip>` | Actions, console/network counts, errors, classification |
+| Playwright report | `node <skill-dir>/scripts/qa-tool.mjs playwright report <results.json>` | The same `{tests, executed}` shape as `junit` |
+| Playwright trace | `node <skill-dir>/scripts/qa-tool.mjs playwright trace <trace.zip>` | Actions, console/network counts, errors, classification |
 
 For Selenium, Cypress, and WebdriverIO, normalize through
-`qa_tool.py analysis junit` — those adapters have no richer artifact than JUnit, and
+`qa-tool.mjs analysis junit` — those adapters have no richer artifact than JUnit, and
 the skill says so rather than implying trace-grade depth.
 
 ## 5. Reporting what ran