qa-engineer 0.9.2 → 0.10.0

package/COMPATIBILITY.md

@@ -9,7 +9,8 @@ This document records which AI coding agents the pack targets, how each one disc
 | Pack version | Released | Discovery paths verified against agent docs | Live agent runs |
 | --- | --- | --- | --- |
 | 0.9.0, 0.9.1 | 2026-07-28 | Not systematically re-read for the release | Claude Code, Cursor (manual, by the maintainer) |
-| 0.9.2 | 2026-07-28 | Yes — every host's own documentation, re-read on 2026-07-28 (sources in the matrix below) | Claude Code, Cursor (manual, by the maintainer) |
+| 0.9.2 | 2026-07-28 | Yes — every host's own documentation, re-read on 2026-07-28 (sources in the matrix below) | **Do not use.** The tarball omitted the engine; every command failed on a missing module |
+| 0.9.3 | 2026-07-28 | Yes, as 0.9.2 | Claude Code, Cursor (manual, by the maintainer) |
 
 "Verified" in the third column means the discovery paths in the matrix below were read off each host's own documentation on that date and are asserted against the installer by `packages/installer/test/hosts.test.mjs`, which fails if the installer writes to a path that host does not document reading. It does **not** mean the pack was executed inside every host: that is the Tier 1 bar, and only Claude Code and Cursor have had a real run.
 
@@ -55,8 +56,14 @@ The tier column in the matrix above is the **planned** tier — the level each a
 
 | Requirement | Status | Used for |
 | --- | --- | --- |
-| Python 3.8+ | Required for analysis | The deterministic analysis toolkit (`shared/analysis/lib/`) and framework analyzers — standard library only, no packages |
-| Node.js 18+ | Required for the installer CLI | `npx qa-engineer` / `qa install` / `qa doctor` / `qa self-test` (interactive onboarding uses `--yes` / `--ci` in non-TTY and CI) |
+| Node.js 18.17+ | The only requirement | Everything: `npx qa-engineer` and the CLI, and the deterministic engine the skills run (`packages/engine/`) |
+
+**One runtime, no dependencies.** Until 0.9.2 the engine was Python, which meant a
+second runtime users had to install for tooling they had installed with Node — and
+when it was missing, skills fell back to model guesswork and said nothing.
+[ADR-0012](docs/architecture/ADR-0012-node-engine.md) records why that changed and
+how the migration was verified. The engine still takes no third-party dependencies:
+the XML and ZIP readers it needs are written out rather than depended on.
 
 ## Operating systems
 
@@ -66,15 +73,22 @@ The tier column in the matrix above is the **planned** tier — the level each a
 | macOS | Expected to work; not covered by CI |
 | Windows | Expected to work; **not yet verified end to end** |
 
-The installer uses Node's platform-independent path handling, and the skills
-invoke their bundled engine through a launcher (`scripts/qa_tool.py`) that needs
-no shell features — the command shape is identical in bash, zsh, PowerShell, and
-cmd.exe. The one difference on Windows is the interpreter name: use `python` where
-`python3` is not on PATH.
-
-Until a Windows run is confirmed, that row says "expected", not "supported".
-
-The analysis toolkit is standard-library-only Python, so it runs on any Python 3.8+ interpreter with nothing to install. Requirements are declared per skill via the specification's `compatibility` frontmatter field, and the pack degrades gracefully: skills describe a manual fallback whenever a runtime or optional integration (such as an MCP server) is unavailable.
+The installer uses Node's platform-independent path handling, and the skills invoke
+the engine through a committed launcher (`scripts/qa-tool.mjs`) that needs no shell
+features — the command shape is identical in bash, zsh, PowerShell, and cmd.exe,
+with no platform difference at all.
+
+The Windows row said "expected" for a specific reason that no longer applies: the
+engine was Python, and `python3` is not on PATH on Windows by default, so every
+deterministic call there failed and each skill quietly fell back to guesswork. The
+engine is now the same Node that ran the install. The row still says "expected"
+rather than "supported" because nobody has run the pack end to end on Windows —
+that is an unverified claim, not a known gap.
+
+Requirements are declared per skill via the specification's `compatibility`
+frontmatter field, and the pack degrades gracefully: skills describe a manual
+fallback whenever a runtime or optional integration (such as an MCP server) is
+unavailable.
 
 ## Reporting compatibility problems
 

