qa-engineer 0.9.2 → 0.10.0

package/packages/engine/lib/diagnostics/repair.mjs

@@ -0,0 +1,73 @@
+// Deterministic repair planning.
+//
+// Turns a root cause into a repair *plan* — never code. It decides whether the
+// failure is test-side repairable at all, and if so proposes an abstract change,
+// the candidate type, the risk, and a rollback. qa-fix consumes these plans; the
+// plan is always gated by the diff guard and always requires permission before any
+// edit is applied.
+
+import * as taxonomy from '../analysis/taxonomy.mjs';
+
+// classification -> [repairable, candidate type, abstract change, risk].
+// Only test-side causes are repairable; product, network, infra, authorization and
+// environment failures are escalations, not repairs.
+const PLANS = {
+  [taxonomy.LOCATOR]: [true, 'locator-update',
+    'Update the failing locator to target the same element in the current DOM.', 'low'],
+  [taxonomy.ASSERTION]: [true, 'assertion-improvement',
+    'Correct the assertion to match the intended behavior, or confirm a product bug first.', 'medium'],
+  [taxonomy.TIMEOUT]: [true, 'wait-strategy',
+    'Replace a fixed or missing wait with a web-first wait on the awaited condition.', 'medium'],
+  [taxonomy.FLAKY]: [true, 'synchronization',
+    'Remove the race by awaiting the real condition; add a tracked quarantine only if needed.', 'medium'],
+  [taxonomy.TEST_DATA]: [true, 'test-data',
+    'Repair or reseed the test data the scenario depends on.', 'medium'],
+  [taxonomy.CONFIGURATION]: [true, 'configuration',
+    'Correct the test configuration the run depends on.', 'low'],
+  [taxonomy.ENVIRONMENT]: [false, 'environment',
+    'Fix the environment (base URL, service availability); not a test-side repair.', 'n/a'],
+  [taxonomy.AUTH]: [true, 'authentication',
+    "Repair the test's credentials or auth setup; do not weaken the check.", 'medium'],
+  [taxonomy.AUTHORIZATION]: [false, 'authorization',
+    'Grant the test account permission or use an authorized role; not a code repair.', 'n/a'],
+  [taxonomy.NETWORK]: [false, 'network',
+    'Investigate the upstream service; not a test-side repair.', 'n/a'],
+  [taxonomy.INFRASTRUCTURE]: [false, 'infrastructure',
+    'Escalate to CI/infra; not a test-side repair.', 'n/a'],
+  [taxonomy.APPLICATION_BUG]: [false, 'application-bug',
+    'File a product bug; the test correctly caught a real defect.', 'n/a'],
+  [taxonomy.FRAMEWORK]: [false, 'framework',
+    'Update or pin the framework/driver; not a test-side repair.', 'n/a'],
+  [taxonomy.UNKNOWN]: [false, 'unknown',
+    'Investigate further before any repair.', 'n/a'],
+};
+
+/**
+ * Produce a repair plan for a root cause.
+ *
+ * `{repairable, candidateType, proposedChanges, affectedFiles, risk,
+ * permissionRequired, rollbackStrategy, safetyReview}`. Never contains code.
+ */
+export function planRepair(rootCause, affectedFiles = null) {
+  const [repairable, candidate, change, risk] =
+    PLANS[rootCause.classification] ?? PLANS[taxonomy.UNKNOWN];
+
+  const safety = repairable
+    ? 'Any edit will be checked by the diff guard before it is proposed as complete; ' +
+      'the guard rejects removed assertions, added skips, forced passes, and timeout inflation.'
+    : 'No test-side edit is appropriate; this is an escalation, not a repair.';
+  const rollback = repairable
+    ? 'No source is changed without approval; revert the proposed edits to roll back.'
+    : 'Not applicable — no change is proposed.';
+
+  return {
+    repairable,
+    candidateType: candidate,
+    proposedChanges: repairable ? [change] : [],
+    affectedFiles: [...(affectedFiles ?? [])],
+    risk,
+    permissionRequired: true,
+    rollbackStrategy: rollback,
+    safetyReview: safety,
+  };
+}

package/packages/engine/lib/diagnostics/root-cause.mjs

