scitex-dev 0.32.0__tar.gz → 0.34.0__tar.gz

{scitex_dev-0.32.0 → scitex_dev-0.34.0}/.github/workflows/pytest-matrix-on-ubuntu-py3-11-3-12-3-13.yml

@@ -41,8 +41,12 @@ jobs:
           # plain editable so a packaging hiccup doesn't strand CI.
           pip install -e ".[all,dev]" || pip install -e ".[dev]" || pip install -e .
       - name: Run tests
+        # -n auto: parallelise across all runner cores (pytest-xdist, in [dev]).
+        # Each worker is a separate process, so matplotlib/global state stays
+        # isolated per worker — the safe way to parallelise the suite. Serial
+        # runs overran the old cap (~28 min); -n auto brings it to minutes.
         run: |
-          pytest tests/ --cov=src/scitex_dev --cov-report=xml --cov-report=term
+          pytest tests/ -n auto --cov=src/scitex_dev --cov-report=xml --cov-report=term
       - name: Upload coverage to Codecov
         if: always() && matrix.python-version == '3.12'
         uses: codecov/codecov-action@v5

{scitex_dev-0.32.0 → scitex_dev-0.34.0}/CHANGELOG.md

@@ -5,6 +5,86 @@ All notable changes to `scitex-dev` are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [0.34.0] - 2026-07-21
+
+### Added
+- **CURRENCY gate — `scitex_dev.staleness.ensure_current()` (#396).** Public,
+  reusable version-currency + install-integrity primitive (operator
+  directive: consumers such as scitex-cards gate their invocation at ERROR
+  severity). INTEGRITY half (always, local): flags ambiguous metadata
+  (multiple dist-infos claiming one distribution) and partial installs
+  (RECORD-listed files missing on disk — parsed from RECORD directly, since
+  py3.12 `Distribution.files` silently drops missing entries). FRESHNESS
+  half (fail-safe): installed vs per-dist cached PyPI latest (TTL,
+  detached opportunistic refresh, never a blocking network call;
+  offline → PASS), editable installs via behind-upstream git. Severity
+  ladder: explicit arg > `$SCITEX_DEV_CURRENCY_SEVERITY` >
+  `currency_severity` knob > `error` (raises `StalenessError` with the
+  exact remedy command). `SCITEX_DEV_NO_CURRENCY_GATE=1` bypasses but logs
+  a loud WARN. The scitex-dev CLI self-checks its own install integrity at
+  startup (warn). Motivated by the 2026-07-21 venv incident where 0.17.4
+  metadata sat over a 0.16-era file set and every version probe lied.
+- **PS-221 `[all]`-closure audit rule + pyproject compliance (#395,
+  consolidates #391/#393).** ERROR-severity rule: every public
+  (non-underscore, non-`all`) extra must be a subset of `[all]`; scitex-dev's
+  own `sync` extra brought into `[all]` (the rule's first catch was its own
+  package). Plus the CLI drift-guard suppression under pytest.
+
+### Fixed
+- **Deterministic audit target-tree resolution (#397).** Explicit
+  `--path` > current checkout (git toplevel of cwd, PEP-503 name match —
+  correct inside linked worktrees and CI checkouts) > ecosystem-registry
+  `local_path`. Previously the per-target audit CLIs injected the registry
+  path as if explicit, so a CI run could silently grade a different
+  develop checkout (the wrong-tree incident #395 exposed). The resolved-tree
+  banner (#392) now also names which rule won (`via explicit|cwd|registry`),
+  and `--json` payloads carry `resolved_via`.
+- **De-flaked 6 FM001 promotion tests on figrecipe detection-skew (#394)**
+  (plugin-provided rule absent ⇒ skip like their plugin-path siblings, not
+  hard-fail) **and 4 xdist-order-fragile tests (#395)** (resolved-tree ×2
+  pinned to the checkout under test; staleness-prefix ×2 capture
+  scitex-logging via a named-logger handler instead of `redirect_stderr`).
+  Two pre-existing PS-204/PS-205 violations the wrong-tree audit had masked
+  were also fixed (test-file renames).
+
+## [0.33.0] - 2026-07-21
+
+### Added
+- **`ecosystem gui` launcher + 3129X port-registry SSOT (#378, #379).** A
+  fan-out launcher (`ecosystem gui list|open`) for the leaf-package browser
+  GUIs, backed by a machine-readable port-registry SSOT (`RESERVED_PORTS`,
+  the scitex-dev-owned 3129X/3130X assignment table) with a `gui audit`
+  conformance auditor that catches port collisions and pending leaf
+  migrations. Distinct from the top-level `gui` dashboard group.
+- **`skills_click_group` federation primitive + PS-217 auditor (#382).** A
+  shared `skills` command-group builder leaves import in one line (mirroring
+  `docs_click_group`), plus a WARN conformance auditor flagging leaves that
+  still hand-roll a `_cli/_skills.py` instead of the primitive.
+- **CLI-normalization + packaging conformance auditors (#381, #383).** PS-216
+  flags direct-URL/VCS dependencies in publishable metadata (a silent
+  PyPI-upload-reject guard, even inside extras); PS-218 / PS-219 flag a
+  `health` verb without `doctor` and a `version` subcommand instead of the
+  `--version` flag.
+- **Generalized test-execution recipe + knob + guard (#385).** A
+  host/scheduler-agnostic `TestExecutionConfig` recipe (`local` |
+  `remote-required`, with a `submit_template` and marker env), a per-package
+  `test_execution` knob, and an auto-loaded `pytest11` guard that blocks
+  local pytest when a package mandates remote — the policy layer of the
+  compute-execution fabric. Fails safe (a malformed recipe never crashes
+  pytest).
+
+### Changed
+- **pytest-xdist `-n auto` standardized across CI (#384).** scitex-dev's own
+  pytest-matrix workflow and the `pr-ci` / `release-ci` leaf templates now
+  parallelise across all runner cores (serial runs overran the ~28 min cap →
+  minutes); the templates install `pytest-xdist` explicitly so `-n auto`
+  works on any leaf.
+
+### Fixed
+- **PS-142 README-structure false-positive regression test (#380).** Pins the
+  full-README scan so a mandatory section past the old 16 KiB truncation
+  boundary is found (the underlying fix shipped earlier in #365).
+
 ## [0.32.0] - 2026-07-20
 
 ### Added

{scitex_dev-0.32.0/src/scitex_dev.egg-info → scitex_dev-0.34.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scitex-dev
-Version: 0.32.0
+Version: 0.34.0
 Summary: Shared developer utilities for the SciTeX ecosystem
 Author-email: Yusuke Watanabe <ywatanabe@scitex.ai>
 License-Expression: AGPL-3.0-only
@@ -50,6 +50,7 @@ Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == "docs"
 Provides-Extra: all
 Requires-Dist: scitex-dev[mcp]; extra == "all"
 Requires-Dist: scitex-dev[skills]; extra == "all"
+Requires-Dist: scitex-dev[sync]; extra == "all"
 Requires-Dist: scitex-dev[dev]; extra == "all"
 Requires-Dist: scitex-dev[docs]; extra == "all"
 Requires-Dist: scitex-dev[umbrella-regen]; extra == "all"

scitex_dev-0.34.0/docs/design/execution-fabric-phase1.md

@@ -0,0 +1,326 @@
+# SciTeX Execution Fabric — Phase-1 Design
+
+Status: Phase-1 proposal (design-first, not yet implemented)
+Owners: scitex-dev (policy/auditor) + scitex-hpc (backend adapters)
+Date: 2026-07-21
+Source vision memo: `central-compute-dispatcher-design-20260720.md` (operator TG1503-1525)
+
+## 1. Purpose & strategic framing
+
+The execution fabric safely routes **reproducible compute jobs** (starting with
+test suites) to available resources — local, HPC, and later cloud — behind a
+single command: `scitex test` (namespaced `scitex-dev dev test`). It is a CORE
+SciTeX compute subsystem, priority VERY HIGH because it is multiplicative on dev
+speed (all agents × all packages × all iterations).
+
+### Strategic decision (operator TG1524) — DO NOT reinvent the executor
+
+"local/HPC/cloud via a common API" is solved prior art: Snakemake (executor
+plugins), Nextflow/Seqera, Parsl (Slurm provider), Dask/dask-jobqueue, AWS/GCP/
+Azure Batch, AWS ParallelCluster. The `submit / status / logs / cancel / collect`
+interface is NOT new. **SciTeX must NOT build** Slurm/Batch wrappers from scratch
+as a differentiator, a DAG scheduler, retry engine, cloud provisioner, distributed
+executor, or storage-staging layer — those are REUSED from existing executors.
+
+What SciTeX uniquely adds is a **POLICY + DX + agent-integration** layer:
+
+1. Repo-level ENFORCEMENT policy — the same rule for humans and agents.
+2. Make WRONG usage IMPOSSIBLE — no laptop-heavy-test, no login-node pytest, no
+   1-core waits, no GPU-test-on-CPU, no confidential-data-to-cloud. Existing
+   executors "work if used right"; SciTeX is the "can't-misuse" layer.
+3. One consistent LLM-agent entry point — the agent only knows `scitex test`
+   (no partition / sbatch / SSH / module / SIF / worker-count knowledge).
+4. Auto-distribution + AUDIT across all packages.
+
+Layering:
+
+```
+Agent/Human → SciTeX policy/guard → SciTeX ExecutionBackend interface
+            → EXISTING executor (subprocess / srun / Snakemake / Parsl)
+            → Slurm / cloud
+```
+
+Positioning: Snakemake/Parsl = HOW to execute; **scitex-dev = WHAT to allow**
+devs/agents; **scitex-hpc = HOW to connect** to resources; Slurm/Batch = actually
+schedule.
+
+### Phase-1 thesis
+
+Build the thin enforcement layer + minimal backends, and **LOCK 4 interfaces NOW**
+so everything deferred becomes "+1 adapter later, not a rewrite."
+
+---
+
+## 2. The 4 foundations to lock as interfaces NOW
+
+Get these right and cloud is just one more `ExecutionBackend` implementation.
+Sketches below are **illustrative**, not a full implementation.
+
+### 2a. Container contract — the execution unit
+
+Cloud/remote reproducibility = `git commit + container image + recipe`, NEVER a
+dirty-tree copy. A job is defined by *what commit* runs *in what image* under
+*what recipe* — nothing implicit about the caller's working directory.
+
+```python
+from dataclasses import dataclass, field
+
+@dataclass(frozen=True)
+class ContainerContract:
+    """The reproducible unit of execution. No dirty-tree state."""
+    repo: str                       # e.g. "scitex-io"
+    commit: str                     # exact git SHA (never "HEAD"/branch)
+    image: str                      # OCI ref or SIF path, e.g. "ghcr.io/.../scitex:2.1"
+    dirty: bool = False             # True only if uncommitted tree; policy may forbid
+    workdir: str = "/work"          # in-container mount point of the checkout
+    env: dict[str, str] = field(default_factory=dict)
+```
+
+Rule: `remote_required` packages MUST run with `dirty=False`. The auditor and the
+receipt both record `commit`, so "tested remotely" can never mask a different SHA.
+
+### 2b. Resource spec — backend-neutral
+
+The user/recipe declares only `cpu / memory / gpu / walltime`. They NEVER write
+`partition: bm`, `instance_type: c7i.4xlarge`, or `machine_type: ...` — each
+backend TRANSLATES the neutral spec into its own vocabulary.
+
+```python
+@dataclass(frozen=True)
+class ResourceSpec:
+    """Backend-neutral resource request. Backends translate it."""
+    cpu: int = 1                    # logical cores; drives allocated -n worker count
+    memory_gb: float | None = None
+    gpu: int = 0
+    walltime_min: int | None = None # soft cap; backend maps to --time / timeout
+```
+
+Translation lives in the backend PROFILE (scitex-hpc), never in the recipe:
+`slurm` maps `cpu -> --cpus-per-task` + partition selection; a future `aws-batch`
+maps `cpu/memory_gb -> instance_type`.
+
+### 2c. ExecutionBackend interface — submit / status / logs / cancel / collect
+
+The one contract scitex-dev calls. It knows nothing of Slurm/AWS; it only calls
+`backend.submit(job)`. Lives in **scitex-hpc**.
+
+```python
+from typing import Protocol
+from enum import Enum
+
+class JobState(str, Enum):
+    PENDING = "pending"; RUNNING = "running"
+    SUCCEEDED = "succeeded"; FAILED = "failed"; CANCELLED = "cancelled"
+
+@dataclass(frozen=True)
+class JobSpec:
+    container: ContainerContract
+    resources: ResourceSpec
+    command: list[str]              # e.g. ["pytest", "-n", "<allocated>", "tests/"]
+    shard: tuple[int, int] | None = None   # (index, total); deferred use
+
+@dataclass(frozen=True)
+class JobHandle:
+    backend: str                    # "local" | "slurm" | ...
+    job_id: str                     # subprocess pid / SLURM job id
+    submitted_at: str
+
+class ExecutionBackend(Protocol):
+    name: str
+    def submit(self, job: JobSpec) -> JobHandle: ...
+    def status(self, handle: JobHandle) -> JobState: ...
+    def logs(self, handle: JobHandle) -> str: ...
+    def cancel(self, handle: JobHandle) -> None: ...
+    def collect(self, handle: JobHandle) -> "JobReceipt": ...
+```
+
+`collect()` blocks (or polls) to terminal state and returns the receipt — the
+only sanctioned way to obtain a result.
+
+### 2d. Execution RECEIPT schema — anti-false-claim
+
+The receipt is how an agent PROVES it tested the right thing at the right commit
+on the right backend with the right CPU count. It prevents "tested remotely" while
+actually testing another commit, or merely submitting.
+
+```python
+@dataclass(frozen=True)
+class ReceiptSource:
+    repo: str; commit: str; dirty: bool
+
+@dataclass(frozen=True)
+class ReceiptRuntime:
+    image: str; backend: str; instance: str | None; cpu: int   # cpu = ALLOCATED
+
+@dataclass(frozen=True)
+class ReceiptResult:
+    passed: int; failed: int; duration_s: float
+    cost_usd: float | None = None   # None until a cost-bearing backend exists
+
+@dataclass(frozen=True)
+class JobReceipt:
+    source: ReceiptSource
+    runtime: ReceiptRuntime
+    result: ReceiptResult
+    junit_xml_path: str | None = None
+```
+
+Mandatory fields in Phase-1: `commit`, `backend`, `cpu` (allocated), and
+`passed/failed`. The receipt is emitted by every `collect()` and is the artifact
+CI + agents cite as proof.
+
+---
+
+## 3. The 2 Phase-1 backends
+
+Exactly two `ExecutionBackend` implementations ship in Phase-1 — nothing else.
+
+### 3a. `local` backend
+
+- Executor: plain `subprocess`.
+- `submit`: fork `pytest -n <allocated> ...` against the checkout at `commit`.
+- `status`: poll the child process.
+- `logs`: tail captured stdout/stderr.
+- `cancel`: signal the process group.
+- `collect`: wait, parse JUnit XML, emit `JobReceipt` with `backend="local"`.
+- Allocated CPUs = the caller's permitted core budget (see §3c), NOT literal
+  all-cores. On an unconstrained laptop this may default to `os.cpu_count()`, but
+  `remote_required` packages are BLOCKED from the `local` backend by policy.
+
+### 3b. `slurm` backend
+
+- Executor: native Slurm via `srun --overlap` into an existing lease (no queue
+  wait), or `sbatch` for a fresh allocation.
+- `submit`: render the recipe `submit_template`, e.g.
+  `srun --overlap -p <cpu-partition> pytest -n <allocated> {pytest_args}`.
+- `status` / `logs` / `cancel`: `sacct` / job stdout file / `scancel`.
+- `collect`: parse JUnit XML from the job output, emit `JobReceipt` with
+  `backend="slurm"`, `instance=<node/partition>`, `cpu=$SLURM_CPUS_PER_TASK`.
+- Hard constraint: submit to a COMPUTE node via the scheduler, NEVER the login
+  node (admins flag login-node compute).
+- Spartan is treated as ONE resource; the fabric DELEGATES internal placement to
+  Spartan's native Slurm via the `submit_template` — it inherits/extends the
+  native scheduler, it does not nest a second controller.
+
+### 3c. `-n auto` → allocated-cpus (fix to fold in)
+
+`pytest -n auto` sees the WHOLE node's cores. On Slurm that over-subscribes an
+allocation and gets flagged. Phase-1 replaces the literal `-n auto` merged in
+#384/#385 with a per-backend **allocated-cpus** abstraction:
+
+- `slurm`: `-n $SLURM_CPUS_PER_TASK` (the permitted count).
+- `local`: `-n <ResourceSpec.cpu>` (bounded, not all-cores).
+
+Login/allocation detection uses `running_inside_slurm()` = presence of
+`SLURM_JOB_ID` / `SLURM_STEP_ID`, NOT hostname (naming varies per environment).
+
+---
+
+## 4. Ownership split — scitex-dev (policy/auditor) vs scitex-hpc (adapters)
+
+POLICY declares WHAT (local/remote/parallel/backend); the scitex-hpc PROFILE holds
+HOW (Spartan/cloud translation). Backends stay independent and portable to other
+universities — no hard dependency on Slurm cloud-bursting.
+
+### scitex-dev owns
+
+- The `scitex-dev dev test` policy-layer CLI (extends the #385 recipe).
+- The recipe schema (`local_allowed` / `remote_required`, resource-spec fields).
+- The 4 interface DEFINITIONS as the shared contract (dataclasses/Protocols above
+  live in a shared `scitex_dev` interface module that scitex-hpc imports, OR a
+  jointly-owned `scitex-execspec` — see §6).
+- The AUDITOR rules (ERROR severity):
+  - `pytest-not-serial` (missing xdist where required),
+  - `remote-required-run-local`,
+  - `public-extra-beyond-[all]`,
+  - `CI-template-off-convention`,
+  - internal `_`-extras exposed in README/docs.
+- The 3-layer guard: L1 agent hook (auto-convert `pytest tests/` → `scitex test
+  tests/` for agents; error+correct-cmd for humans), L2 CLI, L3 `conftest.py`
+  last-line (`pytest_sessionstart` raises if `remote_required` and not in an
+  approved env).
+
+Extras convention (confirmed): public = bare | `[all]` only; internal =
+`_test` / `_docs` / `_hpc` (underscore = intent; auditor also checks README/docs
+don't expose internal extras).
+
+### scitex-hpc owns
+
+- The `ExecutionBackend` interface implementations: `local` and `slurm` in Phase-1
+  (later `ssh`, `aws-batch`, `google-batch`, `azure-batch`).
+- All Spartan/cloud specifics: partition selection, `sbatch` rendering,
+  `--cpus-per-task ↔ -n` match, `--overlap` into leases, account.
+- The resource REGISTRY (resource id → submit_template + capacity/labels +
+  liveness probe) and live-utilisation knowledge.
+- The backend-neutral `ResourceSpec` → backend-vocabulary TRANSLATION.
+
+---
+
+## 5. Explicitly DEFERRED behind the interfaces
+
+Deferrable because each is "+1 adapter" against a locked interface, not a rewrite:
+
+- **Cloud backends** — AWS Batch / Google Batch / Azure Batch as additional
+  `ExecutionBackend` implementations (scitex-hpc). No cloud code in Phase-1.
+- **Best-effort load-balancing / routing** across free registered nodes, and the
+  `scitex test --target fastest|cheapest|local-only|secure` selector with
+  `routing{objective, constraints}` — deferred; Phase-1 selects backend explicitly.
+- **Job sharding** — split the test list across multiple cloud jobs and aggregate
+  JUnit XML (the `JobSpec.shard` field is reserved but unused in Phase-1). Note
+  multi-node ≠ xdist; shard, don't over-subscribe.
+- **Cost control** — `budget{max_cost_per_job, prefer_spot, fallback_to_on_demand}`
+  and the receipt `cost_usd` field (present but `None` until a cost-bearing
+  backend exists).
+- **Data governance** — can-data-go-to-cloud / ethics approval / storage region /
+  PII gating in recipe policy BEFORE resource pick. Only matters once a cloud
+  backend exists; the recipe schema reserves space for it.
+- **DAG / complex workflows** — DELEGATE to Snakemake/Nextflow if ever needed;
+  never hand-rolled.
+
+---
+
+## 6. Coordination ask for scitex-hpc
+
+Phase-1 is scitex-hpc-led on backends and scitex-dev-led on policy/audit/CLI. This
+is a JOINT design — do NOT solo-build either side. Concretely, scitex-hpc must
+agree to and implement:
+
+1. **Own the `ExecutionBackend` Protocol implementations.** Consume the four
+   locked interfaces (`ContainerContract`, `ResourceSpec`, `JobSpec`/`JobHandle`,
+   `JobReceipt`) exactly as defined in §2 — same field names, same
+   `submit/status/logs/cancel/collect` signatures. scitex-dev calls only
+   `backend.submit(job)` and `backend.collect(handle)`.
+2. **Ship exactly two backends in Phase-1:** `local` (subprocess) and `slurm`
+   (`srun --overlap` into a lease; `sbatch` fallback). No cloud, no ssh yet.
+3. **Emit a compliant `JobReceipt` from every `collect()`** — with real
+   `commit`, `backend`, ALLOCATED `cpu`, and `passed/failed`. This is the anti-
+   false-claim contract; a backend that cannot fill these is non-conformant.
+4. **Honour allocated-cpus, never all-cores:** map `-n` to
+   `SLURM_CPUS_PER_TASK` (slurm) / `ResourceSpec.cpu` (local); never emit literal
+   `-n auto` on a shared allocation. Provide `running_inside_slurm()` semantics
+   (env-var based, not hostname).
+5. **Own `ResourceSpec` → backend translation** (partition/account/instance) and
+   the resource registry + liveness probe. Guarantee Slurm submits to COMPUTE
+   nodes only, never the login node.
+6. **Agree the interface-home question:** whether the four dataclasses/Protocols
+   live in a scitex-dev interface module that scitex-hpc imports, or a small
+   jointly-owned `scitex-execspec` package. Recommendation: a thin shared spec
+   module so neither side co-locks the other's release (standalone-independence).
+
+Interface contract scitex-hpc CONSUMES: §2a–§2d verbatim. Interface contract
+scitex-hpc PROVIDES: conformant `local` + `slurm` `ExecutionBackend` objects
+discoverable by name.
+
+### Immediate independent follow-up (lands first)
+
+The **extras-enforcement auditor** (public = bare|`[all]`; internal `_`-extras not
+exposed in README/docs) is small, already agreed, and independent of scitex-hpc —
+queue it to land ahead of the joint backend work.
+
+---
+
+## 7. Non-goals for Phase-1
+
+No cloud provisioning, no DAG scheduler, no retry/backoff engine, no distributed
+executor, no storage staging, no routing/cost optimiser. Those are REUSED or
+deferred behind the four interfaces above.

{scitex_dev-0.32.0 → scitex_dev-0.34.0}/pyproject.toml

@@ -108,6 +108,7 @@ docs = [
 all = [
     "scitex-dev[mcp]",
     "scitex-dev[skills]",
+    "scitex-dev[sync]",
     "scitex-dev[dev]",
     "scitex-dev[docs]",
     "scitex-dev[umbrella-regen]",
@@ -118,6 +119,13 @@ all = [
 scitex-dev = "scitex_dev._cli:main"
 scitex-dev-testmon = "scitex_dev._hooks.run_testmon_cli:main"
 
+# Auto-loaded pytest guard: enforces a package's test-execution recipe
+# (mode=remote-required blocks local pytest). Inert by default (default mode is
+# `local`, and a package with no recipe resolves to that), so this never
+# affects scitex-dev's own CI or any package that has not opted in.
+[project.entry-points."pytest11"]
+scitex_dev_test_execution = "scitex_dev._core._test_execution_plugin"
+
 [project.entry-points."scitex_dev.docs"]
 scitex-dev = "scitex_dev"
 

{scitex_dev-0.32.0 → scitex_dev-0.34.0}/src/scitex_dev/_cli/_root.py

@@ -59,78 +59,10 @@ ROOT_HELP_SPEC = CliHelp(
     see_also=("{prog} docs — browse doctrine and package documentation",),
 )
 
-def _command_to_dict(
-    cmd: click.Command,
-    parent_ctx: click.Context | None,
-    info_name: str,
-) -> dict:
-    """Serialize one click command (and its subcommands recursively) to a dict."""
-    sub_ctx = click.Context(cmd, parent=parent_ctx, info_name=info_name)
-    options: list[dict] = []
-    arguments: list[dict] = []
-    for p in cmd.params:
-        if isinstance(p, click.Argument):
-            arguments.append({"name": p.name, "required": p.required})
-        else:
-            options.append(
-                {
-                    "name": p.name,
-                    "opts": list(p.opts),
-                    "help": getattr(p, "help", "") or "",
-                    "is_flag": bool(getattr(p, "is_flag", False)),
-                }
-            )
-    out: dict = {
-        "name": info_name,
-        "help": (cmd.help or "").strip(),
-        "short_help": (cmd.short_help or "").strip(),
-        "options": options,
-        "arguments": arguments,
-    }
-    if isinstance(cmd, click.Group):
-        commands: dict = {}
-        for sub in sorted(cmd.list_commands(sub_ctx)):
-            sub_cmd = cmd.get_command(sub_ctx, sub)
-            if sub_cmd is None:
-                continue
-            commands[sub] = _command_to_dict(sub_cmd, sub_ctx, sub)
-        out["commands"] = commands
-    return out
-
-def _show_recursive_help(ctx: click.Context) -> None:
-    """Recursively show help for all commands. Honours ctx.obj['json']."""
-    if ctx.obj and ctx.obj.get("json"):
-        import json as _json
-
-        tree = _command_to_dict(
-            ctx.command, ctx.parent, ctx.info_name or "scitex-dev"
-        )
-        click.echo(_json.dumps(tree, indent=2))
-        return
-
-    click.echo(ctx.get_help())
-    click.echo()
-    group = ctx.command
-    if isinstance(group, click.Group):
-        for name in sorted(group.list_commands(ctx)):
-            cmd = group.get_command(ctx, name)
-            sub_ctx = click.Context(cmd, parent=ctx, info_name=name)
-            click.echo(f"{'=' * 60}")
-            click.echo(f"Command: {name}")
-            click.echo(f"{'=' * 60}")
-            click.echo(sub_ctx.get_help())
-            click.echo()
-            if isinstance(cmd, click.Group):
-                for sub_name in sorted(cmd.list_commands(sub_ctx)):
-                    sub_cmd = cmd.get_command(sub_ctx, sub_name)
-                    sub_sub_ctx = click.Context(
-                        sub_cmd, parent=sub_ctx, info_name=sub_name
-                    )
-                    click.echo(f"  {'─' * 56}")
-                    click.echo(f"  Subcommand: {name} {sub_name}")
-                    click.echo(f"  {'─' * 56}")
-                    click.echo(sub_sub_ctx.get_help())
-                    click.echo()
+# Recursive help-rendering helpers extracted to keep this file under the
+# 512-line limit. Re-exported so `from ..._root import _show_recursive_help`
+# (and `_command_to_dict`) keep resolving for existing callers/tests.
+from ._root_help import _command_to_dict, _show_recursive_help
 
 def _get_version() -> str:
     try:
@@ -198,6 +130,46 @@ def main(
         _show_recursive_help(ctx)
         ctx.exit(0)
 
+    # Version-staleness guard: warn — or hard-fail when the severity knob is
+    # `error` — if this scitex-dev install is BEHIND its remote (editable) or
+    # the latest published version (wheel). Placed after the --version /
+    # --help-recursive short-circuits so a version/help query never trips it;
+    # shell-completion and repeat invocations are guarded inside emit_if_drift.
+    # An error-severity abort raises SystemExit and MUST propagate; any other
+    # internal fault is swallowed so the check can never break the host CLI.
+    import os as _os
+
+    # Suppress the drift emission inside a pytest run: this guard fires on
+    # EVERY CLI invocation, so when unrelated tests invoke the `scitex-dev`
+    # CLI it would print a drift line into their captured output whenever the
+    # test checkout is behind its remote — polluting assertions across suites
+    # (seen on the self-hosted runner). Direct unit tests of check() /
+    # emit_if_drift bypass main() and are unaffected.
+    if not _os.environ.get("PYTEST_CURRENT_TEST"):
+        from scitex_dev._release.check_editable_drift import emit_if_drift
+
+        try:
+            emit_if_drift()
+        except SystemExit:
+            raise
+        except Exception:  # noqa: BLE001 — staleness check must never break the CLI
+            pass
+
+        # CURRENCY-gate integrity self-check (operator directive 2026-07-21):
+        # catch a broken scitex-dev install itself (ambiguous dist-info /
+        # RECORD-listed files missing on disk — the venv-corruption incident
+        # where every version probe lied). Integrity half only — freshness is
+        # already covered by emit_if_drift() above (which owns the once-per-
+        # process/subprocess suppression) — at WARN so the CLI keeps working.
+        try:
+            from scitex_dev.staleness import ensure_current
+
+            ensure_current(
+                "scitex-dev", severity="warn", _halves=("integrity",)
+            )
+        except Exception:  # noqa: BLE001 — self-check must never break the CLI
+            pass
+
     if ctx.invoked_subcommand is None:
         click.echo(ctx.get_help())