package/README.md

@@ -2,14 +2,13 @@
 
 > Teach your AI coding assistant to work like a senior QA engineer — and stop it from telling you tests pass when they don't.
 
-[![Version](https://img.shields.io/badge/version-0.9.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.10.0-blue.svg)](CHANGELOG.md)
 [![Status](https://img.shields.io/badge/status-public%20preview-orange.svg)](docs/release/v0.9-release-checklist.md)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
-[![Node](https://img.shields.io/badge/node-%E2%89%A518.18-339933.svg)](#step-1--check-your-prerequisites)
-[![Python](https://img.shields.io/badge/python-%E2%89%A53.8-3776AB.svg)](#step-1--check-your-prerequisites)
+[![Node](https://img.shields.io/badge/node-%E2%89%A518.18-339933.svg)](#step-1--check-your-prerequisite)
 [![Agent Skills](https://img.shields.io/badge/Agent%20Skills-spec--native-6E56CF.svg)](https://agentskills.io)
 [![CI](https://github.com/abisheik88/qa-engineer/actions/workflows/ci.yml/badge.svg)](https://github.com/abisheik88/qa-engineer/actions/workflows/ci.yml)
-[![Tests](https://img.shields.io/badge/tests-235%20passing-success.svg)](#how-this-is-verified)
+[![Tests](https://img.shields.io/badge/tests-165%20passing-success.svg)](#how-this-is-verified)
 
 **This page is everything you need.** Install, first run, every command, and what to do when something breaks — no other document required.
 
@@ -19,7 +18,7 @@
 
 1. [What this is, in plain language](#what-this-is-in-plain-language)
 2. [Is this for me?](#is-this-for-me)
-3. [Step 1 — Check your prerequisites](#step-1--check-your-prerequisites)
+3. [Step 1 — Check your prerequisites](#step-1--check-your-prerequisite)
 4. [Step 2 — Install it](#step-2--install-it)
 5. [Step 3 — Confirm it worked](#step-3--confirm-it-worked)
 6. [Step 4 — Your first real task](#step-4--your-first-real-task)
@@ -67,21 +66,26 @@ You do not need to learn a new language, framework, or config file. You install
 
 **Works best with Playwright** today. Selenium, Cypress, and WebdriverIO are detected and their results are understood, but running and generating tests live is currently Playwright-only. See [framework support](#framework-support).
 
-## Step 1 — Check your prerequisites
+## Step 1 — Check your prerequisite
 
-You need two things. Run these two commands to check — copy and paste them exactly:
+You need one thing. Run this to check — copy and paste it exactly:
 
 ```bash
 node --version
-python3 --version
 ```
 
-You want **Node 18.18 or newer** and **Python 3.8 or newer**. If both print a version number that is high enough, skip ahead to [Step 2](#step-2--install-it).
+You want **Node 18.18 or newer**. If it prints a high enough version, skip ahead to
+[Step 2](#step-2--install-it).
+
+That is the whole list. There is nothing to `pip install`, no second language, and no
+dependencies: the tools that read your test results are dependency-free JavaScript
+that runs on the same Node you just checked.
 
 <details>
 <summary><b>"command not found" — how to install Node.js</b></summary>
 
-Node.js gives you the `npx` command used to install this pack.
+Node.js gives you the `npx` command used to install this pack, and it runs the
+analysis tools afterwards.
 
 - **macOS** — `brew install node` (needs [Homebrew](https://brew.sh)), or download from [nodejs.org](https://nodejs.org).
 - **Windows** — download the LTS installer from [nodejs.org](https://nodejs.org) and run it.
@@ -91,19 +95,6 @@ Then re-run `node --version`. Take the **LTS** version if offered a choice.
 
 </details>
 
-<details>
-<summary><b>"command not found" — how to install Python</b></summary>
-
-Python runs the analysis tools that read your test results. It uses only Python's built-in library — there is nothing extra to install, no `pip install` step.
-
-- **macOS** — `brew install python3`, or download from [python.org](https://python.org).
-- **Windows** — install from [python.org](https://python.org) and **tick "Add Python to PATH"** during setup. Then use `python --version` if `python3` is not found.
-- **Linux** — `sudo apt install python3` (Debian/Ubuntu).
-
-**Can you skip Python?** Yes, but you shouldn't. Without it the skills fall back to the AI reading files by eye, and they will mark their results *degraded* to tell you so. The whole point of this project is that the numbers come from tools, not guesses.
-
-</details>
-
 You also need **an AI coding assistant** open on your project — Claude Code, Cursor, GitHub Copilot, Codex CLI, OpenCode, Gemini CLI, Antigravity, or Kimi.
 
 ## Step 2 — Install it
@@ -165,7 +156,7 @@ Real output from a healthy install:
 ✓ [PASS] skills: 13 skill(s) installed
 ✓ [PASS] contracts: 12 contract schema(s) present
 ✓ [PASS] engine: deterministic engine bundled under .agents/skills/qa-init/scripts/lib
-✓ [PASS] python-imports: Python imports OK (python3 Python 3.12.3)
+✓ [PASS] engine-runs: bundled engine runs cleanly
 ✓ [PASS] node: Node v24.18.0
 ✓ self-test PASSED
 ```
@@ -347,10 +338,9 @@ npx qa-engineer install --yes --force --project .
 
 ### A skill says the engine is missing, or results are "degraded"
 
-The Python tools aren't reachable. Fix in this order:
+The deterministic engine isn't reachable. Fix in this order:
 
 ```bash
-python3 --version                          # is Python installed at all?
 npx qa-engineer repair --project .         # reinstall the bundled tools
 npx qa-engineer doctor --project .         # should now say "bundled engine runs cleanly"
 ```
@@ -409,7 +399,7 @@ The core idea in one line: **tools produce the facts, the AI explains them.**
               │  raw output, exit code
               ▼
   ┌───────────────────────────────────┐
-  │  Bundled Python tools             │  count the results, classify the failure,
+  │  Bundled Node engine              │  count the results, classify the failure,
   │  (installed inside the skill)     │  redact secrets — no guessing
   └───────────────────────────────────┘
               │  facts
@@ -459,11 +449,11 @@ Everything below is reproducible from a clone with the command beside it.
 
 | Evidence | Command |
 | --- | --- |
-| 152 analysis, framework, and branding tests | `python3 shared/analysis/lib/run_tests.py` |
-| 28 diagnostic engine tests · 5 seam tests | `PYTHONPATH=shared/analysis/lib:shared/diagnostics/lib python3 -m unittest discover -s shared/diagnostics/lib/tests` |
+| 82 engine tests: analysis, diagnostics, frameworks, seams | `node --test packages/engine/test/*.test.mjs` |
+| The recorded corpus, proven against a second implementation | `node --test packages/engine/test/corpus.test.mjs` |
 | 50 installer tests — including security and repeated-use stress | `npm test` |
 | 21 evaluation cases, including deliberately dishonest outputs the scorer must reject | `npm run validate:evals` |
-| 4 real AI-produced results, scored | `python3 tests/evals/run_live.py --captures claude-opus-5` |
+| 4 real AI-produced results, scored | `node tests/evals/run-live.mjs --captures claude-opus-5` |
 | 17 repository checks — including "documentation matches implementation" | `npm run validate:skills` … |
 
 ## Going deeper

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qa-engineer",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "A vendor-neutral Agent Skills pack that teaches AI coding agents to work like senior QA automation engineers.",
   "license": "MIT",
   "type": "module",
@@ -29,43 +29,34 @@
     "packages/installer/schemas",
     "packages/installer/package.json",
     "packages/installer/README.md",
+    "packages/engine/lib",
+    "packages/engine/bin",
+    "packages/engine/package.json",
     "skills",
-    "shared/analysis/lib/qa_analysis",
-    "shared/analysis/schemas",
-    "shared/diagnostics/lib/qa_diagnostics",
-    "shared/diagnostics/schemas",
-    "shared/tooling/qa_tool.py",
     "shared/frameworks/registry.json",
     "shared/frameworks/registry.schema.json",
     "shared/frameworks/registry.mjs",
-    "shared/frameworks/playwright/lib/playwright_analysis.py",
-    "shared/frameworks/selenium/lib/selenium_analysis.py",
-    "shared/frameworks/cypress/lib/cypress_analysis.py",
-    "shared/frameworks/webdriverio/lib/webdriverio_analysis.py",
     "COMPATIBILITY.md",
-    "!**/__pycache__",
-    "!**/*.pyc",
-    "!**/tests"
+    "!**/tests",
+    "shared/tooling/qa-tool.mjs",
+    "!packages/engine/test"
   ],
   "scripts": {
-    "eval:live": "python3 tests/evals/run_live.py --baseline tests/evals/baselines/reference.json",
-    "prepublishOnly": "npm run validate:release && npm run validate:doc-claims && npm run validate:docs-commands && npm test && npm run validate:python && npm run validate:evals",
+    "eval:live": "node tests/evals/run-live.mjs --baseline tests/evals/baselines/reference.json",
+    "prepublishOnly": "npm run validate:release && npm run validate:doc-claims && npm run validate:docs-commands && npm test && npm run validate:evals",
     "qa": "node packages/installer/bin/qa.mjs",
     "release:checksums": "node scripts/release/release-notes.mjs --checksums",
     "release:notes": "node scripts/release/release-notes.mjs",
     "test": "node --test packages/installer/test/*.test.mjs packages/engine/test/*.test.mjs",
     "validate:architecture": "node scripts/check-architecture-fitness.mjs",
     "validate:branding": "node scripts/check-branding.mjs",
-    "validate:bundle": "python3 scripts/bundle_python.py --check",
-    "validate:context": "cd shared/analysis/lib && python3 -m qa_analysis.cli context --path tests/fixtures/valid-context.md",
     "validate:doc-claims": "node scripts/check-doc-claims.mjs",
     "validate:docs-commands": "node scripts/check-docs-commands.mjs",
-    "validate:engine-parity": "node scripts/check-engine-parity.mjs",
-    "validate:evals": "python3 tests/evals/run_evals.py",
+    "validate:engine": "node --test packages/engine/test/*.test.mjs",
+    "validate:evals": "node tests/evals/run-evals.mjs",
     "validate:keywords": "node scripts/check-keywords.mjs",
     "validate:knowledge": "node scripts/check-knowledge.mjs",
     "validate:matrix": "node scripts/check-capability-matrix.mjs",
-    "validate:python": "python3 shared/analysis/lib/run_tests.py",
     "validate:registry": "node scripts/check-framework-registry.mjs",
     "validate:release": "node scripts/release/validate-release.mjs",
     "validate:release-notes": "node scripts/release/release-notes.mjs --check",

package/packages/engine/bin/qa-engine.mjs

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+// The deterministic engine's command line — how a skill reaches it.
+//
+// One entry point for all three tool groups, replacing three Python CLIs and a
+// launcher. Every subcommand writes JSON to stdout, so an agent never has to invent
+// glue code, and the shapes are checked rather than assumed.
+//
+//   qa-engine analysis    <subcommand> [args]
+//   qa-engine diagnostics <subcommand> [args]
+//   qa-engine playwright  <subcommand> [args]
+//
+// Exit codes are the contract, not an implementation detail. A skill's fallback
+// logic reads them:
+//
+//   0  success
+//   1  a document was read fine but failed its contract (`validate`, `context`)
+//   2  unreadable input, malformed JSON, a failed seam contract, or bad usage
+//
+// Nothing here reasons: it reads files, calls the engine, prints the result. That
+// separation is the whole architecture — deterministic code owns the facts, the
+// model owns the explanation.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import * as junit from '../lib/analysis/junit.mjs';
+import * as har from '../lib/analysis/har.mjs';
+import * as discovery from '../lib/analysis/discovery.mjs';
+import * as diffGuard from '../lib/analysis/diff-guard.mjs';
+import * as redaction from '../lib/analysis/redaction.mjs';
+import * as contracts from '../lib/analysis/contracts.mjs';
+import * as taxonomy from '../lib/analysis/taxonomy.mjs';
+import * as contextModule from '../lib/analysis/context.mjs';
+import * as branding from '../lib/analysis/branding.mjs';
+import * as reportHtml from '../lib/analysis/report-html.mjs';
+import * as diagnostics from '../lib/diagnostics/engine.mjs';
+import {
+  InternalContractError, validateAnalysisResult, validateExecutionResultMin, validateDiagnosis,
+} from '../lib/diagnostics/internal-contracts.mjs';
+import * as playwright from '../lib/frameworks/playwright.mjs';
+import * as junitFrameworks from '../lib/frameworks/junit-frameworks.mjs';
+
+const USAGE = `usage: qa-engine <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
+
+analysis subcommands
+  junit <report.xml>                        normalized {tests, executed}
+  har <file.har> [--slow-ms N]              redacted network summary
+  discover [--root DIR] [--path P ...]      artifacts found, by state
+  diff-guard <diff-file>                    {issues, safe} — safe:false blocks a change
+  redact <file>                             the file's text with secrets masked
+  validate <instance.json> <schema.json>    {valid, errors}; exit 1 when invalid
+  classify "<message>" [--http-status N]    {classification, confidence, reason}
+  context [--root DIR] [--path P]           parsed, schema-checked project context
+  report-html <result.json> [--out FILE]    a self-contained HTML report
+  branding [--format html|markdown|text]    the exact footer bytes for a report
+
+diagnostics subcommands
+  diagnose --execution-result P [--analysis-result P]
+  plan-repairs --diagnosis P
+  summarize --execution-result P --diagnosis P
+  report --execution-result P [--analysis-result P]     all three in one call
+
+playwright subcommands
+  report <results.json>                     the same shape as analysis junit
+  trace <trace.zip>                         actions, errors, and a classification
+
+examples
+  qa-engine analysis junit test-results/results.xml
+  qa-engine analysis report-html qa-artifacts/explore-result.json --out report.html
+  qa-engine diagnostics report --execution-result qa-artifacts/run.json
+`;
+
+function emit(value) {
+  process.stdout.write(`${JSON.stringify(value, sortedReplacer(), 2)}\n`);
+}
+
+/**
+ * Keys are emitted in sorted order, matching the Python CLIs' `sort_keys=True`.
+ * The output is read by people and diffed in CI, so a stable order is part of it.
+ */
+function sortedReplacer() {
+  return function replacer(key, value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) return value;
+    return Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+  };
+}
+
+function fail(error, detail) {
+  emit({ error, detail });
+  return 2;
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+/** Flags, parsed the way the Python argparse CLIs accepted them. */
+function parseFlags(argv, { repeatable = [] } = {}) {
+  const flags = {};
+  const positional = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      positional.push(token);
+      continue;
+    }
+    const [name, inline] = token.slice(2).split('=', 2);
+    const camel = name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    const value = inline !== undefined ? inline : argv[++index];
+    if (repeatable.includes(camel)) {
+      flags[camel] = [...(flags[camel] ?? []), value];
+    } else {
+      flags[camel] = value;
+    }
+  }
+  return { flags, positional };
+}
+
+// Which flags may appear more than once, per subcommand. `discover` accepts a list
+// of explicit paths; `context` names one file. Treating `--path` as repeatable
+// everywhere handed `context` an array and it failed on "path must be a string".
+const REPEATABLE = { discover: ['path'] };
+
+function analysis(argv) {
+  const [subcommand, ...rest] = argv;
+  const { flags, positional } = parseFlags(rest, { repeatable: REPEATABLE[subcommand] ?? [] });
+
+  switch (subcommand) {
+    case 'junit':
+      requirePositional(positional, 1, 'junit <report.xml>');
+      emit(junit.parseJUnit(positional[0]));
+      return 0;
+
+    case 'har':
+      requirePositional(positional, 1, 'har <file.har>');
+      emit(har.parseHar(positional[0], { slowMs: Number(flags.slowMs ?? 1000) }));
+      return 0;
+
+    case 'discover':
+      emit(discovery.discover({ root: flags.root ?? '.', explicit: flags.path ?? null }));
+      return 0;
+
+    case 'diff-guard': {
+      requirePositional(positional, 1, 'diff-guard <diff-file>');
+      const issues = diffGuard.checkDiff(fs.readFileSync(positional[0], 'utf8'));
+      emit({ issues, safe: !issues.some((issue) => issue.severity === 'high') });
+      return 0;
+    }
+
+    case 'redact':
+      requirePositional(positional, 1, 'redact <file>');
+      process.stdout.write(redaction.redactText(fs.readFileSync(positional[0], 'utf8')));
+      return 0;
+
+    case 'validate': {
+      requirePositional(positional, 2, 'validate <instance.json> <schema.json>');
+      const errors = contracts.validate(readJson(positional[0]), readJson(positional[1]));
+      emit({ valid: errors.length === 0, errors });
+      return errors.length === 0 ? 0 : 1;
+    }
+
+    case 'classify': {
+      requirePositional(positional, 1, 'classify "<message>"');
+      const status = flags.httpStatus === undefined ? null : Number(flags.httpStatus);
+      emit(taxonomy.classify(positional[0], status));
+      return 0;
+    }
+
+    case 'context': {
+      const file = flags.path ?? path.join(flags.root ?? '.', '.qa', 'context.md');
+      const schema = contextSchema();
+      const parsed = contextModule.parseFile(file, { schema });
+      emit({
+        path: file,
+        context: parsed.context,
+        valid: parsed.valid,
+        errors: parsed.errors,
+        schemaChecked: schema !== null,
+      });
+      return parsed.valid ? 0 : 1;
+    }
+
+    case 'report-html': {
+      requirePositional(positional, 1, 'report-html <result.json>');
+      const document = reportHtml.renderFile(positional[0], { title: flags.title ?? null });
+      if (flags.out) {
+        fs.writeFileSync(flags.out, document);
+        emit({ written: flags.out, bytes: document.length });
+      } else {
+        process.stdout.write(document);
+      }
+      return 0;
+    }
+
+    case 'branding':
+      // Written to stdout verbatim, not as JSON: the caller embeds these exact
+      // bytes in a rendered report.
+      if (flags.metadata !== undefined) emit(branding.metadata());
+      else process.stdout.write(branding.footer(flags.format ?? 'text'));
+      return 0;
+
+    default:
+      throw new UsageError(`unknown analysis subcommand: ${subcommand ?? '(none)'}`);
+  }
+}
+
+function diagnosticsCommand(argv) {
+  const [subcommand, ...rest] = argv;
+  const { flags } = parseFlags(rest);
+
+  const execution = () => {
+    if (!flags.executionResult) throw new UsageError('--execution-result is required');
+    return validateExecutionResultMin(readJson(flags.executionResult));
+  };
+  const analysisResult = () =>
+    flags.analysisResult ? validateAnalysisResult(readJson(flags.analysisResult)) : null;
+  // A diagnosis handed back in is held to the same seam contract it was emitted
+  // under, so a hand-edited file is refused rather than half-understood.
+  const diagnosisInput = () => {
+    if (!flags.diagnosis) throw new UsageError('--diagnosis is required');
+    return validateDiagnosis(readJson(flags.diagnosis));
+  };
+
+  switch (subcommand) {
+    case 'diagnose':
+      emit(diagnostics.diagnose(execution(), { analysisResult: analysisResult() }));
+      return 0;
+
+    case 'plan-repairs':
+      // Wrapped in {plans}, matching the shape skills already parse. A bare array
+      // would be tidier and would break every caller.
+      emit({ plans: diagnostics.planRepairs(diagnosisInput()) });
+      return 0;
+
+    case 'summarize': {
+      const result = execution();
+      emit(diagnostics.summarize(result, diagnosisInput()));
+      return 0;
+    }
+
+    case 'report': {
+      // The one-shot path: diagnose, plan, and summarize in a single call, so the
+      // common case is one command instead of three.
+      const result = execution();
+      const diagnosis = diagnostics.diagnose(result, { analysisResult: analysisResult() });
+      emit({
+        diagnosis,
+        plans: diagnostics.planRepairs(diagnosis),
+        summary: diagnostics.summarize(result, diagnosis),
+      });
+      return 0;
+    }
+
+    default:
+      throw new UsageError(`unknown diagnostics subcommand: ${subcommand ?? '(none)'}`);
+  }
+}
+
+function playwrightCommand(argv) {
+  const [subcommand, ...rest] = argv;
+  const { positional } = parseFlags(rest);
+  if (subcommand === 'report') {
+    requirePositional(positional, 1, 'report <results.json>');
+    emit(playwright.parseReport(positional[0]));
+    return 0;
+  }
+  if (subcommand === 'trace') {
+    requirePositional(positional, 1, 'trace <trace.zip>');
+    emit(playwright.analyzeTrace(positional[0]));
+    return 0;
+  }
+  throw new UsageError(`unknown playwright subcommand: ${subcommand ?? '(none)'}`);
+}
+
+class UsageError extends Error {}
+
+function requirePositional(positional, count, shape) {
+  if (positional.length < count) throw new UsageError(`usage: qa-engine analysis ${shape}`);
+}
+
+/** The context contract, in whichever layout the engine is running from. */
+function contextSchema() {
+  const candidates = [new URL('../lib/analysis/schemas/context.schema.json', import.meta.url)];
+  for (const candidate of candidates) {
+    const file = candidate.pathname;
+    if (fs.existsSync(file)) return readJson(file);
+  }
+  return null;
+}
+
+export function main(argv = process.argv.slice(2)) {
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    process.stdout.write(USAGE);
+    return argv.length === 0 ? 2 : 0;
+  }
+  if (argv[0] === '--version') {
+    process.stdout.write(`${engineVersion()}\n`);
+    return 0;
+  }
+
+  const [tool, ...rest] = argv;
+  try {
+    if (tool === 'analysis') return analysis(rest);
+    if (tool === 'diagnostics') return diagnosticsCommand(rest);
+    if (tool === 'playwright') return playwrightCommand(rest);
+    process.stderr.write(USAGE);
+    return fail('usage-error', `unknown tool: ${tool}`);
+  } catch (error) {
+    if (error instanceof junit.MalformedArtifact) return fail('malformed-artifact', error.message);
+    if (error instanceof contextModule.MalformedContext) return fail('malformed-context', error.message);
+    if (error instanceof reportHtml.ReportError) return fail('report-error', error.message);
+    if (error instanceof branding.BrandingError) return fail('branding-error', error.message);
+    if (error instanceof InternalContractError) return fail('invalid-payload', error.message);
+    if (error instanceof UsageError) return fail('usage-error', error.message);
+    if (error instanceof SyntaxError) return fail('io-error', error.message);
+    if (error.code === 'ENOENT' || error.code === 'EACCES' || error.code === 'EISDIR') {
+      return fail('io-error', error.message);
+    }
+    throw error;
+  }
+}
+
+function engineVersion() {
+  try {
+    return readJson(new URL('../package.json', import.meta.url).pathname).version;
+  } catch {
+    return '0.0.0';
+  }
+}
+
+process.exitCode = main();