qa-engineer 0.9.0

package/skills/qa-run/contracts/execution-result.schema.json

@@ -0,0 +1,204 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:qa-pack:contract:qa-run:execution-result:1",
+  "title": "qa-run normalized execution result",
+  "description": "The framework-independent record of a completed (or attempted) test run: status, counts, per-test outcomes, collected artifacts, and environment. This is the interface the analysis layer of later milestones consumes; nothing downstream branches on the producing framework. classification is the run status.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contract", "skill", "generatedAt", "summary", "classification", "evidence", "execution", "framework", "tests", "environment", "artifacts"],
+  "allOf": [
+    {
+      "title": "A green claim must be backed by the runner's own numbers",
+      "description": "classification 'passed' requires exit code 0 and zero failing tests. This is the contract-level answer to hallucinated green: an agent cannot emit a valid result that claims success over a non-zero exit code or a failed test.",
+      "if": {
+        "required": ["classification"],
+        "properties": { "classification": { "const": "passed" } }
+      },
+      "then": {
+        "properties": {
+          "execution": { "properties": { "exitCode": { "const": 0 } } },
+          "tests": { "properties": { "failed": { "const": 0 } } }
+        }
+      }
+    },
+    {
+      "title": "A failure claim must point at a failing test",
+      "description": "classification 'failed' requires at least one failing test. A run with no failures is 'passed', 'no-tests-run', or 'errored' — never 'failed'.",
+      "if": {
+        "required": ["classification"],
+        "properties": { "classification": { "const": "failed" } }
+      },
+      "then": {
+        "properties": { "tests": { "properties": { "failed": { "minimum": 1 } } } }
+      }
+    },
+    {
+      "title": "no-tests-run means nothing executed",
+      "description": "classification 'no-tests-run' requires a zero total. If tests executed, the status is decided by their outcomes.",
+      "if": {
+        "required": ["classification"],
+        "properties": { "classification": { "const": "no-tests-run" } }
+      },
+      "then": {
+        "properties": { "tests": { "properties": { "total": { "const": 0 } } } }
+      }
+    }
+  ],
+  "properties": {
+    "contract": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "const": "qa-run/execution-result" },
+        "version": { "type": "string", "pattern": "^1\\.[0-9]+\\.[0-9]+$" }
+      }
+    },
+    "skill": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "const": "qa-run" },
+        "version": { "type": "string" }
+      }
+    },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "summary": { "type": "string", "minLength": 1 },
+    "classification": {
+      "description": "The run status, computed from the reporter and exit code — never chosen by feel.",
+      "enum": ["passed", "failed", "errored", "no-tests-run", "blocked"]
+    },
+    "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+    "evidence": {
+      "description": "The observations that justify the status: the reporter file, the exit code, launch errors.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["type", "description", "source"],
+        "properties": {
+          "type": { "enum": ["report", "command", "log", "file", "artifact"] },
+          "description": { "type": "string", "minLength": 1 },
+          "source": { "type": "string", "minLength": 1 },
+          "excerpt": { "type": "string" }
+        }
+      }
+    },
+    "execution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["strategy", "command", "exitCode"],
+      "properties": {
+        "strategy": {
+          "enum": ["smoke", "regression", "full-suite", "changed", "single-spec", "targeted", "tag-based", "directory-based", "failed-only", "retry", "dry-run"]
+        },
+        "command": {
+          "type": "string",
+          "description": "The exact command executed, verbatim and secret-free."
+        },
+        "startedAt": { "type": "string", "format": "date-time" },
+        "finishedAt": { "type": "string", "format": "date-time" },
+        "durationMs": { "type": "integer", "minimum": 0 },
+        "exitCode": {
+          "type": ["integer", "null"],
+          "description": "Runner process exit code; null when the run was not attempted (blocked)."
+        }
+      }
+    },
+    "framework": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": { "enum": ["playwright", "selenium", "cypress", "webdriverio"] },
+        "version": { "type": ["string", "null"] }
+      }
+    },
+    "tests": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["total", "passed", "failed", "skipped"],
+      "properties": {
+        "total": { "type": "integer", "minimum": 0 },
+        "passed": { "type": "integer", "minimum": 0 },
+        "failed": { "type": "integer", "minimum": 0 },
+        "skipped": { "type": "integer", "minimum": 0 },
+        "flaky": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "executed": {
+      "description": "Per-test outcomes, normalized across frameworks.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["title", "status"],
+        "properties": {
+          "title": { "type": "string", "minLength": 1 },
+          "file": { "type": "string" },
+          "status": { "enum": ["passed", "failed", "skipped", "flaky"] },
+          "durationMs": { "type": "integer", "minimum": 0 },
+          "retries": { "type": "integer", "minimum": 0 }
+        }
+      }
+    },
+    "artifacts": {
+      "description": "Everything the run produced, in the common artifact model, for the analysis layer to consume.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["type", "location", "framework", "timestamp", "ownership"],
+        "properties": {
+          "type": {
+            "enum": ["stdout", "stderr", "console-log", "network-log", "screenshot", "video", "trace", "har", "junit", "html-report", "attachment"]
+          },
+          "location": { "type": "string", "minLength": 1 },
+          "framework": { "type": "string" },
+          "timestamp": { "type": "string", "format": "date-time" },
+          "mediaType": { "type": "string" },
+          "ownership": { "type": "string" },
+          "testRef": { "type": "string" },
+          "present": {
+            "type": "boolean",
+            "description": "False when the artifact was planned but expected-and-absent."
+          }
+        }
+      }
+    },
+    "environment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["location", "headless"],
+      "properties": {
+        "location": { "enum": ["local", "ci", "remote"] },
+        "headless": { "type": "boolean" },
+        "browser": { "type": ["string", "null"] },
+        "baseUrl": { "type": ["string", "null"] },
+        "os": { "type": "string" },
+        "ciProvider": { "type": ["string", "null"] },
+        "envVarNames": {
+          "type": "array",
+          "description": "Names only of the environment variables the run depended on — never values.",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "recommendations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["action", "priority"],
+        "properties": {
+          "action": { "type": "string", "minLength": 1 },
+          "priority": { "enum": ["high", "medium", "low"] },
+          "command": { "type": "string" }
+        }
+      }
+    },
+    "metadata": { "type": "object" }
+  }
+}