@@ -0,0 +1,92 @@
+// Deterministic root-cause analysis.
+//
+// Turns a failure signal into a classified root cause with the four things every
+// classification must carry: a taxonomy class (with confidence and evidence-backed
+// reason), a recommended action, and an owner. It reuses the analysis platform's
+// failure taxonomy; it adds the ownership and recommendation mappings and the
+// metadata-driven classes (flaky) the taxonomy cannot infer from a message alone.
+//
+// No unsupported conclusions: a signal that matches no rule is `unknown`.
+
+import * as taxonomy from '../analysis/taxonomy.mjs';
+
+/** classification -> the party that typically owns the fix. */
+export const OWNERSHIP = {
+  [taxonomy.ASSERTION]: 'test-author-or-product',
+  [taxonomy.LOCATOR]: 'test-author',
+  [taxonomy.TIMEOUT]: 'test-author-or-environment',
+  [taxonomy.NETWORK]: 'backend-or-infrastructure',
+  [taxonomy.AUTH]: 'auth-or-test-setup',
+  [taxonomy.AUTHORIZATION]: 'permissions-or-test-account',
+  [taxonomy.ENVIRONMENT]: 'environment-owner',
+  [taxonomy.CONFIGURATION]: 'config-owner',
+  [taxonomy.INFRASTRUCTURE]: 'ci-or-infrastructure',
+  [taxonomy.TEST_DATA]: 'test-data-owner',
+  [taxonomy.APPLICATION_BUG]: 'product',
+  [taxonomy.FRAMEWORK]: 'framework-or-driver',
+  [taxonomy.FLAKY]: 'test-author',
+  [taxonomy.UNKNOWN]: 'needs-triage',
+};
+
+// classification -> the safe recommended action (implements the analysis
+// platform's recommendation-guidelines; never recommends forcing a pass).
+export const RECOMMENDATION = {
+  [taxonomy.ASSERTION]: 'Confirm whether the app or the expectation is wrong; fix whichever is genuinely incorrect.',
+  [taxonomy.LOCATOR]: 'Inspect the current DOM and update the locator to target the same element.',
+  [taxonomy.TIMEOUT]: 'Investigate the slowness; raise a wait only if the operation is legitimately slower.',
+  [taxonomy.NETWORK]: 'Check the upstream service and the request; retry only if the failure is genuinely transient.',
+  [taxonomy.AUTH]: 'Fix the credentials or auth setup; do not weaken the authentication check.',
+  [taxonomy.AUTHORIZATION]: 'Grant the test account the needed permission or use an authorized role; do not bypass the check.',
+  [taxonomy.ENVIRONMENT]: 'Fix the environment (base URL, service availability); the test is likely fine.',
+  [taxonomy.CONFIGURATION]: 'Correct the configuration; do not work around it in the test.',
+  [taxonomy.INFRASTRUCTURE]: 'Escalate to CI or infrastructure owners; add resources, do not shrink the suite.',
+  [taxonomy.TEST_DATA]: 'Repair or reseed the data; do not delete the assertion that caught the gap.',
+  [taxonomy.APPLICATION_BUG]: 'File a bug against the product; do NOT modify the test to pass.',
+  [taxonomy.FRAMEWORK]: 'Update or pin the framework/driver; report upstream if it is a genuine defect.',
+  [taxonomy.FLAKY]: 'Stabilize the test (fix the race or synchronization); quarantine only with a tracking issue.',
+  [taxonomy.UNKNOWN]: 'Investigate further; the evidence was insufficient to classify.',
+};
+
+/**
+ * Classify a failure signal into a root cause.
+ *
+ * `signal` may carry: message, httpStatus, retries, finalStatus, classification,
+ * confidence, reason, evidence. Returns
+ * `{classification, confidence, reason, ownership, recommendation, evidence}`.
+ */
+export function analyze(signal) {
+  const message = signal.message ?? '';
+  const httpStatus = signal.httpStatus;
+  const retries = signal.retries || 0;
+  const finalStatus = signal.finalStatus;
+  const provided = signal.classification;
+
+  let classification;
+  let confidence;
+  let reason;
+
+  // Flakiness is a metadata signal, not a message pattern: a test that needed a
+  // retry to pass, or is explicitly flagged flaky, is nondeterministic.
+  if (finalStatus === 'flaky' || (retries > 0 && ['passed', 'flaky'].includes(finalStatus))) {
+    classification = taxonomy.FLAKY;
+    confidence = 0.8;
+    reason = 'The test passed only after a retry, indicating nondeterministic behavior.';
+  } else if (taxonomy.CLASSES.has(provided)) {
+    // The analysis platform already classified this deterministically; trust it
+    // rather than re-deriving from the message.
+    classification = provided;
+    confidence = 'confidence' in signal ? signal.confidence : 0.8;
+    reason = signal.reason || `Classified ${provided} by the analysis platform.`;
+  } else {
+    ({ classification, confidence, reason } = taxonomy.classify(message, httpStatus ?? null));
+  }
+
+  return {
+    classification,
+    confidence,
+    reason,
+    ownership: OWNERSHIP[classification] ?? 'needs-triage',
+    recommendation: RECOMMENDATION[classification] ?? RECOMMENDATION[taxonomy.UNKNOWN],
+    evidence: signal.evidence ?? [],
+  };
+}

