qa-engineer 0.9.1 → 0.10.0

package/shared/analysis/lib/qa_analysis/junit.py

@@ -1,80 +0,0 @@
-"""JUnit XML parser.
-
-Framework-agnostic: Playwright, Selenium, Cypress, WebdriverIO, and most unit
-runners emit JUnit XML, so this one parser normalizes them all into the pack's
-per-test result shape. This is the concrete proof that different frameworks
-share one contract — only where the file lives differs, not how it is read.
-
-Parses deterministically; a malformed document raises rather than guessing.
-"""
-
-import xml.etree.ElementTree as ET
-
-from .redaction import redact_text
-
-
-class MalformedArtifact(ValueError):
-    """Raised when an artifact cannot be parsed. Never swallowed into a guess."""
-
-
-def _int(value, default=0):
-    try:
-        return int(value)
-    except (TypeError, ValueError):
-        return default
-
-
-def parse_junit(path):
-    """Parse a JUnit XML file into a normalized result.
-
-    Returns a dict: {tests: {total, passed, failed, skipped}, executed: [...]}.
-    Each executed entry: {title, file, status, durationMs, message?}.
-    Raises MalformedArtifact if the XML is unreadable or not JUnit-shaped.
-    """
-    try:
-        tree = ET.parse(path)
-    except (ET.ParseError, OSError) as exc:
-        raise MalformedArtifact(f"could not parse JUnit XML at {path}: {exc}") from exc
-
-    root = tree.getroot()
-    # Accept either a <testsuites> root or a single <testsuite> root.
-    if root.tag == "testsuites":
-        suites = root.findall("testsuite")
-    elif root.tag == "testsuite":
-        suites = [root]
-    else:
-        raise MalformedArtifact(f"not a JUnit document (root <{root.tag}>) at {path}")
-
-    executed = []
-    for suite in suites:
-        for case in suite.findall("testcase"):
-            failure = case.find("failure")
-            error = case.find("error")
-            skipped = case.find("skipped")
-            if failure is not None or error is not None:
-                status = "failed"
-                node = failure if failure is not None else error
-                message = redact_text((node.get("message") or node.text or "").strip())
-            elif skipped is not None:
-                status = "skipped"
-                message = redact_text((skipped.get("message") or "").strip())
-            else:
-                status = "passed"
-                message = ""
-            entry = {
-                "title": case.get("name", ""),
-                "file": case.get("classname", ""),
-                "status": status,
-                "durationMs": int(round(float(case.get("time", "0") or "0") * 1000)),
-            }
-            if message:
-                entry["message"] = message
-            executed.append(entry)
-
-    counts = {
-        "total": len(executed),
-        "passed": sum(1 for e in executed if e["status"] == "passed"),
-        "failed": sum(1 for e in executed if e["status"] == "failed"),
-        "skipped": sum(1 for e in executed if e["status"] == "skipped"),
-    }
-    return {"tests": counts, "executed": executed}

package/shared/analysis/lib/qa_analysis/redaction.py