package/skills/qa-run/examples/execute-playwright.md

@@ -0,0 +1,89 @@
+# Example: execute a Playwright smoke run
+
+Shows the full execution path — plan, run, collect, normalize — for the one framework this milestone executes. Contrast with [plan-a-run.md](plan-a-run.md), which stops at the plan; here `qa-run` actually runs the suite and reports what happened.
+
+## Request
+
+```text
+/qa-run smoke
+```
+
+## Context
+
+The Playwright + TypeScript repository from the qa-init example: `.qa/context.md` records `testFramework.e2e: playwright`, `packageManager: pnpm`, `conventions.specGlob: e2e/**/*.spec.ts`, and a `chromium` project. Smoke tests are tagged `@smoke`. `BASE_URL` is set in the environment; a local dev server is running.
+
+## Expected behavior
+
+1. **Discover / adapter.** `.qa/context.md` exists and records Playwright — a supported framework, so execution proceeds.
+2. **Intent / strategy.** "smoke" selects the `smoke` strategy, scope `@smoke`.
+3. **Environment.** Local, headless, `chromium`, base URL from `BASE_URL`; the variable name is recorded, its value is not.
+4. **Command.** Playwright config discovered; one command built with a JSON reporter and `--trace=on-first-retry`, recorded verbatim.
+5. **Execute.** The command runs under the smoke timeout; one test fails and is retried once, still failing; the browser is cleaned up.
+6. **Collect / normalize.** Artifacts located into the common model; the JSON reporter is normalized — 11 passed, 1 failed → status `failed`, backed by the reporter and the exit code.
+7. **Report.** The result is self-validated and presented; a recommendation points at the collected trace for future failure analysis.
+
+## Expected output
+
+The normalized result `qa-artifacts/qa-run-result-9c2e.json` (the plan artifact is emitted first, as in the planning example):
+
+```json
+{
+  "contract": { "name": "qa-run/execution-result", "version": "1.0.0" },
+  "skill": { "name": "qa-run", "version": "0.2.0" },
+  "generatedAt": "2026-07-18T11:05:03Z",
+  "summary": "Smoke run executed on Playwright/Chromium (headless): 11 passed, 1 failed. The checkout purchase test failed after one retry; its trace was collected. No tests were skipped.",
+  "classification": "failed",
+  "confidence": 0.98,
+  "evidence": [
+    {
+      "type": "report",
+      "description": "Playwright JSON reporter: 11 passed, 1 failed, 0 skipped",
+      "source": "test-results/results.json",
+      "excerpt": "\"stats\": { \"expected\": 11, \"unexpected\": 1, \"skipped\": 0 }"
+    },
+    {
+      "type": "command",
+      "description": "Runner exited non-zero, consistent with a reported failure",
+      "source": "exit code 1"
+    }
+  ],
+  "execution": {
+    "strategy": "smoke",
+    "command": "pnpm exec playwright test --grep @smoke --project=chromium --reporter=json,line --trace=on-first-retry",
+    "startedAt": "2026-07-18T11:04:33Z",
+    "finishedAt": "2026-07-18T11:05:03Z",
+    "durationMs": 30120,
+    "exitCode": 1
+  },
+  "framework": { "name": "playwright", "version": "1.58.0" },
+  "tests": { "total": 12, "passed": 11, "failed": 1, "skipped": 0, "flaky": 0 },
+  "executed": [
+    { "title": "checkout > completes a purchase", "file": "e2e/checkout.spec.ts", "status": "failed", "durationMs": 8300, "retries": 1 },
+    { "title": "login > accepts valid credentials", "file": "e2e/login.spec.ts", "status": "passed", "durationMs": 2100, "retries": 0 }
+  ],
+  "artifacts": [
+    { "type": "attachment", "location": "test-results/results.json", "framework": "playwright", "timestamp": "2026-07-18T11:05:03Z", "mediaType": "application/json", "ownership": "qa-run", "present": true },
+    { "type": "trace", "location": "test-results/checkout-completes-a-purchase/trace.zip", "framework": "playwright", "timestamp": "2026-07-18T11:05:01Z", "ownership": "qa-run", "testRef": "checkout > completes a purchase", "present": true },
+    { "type": "html-report", "location": "playwright-report/index.html", "framework": "playwright", "timestamp": "2026-07-18T11:05:03Z", "ownership": "qa-run", "present": true }
+  ],
+  "environment": {
+    "location": "local",
+    "headless": true,
+    "browser": "chromium",
+    "baseUrl": "http://localhost:3000",
+    "os": "linux",
+    "ciProvider": null,
+    "envVarNames": ["BASE_URL"]
+  },
+  "recommendations": [
+    {
+      "action": "Analyze the checkout failure from its collected trace once failure analysis ships",
+      "priority": "high",
+      "command": "/qa-debug"
+    }
+  ],
+  "metadata": { "planRef": "qa-run-plan-9c2e" }
+}
+```
+
+The prose reply states the counts, that the run genuinely executed, and where the failure's evidence was collected — without diagnosing the failure, which is a later skill's job.