package/packages/engine/lib/diagnostics/timeline.mjs

@@ -0,0 +1,101 @@
+// Deterministic timeline reconstruction.
+//
+// Reconstructs the ordered sequence of a run — start, browser launch, navigation,
+// requests and responses, console errors, assertions, failure, cleanup — from the
+// execution result and the analysis findings. It records only stages for which there
+// is evidence; it never invents an event to fill the shape. Reusable by qa-debug and
+// qa-report.
+
+// Canonical phase order, used to sort events that share (or lack) a timestamp.
+export const PHASE_ORDER = [
+  'execution-start', 'browser-launch', 'navigation', 'request', 'response',
+  'console-error', 'assertion', 'failure', 'cleanup', 'execution-finish',
+];
+const PHASE_INDEX = new Map(PHASE_ORDER.map((phase, index) => [phase, index]));
+
+// Evidence type -> the timeline phase it contributes.
+const EVIDENCE_PHASE = {
+  network: 'response',
+  console: 'console-error',
+  trace: 'navigation',
+  junit: 'assertion',
+  report: 'assertion',
+};
+
+/**
+ * Build an ordered timeline: `[{order, phase, detail, source, timestamp?}]`.
+ *
+ * Deterministic: same inputs, same timeline. Only evidenced stages appear.
+ */
+export function buildTimeline(executionResult, findings = null) {
+  const events = [];
+  const execution = (executionResult ?? {}).execution ?? {};
+
+  const started = execution.startedAt;
+  if (started || (executionResult !== null && executionResult !== undefined && truthy(executionResult))) {
+    events.push(event('execution-start', 'Run started', 'execution-result', started ?? null));
+  }
+
+  // Contribute a stage per evidence entry we actually have.
+  for (const finding of findings ?? []) {
+    for (const item of finding.evidence ?? []) {
+      const phase = EVIDENCE_PHASE[item.type];
+      if (phase) {
+        events.push(event(phase, item.description ?? '', item.source ?? 'analysis', null));
+      }
+    }
+  }
+
+  // A failure stage per failed test recorded in the result.
+  for (const test of (executionResult ?? {}).executed ?? []) {
+    if (test.status === 'failed') {
+      events.push(event('failure', `Test failed: ${test.title ?? ''}`,
+        test.file ?? 'execution-result', null));
+    }
+  }
+
+  const finished = execution.finishedAt;
+  if (finished) {
+    events.push(event('cleanup', 'Run cleaned up', 'execution-result', null));
+    events.push(event('execution-finish', 'Run finished', 'execution-result', finished));
+  }
+
+  // Deterministic order: by canonical phase first (it encodes the logical
+  // sequence), then by timestamp within a phase, then by insertion order. Phase
+  // order is primary because per-event wall-clock times are often unavailable.
+  const decorated = events.map((entry, seq) => ({ entry, seq }));
+  decorated.sort((a, b) => {
+    const phaseDelta = (PHASE_INDEX.get(a.entry.phase) ?? 99) - (PHASE_INDEX.get(b.entry.phase) ?? 99);
+    if (phaseDelta !== 0) return phaseDelta;
+    const left = a.entry.timestamp || '';
+    const right = b.entry.timestamp || '';
+    if (left !== right) return left < right ? -1 : 1;
+    return a.seq - b.seq;
+  });
+
+  // Key order matters: these events are serialized and compared byte-for-byte
+  // against the Python implementation, which builds phase/detail/source/timestamp
+  // and then appends `order`. Assigning `order` before `timestamp` would produce
+  // the same data in a different JSON shape.
+  return decorated.map(({ entry }, order) => {
+    const result = { phase: entry.phase, detail: entry.detail, source: entry.source };
+    if (entry.timestamp !== null && entry.timestamp !== undefined) result.timestamp = entry.timestamp;
+    result.order = order;
+    return result;
+  });
+}
+
+function event(phase, detail, source, timestamp) {
+  return { phase, detail, source, timestamp };
+}
+
+/**
+ * Python's `if started or execution_result:` treats an empty dict as falsey, so a
+ * bare `{}` produces no start event while `{"tests": {...}}` does. JavaScript
+ * considers every object truthy, so the emptiness has to be asked about directly.
+ */
+function truthy(value) {
+  if (Array.isArray(value)) return value.length > 0;
+  if (value && typeof value === 'object') return Object.keys(value).length > 0;
+  return Boolean(value);
+}

