misterdev 0.2.0__py3-none-any.whl

misterdev/core/verification/gatekeeper/constants.py

@@ -0,0 +1,138 @@
+import re
+
+# Patterns that indicate incomplete or debug code
+BANNED_MARKERS = ("todo!", "FIXME", "HACK", "XXX", "placeholder", "dummy")
+
+# High-signal patterns: a bare substring match is enough to flag a file. Only
+# DISTINCTIVE provider prefixes belong here — a short fragment like "sk_" would
+# substring-match ordinary identifiers (task_, disk_) and block legitimate code,
+# so Stripe/AWS use their full prefixes.
+SECRET_PATTERNS = (
+    "PRIVATE KEY",
+    "BEGIN RSA",
+    "BEGIN EC",
+    "BEGIN DSA",
+    "sk_live_",  # Stripe secret (live)
+    "sk_test_",  # Stripe secret (test)
+    "ghp_",  # GitHub PAT
+    "gho_",  # GitHub OAuth
+    "ghs_",  # GitHub server-to-server
+    "ghu_",  # GitHub user-to-server
+    "ghr_",  # GitHub refresh
+    "github_pat_",  # GitHub fine-grained PAT
+    "glpat-",  # GitLab PAT
+    "xoxb-",  # Slack bot token
+    "xoxp-",  # Slack user token
+    "AIza",  # Google API key
+    "AKIA",  # AWS access key id
+    "ASIA",  # AWS temporary access key id
+)
+
+# Patterns too short to match as a bare substring without colliding with ordinary
+# tokens. "sk-" alone substring-matches kebab-case identifiers/URLs (disk-size,
+# task-list, /task-…), so an OpenAI key is matched by a boundaried regex anchored
+# at a word boundary (excludes di"sk-"/ta"sk-"). The run then qualifies EITHER by
+# containing a digit (≥6 chars — catches typical high-entropy keys and short
+# fakes) OR by being very long (≥40 chars — catches a rare all-letter real key,
+# which is 48+ chars, without matching the short word-like "sk-spinner" CSS-class
+# identifiers a human writes).
+SECRET_REGEXES = (
+    re.compile(
+        r"\bsk-(?:(?=[A-Za-z0-9_-]*\d)[A-Za-z0-9_-]{6,}|[A-Za-z0-9_-]{40,})"
+    ),  # OpenAI
+)
+
+# Low-signal credential keys. These appear constantly in ordinary source
+# (struct fields, function params, config keys), so they are only flagged when
+# assigned a concrete quoted literal, not a variable/env reference.
+ASSIGNMENT_SECRET_KEYS = (
+    "password",
+    "passwd",
+    "secret",
+    "api_key",
+    "apikey",
+    "access_key",
+    "token",
+)
+
+# In a quoted credential VALUE these mark an environment/variable REFERENCE (the
+# secret is read from elsewhere), so the literal is a reference, not a leak, and
+# is skipped. Deliberately specific: a bare "env" substring test also skipped a
+# real credential that merely contains those three letters (e.g. "Denver7x9").
+ENV_REFERENCE_MARKERS = (
+    "os.environ",
+    "getenv",
+    "process.env",
+    "${",
+    "{{",
+    "%(",
+    "$env",
+)
+
+# Extensions to skip during file scanning
+SKIP_DIRS = frozenset(
+    {
+        ".venv",
+        "venv",
+        ".git",
+        "node_modules",
+        "__pycache__",
+        "target",
+        "build",
+        "dist",
+        ".tox",
+        ".mypy_cache",
+        ".eggs",
+    }
+)
+
+CODE_EXTENSIONS = frozenset(
+    {
+        ".py",
+        ".js",
+        ".ts",
+        ".tsx",
+        ".jsx",
+        ".rs",
+        ".go",
+        ".java",
+        ".c",
+        ".cpp",
+        ".h",
+        ".rb",
+        ".php",
+        ".swift",
+        ".kt",
+        ".sh",
+    }
+)
+
+# Secrets leak through config/env files just as readily as source — and a
+# planted credential there is never "code", so the code-only scan (G5/G9) misses
+# it. G6 therefore scans these in addition to CODE_EXTENSIONS. Banned-marker and
+# debug-artifact scans deliberately stay code-only (a TODO in a YAML is fine).
+SECRET_SCAN_EXTENSIONS = CODE_EXTENSIONS | frozenset(
+    {
+        ".env",
+        ".yaml",
+        ".yml",
+        ".json",
+        ".toml",
+        ".ini",
+        ".cfg",
+        ".conf",
+        ".properties",
+        ".xml",
+        ".tfvars",
+    }
+)
+
+# Dotfiles whose whole name is the extension (``Path(".env").suffix == ""``), so
+# they must be matched by name rather than suffix.
+SECRET_SCAN_FILENAMES = frozenset({".env", ".envrc", ".netrc", ".pgpass"})
+
+# File types where ``KEY=value`` is a literal config assignment (so an UNQUOTED
+# value can be a real secret), as opposed to source code where an unquoted RHS
+# is a variable reference. Used to gate the unquoted-secret heuristic so it never
+# fires on .py/.rs/etc and blocks legitimate code.
+ENV_LITERAL_EXTENSIONS = frozenset({".env", ".ini", ".properties", ".conf", ".cfg"})