package/skills/qa-run/examples/plan-a-run.md

@@ -0,0 +1,83 @@
+# Example: plan a smoke run
+
+## Request
+
+```text
+/qa-run smoke
+```
+
+## Context
+
+The repository from the qa-init example: `.qa/context.md` exists with `testFramework.e2e: playwright`, `packageManager: pnpm`, and `conventions.specGlob: e2e/**/*.spec.ts`. Smoke tests are tagged `@smoke`.
+
+## Expected behavior
+
+1. **Discover.** Read `.qa/context.md`; it exists, so proceed.
+2. **Understand repository / framework.** Runner is Playwright via pnpm, from the context.
+3. **Understand intent.** "smoke" selects the smoke strategy; no ambiguity, so no question.
+4. **Determine strategy.** `smoke`, justified by the intent word "smoke" and the Playwright context fact.
+5. **Plan.** Scope is the `@smoke`-tagged tests; the evidence plan captures a trace on failure and a report always; the collect, execute, and validate phases are marked `deferred`.
+6. **Report.** Emit and self-validate the execution plan; execute nothing.
+
+## Expected output
+
+`qa-artifacts/qa-run-7f3a.json`:
+
+```json
+{
+  "contract": { "name": "qa-run/execution-plan", "version": "1.0.0" },
+  "skill": { "name": "qa-run", "version": "0.1.0" },
+  "generatedAt": "2026-07-18T10:20:00Z",
+  "summary": "Smoke run planned: the @smoke-tagged Playwright suite, run with pnpm, capturing a trace on failure. Planning only — no tests were executed.",
+  "classification": "smoke",
+  "confidence": 0.9,
+  "evidence": [
+    {
+      "type": "context",
+      "description": "E2E framework and runner",
+      "source": ".qa/context.md",
+      "excerpt": "testFramework.e2e: playwright; packageManager: pnpm"
+    },
+    {
+      "type": "intent",
+      "description": "User selected the smoke strategy",
+      "source": "user request",
+      "excerpt": "/qa-run smoke"
+    }
+  ],
+  "plan": {
+    "framework": "playwright",
+    "runner": "pnpm exec playwright test",
+    "command": "pnpm exec playwright test --grep @smoke --trace on-first-retry",
+    "scope": { "include": ["@smoke"], "exclude": [] },
+    "environment": {},
+    "phases": [
+      { "name": "discover", "status": "performed", "detail": "read .qa/context.md" },
+      { "name": "understand-repository", "status": "performed" },
+      { "name": "understand-intent", "status": "performed" },
+      { "name": "determine-framework", "status": "performed", "detail": "playwright from context" },
+      { "name": "determine-strategy", "status": "performed", "detail": "smoke" },
+      { "name": "collect-evidence", "status": "deferred", "detail": "execution engine, later milestone" },
+      { "name": "execute", "status": "deferred", "detail": "execution engine, later milestone" },
+      { "name": "validate", "status": "deferred", "detail": "execution engine, later milestone" },
+      { "name": "report", "status": "performed" },
+      { "name": "recommendations", "status": "performed" }
+    ]
+  },
+  "evidencePlan": {
+    "artifacts": [
+      { "type": "trace", "when": "on-failure", "purpose": "timeline for /qa-debug if the run fails" },
+      { "type": "report", "when": "always", "purpose": "machine-readable pass/fail for the result" }
+    ]
+  },
+  "recommendations": [
+    {
+      "action": "Deterministic execution of this plan arrives in a later milestone; until then the illustrative command can be run manually",
+      "priority": "medium"
+    }
+  ],
+  "metadata": {}
+}
+```
+
+The prose reply presents the strategy and scope, states plainly that nothing was executed, and points to the plan artifact.