package/packages/engine/lib/frameworks/junit-frameworks.mjs

@@ -0,0 +1,48 @@
+// The JUnit-XML frameworks: Selenium, Cypress, WebdriverIO.
+//
+// All three emit JUnit XML, so their normalization *is* the framework-agnostic JUnit
+// parser — each adapter only points at the right artifact and tags provenance. That
+// thinness is the proof of the pack's multi-framework claim: the second, third and
+// fourth frameworks cost a few lines each, because the contract and the parsing are
+// shared and only the artifact location differs (ADR-0013).
+//
+// The three lived in separate Python modules that were identical but for a name and
+// a glob list. Here they are one table, because three copies of the same four lines
+// is three places for them to drift.
+
+import { parseJUnit } from '../analysis/junit.mjs';
+import { classify } from '../analysis/taxonomy.mjs';
+
+/** framework -> where that framework's runners conventionally write JUnit XML. */
+export const RESULT_GLOBS = {
+  selenium: ['**/target/surefire-reports/*.xml', '**/test-results/*.xml', '**/junit*.xml'],
+  cypress: ['**/results/*.xml', '**/cypress/results/*.xml', '**/junit*.xml'],
+  webdriverio: ['**/junit*.xml', '**/results/*.xml', '**/test-results/*.xml'],
+};
+
+export const FRAMEWORKS = Object.keys(RESULT_GLOBS);
+
+/**
+ * Normalize a run into the shared result shape.
+ *
+ * Identical output for every framework — that is the point. The `framework`
+ * argument selects nothing in the parsing; it exists so a caller can be explicit
+ * about provenance and so an unknown name is refused rather than silently treated
+ * as one of the three.
+ */
+export function normalize(framework, junitPath) {
+  if (!Object.prototype.hasOwnProperty.call(RESULT_GLOBS, framework)) {
+    throw new Error(`unknown JUnit framework: ${framework} (known: ${FRAMEWORKS.join(', ')})`);
+  }
+  return parseJUnit(junitPath);
+}
+
+/**
+ * Classify a failure using the shared taxonomy.
+ *
+ * There is no per-framework classifier, because failure classes are
+ * framework-agnostic: a missing element is a locator failure whoever reported it.
+ */
+export function classifyFailure(message, httpStatus = null) {
+  return classify(message, httpStatus);
+}

package/packages/engine/lib/frameworks/playwright.mjs