misterdev/core/verification/gatekeeper/helpers.py

@@ -0,0 +1,28 @@
+from pathlib import Path
+from typing import Optional
+
+# Cap how much of a single file the scanners read into memory. A generated
+# project can contain a multi-GB file (data dumps, bundles); reading it whole to
+# grep for secrets would exhaust the gate's memory. Secrets/markers of interest
+# live near the top or in small config files, so the head is what matters.
+_MAX_SCAN_CHARS = 2_000_000
+
+
+def _path_in_scope(
+    path_str: str,
+    extensions: frozenset,
+    filenames: frozenset = frozenset(),
+) -> bool:
+    """True when ``path_str`` is in scope by file extension or exact name."""
+    p = Path(path_str)
+    return p.suffix in extensions or p.name in filenames
+
+
+def _read_capped(path: Path, max_chars: int = _MAX_SCAN_CHARS) -> Optional[str]:
+    """Read at most ``max_chars`` characters of ``path`` for scanning, or ``None``
+    on an OS error. Bounds memory so a huge file can't OOM the gate."""
+    try:
+        with path.open("r", encoding="utf-8", errors="replace") as fh:
+            return fh.read(max_chars)
+    except OSError:
+        return None

misterdev/core/verification/goal_check.py

@@ -0,0 +1,219 @@
+"""Optional goal-completion check (LLM judge).
+
+Green gates prove the code compiles, tests pass, and the diff is hygienic — but
+not that the work actually accomplished what was asked. "Gates green != goal
+met": a build can satisfy every mechanical gate while quietly omitting a feature
+the goal called for. This check closes that gap. Given the goal text, the
+acceptance criteria, and the cumulative diff/summary of the build, an LLM judge
+returns a verdict {satisfied: bool, gaps: [str]}.
+
+It mirrors :mod:`misterdev.core.verification.vision_verify`: best-effort and run
+in a daemon worker thread with a hard timeout so a slow or unreachable model can
+NEVER block the build. It is ADVISORY by default — the verdict's gaps are
+recorded into the report and logged, and the build is NOT failed. It blocks only
+when ``orchestrator.block_on_goal_gap`` is true (the caller's choice). Absent a
+goal / criteria, absent an LLM client, an unparseable verdict, or a timeout is a
+SKIP (no opinion), never a failure.
+
+Like the vision gate, the signal IS a model judgment, so the judge is shown the
+concrete evidence the build produced (the diff/summary) rather than asked to
+self-report on intent.
+"""
+
+from typing import Callable, List, Optional
+
+from misterdev.core.execution.bounded import run_bounded
+from misterdev.core.verification.independent import build_independent_call
+from misterdev.llm.responses import (
+    extract_json_object as _extract_json_object,
+)
+from misterdev.logging_setup import setup_logger
+
+logger = setup_logger(__name__)
+
+# Outcome constants. SKIP means "no opinion" (no goal/criteria/client, an
+# unparseable verdict, or a timeout) and must never be treated as a pass/fail
+# signal by callers.
+SKIP = "skip"
+SATISFIED = "satisfied"
+GAP = "gap"
+
+_PROMPT = (
+    "You are a strict acceptance reviewer. Decide whether the WORK that was done "
+    "actually satisfies the stated GOAL and ACCEPTANCE CRITERIA. Judge only from "
+    "the evidence given; do not assume work that is not shown.\n\n"
+    "## Goal\n{goal}\n\n"
+    "## Acceptance Criteria\n{criteria}\n\n"
+    "## Work Done (diff / summary)\n{evidence}\n\n"
+    "Reply with a single JSON object on the first line and nothing else:\n"
+    '{{"satisfied": true|false, "gaps": ["short description of each unmet '
+    'requirement"]}}\n'
+    "If satisfied is true, gaps must be an empty list. Keep each gap to one "
+    "sentence."
+)
+
+# Cap the evidence we feed the judge so a huge diff can't blow up the prompt or
+# cost; the head of a diff carries the most signal (new files, signatures).
+_MAX_EVIDENCE_CHARS = 16000
+
+# A judge call takes the assembled prompt text and returns the model's text.
+# Injected in tests; defaulted to the project client's generate_code path.
+JudgeCall = Callable[[str], str]
+
+
+class GoalVerdict:
+    """Outcome of a goal-completion check.
+
+    ``status`` is SKIP / SATISFIED / GAP. ``gaps`` lists the unmet requirements
+    (empty when satisfied or skipped). ``raw`` is the model's text (evidence);
+    ``reason`` explains a SKIP.
+    """
+
+    def __init__(
+        self,
+        status: str,
+        gaps: Optional[List[str]] = None,
+        raw: str = "",
+        reason: str = "",
+    ):
+        self.status = status
+        self.gaps = list(gaps or [])
+        self.raw = raw
+        self.reason = reason
+
+    @property
+    def satisfied(self) -> bool:
+        return self.status == SATISFIED
+
+    @property
+    def skipped(self) -> bool:
+        return self.status == SKIP
+
+    @property
+    def has_gap(self) -> bool:
+        return self.status == GAP
+
+    def __repr__(self) -> str:
+        return f"GoalVerdict(status={self.status!r}, gaps={len(self.gaps)})"
+
+
+def run_goal_check(
+    goal: Optional[str],
+    criteria: Optional[str],
+    evidence: Optional[str],
+    judge_call: Optional[JudgeCall] = None,
+    llm_client=None,
+    judge_model: Optional[str] = None,
+    timeout: float = 60,
+) -> GoalVerdict:
+    """Judge whether ``evidence`` satisfies ``goal`` + ``criteria``.
+
+    The model call is performed by ``judge_call`` when supplied (the test seam);
+    otherwise one is built from ``llm_client`` if provided. ``judge_model``, when
+    given, routes the judgment through an INDEPENDENT model so it does not share
+    the generator's blind spots (its absence is logged — the same-model judge is
+    weaker). With neither a callable nor a client, the check SKIPs (no model).
+    SKIP also when there is no goal AND no criteria (no target to judge against),
+    on an unparseable verdict, on any judge error, or on the hard timeout (never
+    blocks). ``timeout`` is the hard ceiling for the whole run.
+    """
+    if not (goal or "").strip() and not (criteria or "").strip():
+        return GoalVerdict(SKIP, reason="no goal or acceptance criteria")
+
+    call = judge_call or _default_judge_call(llm_client, judge_model)
+    if call is None:
+        return GoalVerdict(SKIP, reason="no LLM judge available")
+
+    prompt = _PROMPT.format(
+        goal=(goal or "(none given)").strip(),
+        criteria=(criteria or "(none given)").strip(),
+        evidence=(evidence or "(no diff/summary captured)").strip()[
+            :_MAX_EVIDENCE_CHARS
+        ],
+    )
+
+    def _work() -> GoalVerdict:
+        try:
+            return _parse_verdict(call(prompt) or "")
+        except Exception as e:  # any model/IO failure is non-fatal -> skip
+            logger.debug(f"Goal-completion check unavailable: {e}")
+            return GoalVerdict(SKIP, reason=f"error: {e}")
+
+    return run_bounded(
+        _work, timeout, GoalVerdict(SKIP, reason="timed out"), "Goal-completion check"
+    )
+
+
+def _parse_verdict(text: str) -> GoalVerdict:
+    """Deterministically parse the judge's JSON verdict.
+
+    Tolerates surrounding prose and markdown fences by extracting the first
+    balanced ``{...}`` object. A missing/invalid object, or a missing
+    ``satisfied`` boolean, is a SKIP (no opinion), not a failure. When
+    ``satisfied`` is false, ``gaps`` is normalized to a list of non-empty
+    strings; an unsatisfied verdict with no listed gaps still records one
+    generic gap so the report never claims a gap exists without saying which.
+    """
+    if not text or not text.strip():
+        return GoalVerdict(SKIP, raw=text, reason="empty verdict")
+
+    obj = _extract_json_object(text)
+    if obj is None or "satisfied" not in obj:
+        return GoalVerdict(SKIP, raw=text, reason="unparseable verdict")
+
+    satisfied = obj.get("satisfied")
+    if not isinstance(satisfied, bool):
+        return GoalVerdict(SKIP, raw=text, reason="non-boolean 'satisfied'")
+
+    if satisfied:
+        return GoalVerdict(SATISFIED, gaps=[], raw=text)
+
+    gaps_raw = obj.get("gaps")
+    gaps: List[str] = []
+    if isinstance(gaps_raw, list):
+        for g in gaps_raw:
+            if isinstance(g, str) and g.strip():
+                gaps.append(g.strip())
+    elif isinstance(gaps_raw, str) and gaps_raw.strip():
+        gaps.append(gaps_raw.strip())
+    if not gaps:
+        gaps = ["goal not satisfied (no specific gap reported)"]
+    return GoalVerdict(GAP, gaps=gaps, raw=text)
+
+
+def _default_judge_call(
+    llm_client, judge_model: Optional[str] = None
+) -> Optional[JudgeCall]:
+    """Build a judge call from the project's LLM client, or None if unusable.
+
+    Uses the client's ``generate_code(prompt, system)`` text interface. When
+    ``judge_model`` is given and the client supports ``with_model``, the call is
+    routed through that INDEPENDENT model; otherwise it runs on the generator's
+    own model and the weaker independence is logged. Kept tolerant of client
+    shape so an absent/limited client degrades to SKIP rather than raising. No
+    network is touched until the returned callable is invoked inside the worker.
+    """
+    system = (
+        "You are a precise acceptance reviewer. Output only the requested JSON "
+        "object. Do not invent work that is not shown in the evidence."
+    )
+    return build_independent_call(
+        llm_client, system, judge_model, "Goal-completion check"
+    )
+
+
+def build_evidence(diff: str = "", summary: str = "") -> str:
+    """Compose the judge's evidence from a diff and/or a summary.
+
+    Either may be empty; the summary (what the build reports it did) is shown
+    first because it is the most compact statement of intent-realized, with the
+    raw diff following as the ground truth. Returned empty when both are empty,
+    which the caller treats as "no evidence" (the judge still runs but is told
+    so, and a satisfied verdict on no evidence is unlikely).
+    """
+    parts = []
+    if summary and summary.strip():
+        parts.append(f"### Summary\n{summary.strip()}")
+    if diff and diff.strip():
+        parts.append(f"### Diff\n{diff.strip()}")
+    return "\n\n".join(parts)