package/skills/qa-run/references/artifact-collector.md

@@ -0,0 +1,40 @@
+<!-- synced-from: shared/execution/artifact-collector.md — do not edit; edit the source and run: node scripts/sync-shared.mjs --write -->
+# Artifact Collector
+
+The common, framework-independent model for everything a run produces, and the rules for collecting it. This model is the interface between execution and the analysis layer of later milestones: a future analyzer consumes artifacts by their normalized type and never needs to know which framework produced them.
+
+## The artifact model
+
+Every collected artifact is described by the same fields, whatever produced it:
+
+| Field | Meaning |
+| --- | --- |
+| `type` | Normalized kind, from the closed set below — the field analyzers key on |
+| `location` | Path to the artifact, relative to the repository root |
+| `framework` | The framework that produced it, for provenance (analyzers do not branch on this) |
+| `timestamp` | ISO 8601 UTC time the artifact was produced |
+| `mediaType` | The artifact's media type where meaningful (for example, the type for a video or an XML report) |
+| `ownership` | The skill and run that produced it, for example `qa-run` |
+| `testRef` | The test the artifact belongs to, when it is test-scoped rather than run-scoped |
+
+## Normalized types
+
+The `type` set is fixed so analyzers can rely on it across frameworks:
+
+```text
+stdout · stderr · console-log · network-log · screenshot · video · trace · har · junit · html-report · attachment
+```
+
+A framework that emits something outside this set maps it to the closest type or to `attachment` with a descriptive note; it never invents a new top-level type, because a new type is a change every future analyzer would have to learn.
+
+## Collection rules
+
+- **Locate, describe, never move.** Collection records where the framework wrote each artifact; it does not relocate or rewrite them. The result points at real files in place.
+- **Run-scoped and test-scoped.** Some artifacts belong to the whole run (stdout, the JUnit report); others belong to one test (a trace, a failure screenshot). Test-scoped artifacts carry `testRef`.
+- **Collect what the strategy planned.** The evidence plan chose what to capture and when (for example, a trace only on failure). Collection gathers exactly that set, so cost matches the strategy.
+- **Redact at the boundary.** Text artifacts (stdout, logs) may contain credentials from the environment; any credential or token is redacted as the artifact is described, before it appears in a result or is shown. This applies to the description and any excerpt, not to the file on disk, which the user controls.
+- **Absence is data.** A planned artifact that is missing (no trace though a test failed) is recorded as an expected-but-absent note, not silently dropped — its absence may matter to an analyzer.
+
+## Why normalize now
+
+Normalizing artifacts at collection time, rather than leaving each framework's raw layout for analyzers to decode, is what lets the analysis layer be written once against one model. It is the concrete form of the pack's promise that `qa-debug` and `qa-report` will work across frameworks: they will read this model, not Playwright's or Selenium's native output. The decision is recorded in the pack's architecture decision on the normalized result.