@@ -0,0 +1,158 @@
+// Playwright-specific analyzers: trace and JSON report.
+//
+// This is the Playwright *adapter* for the analysis platform. It depends on the
+// framework-agnostic analysis core for the evidence model, redaction, and the
+// failure taxonomy; it adds only what is Playwright-specific — the shape of a
+// trace.zip and of Playwright's JSON reporter. Everything it emits is in the shared
+// normalized shape, so nothing downstream knows it was Playwright.
+//
+// Framework knowledge stays inside the adapter: the core never grows a
+// `--framework` flag (ADR-0013).
+
+import fs from 'node:fs';
+
+import { MalformedArtifact } from '../analysis/junit.mjs';
+import { redactText } from '../analysis/redaction.mjs';
+import * as taxonomy from '../analysis/taxonomy.mjs';
+import { openZip, isZip, ZipError } from '../analysis/zip.mjs';
+
+export const FRAMEWORK = 'playwright';
+
+/**
+ * Parse Playwright's JSON reporter output into the normalized result shape.
+ *
+ * Mirrors the JUnit parser's output (`{tests, executed}`) so a Playwright run
+ * normalizes identically whether it emitted JSON or JUnit.
+ */
+export function parseReport(path) {
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw new MalformedArtifact(`could not parse Playwright report at ${path}: ${error.message}`);
+  }
+
+  const executed = [];
+  for (const suite of data.suites ?? []) walkSuite(suite, executed);
+
+  return {
+    tests: {
+      total: executed.length,
+      passed: executed.filter((e) => e.status === 'passed').length,
+      failed: executed.filter((e) => e.status === 'failed').length,
+      skipped: executed.filter((e) => e.status === 'skipped').length,
+    },
+    executed,
+  };
+}
+
+function walkSuite(suite, executed) {
+  for (const spec of suite.specs ?? []) {
+    for (const test of spec.tests ?? []) {
+      const results = test.results ?? [];
+      const status = statusOf(results);
+      let message = '';
+      if (status === 'failed' && results.length > 0) {
+        const errors = results[results.length - 1].errors ?? [];
+        if (errors.length > 0) {
+          message = redactText((errors[0].message ?? '').trim());
+        }
+      }
+      const entry = {
+        title: spec.title ?? '',
+        file: suite.file ?? '',
+        status,
+        durationMs: results.length > 0 ? (results[results.length - 1].duration ?? 0) : 0,
+        retries: Math.max(0, results.length - 1),
+      };
+      if (message) entry.message = message;
+      executed.push(entry);
+    }
+  }
+  for (const child of suite.suites ?? []) walkSuite(child, executed);
+}
+
+function statusOf(results) {
+  if (results.length === 0) return 'skipped';
+  const final = results[results.length - 1].status;
+  if (final === 'passed' || final === 'expected') return results.length > 1 ? 'flaky' : 'passed';
+  if (final === 'skipped') return 'skipped';
+  return 'failed';
+}
+
+/**
+ * Extract a deterministic summary from a Playwright trace.zip.
+ *
+ * A trace is a zip of newline-delimited JSON event files. This lists the actions,
+ * surfaces the last error, and counts console and network events — enough for a
+ * diagnostic skill to reason over, without decoding the full binary.
+ */
+export function analyzeTrace(path) {
+  let archive;
+  try {
+    const buffer = fs.readFileSync(path);
+    if (!isZip(buffer)) throw new MalformedArtifact(`not a valid trace zip: ${path}`);
+    archive = openZip(path);
+  } catch (error) {
+    if (error instanceof MalformedArtifact) throw error;
+    throw new MalformedArtifact(`not a valid trace zip: ${path}`);
+  }
+
+  const actions = [];
+  const errors = [];
+  let console = 0;
+  let network = 0;
+
+  try {
+    const named = archive.entries.filter(
+      (entry) => entry.name.endsWith('.trace') || entry.name.endsWith('.jsonl') || entry.name.includes('trace'),
+    );
+    for (const entry of named.length > 0 ? named : archive.entries) {
+      const text = archive.read(entry).toString('utf8');
+      for (const line of text.split('\n')) {
+        const raw = line.trim();
+        if (!raw || !raw.startsWith('{')) continue;
+        let event;
+        try {
+          event = JSON.parse(raw);
+        } catch {
+          continue;
+        }
+        const kind = event.type ?? event.kind;
+        if (kind === 'action' || kind === 'before') {
+          actions.push(redactText(String(event.apiName ?? event.method ?? '')));
+        } else if (kind === 'console') {
+          console += 1;
+        } else if (kind === 'resource' || kind === 'network' || kind === 'http') {
+          network += 1;
+        }
+        if (event.error || kind === 'error') {
+          const message = event.error && typeof event.error === 'object'
+            ? event.error.message
+            : event.message;
+          if (message) errors.push(redactText(String(message)));
+        }
+      }
+    }
+  } catch (error) {
+    if (error instanceof ZipError) {
+      throw new MalformedArtifact(`could not read trace ${path}: ${error.message}`);
+    }
+    throw error;
+  }
+
+  const lastError = errors.length > 0 ? errors[errors.length - 1] : '';
+  const classified = lastError
+    ? taxonomy.classify(lastError)
+    : { classification: taxonomy.UNKNOWN, confidence: 0.2, reason: 'No error found in trace.' };
+
+  return {
+    actions: actions.filter(Boolean),
+    consoleEvents: console,
+    networkEvents: network,
+    errors,
+    classification: classified.classification,
+    confidence: classified.confidence,
+    reason: classified.reason,
+  };
+}

