qa-engineer 0.9.0

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

@@ -0,0 +1,124 @@
+"""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

@@ -0,0 +1,143 @@
+"""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

@@ -0,0 +1,75 @@
+"""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")

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

@@ -0,0 +1,101 @@
+"""Deterministic finding prioritization.
+
+Assigns every finding a severity, priority, the three impacts, an owner, and an
+estimated effort — by a fixed algorithm, so the same finding always ranks the
+same way. Priority is not a feeling; it is a function of severity, confidence,
+and business impact.
+"""
+
+from qa_analysis import taxonomy
+
+# Base severity per classification (before confidence adjustment).
+_SEVERITY = {
+    taxonomy.APPLICATION_BUG: "high",
+    taxonomy.INFRASTRUCTURE: "high",
+    taxonomy.NETWORK: "high",
+    taxonomy.AUTH: "high",
+    taxonomy.AUTHORIZATION: "high",
+    taxonomy.ASSERTION: "medium",
+    taxonomy.LOCATOR: "medium",
+    taxonomy.TIMEOUT: "medium",
+    taxonomy.TEST_DATA: "medium",
+    taxonomy.CONFIGURATION: "medium",
+    taxonomy.ENVIRONMENT: "medium",
+    taxonomy.FRAMEWORK: "medium",
+    taxonomy.FLAKY: "medium",
+    taxonomy.UNKNOWN: "low",
+}
+
+# Where the impact predominantly lands, per classification.
+_IMPACT = {
+    taxonomy.APPLICATION_BUG: {"business": "high", "technical": "high", "testing": "low"},
+    taxonomy.NETWORK: {"business": "high", "technical": "high", "testing": "medium"},
+    taxonomy.AUTH: {"business": "high", "technical": "medium", "testing": "medium"},
+    taxonomy.AUTHORIZATION: {"business": "high", "technical": "medium", "testing": "medium"},
+    taxonomy.INFRASTRUCTURE: {"business": "medium", "technical": "high", "testing": "high"},
+    taxonomy.LOCATOR: {"business": "low", "technical": "low", "testing": "high"},
+    taxonomy.ASSERTION: {"business": "medium", "technical": "medium", "testing": "medium"},
+    taxonomy.TIMEOUT: {"business": "low", "technical": "medium", "testing": "high"},
+    taxonomy.TEST_DATA: {"business": "low", "technical": "low", "testing": "high"},
+    taxonomy.CONFIGURATION: {"business": "low", "technical": "medium", "testing": "high"},
+    taxonomy.ENVIRONMENT: {"business": "low", "technical": "medium", "testing": "high"},
+    taxonomy.FRAMEWORK: {"business": "low", "technical": "medium", "testing": "high"},
+    taxonomy.FLAKY: {"business": "low", "technical": "low", "testing": "high"},
+    taxonomy.UNKNOWN: {"business": "low", "technical": "low", "testing": "medium"},
+}
+
+# Rough effort to resolve, per classification.
+_EFFORT = {
+    taxonomy.LOCATOR: "low",
+    taxonomy.ASSERTION: "low",
+    taxonomy.CONFIGURATION: "low",
+    taxonomy.ENVIRONMENT: "low",
+    taxonomy.TEST_DATA: "medium",
+    taxonomy.TIMEOUT: "medium",
+    taxonomy.FLAKY: "medium",
+    taxonomy.AUTH: "medium",
+    taxonomy.AUTHORIZATION: "medium",
+    taxonomy.FRAMEWORK: "medium",
+    taxonomy.NETWORK: "high",
+    taxonomy.INFRASTRUCTURE: "high",
+    taxonomy.APPLICATION_BUG: "external",
+    taxonomy.UNKNOWN: "unknown",
+}
+
+_RANK = {"low": 1, "medium": 2, "high": 3}
+_PRIORITY = {1: "P3", 2: "P2", 3: "P1", 4: "P1"}
+
+
+def prioritize(root_cause, blocking=False):
+    """Prioritize a root cause. Returns a dict with severity, priority, the three
+    impacts, confidence, owner, and estimatedEffort.
+
+    priority derives from severity, business impact, and confidence, and is
+    escalated one step when the failure blocks a release (blocking=True).
+    """
+    classification = root_cause["classification"]
+    confidence = root_cause.get("confidence", 0.5)
+    severity = _SEVERITY.get(classification, "low")
+    impact = _IMPACT.get(classification, _IMPACT[taxonomy.UNKNOWN])
+
+    # Priority score: severity and business impact drive it; low confidence
+    # holds it back (an uncertain finding should not top the queue).
+    score = _RANK[severity]
+    if impact["business"] == "high":
+        score += 1
+    if confidence < 0.5:
+        score -= 1
+    if blocking:
+        score += 1
+    score = max(1, min(4, score))
+
+    return {
+        "severity": severity,
+        "priority": _PRIORITY[score],
+        "businessImpact": impact["business"],
+        "technicalImpact": impact["technical"],
+        "testingImpact": impact["testing"],
+        "confidence": confidence,
+        "owner": root_cause.get("ownership", "needs-triage"),
+        "estimatedEffort": _EFFORT.get(classification, "unknown"),
+    }

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

@@ -0,0 +1,72 @@
+"""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.
+"""
+
+from qa_analysis import taxonomy
+
+# classification -> (repairable, candidate type, abstract change, risk).
+# Only test-side causes are repairable; product, network, infra, auth, and
+# environment failures are escalations, not repairs.
+_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"),
+}
+
+
+def plan_repair(root_cause, affected_files=None):
+    """Produce a repair plan for a root cause. Returns a dict:
+    {repairable, candidateType, proposedChanges, affectedFiles, risk,
+    permissionRequired, rollbackStrategy, safetyReview}. Never contains code.
+    """
+    classification = root_cause["classification"]
+    repairable, candidate, change, risk = _PLANS.get(classification, _PLANS[taxonomy.UNKNOWN])
+
+    if repairable:
+        safety = ("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.")
+        rollback = "No source is changed without approval; revert the proposed edits to roll back."
+    else:
+        safety = "No test-side edit is appropriate; this is an escalation, not a repair."
+        rollback = "Not applicable — no change is proposed."
+
+    return {
+        "repairable": repairable,
+        "candidateType": candidate,
+        "proposedChanges": [change] if repairable else [],
+        "affectedFiles": list(affected_files or []),
+        "risk": risk,
+        "permissionRequired": True,
+        "rollbackStrategy": rollback,
+        "safetyReview": safety,
+    }

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

@@ -0,0 +1,89 @@
+"""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`.
+"""
+
+from qa_analysis import taxonomy
+
+# classification -> the party that typically owns the fix.
+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).
+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.",
+}
+
+
+def analyze(signal):
+    """Classify a failure signal into a root cause.
+
+    signal is a dict that may contain: message, httpStatus, retries, finalStatus,
+    evidence (a list of evidence refs). Returns a dict:
+    {classification, confidence, reason, ownership, recommendation, evidence}.
+    """
+    message = signal.get("message", "")
+    http_status = signal.get("httpStatus")
+    retries = signal.get("retries", 0) or 0
+    final_status = signal.get("finalStatus")
+
+    provided = signal.get("classification")
+
+    # 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 final_status == "flaky" or (retries > 0 and final_status in ("passed", "flaky")):
+        classification, confidence, reason = (
+            taxonomy.FLAKY, 0.8,
+            "The test passed only after a retry, indicating nondeterministic behavior.",
+        )
+    elif provided in taxonomy.CLASSES:
+        # The analysis platform already classified this deterministically; trust it
+        # rather than re-deriving from the message.
+        classification = provided
+        confidence = signal.get("confidence", 0.8)
+        reason = signal.get("reason") or f"Classified {provided} by the analysis platform."
+    else:
+        classification, confidence, reason = taxonomy.classify(message, http_status=http_status)
+
+    return {
+        "classification": classification,
+        "confidence": confidence,
+        "reason": reason,
+        "ownership": OWNERSHIP.get(classification, "needs-triage"),
+        "recommendation": RECOMMENDATION.get(classification, RECOMMENDATION[taxonomy.UNKNOWN]),
+        "evidence": signal.get("evidence", []),
+    }