package/skills/qa-run/references/browser-launch.md

@@ -0,0 +1,39 @@
+<!-- synced-from: shared/execution/browser-launch.md — do not edit; edit the source and run: node scripts/sync-shared.mjs --write -->
+# Browser Execution Lifecycle
+
+How a run's browser and mode are chosen and controlled: startup, timeouts, retries, cleanup, and cancellation. The engine expresses these as intents; the framework adapter realizes them with the framework's own mechanisms.
+
+## Browsers and modes
+
+| Dimension | Options | Default |
+| --- | --- | --- |
+| Engine | Chromium, Firefox, WebKit | The framework's configured default, else Chromium |
+| Display | Headed, headless | Headless (headed only on explicit request, and never in CI) |
+| Location | Local, remote/grid, CI runner | Local this milestone; remote and CI-runner execution are adapter extensions |
+
+The chosen browser and mode come from the environment decision (see the environment-detection module) and are recorded in the result's environment block, so a reader knows exactly what ran where.
+
+## Lifecycle
+
+```text
+  resolve browser+mode → start → run under timeout → on failure: bounded retry → collect → clean up
+                                        │
+                                   cancellation can interrupt at any point → clean up
+```
+
+- **Startup.** The adapter launches the browser as part of the run command; the engine does not manage browser processes directly. Startup failure (missing browser binary, unavailable display) is an `errored` result with the cause as evidence — never a silent fallback.
+- **Timeout.** Every run has an overall wall-clock timeout appropriate to the strategy (a smoke run is short; a regression run is long). A run that exceeds it is stopped, cleaned up, and reported as `errored` with the timeout as the cause — a hang is never reported as a failure of the tests.
+- **Retry.** Retries are the framework's own test-level retry (configured through the command), used to observe flakiness, not to manufacture a pass. The number of retries is recorded; a test that passes only on retry is reported as flaky, not as passed.
+- **Cleanup.** After every run — success, failure, timeout, or cancellation — browser processes are ended and temporary state is removed, so no run leaves orphaned processes or locked resources.
+- **Cancellation.** If the user interrupts, the run is stopped, the browser is cleaned up, and a partial result is reported honestly as cancelled with whatever completed — never as passed.
+
+## Rules
+
+- Headless by default; headed is explicit and never assumed in CI.
+- A hang, a crash, and a test failure are three different outcomes and are reported as three different things.
+- Cleanup always runs, on every exit path.
+- The browser, mode, and location that actually ran are recorded as evidence; the result never describes an environment that was requested but not achieved.
+
+## Extension
+
+Remote and grid execution, additional engines, and containerized browsers are adapter-level additions: they change how the adapter starts and points the browser, not the lifecycle above. The startup-timeout-retry-cleanup-cancellation shape holds for every framework and location.

package/skills/qa-run/references/command-builder.md

@@ -0,0 +1,39 @@
+<!-- synced-from: shared/execution/command-builder.md — do not edit; edit the source and run: node scripts/sync-shared.mjs --write -->
+# Command Builder
+
+How a chosen strategy, a resolved scope, a browser, and an environment become the one concrete command the run executes. The builder is framework-agnostic: it assembles the *intent* of the command, and the framework adapter supplies the framework's actual flags and syntax.
+
+Every built command is recorded verbatim in the execution result, so a run is always reproducible and auditable.
+
+## Inputs
+
+The builder consumes decisions already made by other modules — it invents nothing:
+
+| Input | Source |
+| --- | --- |
+| Strategy | The chosen strategy (see the execution-strategy module) |
+| Scope | The include and exclude sets the strategy resolved |
+| Browser and mode | The environment decision (see the environment-detection module) |
+| Runner | The framework adapter, from the recorded framework |
+| Reporter | Always includes a machine-readable reporter, so the result can be normalized |
+
+## The build
+
+1. Start from the adapter's base run command.
+2. Apply the scope as the adapter's selection mechanism — a tag filter, a path filter, a project selection, or named files. The adapter owns the syntax; the builder owns which selection to apply.
+3. Apply the browser and mode as the adapter's flags.
+4. Always add a machine-readable reporter alongside any human reporter. Normalization depends on it; a run without it cannot produce a trustworthy result.
+5. Add the evidence flags the artifact plan requires (tracing, video, screenshots) at the levels the strategy chose.
+6. Record the full command string in the result.
+
+## Rules
+
+- **One command, fully specified.** The builder produces a single command with every relevant flag explicit. It does not rely on ambient defaults that a reader of the result could not see.
+- **Reporter is non-negotiable.** A machine-readable reporter is always present; the result's counts and per-test outcomes come from it, not from scraping human output.
+- **Secrets never enter the command line.** Credentials are passed by environment-variable reference, never interpolated into the recorded command (the command is stored and shown).
+- **No destructive flags.** The builder never adds flags that update snapshots, rewrite baselines, or delete artifacts; execution observes, it does not mutate the project.
+- **Illustrative until launched.** The built command is presented in the plan before the run; the guardrails against claiming a run happened apply until the command has actually executed and returned.
+
+## Extension
+
+A new framework changes only the adapter's answers — base command, selection syntax, reporter and evidence flags. The builder's logic (which selection, which reporter, record verbatim) is unchanged. This is why adding a framework never touches the command-building step of any skill.

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