package/packages/engine/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@qa-engineer/engine",
+  "version": "0.9.2",
+  "description": "Deterministic QA analysis engine — zero dependencies, Node only",
+  "license": "MIT",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "exports": {
+    "./analysis/*": "./lib/analysis/*.mjs"
+  }
+}

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

@@ -6,8 +6,8 @@ import { EXIT, SHARED_SKILLS_DIR } from '../constants.mjs';
 import { resolveSourceRoot, resolveProjectRoot } from '../core/paths.mjs';
 import { VERSION, SPEC_REVISION } from '../version.mjs';
 import { AGENTS, resolveInstallTargets, listAgentIds } from '../agents/registry.mjs';
-import { packHasBundles, findPython, verifyImports } from '../core/bundle.mjs';
-import { BUNDLE_DEST, BUNDLE_MANIFEST, bundlePackagesForSkill } from '../core/manifest.mjs';
+import { packHasBundles, verifyEngine } from '../core/bundle.mjs';
+import { BUNDLE_DEST, BUNDLE_MANIFEST } from '../core/manifest.mjs';
 import { readLock } from '../core/lockfile.mjs';
 import { createLogger } from '../core/logger.mjs';
 import { parseCommonFlags } from '../cli/flags.mjs';
@@ -46,7 +46,6 @@ Each failure includes an exact repair command.`);
   const detected = AGENTS.filter((a) => a.detect(root)).map((a) => a.id);
   const targets = resolveInstallTargets(root, opts.agents).map((a) => a.id);
   const lock = readLock(root);
-  const python = findPython();
   const gitOk = hasGit(root);
   const scan = scanProject(root, opts.agents);
   const validation = lock ? validateInstall(root) : null;
@@ -62,13 +61,6 @@ Each failure includes an exact repair command.`);
     message: `Node ${process.version}`,
     hint: nodeMajor >= 18 ? undefined : 'upgrade to Node.js 18.18+',
   });
-  checklist.push({
-    section: 'Environment',
-    id: 'python',
-    ok: Boolean(python),
-    message: python ? `${python.bin} (${python.version})` : 'Python not found',
-    hint: python ? undefined : 'install Python 3.8+ for analysis/diagnostics engines',
-  });
   checklist.push({
     section: 'Environment',
     id: 'git',
@@ -114,18 +106,18 @@ Each failure includes an exact repair command.`);
     });
   }
 
-  // Deep Python import check when bundles are on disk
-  if (lock && packHasBundles() && python) {
+  // Deep check: the bundled engine must RUN, not merely be present. It runs under
+  // this same Node, so there is no interpreter to look for and no reason to skip.
+  if (lock && packHasBundles()) {
     const bundledSkill = Object.keys(BUNDLE_MANIFEST)[0];
     const libDir = path.join(root, SHARED_SKILLS_DIR, bundledSkill, BUNDLE_DEST);
     const claudeLib = path.join(root, '.claude', 'skills', bundledSkill, BUNDLE_DEST);
     const resolvedLib = fs.existsSync(libDir) ? libDir : fs.existsSync(claudeLib) ? claudeLib : null;
     if (resolvedLib) {
-      const packages = bundlePackagesForSkill(bundledSkill);
-      const result = verifyImports({ pythonBin: python.bin, libDir: resolvedLib, packages });
+      const result = verifyEngine({ libDir: resolvedLib });
       checklist.push({
         section: 'QA Engineer Pack',
-        id: 'engine-imports',
+        id: 'engine-runs',
         ok: result.ok,
         message: result.ok ? 'bundled engine runs cleanly' : `engine check failed: ${result.stderr}`,
         hint: result.ok ? undefined : 'run: qa repair',
@@ -149,7 +141,6 @@ Each failure includes an exact repair command.`);
     installTargets: targets,
     lockfilePresent: Boolean(lock),
     lockfilePack: lock?.pack ?? null,
-    python,
     bundles: packHasBundles(),
     node: process.version,
     git: gitOk,

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

@@ -226,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);
 
@@ -275,6 +299,9 @@ 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);
@@ -288,6 +315,7 @@ export async function executeInstall({
     skills: skills.length,
     files: unique.length,
     lockfile: dryRun ? null : LOCKFILE,
+    removed: orphans,
     validation,
   };
 }