misterdev/core/verification/independent.py

@@ -0,0 +1,68 @@
+"""Shared routing for an INDEPENDENT reviewer/judge model.
+
+The orchestrator runs several LLM judgments that should not share the generating
+model's blind spots: the edit-time adversarial critic, the post-build
+goal-completion check, and the LLM acceptance judge. Each wants the same thing —
+run ``generate_code`` on a configured independent model when the client can
+switch to it, otherwise fall back to the generator's own model and make the
+weaker independence visible rather than silent. This centralizes that so the
+three call sites don't each re-implement it.
+"""
+
+from typing import Callable, Optional
+
+from misterdev.logging_setup import setup_logger
+
+logger = setup_logger(__name__)
+
+
+def generate_independent(
+    llm_client, prompt: str, system: str = "", *, model: Optional[str] = None
+) -> str:
+    """Run ``generate_code`` on ``model`` when the client can switch to it.
+
+    Routes through the client's ``with_model`` context manager for a configured
+    independent model; otherwise (no model, or a client without ``with_model``)
+    runs on the client's own model. Returns the model's text (never None).
+    """
+    if model and hasattr(llm_client, "with_model"):
+        with llm_client.with_model(model):
+            return llm_client.generate_code(prompt, system) or ""
+    return llm_client.generate_code(prompt, system) or ""
+
+
+def build_independent_call(
+    llm_client, system: str, model: Optional[str], role: str
+) -> Optional[Callable[[str], str]]:
+    """Build a ``call(prompt) -> str`` bound to an independent model, or None.
+
+    Returns None when ``llm_client`` can't generate text (so the caller SKIPs).
+    Otherwise returns a closure that runs each prompt through ``model`` (when the
+    client supports ``with_model``) or the generator's own model. The
+    independence level is logged ONCE here, at build time — a warning when a
+    model is set but the client can't switch, an info when none is configured —
+    so the weaker case is never silently assumed. ``role`` names the judge for
+    the log. No network is touched until the returned closure is invoked.
+    """
+    if llm_client is None or not hasattr(llm_client, "generate_code"):
+        return None
+
+    can_switch = hasattr(llm_client, "with_model")
+    if model and not can_switch:
+        logger.warning(
+            f"{role}: an independent model is set but the client cannot switch "
+            f"models; running on the generator's own model (weaker independence)."
+        )
+    elif not model:
+        logger.info(
+            f"{role}: no independent model configured; running on the generator's "
+            f"own model (weaker independence — set one for a true second "
+            f"component)."
+        )
+
+    effective = model if (model and can_switch) else None
+
+    def _call(prompt: str) -> str:
+        return generate_independent(llm_client, prompt, system, model=effective)
+
+    return _call