@@ -1,99 +0,0 @@
-"""Credential, secret, token, and PII redaction.
-
-Every analyzer runs artifact text through redaction before it appears in a
-finding, a report, or stdout. Redaction happens as evidence is captured, not
-after — a secret must never reach a model's context or a log. Standard library
-only; deterministic.
-"""
-
-import re
-
-# Ordered (name, pattern, replacement). Order matters: match structured,
-# high-signal secrets (JWTs, provider keys) before generic fallbacks.
-_RULES = [
-    ("jwt", re.compile(r"eyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}")),
-    ("aws-access-key", re.compile(r"AKIA[0-9A-Z]{16}")),
-    ("github-token", re.compile(r"gh[pousr]_[A-Za-z0-9]{20,}")),
-    ("slack-token", re.compile(r"xox[baprs]-[A-Za-z0-9-]{10,}")),
-    ("openai-key", re.compile(r"sk-[A-Za-z0-9]{20,}")),
-    ("bearer", re.compile(r"(?i)\bBearer\s+[A-Za-z0-9._~+/-]+=*")),
-    # Sensitive header lines: keep the header name, mask the value.
-    ("auth-header", re.compile(r"(?im)^(\s*(?:authorization|proxy-authorization)\s*[:=]\s*).+$")),
-    ("cookie-header", re.compile(r"(?im)^(\s*(?:set-cookie|cookie)\s*[:=]\s*).+$")),
-    # Secret-like assignments: key=value / "key": "value".
-    ("assigned-secret", re.compile(
-        r'(?i)(\b(?:password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key|client[_-]?secret)\b\s*[:=]\s*["\']?)'
-        r'([^\s"\'&]{4,})')),
-    # Credentials in URLs and query strings.
-    ("url-credential", re.compile(r"(?i)(://[^:/@\s]+:)([^@/\s]+)(@)")),
-    ("query-secret", re.compile(
-        r"(?i)([?&](?:password|passwd|pwd|token|secret|api[_-]?key|access[_-]?key)=)([^&\s#]+)")),
-    # PII: email addresses.
-    ("email", re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b")),
-]
-
-# Rules whose replacement preserves a leading captured group (the label/prefix).
-_PREFIX_PRESERVING = {
-    "auth-header": r"\1[REDACTED:auth-header]",
-    "cookie-header": r"\1[REDACTED:cookie-header]",
-    "assigned-secret": r"\1[REDACTED:secret]",
-    "url-credential": r"\1[REDACTED:credential]\3",
-    "query-secret": r"\1[REDACTED:secret]",
-}
-
-
-def redact_text(text):
-    """Return text with every recognized secret or PII value masked."""
-    if not text:
-        return text
-    result = text
-    for name, pattern in _RULES:
-        if name in _PREFIX_PRESERVING:
-            result = pattern.sub(_PREFIX_PRESERVING[name], result)
-        else:
-            result = pattern.sub(f"[REDACTED:{name}]", result)
-    return result
-
-
-def detect_secrets(text):
-    """Return a list of {type, start, end} for secrets found — never the values.
-
-    Used to decide whether an artifact is safe to expose, without surfacing the
-    secret itself.
-    """
-    findings = []
-    if not text:
-        return findings
-    for name, pattern in _RULES:
-        for match in pattern.finditer(text):
-            findings.append({"type": name, "start": match.start(), "end": match.end()})
-    findings.sort(key=lambda f: f["start"])
-    return findings
-
-
-_SENSITIVE_HEADERS = {
-    "authorization", "proxy-authorization", "cookie", "set-cookie",
-    "x-api-key", "x-auth-token", "api-key", "x-csrf-token",
-}
-
-
-def redact_headers(headers):
-    """Mask the values of sensitive HTTP headers.
-
-    Accepts a dict, or a list of {"name","value"} entries (HAR shape), and
-    returns the same shape with sensitive values replaced.
-    """
-    def mask(name, value):
-        return "[REDACTED:header]" if name.strip().lower() in _SENSITIVE_HEADERS else redact_text(value)
-
-    if isinstance(headers, dict):
-        return {k: mask(k, str(v)) for k, v in headers.items()}
-    if isinstance(headers, list):
-        out = []
-        for entry in headers:
-            if isinstance(entry, dict) and "name" in entry:
-                out.append({**entry, "value": mask(str(entry["name"]), str(entry.get("value", "")))})
-            else:
-                out.append(entry)
-        return out
-    return headers

package/shared/analysis/lib/qa_analysis/taxonomy.py

@@ -1,98 +0,0 @@
-"""The canonical QA failure taxonomy and its deterministic classifier.
-
-Classification maps observed signals to one of a closed set of failure classes.
-It is rule-based and conservative: when no rule matches with sufficient signal,
-the result is UNKNOWN. Unknown is preferable to incorrect.
-"""
-
-import re
-
-# The closed set of failure classifications. Every value implies a different
-# owner and next action; if two would lead to the same action, they are merged.
-ASSERTION = "assertion-failure"
-LOCATOR = "locator-failure"
-TIMEOUT = "timeout"
-NETWORK = "network"
-AUTH = "authentication"
-AUTHORIZATION = "authorization"
-ENVIRONMENT = "environment"
-CONFIGURATION = "configuration"
-INFRASTRUCTURE = "infrastructure"
-TEST_DATA = "test-data"
-APPLICATION_BUG = "application-bug"
-FRAMEWORK = "framework-failure"
-FLAKY = "flaky"
-UNKNOWN = "unknown"
-
-CLASSES = {
-    ASSERTION, LOCATOR, TIMEOUT, NETWORK, AUTH, AUTHORIZATION, ENVIRONMENT,
-    CONFIGURATION, INFRASTRUCTURE, TEST_DATA, APPLICATION_BUG, FRAMEWORK,
-    FLAKY, UNKNOWN,
-}
-
-# Ordered rules: (classification, message-pattern, confidence, reason).
-#
-# Order encodes priority, and the first two rules exist because modern runners
-# print a timeout budget in *every* assertion failure. Playwright's message for a
-# plain text mismatch ends with "Timeout: 5000ms" even though nothing timed out,
-# so a naive timeout rule captures assertion and locator failures alike and sends
-# the reader to raise a timeout — the one action guaranteed not to help. The
-# patterns below are derived from real captured runner output; see
-# tests/test_analysis.py::RealRunnerMessageTests, which pins the exact strings.
-#
-# The discriminators, from that output:
-#   element missing  -> "Error: element(s) not found"   (no Received: value)
-#   value mismatch   -> "Expected: X" + "Received: Y"   (element was resolved)
-#   real timeout     -> a timeout with neither of the above
-_RULES = [
-    (LOCATOR, re.compile(r"(?i)(no such element|element(?:\(s\))?\s+not\s+(?:found|visible|attached)|locator.*(?:resolved to 0|not found)|waiting for (?:locator|selector)|unable to locate element)"), 0.8,
-     "Error indicates the target element could not be found or resolved."),
-    # A concrete expected-vs-received comparison is an assertion result, not a
-    # time budget: the runner resolved the target and compared values.
-    (ASSERTION, re.compile(r"(?is)expected:.*received:"), 0.8,
-     "Error shows a concrete expected-versus-received comparison, so the assertion did not hold."),
-    (TIMEOUT, re.compile(r"(?i)(timeout|timed out|exceeded .*ms|deadline exceeded)"), 0.75,
-     "Error indicates an operation exceeded its time budget."),
-    (AUTH, re.compile(r"(?i)(401 unauthorized|authentication failed|invalid (?:credentials|token)|login failed|not authenticated)"), 0.85,
-     "Error indicates an authentication failure — the identity could not be established."),
-    (AUTHORIZATION, re.compile(r"(?i)(403 forbidden|permission denied|access denied|not authorized|forbidden\b|insufficient (?:permission|privilege))"), 0.85,
-     "Error indicates an authorization failure — the identity lacked permission."),
-    (NETWORK, re.compile(r"(?i)(ECONNREFUSED| ENOTFOUND|net::ERR|connection (?:refused|reset)|5\d\d (?:internal server error|bad gateway|service unavailable)|fetch failed)"), 0.8,
-     "Error indicates a network or upstream service failure."),
-    (ASSERTION, re.compile(r"(?i)(assertion|expect(?:ed)?\b|toBe|toEqual|toHaveText|toBeVisible|AssertionError|expected .* (?:to|but))"), 0.7,
-     "Error indicates an assertion did not hold."),
-    (TEST_DATA, re.compile(r"(?i)(duplicate key|constraint violation|no rows|seed data|fixture .*(?:missing|not found)|invalid test data)"), 0.7,
-     "Error indicates a test-data problem."),
-    (CONFIGURATION, re.compile(r"(?i)(cannot find module|config(?:uration)? (?:error|not found)|missing (?:config|environment variable)|unknown option)"), 0.7,
-     "Error indicates a configuration problem."),
-    (ENVIRONMENT, re.compile(r"(?i)(base ?url|env(?:ironment)? .*(?:not set|missing)|ECONNREFUSED .*localhost|dev server)"), 0.6,
-     "Error indicates an environment problem such as a missing base URL or unreachable local service."),
-    (INFRASTRUCTURE, re.compile(r"(?i)(out of memory|OOM|disk (?:full|space)|browser .*(?:crash|closed unexpectedly)|worker .*(?:died|crashed))"), 0.7,
-     "Error indicates an infrastructure problem such as a crash or resource exhaustion."),
-    (FRAMEWORK, re.compile(r"(?i)(internal error|unexpected error in (?:playwright|selenium|cypress|webdriver)|driver .*mismatch)"), 0.6,
-     "Error indicates a fault in the test framework or driver itself."),
-]
-
-
-def classify(message, http_status=None):
-    """Classify a failure from its error message and optional HTTP status.
-
-    Returns (classification, confidence, reason). Never guesses: an
-    unrecognized signal yields UNKNOWN at low confidence with an honest reason.
-    """
-    text = message or ""
-
-    # A concrete HTTP status is stronger evidence than message text.
-    if http_status is not None:
-        if http_status == 401:
-            return (AUTH, 0.9, "HTTP 401 indicates an authentication failure.")
-        if http_status == 403:
-            return (AUTHORIZATION, 0.9, "HTTP 403 indicates an authorization failure.")
-        if 500 <= http_status <= 599:
-            return (NETWORK, 0.85, f"HTTP {http_status} indicates an upstream server failure.")
-
-    for classification, pattern, confidence, reason in _RULES:
-        if pattern.search(text):
-            return (classification, confidence, reason)
-
-    return (UNKNOWN, 0.2, "No classification rule matched the available signals; manual review needed.")

package/shared/diagnostics/lib/qa_diagnostics/__init__.py

@@ -1,13 +0,0 @@
-"""qa_diagnostics — the pack's shared diagnostic engine.
-
-One place where failure reasoning lives: root-cause analysis, timeline
-reconstruction, finding prioritization, and repair planning. The three
-diagnostic skills (qa-debug, qa-fix, qa-report) consume this engine and differ
-only in presentation — the reasoning is not duplicated across them.
-
-Standard library only. Builds on qa_analysis (taxonomy, evidence, diff guard);
-adds no framework-specific logic. Deterministic: the same inputs yield the same
-diagnosis every time.
-"""
-
-__version__ = "0.1.0"

package/shared/diagnostics/lib/qa_diagnostics/cli.py

@@ -1,124 +0,0 @@
-"""Unified CLI for the diagnostic engine.
-
-The engine's reasoning is deterministic; this is how a skill reaches it. Every
-subcommand reads JSON files, validates them against the internal seam contracts,
-and writes JSON to stdout — so an agent never has to invent glue code, and the
-input and output shapes are checked rather than assumed.
-
-Mirrors `qa_analysis.cli` exactly: JSON to stdout, exit 0 on success, exit 2 on
-bad input or usage. Standard library only.
-
-Usage:
-  python -m qa_diagnostics.cli diagnose --execution-result <path> [--analysis-result <path>]
-  python -m qa_diagnostics.cli plan-repairs --diagnosis <path>
-  python -m qa_diagnostics.cli summarize --execution-result <path> --diagnosis <path>
-  python -m qa_diagnostics.cli report --execution-result <path> [--analysis-result <path>]
-
-`report` is the one-shot path: it diagnoses, plans, and summarizes in a single
-invocation, so the common case is one command instead of three.
-
-Inputs
-  --execution-result   a qa-run execution result (or the minimal subset:
-                       `tests` counts plus `executed[]` with `status`)
-  --analysis-result    an analysis result with `findings[]`; preferred over
-                       `executed[]` when present
-  --diagnosis          the object emitted by `diagnose`
-
-Exit codes
-  0  success
-  2  unreadable file, malformed JSON, or a payload that fails its seam contract
-"""
-
-import argparse
-import json
-import sys
-
-from . import engine
-from . import internal_contracts
-from .internal_contracts import InternalContractError
-
-
-def _emit(obj):
-    json.dump(obj, sys.stdout, indent=2, sort_keys=True)
-    sys.stdout.write("\n")
-
-
-def _read(path):
-    with open(path, "r", encoding="utf-8") as handle:
-        return json.load(handle)
-
-
-def _read_execution(path):
-    """Read an execution result and hold it to the seam contract."""
-    return internal_contracts.validate_execution_result_min(_read(path))
-
-
-def _read_analysis(path):
-    """Read an analysis result and hold it to the seam contract."""
-    if path is None:
-        return None
-    return internal_contracts.validate_analysis_result(_read(path))
-
-
-def _read_diagnosis(path):
-    """Read a diagnosis and hold it to the seam contract."""
-    return internal_contracts.validate_diagnosis(_read(path))
-
-
-def main(argv=None):
-    parser = argparse.ArgumentParser(
-        prog="qa-diagnostics",
-        description="Deterministic diagnostic engine: root cause, timeline, priority, repairs",
-    )
-    sub = parser.add_subparsers(dest="command", required=True)
-
-    p = sub.add_parser("diagnose", help="root causes, timeline, prioritization, recommendations")
-    p.add_argument("--execution-result", required=True)
-    p.add_argument("--analysis-result")
-
-    p = sub.add_parser("plan-repairs", help="repair plans for a diagnosis (never code)")
-    p.add_argument("--diagnosis", required=True)
-
-    p = sub.add_parser("summarize", help="totals, breakdown, top priorities, release readiness")
-    p.add_argument("--execution-result", required=True)
-    p.add_argument("--diagnosis", required=True)
-
-    p = sub.add_parser("report", help="diagnose + plan-repairs + summarize in one call")
-    p.add_argument("--execution-result", required=True)
-    p.add_argument("--analysis-result")
-
-    args = parser.parse_args(argv)
-
-    try:
-        if args.command == "diagnose":
-            execution = _read_execution(args.execution_result)
-            analysis = _read_analysis(args.analysis_result)
-            _emit(engine.diagnose(execution, analysis))
-        elif args.command == "plan-repairs":
-            _emit({"plans": engine.plan_repairs(_read_diagnosis(args.diagnosis))})
-        elif args.command == "summarize":
-            _emit(engine.summarize(_read_execution(args.execution_result),
-                                   _read_diagnosis(args.diagnosis)))
-        elif args.command == "report":
-            execution = _read_execution(args.execution_result)
-            analysis = _read_analysis(args.analysis_result)
-            diagnosis = engine.diagnose(execution, analysis)
-            _emit({
-                "diagnosis": diagnosis,
-                "plans": engine.plan_repairs(diagnosis),
-                "summary": engine.summarize(execution, diagnosis),
-            })
-    except InternalContractError as exc:
-        _emit({"error": "invalid-payload", "detail": str(exc)})
-        return 2
-    except (OSError, json.JSONDecodeError) as exc:
-        _emit({"error": "io-error", "detail": str(exc)})
-        return 2
-    except (KeyError, TypeError) as exc:
-        _emit({"error": "unexpected-shape", "detail": f"{type(exc).__name__}: {exc}"})
-        return 2
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/shared/diagnostics/lib/qa_diagnostics/engine.py

@@ -1,143 +0,0 @@
-"""The diagnostic engine — the one place failure reasoning happens.
-
-Orchestrates the analysis platform and the diagnostics modules into a single
-diagnosis: per-failure root cause, prioritization, a reconstructed timeline, and
-ranked recommendations. qa-debug presents the diagnosis; qa-fix turns it into
-repair plans; qa-report aggregates diagnoses. None of them re-implements this.
-"""
-
-from qa_analysis import taxonomy
-
-from . import root_cause, prioritization, repair, timeline
-from . import internal_contracts
-
-_PRIORITY_RANK = {"P1": 3, "P2": 2, "P3": 1}
-
-# Classifications that block a release when they are the cause of a failure.
-_RELEASE_BLOCKING = {
-    taxonomy.APPLICATION_BUG, taxonomy.NETWORK, taxonomy.INFRASTRUCTURE,
-    taxonomy.AUTH, taxonomy.AUTHORIZATION,
-}
-
-
-def diagnose(execution_result, analysis_result=None, generation_result=None):
-    """Produce a full diagnosis from the available results.
-
-    Returns {entries: [...], timeline: [...], recommendations: [...]}, where each
-    entry combines a root cause with its prioritization and affected tests.
-    """
-    signals = _signals(execution_result, analysis_result)
-    findings = (analysis_result or {}).get("findings", [])
-
-    entries = []
-    for signal in signals:
-        rc = root_cause.analyze(signal)
-        blocking = rc["classification"] in _RELEASE_BLOCKING
-        prio = prioritization.prioritize(rc, blocking=blocking)
-        entries.append({
-            "rootCause": rc,
-            "priority": prio,
-            "affectedTests": signal.get("affectedTests", []),
-        })
-
-    entries.sort(key=lambda e: (_PRIORITY_RANK.get(e["priority"]["priority"], 0),
-                                e["rootCause"]["confidence"]), reverse=True)
-
-    diagnosis = {
-        "entries": entries,
-        "timeline": timeline.build_timeline(execution_result, findings),
-        "recommendations": _recommendations(entries),
-    }
-    # Mechanical seam enforcement: diagnosis must match the internal contract.
-    return internal_contracts.validate_diagnosis(diagnosis)
-
-
-def plan_repairs(diagnosis):
-    """Turn a diagnosis into repair plans (for qa-fix). One plan per entry;
-    non-repairable causes yield an escalation plan. Never produces code."""
-    plans = []
-    for entry in diagnosis["entries"]:
-        plan = repair.plan_repair(entry["rootCause"], affected_files=entry.get("affectedTests"))
-        plan["priority"] = entry["priority"]["priority"]
-        plans.append(plan)
-    return plans
-
-
-def summarize(execution_result, diagnosis):
-    """Aggregate a diagnosis for qa-report: totals, breakdown by classification,
-    the top-priority findings, and a deterministic release-readiness call."""
-    tests = (execution_result or {}).get("tests", {})
-    by_class = {}
-    for entry in diagnosis["entries"]:
-        cls = entry["rootCause"]["classification"]
-        by_class[cls] = by_class.get(cls, 0) + 1
-
-    return {
-        "totals": tests,
-        "byClassification": by_class,
-        "topPriority": [e for e in diagnosis["entries"] if e["priority"]["priority"] == "P1"],
-        "releaseReadiness": _release_readiness(execution_result, diagnosis),
-    }
-
-
-def _signals(execution_result, analysis_result):
-    """Derive failure signals, preferring the analysis platform's findings."""
-    signals = []
-    findings = (analysis_result or {}).get("findings", [])
-    if findings:
-        for f in findings:
-            signals.append({
-                "message": f.get("reason", ""),
-                "classification": f.get("classification"),
-                "confidence": f.get("confidence"),
-                "reason": f.get("reason"),
-                "httpStatus": f.get("httpStatus"),
-                "retries": f.get("retries", 0),
-                "finalStatus": f.get("finalStatus"),
-                "evidence": f.get("evidence", []),
-                "affectedTests": f.get("affectedTests", []),
-            })
-        return signals
-
-    for test in (execution_result or {}).get("executed", []):
-        if test.get("status") in ("failed", "flaky"):
-            signals.append({
-                "message": test.get("message", ""),
-                "retries": test.get("retries", 0),
-                "finalStatus": test.get("status"),
-                "affectedTests": [test.get("title", "")],
-                "evidence": [{
-                    "type": "junit",
-                    "description": f"{test.get('status')}: {test.get('title', '')}",
-                    "source": test.get("file", "execution-result"),
-                }],
-            })
-    return signals
-
-
-def _recommendations(entries):
-    """Ranked, de-duplicated recommendations — highest priority first."""
-    seen, ranked = set(), []
-    for entry in entries:
-        rec = entry["rootCause"]["recommendation"]
-        if rec not in seen:
-            seen.add(rec)
-            ranked.append({
-                "action": rec,
-                "priority": entry["priority"]["priority"],
-                "owner": entry["rootCause"]["ownership"],
-                "classification": entry["rootCause"]["classification"],
-            })
-    return ranked
-
-
-def _release_readiness(execution_result, diagnosis):
-    failed = (execution_result or {}).get("tests", {}).get("failed", 0)
-    if failed == 0 and not diagnosis["entries"]:
-        return "ready"
-    classes = {e["rootCause"]["classification"] for e in diagnosis["entries"]}
-    if classes & _RELEASE_BLOCKING:
-        return "not-ready"
-    if classes <= {taxonomy.UNKNOWN}:
-        return "insufficient-data"
-    return "ready-with-risks"

package/shared/diagnostics/lib/qa_diagnostics/internal_contracts.py

@@ -1,75 +0,0 @@
-"""Validate internal Analysis → Diagnostics seam payloads.
-
-Uses the existing dependency-free qa_analysis.contracts validator against
-schemas under shared/diagnostics/schemas/internal/.
-
-The schemas must be reachable in **both** layouts this package runs in:
-
-- the repository, where they live at `shared/diagnostics/schemas/internal/`; and
-- a bundled skill, where the installer materializes the package into
-  `<skill>/scripts/lib/qa_diagnostics/` and copies the schemas alongside it as
-  package data (`qa_diagnostics/schemas/internal/`).
-
-Resolution therefore tries package-local data first and falls back to the
-canonical repository path. Missing schemas raise `InternalContractError` naming
-the locations tried, rather than a bare FileNotFoundError from deep inside a
-diagnosis.
-"""
-
-from __future__ import annotations
-
-import json
-from pathlib import Path
-
-from qa_analysis import contracts
-
-_HERE = Path(__file__).resolve().parent
-
-# Ordered candidates: bundled package data first, then the repository layout.
-_SCHEMA_DIRS = (
-    _HERE / "schemas" / "internal",
-    _HERE.parents[1] / "schemas" / "internal",
-)
-
-
-class InternalContractError(ValueError):
-    """Raised when an internal seam payload fails its schema."""
-
-
-def schema_dir() -> Path:
-    """The directory holding the internal schemas, whichever layout applies."""
-    for candidate in _SCHEMA_DIRS:
-        if candidate.is_dir():
-            return candidate
-    tried = ", ".join(str(c) for c in _SCHEMA_DIRS)
-    raise InternalContractError(
-        f"internal schemas not found; tried: {tried}. "
-        "A bundled skill must carry qa_diagnostics/schemas/internal/ as package data."
-    )
-
-
-def _load(name: str) -> dict:
-    path = schema_dir() / name
-    if not path.is_file():
-        raise InternalContractError(f"internal schema missing: {path}")
-    return json.loads(path.read_text(encoding="utf-8"))
-
-
-def _require(payload: dict, schema_name: str) -> dict:
-    schema = _load(schema_name)
-    ok, errors = contracts.validate(payload, schema)
-    if not ok:
-        raise InternalContractError(f"{schema_name}: " + "; ".join(errors))
-    return payload
-
-
-def validate_analysis_result(payload: dict) -> dict:
-    return _require(payload, "analysis-result.schema.json")
-
-
-def validate_execution_result_min(payload: dict) -> dict:
-    return _require(payload, "execution-result-min.schema.json")
-
-
-def validate_diagnosis(payload: dict) -> dict:
-    return _require(payload, "diagnosis.schema.json")