@@ -0,0 +1,128 @@
+<!-- synced-from: shared/execution/deterministic-tooling.md — do not edit; edit the source and run: node scripts/sync-shared.mjs --write -->
+# Deterministic tooling invocation
+
+How a skill runs the pack's deterministic tooling. One recipe, identical in every
+skill that bundles an engine, so an agent never has to invent the glue.
+
+**The rule this module exists to enforce:** deterministic code owns facts. If a
+value could have been computed by a tool, the skill runs the tool and cites its
+output. Hand-normalizing a reporter, hand-counting failures, or hand-classifying
+an error message is a boundary violation, not a shortcut — see the pack's
+*Deterministic Execution Boundary* architecture document.
+
+## 1. One command shape, every platform
+
+The engine is bundled inside the installed skill, and a launcher beside it
+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]
+```
+
+`<skill-dir>` is wherever the host installed this skill — usually
+`.agents/skills/<skill>` or, for Claude Code, `.claude/skills/<skill>`. Use
+whichever exists.
+
+```bash
+python3 .agents/skills/qa-run/scripts/qa_tool.py 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.
+
+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.
+
+If `qa_tool.py` 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
+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.
+
+## 2. Analysis core — `qa_tool.py 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 |
+
+## 3. Diagnostic engine — `qa_tool.py 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 |
+
+**Inputs.** `--execution-result` takes a `qa-run` execution result, or the minimal
+subset (`tests` counts plus `executed[]` entries carrying `status`).
+`--analysis-result` takes `{findings: [...]}` and is preferred over `executed[]`
+when available. Both are validated against the internal seam contracts before
+the engine runs, so a malformed payload fails loudly with `exit 2` instead of
+producing a confident-looking diagnosis from nothing.
+
+**Output.** Every diagnosis is validated against the internal diagnosis contract
+before it is returned. The skill adds explanation, never new facts.
+
+**The engine's shape is internal; the public contract is a projection of it.** Do
+not copy an engine object wholesale into a contract field — the internal shape
+carries more than the public contract accepts, and every public contract sets
+`additionalProperties: false`, so a wholesale copy is rejected. Map the fields the
+contract names:
+
+| Contract field | Take from | Note |
+| --- | --- | --- |
+| `rootCause` | `entries[i].rootCause` | Exactly five keys: `classification`, `confidence`, `reason`, `ownership`, `recommendation`. The engine also returns per-cause `evidence` — that belongs in the envelope's `evidence[]`, not nested here. |
+| `priority` | `entries[i].priority` | Copied as-is |
+| `timeline` | `diagnosis.timeline` | Add `order` if absent |
+| `evidence[]` | the artifacts and commands you actually ran | Include a `command` entry citing the invocation |
+| `classification` | `entries[0].rootCause.classification` | The envelope mirrors the top cause |
+
+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
+result, never the claim.
+
+## 4. Framework adapters
+
+Framework-specific artifact shapes stay in the adapter. The core CLI never takes
+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 |
+
+For Selenium, Cypress, and WebdriverIO, normalize through
+`qa_tool.py 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
+
+Cite the invocation in `evidence[]`: the command, the file it read, and the field
+that carried the fact. A skill that reports a fact no tool produced has violated
+its own contract, and the adversarial evaluation cases exist to catch it.
+
+When a tool is unavailable, the skill's documented fallback applies — and the
+result must state that it is degraded, name what was missing, and lower
+confidence accordingly. Silence about a missing tool is the failure mode; an
+honest "I could not run the trace analyzer" is not.