misterdev/core/verification/mutation_gate.py

@@ -0,0 +1,221 @@
+"""Optional mutation-score gate (generic, command-based, language-agnostic).
+
+A passing test suite proves the tests *run* green, but not that they would
+*catch a regression*: a suite with no meaningful assertions passes while a
+mutation testing tool shows it kills almost no injected faults. This gate runs a
+project-configured mutation command, parses a mutation score from its output,
+and asserts it meets a floor.
+
+It is deliberately tool-agnostic: it does NOT hardcode mutmut / cosmic-ray /
+Stryker / cargo-mutants. The project supplies the command and the floor; this
+module just runs it and robustly parses a percentage or fraction from common
+output formats, skipping cleanly when the score is unparseable.
+
+It mirrors :mod:`misterdev.core.execution.runtime`: strictly opt-in (off
+unless ``mutation.command`` is configured and ``orchestrator.mutation_gate`` is
+true), best-effort, and run in a daemon worker thread with a hard timeout so a
+slow or hung mutation run can NEVER block the build. Absent config or a timeout
+is a SKIP (no opinion); an unparseable score is ALSO a SKIP (we will not fail a
+build on a number we could not read); only a parsed score strictly below the
+floor is a RED.
+"""
+
+import re
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+from misterdev.core.execution.bounded import run_bounded
+from misterdev.core.execution.outcomes import (
+    GREEN,
+    RED,
+    SKIP,
+    GateOutcome,
+)
+from misterdev.logging_setup import setup_logger
+
+logger = setup_logger(__name__)
+
+# Outcome constants. SKIP means "no opinion" (no config, unparseable score, or
+# timeout) and must never be treated as a pass/fail signal by callers.
+_MAX_EVIDENCE_CHARS = 16384
+
+# Score patterns, tried in order. Each captures a number normalized to a 0..1
+# fraction by :func:`_parse_score`. Ordered most-specific first so a labeled
+# score ("mutation score: 82%") wins over a bare trailing percentage.
+_SCORE_PATTERNS = (
+    # "mutation score: 82.5%" / "score = 82%" / "killed 82.5 %"
+    re.compile(
+        r"(?:mutation\s+)?score[^0-9]{0,12}([0-9]+(?:\.[0-9]+)?)\s*%",
+        re.IGNORECASE,
+    ),
+    # "mutation score: 0.82" / "score = .82" (fraction, no percent sign)
+    re.compile(
+        r"(?:mutation\s+)?score[^0-9]{0,12}([01](?:\.[0-9]+)?|\.[0-9]+)\b",
+        re.IGNORECASE,
+    ),
+    # "killed 41/50" / "41 / 50 mutants killed" (a ratio)
+    re.compile(r"([0-9]+)\s*/\s*([0-9]+)"),
+    # Fallback: a standalone percentage anywhere ("82.5%").
+    re.compile(r"([0-9]+(?:\.[0-9]+)?)\s*%"),
+)
+
+
+class MutationResult(GateOutcome):
+    """Outcome of a mutation-score gate run.
+
+    ``status`` is SKIP/GREEN/RED; ``score`` is the parsed mutation score as a
+    0..1 fraction (None when unparseable/skipped); ``evidence`` is the captured
+    output (truncated); ``reason`` explains a SKIP/RED.
+    """
+
+    def __init__(
+        self,
+        status: str,
+        score: Optional[float] = None,
+        evidence: str = "",
+        reason: str = "",
+    ):
+        super().__init__(status, reason)
+        self.score = score
+        self.evidence = evidence
+
+    def __repr__(self) -> str:
+        return f"MutationResult(status={self.status!r}, score={self.score!r})"
+
+
+def run_mutation_gate(
+    project_root: Path,
+    mutation_config: Optional[dict],
+    runner=None,
+) -> MutationResult:
+    """Run the mutation gate described by ``mutation_config``.
+
+    ``mutation_config`` keys:
+      - ``command`` (required): the mutation-testing command to run. No command
+        means the feature is off -> SKIP.
+      - ``min_score`` (optional, default 0.0): the floor the parsed score must
+        meet, accepted as a fraction (0.8) or a percentage (80). A score at or
+        above the floor is GREEN, strictly below is RED.
+      - ``timeout`` (optional, default 1800): hard ceiling for the whole run, in
+        seconds (mutation runs are slow). The outer join always returns.
+
+    Returns a :class:`MutationResult`. ``runner`` accepts the gate's container
+    seam ``(cmd, timeout) -> (ok, output)``; when None the command runs locally.
+    """
+    if not mutation_config or not mutation_config.get("command"):
+        return MutationResult(SKIP, reason="no mutation config")
+
+    command = mutation_config["command"]
+    min_score = _normalize_floor(mutation_config.get("min_score", 0.0))
+    timeout = float(mutation_config.get("timeout", 1800))
+
+    def _work() -> MutationResult:
+        try:
+            return _mutation(project_root, command, min_score, timeout, runner)
+        except Exception as e:  # any launch/IO failure is non-fatal -> skip
+            logger.debug(f"Mutation gate unavailable: {e}")
+            return MutationResult(SKIP, reason=f"error: {e}")
+
+    # A small margin over the inner timeout so a clean inner teardown is
+    # preferred, but the outer bound still guarantees we return.
+    return run_bounded(
+        _work, timeout + 5, MutationResult(SKIP, reason="timed out"), "Mutation gate"
+    )
+
+
+def _mutation(
+    project_root: Path,
+    command: str,
+    min_score: float,
+    timeout: float,
+    runner,
+) -> MutationResult:
+    """Run the command, parse a score, and compare it to the floor.
+
+    A non-zero exit is not itself a failure: many mutation tools exit non-zero
+    when survivors exist yet still print a usable score, so we parse the output
+    regardless and only RED on a score below the floor. We SKIP (not RED) when no
+    score can be parsed, so the build is never failed on an unread number.
+    """
+    if runner is not None:
+        ok, output = runner(command, int(timeout))
+    else:
+        try:
+            proc = subprocess.run(
+                command,
+                shell=True,
+                cwd=str(project_root),
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+        except subprocess.TimeoutExpired:
+            return MutationResult(SKIP, reason="command timed out")
+        output = (proc.stdout or "") + (proc.stderr or "")
+
+    evidence = output[-_MAX_EVIDENCE_CHARS:]
+    score = parse_mutation_score(output)
+    if score is None:
+        return MutationResult(
+            SKIP, evidence=evidence, reason="could not parse a mutation score"
+        )
+    if score >= min_score:
+        return MutationResult(GREEN, score=score, evidence=evidence)
+    return MutationResult(
+        RED,
+        score=score,
+        evidence=evidence,
+        reason=f"mutation score {score:.2%} below floor {min_score:.2%}",
+    )
+
+
+def parse_mutation_score(output: str) -> Optional[float]:
+    """Parse a mutation score from ``output`` as a 0..1 fraction, or None.
+
+    Handles labeled percentages ("mutation score: 82.5%"), labeled fractions
+    ("score: 0.82"), kill ratios ("killed 41/50"), and a bare trailing
+    percentage. Returns None when nothing parseable is found OR the value is out
+    of the sane 0..1 range, so a stray number can't be misread as a score.
+    """
+    if not output:
+        return None
+    for pattern in _SCORE_PATTERNS:
+        match = pattern.search(output)
+        if not match:
+            continue
+        groups = match.groups()
+        if len(groups) == 2:  # ratio "killed/total"
+            killed = float(groups[0])
+            total = float(groups[1])
+            if total <= 0:
+                continue
+            value = killed / total
+        else:
+            raw = float(groups[0])
+            # A value > 1 is a percentage even without a sign (the percent
+            # patterns already matched the sign); normalize to a fraction.
+            value = raw / 100.0 if raw > 1 else raw
+        if 0.0 <= value <= 1.0:
+            return value
+    return None
+
+
+def _normalize_floor(value) -> float:
+    """Accept a floor as a fraction (0.8) or a percentage (80) -> 0..1 fraction.
+
+    A value > 1 is read as a percentage. Out-of-range or non-numeric input
+    clamps to a 0.0 floor (effectively "any score passes") rather than raising,
+    so a misconfigured floor degrades to permissive instead of crashing.
+    """
+    try:
+        f = float(value)
+    except (TypeError, ValueError):
+        return 0.0
+    if f > 1.0:
+        f = f / 100.0
+    if f < 0.0:
+        return 0.0
+    if f > 1.0:
+        return 1.0
+    return f