scitex-dev 0.25.0__tar.gz → 0.26.0__tar.gz

{scitex_dev-0.25.0 → scitex_dev-0.26.0}/.scitex/dev/cli-audit-dict.yaml

@@ -40,3 +40,10 @@ intransitive_verbs:
   # ("preflight the deploy", cf. `terraform plan`); Moby classifies it
   # noun-only, tripping §1. It takes no object — it checks lease+runner state.
   - preflight
+  # `scitex-dev gate <workdir>` — GATE a submission at a stage (run the
+  # aggregated pre/post-submission checks, block on an enforced failure).
+  # "gate" is a transitive verb here ("gate the submission"); Moby
+  # classifies it both noun AND verb so §1 flags the noun reading. The verb
+  # meaning is intended — the whole point is to GATE. Same escape hatch as
+  # `run` / `preflight`.
+  - gate

{scitex_dev-0.25.0 → scitex_dev-0.26.0}/CHANGELOG.md

@@ -7,6 +7,28 @@ versions follow [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.26.0] - 2026-07-03
+
+### Added
+- **Submission-gate plugin federation + `scitex-dev gate` CLI (#285).**
+  Operator-directed (cohort-A eval): a pre-submission GATE so a solver can't
+  "submit" without real provenance. `scitex_dev.gate` is a new federation
+  (mirroring `jobs` / `system_deps` / `linter.plugins`): packages register
+  per-stage checks under the `scitex_dev.gate.checks` entry-point group; the
+  `scitex-dev gate --stage=pre-submission <workdir> [--json]` CLI aggregates
+  them so a hook depends ONLY on scitex-dev (SOC — each check reads its own
+  state from the capsule workdir; scitex-dev stays package-agnostic).
+  Contract: `GateCheck(id, stage, run, requires, description)`,
+  `GateResult(passed, findings)`, `Finding(check_id, kind, message, severity,
+  fix_hint)`. Severity is config-driven: a failed check is ADVISORY by default
+  (warn, exit 0) and only BLOCKS (exit 2) when its id is under `gate.enforce`
+  in `<root>/.scitex/dev/config.yaml` (mirrors `project-type: research`
+  escalation); `gate.disable` skips a check; a crashing check fails CLOSED.
+  Ships a built-in `gate-workdir-present` check so a hook can be wired and
+  tested before package checks (scitex-clew `clew-source-reachability`,
+  scitex-dataset `dataset-submission-format`) register. Design doc:
+  `docs/submission-gate.md`.
+
 ## [0.25.0] - 2026-07-03
 
 ### Added

{scitex_dev-0.25.0/src/scitex_dev.egg-info → scitex_dev-0.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scitex-dev
-Version: 0.25.0
+Version: 0.26.0
 Summary: Shared developer utilities for the SciTeX ecosystem
 Author-email: Yusuke Watanabe <ywatanabe@scitex.ai>
 License-Expression: AGPL-3.0-only

scitex_dev-0.26.0/docs/submission-gate.md

@@ -0,0 +1,121 @@
+# Submission Gate — `scitex-dev gate`
+
+Design doc for the cohort-A submission GATE (operator-directed, 2026-07-03).
+Owner: scitex-dev. Consumers: paper-scitex-clew (hooks), scitex-clew +
+scitex-dataset (check plugins).
+
+## Problem
+
+A solver can "submit" without real provenance: the scitex arm writes computed
+outputs and registers `scitex_clew` claims, but SKIPS `@stx.session`, so the
+clew DB has claims yet `runs=0`, the DAG renders empty, and claim status stays
+`partial`. We want a pre-submission GATE that blocks a submit lacking valid
+provenance and tells the solver exactly what to fix.
+
+## Separation of concerns
+
+- **scitex-dev** owns the *contract*, the *aggregation*, and the *CLI*. It is
+  package-agnostic: it never imports scitex-clew / scitex-dataset. The
+  pre-submission hook depends on **only** scitex-dev.
+- Each **leaf** owns its *rule* and reads its *own* state from the capsule
+  workdir (clew → `.scitex/clew/*.db`; dataset → the bound submission file).
+- **paper** owns the hooks and the submit command.
+
+This mirrors scitex-dev's existing federations (`scitex_dev.jobs`,
+`scitex_dev.system_deps`, `scitex_dev.linter.plugins`).
+
+## The contract (`scitex_dev.gate`)
+
+```python
+@dataclass(frozen=True)
+class Finding:
+    check_id: str
+    kind: str            # check-defined code, e.g. "runs_zero", "no_file"
+    message: str
+    severity: str = "error"   # "error" | "warning" | "info" (intrinsic)
+    fix_hint: str = ""        # actionable text the hook echoes on block
+
+@dataclass(frozen=True)
+class GateResult:
+    passed: bool
+    findings: tuple[Finding, ...] = ()
+
+@dataclass(frozen=True)
+class GateCheck:
+    id: str                       # unique; config keys by this
+    stage: str                    # "pre-submission" | "post-submission"
+    run: Callable[[Path, Mapping], GateResult]
+    requires: str = ""            # optional extra import-gate; skip-if-absent
+    description: str = ""
+```
+
+A leaf registers a provider `() -> list[GateCheck]` under the entry-point group
+**`scitex_dev.gate.checks`**:
+
+```toml
+# scitex-clew / pyproject.toml
+[project.entry-points."scitex_dev.gate.checks"]
+scitex-clew = "scitex_clew._gate_plugin:provide"
+```
+
+`run(workdir, config)` receives the capsule workdir and the raw `gate` config
+section; it locates its own state under `workdir` and returns pass/fail +
+findings. A provider that isn't installed simply never registers (graceful);
+`requires=` is a secondary import-gate for cross-package needs.
+
+## Severity model — warn-default, opt-in enforce
+
+A check's `severity` is its intrinsic opinion. Whether a **failure BLOCKS**
+(non-zero exit) is decided by config, not the check:
+
+```yaml
+# <project-root>/.scitex/dev/config.yaml   (the research-flags SSOT)
+gate:
+  enforce:            # check ids that HARD-BLOCK (exit 2) on failure
+    - clew-source-reachability
+    - dataset-submission-format
+  disable:            # check ids skipped entirely
+    - some-check
+```
+
+- Default (not listed) = **advisory**: the failure is reported (warning) but
+  the gate exits 0.
+- Listed under `enforce` = **blocking**: a failure exits 2.
+- A crashing check **fails closed** (a broken provenance check must never
+  silently pass a submission) but still only BLOCKS if it is enforced.
+
+This mirrors the linter's `project-type: research` severity-escalation: warn by
+default, opt-in hard-enforce.
+
+## CLI
+
+```bash
+scitex-dev gate --stage=pre-submission <capsule-workdir> [--json]
+scitex-dev gate --stage=pre-submission --list [--json]   # registered checks
+```
+
+- exit **0** = pass or advisory-only failures
+- exit **2** = at least one *enforced* check failed → the hook blocks the submit
+- `--json` emits the full report (per-check `passed`/`enforced`/`blocked` +
+  each `finding.fix_hint`) for the hook to render feedback.
+
+## Wiring (paper side)
+
+- `to_home/.claude/hooks/` **pre-submission** → `scitex-dev gate
+  --stage=pre-submission <workdir> --json`; block on exit 2, render each
+  `fix_hint` to the solver.
+- Replace the fragile `drive_until='DONE'` trigger with a **submit** command:
+  pre-gate → (block or) submit → post-score.
+- **post-submission** scoring stays paper-side (the cohort's oracle-scorer); a
+  `post-submission` stage seam is left open for a future federated post-check.
+
+## Planned checks
+
+| id | stage | owner | fails when |
+|----|-------|-------|-----------|
+| `gate-workdir-present` | pre-submission | scitex-dev (built-in) | workdir missing (wiring sanity) |
+| `clew-source-reachability` | pre-submission | scitex-clew | `runs==0` OR any submission-backing claim partial/unsourced (v0.8.0 UNSOURCED gate) |
+| `dataset-submission-format` | pre-submission | scitex-dataset | `validate_submission(...)["ok"]` is False (non-`WARN_KINDS` error) |
+
+The built-in `gate-workdir-present` ships now so the hook can be wired and
+tested before the two package checks register.

{scitex_dev-0.25.0 → scitex_dev-0.26.0}/pyproject.toml

@@ -145,6 +145,16 @@ scitex-dev-ecosystem = "scitex_dev._ecosystem_jobs._provider:provide_jobs"
 # scholar-library-sync managed cron job (scitex-ssh sync wraps rsync).
 scitex-dev = "scitex_dev._system_deps:provide"
 
+# Federated SUBMISSION-GATE check providers live under the entry-point group
+# `scitex_dev.gate.checks`. Each entry point loads to a callable returning
+# `list[scitex_dev.gate.GateCheck]`; `scitex_dev.gate.discover_gate_checks()`
+# aggregates them (deduped by check id). The `scitex-dev gate` CLI runs them
+# so a hook depends ONLY on scitex-dev. scitex-dev ships its own built-in
+# check via an INTERNAL provider (always merged, not an entry point), so it
+# declares no provider here; this group is for downstream leaves, e.g.:
+#   scitex-clew    = "scitex_clew._gate_plugin:provide"
+#   scitex-dataset = "scitex_dataset._gate_plugin:provide"
+
 [project.urls]
 Homepage = "https://github.com/ywatanabe1989/scitex-dev"
 Repository = "https://github.com/ywatanabe1989/scitex-dev"

{scitex_dev-0.25.0 → scitex_dev-0.26.0}/src/scitex_dev/_cli/_root.py

@@ -479,3 +479,13 @@ except Exception:
 from ._list_apis import register_list_python_apis_command
 
 register_list_python_apis_command(main)
+
+# -------------------------------------------------------------------
+# gate — submission-gate plugin federation (scitex_dev.gate.checks).
+# Leaves register per-package pre/post-submission checks; the hook calls
+# ONLY `scitex-dev gate`, staying package-agnostic (SOC).
+# -------------------------------------------------------------------
+
+from .gate import register_gate_command
+
+register_gate_command(main)

scitex_dev-0.26.0/src/scitex_dev/_cli/gate/__init__.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: src/scitex_dev/_cli/gate/__init__.py
+"""``scitex-dev gate`` CLI package."""
+
+from ._cmd import register_gate_command
+
+__all__ = ["register_gate_command"]

scitex_dev-0.26.0/src/scitex_dev/_cli/gate/_cmd.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: src/scitex_dev/_cli/gate/_cmd.py
+"""``scitex-dev gate`` — run the aggregated submission gate for a workdir.
+
+The cohort pre-submission hook calls::
+
+    scitex-dev gate --stage=pre-submission <capsule-workdir> --json
+
+and blocks the submit on exit code 2 (a check failed AND is enforced in
+``.scitex/dev/config.yaml``), rendering each finding's ``fix_hint`` to the
+solver. Exit 0 = pass or advisory-only failures. Exit 1 = usage error.
+"""
+
+from __future__ import annotations
+
+import click
+
+
+def register_gate_command(main_group: click.Group) -> None:
+    """Register ``scitex-dev gate`` on the given main group."""
+
+    @main_group.command("gate")
+    @click.argument("workdir", type=click.Path(), required=False)
+    @click.option(
+        "--stage",
+        type=click.Choice(["pre-submission", "post-submission"]),
+        default="pre-submission",
+        show_default=True,
+        help="Which submission stage's checks to run.",
+    )
+    @click.option(
+        "--json",
+        "as_json",
+        is_flag=True,
+        default=False,
+        help="Emit the full report as JSON (for hook consumption).",
+    )
+    @click.option(
+        "--list",
+        "list_only",
+        is_flag=True,
+        default=False,
+        help="List the registered checks for the stage and exit 0 (no run).",
+    )
+    def gate(workdir: str, stage: str, as_json: bool, list_only: bool) -> None:
+        """Aggregate per-package submission checks for WORKDIR at STAGE.
+
+        \b
+        Checks are contributed by packages via the `scitex_dev.gate.checks`
+        entry-point group; a failed check BLOCKS (exit 2) only when its id
+        is under `gate.enforce` in `.scitex/dev/config.yaml` (warn-default).
+
+        \b
+        Example:
+          $ scitex-dev gate --stage=pre-submission ./capsule-007 --json
+        """
+        import json as _json
+
+        from ...gate import discover_gate_checks, report_to_dict, run_gate
+
+        if list_only:
+            checks = discover_gate_checks(stage)
+            if as_json:
+                click.echo(
+                    _json.dumps(
+                        [
+                            {
+                                "id": c.id,
+                                "stage": c.stage,
+                                "requires": c.requires,
+                                "description": c.description,
+                            }
+                            for c in checks
+                        ]
+                    )
+                )
+            else:
+                if not checks:
+                    click.echo(f"(no gate checks registered for stage {stage!r})")
+                for c in checks:
+                    click.echo(f"{c.id}  [{c.stage}]  {c.description}")
+            raise SystemExit(0)
+
+        if not workdir:
+            raise click.UsageError("WORKDIR is required unless --list is given.")
+
+        report = run_gate(workdir, stage)
+
+        if as_json:
+            click.echo(_json.dumps(report_to_dict(report)))
+            raise SystemExit(2 if report.blocking else 0)
+
+        _render_human(report)
+        raise SystemExit(2 if report.blocking else 0)
+
+    return None
+
+
+def _render_human(report) -> None:
+    """Human-readable gate report to stdout/stderr."""
+    header = (
+        f"gate [{report.stage}] {report.workdir}: "
+        f"{'BLOCK' if report.blocking else 'PASS'}"
+    )
+    click.secho(header, fg="red" if report.blocking else "green", bold=True)
+    for o in report.outcomes:
+        if not o.ran:
+            click.echo(f"  - {o.id}: skipped ({o.skipped_reason})")
+            continue
+        tag = "BLOCK" if o.blocked else ("fail" if o.passed is False else "ok")
+        enforce = " [enforced]" if o.enforced else ""
+        click.echo(f"  - {o.id}: {tag}{enforce}")
+        for f in o.findings:
+            click.echo(f"      {f.severity}: {f.message}")
+            if f.fix_hint:
+                click.echo(f"      fix: {f.fix_hint}")
+
+
+__all__ = ["register_gate_command"]

scitex_dev-0.26.0/src/scitex_dev/gate/__init__.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: src/scitex_dev/gate/__init__.py
+"""Submission-gate plugin federation for scitex-dev.
+
+A capsule/submission GATE that aggregates per-package validation checks
+as PLUGINS: leaves register a ``GateCheck`` provider under the
+``scitex_dev.gate.checks`` entry-point group; scitex-dev owns the
+contract, the aggregation, and the ``scitex-dev gate`` CLI, and stays
+package-agnostic (each check locates + reads its own state given the
+capsule workdir). Behaviour is configured by which packages are installed
+plus a per-check ``enforce`` knob in ``.scitex/dev/config.yaml`` — the
+pre-submission hook depends ONLY on scitex-dev.
+
+See ``_skills/... submission-gate`` / the design doc for the full model.
+"""
+
+from __future__ import annotations
+
+from ._config import GateConfig, load_gate_config
+from ._discover import ENTRY_POINT_GROUP, discover_gate_checks
+from ._run import CheckOutcome, GateReport, report_to_dict, run_gate
+from ._spec import (
+    SEVERITIES,
+    STAGES,
+    Finding,
+    GateCheck,
+    GateCheckProvider,
+    GateResult,
+)
+
+__all__ = [
+    "STAGES",
+    "SEVERITIES",
+    "Finding",
+    "GateResult",
+    "GateCheck",
+    "GateCheckProvider",
+    "ENTRY_POINT_GROUP",
+    "discover_gate_checks",
+    "GateConfig",
+    "load_gate_config",
+    "CheckOutcome",
+    "GateReport",
+    "run_gate",
+    "report_to_dict",
+]

scitex_dev-0.26.0/src/scitex_dev/gate/_builtin.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: src/scitex_dev/gate/_builtin.py
+"""scitex-dev's own built-in GateCheck(s).
+
+Ships a single trivial pre-submission check — ``gate-workdir-present`` —
+so the cohort's pre/post-submission hooks can wire and test
+``scitex-dev gate --stage=pre-submission <workdir>`` end-to-end BEFORE
+scitex-clew's source-reachability and scitex-dataset's format checks
+register (paper-scitex-clew explicitly asked for this skeleton).
+
+Registered via an INTERNAL provider (always merged by
+``discover_gate_checks``), not an entry point — so scitex-dev never
+double-counts its own built-in and it is always available.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Mapping
+
+from ._spec import Finding, GateCheck, GateResult
+
+
+def _workdir_present(workdir: Path, config: Mapping) -> GateResult:
+    """Pass iff ``workdir`` exists and is a directory.
+
+    Deliberately minimal — it validates the HOOK WIRING (a real capsule
+    workdir was passed) rather than any package's provenance. Its value
+    is being installable-free: it lets the hook be built and exercised
+    while the real package checks are still in flight.
+    """
+    p = Path(workdir)
+    if p.is_dir():
+        return GateResult(passed=True)
+    return GateResult(
+        passed=False,
+        findings=(
+            Finding(
+                check_id="gate-workdir-present",
+                kind="no_workdir",
+                message=f"submission workdir does not exist or is not a directory: {p}",
+                severity="error",
+                fix_hint=(
+                    "pass an existing capsule workdir to "
+                    "`scitex-dev gate --stage=pre-submission <workdir>`"
+                ),
+            ),
+        ),
+    )
+
+
+BUILTIN_CHECKS: tuple[GateCheck, ...] = (
+    GateCheck(
+        id="gate-workdir-present",
+        stage="pre-submission",
+        run=_workdir_present,
+        requires="",
+        description=(
+            "scitex-dev built-in: the submission workdir exists "
+            "(validates hook wiring before package checks land)."
+        ),
+    ),
+)
+
+
+def provide() -> list[GateCheck]:
+    """Internal provider — scitex-dev's own built-in gate checks."""
+    return list(BUILTIN_CHECKS)
+
+
+__all__ = ["BUILTIN_CHECKS", "provide"]

scitex_dev-0.26.0/src/scitex_dev/gate/_config.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: src/scitex_dev/gate/_config.py
+"""Load the ``gate`` section of ``.scitex/dev/config.yaml``.
+
+The gate's SEVERITY model is config-driven (operator directive
+2026-07-03): a check's failure is ADVISORY by default (warn, exit 0) and
+only BLOCKS (exit 2) when the check id is listed under ``gate.enforce`` in
+the project-root ``.scitex/dev/config.yaml`` — the same research-project
+flags SSOT the linter's ``project-type`` escalation reads. This mirrors
+that escalation model: warn-by-default, opt-in hard-enforce per check.
+
+Schema::
+
+    # .scitex/dev/config.yaml
+    gate:
+      enforce:            # check ids that HARD-BLOCK (exit 2) on failure
+        - clew-source-reachability
+        - dataset-submission-format
+      disable:            # check ids skipped entirely
+        - some-check
+      # arbitrary extra keys are passed through to each check's run(config)
+
+Resolution walks up from the workdir to the first ``.scitex/dev/config.yaml``
+(same walk as ``linter._project_type``), so one repo has one SSOT. Missing
+file / missing ``gate`` section ⇒ empty enforce+disable ⇒ everything
+advisory (warn-default). Fail-open: a malformed file yields the empty
+config rather than raising.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_CONFIG_REL = Path(".scitex") / "dev" / "config.yaml"
+
+
+@dataclass(frozen=True)
+class GateConfig:
+    """Resolved ``gate`` config for one workdir."""
+
+    enforce: frozenset[str] = frozenset()
+    disable: frozenset[str] = frozenset()
+    raw: dict = field(default_factory=dict)
+    source: str | None = None  # path of the config file, or None
+
+    def is_enforced(self, check_id: str) -> bool:
+        return check_id in self.enforce
+
+    def is_disabled(self, check_id: str) -> bool:
+        return check_id in self.disable
+
+
+def _find_config_file(start_dir: Path) -> Path | None:
+    current = start_dir.resolve()
+    while True:
+        candidate = current / _CONFIG_REL
+        if candidate.is_file():
+            return candidate
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def load_gate_config(start_path: str | Path) -> GateConfig:
+    """Resolve the ``gate`` config by walking up from ``start_path``.
+
+    ``start_path`` may be a file or directory; the walk begins at its
+    directory. Warn-default on any absence/parse error.
+    """
+    start = Path(start_path)
+    start_dir = start if start.is_dir() else start.parent
+    cfg_path = _find_config_file(start_dir)
+    if cfg_path is None:
+        return GateConfig()
+
+    try:
+        text = cfg_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return GateConfig()
+
+    try:
+        import yaml  # type: ignore[import-untyped]
+
+        data = yaml.safe_load(text) or {}
+    except Exception:
+        # No PyYAML or malformed YAML → warn-default (fail-open). A gate
+        # that silently HARD-BLOCKED on an unreadable config would wedge
+        # every submission; advisory-default is the safe degradation.
+        return GateConfig(source=str(cfg_path))
+
+    gate = data.get("gate") if isinstance(data, dict) else None
+    if not isinstance(gate, dict):
+        return GateConfig(source=str(cfg_path))
+
+    enforce = frozenset(_as_str_list(gate.get("enforce")))
+    disable = frozenset(_as_str_list(gate.get("disable")))
+    return GateConfig(enforce=enforce, disable=disable, raw=gate, source=str(cfg_path))
+
+
+def _as_str_list(value) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, (list, tuple)):
+        return [str(v) for v in value]
+    return []
+
+
+__all__ = ["GateConfig", "load_gate_config"]

scitex_dev-0.26.0/src/scitex_dev/gate/_discover.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# File: src/scitex_dev/gate/_discover.py
+"""Aggregate every ``GateCheck`` declared across the ecosystem.
+
+Mirrors ``discover_jobs`` / ``discover_system_deps``: leaves register a
+provider (``() -> list[GateCheck]``) under the ``scitex_dev.gate.checks``
+entry-point group; this module merges them with scitex-dev's own internal
+built-in provider, dedups by check id (first-wins), and returns a
+deterministic (id-sorted) list. A provider that raises — or an entry
+point that fails to load — is skipped with a logged warning so one broken
+leaf never wedges the gate.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Callable
+
+from ._spec import GateCheck
+
+_logger = logging.getLogger(__name__)
+
+#: Entry-point group every leaf registers its gate-check provider under.
+ENTRY_POINT_GROUP = "scitex_dev.gate.checks"
+
+
+def _iter_entry_points(group: str):
+    """Yield entry points for ``group``, compatible with Python 3.9+."""
+    from importlib.metadata import entry_points
+
+    if sys.version_info >= (3, 10):
+        return entry_points(group=group)
+    return entry_points().get(group, [])
+
+
+def _make_ep_provider(ep) -> Callable[[], list[GateCheck]]:
+    def _provider() -> list[GateCheck]:
+        get_checks = ep.load()
+        return list(get_checks())
+
+    _provider.__name__ = f"entry_point:{getattr(ep, 'name', '?')}"
+    return _provider
+
+
+def discover_gate_checks(
+    stage: str | None = None,
+    *,
+    extra_providers: list[Callable[[], list[GateCheck]]] | None = None,
+    include_entry_points: bool = True,
+    include_builtins: bool = True,
+) -> list[GateCheck]:
+    """Return every registered ``GateCheck``, optionally filtered by stage.
+
+    ``include_entry_points=False`` skips the entry-point walk (the unit-test
+    isolation seam — exact-list assertions stay valid regardless of which
+    real leaf providers are installed). ``include_builtins=False`` drops
+    scitex-dev's own built-in checks. Dedup is by check id, first-wins in
+    provider order (built-ins, then entry points, then ``extra_providers``);
+    the returned list is sorted by id for determinism.
+    """
+    providers: list[Callable[[], list[GateCheck]]] = []
+    if include_builtins:
+        from ._builtin import provide as _builtin_provide
+
+        providers.append(_builtin_provide)
+    if include_entry_points:
+        for ep in _iter_entry_points(ENTRY_POINT_GROUP):
+            providers.append(_make_ep_provider(ep))
+    if extra_providers:
+        providers.extend(extra_providers)
+
+    by_id: dict[str, GateCheck] = {}
+    for provider in providers:
+        try:
+            checks = provider()
+        except Exception:
+            _logger.warning(
+                "Failed to load gate checks from provider %r", provider, exc_info=True
+            )
+            continue
+        for check in checks:
+            if not isinstance(check, GateCheck):
+                _logger.warning(
+                    "Provider %r yielded a non-GateCheck %r; skipping",
+                    provider,
+                    check,
+                )
+                continue
+            if stage is not None and check.stage != stage:
+                continue
+            if check.id in by_id:
+                _logger.warning(
+                    "Duplicate gate-check id %r; keeping the first-registered "
+                    "and dropping %r",
+                    check.id,
+                    provider,
+                )
+                continue
+            by_id[check.id] = check
+
+    return [by_id[cid] for cid in sorted(by_id)]
+
+
+__all__ = ["ENTRY_POINT_GROUP", "discover_gate_checks"]